> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zappway.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram

> The Telegram integration lets you connect an **AI Employee** (Agent) to one or more Telegram conversations—private chats, groups, or channels—via the official **Telegram Bot API**. Once configured, the AI automatically replies to new messages according to the workflows you set up in ZappWay, and you can jump in manually at any time through the **Inbox** interface.

> **Important:**
> Telegram “bots” are special accounts controlled by a token, not by a phone number. A single bot can be added to many groups or channels, but **every message must reach the bot** (via a direct mention, reply, or channel post) for the AI to respond.

***

## 🔢 Table of Contents

1. [Create a Telegram Bot with BotFather](#1-create-a-telegram-bot-with-botfather)
2. [Retrieve the Bot HTTP Token](#2-retrieve-the-bot-http-token)
3. [Add & Promote the Bot in Chats / Channels](#3-add--promote-the-bot-in-chats--channels)
4. [Configure Webhooks in Telegram](#4-configure-webhooks-in-telegram)
5. [Connect Your Bot to ZappWay](#5-connect-your-bot-to-zappway)
6. [Send a Test Message](#6-send-a-test-message)
7. [Monitoring & Maintenance](#7-monitoring--maintenance)

***

## 1. Create a Telegram Bot with BotFather

1. Open **Telegram** (desktop or mobile).
2. Search for **`@BotFather`** and open the verified account.
3. Tap **Start** (or send `/start`). BotFather displays a menu of commands.
4. Send `/newbot`.
5. Follow the prompts:

   * **Bot name** – the full display name shown to users (e.g., “ZappWay Support”).
   * **Username** – must end with `bot` (e.g., `zappway_support_bot`).
6. BotFather replies with:

   ```
   Done! Congratulations on your new bot.
   Use this token to access HTTP API:
   123456789:AAE-YourLongTokenHere
   ```

   ✅ **Copy the token**—you will paste it into ZappWay later.

> **Tip:** Your bot is public by default. If you prefer to hide it from search, send `/setprivate` to BotFather.

***

## 2. Retrieve the Bot HTTP Token

* If you lost the token, open BotFather and send `/token`, then pick your bot.
* Store the token **securely** (password manager, vault); anyone with this token can control the bot.

***

## 3. Add & Promote the Bot in Chats / Channels

### 3.1 Private Support Chat (optional)

1. Open a 1-on-1 chat with your bot.
2. Send `/start` so the bot is allowed to message you.

### 3.2 Group Support Chat

1. Create or open the group where customers will send messages.
2. Tap the group title ➜ **Add Member** ➜ search your bot’s username ➜ **Add**.
3. Promote it to **Administrator** (required so it can read and send all messages).

   * Permissions needed: *Read messages*, *Send messages*, *Manage messages* (optional).

### 3.3 Public or Private Channel

1. Open the channel ➜ **Manage** ➜ **Administrators** ➜ **Add Admin** ➜ select your bot.
2. Grant **Post Messages** permission so the AI can publish replies.

> **Why admin?** Telegram only delivers all messages to bots that are admins; otherwise the bot sees *mentions* only.

***

## 4. Configure Webhooks in Telegram

Telegram delivers updates to **one** webhook URL per bot.

1. Copy the **Callback URL** and **Verify Token** shown in ZappWay (you will get them in Step 5).
2. Send this HTTPS request (you can use a browser address bar):

```
https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook
  ?url=<CALLBACK_URL>
  &secret_token=<VERIFY_TOKEN>
```

* Replace `<YOUR_TOKEN>`, `<CALLBACK_URL>`, `<VERIFY_TOKEN>` with real values.
* Telegram replies with `{"ok":true, "result":true, ...}` if the webhook is set.

> **Note:**
>
> * The URL **must** use HTTPS with a valid certificate.
> * A single bot can point to one webhook at a time. Calling `setWebhook` again overwrites the previous URL.

***

## 5. Connect Your Bot to ZappWay

1. Sign in to **ZappWay ➜ Integrations ➜ Telegram ➜ Add Telegram Integration**.

2. **Paste the HTTP Token** you copied from BotFather. Click **Continue**.

   * ZappWay validates the token with Telegram’s `getMe` endpoint.

3. ZappWay now displays two read-only fields:

   * **Callback URL** – the endpoint you just set in Step 4
   * **Verify Token** – the `secret_token` you passed to `setWebhook`

4. Click **Save**. The integration status changes to **“Waiting for updates”**.

> If ZappWay shows “Invalid credentials,” re-check the token in BotFather and repeat Step 5.

***

## 6. Send a Test Message

1. From any Telegram account, send “Hello” to:

   * the bot directly **or**
   * a group/channel where the bot is admin.
2. In ZappWay ➜ **Inbox**, you should see the incoming message.
3. If you configured auto-reply flows, the AI Employee should respond automatically.

> **Troubleshooting:** No message in Inbox?
>
> * Confirm webhook status with `https://api.telegram.org/bot<YOUR_TOKEN>/getWebhookInfo`.
> * `last_error_message` will reveal SSL or network issues.
> * Ensure the bot has permission to read group/channel messages (admin role).

***

## 7. Monitoring & Maintenance

### 7.1 Webhook Health

* `getWebhookInfo` returns fields `pending_update_count` and `last_error_date/message`.
* A non-zero `last_error_date` means Telegram could not POST to ZappWay. Check firewall/SSL.

### 7.2 Token Security

* Tokens never expire automatically but revoke them immediately if leaked:
  `/revoke` command in BotFather ➜ Requires setting a new webhook.

### 7.3 Scaling & Limits

* Telegram bots can send **30 messages / second** overall and **1 message / second** per chat.
* Large attachments (video, docs) are delivered as file IDs; ZappWay fetches content on demand.

### 7.4 Common Errors

| Error Code           | Meaning       | Fix                                                  |
| -------------------- | ------------- | ---------------------------------------------------- |
| 401 / 403            | Invalid token | Re-paste correct token in ZappWay & setWebhook again |
| 400 “chat not found” | Bot not admin | Add/promote bot in the group/channel                 |
| 429                  | Flood control | Reduce message rate or chunk long replies            |

***

## ✅ Final Notes

* **One webhook per bot** – if you experiment in staging, remember to switch back to production URL.
* **Privacy Mode** – by default, bots *do not* see every group message. Admin promotion disables privacy mode so the AI can read full context.
* **Testing** – Always test in a private chat first, then small group, before rolling out to public channels.
* **Security** – Never share your token in screenshots or logs.

***

### Useful Links

* Telegram Bot API Documentation: [https://core.telegram.org/bots/api](https://core.telegram.org/bots/api)
* BotFather Command Reference: [https://core.telegram.org/bots#botfather](https://core.telegram.org/bots#botfather)
* Webhook Setup Guide: [https://core.telegram.org/bots/webhooks](https://core.telegram.org/bots/webhooks)

Follow every step above and your Telegram integration with ZappWay will be live and ready to handle customer conversations automatically.