Copy page

Platforms

Telegram API: Posting Reference

OmniSocials posts to a Telegram channel or group through the OmniSocials bot. The workspace connects the chat once in the OmniSocials dashboard (Channels, then Add a channel, then Telegram): the person opens the bot in Telegram, picks the channel or group, and Telegram adds the bot as an admin that can post. OmniSocials checks that the person who connects is an admin of that chat. Each workspace connects one Telegram chat.

In a channel, a post shows as the channel itself. In a group, a post shows as the OmniSocials bot.

Channel ID: telegram

Supported content types

Type	Supported
Text post	✅
Photo, video, GIF or file	✅
Album (2 to 10 photos and videos)	✅
Native poll	✅
Reel	✅ (sent as a video message)
Story	-

Minimal example

Code
curl -X POST https://api.omnisocials.com/v1/posts/create \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": { "default": "The new collection is live." },
    "channels": ["telegram"],
    "media_urls": ["https://example.com/collection.jpg"],
    "telegram": { "silent": true, "pin": true }
  }'

Platform-specific options

Field	Type	Description
telegram.silent	boolean	Send without a notification sound.
telegram.link_preview	boolean	false hides the link preview of a text-only post. The preview shows by default.
telegram.pin	boolean	Pin the post in the chat after it is sent. See Pinning.
telegram.protect_content	boolean	Stop forwarding and saving of the post in Telegram apps.
telegram.spoiler	boolean	Blur the photos and videos until someone taps them.
telegram.caption_above_media	boolean	Show the text above the media instead of below.
telegram.buttons	array	Up to 3 link buttons under the post. See Buttons.
telegram.poll	object	A native Telegram poll; the post text is the question. See Polls.
telegram.first_comment	string	A reply the bot sends under the post right after it is published (max 4,096 characters).

On PATCH /posts/:id, every key merges into the stored options, and a key set to null removes it (for example "telegram": { "poll": null }).

Buttons

Code
{
  "channels": ["telegram"],
  "content": { "telegram": "Early access opens today." },
  "media_urls": ["https://example.com/launch.jpg"],
  "telegram": {
    "buttons": [
      { "text": "Get early access", "url": "https://example.com/early" },
      { "text": "Read the story", "url": "https://example.com/blog/launch" }
    ]
  }
}

Rules:

• At most 3 buttons. Each button has its own row.
• text is 1 to 64 characters. url starts with https://, http:// or tg://.
• Telegram shows no buttons under an album (2 or more media) or a poll. A request with buttons on an album or a poll is refused with 400 validation_error.

Polls

Code
{
  "channels": ["telegram"],
  "content": { "telegram": "Which day suits the live Q&A?" },
  "telegram": {
    "poll": {
      "options": ["Tuesday", "Thursday", "Saturday"],
      "open_period": 86400,
      "multiple": false
    }
  }
}

Field	Type	Description
options	array of strings	2 to 12 answers of up to 100 characters. The answers must differ from each other.
open_period	integer	Seconds the poll stays open, 5 to 2628000 (about 30 days). Leave it out and the poll stays open until someone closes it in Telegram.
multiple	boolean	Let people pick several answers (default false).

The question is the post text, max 300 characters. A poll carries no media and no buttons: a request with both is refused with 400 validation_error. The poll is anonymous, the Telegram default for channels. The votes come back in analytics under metrics.poll, updated while people vote.

Pinning

telegram.pin: true pins the post after it is sent. The bot needs the Edit messages right in a channel, or the Pin messages right in a group. OmniSocials asks for these rights when the chat is connected. When the bot cannot pin, the post is still sent: GET /posts/:id then returns telegram.result.pinned: false with pin_error: "no_right".

Long text with media

A message holds up to 4,096 characters, but Telegram limits the text under media to 1,024 characters. When a post with media has a longer text, OmniSocials sends the media first and the full text as a reply under it. Buttons then go on the text message. A text-only post can use all 4,096 characters.

Media requirements

Media	Requirement
Photo	JPEG and PNG go as they are; other formats such as WebP are sent as JPEG. Telegram allows 10 MB and a width plus height of 10,000 pixels; OmniSocials resizes a larger photo (up to 40 MB) to fit. A photo wider or taller than 20:1 is sent as a file.
Video	MP4 (H.264), max 50 MB. No duration cap.
GIF	Max 50 MB. A GIF goes on its own, never in an album.
File (PDF and similar)	Max 50 MB. Files do not share an album with photos or videos.

An album holds 2 to 10 photos and videos, which can be mixed. OmniSocials uploads every file to Telegram from its own servers, so the 5 MB and 20 MB limits of Telegram's URL upload do not apply.

Character limit

4,096 characters per message, counted in UTF-16 code units the way Telegram counts them: most emoji count as 2. With media, see Long text with media. A poll question allows 300 characters.

Published post

GET /posts/:id returns under telegram.result:

Field	Description
chat_id	The Telegram chat the post went to.
message_ids	The ids of the sent messages (one per album item).
text_message_id	The reply that holds the long text, when the text went separately.
pinned, pin_error	Whether the pin worked.
link_public, link_private	The t.me link of a public chat, or the t.me/c/... link that only members can open.
sent_at	When the post went out.

published_urls.telegram is the public link when the chat has a username, else the private link.

Analytics

Telegram gives bots no view counts. A Telegram post carries:

• likes: all reactions together
• reactions: the count per emoji
• poll: the votes per answer, for a poll

The account row carries the subscribers of a channel, or the members of a group. Views, reach, forwards and comments are not reported; open the post in Telegram to see its views.

Removing a post

Telegram lets a bot remove a message only in the first 48 hours after it was sent. In that window, "Delete from Telegram" on the post in the OmniSocials dashboard removes every message of the post. After 48 hours, remove the post in Telegram yourself. DELETE /posts/:id removes the post from OmniSocials only and never touches the live message.

Limitations

• One Telegram chat per workspace. Connect more chats through more workspaces.
• Text formatting (bold, italic, links in text) is sent as plain text for now.
• Topics in forum groups are not supported: the post goes to the General topic.
• Telegram messages are not part of the Social Inbox.
• A post that was sent cannot be edited through OmniSocials.
• Files over 50 MB need a self-hosted Telegram Bot API server and are not supported.

When the connection breaks

When someone removes the bot from the chat or takes away its right to post, the account shows needs_reconnect: true in GET /accounts and posts to it fail with a message that says what to fix. Add the bot back as an admin with the right to post, then reconnect the chat in OmniSocials.