Skip to main content

Telegram Publishing Options

Your connected bot publishes in the chat, group or channel you connected (see Connecting Telegram). Everything on this page is optional: without these parameters a post goes out exactly as before.

The options use the official Telegram Bot API names with a telegram_ prefix, and JSON options take the official object as-is (ReplyParameters, LinkPreviewOptions, MessageEntity, InputRichMessage…). They work the same way in immediate, asynchronous and scheduled posts. Send booleans as true/false and JSON options as a JSON string in the multipart form.

  • Authentication: API Key — Authorization: Apikey <YOUR_API_KEY>

Options for every post​

These work on /api/upload (video), /api/upload_photos, /api/upload_text and /api/upload_document.

ParameterTypeDescription
telegram_titleStringText / caption for Telegram. Falls back to title.
telegram_parse_modeStringMarkdownV2 or HTML.
telegram_entitiesJSON arrayText posts: MessageEntity list, instead of telegram_parse_mode (not both). At most 4096 entities and 256 kB.
telegram_caption_entitiesJSON arrayMedia posts: entities of the caption, instead of telegram_parse_mode. The caption must fit in 1024 characters.
telegram_message_thread_idIntegerForum topic to post in.
telegram_direct_messages_topic_idIntegerTopic of a channel direct messages chat (required by Telegram when the connected chat is one).
telegram_disable_notificationBooleanSend silently.
telegram_protect_contentBooleanDisallow forwarding and saving.
telegram_reply_markupJSON objectInline keyboard: {"inline_keyboard": [[{"text": "Open", "url": "https://…"}]]}. Use URL buttons: buttons with callback_data need your own bot to answer them.
telegram_reply_to_message_idIntegerPublish as a reply to this message of the chat. Replying to a suggested post makes Telegram decline it automatically; the response then carries a warnings entry.
telegram_reply_quoteStringWith telegram_reply_to_message_id: the exact part of the message to quote (max 1024).
telegram_reply_parametersJSON objectThe full ReplyParameters object instead of the two above (e.g. a reply to a message of another chat).
telegram_message_effect_idStringMessage effect. Telegram only shows effects in private chats.
telegram_pinBooleanPin the post after publishing, silently (no notification to members). The bot needs the right to pin. The response says pinned: true/false (and pin_error); a failed pin never fails the post.
telegram_pin_notifyBooleanWith telegram_pin: notify the members about the pin. Only matters in groups: Telegram never notifies a pin in channels or private chats.
telegram_first_comment_as_replyBooleanfirst_comment (or telegram_first_comment) is sent as a reply to the post. Default true; false sends it as a separate message.
telegram_suggested_post_parametersJSON objectOnly for channel direct messages chats: SuggestedPostParameters (send_date). A price can be paid from your bot's balance and is not available on Upload-Post for now (the Telegram result fails with telegram_invalid_parameter).
telegram_ephemeral_message_parametersJSON objectEphemeralMessageParameters: the message is shown only to receiver_user_id.
telegram_allow_paid_broadcastBooleanNot available on Upload-Post for now (the Telegram result fails with telegram_invalid_parameter): it can spend your bot's Stars. Telegram's paid broadcasts let a bot send up to 1000 messages/s; only messages above the free 30 per second cost 0.1 Telegram Stars each, taken from the bot's balance, and the bot needs at least 100,000 Stars and 100,000 monthly active users (FAQ).

Text posts (/api/upload_text)​

ParameterTypeDescription
telegram_link_previewBooleanfalse turns the link preview off.
telegram_link_preview_optionsJSON objectLinkPreviewOptions: url, prefer_small_media / prefer_large_media, show_above_text, is_disabled.
telegram_rich_messagetrue / markdown / html / JSONSend a rich message (headings, lists, tables, quotes, formulas, up to 32,768 characters). true = the post text is rich Markdown, html = rich HTML, or pass the InputRichMessage object (one of markdown, html, blocks).

Polls, locations, contacts, dice and games​

Send one of these with /api/upload_text:

ParameterTypeTelegram methodNotes
telegram_pollJSON objectsendPolloptions (1-12 answers, 1-100 characters, plain strings or InputPollOption), question (1-300, defaults to the post text), type (regular/quiz), correct_option_ids (quiz), is_anonymous, allows_multiple_answers, explanation (max 200), description (max 1024), open_period (5-2628000 s) or close_date, members_only, country_codes… Every official field is passed through.
telegram_locationJSON objectsendLocationlatitude, longitude, horizontal_accuracy (0-1500). Live location: live_period (60-86400 s, or 2147483647 = no end), heading (1-360), proximity_alert_radius (1-100000).
telegram_venueJSON objectsendVenuelatitude, longitude, address, title (defaults to the post text), foursquare_id, google_place_id…
telegram_contactJSON objectsendContactphone_number, first_name, last_name, vcard (max 2048 bytes).
telegram_diceEmoji or truesendDice🎲 🎯 🏀 ⚽ 🎳 🎰 (true = 🎲).
telegram_game_short_nameStringsendGameA game you created in @BotFather. Not available in channels.

Locations, contacts, dice and games have no text of their own, so the post text is sent first as a normal message and the interactive message right after it (telegram_send_title=false skips the text). post_id is the interactive message. Deleting the post with the default unpublish removes only that message: send delete_all_messages=true to delete the text sent before it too.

curl -X POST https://api.upload-post.com/api/upload_text \
-H "Authorization: Apikey your-api-key-here" \
-F 'user=my_profile' -F 'platform[]=telegram' \
-F 'title=Which day works best for the live session?' \
-F 'telegram_poll={"options": ["Monday", "Wednesday", "Friday"], "is_anonymous": false}'

Videos (/api/upload)​

ParameterTypeDescription
telegram_coverStringCover image of the video: public URL or Telegram file_id.
telegram_start_timestampIntegerSecond where the video starts playing.
telegram_thumbnailURLThumbnail: public URL of a JPEG under 200 kB, max 320×320.
telegram_as_documentBooleanSend the file as a document (no compression).
telegram_media_urlsComma-separated URLsUp to 9 extra photos/videos by URL: the video plus these go out as one album.
telegram_send_by_urlBooleanWhen video is a URL, Telegram downloads it directly (max 20 MB by URL).
telegram_send_asStringanimation (GIF-style, no sound), video_note (round video, square, max 60 s; the post text goes first as a message), live_photo (max 10 s and 10 MB, needs telegram_live_photo_photo), document. Nothing is converted unless you ask.
telegram_live_photo_photoURLStill photo of the live photo.
telegram_lengthIntegerVideo note diameter (defaults to the video width when it is square).
telegram_caption_overflowtruncate / splitCaption over 1024 characters. By default (truncate) the request is refused with 400 (on /api/upload_document the caption is cut); split sends the first part as the caption and the rest as a reply.
telegram_has_spoiler, telegram_show_caption_above_mediaBooleanSpoiler animation; caption above the media.

Photos (/api/upload_photos)​

  • Up to 10 items per album. Videos can be mixed with photos in the same request: they go out as one album (at most 150 MB in total for albums with videos; use telegram_send_by_url for bigger ones).
  • telegram_as_document, telegram_has_spoiler, telegram_show_caption_above_media, telegram_caption_overflow as above.
  • telegram_send_by_url=true: when every photos[] is a URL, Telegram downloads them directly (max 5 MB per photo by URL).

telegram_paid_star_count (1-25000) on /api/upload_photos or /api/upload sends the photos/videos as paid media: readers pay that many Stars to unlock them. In a channel the Stars go to the channel's balance, elsewhere to your bot's balance. Upload-Post does not take any part. telegram_paid_payload (max 128 bytes) is an internal reference that readers never see. Up to 10 items.

Any file: audio, voice, stickers, GIFs, documents (/api/upload_document)​

/api/upload_document accepts platform[]=telegram with any file up to 50 MB (document as a file or a public URL). By default it is sent as a document; telegram_send_as changes the type:

telegram_send_asFileExtra parameters
document (default)anythingtelegram_thumbnail, telegram_disable_content_type_detection
audioMP3, M4Atelegram_performer, telegram_title_audio, telegram_duration, telegram_thumbnail
voiceOGG (Opus), MP3, M4Atelegram_duration
animationGIF, MP4telegram_duration, telegram_thumbnail
stickerWEBP, TGS, WEBMtelegram_emoji
video_noteMP4telegram_duration, telegram_length
video, photoMP4/MOV, JPG/PNG/WEBPas above

Stickers and video notes have no caption: the post text goes first as a message (telegram_send_title=false skips it). telegram_media_urls adds more documents or audios by URL to make an album. telegram_send_by_url=true lets Telegram download the document URL (Telegram only supports this for PDF and ZIP). LinkedIn and Telegram can be combined in one request; then the file must also meet LinkedIn's document rules.

curl -X POST https://api.upload-post.com/api/upload_document \
-H "Authorization: Apikey your-api-key-here" \
-F 'user=my_profile' -F 'platform[]=telegram' \
-F 'title=Episode 12' -F '[email protected]' \
-F 'telegram_send_as=audio' -F 'telegram_performer=My Podcast'

Response​

The usual result per platform (success, post_id, url). Posts made of several messages also return message_ids: every message of the post in the order it was sent (the text sent before a location, contact, dice or sticker, each album item, the caption rest and the first comment). post_id is the main message (the first album item, or the poll, location, contact, dice or sticker itself). Polls, locations and the other interactive messages add telegram_type.

An invalid value in one of the options on this page fails only Telegram's part of the request: results.telegram has success: false, error_code: "telegram_invalid_parameter" and an error that names the field. Nothing is sent to the chat and the other platforms of the request publish as usual.

Once the post is in the chat, what comes after it never turns it into a failure: if the rest of the caption, the first comment or the pin fail, the post is still success: true and the result says which step failed (caption_rest_error, first_comment_error, pin_error).

If Telegram does not answer for the main message of a post whose text was already sent before it (location, contact, dice, game, video note, sticker), the result is success: false, error_code: "telegram_outcome_unknown", retryable: false and published_message_ids: the message may or may not be in the chat, so check the chat before publishing again. When Telegram refuses the main message, the text sent before it is deleted.

Edit, repost and delete a post​

These go through the common post actions with platform=telegram and the post_id returned when publishing:

  • Edit (/api/uploadposts/posts/edit): new text or caption, buttons, action=pin / unpin (silent unless telegram_pin_notify=true), action=stop_poll (returns the final poll), action=edit_live_location / stop_live_location, a new rich message, or replace the media.
  • Repost (/api/uploadposts/posts/repost): forward or copy the post to the same chat or another one.
  • Delete (/api/uploadposts/posts/unpublish): by default only the post_id message; delete_all_messages=true deletes every message of the post. Bots can delete messages for 48 hours, and in a private chat Telegram does not let anyone delete a dice message during its first 24 hours.

Suggested posts​

POST /api/uploadposts/telegram/suggested-posts approves or declines a suggested post received in your channel's direct messages.

FieldTypeDescription
userStringProfile with Telegram connected.
message_idIntegerThe suggested post.
actionStringapprove or decline.
send_dateIntegerApprove: Unix time to publish it (max 30 days ahead).
commentStringDecline: note for the author (max 128).
chat_idStringThe direct messages chat, if it is not the connected chat.

The bot needs Post Messages to approve and Manage Direct Messages to decline.

Reads​

EndpointTelegram method
GET /api/uploadposts/telegram/users/{user_id}/personal-chat-messages?user=&limit= (1-20, default 20)getUserPersonalChatMessages
GET /api/uploadposts/telegram/users/{user_id}/profile-audios?user=&offset=&limit= (1-100)getUserProfileAudios
GET /api/uploadposts/telegram/share-theme-backdrops?user=getChatShareThemeBackdrops

Errors carry a stable error_code: telegram_not_connected (400), telegram_invalid_parameter (400), telegram_bad_request (400, Telegram refused the request), telegram_not_enough_rights (403), telegram_message_not_found (404), telegram_rate_limited (429, with retry_after), telegram_reconnect_required, telegram_unreachable (502, nothing was changed), telegram_api_error.

Limits​

  • Files: 10 MB photos and 50 MB other files when uploaded; 5 MB photos and 20 MB other files when Telegram downloads them by URL (Sending files).
  • Text 4096 characters, captions 1024, rich messages 32,768. On /api/upload_text, /api/upload and /api/upload_photos longer text or captions are refused with 400 (nothing is cut), except media captions with telegram_caption_overflow=split. On /api/upload_document a longer caption is cut at 1024 characters unless you use split.
  • About 1 message per second per chat and 20 per minute in groups (FAQ).
  • Not offered by the Telegram Bot API: views or channel statistics, chat history, native scheduling (Upload-Post schedules for you), stories in channels.