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.
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, orerror_code: "telegram_not_enough_rights"— it is, but lacks the right inrequired_right(for examplecan_restrict_members).
The right each endpoint needs is listed below.
confirm: trueBanning, 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).
| Field | Type | Description | Bot right |
|---|---|---|---|
title | string | 1-128 characters. Not for private chats. | can_change_info |
description | string | 0-255 characters. "" in a JSON body (or clear_description=true) removes it. | can_change_info |
photo / photo_url | file / URL | New chat photo (multipart file, or a public URL we download, max 10 MB). | can_change_info |
delete_photo | boolean | Remove the chat photo. Needs confirm. | can_change_info |
permissions | object | Default 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_permissions | boolean | Telegram's flag of the same name. Default true (the full merged set is applied as is). | |
sticker_set_name / delete_sticker_set | string / boolean | Group 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." }
Invite links
| Method | Endpoint | What it does | Telegram method |
|---|---|---|---|
POST | /invite-links | Create 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-links | Edit a link the bot created: invite_link + the same fields. For subscription links send subscription: true; only name can change. | editChatInviteLink, editChatSubscriptionInviteLink |
DELETE | /invite-links | Revoke invite_link. Needs confirm. | revokeChatInviteLink |
POST | /invite-links/primary | New 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:
action | Fields | Confirm | Bot right |
|---|---|---|---|
ban | user_id, until_date (Unix time; 0 or omitted = forever), revoke_messages | ✅ | can_restrict_members |
unban | user_id, only_if_banned (default true here, so a current member is never kicked; false needs confirm) | can_restrict_members | |
restrict | user_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 |
promote | user_id, rights (object with the promoteChatMember booleans) | ✅ | can_promote_members |
demote | user_id (every right set to false) | ✅ | can_promote_members |
set_title | user_id, custom_title (0-16 characters, no emoji; admins promoted by the bot) | can_promote_members | |
set_tag | user_id, tag (0-16 characters, no emoji; omit to remove) | can_manage_tags | |
ban_sender_chat / unban_sender_chat | sender_chat_id (a channel posting in your group) | ban ✅ | can_restrict_members |
delete_all_reactions | user_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)
| Method | Endpoint | Fields | Telegram method |
|---|---|---|---|
GET | /topics/icons | — | getForumTopicIconStickers (also returns the allowed icon_colors) |
POST | /topics | name (1-128), icon_color (one of 7322096, 16766590, 13338331, 9367192, 16749490, 16478047), icon_custom_emoji_id | createForumTopic (returns message_thread_id) |
PATCH | /topics | message_thread_id + action: edit (name, icon_custom_emoji_id; "" removes the icon), close, reopen, unpin_all (confirm) | editForumTopic, closeForumTopic, reopenForumTopic, unpinAllForumTopicMessages |
PATCH | /topics | general: true + action: edit (name), close, reopen, hide, unhide, unpin_all (confirm) | editGeneralForumTopic, closeGeneralForumTopic, reopenGeneralForumTopic, hideGeneralForumTopic, unhideGeneralForumTopic, unpinAllGeneralForumTopicMessages |
DELETE | /topics | message_thread_id, confirm — deletes the topic and all its messages | deleteForumTopic |
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.
| HTTP | error_code | Meaning |
|---|---|---|
| 400 | user_required, profile_not_found, telegram_invalid_parameter | Missing or invalid field (checked before calling Telegram). |
| 400 | telegram_confirmation_required | Destructive action without confirm: true. |
| 400 | telegram_file_too_large, telegram_download_failed | A photo or file is too big, or its URL could not be downloaded. |
| 400 | telegram_bad_request, telegram_unsupported_chat_type | Telegram rejected it (e.g. topics in a chat that is not a forum). |
| 401 | telegram_reconnect_required | The bot token was revoked or changed: reconnect Telegram. |
| 403 | telegram_bot_not_admin, telegram_not_enough_rights | See required_right. |
| 403 | telegram_chat_unreachable | The bot is no longer in the chat. |
| 403 | telegram_target_chat_unreachable | Repost: the bot can't post in the destination chat. |
| 403 | PROFILE_BLOCKED | The profile is not available on your current plan. |
| 404 | user_not_found, telegram_not_connected, profile_not_found, telegram_user_not_found | |
| 429 | telegram_rate_limited | Telegram flood limit; wait retry_after seconds. |
| 502 | telegram_unreachable | The request never reached Telegram: safe to retry (retryable: true). |
| 502 | telegram_api_error | Telegram failed. |
| 504 | telegram_outcome_unknown | Telegram did not answer in time after receiving a change: it may have been applied. retryable: false; check the chat before repeating. |
| 503 | telegram_feature_disabled | Temporarily disabled on our side. |
Related
- Bot profile and commands
- Sticker sets
- Edit, Unpublish, Repost a Telegram post