Telegram API

Connect a channel or group through RelayAPI's managed bot and publish text, media, albums, and documents.

Current RelayAPI capability

Hosted users do not submit a Telegram bot token. The connection and publisher use RelayAPI's managed bot and store the authorized chat ID as the account identity.

Connect a channel or group

Initiate a challenge:

curl -X POST "https://api.relayapi.dev/v1/connect/telegram?workspace_id=ws_example" \
  -H "Authorization: Bearer $RELAY_API_KEY"

The response contains the bot username, an RLAY-... code, an expiry timestamp, and exact instructions. Before sending the challenge:

1. Add the named bot to the target channel, group, or supergroup.
2. For a channel, make the bot an administrator and enable Post Messages.
3. Open a private chat with the bot and send RLAY-... @targetusername.
4. Poll the challenge with the same API key.

curl --get https://api.relayapi.dev/v1/connect/telegram \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  --data-urlencode "code=$TELEGRAM_CHALLENGE"

RelayAPI verifies both actors before creating the account:

• The human who sends the private challenge must be the target chat's creator or an administrator.
• In a channel, the managed bot must be creator/administrator and can_post_messages must be true.
• In a group or supergroup, the managed bot must be a member/administrator (or a restricted member explicitly allowed to send messages).

The challenge lasts 15 minutes, is one-time, and remains bound to the initiating organization, API key/session, and workspace authority. The current challenge format requires a public @username; an unaddressable private channel cannot complete it.

Publish text

curl -X POST https://api.relayapi.dev/v1/posts \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: telegram-update-20260809" \
  -d '{
    "content": "<b>Deployment complete</b>",
    "targets": ["acc_telegram_example"],
    "scheduled_at": "now",
    "target_options": {
      "telegram": {
        "parse_mode": "HTML",
        "silent": true
      }
    }
  }'

The account's stored platform_account_id is the destination chat. A post request cannot select another chat_id.

Publish media

A single media item uses the matching Bot API method (sendPhoto, sendVideo, sendAnimation, or sendDocument). Its caption is the post content.

{
  "content": "Product gallery",
  "targets": ["acc_telegram_example"],
  "media": [
    {"url": "https://cdn.example.com/front.jpg", "type": "image"},
    {"url": "https://cdn.example.com/demo.mp4", "type": "video"}
  ],
  "scheduled_at": "now",
  "target_options": {
    "telegram": {"protect_content": true}
  }
}

Two or more items use sendMediaGroup; only the first item receives the caption. RelayAPI rejects groups containing an animation/GIF and groups that mix a document with a photo or video. Telegram fetches the public URLs and remains authoritative for current MIME, size, dimension, and duration requirements. A group can contain up to ten videos, subject to the ten-item album total.

target_options.telegram

Edit an outbound message

RelayAPI can edit text on a Telegram bot-authored message already persisted in an inbox conversation. It cannot edit an inbound user message. The provider write requires an idempotency key and returns a durable operation; see Published Edits and Social Actions.

Confirmation and lifecycle

RelayAPI reports a Telegram publish as successful only when the Bot API returns ok: true and the expected Message object or Message array. It records every Message ID returned for a media group as a durable provider effect; the first ID remains the target's primary platform_post_id and is used to build a t.me URL when the chat address permits one. An incomplete album response becomes outcome-unknown instead of being replayed. The Bot API send response is the terminal confirmation available to this publisher; RelayAPI does not claim a separate asynchronous delivery/read lifecycle.

Unpublishing retries deletion for every recorded message in an album, not only its first item. Telegram's “message to delete not found” response is treated idempotently so a retry can finish after an earlier partial delete. Telegram's own deletion age and chat-permission rules still apply.

• Removing the bot or revoking its posting permission causes future publishes to fail. Restoring the same permission can resume publishing without changing the stored chat ID.
• If the destination changes, run a new challenge; post options cannot retarget the account.
• A self-hosted operator supplies its own TELEGRAM_BOT_TOKEN and TELEGRAM_WEBHOOK_SECRET. Tenant users still use the same managed-bot challenge and never place those secrets in connection requests.
• Respect Telegram's retry_after on rate limits and reuse the same RelayAPI idempotency key/body for a safe retry.

Official Telegram references

• Bot API: getMe, getChatMember, and administrator permissions
• Bot API: sendMessage
• Bot API: sendMediaGroup
• Bots introduction and BotFather