Channels: WhatsApp, Telegram & MAX
One API, three channels: capabilities, bot-token setup for Telegram and MAX, and honest limits.
Every instance has a channel chosen when you create it: WHATSAPP, TELEGRAM or MAX. The queue, idempotency keys, opt-outs, daily caps, webhooks, message history, roles and workspace isolation work the same on every channel, and each message and webhook payload carries its channel. The Green-compatible routes work for all three too.
What each channel can doLive
| Capability | Telegram (Beta) | MAX (Beta) | |
|---|---|---|---|
| Login | QR code or pairing code | Bot token | Bot token |
| Connection type | Unofficial linked device: numbers can be restricted | Official Bot API | Official bot API |
| Text and replies (quotes) | yes | yes (4096 characters) | yes (4000 characters) |
| Files (document, image, video, audio, voice) | yes | yes | yes (two-step upload, handled for you) |
| Location, contact card | yes | yes (a contact needs a phone number) | yes |
| Poll | yes | yes (max 10 options) | no |
| Reaction | yes | yes | no |
| Forward, edit, delete a sent message | yes | yes | yes |
| Typing indicator | yes | yes | yes (numeric chat id) |
| Mentions in groups | yes, resolved against the member list | yes: @username or numeric user id (real entities) | no |
| Group info | yes | yes (administrators only: a bot cannot list every member) | yes |
| Group management | full | rename, description, permissions, remove, promote, demote, leave, picture; cannot create groups or add people | rename, leave |
| Delivered / read receipts | yes | no: messages stay at Sent | no: messages stay at Sent |
Read marks (readChat) | yes | no | no |
| Phone checks, stories, catalog, pairing code | yes | no | no |
| Who the account can message | anyone, subject to WhatsApp rules | only people who messaged the bot first | only people who started the bot |
| Receiving | live connection | long polling or webhook | long polling or webhook |
GET /instances/{id}/capabilities returns what the instance's channel supports. Anything it cannot do answers 422 not_supported_on_channel when you send (nothing is queued): never a fake success.
Connect a Telegram botBeta
- In Telegram open @BotFather, send
/newbot, choose a name and a username ending inbot. BotFather replies with a token like123456789:AA.... - In the console choose Create instance, Telegram, then Connect and paste the token (API:
POST /instances/{id}/connectwith{ "botToken": "..." }). The instance shows@yourbotand the status Authorized. - A person must message the bot first (or add it to a group) before it can write to them. Their numeric chat id arrives with their first message, in the Inbox, the webhook payload or the polling queue.
- For groups, add the bot to the group. Make it an administrator so it can read every message (
/setprivacyin BotFather controls what bots see). - Send:
POST /instances/{id}/messages/textwith{ "chatId": "<numeric chat id>", "text": "Hello" }.
Connect a MAX botBeta
- Create a bot in the MAX bot platform (dev.max.ru) and copy its access token.
- Create an instance with channel MAX and connect with the token. The token travels in the
Authorizationheader tohttps://platform-api2.max.ru, never in a URL. - MAX's servers use a certificate issued by the Russian Ministry of Digital Development. A self-hosted Sendjade needs that root CA: set
MAX_CA_CERT_PATH(TLS verification stays on) orNODE_EXTRA_CA_CERTS. - A user must start the bot first. To receive group and channel events the bot must be an administrator.
Chat ids and message idsLive
| Channel | `chatId` looks like |
|---|---|
A phone number (2348012345678), a Green-style id (2348012345678@c.us), a group id (...@g.us) or a LID | |
| Telegram | The numeric chat id (users positive, groups and channels negative, e.g. -1001234567890) or @channelusername |
| MAX | The numeric chat_id, or user:<id> to message a user directly |
A WhatsApp-style id on a Telegram instance answers 400 invalid_chat_id. On Telegram and MAX the final message id is assigned when the message is sent, so track a message by its Sendjade `id` (the UUID) on these channels.
Receiving updatesBeta
- Default: long polling, one poller per connected instance. It works behind NAT and on localhost, and resumes after a restart.
- Webhook mode (for self-hosting): set
CHANNEL_WEBHOOK_BASE_URLandCHANNEL_WEBHOOK_SECRET(16+ characters). Connecting then registers a per-instance webhook with Telegram or MAX, verified with a per-instance secret. - Incoming messages are stored and appear in the Inbox, the polling queue and your Sendjade webhooks exactly like WhatsApp messages. Edits and deletions of received messages and channel-specific bot events are not mapped.
Opt-outs and pacingLive
- Opt-out keys are
telegram:<chatId>andmax:<chatId>(WhatsApp keeps plain phone numbers), so the same person on two channels is two recipients. A STOP reply in a private chat opts them out on that channel only. - The queue never sends faster than the channel allows: at least 1.1 seconds between sends on Telegram and 0.6 seconds on MAX. A blocked bot or unknown chat fails the message permanently and is never billed.
GET /instances/{id}/groupslists the groups that have written to the bot, because bots cannot ask Telegram or MAX for their chats.
Honest limitsBeta
- Telegram and MAX do not give bots delivered or read receipts, so those messages stay at Sent. A Sent message means the channel accepted it.
- A Telegram or MAX bot can only message people who contacted it first. It cannot cold-message a phone number.
- MAX's location and contact attachment shapes follow the current documentation but are the least certain part: check them with a real bot before relying on them.
- MAX files that are still processing are retried automatically with growing waits.
CostLive
The Telegram Bot API is free to use, and MAX currently offers its bot API free of charge (check dev.max.ru for any change). Sendjade's own plans are priced per connected instance in US dollars.