> ## Documentation Index > Fetch the complete documentation index at: https://kavenio.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Telegram Kavenio publishes to Telegram through connected bots. Use `telegram` as the platform value in post payloads. Telegram supports two connection modes: * managed bot connections, where Kavenio owns the bot credential and the customer connects a channel or group by chat ID or access code * bring-your-own bot-token connections, where the customer supplies a Telegram bot token and optional chat ID * managed Business connections, where a Telegram user grants the Kavenio bot permission to publish Stories on their profile ## Quick Reference | Capability | Support | | ---------------------- | ----------------------------------------------- | | Platform key | `telegram` | | Managed connect | Direct chat ID or access code | | BYO bot-token connect | Supported | | Text post | Supported | | Image post | Supported | | Video post | Supported | | Document post | Supported | | Media group | Images, videos, or documents | | Forum topic | `messageThreadId` | | Parse mode | `HTML`, `Markdown`, or `MarkdownV2` | | Command menu | Supported | | Text DMs | Managed Telegram accounts only | | DM attachments | Managed Telegram accounts only | | Native edit/delete | Supported for Kavenio-published message targets | | Profile Stories | Managed Telegram Business accounts | | Polls/quizzes | Not supported | | Analytics | Not supported | | Admin/pin/invite tools | Not supported | ## Connect Use managed connect when customers should not handle bot credentials. The direct form connects an already-known Telegram chat ID: ```json theme={null} { "profileId": "customer_user_123", "chatId": "-1001234567890" } ``` ```http theme={null} POST /v1/connect/telegram ``` Managed direct connect verifies the Kavenio bot credential, looks up the target chat, checks that the bot is an administrator, and stores the connected account with the chat metadata returned by Telegram. For self-serve setup, create an access code: ```json theme={null} { "profileId": "customer_user_123" } ``` ```http theme={null} POST /v1/connect/telegram/access-code GET /v1/connect/telegram/access-code/{code} ``` Kavenio returns a short-lived code, expiration, bot username when configured, and instructions. The customer adds the Kavenio bot as an administrator in the target channel or group, then sends the code to the bot with the channel username or posts the code in the target chat. Poll the code endpoint until the status is `connected`, `pending`, or `expired`. Use BYO bot-token connect when the customer owns the Telegram bot credential: ```json theme={null} { "profileId": "customer_user_123", "botToken": "123456:telegram_bot_token", "chatId": "-1001234567890", "displayName": "Announcements" } ``` ```http theme={null} POST /v1/connect/telegram/credentials ``` The bot token is accepted only when connecting the account, stored encrypted, and never returned by the API. ### Connect A Telegram Business Profile Start an automatic pairing session: ```http theme={null} POST /v1/connect/telegram/business/session ``` ```json theme={null} { "profileId": "customer_user_123" } ``` The response includes an expiring `botUrl`. Open it and press **Start**. The bot then asks the Telegram user to open **Settings > Chat Automation**, add `@kavenio_bot`, and enable **Manage Stories**. Kavenio matches the Telegram user from the private Start message to the later Business connection and completes the account automatically. Poll the organization-scoped session until it reaches `connected`: ```http theme={null} GET /v1/connect/telegram/business/session/{sessionId} ``` ```bash theme={null} kavenio connect telegram-business --profile-id customer_user_123 kavenio connect telegram-business-status --session-id SESSION_ID ``` Telegram requires the user-controlled Chat Automation permission screen. The pairing link expires after 24 hours, is single-use, and is stored by Kavenio only as a SHA-256 digest. #### Fallback claim code If a user connects the bot without starting a pairing link, Kavenio sends an eight-character recovery code. Claim it with: ```http theme={null} POST /v1/connect/telegram/business/claim ``` ```json theme={null} { "profileId": "customer_user_123", "code": "ABCD2345" } ``` ```bash theme={null} kavenio connect telegram-business \ --profile-id customer_user_123 \ --code ABCD2345 ``` The fallback code also expires after 24 hours. The API never returns the Telegram Business connection ID or bot token. ## Create A Post Create a Telegram post through the shared posts API: ```json theme={null} { "profileId": "customer_user_123", "content": "Shipping a product update today.", "platforms": [ { "platform": "telegram", "accountId": "acc_123" } ], "publishNow": true } ``` ```bash theme={null} kavenio posts create \ --profile-id customer_user_123 \ --content "Shipping a product update today." \ --publish-now \ --platform telegram:acc_123 ``` By default, Kavenio sends the post to the connected account's stored chat ID. Set `platformSpecificData.chatId` only when the connected bot is allowed to post to another Telegram chat. ## Platform Options Telegram-specific options live under `platformSpecificData`: ```json theme={null} { "content": "Launch notes", "platforms": [ { "platform": "telegram", "accountId": "acc_123", "platformSpecificData": { "parseMode": "HTML", "disableWebPagePreview": true, "disableNotification": true, "protectContent": true, "messageThreadId": 42 } } ], "publishNow": true } ``` Supported options: | Option | Meaning | | ----------------------- | ------------------------------------------------- | | `chatId` | Override the destination chat for this target | | `parseMode` | `HTML`, `Markdown`, or `MarkdownV2` | | `disableWebPagePreview` | Hide Telegram URL previews for text messages | | `disableNotification` | Send without notification | | `protectContent` | Ask Telegram to prevent forwarding/saving content | | `messageThreadId` | Post into a forum topic | | `sendAsDocument` | Send media as Telegram documents | ## Profile Stories Use the same Posts API with `contentType: "story"` on a claimed Telegram Business account. The agent supplies the public image or video URL; Kavenio downloads it with outbound-URL and size checks, then uploads a fresh file to Telegram as required by the Bot API. ```json theme={null} { "profileId": "customer_user_123", "content": "Today in Milan.", "mediaItems": [ { "type": "image", "url": "https://cdn.example.com/story.jpg", "mimeType": "image/jpeg", "width": 1080, "height": 1920 } ], "platforms": [ { "platform": "telegram", "accountId": "acc_123", "platformSpecificData": { "contentType": "story", "activePeriodSeconds": 86400, "postToChatPage": true, "protectContent": false } } ], "publishNow": true } ``` Story-specific options: | Option | Meaning | | --------------------- | --------------------------------------------------------- | | `contentType` | Set to `story`; omitted values remain normal messages | | `activePeriodSeconds` | `21600`, `43200`, `86400`, or `172800` | | `postToChatPage` | Keep the Story accessible after its active period expires | | `protectContent` | Request forwarding and screenshot protection | | `parseMode` | Parse formatting in the Story caption | Stories require exactly one image or video. Captions are limited to 2,048 characters. Photos must be 1080x1920 and no larger than 10 MB. Videos must be 720x1280, no longer than 60 seconds, and no larger than 30 MB. The managed Bot API publishes Business profile Stories with Everyone visibility; contacts and other Telegram users can see them subject to Telegram's normal Story surfaces. Telegram account eligibility and Story quotas remain provider-enforced. ## Media Add `mediaItems` for images, videos, documents, or media groups. Kavenio validates the public media URL and either passes it to Telegram by URL or uploads it as multipart form data when the item requires upload. ```json theme={null} { "content": "New dashboard preview.", "mediaItems": [ { "type": "image", "url": "https://cdn.example.com/dashboard.png", "mimeType": "image/png", "altText": "Dashboard preview" } ], "platforms": [ { "platform": "telegram", "accountId": "acc_123" } ], "publishNow": true } ``` Telegram captions use the post `content`. For multi-item media groups, the caption is attached to the first media item. ## Edit And Delete Kavenio can edit text and captions for Kavenio-published Telegram message targets, edit Kavenio-published Business Stories, and delete both through the shared post target APIs. Telegram requires Story media on edit, so Kavenio reuploads the source media recorded when the Story was published. Telegram edit behavior depends on the message type and Telegram provider rules. If Telegram reports that the message is already unchanged or already deleted, Kavenio treats the operation as idempotent. ## Command Menus Telegram command menus are account scoped: ```http theme={null} GET /v1/accounts/{accountId}/telegram-commands PUT /v1/accounts/{accountId}/telegram-commands DELETE /v1/accounts/{accountId}/telegram-commands ``` ```json theme={null} { "commands": [ { "command": "help", "description": "Show support options" }, { "command": "status", "description": "Check account status" } ] } ``` Command names must be unique and can contain lowercase letters, numbers, and underscores. Telegram allows up to 100 commands and command descriptions up to 256 characters. Managed accounts use a chat-scoped command menu for the connected chat. BYO bot-token accounts use the bot's default command menu. The CLI exposes the same surface: ```bash theme={null} kavenio accounts telegram-commands --account-id acc_123 kavenio accounts telegram-commands-set \ --account-id acc_123 \ --command help:"Show support options" kavenio accounts telegram-commands-delete --account-id acc_123 ``` ## Direct Messages Kavenio exposes account-scoped Telegram inbox APIs for managed Telegram accounts: ```http theme={null} GET /v1/accounts/{accountId}/telegram-conversations GET /v1/accounts/{accountId}/telegram-conversations/{conversationId}/messages POST /v1/accounts/{accountId}/telegram-conversations/{conversationId}/messages POST /v1/accounts/{accountId}/telegram-conversations/{conversationId}/archive ``` Conversation listing accepts `limit` and `includeArchived`. Message listing accepts `limit`. Sending a message accepts text, media, or both: ```json theme={null} { "text": "Thanks for reaching out. We will take a look.", "mediaItems": [ { "type": "image", "url": "https://cdn.example.com/screenshot.png", "mimeType": "image/png" } ] } ``` Telegram conversations also appear in the shared engagement inbox: ```http theme={null} GET /v1/inbox/engagement?platform=telegram&itemType=telegram_conversation&includeDirect=true ``` Shared inbox rows use `itemType: "telegram_conversation"`. Kavenio does not invent Telegram read state, so Telegram conversation rows are not returned by `unreadOnly=true`. Kavenio creates the first persisted conversation when a private Telegram user redeems a managed access code. Later inbound private messages are stored only when the provider chat maps to exactly one existing conversation; ambiguous private chats are ignored instead of guessed. BYO bot-token accounts return an unsupported-provider error for Telegram DM APIs. Read receipts, typing indicators, and arbitrary Telegram Bot API proxying are not supported. The CLI exposes the same managed-inbox surface: ```bash theme={null} kavenio accounts telegram-conversations --account-id acc_123 kavenio accounts telegram-messages \ --account-id acc_123 \ --conversation-id conv_123 kavenio accounts telegram-message-send \ --account-id acc_123 \ --conversation-id conv_123 \ --text "Thanks for reaching out." \ --media-file ./telegram-media.json kavenio accounts telegram-conversation-archive \ --account-id acc_123 \ --conversation-id conv_123 ``` Pass `--include-archived` to include archived conversations. Pass `--archived false` to unarchive a conversation. ## Operational Notes Telegram managed connect and managed inbox depend on Kavenio's configured Telegram bot and inbound-update worker. The bot must remain an administrator in each connected channel or group. If a channel migrates to a supergroup, Kavenio records Telegram's migrated chat ID when Telegram returns it during publishing. For production operations, monitor polling and update-ingestion health, account health, command-menu errors, access-code rate limits, and publish failures. Managed bot tokens are stored in server-side platform credentials or deployment configuration. The update-ingestion secret is deployment-level configuration; raw secrets are never exposed through public account responses. ## Unsupported Kavenio does not support Telegram polls, quizzes, analytics, message pinning, chat administration, invite link management, inline keyboard workflows, DM read receipts, typing indicators, or arbitrary Bot API proxy routes.