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.
| Parameter | Type | Description |
|---|---|---|
telegram_title | String | Text / caption for Telegram. Falls back to title. |
telegram_parse_mode | String | MarkdownV2 or HTML. |
telegram_entities | JSON array | Text posts: MessageEntity list, instead of telegram_parse_mode (not both). At most 4096 entities and 256 kB. |
telegram_caption_entities | JSON array | Media posts: entities of the caption, instead of telegram_parse_mode. The caption must fit in 1024 characters. |
telegram_message_thread_id | Integer | Forum topic to post in. |
telegram_direct_messages_topic_id | Integer | Topic of a channel direct messages chat (required by Telegram when the connected chat is one). |
telegram_disable_notification | Boolean | Send silently. |
telegram_protect_content | Boolean | Disallow forwarding and saving. |
telegram_reply_markup | JSON object | Inline 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_id | Integer | Publish 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_quote | String | With telegram_reply_to_message_id: the exact part of the message to quote (max 1024). |
telegram_reply_parameters | JSON object | The full ReplyParameters object instead of the two above (e.g. a reply to a message of another chat). |
telegram_message_effect_id | String | Message effect. Telegram only shows effects in private chats. |
telegram_pin | Boolean | Pin 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_notify | Boolean | With 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_reply | Boolean | first_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_parameters | JSON object | Only 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_parameters | JSON object | EphemeralMessageParameters: the message is shown only to receiver_user_id. |
telegram_allow_paid_broadcast | Boolean | Not 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)
| Parameter | Type | Description |
|---|---|---|
telegram_link_preview | Boolean | false turns the link preview off. |
telegram_link_preview_options | JSON object | LinkPreviewOptions: url, prefer_small_media / prefer_large_media, show_above_text, is_disabled. |
telegram_rich_message | true / markdown / html / JSON | Send 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:
| Parameter | Type | Telegram method | Notes |
|---|---|---|---|
telegram_poll | JSON object | sendPoll | options (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_location | JSON object | sendLocation | latitude, 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_venue | JSON object | sendVenue | latitude, longitude, address, title (defaults to the post text), foursquare_id, google_place_id… |
telegram_contact | JSON object | sendContact | phone_number, first_name, last_name, vcard (max 2048 bytes). |
telegram_dice | Emoji or true | sendDice | 🎲 🎯 🏀 ⚽ 🎳 🎰 (true = 🎲). |
telegram_game_short_name | String | sendGame | A 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)
| Parameter | Type | Description |
|---|---|---|
telegram_cover | String | Cover image of the video: public URL or Telegram file_id. |
telegram_start_timestamp | Integer | Second where the video starts playing. |
telegram_thumbnail | URL | Thumbnail: public URL of a JPEG under 200 kB, max 320×320. |
telegram_as_document | Boolean | Send the file as a document (no compression). |
telegram_media_urls | Comma-separated URLs | Up to 9 extra photos/videos by URL: the video plus these go out as one album. |
telegram_send_by_url | Boolean | When video is a URL, Telegram downloads it directly (max 20 MB by URL). |
telegram_send_as | String | animation (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_photo | URL | Still photo of the live photo. |
telegram_length | Integer | Video note diameter (defaults to the video width when it is square). |
telegram_caption_overflow | truncate / split | Caption 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_media | Boolean | Spoiler 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_urlfor bigger ones). telegram_as_document,telegram_has_spoiler,telegram_show_caption_above_media,telegram_caption_overflowas above.telegram_send_by_url=true: when everyphotos[]is a URL, Telegram downloads them directly (max 5 MB per photo by URL).
Paid media (Telegram Stars)
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_as | File | Extra parameters |
|---|---|---|
document (default) | anything | telegram_thumbnail, telegram_disable_content_type_detection |
audio | MP3, M4A | telegram_performer, telegram_title_audio, telegram_duration, telegram_thumbnail |
voice | OGG (Opus), MP3, M4A | telegram_duration |
animation | GIF, MP4 | telegram_duration, telegram_thumbnail |
sticker | WEBP, TGS, WEBM | telegram_emoji |
video_note | MP4 | telegram_duration, telegram_length |
video, photo | MP4/MOV, JPG/PNG/WEBP | as 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 unlesstelegram_pin_notify=true),action=stop_poll(returns the finalpoll),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 thepost_idmessage;delete_all_messages=truedeletes 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.
| Field | Type | Description |
|---|---|---|
user | String | Profile with Telegram connected. |
message_id | Integer | The suggested post. |
action | String | approve or decline. |
send_date | Integer | Approve: Unix time to publish it (max 30 days ahead). |
comment | String | Decline: note for the author (max 128). |
chat_id | String | The direct messages chat, if it is not the connected chat. |
The bot needs Post Messages to approve and Manage Direct Messages to decline.
Reads
| Endpoint | Telegram 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/uploadand/api/upload_photoslonger text or captions are refused with400(nothing is cut), except media captions withtelegram_caption_overflow=split. On/api/upload_documenta longer caption is cut at 1024 characters unless you usesplit. - 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.