# Telegram 3 endpoints. ## The Telegram bot to add to a channel ```http GET https://orbitwrite.com/api/v1/integrations/telegram/bot ``` The bot a channel must have as an administrator (with Post Messages) before `POST /integrations/telegram/channels` can connect it, plus deep links that add it. **Authentication:** bearer token or session cookie. ### Responses #### 200 The bot - `bot` (TelegramBot, required) - `username` (string, required) — The bot's @name, without the @. - `addToChannelUrl` (string, required) — Opens Telegram's picker to add the bot to a channel as an administrator, with Post Messages pre-selected. - `addToGroupUrl` (string, required) — Opens Telegram's picker to add the bot to a group. #### 401 Not signed in - `error` (string, required) - `issues` (any[], optional) #### 429 Rate limit exceeded - `error` (string, required) - `issues` (any[], optional) #### 502 Telegram API unreachable, or no bot is configured - `error` (string, required) - `issues` (any[], optional) ## Get the code that proves you control a Telegram channel ```http POST https://orbitwrite.com/api/v1/integrations/telegram/channels/verification ``` Checks a Telegram channel is connectable — it exists, the bot is in it and can post — and returns the verification code its description must carry before `POST /integrations/telegram/channels` will connect it. Refuses exactly what the connect would, with the same messages. Requires `account:connect`. **Authentication:** bearer token or session cookie. ### Query parameters - `organizationId` (string, optional) — Session callers only — an API key already determines the workspace. ### Request body (`application/json`) - `chat` (string, required) — The channel to connect: `@username`, a `t.me/username` link, or the numeric chat id for a private channel. The bot must already be an administrator of the channel with the Post Messages right, and the channel's description must carry this workspace's verification code — the first attempt without it is refused with the code to add. ### Responses #### 200 The channel is connectable; here is its code - `verification` (TelegramChannelVerification, required) - `chat` (object, required) - `title` (string, required) - `displayHandle` (string, required) - `type` (string, required, one of `group`, `supergroup`, `channel`) - `verificationCode` (string, required) — Add this to the channel's description, then call `POST /integrations/telegram/channels`. It can be removed once the channel is connected. - `verified` (boolean, required) — Whether the description already carries the code. #### 400 Invalid request - `error` (string, required) - `issues` (any[], optional) #### 401 Not signed in - `error` (string, required) - `issues` (any[], optional) #### 403 Not a member of the organization - `error` (string, required) - `issues` (any[], optional) #### 404 The resource does not exist - `error` (string, required) - `issues` (any[], optional) #### 429 Rate limit exceeded - `error` (string, required) - `issues` (any[], optional) #### 502 Telegram API unreachable while checking the channel - `error` (string, required) - `issues` (any[], optional) ## Connect a Telegram channel as a posting channel ```http POST https://orbitwrite.com/api/v1/integrations/telegram/channels ``` Adds a Telegram channel or group to the workspace's channels, so posts can be published to it. Telegram has no OAuth flow: a person adds the bot (see `GET /integrations/telegram/bot`) to the channel as an administrator in Telegram itself, and this call names it. The bot's presence and its Post Messages right are both verified, and the channel's description must carry this workspace's verification code — the bot is shared by every workspace, so its presence proves nothing about who controls the channel. The first attempt without the code is refused with a 400 whose message carries the code to add. Requires `account:connect`. **Authentication:** bearer token or session cookie. ### Query parameters - `organizationId` (string, optional) — Session callers only — an API key already determines the workspace. ### Request body (`application/json`) - `chat` (string, required) — The channel to connect: `@username`, a `t.me/username` link, or the numeric chat id for a private channel. The bot must already be an administrator of the channel with the Post Messages right, and the channel's description must carry this workspace's verification code — the first attempt without it is refused with the code to add. ### Responses #### 200 The channel is connected - `channel` (ConnectedTelegramChannel, required) - `id` (string, required) - `displayHandle` (string, required) - `created` (boolean, required) - `restored` (boolean, required) - `becamePrimary` (boolean, required) #### 400 Invalid request - `error` (string, required) - `issues` (any[], optional) #### 401 Not signed in - `error` (string, required) - `issues` (any[], optional) #### 403 Not a member of the organization - `error` (string, required) - `issues` (any[], optional) #### 404 The resource does not exist - `error` (string, required) - `issues` (any[], optional) #### 429 Rate limit exceeded - `error` (string, required) - `issues` (any[], optional) #### 502 Telegram API unreachable while verifying the channel - `error` (string, required) - `issues` (any[], optional)