Connect Telegram

Connect a Telegram bot — personal or for your company — and let an agent answer incoming messages automatically, with the right Brain and persona.

Overview

Each connection is one Telegram bot linked to one agent profile. A customer or colleague messages the bot, the linked agent handles it (including Brain search and tools) and the reply lands back in the same chat. Conversation context is kept per chat.

What you need

  • A Telegram account to create your bot (see step 1 below).
  • An agent to answer the messages — ideally with a Brain and persona configured.

1. Create a bot with BotFather

  1. 1

    Open @BotFather

    Search Telegram for @BotFather and start a chat.

  2. 2

    Create a new bot

    Send /newbot and pick a name and username. For customer service: use your company name.

  3. 3

    Copy the token

    BotFather gives you a bot token (e.g. 123456:ABC...). You need it to connect — treat it like a password.

2. Connect the bot

Link the bot to an agent. The same mechanism works for personal use and for companies — the only difference is the connection_scope.

Personal

Create your own bot and connect it with scope personal to your personal agent. You then chat with your own assistant via Telegram.

Company / customer service

Connect the support bot with scope organization to your customer-service agent (with the right Brain). Customers message the bot, the agent replies.

Go to Connections, paste your bot token, pick which agent answers and click connect. We validate the token, store it encrypted and set up the rest automatically — Telegram messages then arrive on their own. Prefer the API? That works too:

POST /agent/telegram/connections
{
  "token": "123456:ABC-bot-token-van-botfather",
  "agent_profile_id": 123,
  "connection_scope": "organization"
}

3. How it works

Once the bot is connected, everything runs automatically:

  1. 1

    Message in

    Telegram posts every message to the webhook. We verify the secret token and ignore non-text messages.

  2. 2

    Agent runs

    An invocation is queued for the linked agent, with its own Brain and tools.

  3. 3

    Reply back

    The agent's reply is sent back to the same chat through a separate messaging job.

  4. 4

    Context kept

    The session is kept per chat, so follow-up questions understand the earlier context.

Reply delivery runs in a decoupled job with its own retries. If Telegram is briefly down, only the send is retried — the (expensive) agent run never runs twice.

Replies & sending messages

There are two ways messages go out to Telegram. For most customer-service cases you only need the first.

Automatic reply (default)

Every message to the bot is answered automatically by the agent in the same chat. Nothing to set up — this works as soon as the bot is connected.

Agent sends itself (optional)

Want the agent to send extra or proactive messages? Assign the "Send Telegram message" tool to your agent under Tools. In a Telegram chat the agent knows the chat automatically; from the web chat you pass a chat id yourself. Use this only in addition to the automatic reply.

Things to note

  • For now only text messages are handled (no photos, voice or files).
  • The bot token is stored encrypted and never shown in agent output.
  • One bot maps to one agent profile. Multiple departments? Create multiple bots.
  • The webhook is protected with a secret token that Telegram sends with every message.

Ready to connect your first bot?