Skip to main content
SocialAPI receives the direct messages (DMs) people send to your Telegram bot in a private chat and sends your replies as text, photos, and documents. Every message arrives as a dm.received webhook event and lands in the inbox, where you read and answer it with the same conversation endpoints as every other platform. A Telegram bot cannot write first: you can message a person only after that person has messaged the bot, and from then on there is no reply window. For the endpoints every platform shares, see Direct messages.

Endpoints

POST and DELETE on /v1/inbox/conversations/{conversation_id}/messages/{message_id}/reaction, and POST /v1/inbox/conversations/{conversation_id}/sender-action, return 501 resource.not_supported on Telegram. In the conversation paths, {conversation_id} is the conversation id, a UUID. In /v1/inbox/media/{media_id}, use the URL from content.media[].url or attachment_url.

Your first reply

List the conversations of the bot:
Response (HTTP 200):
Reply into that conversation with a text and a PDF:
Response (HTTP 200):
The person receives 2 messages: the text, then the PDF as a document with the caption “Invoice A1234” under it. The request costs 1 interaction credit. message_ids lists the SocialAPI ID of each message in send order, and message_id is the first one (deprecated).

Who you can message

A Telegram bot can only answer. SocialAPI sends a message to a person only after that person has opened a private chat with the bot and sent /start or any other message.
  • Before the person writes: there is no conversation to send into, because a conversation exists only once the person has messaged the bot.
  • After the person writes: the bot can answer at any time. Telegram has no 24-hour window or other reply window.
  • When the person blocks the bot: every send fails with 403 telegram.cannot_message until the person unblocks the bot. SocialAPI does not change the conversation when the person blocks the bot: the conversation stays active and no event fires.
Telegram support in SocialAPI covers private chats between one person and your bot. Do not add the bot to a group: messages from a group can appear in the inbox as a conversation, but a reply to that conversation is sent as a private message to the first group member who wrote, never to the group. If that member has not messaged the bot, the reply fails with 403 telegram.cannot_message. Posts in a channel never arrive.

Receive messages

Each message a person sends to the bot arrives as a dm.received event and is added to its conversation in the inbox. Telegram gives bots no message history. The inbox starts with the messages Telegram delivers once the bot is connected, including messages up to 24 hours old that no other service received.
There is no recipient field on Telegram events. id is the event’s interaction ID: to find the message in the message list, join on platform_id, never on id.

Message types

Telegram delivers one file per message. SocialAPI reports each Telegram message type with these type values, in content.media[].type on the event and in attachment_type on the message in GET /v1/inbox/conversations/{conversation_id}/messages: A message with none of these and no text, such as a location, a contact, or a poll, arrives with empty content.text and no content.media.

Files a person sends

The url of a file is a SocialAPI URL of the form https://api.social-api.ai/v1/inbox/media/{media_id}, because Telegram files can be downloaded only with the bot’s token. Fetch it with your API key. The same URL appears as attachment_url on the message in GET /v1/inbox/conversations/{conversation_id}/messages. It stays available for 30 days after the message arrives, then returns 410. Telegram does not let bots download a file larger than 20 MB, so the URL of such a file returns 410. A file that is not ready yet returns 503: retry it. Fetch an inbound attachment lists every status the URL returns.

Edited and deleted messages

A person can edit or delete a message in Telegram. Neither change raises a webhook event, and the inbox keeps the message as it first arrived.

Read conversations and messages

The conversation and message lists work as on every other platform, described in Direct messages. These fields have Telegram values: Telegram has no message history, so POST /v1/inbox/sync adds no messages. Pagination works as described in Pagination.

Send messages

POST /v1/inbox/conversations/{conversation_id}/messages sends a message. The request fields are on Send a message. A request with no text, no attachment, and no quick_replies, buttons, cards, or list_sections returns 400 validation.field_required, and a request without account_id returns 400 validation.field_required as well. SocialAPI sends the text first, then each attachment in order, each as its own Telegram message. These rules are specific to Telegram:
  • Photo or document. SocialAPI sends a file as a photo when its name ends in .jpg, .jpeg, .png, .gif, or .webp, and as a document otherwise. For a url attachment the name is the end of the URL path, without the query string. For a media_id attachment it is the file name you uploaded to your media library. The attachment’s type field does not change this choice.
  • Captions. An attachment’s caption is shown under the file. The message text is always a separate message, also when you send the single file with the deprecated attachment_url field.
  • No platform_attachment_id. Send files as url or media_id attachments. A platform_attachment_id attachment fails with 400 validation.telegram_bad_request, or with 400 validation.attachment_type_required when it has no type.
  • Public URLs. Telegram downloads a url attachment itself, so the URL must be reachable without a login. A URL Telegram cannot fetch fails with 400 validation.telegram_bad_request.
  • Interactive content is not sent. quick_replies, buttons, cards, list_sections, and list_button are ignored: SocialAPI sends the text without them, then any attachments. A request with quick_replies, buttons, cards, or list_sections and no text fails with 400 validation.telegram_bad_request and sends nothing, even when it carries attachments.
  • No replies to a specific message. reply_to_message_id is ignored, so the message is sent as a plain message.
  • No message tags. A request with message_tag returns 422 messaging.tag_not_supported and sends nothing.
If one message of a request fails, the messages before it stay delivered. The error carries error.meta.sent_count (messages sent) and error.meta.failed_index (the item that failed, counted from 0: the text, or the interactive content without text, is item 0 when the request has one, otherwise the first attachment is item 0), so you can retry from there.

Limits

Telegram enforces the text, caption, and file limits. A request over one of them fails with 400 validation.telegram_bad_request, and error.message carries Telegram’s own description. Telegram’s guideline for bots is at most 1 message per second in one chat and 30 messages per second across all chats. When Telegram rate-limits the bot, the send fails with 429 platform.telegram.rate_limit: wait the number of seconds in the Retry-After header before you retry. Without the header, wait at least 60 seconds, then retry with exponential backoff.

Cost

Each send request costs 1 interaction credit, however many messages it sends. Listing, reading, archiving, marking as read, and downloading files cost nothing. A request refused with 400 validation.telegram_bad_request before any of its messages was sent gets its credit back. A send refused with 403 telegram.cannot_message or 429 platform.telegram.rate_limit keeps the credit spent, and so does validation.telegram_bad_request once a message of the request has been sent. Any other error that Telegram or SocialAPI returns after sending has started keeps the credit spent. A request refused before sending, for example an invalid body, 403 auth.insufficient_scope, 404 conversation.not_found, 403 account.permission_missing, 422 messaging.tag_not_supported, or 429 validation.interaction_limit_exhausted, costs nothing. When the allowance is used up, the call returns 429 validation.interaction_limit_exhausted. See When a credit comes back.

Errors and debugging

Check these in order when a Telegram send fails:
  1. 403 telegram.cannot_message. The person has not messaged the bot, or blocked it. Wait for the person to write to the bot.
  2. 400 validation.telegram_bad_request. Telegram rejected the content: text or caption too long, a file over its size limit, or a URL Telegram could not fetch. Read error.message for Telegram’s reason, fix the request, and send again.
  3. 404 media.not_found. A media_id does not exist, is not yours, or has not finished uploading. Nothing was sent and no credit was used. Check it in your media library and send again.
  4. 422 messaging.tag_not_supported. Remove message_tag from the request.
  5. 429 platform.telegram.rate_limit. Wait for the seconds in Retry-After, then retry. Without the header, wait at least 60 seconds, then retry with exponential backoff.
  6. 401 platform.telegram.auth. Telegram rejected the bot token, for example after /revoke in @BotFather. Connect the bot again with the new token: see Reconnect an account.
  7. 503 platform.telegram.api_error. Telegram did not answer, or answered with an error SocialAPI does not map. Retry with backoff. If it persists, check that the conversation still exists in Telegram.
  8. 403 account.permission_missing. The account lacks the messages.write permission.
  9. 403 auth.insufficient_scope. The API key is a scoped key without dms:send.
  10. 404 conversation.not_found. The conversation does not exist, is not yours, or belongs to another connected account than account_id.
  11. 429 validation.interaction_limit_exhausted. Your interaction credits for the billing period are used up: see Plans and usage.
Every code is in Errors.

Scopes

Scoped API keys are described in Scoped API keys.

Events

A Telegram account emits one DM event, dm.received, described in Receive messages. It emits no dm.sent, no dm.status.*, no dm.deleted, and no dm.postback. An account without the messages.read permission receives no dm.received event, and no new messages appear in its conversations.

Use from an AI agent

social_api_send_sender_action returns 501 resource.not_supported on Telegram. To send a file, use the REST endpoint. See MCP tools.
Last modified on November 15, 2026