# PostEverywhere Telegram API Guide

> PostEverywhere API reference for Telegram: bot setup, request fields and examples for channel posts with text, images, carousels and video.

**Source:** https://posteverywhere.ai/docs/platforms/telegram
**Section:** Platforms
**API reference:** https://posteverywhere.ai/docs/api/reference

---

Publish text, images, image carousels, and video to a Telegram channel through your bot. PostEverywhere uses the Telegram Bot API to deliver content; the bot you connected at setup is the credential: there is no OAuth flow. For a general overview of all supported platforms, see the [Introduction](/docs).

## Connect your Telegram account to PostEverywhere
Telegram uses a **bot token** plus a **target channel**. There is no OAuth flow.

1. Open a chat with [@BotFather](https://t.me/BotFather) on Telegram and create a bot. Copy the bot token it gives you.
2. Add the bot as an **administrator** of the channel you want to post to. Enable the **Post Messages** permission.
3. In your PostEverywhere dashboard, go to **Accounts → Connect Telegram** and paste:
   - The **bot token** from BotFather (format: `123456:ABC-DEF1234...`)
   - The **channel**: either `@channelusername`, a `t.me/channelusername` link, or a numeric chat ID.

We validate the bot token, confirm the bot can see the channel, and check it has post permission before saving the account. If any of those fail, we surface the exact error so you can fix the setup.

## What you can post to Telegram
| Content Type | Media Required | Description |
|-------------|---------------|-------------|
| **Text post** | None | Plain text message, up to 4,096 characters. |
| **Image post** | Image | Single image with optional caption (up to 1,024 chars). |
| **Image carousel** | Images (2-10) | Media group with up to 10 images. |
| **Video post** | Video (MP4) | Single video with optional caption. |
| **Document post** | PDF | Not currently accepted: `POST /v1/posts` rejects PDF for Telegram destinations, although the publisher itself supports documents. |

When the post text exceeds Telegram's 1,024-character caption limit but media is attached, we send the long text as a separate message first, then send the media without a caption, so nothing gets truncated.

## Telegram-specific options in the API
`platform_content.telegram.content` overrides the caption or text per platform, and `platform_content.telegram.settings` accepts optional delivery options: `silent` (no notification sound), `protectContent` (block forwarding and saving), `captionAboveMedia`, `mediaSpoiler`, `linkPreview` (`off`, `large` or `small`) and `linkPreviewAboveText`. The link preview options only change messages sent as text: a text-only post, long text sent before the media, and `thread_posts` follow-ups. A post whose text fits as the media caption has no text message for them to change. There are no privacy, comment-control, or reply-restriction fields.

```json
{
  "platform_content": {
    "telegram": {
      "content": "Telegram-specific caption (up to 4,096 chars text, 1,024 chars caption)"
    }
  }
}
```

## Publish to Telegram: a working request
### Schedule a Telegram Text Post

```bash
curl -X POST https://app.posteverywhere.ai/api/v1/posts \
  -H "Authorization: Bearer $POSTEVERYWHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "New blog post is live. Read it here: https://example.com/blog/foo",
    "account_ids": [3100],
    "scheduled_for": "2026-06-15T12:00:00Z",
    "timezone": "UTC"
  }'
```

### Schedule a Telegram Image Carousel

```bash
curl -X POST https://app.posteverywhere.ai/api/v1/posts \
  -H "Authorization: Bearer $POSTEVERYWHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Launch day photos",
    "account_ids": [3100],
    "media_ids": [
      "11111111-1111-1111-1111-111111111111",
      "22222222-2222-2222-2222-222222222222",
      "33333333-3333-3333-3333-333333333333"
    ]
  }'
```

### Send Follow-up Messages

`thread_posts` works on Telegram too. `content` (with any media) goes out first, then each string in `thread_posts` is sent as its own text message, in order. You can add up to 25 parts, each up to 4,096 characters; a part that is too long is rejected with `400 invalid_thread_posts` before anything is sent. Media goes on the first message only.

```bash
curl -X POST https://app.posteverywhere.ai/api/v1/posts \
  -H "Authorization: Bearer $POSTEVERYWHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Release notes for v2.4, in three parts.",
    "account_ids": [3100],
    "thread_posts": [
      "1/ New: dark mode across the whole app.",
      "2/ Fixed: exports now keep your time zone.",
      "3/ Full changelog: https://example.com/changelog"
    ]
  }'
```

## Telegram limits: characters, media and video
| Requirement | Limit |
|-------------|-------|
| Text-only message length | 4,096 characters |
| Caption length (with media) | 1,024 characters |
| Images per carousel | 2 - 10 (media group) |
| Image formats | JPEG, PNG, WebP |
| Image max file size | 10 MB (Telegram limit) |
| Video format | MP4 (H.264) |
| Video max file size | 50 MB (Telegram limit); up to 20 MB is sent by URL, larger files are uploaded as bytes |
| Document formats | PDF |
| Document max file size | 20 MB (PostEverywhere upload limit; see the note above on `POST /v1/posts`) |
| Follow-up messages | Up to 25 in `thread_posts`, text only |
| Bot must be channel admin | Yes, with "Post Messages" permission |

> **Bot must have "Post Messages" enabled**
>
> If you remove the bot from your channel or revoke its post permission, every subsequent publish will fail with "bot can't post to chat". Reconnect via **Accounts → Connect Telegram** after fixing the permission on Telegram.

## Getting better results on Telegram
- **Small files go by URL, large ones by upload.** Media up to 20 MB is passed to Telegram as a URL to our storage; larger videos (up to Telegram's 50 MB ceiling) are uploaded as bytes. Files over 50 MB cannot be sent via the Bot API.
- **Long text + media gets split automatically.** If your post text is longer than 1,024 characters but you've attached media, we send the text as a separate message before the media (with no caption on the media). This avoids silent truncation.
- **The bot's display name is the post author.** Posts appear authored by the channel, but Telegram shows that the message was sent via a bot. Pick a bot name that makes sense for your channel.

## Common questions about posting to Telegram
### How do I connect a Telegram channel?

Create a bot via [@BotFather](https://t.me/BotFather), copy the token, add the bot to your channel as an administrator with "Post Messages" enabled, then go to **Accounts → Connect Telegram** in your PostEverywhere dashboard. Enter the bot token and the channel (`@channelname` or a numeric chat ID).

### Why did my Telegram post fail with "bot is not an admin"?

The bot was removed from the channel, demoted, or had its "Post Messages" permission revoked. Re-add the bot as an administrator with post permissions, then re-validate the connection by clicking **Reconnect** on the account in your dashboard.

### Can I post to a private Telegram group via the API?

Yes, the bot must be an administrator of the group. We support channels, supergroups, and private groups. Direct messages to users are not supported (Telegram's Bot API restricts that to opted-in users only).

### Can I edit a Telegram post after it's published?

No. Telegram's Bot API supports `editMessageText` and `editMessageCaption`, but `PATCH /v1/posts/:id` only accepts `scheduled` or `draft` posts. Edits via our API on published posts return `400 invalid_post_status`. Edit directly in Telegram if needed.

## Other platforms you can publish to
- **[Discord](/docs/platforms/discord)**: webhook-based posting to a server channel
- **[Bluesky](/docs/platforms/bluesky)**: app-password connection model, similar low-friction setup
- **[X (Twitter)](/docs/platforms/x-twitter)**: short-form text with thread support

## Related Telegram and API reference pages
- [API Reference -- Create Post](/docs/api/create-post)
- [Upload Media](/docs/api/init-media-upload)
- [Quick Start Guide](/docs/quick-start)

**Related:** [Telegram media requirements](/docs/media-requirements) · [connecting a Telegram bot](/docs/connecting-accounts) · [testing posts safely](/docs/testing) · [posting to Telegram with an API](/blog/post-to-telegram-api) · [one API for every network](/social-media-api)
