Configuration

bot-gateway is configured with environment variables.

Variable	Default	Meaning
BOT_TOKEN	—	Required. Every API request must send Authorization: Bearer <BOT_TOKEN>. Make it long and random: openssl rand -hex 24.
RELAY_URL	—	The Mailbees server the bot registers on at the first start, e.g. https://mailbees.online.
BOT_NAME	—	The bot's name. Required at the first start; later the name is changed if it differs.
BOT_AVATAR	—	Path to a JPEG, PNG or WebP inside the container. It is cropped to a square and scaled down.
ACCEPT_REQUESTS	all	all: chat requests and group invitations are accepted at once. contacts: only people who came by the bot's link get in; the rest stay requests until POST /v1/chats/{chat}/accept.
WEBHOOK_URL, WEBHOOK_SECRET	—	Deliver updates by POST to this URL instead of GET /v1/updates. See webhook.
UPDATES	on	off: the bot only sends (for example, through hooks). No update queue is kept, GET /v1/updates answers 409.
HOOKS_URL	—	The gateway's public address. Turns on incoming hooks: their URLs are HOOKS_URL/hooks/<secret>.
BOT_OWNERS	—	Account ids separated by commas: only they can create and remove hooks with chat commands.
LISTEN	:8080	Address of the HTTP API.
DATA_DIR	/data	Keys, the database and the update queue.
LOG_LEVEL	—	debug for a verbose log.

The data volume

DATA_DIR holds:

• db.key — the key the database is encrypted with; created at the first start;
• the core's database: the bot's identity keys, contacts, chats and messages;
• the queue of updates that are not confirmed yet (encrypted with the same key).

Losing it means losing the bot: a new account is registered on the next start and people have to add the bot again. Back up the whole volume.

Health check

GET /healthz answers 200 without a token. Use it for container health checks.

Exposing the API

The API gives full control over the bot. Keep it on a private network or 127.0.0.1, as in the example. If you use incoming hooks, publish only the /hooks/ path through your reverse proxy.

Limits worth knowing

• The relay limits how many new people an account may write to first in a day (50). Answering someone who wrote first is free, so a bot in private chats is not affected, but a bot in a big group counts its members like a person would.
• In a group the bot receives every message: it is a full member. The apps warn about this when someone adds a bot to a group.
• Unconfirmed updates are kept for 24 hours, at most 10,000; older ones are dropped.