# Telegram: coming soon

Source: https://postgale.com/docs/telegram

Publish text, photos, videos, documents and albums to Telegram channels and groups, and edit or delete them, through the Postgale API and MCP server.

> **Coming soon.** Telegram is not available yet: Telegram channels and groups cannot be connected in production, so none of the
> endpoints or tools below work against Telegram today. This page describes the planned integration and may change before launch.

Postgale publishes to Telegram channels and groups with its own bot (Telegram Bot API): text messages, one photo, video or document,
or an album of 2 to 10 items, with edits and deletes of what was published. Everything is available over the [REST API](https://postgale.com/docs/api)
(paths relative to `https://postgale.com/api/v1`) and the [MCP server](https://postgale.com/docs/mcp) (`connect_account`, `create_post`, `manage_published_post`,
`get_analytics`). Each connected channel or group is one account with platform `telegram`; its `platformAccountId` is the Telegram chat id.

## Connect a channel or group

Telegram has no sign-in for bots, so connecting works with a one-time code instead of a link:

1. In Postgale open **Dashboard → Accounts → Telegram** (or ask for a code with the API or `connect_account`). You get a code that works once and expires after 15 minutes.
2. In Telegram, add Postgale's bot (shown with the code) to your channel or group as an **administrator** with the right to post messages. In channels the right is called *Post messages*.
3. Post `/connect <code>` in the channel or group. In groups `/connect@<bot> <code>` works too. You can also post it in the channel and forward that post to the bot in a private chat.

The chat appears as a Telegram account within seconds (the dashboard waits for it; API clients get the `account.connected` webhook or see it in `GET /accounts`).
When the bot may delete messages, it removes the `/connect` message afterwards.

POST /api/v1/connect/telegram:
```bash
curl -X POST https://postgale.com/api/v1/connect/telegram \
  -H 'Authorization: Bearer sk_…' \
  -H 'Content-Type: application/json' \
  -d '{"externalId":"cust-1"}'

# {"platform":"telegram","code":"K7PQ2MXH9D","command":"/connect K7PQ2MXH9D","botUsername":"PostgaleBot","instructions":[…],"expiresAt":"…","expiresInSeconds":900}
```

`GET /connect/telegram?externalId=…` returns the same. `externalId` (your own reference) is stored on the account that the code connects.

If the bot is removed from the chat or loses the right to post, the account becomes `needs_reconnect` and `account.disconnected` is
sent (reason `bot_removed`). Making the bot an admin with the right to post again restores it; posting `/connect` with a new code
works too.

## Publish

The post content is the message, up to 4096 characters. With media it is the caption of the photo, video, document or of the first
album item, up to 1024 characters. Both limits count the visible text (after `parseMode` markup) and are checked when the post is
created. Postgale uploads the files to Telegram itself: photos up to 10 MB, videos and documents up to 50 MB. Use the `publicUrl` of
[uploaded media](https://postgale.com/docs/api) or any public https URL.

POST /api/v1/posts:
```bash
curl -X POST https://postgale.com/api/v1/posts \
  -H 'Authorization: Bearer sk_…' \
  -H 'Content-Type: application/json' \
  -d '{"content":"<b>Release 2.4</b> is out: faster sync and dark mode.","platforms":[{"accountId":"acc_tg","platformSpecificData":{"parseMode":"HTML","disableLinkPreview":true}}],"publishNow":true}'
```

POST /api/v1/posts:
```bash
curl -X POST https://postgale.com/api/v1/posts \
  -H 'Authorization: Bearer sk_…' \
  -H 'Content-Type: application/json' \
  -d '{"content":"Photos from the meetup 📸","platforms":[{"accountId":"acc_tg","platformSpecificData":{"mediaUrls":["https://media.postgale.com/…/1.jpg","https://media.postgale.com/…/2.jpg","https://media.postgale.com/…/clip.mp4"],"disableNotification":true}}],"publishNow":true}'
```

| platformSpecificData | What it does |
| --- | --- |
| `mediaUrl` | One photo, video or document (public https URL) |
| `mediaUrls` | An album of 2-10 items (one URL is a single media post). Photos and videos can be mixed; documents only with documents |
| `mediaType` | text \| photo \| video \| document (default: from the URL extension: jpg/png/webp photo, mp4/mov video, anything else document) |
| `parseMode` | `MarkdownV2` or `HTML` (default: plain text). Edits keep it |
| `disableNotification` | Deliver silently |
| `disableLinkPreview` | Text posts: no link preview |

The target's `platformPostId` is `text:<message_id>`, `media:<message_id>` or `group:<id>.<id>…` (every message of an album), and
`url` is the message's t.me link (public chats, or `t.me/c/…` for members of private supergroups and channels).

## Edit and delete

| Method | Path | What it does |
| --- | --- | --- |
| POST | `/posts/{id}/edit` | `{content}`: new text of a text post, or new caption of a media post or album (same limits, same `parseMode`) |
| POST | `/posts/{id}/unpublish` | Delete the message, or every message of an album |
| GET | `/analytics/accounts/{id}` | `followers`: the chat's member count |
| GET | `/accounts/{id}/health` | Whether the bot is still an admin that may post, the chat title and member count |

Both are queued for a person while approval applies to the API key, the organization or the account (202 `pending_approval`; MCP
`manage_published_post` returns the queued action). Telegram only lets bots delete messages from the last 48 hours.

## Telegram's rules to know

- **Rate limits**: when Telegram answers 429, Postgale retries the post after the `retry_after` Telegram asks for. Telegram allows about 20 messages per minute per group.
- **Rights**: in channels the bot must be an admin with *Post messages* (and *Edit messages of others* / *Delete messages* is not needed for its own posts). In groups it must be an admin.
- **Errors**: "bot was kicked", "not enough rights" or "chat not found" mark the account `needs_reconnect` (`reconnect_required` on the API).
- **Analytics**: the Bot API gives bots no views or reactions per message, so post analytics answer `not_supported`; the member count is available as an account metric.
- **Groups upgraded to supergroups** get a new chat id from Telegram; Postgale follows the change automatically.