Telegram - Kavenio

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:

{
  "profileId": "customer_user_123",
  "chatId": "-1001234567890"
}

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:

{
  "profileId": "customer_user_123"
}

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:

{
  "profileId": "customer_user_123",
  "botToken": "123456:telegram_bot_token",
  "chatId": "-1001234567890",
  "displayName": "Announcements"
}

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:

POST /v1/connect/telegram/business/session

{
  "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:

GET /v1/connect/telegram/business/session/{sessionId}

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:

POST /v1/connect/telegram/business/claim

{
  "profileId": "customer_user_123",
  "code": "ABCD2345"
}

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:

{
  "profileId": "customer_user_123",
  "content": "Shipping a product update today.",
  "platforms": [
    {
      "platform": "telegram",
      "accountId": "acc_123"
    }
  ],
  "publishNow": true
}

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:

{
  "content": "<b>Launch notes</b>",
  "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.

{
  "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.

{
  "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:

GET /v1/accounts/{accountId}/telegram-commands
PUT /v1/accounts/{accountId}/telegram-commands
DELETE /v1/accounts/{accountId}/telegram-commands

{
  "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:

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:

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:

{
  "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:

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:

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.

​Quick Reference

​Connect

​Connect A Telegram Business Profile

​Fallback claim code

​Create A Post

​Platform Options

​Profile Stories

​Media

​Edit And Delete

​Command Menus

​Direct Messages

​Operational Notes

​Unsupported