Telegram

Postgale publishes to Telegram channels and groups with its own bot (Telegram Bot API): text messages, one photo, video or document, or an album of 2 to 10 items, with edits and deletes of what was published, plus an inbox for the bot's chats (messages, inline buttons, quick replies, edits, deletes, reactions and bot commands). Everything is available over the REST API (paths relative to https://staging.postgale.com/api/v1) and the MCP server (connect_account, create_post, manage_published_post, get_analytics, send_message, manage_message, send_typing, telegram_bot_commands). Each connected channel or group is one account with platform telegram; its platformAccountId is the Telegram chat id.

Connect a channel or groupCopy Anchor Link

Telegram has no sign-in for bots, so connecting works with a one-time code instead of a link:

1. In Postgale open Dashboard → Accounts → Telegram (or ask for a code with the API or connect_account). You get a code that works once and expires after 15 minutes.
2. In Telegram, add Postgale's bot (shown with the code) to your channel or group as an administrator with the right to post messages. In channels the right is called Post messages.
3. Post /connect <code> in the channel or group. In groups /connect@<bot> <code> works too. You can also post it in the channel and forward that post to the bot in a private chat.

The chat appears as a Telegram account within seconds (the dashboard waits for it; API clients get the account.connected webhook or see it in GET /accounts). When the bot may delete messages, it removes the /connect message afterwards.

curl -X POST https://staging.postgale.com/api/v1/connect/telegram \
  -H 'Authorization: Bearer sk_…' \
  -H 'Content-Type: application/json' \
  -d '{"externalId":"cust-1"}'

# {"platform":"telegram","code":"K7PQ2MXH9D","command":"/connect K7PQ2MXH9D","botUsername":"PostgaleBot","instructions":[…],"expiresAt":"…","expiresInSeconds":900}

GET /connect/telegram?externalId=… returns the same. externalId (your own reference) is stored on the account that the code connects.

If the bot is removed from the chat or loses the right to post, the account becomes needs_reconnect and account.disconnected is sent (reason bot_removed). Making the bot an admin with the right to post again restores it; posting /connect with a new code works too.

PublishCopy Anchor Link

The post content is the message, up to 4096 characters. With media it is the caption of the photo, video, document or of the first album item, up to 1024 characters. Both limits count the visible text (after parseMode markup) and are checked when the post is created. Postgale uploads the files to Telegram itself: photos up to 10 MB, videos and documents up to 50 MB. Use the publicUrl of uploaded media or any public https URL.

curl -X POST https://staging.postgale.com/api/v1/posts \
  -H 'Authorization: Bearer sk_…' \
  -H 'Content-Type: application/json' \
  -d '{"content":"<b>Release 2.4</b> is out: faster sync and dark mode.","platforms":[{"accountId":"acc_tg","platformSpecificData":{"parseMode":"HTML","disableLinkPreview":true}}],"publishNow":true}'

curl -X POST https://staging.postgale.com/api/v1/posts \
  -H 'Authorization: Bearer sk_…' \
  -H 'Content-Type: application/json' \
  -d '{"content":"Photos from the meetup 📸","platforms":[{"accountId":"acc_tg","platformSpecificData":{"mediaUrls":["https://media.postgale.com/…/1.jpg","https://media.postgale.com/…/2.jpg","https://media.postgale.com/…/clip.mp4"],"disableNotification":true}}],"publishNow":true}'

The target's platformPostId is text:<message_id>, media:<message_id> or group:<id>.<id>… (every message of an album), and url is the message's t.me link (public chats, or t.me/c/… for members of private supergroups and channels).

Edit and deleteCopy Anchor Link

Both are queued for a person while approval applies to the API key, the organization or the account (202 pending_approval; MCP manage_published_post returns the queued action). Telegram only lets bots delete messages from the last 48 hours.

InboxCopy Anchor Link

Telegram conversations appear in the same inbox as Instagram, Messenger, WhatsApp and X (GET /inbox/conversations?platform=telegram, MCP list_conversations). Bots cannot read message history, so everything is stored as it arrives through the webhook and POST /inbox/conversations/sync answers not_supported. There is no messaging window: the bot may write in any chat it is in.

• A connected group is one conversation (its participant is the group). Members' messages are inbound and carry the sender in metadata.sender on the webhook. In a connected channel, posts an admin makes in Telegram are stored as outbound messages.
• Private chats with the bot are shared by every Postgale customer, so a private chat belongs to an account only after the person opens the account's start link (startLink from GET /accounts/{id}/telegram-commands, or MCP telegram_bot_commands with action get). Share it on your site or in the channel. When someone opens the start links of two accounts, the latest one wins. Private chats that never opened a start link are not stored.

Message ids are stored as <chatId>:<messageId> (platformMessageId). Every endpoint below also accepts the bare Telegram message id or the Postgale message id. Attachments people send arrive as Telegram file ids ({type, id, mimeType?, filename?, url: null}): Telegram's download links contain the bot token, so Postgale never hands them out.

SendCopy Anchor Link

POST /inbox/conversations/{id}/messages (MCP send_message) takes text (or Zernio's message, ≤4096) and/or one attachment (mediaUrl / attachmentUrl or mediaId, with attachmentType image | video | audio | file). With an attachment the text is its caption (≤1024). Add at most one of:

replyTo quotes a message (its Telegram id), and parseMode, disableNotification, protectContent and disableWebPagePreview work like on posts. A person who blocked the bot answers 409 recipient_unavailable; the account stays connected.

curl -X POST https://staging.postgale.com/api/v1/inbox/conversations/conv_tg/messages \
  -H 'Authorization: Bearer sk_…' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Your order is ready. Pick it up today?","buttons":[{"type":"postback","title":"Yes","payload":"pickup:yes"},{"type":"postback","title":"Tomorrow","payload":"pickup:later"}]}'

Edit, delete and reactCopy Anchor Link

Each answers {message} with the updated stored copy. Over MCP these are manage_message (edit, delete, react, unreact) and send_typing.

Sends, edits, deletes and reactions are queued for a person while approval applies, like every other agent action.

Bot commandsCopy Anchor Link

The "/" menu people see when they chat with the bot. Postgale's bot serves every customer, so commands are set per chat: in the account's group (channels have no command menu) and in every private chat bound to the account, including ones that open the start link later.

curl -X PUT https://staging.postgale.com/api/v1/accounts/acc_tg/telegram-commands \
  -H 'Authorization: Bearer sk_…' \
  -H 'Content-Type: application/json' \
  -d '{"commands":[{"command":"order","description":"Place an order"},{"command":"help","description":"Talk to a person"}]}'

A command someone sends arrives as an ordinary message.received with the text (/order).

WebhooksCopy Anchor Link

Telegram tells bots nothing about deleted or read messages.

Telegram's rules to knowCopy Anchor Link

• Rate limits: when Telegram answers 429, Postgale retries the post after the retry_after Telegram asks for. Telegram allows about 20 messages per minute per group.
• Rights: in channels the bot must be an admin with Post messages (and Edit messages of others / Delete messages is not needed for its own posts). In groups it must be an admin.
• Errors: "bot was kicked", "not enough rights" or "chat not found" mark the account needs_reconnect (reconnect_required on the API).
• Analytics: the Bot API gives bots no views or reactions per message, so post analytics answer not_supported; the member count is available as an account metric.
• Groups upgraded to supergroups get a new chat id from Telegram; Postgale follows the change automatically.