Documentation

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

CapabilityWhatsAppTelegram (Beta)MAX (Beta)
LoginQR code or pairing codeBot tokenBot token
Connection typeUnofficial linked device: numbers can be restrictedOfficial Bot APIOfficial bot API
Text and replies (quotes)yesyes (4096 characters)yes (4000 characters)
Files (document, image, video, audio, voice)yesyesyes (two-step upload, handled for you)
Location, contact cardyesyes (a contact needs a phone number)yes
Pollyesyes (max 10 options)no
Reactionyesyesno
Forward, edit, delete a sent messageyesyesyes
Typing indicatoryesyesyes (numeric chat id)
Mentions in groupsyes, resolved against the member listyes: @username or numeric user id (real entities)no
Group infoyesyes (administrators only: a bot cannot list every member)yes
Group managementfullrename, description, permissions, remove, promote, demote, leave, picture; cannot create groups or add peoplerename, leave
Delivered / read receiptsyesno: messages stay at Sentno: messages stay at Sent
Read marks (readChat)yesnono
Phone checks, stories, catalog, pairing codeyesnono
Who the account can messageanyone, subject to WhatsApp rulesonly people who messaged the bot firstonly people who started the bot
Receivinglive connectionlong polling or webhooklong 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 in bot. BotFather replies with a token like 123456789:AA....
  • In the console choose Create instance, Telegram, then Connect and paste the token (API: POST /instances/{id}/connect with { "botToken": "..." }). The instance shows @yourbot and 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 (/setprivacy in BotFather controls what bots see).
  • Send: POST /instances/{id}/messages/text with { "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 Authorization header to https://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) or NODE_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
WhatsAppA phone number (2348012345678), a Green-style id (2348012345678@c.us), a group id (...@g.us) or a LID
TelegramThe numeric chat id (users positive, groups and channels negative, e.g. -1001234567890) or @channelusername
MAXThe 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_URL and CHANNEL_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> and max:<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}/groups lists 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.