# Telegram

> Create your own Telegram bot in a few taps and let your agent answer the people who message it.

Create a Telegram bot for your business, and your agent answers everyone who messages it. Customers find the bot by its name in Telegram and chat with it like with any contact.

**Where to find it:** open your agent and go to **Channels → Telegram**.

## What customers see

Customers search for your bot's `@username` in Telegram, or open a link to it. They send a message, and the agent replies in the same chat, under the name and picture you chose.

The bot also works in Telegram groups. Add it to the group, and people mention it by its username to ask a question.

## How it works

You don't need to copy any codes or tokens. Hourzero and Telegram create the bot together, and Hourzero connects it automatically.

1. **Connect**: Sign in to Telegram and create your bot.
2. **Choose the agent**: Make sure this agent answers the bot.
3. **Publish**: Turn on replies and set the bot's name and picture.
4. **Test**: Message the bot and check the reply.

## Before you start

- **You're a workspace owner or admin** in Hourzero. Other members can't see the setup buttons.
- **You have a Telegram account** and the Telegram app on your phone or computer.
- **Your agent has the name you want.** Hourzero suggests the bot's name and username based on your agent's name.

> [!IMPORTANT] The username is permanent
> You can change the bot's display name and picture at any time from Hourzero. The `@username` is set when you create the bot and can't be changed afterwards.

## Connect Telegram and create your bot

1. Go to **Channels** and find the **Telegram** row.
2. Select **Connect Telegram**. If a bot is already connected, the button says **Add bot** instead. Telegram opens in a new tab, and the button changes to **Waiting for Telegram…**.
3. In the new tab, sign in with your Telegram account and approve the connection to Hourzero.
4. Telegram then shows a screen to create your bot, with the suggested name and username. Check them, and confirm.
5. Go back to the Hourzero tab. It updates by itself: first **Finishing your bot connection…**, then the message "Telegram connected. Publish Telegram to start replies."
6. Your bot appears under the Telegram row with its `@username`, and the badge says **Connected**.

While Hourzero waits, you can select **Continue in Telegram** to reopen the bot screen, or **Cancel connection** to stop.

> [!NOTE]
> You have 20 minutes to finish. After that, Hourzero shows "Telegram connection timed out" and you can select **Connect Telegram** to start again.

## Choose which agent answers

When you create a bot from an agent's Channels page, Hourzero assigns it to that agent. Each bot has exactly one agent.

To check or change it:

1. Under your bot, select **Reply settings**.
2. Turn on **Use this agent for this bot**. Turn it off to keep the bot connected but unassigned.
3. Select **Save choices**. A message confirms: "Choices saved. Publish Telegram to apply them."

If another agent already answers the bot, the dialog says **Currently assigned to** that agent and the switch is locked. To move the bot, open the other agent, turn the switch off in its **Reply settings**, and save. Then assign it here, and publish Telegram on both agents.

People who are already chatting stay with the agent that started their conversation, even if you move the bot later.

## Set the bot's name and picture

1. In the Telegram row, select **Edit agent**. The Playground opens with Telegram selected.
2. On the **Display** tab, set the **Display name**, up to 64 characters. Leave it blank to use the agent's name.
3. Under **Avatar**, select **Upload image** and choose a JPG, PNG, or WebP file up to 5 MB.
4. Select **Save draft**, then publish Telegram.

Telegram shows the new name and picture after you publish.

## Publish Telegram

1. In the Telegram row, select **Edit agent**. The Playground opens with Telegram selected.
2. On the **Overview** tab, make sure **Agent replies** says **Replies on after publishing**. Select **Save draft** if you changed anything.
3. Select **Publish → Telegram**. The **Publish Telegram** dialog shows whether the draft is saved and the connection is ready.
4. Select **Publish saved draft**. The next time, the button says **Publish latest draft**.

A message confirms "Telegram published". The bot now answers new messages.

> [!IMPORTANT]
> Connecting doesn't start replies, and neither do later changes. New instructions, a new name or picture, or a new assigned agent only reach Telegram after you publish Telegram again.

## Test it for real

1. In Telegram, search for your bot's `@username` (it's shown under the Telegram row in Hourzero) and open the chat.
2. Select **Start** if Telegram shows it, then ask a question, for example "Where is my order 48213?".
3. Check that the agent replies.
4. Optional: add the bot to a group, and send a message that mentions its `@username`, like "do you ship to Canada?".
5. In Hourzero, open **Activity → Conversations** and select **Visitors**. The chat appears with the Telegram label.

> [!TIP]
> Share your bot with a link: `https://t.me/` followed by its username without the `@`. Put it on your website, in your email signature, or on your order confirmation page.

## Stop or disconnect

To pause the agent but keep the bot connected, open the Playground for Telegram, turn off **Agent replies** on the **Overview** tab, save, and publish.

To remove the bot from Hourzero:

1. In Channels, select the trash icon next to your bot.
2. Read the warning and select **Disconnect**.

All agents stop replying through that bot right away. Your past conversations stay saved in Hourzero.

> [!WARNING]
> You can't reconnect a disconnected bot. Connecting Telegram again creates a new bot with a new username. The old bot stays in your Telegram account, but Hourzero no longer answers it.

## Troubleshooting

### The Hourzero page keeps saying "Waiting for Telegram…"

Finish both steps in the Telegram tab: approve the sign-in, then confirm the new bot. If you closed that tab, select **Continue in Telegram**. To start over, select **Cancel connection**.

### "Telegram could not be connected. Finish or cancel any other Telegram connection"

Only one bot creation can be in progress at a time for your Telegram account, even across agents. Finish or cancel the other one, then try again.

### "Telegram published, but its name or photo could not be updated"

Your answers are live, but Telegram didn't accept the new name or picture. Publish Telegram again to retry.

### The bot doesn't answer in a group

Mention the bot by its username in your message. In groups, Telegram only passes messages addressed to the bot by default.

### The bot doesn't answer at all

- Did you publish Telegram after connecting?
- Does the bot show **This agent is selected for the bot**, and is **Agent replies** on?
- Does your workspace have credits left? Check the [Usage](https://hourzero.dev/docs/workspace-management/usage) page.

### The button says "Telegram is not available yet"

Telegram isn't ready to connect in Hourzero yet. Contact your workspace administrator.

## Next steps

- [WhatsApp](https://hourzero.dev/docs/integrations/whatsapp): Answer customers on WhatsApp too.
- [Playground](https://hourzero.dev/docs/ai-agent-management/playground): Give Telegram its own instructions and test your draft.
- [Conversations](https://hourzero.dev/docs/ai-agent-management/conversations): Read Telegram chats in one place.
