# Telegram

> Connect Quickchat AI to Telegram. Add the shared Quickchat AI bot to a group in one click, or create your own bot with BotFather via Advanced setup for custom branding and AI Actions.

There are two ways to connect your AI Agent to Telegram:

1. **Add to a Telegram group**: the recommended one-click flow. No BotFather and no bot token, live in under a minute.
2. **Use your own bot**: the advanced flow where you create a bot with BotFather and supply its token yourself.

We recommend the one-click flow. You can switch to your own bot later if you need the advanced features.

If you get stuck, jump to [Troubleshooting & FAQs](#troubleshooting--faqs) or [contact us](https://quickchat.ai/contact).

## Optional example checks

- [Compare deployment methods][public-lab-deployment-fit-get]. Check your declared channels, website access and required features against Quickchat AI setup options. This does not inspect your website or account.

- [Compare replies per credit budget][public-lab-credit-capacity-get]. Calculate the maximum whole AI replies for each supported model from a supplied credit budget. This does not check your balance or model eligibility.

## Connect with Telegram (recommended)

In the Quickchat AI dashboard, open **External Apps** in the left sidebar, find **Telegram**, and open it. Click **Add to a Telegram group**.

Telegram opens and asks which group to add the shared **Quickchat AI** bot to. Pick the group and confirm. You need permission to add members to that group.

### Confirm the group in the dashboard

Back in the dashboard, the group appears under **Waiting for your confirmation**. Click **Confirm** next to it.

This step is deliberate. The invite is delivered as an ordinary message in the group, which everyone in that group can read, so Quickchat AI does not treat it as proof on its own. Until you confirm, the AI Agent stays completely silent in that group. The entry shows who added the bot, so a group you did not expect is easy to spot and remove instead of confirming.

![The Telegram channel in Quickchat AI: a group waiting for confirmation, a connected group, and the direct message link](https://quickchat.ai/docs/_astro/telegram_oneclick.CvmT-p2_.png)

That's it! 🎉 **Your AI Agent is live on Telegram.** Members start a conversation by **@mentioning** it in the group, or by replying to one of its messages.

:::note
The dashboard shows an **Admin** badge on the chats where the bot is a Telegram admin. That is a status readout, not a requirement: the shared bot answers whether or not it is an admin. Moderation like muting and banning is done with Telegram AI Actions, which need your own bot rather than the shared one.
:::

### Direct message link

Each AI Agent also gets a personal link that opens a one-to-one chat with it on Telegram. On the Telegram page, switch on **Direct message link** and copy the link that appears. Anyone who opens it can message your Agent privately, and it replies straight away with no confirmation step, because a private chat is between one person and the bot.

The link is off by default. Switch it off again at any time to stop new private chats.

### Managing your chats

The Telegram page lists every chat the shared bot serves under **Connected chats**. From there you can:

- **Add to another group** with the same one-click flow, so one AI Agent can serve several groups.
- Switch a chat off to pause replies there without disconnecting it.
- **Disconnect** a chat. The bot leaves that group and stops replying, and you can add it again anytime.

A Telegram chat can be connected to one AI Agent at a time. If a group is already connected to another Agent, disconnect it there first, or choose a different group.

### When to use your own bot

The one-click bot runs as the shared **Quickchat AI** identity, which is perfect for going live fast. Create your own bot (see below) when you want:

- A custom bot name, username and profile picture
- **Telegram AI Actions**. The shared bot does not expose its token as the `{{telegram_bot_token}}` System Token that these Actions need, so they require your own bot.
- A bot that replies to every message in a group rather than only when addressed

The shared bot and your own bot can run side by side, in different groups. Keep them out of the same group: they are separate Telegram bots with separate connections, so if your own bot has privacy mode off it replies alongside the shared one and both answer the same message.

## Use your own bot (Advanced setup)

### Create your Telegram bot

Telegram bots are created through **BotFather**, Telegram's official bot for managing bots. Everything happens inside a normal Telegram chat, so there's no developer portal to sign up for.

1. Open Telegram and start a chat with [@BotFather](https://t.me/BotFather) (look for the blue verified checkmark).
2. Send `/newbot`.
3. Choose a **name** for your bot. This is the display name people see in the chat, for example "Acme Support".
4. Choose a **username**. It must be unique and end in `bot`, for example `acme_support_bot`.

![Creating a bot with BotFather](https://quickchat.ai/docs/_astro/telegram_intro.xxKNAw0o.gif)

BotFather replies with your **bot token**, a string that looks like `5175890488:AAEI8qpz...`. You'll paste it into Quickchat in the next step, so keep the chat open.

:::caution
Treat your bot token like a password. Anyone who has it can control your bot. If it ever leaks, send `/revoke` to BotFather to invalidate the old token and get a new one.
:::

:::tip
You can personalize your bot at any time from BotFather: `/setdescription`, `/setabouttext`, `/setuserpic` (profile picture) and `/setcommands`. Send `/help` to see the full list.
:::

### Connect your bot to Quickchat AI

1. Open the [Quickchat AI App](https://app.quickchat.ai) and go to **External Apps**.
2. Click **Telegram**.
3. Under **Your own bot**, click **Connect to Telegram** and paste your **bot token**.
4. Switch **Enable your own bot** on.
5. Save.

![Telegram integration in the Quickchat AI dashboard](https://quickchat.ai/docs/_astro/telegram_integration.CbcIUGZI.png)

That's it. **Your AI Agent is now live on Telegram!** 🎉

## Try it out

Open your bot in Telegram and send `/start`. Your AI Agent replies with its welcome message and then answers anything you ask. With the shared bot, use your **Direct message link**; with your own bot, BotFather gives you a `t.me/<your_bot_username>` link.

Every conversation also appears in your [Quickchat AI Inbox](https://app.quickchat.ai), where you can read the full transcript, see the visitor's Telegram name, and take over from the AI at any time.

## Character and roleplay bots

A character is an AI Agent with its own persona. Write it in **Identity**: who the character is, how it talks, and what it never says belong in the [Main Prompt](/docs/ai-agent/identity#main-prompt) and **Guidelines**.

The shared bot can serve one AI Agent per chat, so a group with several characters needs one bot per character. For each character, create a bot with BotFather, give it the character's name and profile picture, and connect it to that character's AI Agent under **Your own bot**, as described in [Use your own bot](#use-your-own-bot-advanced-setup).

How members reach each character depends on Telegram's privacy mode, which BotFather turns on for every new bot:

- **Privacy mode on** (keep it on in a group with several characters): a bot only receives replies to its own messages and commands addressed to it. Members talk to a character by replying to one of its messages. To call a character in, send `/start@` followed by its username, for example `/start@luna_bot`, then reply to its greeting.
- **Privacy mode off, or the bot is a group admin**: the bot receives every message in the group and answers all of them, so every character would reply to everything.

Telegram never shows a bot the messages of other bots, so the characters do not reply to each other.

Every AI Agent has its own plan. The Free plan is for personal, non-commercial use; see [Plans & limits](/docs/pricing-and-plans).

## Troubleshooting & FAQs

**I added the bot to a group but nothing happens.**

- Check the Telegram page for a **Waiting for your confirmation** entry and click **Confirm**. The AI Agent stays silent in a group until you do.
- In a group, the shared bot replies when you **@mention** it or reply to one of its messages. It ignores ordinary conversation between members on purpose, so it doesn't interrupt.
- If that group is already connected to a different AI Agent, the bind is refused and no entry ever appears. Disconnect the group from that Agent first, or pick another group.

**My own bot doesn't reply.**

- Make sure the **Enable your own bot** is on and the **bot token is pasted correctly** (no extra spaces). If in doubt, `/revoke` in BotFather and paste the fresh token.
- Send `/start` to the bot first. This is how Telegram activates the chat.
- One bot connects to **one AI Agent**. Don't reuse the same token across multiple Quickchat AI Agents.

**Can I paste the shared Quickchat AI bot's token into the Advanced setup?**

- No, and Quickchat AI refuses it. That token belongs to the bot serving every one-click customer, so accepting it would break their Telegram at once. Use the one-click flow, or create your own bot with BotFather.

**Does the bot work in group chats?**

- Yes. The shared bot replies when @mentioned or replied to. Your own bot runs in Telegram's **privacy mode** by default, so it only sees messages that reply to it or start with `/`. To let your own bot respond to every message in a group, open BotFather, send `/setprivacy`, pick your bot and choose **Disable**, then remove and re-add the bot to the group.

**How do I change the welcome message?**

- The message sent on `/start` is your AI Agent's greeting, configured in the [Quickchat AI App](https://app.quickchat.ai). Update it there and it applies to every channel, including Telegram.

**Can I connect a bot I already have?**

- Absolutely. Open it in BotFather, run `/token` to retrieve (or `/revoke` to reset) its token, and paste that into the Telegram integration. No need to create a new bot.

**Can the bot handle images and files?**

- **Photos** are analyzed by your AI Agent, which can describe them and answer questions about what they show. For other **files** (PDFs, documents), the Agent is told a file was sent and its filename, but it does not read the file's contents. See [Images & files](/docs/ai-agent/attachments) for details.

## Watch the Video

[Watch on YouTube](https://www.youtube.com/watch?v=N1QkRTp_ec0)

## Need Help?

Still stuck? Reach out on [Discord](https://discord.gg/KqkHwvPRNH) or [contact us](https://quickchat.ai/contact) and we'll help you get your bot live.

[public-lab-deployment-fit-get]: https://app.quickchat.ai/v1/api_core/public-question/quickchat/tools/deployment-fit/lab/get/?placement=docs-telegram-deployment-fit-get-v1

[public-lab-credit-capacity-get]: https://app.quickchat.ai/v1/api_core/public-question/quickchat/tools/credit-capacity/lab/get/?placement=docs-telegram-credit-capacity-get-v1
