# OmniSocials Telegram API > Post to your Telegram channel or group with one REST call: photos, videos, albums, polls and link buttons. No bot token, no BotFather, no webhook server. Read reactions per emoji and poll votes. This is the machine-readable version of [omnisocials.com/telegram-api](https://omnisocials.com/telegram-api), maintained for AI agents. Facts checked against the OmniSocials app and API on October 17, 2026. Platform reference: [docs.omnisocials.com/platforms/telegram](https://docs.omnisocials.com/platforms/telegram). API reference: [docs.omnisocials.com/api](https://docs.omnisocials.com/api). ## Basics - Base URL: `https://api.omnisocials.com/v1` - Auth: `Authorization: Bearer omsk_live_...`. One key belongs to one workspace. Keys are created in the app under Settings, API. - Channel id in `accounts`: `telegram`. The account connects inside the OmniSocials app, not through the API. - Rate limit: 100 requests per minute per key. A 429 carries `Retry-After`. - Responses use a `{ "data": ... }` envelope. Create returns `201`. - Webhooks: `post.scheduled`, `post.published`, `post.failed`, `post.approved`, `post.rejected`, signed with HMAC-SHA256 in `X-OmniSocials-Signature`. ## Skip building a Telegram bot Telegram’s Bot API is free, but the bot is yours to build: create it with BotFather, run a webhook server or a long-poll loop, store every chat id, check the bot’s admin rights, upload the media, split captions over 1,024 characters and retry on 429. OmniSocials runs that bot for you. - On your own: BotFather, Webhook, Chat ids, Admin rights, Uploads, Captions, Retries, Reconnects, then the first post. - Permissions your own app must get approved: `can_post_messages`, `can_edit_messages`, `can_pin_messages`. - On OmniSocials: sign in, create an API key, POST. Our bot, added with Telegram’s chat picker. ## Schedule a post ```bash curl -X POST https://api.omnisocials.com/v1/posts/create \ -H "Authorization: Bearer $OMNISOCIALS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "content": "New: Best times to post", "accounts": ["telegram"], "media_urls": ["https://cdn.example.com/best-times.png"], "telegram": { "buttons": [ { "text": "Read the docs", "url": "https://docs.omnisocials.com/api/analytics" } ] }, "schedule_at": "2026-10-22T18:00:00Z" }' ``` The answer (`201`, shortened): ```json { "data": { "id": "1024", "status": "scheduled", "app_url": "https://app.omnisocials.com/create-post/1024" } } ``` ## Every Telegram format, one request Text, a photo, a video, a GIF, albums of up to 10 and native polls share one request shape. OmniSocials checks the post against Telegram’s limits and counts characters the way Telegram does before anything is sent. - **Text, photos and video.** Text up to 4,096 characters, with a link preview. One photo, one MP4 or MOV video up to 50 MB, or one GIF, with a caption. (`content`, `media_urls`) - **Albums.** 2 to 10 photos and videos in one message, mixed as you like. A GIF goes on its own. (`media_urls`) - **Native polls.** The post text is the question. 2 to 12 answers, one or several per person, open until you close it or up to 30 days. Always anonymous. (`telegram.poll`) ### Text ```json { "content": "What's new: https://omnisocials.com/changelog", "accounts": ["telegram"], "telegram": { "link_preview": true }, "schedule_at": "2026-10-23T12:00:00Z" } ``` ### Photo ```json { "content": "New: Best times to post", "accounts": ["telegram"], "media_urls": ["https://cdn.example.com/best-times.png"], "telegram": { "buttons": [ { "text": "Read the docs", "url": "https://docs.omnisocials.com/api/analytics" } ] }, "schedule_at": "2026-10-22T18:00:00Z" } ``` ### Album ```json { "content": "Sidebar update:\n\n1. New Home tab\n2. New Drafts tab\n\nSave a post as a draft, find it waiting for you under Drafts. Simple.", "accounts": ["telegram"], "media_urls": [ "https://cdn.example.com/sidebar-1.png", "https://cdn.example.com/sidebar-2.png" ], "telegram": { "silent": true }, "schedule_at": "2026-10-25T10:00:00Z" } ``` ### Poll ```json { "content": "Which channel should we add next?", "accounts": ["telegram"], "telegram": { "poll": { "options": ["Discord", "Tumblr", "WordPress"], "open_period": 86400 } }, "schedule_at": "2026-10-24T11:00:00Z" } ``` ## Every Telegram option in one object Send it silently, pin it, protect it from forwarding, blur the media, put the text above it, turn off the link preview or add a first comment. The telegram object holds them all, and the app shows the same switches. `POST /v1/posts/create`: ```json { "content": "New in OmniSocials: Notable Days", "accounts": ["telegram"], "media_urls": ["https://cdn.example.com/notable-days.png"], "telegram": { "silent": true, "protect_content": true, "pin": true, "first_comment": "Release notes: https://omnisocials.com/changelog" }, "schedule_at": "2026-10-23T16:00:00Z" } ``` - **Message options.** silent, protect_content, spoiler, caption_above_media and link_preview, the switches Telegram itself has. Each takes true, false or null, and the link preview stays on unless you send false. (`telegram.silent`, `telegram.protect_content`) - **Pin and first comment.** pin pins the post once it is out. In a group, make the bot an admin with Pin messages first; without the right the post still goes out and result.pin_error reads “no_right”. first_comment is a silent reply under the post. (`telegram.pin`, `telegram.first_comment`) - **Link buttons.** Up to 3 buttons, one per row, each a label of 1 to 64 characters and a link that starts with https://, http:// or tg://. Telegram shows none under an album or a poll. (`telegram.buttons`) ## Long text under media, handled Telegram allows 1,024 characters under a photo or video. Send up to 4,096 and OmniSocials sends the media first and the full text as a reply under it, buttons included. The post then says where every message landed. `POST /v1/posts/create-and-publish`: ```json { "content": "New: Review posts in a feed and comment on any word\n\nApprovals is now a feed. Every post that waits for you is a card with its real preview per channel. Approve it, or choose Request changes and write what to change. The tabs are For you, Sent by you, In review, Approved and Sent back, and the list view is one click away.\n\nSelect words in a caption to comment on them, or suggest new words that the author applies with one click. On a Reel you comment on a moment in the video, on a Story on a point of a slide. You can also edit a caption in the card itself and choose Save and approve. A post you have decided folds into one line, and the message tells you who reviews next.\n\nEdits during a review keep the approvals: a change to the caption, the first comment or the time keeps every approval given, and the people who approved get a notice. A change to the media or the channels starts the review again from step 1, and the editor asks you first.\n\nAlso new: a Library with folders, a Reports page and one bell for every workspace. https://omnisocials.com/changelog", "accounts": ["telegram"], "media_urls": ["https://cdn.example.com/approvals.jpg"], "telegram": { "buttons": [ { "text": "Read the changelog", "url": "https://omnisocials.com/changelog" } ] } } ``` - **Media first, then the text.** Over the 1,024 characters a caption allows, the picture or album goes first and the full text follows as a silent reply under it. Your link buttons move to that reply. (`content`, `result.text_message_id`) - **Counted like Telegram.** Up to 4,096 characters, counted in UTF-16 the way Telegram counts, so most emoji count as 2. A longer text fails in your request, with the count, before anything is sent. - **Where it landed.** telegram.result lists the message ids, the reply, the pin and both links. published_urls.telegram is the t.me link of a public chat, else the t.me/c link members can open. (`telegram.result`, `published_urls.telegram`) ## Connect in Telegram, post from code Open the OmniSocials bot from Channels, press Start and pick your channel or group in Telegram’s own chat picker. OmniSocials checks that you are an admin of that chat. Then create an API key, and your code posts there. - **Our bot, your chat.** No bot token and no BotFather. In a channel Telegram adds the bot as an admin that can post; in a group it joins as a member. - **Knows when the bot is gone.** When someone removes the bot or takes away its right to post, the account reads needs_reconnect with the reason, and you get one email. (`needs_reconnect`, `reauth_reason`) - **What the chat is.** The accounts call returns the chat type, its id, the subscribers or members and its t.me link. Each workspace connects one chat. (`GET /v1/accounts`, `platform_details`) `GET /v1/accounts?platform=telegram` answers: ```json { "data": [ { "id": "4127_telegram", "platform": "telegram", "display_name": "OmniSocials", "needs_reconnect": false, "platform_details": { "chat_type": "channel", "chat_id": "-1002049318842", "subscribers": 2418, "url": "https://t.me/omnisocials" } } ] } ``` ## Read what Telegram gives bots Reactions per emoji, poll votes and your subscribers. Telegram gives bots no view counts, so views read N/A in the app and the API leaves them out. - **Reactions per emoji.** likes is the total of every reaction, reactions the count per emoji. Telegram pushes them as they come in. In a group, the bot must be an admin to get them. (`/analytics/posts/:id`, `reactions`) - **Poll votes.** The votes per answer and the total, kept up to date as people vote. (`metrics.poll`) - **Subscribers.** The subscribers of a channel or the members of a group, checked once a day, as the account’s followers. (`/analytics/accounts`, `followers`) `GET /v1/analytics/posts/1016` answers: ```json { "data": { "post_id": "1016", "platforms": { "telegram": { "metrics": { "likes": 35, "reactions": { "👍": 24, "🔥": 11 }, "poll": { "votes_count": 286, "options": [ { "title": "Dark", "votes_count": 148 }, { "title": "System", "votes_count": 97 }, { "title": "Light", "votes_count": 41 } ] } } } } } } ``` ## Telegram’s rules, in one place OmniSocials checks every post against them before it reaches Telegram, so a post that breaks one fails in your request with the reason, not at publish time. | Limit | Value | | --- | --- | | Text | 4,096 characters, an emoji counts 2 | | Caption | 1,024 under media, the rest as a reply | | Album | 2 to 10 photos and videos, no GIFs | | Photos | Up to 40 MB, re-encoded above 10 MB | | Video and GIF | MP4 or MOV up to 50 MB, one GIF | | Poll | 2 to 12 answers of up to 100 characters | | Poll question | 300 characters, open up to 30 days | | Buttons | Up to 3, labels of 1 to 64 characters | | First comment | 4,096 characters, sent silently | | Chats | One channel or group per workspace | | Removal | From Telegram within 48 hours | | Rate limit | 100 requests a minute per API key | ## Your first Telegram post in three steps About five minutes from sign-up to a scheduled post in your channel. Then hand the key to your coding agent. 1. **Create an API key** (`Settings › API`). Start your trial, open Settings, API and create a key. It is shown once. 2. **Connect your chat** (`GET /v1/accounts`). Open Channels, pick Telegram and press Start in the OmniSocials bot. Choose your channel or group, then list it from your code. 3. **Send your first post** (`POST /v1/posts/create`). Post now with create-and-publish, or add schedule_at to plan it. Add the telegram object for buttons, a poll or a pin. ## FAQ ### Do I need my own Telegram bot? No. OmniSocials runs the bot. In OmniSocials you open Channels, pick Telegram and press Start in the OmniSocials bot, then choose your channel or group in Telegram’s own chat picker. No bot token, no BotFather and no webhook server. Your code calls the OmniSocials API with an API key. ### Can I post to a Telegram group? Yes. Channels, groups and supergroups all work. In a channel Telegram adds the bot as an admin that can post, and posts appear as your channel. In a group the bot joins as a member, and posts appear as the OmniSocials bot. Either way OmniSocials checks that you are an admin of that chat. Each workspace connects one channel or group. ### How do I post an album or a poll? For an album, send 2 to 10 photo and video URLs in media_urls, mixed as you like; a GIF goes on its own. For a poll, put the answers in telegram.poll: 2 to 12 options of up to 100 characters, multiple for several answers per person, and open_period in seconds (5 to 2,628,000, about 30 days) or nothing to keep it open until you close it. The post text is the question, up to 300 characters. A poll carries no media, and polls from OmniSocials are always anonymous. ### What happens to a caption over 1,024 characters? Telegram allows 1,024 characters under a photo or video. When your text is longer, up to 4,096, OmniSocials sends the media first and the full text as a silent reply under it. Link buttons move to that reply, and GET /posts/{id} returns its id in telegram.result.text_message_id. ### Can I add buttons to a Telegram post? Yes, up to 3 link buttons in telegram.buttons, one per row, each with a label of 1 to 64 characters and a link that starts with https://, http:// or tg://. Telegram shows no buttons under an album or a poll, so the API refuses those with a 400 validation_error, for example: “Telegram shows no buttons under an album. Use one photo or video, or remove the buttons.” ### Can I read views? No. Telegram gives bots no view counts, so views read N/A in OmniSocials and the API leaves them out. You get the reactions per emoji (likes is their total), the votes of a poll and the subscribers of a channel or the members of a group. In a group, reactions need the bot to be an admin. ### Can I edit or delete a sent message? A sent post can’t be edited through OmniSocials; the API and MCP change draft and scheduled posts only. To take a post down, Delete from Telegram on the post in OmniSocials removes all its messages within 48 hours of sending. After that, delete it in Telegram itself. DELETE /posts/{id} removes the post from OmniSocials only. ### What happens when someone removes the bot? Telegram tells OmniSocials right away. GET /v1/accounts then shows needs_reconnect: true with a reauth_reason such as “OmniSocials was removed from this Telegram chat”, you get one email, and a post to that chat fails with a message that says what to fix. Adding the bot back clears it. ### Can my AI agent post to Telegram? Yes, through the hosted MCP server. create_post and update_post take the same telegram options, get_post shows them with the result, get_post_analytics returns the reactions and list_accounts shows the chat type and subscribers. They are 5 of its 56 tools. ### Is the Telegram API free? Telegram’s Bot API is free, but you build, host and run the bot yourself. With OmniSocials there is no bot to run: Telegram is part of the plan, $10 per seat per month billed annually, and posting to it uses no credits. ### How much does OmniSocials cost? One plan with every feature included: $10 per seat per month billed annually, or $12 billed monthly. Team members and client seats cost the same. Every account starts with a 14-day free trial. The REST API, the SDKs, the CLI, webhooks and the MCP server are part of that one plan. ## Pricing From $10 per seat a month, API included. 14-day free trial. ## Related - [Telegram scheduler](https://omnisocials.com/telegram.md) - [Telegram MCP server](https://omnisocials.com/telegram-mcp.md) - [All channels](https://omnisocials.com/channels.md) ## Links - Page: https://omnisocials.com/telegram-api - Telegram platform docs: https://docs.omnisocials.com/platforms/telegram - API reference: https://docs.omnisocials.com/api - REST API overview: https://omnisocials.com/api.md - MCP server: https://omnisocials.com/mcp.md - Sign up: https://app.omnisocials.com/signup