Telegram - SocialAPI.AI

Available Messaging connector. Telegram is a DM-only connector: you connect a bot with a static token from @BotFather and use SocialAPI’s unified inbox to read and reply to the direct messages the bot receives. There is no OAuth, no posts, and no comments.

At a glance

Field	Value
Platform slug	`telegram`
Auth type	Static bot token (from @BotFather)
API	Telegram Bot API
Best for	A unified inbox for your Telegram bot’s direct messages.

Capabilities

Feature	Supported	Notes
DMs	Yes	Read direct messages your bot receives and reply to them
Send DM	Yes	Send text, a photo (by URL), or a document (by URL)
Comments	No	Telegram bots have no post-comment model
Reviews	No	Not applicable
Mentions	No	Not tracked for Telegram
Publishing	No	Telegram is a messaging connector here; it does not publish posts
Webhooks	Yes	Inbound messages arrive in real time via Telegram webhooks

Connecting

Telegram does not use OAuth. There is no authorization URL, no code exchange, no refresh token, and no token expiry. You create a bot with @BotFather, copy its token, and pass it in metadata.bot_token:

curl -X POST https://api.social-api.ai/v1/accounts/connect \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "telegram",
    "metadata": { "bot_token": "123456789:ABCdefGhIjKlMnOpQrStUvWxYz-1234" }
  }'

Response (HTTP 201):

{
  "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
  "platform": "telegram",
  "username": "mysocialinboxbot",
  "display_name": "My Social Inbox Bot"
}

SocialAPI validates the token, registers a Telegram webhook for your bot automatically, and stores the account. No redirect, no second call.

Getting a bot token

Open Telegram and message @BotFather.
Send /newbot and follow the prompts (choose a name and a username ending in bot).
BotFather replies with a token of the form <bot_id>:<secret>.
Paste that token as metadata.bot_token.

The whole process takes about two minutes. There is no developer account, business verification, or app review.

Reading and sending DMs

Telegram has no message-history API: a bot only sees messages that arrive after it is connected. SocialAPI builds the inbox from inbound webhook events from connect time onward.

List DM conversations

curl "https://api.social-api.ai/v1/inbox/conversations?account_id={id}" \
  -H "Authorization: Bearer $SOCAPI_KEY"

Send a DM

curl -X POST https://api.social-api.ai/v1/inbox/conversations/{conversation_id}/messages \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "{account_id}",
    "text": "Thanks for reaching out!"
  }'

account_id is required. Omitting it returns 400 field_required.

Send a DM with an attachment

Use attachment_url to send a file. SocialAPI picks the Telegram method based on the URL extension: image extensions (.jpg, .jpeg, .png, .gif, .webp) call sendPhoto; all other extensions call sendDocument.

curl -X POST https://api.social-api.ai/v1/inbox/conversations/{conversation_id}/messages \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "{account_id}",
    "text": "Here is the file you requested.",
    "attachment_url": "https://example.com/report.pdf"
  }'

Limitations and gotchas

The bot cannot start a conversation. Telegram forbids a bot from messaging a user who has never messaged it. Sending to such a user returns telegram.cannot_message (HTTP 403). The user must send /start or any message to the bot first. There is no 24-hour window once started.
No message history backfill. There is no list or history endpoint in the Bot API. The inbox is populated only by webhooks received after you connect.
DM-only. Posts, channels, and comments are not supported through this connector.
No token expiry. A bot token never expires. It is revoked only via @BotFather (/revoke). If a token is revoked, reconnect with a fresh token.

Errors

HTTP	Code	When it occurs
401	`platform.telegram.auth`	The bot token is invalid or has been revoked via @BotFather. Reconnect the account with a fresh token.
403	`telegram.cannot_message`	The bot cannot message this chat: the user has not started the bot, or blocked or removed it.
429	`platform.telegram.rate_limit`	Telegram rate-limited the bot. The `retry_after` metadata field contains the number of seconds to wait before retrying.

See Errors for the full catalog.

​At a glance

​Capabilities

​Connecting

​Getting a bot token

​Reading and sending DMs

​List DM conversations

​Send a DM

​Send a DM with an attachment

​Limitations and gotchas

​Errors

​Related