Skip to main content

Telegram Chat Management

Manage the Telegram channel, group or supergroup connected to a profile, using the bot you connected (your token from @BotFather). Every call acts on the chat connected to that profile.

  • Authentication: API Key — Authorization: Apikey <YOUR_API_KEY>
  • Base: https://api.upload-post.com/api/uploadposts/telegram
  • Every request takes user (the profile username), in the JSON body, the form or the query string.
The bot needs the right administrator rights

Telegram only lets a bot manage a chat when it is an administrator with the matching right (you grant them in Telegram: chat settings → Administrators → your bot). When a right is missing the API answers 403 with:

  • error_code: "telegram_bot_not_admin" — the bot is not an administrator of the chat, or
  • error_code: "telegram_not_enough_rights" — it is, but lacks the right in required_right (for example can_restrict_members).

The right each endpoint needs is listed below.

Actions that need confirm: true

Banning, restricting, promoting or demoting members, changing the chat permissions, deleting the chat photo or the group sticker set, revoking links, creating a new primary link (it revokes the previous one), deleting a forum topic, unpinning everything and making the bot leave the chat answer 400 telegram_confirmation_required unless the request carries "confirm": true. Nothing is retried automatically.

Update chat info​

PATCH /api/uploadposts/telegram/chat-info — JSON or multipart/form-data (for the photo).

FieldTypeDescriptionBot right
titlestring1-128 characters. Not for private chats.can_change_info
descriptionstring0-255 characters. "" in a JSON body (or clear_description=true) removes it.can_change_info
photo / photo_urlfile / URLNew chat photo (multipart file, or a public URL we download, max 10 MB).can_change_info
delete_photobooleanRemove the chat photo. Needs confirm.can_change_info
permissionsobjectDefault ChatPermissions for every member (groups and supergroups). Only the keys you send change: we read the current permissions and merge, because Telegram takes every missing key as false. The response returns the resulting set in permissions. Needs confirm.can_restrict_members
use_independent_chat_permissionsbooleanTelegram's flag of the same name. Default true (the full merged set is applied as is).
sticker_set_name / delete_sticker_setstring / booleanGroup sticker set (supergroups). Delete needs confirm.can_change_info

Files given by URL are only downloaded once every field is valid and confirm is present. The changes are applied in that order. If one fails, the response says which ones were already applied (applied) and which one failed (failed_field).

curl -X PATCH https://api.upload-post.com/api/uploadposts/telegram/chat-info \
-H 'Authorization: Apikey your-api-key-here' -H 'Content-Type: application/json' \
-d '{"user": "my-profile", "title": "My Channel", "description": "Daily news"}'
{ "success": true, "chat_id": "-1001234567890", "updated": ["title", "description"], "message": "Telegram chat updated." }
MethodEndpointWhat it doesTelegram method
POST/invite-linksCreate a link: name (0-32), expire_date (future Unix time), member_limit (1-99999) or creates_join_request. With subscription_price (1-10000 Stars) it creates a paid subscription link for a channel (30-day period, the only one Telegram allows).createChatInviteLink, createChatSubscriptionInviteLink
PATCH/invite-linksEdit a link the bot created: invite_link + the same fields. For subscription links send subscription: true; only name can change.editChatInviteLink, editChatSubscriptionInviteLink
DELETE/invite-linksRevoke invite_link. Needs confirm.revokeChatInviteLink
POST/invite-links/primaryNew primary link; the bot's previous primary link stops working. Needs confirm.exportChatInviteLink

Bot right: can_invite_users. Bots can only edit or revoke links they created themselves. The response carries the ChatInviteLink in invite_link.

Join requests​

POST /join-requests with user_id and action: "approve" | "decline" (approveChatJoinRequest, declineChatJoinRequest; right can_invite_users). Requests come from links created with creates_join_request: true.

Members and administrators​

GET /members?user=my-profile&user_id=42 returns that member (getChatMember). Without user_id it lists the administrators (getChatAdministrators; return_bots=true includes other bots).

POST /members with action:

actionFieldsConfirmBot right
banuser_id, until_date (Unix time; 0 or omitted = forever), revoke_messages✅can_restrict_members
unbanuser_id, only_if_banned (default true here, so a current member is never kicked; false needs confirm)can_restrict_members
restrictuser_id, permissions (only the keys you send change: merged with the member's current restrictions, or with the chat's default permissions if the member has none), use_independent_chat_permissions (default true), until_date✅can_restrict_members
promoteuser_id, rights (object with the promoteChatMember booleans)✅can_promote_members
demoteuser_id (every right set to false)✅can_promote_members
set_titleuser_id, custom_title (0-16 characters, no emoji; admins promoted by the bot)can_promote_members
set_taguser_id, tag (0-16 characters, no emoji; omit to remove)can_manage_tags
ban_sender_chat / unban_sender_chatsender_chat_id (a channel posting in your group)ban ✅can_restrict_members
delete_all_reactionsuser_id or actor_chat_id (removes up to 10,000 recent reactions)✅can_delete_messages

user_id can't be the bot itself: use leave.

curl -X POST https://api.upload-post.com/api/uploadposts/telegram/members \
-H 'Authorization: Apikey your-api-key-here' -H 'Content-Type: application/json' \
-d '{"user": "my-profile", "action": "ban", "user_id": 123456789, "revoke_messages": true, "confirm": true}'

Forum topics (supergroups with topics)​

MethodEndpointFieldsTelegram method
GET/topics/icons—getForumTopicIconStickers (also returns the allowed icon_colors)
POST/topicsname (1-128), icon_color (one of 7322096, 16766590, 13338331, 9367192, 16749490, 16478047), icon_custom_emoji_idcreateForumTopic (returns message_thread_id)
PATCH/topicsmessage_thread_id + action: edit (name, icon_custom_emoji_id; "" removes the icon), close, reopen, unpin_all (confirm)editForumTopic, closeForumTopic, reopenForumTopic, unpinAllForumTopicMessages
PATCH/topicsgeneral: true + action: edit (name), close, reopen, hide, unhide, unpin_all (confirm)editGeneralForumTopic, closeGeneralForumTopic, reopenGeneralForumTopic, hideGeneralForumTopic, unhideGeneralForumTopic, unpinAllGeneralForumTopicMessages
DELETE/topicsmessage_thread_id, confirm — deletes the topic and all its messagesdeleteForumTopic

Bot right: can_manage_topics (can_pin_messages to unpin, can_delete_messages to delete). Telegram has no method to list topics. To publish inside a topic use telegram_message_thread_id when uploading.

Unpin every message​

POST /unpin-all with confirm: true (unpinAllChatMessages; right can_pin_messages in groups, can_edit_messages in channels). To pin or unpin one post use edit with action: "pin".

Leave the chat​

POST /leave with confirm: true (leaveChat). The bot stops being able to publish there until you add it back.

Errors​

All errors carry success: false, a stable error_code and a readable error; Telegram's own text is in telegram_error when there is one.

HTTPerror_codeMeaning
400user_required, profile_not_found, telegram_invalid_parameterMissing or invalid field (checked before calling Telegram).
400telegram_confirmation_requiredDestructive action without confirm: true.
400telegram_file_too_large, telegram_download_failedA photo or file is too big, or its URL could not be downloaded.
400telegram_bad_request, telegram_unsupported_chat_typeTelegram rejected it (e.g. topics in a chat that is not a forum).
401telegram_reconnect_requiredThe bot token was revoked or changed: reconnect Telegram.
403telegram_bot_not_admin, telegram_not_enough_rightsSee required_right.
403telegram_chat_unreachableThe bot is no longer in the chat.
403telegram_target_chat_unreachableRepost: the bot can't post in the destination chat.
403PROFILE_BLOCKEDThe profile is not available on your current plan.
404user_not_found, telegram_not_connected, profile_not_found, telegram_user_not_found
429telegram_rate_limitedTelegram flood limit; wait retry_after seconds.
502telegram_unreachableThe request never reached Telegram: safe to retry (retryable: true).
502telegram_api_errorTelegram failed.
504telegram_outcome_unknownTelegram did not answer in time after receiving a change: it may have been applied. retryable: false; check the chat before repeating.
503telegram_feature_disabledTemporarily disabled on our side.