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: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_messageuntil the person unblocks the bot. SocialAPI does not change the conversation when the person blocks the bot: the conversation staysactiveand no event fires.
403 telegram.cannot_message. Posts in a channel never arrive.
Receive messages
Each message a person sends to the bot arrives as adm.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 thesetype 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
Theurl 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 aurlattachment the name is the end of the URL path, without the query string. For amedia_idattachment it is the file name you uploaded to your media library. The attachment’stypefield does not change this choice. - Captions. An attachment’s
captionis shown under the file. The messagetextis always a separate message, also when you send the single file with the deprecatedattachment_urlfield. - No
platform_attachment_id. Send files asurlormedia_idattachments. Aplatform_attachment_idattachment fails with400 validation.telegram_bad_request, or with400 validation.attachment_type_requiredwhen it has notype. - Public URLs. Telegram downloads a
urlattachment itself, so the URL must be reachable without a login. A URL Telegram cannot fetch fails with400 validation.telegram_bad_request. - Interactive content is not sent.
quick_replies,buttons,cards,list_sections, andlist_buttonare ignored: SocialAPI sends thetextwithout them, then any attachments. A request withquick_replies,buttons,cards, orlist_sectionsand notextfails with400 validation.telegram_bad_requestand sends nothing, even when it carries attachments. - No replies to a specific message.
reply_to_message_idis ignored, so the message is sent as a plain message. - No message tags. A request with
message_tagreturns422 messaging.tag_not_supportedand sends nothing.
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 with400 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:403 telegram.cannot_message. The person has not messaged the bot, or blocked it. Wait for the person to write to the bot.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. Readerror.messagefor Telegram’s reason, fix the request, and send again.404 media.not_found. Amedia_iddoes 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.422 messaging.tag_not_supported. Removemessage_tagfrom the request.429 platform.telegram.rate_limit. Wait for the seconds inRetry-After, then retry. Without the header, wait at least 60 seconds, then retry with exponential backoff.401 platform.telegram.auth. Telegram rejected the bot token, for example after/revokein @BotFather. Connect the bot again with the new token: see Reconnect an account.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.403 account.permission_missing. The account lacks themessages.writepermission.403 auth.insufficient_scope. The API key is a scoped key withoutdms:send.404 conversation.not_found. The conversation does not exist, is not yours, or belongs to another connected account thanaccount_id.429 validation.interaction_limit_exhausted. Your interaction credits for the billing period are used up: see Plans and usage.
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.
Related
- Telegram API: connect the bot, capabilities, and webhook events
- Direct messages: the request fields and conversation endpoints for every platform
- Webhook events: the
dm.receivedpayload on every platform - Unified inbox: every status of the file download URL
- Plans and usage: what costs an interaction credit