---
title: "Telegram setup"
url: "/channels/telegram"
description: "Connect a Telegram bot to your agent, including the slash commands users get automatically."
productArea: channels
audience: ["business-user"]
plan: startup
tags: ["channels", "telegram"]
lastReviewed: 2026-08-14
---

# Telegram setup (/channels/telegram)





Connecting a Telegram bot routes messages from Telegram to your agent and sends its replies
back. It uses webhooks — Telegram pushes messages to KlicForge, so there is nothing to poll and
nothing to host.

## Prerequisites [#prerequisites]

* A Telegram account.
* An agent with status `active`.
* A plan that includes the Telegram channel.

## Connecting [#connecting]

<Steps>
  <Step>
    ### Create a bot [#create-a-bot]

    Message [@BotFather](https://t.me/BotFather) on Telegram, create a bot, and copy the token it
    gives you.
  </Step>

  <Step>
    ### Connect it [#connect-it]

    In the dashboard, open your agent's **Channels** tab and select **Connect Channel → Telegram**.
    Paste the bot token and save.
  </Step>

  <Step>
    ### Confirm [#confirm]

    KlicForge encrypts the token and registers the webhook with Telegram automatically. Message your
    bot to check it replies.
  </Step>
</Steps>

## Expected result [#expected-result]

Messages sent to your bot are answered by the agent, and the conversations appear in the
dashboard.

## Slash commands [#slash-commands]

`/start` and `/reset` are registered with Telegram automatically when the channel connects, so
they appear in the bot's command menu. `/help` is recognised in the message text like any other
command, without appearing in that menu.

| Command  | What it does                                                                  |
| -------- | ----------------------------------------------------------------------------- |
| `/start` | Starts a new conversation, keeping what the agent remembers about the contact |
| `/reset` | Starts a new conversation and excludes the session from [memory](/memory)     |
| `/help`  | Lists the commands available on this channel                                  |

`/start` and `/reset` answer immediately with a short greeting from the agent. The greeting is
fixed text, so an agent cannot be prompted to look anything up before replying to a command.

## Group chats [#group-chats]

A Telegram bot can be added to a group. Group behaviour is configurable so the agent responds
only when it should — for example when mentioned — rather than to every message.

## Restricting who can chat [#restricting-who-can-chat]

A Telegram bot is reachable by anyone who finds it, so a bot meant for staff or paying customers
needs an allow list. Set the channel to **Restricted** on its **Allow List** tab and add the
people who may use it.

Entries can be contacts who have messaged before, or rows from a data table with a
`telegram_id` or `telegram_handle` column — which is how you authorise someone who has not
messaged yet. Telegram confirms the sender's identity, so these entries hold. See
[access control](/channels#access-control).

## Disconnecting [#disconnecting]

From the agent's **Channels** tab, select **Disconnect**. KlicForge deregisters the webhook with
Telegram for you.

## Troubleshooting [#troubleshooting]

| Symptom                                            | Likely cause                                                                        |
| -------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Bot does not reply at all                          | Agent status is not `active`, or the token was mistyped                             |
| Bot replies in direct messages but not groups      | Group settings, or Telegram's own bot privacy mode                                  |
| Bot stopped working after an infrastructure change | The webhook URL changed — reconnect the channel                                     |
| Specific people get no reply                       | A deny list entry is filtering them                                                 |
| Nobody gets a reply                                | The channel is **Restricted** and the allow list matches nobody                     |
| Someone on the allow list is refused               | Their handle is stored differently in the data table than the one they message from |

## Related pages [#related-pages]

* [Channels overview](/channels)
* [WhatsApp setup](/channels/whatsapp)
* [Memory](/memory)