Skip to main content
Go to the Studio
Integrations

Telegram

Connect the agent to Telegram through a bot registered with @BotFather.

Telegram

The Telegram integration lets the agent talk to users directly in Telegram, through a bot registered with @BotFather.

Reach it through the Settings icon → Integrations tab → the Telegram card.

Turning the integration on​

Turn on the toggle in the Telegram card. The configuration fields appear once it is on.

How it works​

  1. The user sends a message to the bot in Telegram.
  2. Telegram forwards the update to Roberty's webhook.
  3. Roberty validates the X-Telegram-Bot-Api-Secret-Token header (where one is configured).
  4. The agent runs and the answer goes out through sendMessage.

The webhook's endpoint:

https://agent-backend.roberty.app/integrations/telegram/<AGENT_ID>

Use Copy ID at the top of the Integrations tab to get the AGENT_ID.

The configuration fields​

FieldRequiredWhat it is
Bot TokenYesThe token @BotFather gives you when the bot is created
Secret TokenNoA security string — it must match the secret_token parameter of the setWebhook call
Allowed Chat IDsNoChat IDs separated by commas (123456789,-100987654321). With this filled in, the bot only answers in those chats

Creating the bot in Telegram​

1. Create the bot​

  1. In Telegram, open the chat with @BotFather.
  2. Send /newbot and follow the instructions to name it.
  3. BotFather gives you the Bot Token at the end.

2. Register the webhook​

Use the setWebhook API to register Roberty's endpoint:

bash
curl -X POST "https://api.telegram.org/bot<BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://agent-backend.roberty.app/integrations/telegram/<AGENT_ID>",
    "secret_token": "YOUR_OPTIONAL_SECRET",
    "allowed_updates": ["message", "edited_message"]
  }'
  • secret_token is optional but strongly recommended in production.
  • To remove the webhook: POST /bot<TOKEN>/deleteWebhook.

3. Configure the agent in Roberty​

Fill in Bot Token and, optionally, Secret Token and Allowed Chat IDs.

4. (Optional) Restrict who can talk to it​

Use Allowed Chat IDs to restrict the bot to particular conversations.

To find a chat.id:

  1. Send /start to your bot.
  2. Call https://api.telegram.org/bot<BOT_TOKEN>/getUpdates.
  3. message.chat.id is in the JSON that comes back.
info

Chats that are not allowed get a silent 200, with no answer.

Security validation​

With a Secret Token configured on the agent, Telegram sends the X-Telegram-Bot-Api-Secret-Token: <value> header. Requests without it, or with a different value, get a 401.

With Secret Token blank, that validation is off.

The update types it handles​

UpdateWhat happens
messageRuns the agent with message.text.
edited_messageTreated as a new message (the updated text).

Other types (button callbacks, commands, photos and so on) are ignored in the current version.

References​