Skip to main content

Telegram

The Telegram channel connects a Flametree agent to a Telegram bot. Customers write to the bot in Telegram, the agent answers, and every conversation appears in Sessions like any other channel. The integration uses the Telegram Bot API with a token issued by Telegram's official @BotFather bot.

Use this channel to:

  • Offer support in a messenger your customers already have installed.
  • Run an inbound bot that answers questions, collects data, and hands over to a human agent when needed.
  • Give an outbound agent a channel to message customers who already talk to your bot.

Setting up Telegram has three parts: create the bot in Telegram, add the bot token as a channel connection in Settings > Channels, and attach the connection to an agent.

Before you start​

  • The Telegram app (mobile, desktop, or web) — you need it to talk to @BotFather and to test your bot.
  • You are signed in to the portal with an account that can edit settings.
  • A bot token from @BotFather. If you do not have a bot yet, create one as described below.

Create the bot and get the token​

If you do not have a bot yet, create one with @BotFather, Telegram's bot for managing bots.

  1. In Telegram, open @BotFather and send /start.
  2. Send /newbot and follow the wizard:
    • Bot name — the display name customers see in the chat (for example, "My Company Support").
    • Username — the bot's unique handle, used to find the bot in search. It must end with bot (for example, mycompany_support_bot).
  3. BotFather replies with a token in the format 123456789:AAH...XYZ. Copy it — this is the value you paste into the channel form.

If the bot already exists, find its token in @BotFather under /mybots.

Keep the token secret

Anyone who has the token controls the bot. Store it like a password. If the token leaks, revoke it in @BotFather with /mybots — and note that revoking it also disconnects the existing channel connection (see Common issues).

tip

You can customize the bot at any time with BotFather commands such as /setuserpic (avatar), /setdescription (the text shown before the first message), and /setcommands (the command menu). These changes do not affect the channel connection.

Connect Telegram​

Create the channel connection in Settings > Channels. The connection holds the bot token and runs independently of any agent.

  1. Go to Settings > Channels.

  2. Select Telegram in the channel list and click Add. The New connector form opens on the right.

  3. Fill in the form:

    FieldRequiredNotes
    NameYesAn internal name shown across the portal — pick something that identifies the bot.
    DescriptionNoInternal reference.
    Bot tokenYesThe token from @BotFather. Stored as a secret and displayed masked.
    Bot username—Read-only — displays the bot's Telegram username. You do not type it in.
    Stream responsesNoOn by default. The bot shows replies as they are generated instead of waiting for the complete message.

  4. Click Save.

  5. Click Start in the panel header.

The status dot turns purple (STARTING), then green (RUNNING). On startup the channel validates the token with Telegram — if the token is invalid, the status turns red (ERROR); hover over the dot for the message and click Logs for details.

Simple mode shortcut

In Simple mode you can also attach Telegram directly on the agent's Channels tab and enter the bot token there. The resulting connection then appears in Settings > Channels, where it is monitored and managed like any other.

Edit or delete the connection​

You can change the connection later, including the Bot token — it displays masked; paste the new token over the masked value to replace it.

  1. In Settings > Channels, select the connection in the list. The Details panel opens.
  2. Change the fields you need and click Save.
  3. Restart the channel so the changes take effect: click Stop, wait for STOPPED, then click Start.

To delete the connection, click the delete button at the bottom of the form and confirm Delete the integration?.

caution

Stopping or deleting the connection takes the bot offline: customers can no longer reach the agent through Telegram until a connection for that bot is running again.

Attach to an agent​

A running channel does nothing on its own — attach the connection to the agent that should answer the bot's messages.

  1. Open AI Agents and select the agent.
  2. Find the Communication channels card and click Add.
  3. Pick Telegram from the dropdown and tick the checkbox next to your connection.
  4. Enable the Inbound switch so the agent answers incoming messages. With Inbound off, the agent can only send outbound messages through the channel.
  5. Save the agent, then restart it (Stop agent, then Start agent).

After the restart, new messages sent to the bot open sessions for this agent.

One bot, one inbound agent

Only one agent should handle inbound traffic from a bot — otherwise several agents would answer the same customer message. To put several inbound agents on Telegram, create a separate bot and a separate connection for each.

Test the bot​

  1. In Telegram, search for your bot's username and open the chat.
  2. Send /start, then a text message, and check that the agent replies according to its instructions. With Stream responses on, the reply builds up progressively while the agent generates it.
  3. Send a voice message — if speech-to-text is configured for the agent, the agent understands it and a transcription appears in the conversation.
  4. Open Sessions in the portal and confirm the conversation appears there with the Telegram channel icon.
tip

Telegram marks bot accounts with a BOT label and shows no online status — that is normal and does not indicate a problem.

Supported content on this channel: text, voice messages with transcription, and images. Documents and calls are not supported — see Supported channels for the full capability comparison.

Common issues​

  • The channel goes to ERROR on Start. The token is invalid — a typo, extra spaces, or a token that was revoked. Click Logs for the error message and check the token in @BotFather (/mybots). Paste the correct token over the masked value in the connection, click Save, then Start.
  • The bot receives messages but the agent stays silent. The connection is not attached to the agent, Inbound is off, or the agent was not restarted after attaching. Also confirm the channel status is RUNNING in Settings > Channels.
  • The bot stopped responding after you regenerated the token in @BotFather. Regenerating revokes the token saved in the connection. Open the connection, paste the new token over the masked value, click Save, then restart the channel (Stop, wait for STOPPED, then Start).
  • You cannot enable Inbound for the bot on a second agent. Expected — one agent handles inbound traffic per bot. Create a separate bot and connection for the other agent.
  • Voice messages get no reply. Configure a speech-to-text model for the agent so it can process audio.
  • Customers report the bot is offline. Check the connection in Settings > Channels — if it shows STOPPED, click Start; if it shows ERROR, check Logs.

Was this article helpful?