Telegram

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

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