Skip to main content

Telegram: updates, DMs and Business

Upload-Post publishes to Telegram with your own bot (see Connect Telegram). The same bot can also receive what people send it: private messages, button presses, inline queries, join requests, reactions, payments and, if you connect it to your Telegram Business account, the chats of that account.

Everything on this page is opt-in per bot. Until you turn it on, Upload-Post never changes your bot's webhook.

Not generally available yet

Receiving updates is not generally available yet: POST /api/uploadposts/telegram/updates with enabled: true (and receive_updates when connecting) answers 503 telegram_updates_unavailable, and GET reports enabled: false. Everything that depends on it (the dm_received and telegram_update events, listing conversations, real-time answers) has nothing to work with until then. Telegram Business answers 503 telegram_business_unavailable on every endpoint, reads included. Sending a DM with /dms/send to a person who started your bot already works.


How it works (read this first)​

  • A Telegram bot has one webhook. While a webhook is set, getUpdates stops working for that bot (Telegram docs).
  • When you turn updates on, Upload-Post checks the bot first:
    • If it already sends its updates to another webhook, nothing is changed and you get 409 telegram_webhook_in_use with that webhook's host. Send replace_existing_webhook: true to take it over (your other integration stops receiving updates, and Telegram does not let anyone restore it later). forward_url can keep feeding it.
    • If the bot has no webhook, Telegram cannot tell whether your own code reads it with getUpdates. The response then carries a warning: if you do, that code stops receiving updates.
  • The same bot in several profiles of your account shares one subscription; each profile receives the events of the bot. A bot already subscribed by another Upload-Post account answers 409 telegram_webhook_in_use unless you send replace_existing_webhook: true.
  • Messages are kept for 90 days and deleted when you disconnect the bot, turn updates off, delete the profile or delete your account (the bot's webhook is removed too, if it is still Upload-Post's).
  • Upload-Post only keeps private chats with your bot. Group and channel messages reach you as telegram_update but are never stored, and the chats of a Telegram Business account are kept only if you turn on business_chats.
  • A bot can only write to people who started it (/start) and did not block it. There is no 24-hour window for bot chats. In Business chats, Telegram lets the bot answer chats with an incoming message in the last 24 hours.

Turn updates on or off​

Endpoint​

POST /api/uploadposts/telegram/updates
GET /api/uploadposts/telegram/updates?user=<profile>

Body Parameters (JSON, POST)​

NameTypeRequiredDescription
userStringYesProfile username with the Telegram bot connected.
enabledBooleanYestrue to receive the bot's updates, false to stop (the last profile out removes the webhook and the stored messages).
replace_existing_webhookBooleanNoReplace a webhook that is not Upload-Post's. Default false.
forward_urlStringNoPublic https:// URL. Every raw Telegram update is also sent there, signed like your other Upload-Post webhooks (X-Upload-Post-Signature), event header telegram.update_forward. Needs a webhook secret on your account (webhook secret). One attempt per update, no retries; button presses, inline queries and payments go out first. Send null to remove it.
business_chatsBooleanNoAlso receive and keep the private chats of the Telegram Business account connected to the bot (see Business). Default false; turning it off deletes the stored Business chats.
auto_answer_callbacksBooleanNoIf you have not answered a button press after about 8 seconds, Upload-Post sends an empty answer so the user's spinner stops. Default false.
extra_updatesArrayNoExtra update types, only if you need them: channel_post, edited_channel_post, chat_member, chat_boost, removed_chat_boost, managed_bot, stopped_message_generation.

You can also turn it on when connecting the bot: add "receive_updates": true to Connect Telegram. The connection succeeds either way; the result of the subscription comes in updates.

Example​

curl -X POST https://api.upload-post.com/api/uploadposts/telegram/updates \
-H "Authorization: Apikey YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"user": "my_profile", "enabled": true}'
{
"success": true,
"platform": "telegram",
"enabled": true,
"bot": {"id": "123456789", "username": "my_shop_bot"},
"profiles_subscribed": 1,
"forward_url": null,
"auto_answer_callbacks": false,
"allowed_updates": ["message", "edited_message", "callback_query", "..."],
"last_update_at": null,
"warning": "This bot had no webhook. If your own code reads it with getUpdates, it stops receiving updates now..."
}

GET returns the same object plus webhook (pending_update_count, last_error_date, last_error_message as Telegram reports them) and webhook_replaced: true if someone changed the bot's webhook afterwards.

Errors​

Statuserror_codeMeaning
400telegram_not_connectedThe profile has no Telegram bot.
400telegram_invalid_forward_urlforward_url is not a public https URL.
401telegram_reauth_requiredTelegram no longer accepts the bot token (revoked in @BotFather). Reconnect.
400telegram_forward_needs_secretforward_url needs a webhook secret on the account first.
409telegram_webhook_in_useThe bot already has another webhook (webhook_host), or another Upload-Post account receives it.
409telegram_updates_busyAnother request is changing this bot's subscription right now. Retry in a few seconds.
503telegram_updates_unavailable / telegram_updates_not_configuredNot available yet or temporarily, retry later.

Events you receive​

Subscribe in webhook_events (account or per-profile webhooks). Both are opt-in.

  • dm_received: a private message to your bot, or an incoming message in a connected Business chat.
{
"event": "dm_received",
"platform": "telegram",
"profile_username": "my_profile",
"account_id": "123456789",
"sender": {"id": "777000111", "username": "ana", "name": "Ana García"},
"conversation_id": "123456789:777000111",
"message": {"id": "42", "text": "Hi!", "type": "text", "attachments": [], "reply_to": null, "media_group_id": null},
"timestamp": "2026-11-14T10:00:00+0000"
}

Business chats add "business_connection_id". Attachments come as {"type": "photo", "media_id": "<file_id>", ...}; download them with GET /dms/media.

  • telegram_update: every update of the bot, raw, as Telegram sent it: callback_query (button presses), inline_query, chosen_inline_result, chat_join_request, guest_message, widget_query, shared_widget_query, shipping_query, pre_checkout_query, poll, poll_answer, message_reaction, message_reaction_count, my_chat_member, business_connection, messages in groups...
{
"event": "telegram_update",
"platform": "telegram",
"profile_username": "my_profile",
"account_id": "123456789",
"bot": {"id": "123456789", "username": "my_shop_bot"},
"update_id": 918273645,
"update_type": "callback_query",
"update": {"id": "4382bfdwdsb323b2d9", "from": {"id": 777000111}, "data": "buy_42", "chat_instance": "..."}
}

Group and channel messages are never stored by Upload-Post: they only reach you as telegram_update. telegram_update is real-time: it is not retried, and the deliveries log keeps only its envelope (event, type, update_id), not the update itself. A pre-checkout or shipping query that your automatic payment rule already answered is not sent to you. If the bot is removed from the connected channel or group, the account is marked as needing reconnection.


Direct messages​

Telegram uses the common DM endpoints with platform: "telegram". recipient_id is the numeric chat id of a person (the sender.id of dm_received): groups and channels are refused (400 telegram_private_chats_only); publish to them with the upload endpoints.

Send: POST /api/uploadposts/dms/send​

NameTypeDescription
messageStringText, up to 4096 characters (1024 as a caption of an attachment).
parse_mode / entitiesString / ArrayMarkdownV2, HTML or Markdown, or a list of MessageEntity. Not both.
attachmentsArrayStickers and video notes carry no text (send the message separately). Up to 10: {"type": "photo|video|document|audio|voice|animation|sticker|video_note", "url": "https://..."} or {"type": ..., "media_id": "<file_id>"}. Telegram downloads URLs itself (photos up to 5 MB, other files up to 20 MB). Several attachments go out as one album: photos and videos together, or only documents, or only audios. Video notes only by media_id.
buttonsArrayInline keyboard: {text, url} or {text, callback_data} (1-64 bytes), or a list of rows. Presses arrive as telegram_update (callback_query). reply_markup with an inline_keyboard is accepted too.
reply_toInteger or ObjectMessage id to reply to, or a ReplyParameters object (quote...).
location / contactObject{latitude, longitude[, title, address]} (with title and address it is a venue) / {phone_number, first_name[, last_name, vcard]}.
disable_notification, protect_content, link_preview, message_effect_idAs in the Bot API. link_preview: false hides the preview.
business_connection_idStringSend as your connected Business account (see Business).
checklistObjectBusiness only: an InputChecklist (title and 1-30 tasks).
message_thread_idIntegerTopic of a private chat with topics enabled.
sender_actionStringtyping, upload_photo, record_video, upload_video, record_voice, upload_voice, upload_document, choose_sticker, find_location, record_video_note, upload_video_note; react / unreact (with message_id and reaction: an emoji or a list of ReactionType); delete (message_id or message_ids, up to 100; Telegram allows 48 hours); Business only: mark_read and edit_checklist. Sender actions do not use the daily DM quota.

Response:

{"success": true, "platform": "telegram", "recipient_id": "777000111", "conversation_id": "123456789:777000111",
"message_id": "43", "created_time": "2026-11-14T10:00:05+0000", "message": "Telegram DM sent successfully"}

Albums also return message_ids. Errors: 400 telegram_invalid_recipient (recipient_id is not a numeric chat id: @username is not accepted), 403 telegram_recipient_not_started (the person never started the bot), 403 telegram_recipient_blocked, 404 telegram_chat_not_found, 429 telegram_rate_limited (with retry_after), 400 telegram_rejected (Telegram's own wording), 504 telegram_send_unconfirmed (it may have been sent: read the conversation before sending again).

Read: GET /api/uploadposts/dms/conversations?platform=telegram&user=<profile>​

Needs updates turned on (409 telegram_updates_not_enabled otherwise). Only messages received or sent since then are listed: Telegram has no history API. Same parameters and shape as the other networks (limit, cursor, since, participant_id, messages_limit), plus business_connection_id for a Business inbox and include_profile_photos=true (adds profile_pic_media_id to each contact).

Download an attachment​

GET /api/uploadposts/dms/media?platform=telegram&user=<profile>&media_id=<file_id> returns the file (Telegram lets bots download up to 20 MB). Telegram has no separate upload step: send files by URL in attachments.


Answer in real time: POST /api/uploadposts/telegram/answer​

typeTelegram methodFields
callbackanswerCallbackQuerycallback_query_id, text (0-200), show_alert, url, cache_time
inlineanswerInlineQueryinline_query_id, results (≤50), cache_time, is_personal, next_offset, button
join_requestanswerChatJoinRequestQuerychat_join_request_query_id, result (approve, decline, queue)
join_request_web_appsendChatJoinRequestWebAppchat_join_request_query_id, web_app_url (https)
guestanswerGuestQueryguest_query_id, result (InlineQueryResult)
widgetanswerWidgetQuerywidget_query_id, data (≤1024 bytes)
shippinganswerShippingQueryshipping_query_id, ok, shipping_options or error_message
pre_checkoutanswerPreCheckoutQuerypre_checkout_query_id, ok, error_message

query_id works for any type. Telegram's clocks are short (join requests and pre-checkout: 10 seconds; widgets: 15 seconds), so answer as soon as the telegram_update arrives. An expired query answers 410 telegram_query_expired.

curl -X POST https://api.upload-post.com/api/uploadposts/telegram/answer \
-H "Authorization: Apikey YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"user": "my_profile", "type": "callback", "query_id": "4382bfdwdsb323b2d9", "text": "Added to cart"}'

Telegram Business​

Business features are not generally available yet: every endpoint of this section answers 503 telegram_business_unavailable until they are. Connect your bot to your personal or business Telegram account: turn on Business Mode for the bot in @BotFather, then in Telegram open Settings > Business > Chatbots, add the bot and choose its rights. No Telegram Premium is needed. With updates turned on, Upload-Post receives the connection (business_connection event) and the chats of the account; the bot then acts as you.

  • Chats (only with business_chats: true on /telegram/updates): dm_received with business_connection_id, /dms/conversations?business_connection_id=..., and /dms/send with business_connection_id (replies, mark_read, delete, checklists).
  • GET /api/uploadposts/telegram/business-connections?user=<profile>: the connections we know (id, user, rights, is_enabled). Add business_connection_id to refresh one from Telegram.

Every endpoint below takes user and business_connection_id (optional when the bot has a single active connection). Missing rights answer 403 telegram_business_right_missing with the right.

EndpointWhat it does
GET /telegram/business-profileThe connected account (name, username, rights).
PATCH /telegram/business-profilefirst_name + last_name, username, bio (≤140), photo (multipart JPG or animation MP4, or media_url; is_public, main_frame_timestamp), remove_photo, gift_settings (show_gift_button, accepted_gift_types).
POST /telegram/business-storiesPost a story: multipart file (or media_url), active_period (6, 12, 24 or 48 hours), caption (≤2048), parse_mode, caption_entities, areas, post_to_chat_page, protect_content; videos also duration, cover_frame_timestamp, is_animation. Photos 1080x1920 up to 10 MB; videos 720x1280 H.265 up to 30 MB and 60 s. Returns story_id.
PATCH /telegram/business-storiesEdit a story (story_id + new content).
DELETE /telegram/business-storiesDelete a story (story_id).
POST /telegram/business-stories/repostRepost a story from another Business account managed by the same bot (from_chat_id, from_story_id, active_period).
GET /telegram/business-giftsGifts owned by the account (Telegram's filters: exclude_unique, sort_by_price, offset, limit...).
POST /telegram/business-giftsaction: convert (to Stars), upgrade, transfer (new_owner_chat_id), delete; owned_gift_id, star_count where Telegram asks for it. Requires confirm: true and an idempotency_key: it cannot be undone.
GET /telegram/business-starsStars balance of the account.
POST /telegram/business-stars/transferMove 1-10000 Stars from the account to the bot. Requires confirm: true and an idempotency_key.

Moving Stars or gifts may not be enabled on your account yet (503 telegram_business_money_unavailable). idempotency_key is any unique string up to 128 characters (for example your own operation id): repeating a request with the same key returns the first answer instead of moving anything again; the same key with different data answers 409 idempotency_key_reused, and a key whose outcome is unknown (Telegram did not confirm) answers 409 telegram_outcome_unknown: check the account before trying with a new key.

All paths are under /api/uploadposts.