Telegram

​

📌 Overview

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
2. Retrieve the Bot HTTP Token
3. Add & Promote the Bot in Chats / Channels
4. Configure Webhooks in Telegram
5. Connect Your Bot to ZappWay
6. Send a Test Message
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:

   Copy

   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

​

✅ 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
• BotFather Command Reference: https://core.telegram.org/bots#botfather
• Webhook Setup Guide: 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.