Telegram

A Telegram bot answered by a text agent takes three things: a bot, a telegram integration holding its token, and a telegram.message.inbound trigger pointing at a published text agent. Telegram is a channel integration: it lends an agent no tools and cannot be attached under mcps.

Set it up

Create a bot with BotFather

Message @BotFather, send /newbot, and choose a display name and username. BotFather answers with a token shaped 123456789:AAH…; treat it like a password. Do not set a webhook in BotFather — Talqing registers it when you enable the trigger.

Create the integration

Send the bot token as credentials_ref and a webhook secret of your choosing as webhook_config.secret_token — 1–256 letters, digits, underscores and hyphens. Telegram sends the secret back in X-Telegram-Bot-Api-Secret-Token on every delivery, and a delivery without it is refused with 403. Both are stored as workspace secrets (TELEGRAM_BOT_TOKEN, TELEGRAM_WEBHOOK_SECRET); reads return the {{secrets.NAME}} reference.

curl -X POST https://api.talqing.com/v1/integrations \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Northwind support bot",
    "provider": "telegram",
    "credentials_ref": "123456789:AAHc3xR2pL9wV5nT7bY4cH6jZ1aS0dF8kQm",
    "webhook_config": { "secret_token": "nw-bot-7f3ac21e9b" }
  }'

const integration = await talqing.integrations.create({
  createIntegrationRequest: {
    display_name: "Northwind support bot",
    provider: "telegram",
    credentials_ref: "123456789:AAHc3xR2pL9wV5nT7bY4cH6jZ1aS0dF8kQm",
    webhook_config: { secret_token: "nw-bot-7f3ac21e9b" },
  },
});

integration = talqing.integrations.create(
    display_name="Northwind support bot",
    provider="telegram",
    credentials_ref="123456789:AAHc3xR2pL9wV5nT7bY4cH6jZ1aS0dF8kQm",
    webhook_config={"secret_token": "nw-bot-7f3ac21e9b"},
)

The token is checked with Telegram’s getMe before the integration is saved, so a bad token fails here. One bot is one integration; a second is refused with a Telegram integration with that bot already exists.

Create the trigger

The agent must be published, and its published version must be on the text channel.

curl -X POST "https://api.talqing.com/v1/integrations/$INTEGRATION_ID/triggers" \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger_type": "telegram.message.inbound",
    "agent_id": "9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704",
    "enabled": true
  }'

Enabling calls Telegram’s setWebhook and sets the trigger’s status to active. Messages sent to the bot while no webhook was registered are dropped, not answered late.

Message the bot

Open a private chat with the bot and send something. A typing indicator shows for the whole turn, then the reply. The thread appears under Conversations with surface telegram.

When enabling fails

Response	Why
`400` `publish the agent before enabling this trigger`	The agent has no published version
`400` `telegram.message.inbound requires a published text agent`	The published version is voice or video
`400` `activate or reconnect this integration before enabling a trigger`	The integration is not `active`
`400` `this integration already has an enabled trigger of that type`	One enabled trigger per integration and type
`400` `Telegram bot identity check failed: …`	The token stopped working. Trigger left at `error`
`502` `Telegram webhook registration failed: …`	Telegram refused `setWebhook`. Trigger left at `error`

Fix the cause and PATCH the trigger with enabled: true; registration is retried each time. Disabling or deleting the trigger or the integration calls deleteWebhook.

What Telegram delivers

Private chats only. Messages from groups, supergroups and channels are discarded.
Text only. Photos, stickers, voice notes, documents and locations are ignored; the agent is not told they arrived.
Replies longer than 4,096 characters are split at the last line or word break. The conversation keeps one item; if a later part fails after earlier parts were sent, the item is marked failed and not retried.

How a person becomes a chat

The first message from a person creates a contact and starts a chat with the trigger’s agent.

Field	Value
`contact_key`	`telegram:<bot_id>:<chat_id>` (`telegram:` is reserved for your own keys)
`surface`	`telegram`
`userdata.telegram`	`chat_id`, `user_id`, `display_name`, and `username` when set — e.g. `{{userdata.telegram.display_name}}`

Every message joins the same chat until it ends. It ends when the agent runs end_call, you call POST /v1/chats/{id}/end, or 24 hours pass without a message from the person (inactivity_timeout); the next message starts a new chat, in a new conversation unless the agent’s conversation.context is transcript. Analysis and session.completed happen only when a chat ends, so give the agent an end_call tool and say in the prompt when the conversation is over.

Pointing the trigger at another agent ends the chats it opened (close_reason: "replaced") at once; turning it off ends every open chat (messages_off). A chat whose agent a post chose keeps running.
Republishing the agent reaches open chats on the next message.
{{vars.*}} come only from a post that chooses the agent; otherwise the agent runs on its declared defaults. Put per-person data in userdata.

Read threads over the API with GET /v1/chats?contact_key=telegram:123456789:987654321 or GET /v1/conversations?contact_key=… (conversations).

`reply_mode`

Value	On Telegram
`public_reply`	The reply is sent. Default
`none`	The agent runs and its reply is recorded, but nothing is sent; the item settles `skipped`
`internal_note`	Accepted at save but never sent — Telegram has no private notes. The item settles `skipped` with `provider telegram does not support reply_mode:internal_note`

Triggers

The trigger model, statuses, and the rules enabling one checks.

Chats

How a chat starts and ends, its items, and what it costs.

Get started

Build

Guides

Set it up

When enabling fails

What Telegram delivers

How a person becomes a chat

`reply_mode`

Next

Triggers

Chats

​Set it up

​When enabling fails

​What Telegram delivers

​How a person becomes a chat

​reply_mode

​Next

Triggers

Chats

Set it up

When enabling fails

What Telegram delivers

How a person becomes a chat

`reply_mode`

Next