Telegram

Telegram is the simplest channel to configure — bot creation takes under five minutes with no external approval required. This guide covers creating a bot with @BotFather, connecting it to Snippbot, and registering the webhook.

Prerequisites

• A Telegram account (mobile or desktop)
• A running Snippbot instance reachable from the internet on port 18790 (or via ngrok)
• HTTPS on your webhook URL (required by Telegram in production)

---

Setup Steps

1. Open @BotFather in Telegram

   Start a conversation with @BotFather. This is Telegram’s official bot management account.

2. Create a new bot

   Send the command:

   /newbot

   BotFather asks you two questions:

   • Name: A display name for your bot (e.g. “My Snippbot”)
   • Username: A unique handle ending in bot (e.g. mysnippbot → @mysnippbot)

3. Copy the bot token

   After creating the bot, BotFather replies with a message containing your bot token. It looks like:

   1234567890:AAFhash_randomcharactershere

   Copy this token. Treat it like a password — anyone with this token can control your bot.

4. Configure Snippbot with the bot token

   In the Snippbot UI, navigate to Settings > Channels > Telegram and enter:

   Field	Value
   Bot Token	The token from BotFather
   Webhook Secret	Optional random string for request verification (recommended)

   Click Save.

   Alternatively, add it to ~/.snippbot/config.toml:

   ~/.snippbot/config.toml

   [channels.telegram]
   bot_token = "1234567890:AAFhash_randomcharactershere"
   webhook_secret = "my-random-secret-string"

5. Start the channel adapter

   Start the channel adapter

   snippbot channel start

   When the adapter starts, Snippbot automatically calls the Telegram Bot API to register the webhook URL:

   POST https://api.telegram.org/bot{token}/setWebhook
   Body: { "url": "https://your-server.com:18790/webhook/telegram" }

   The webhook URL is derived from the public_url setting in your Snippbot config (see Configuration Reference).

6. Verify the webhook is registered

   Check webhook status

   curl "https://api.telegram.org/bot{YOUR_BOT_TOKEN}/getWebhookInfo"

   A successful response looks like:

   {
     "ok": true,
     "result": {
       "url": "https://your-server.com:18790/webhook/telegram",
       "has_custom_certificate": false,
       "pending_update_count": 0,
       "last_error_date": null,
       "last_error_message": null,
       "max_connections": 40
     }
   }

7. Test the bot

   Open Telegram and search for your bot by its username (e.g. @mysnippbot). Send it a message. The bot should reply within a few seconds.

---

Webhook URL Pattern

Snippbot registers the webhook at this path on the channel adapter:

https://{your-public-host}:18790/webhook/telegram

The {your-public-host} is determined by the public_url config setting:

~/.snippbot/config.toml

[channels]
public_url = "https://snippbot.yourserver.com"

If public_url is not set, Snippbot will prompt you to provide it when you start the adapter.

---

Configuration Reference

Option	Type	Required	Description
bot_token	string	Yes	Bot token from @BotFather
webhook_secret	string	No	Random secret added to webhook URL for verification. Snippbot validates this on every incoming request
default_agent_id	string	No	Agent to use when no binding matches the incoming chat ID
parse_mode	string	No	How to format bot replies: Markdown, MarkdownV2, or HTML (default: MarkdownV2)

---

Channel Bindings

By default, all messages to your Telegram bot are routed to the default agent. To route messages from specific Telegram chats or users to different agents:

Bind a Telegram chat to an agent

1. Open Settings → Channels → Bindings in the Snippbot UI
2. Click New Binding
3. Select Telegram as the platform
4. Enter the Telegram chat ID as the context ID
5. Select which agent handles messages from that chat
6. Click Save

The context_id is the Telegram chat ID. To find a chat ID, forward a message from that chat to @userinfobot, which returns the ID.

All binding management is done through the Snippbot UI under Settings → Channels → Bindings.

---

Troubleshooting

Webhook registration fails at startup

The most common cause is that your server is not reachable from the internet, or is using HTTP instead of HTTPS.

• Telegram requires HTTPS for all webhook URLs
• For local development, use ngrok: ngrok http 18790 — the HTTPS URL provided by ngrok works with Telegram
• Set public_url to the ngrok HTTPS URL before starting the adapter

The bot does not respond

1. Check the adapter is running: snippbot channel start should show no errors
2. Check the webhook is registered: run the getWebhookInfo command above and look for errors in last_error_message
3. Look at adapter logs for any routing errors

”Unauthorized” error from Telegram API

Your bot token is incorrect or has been revoked. Generate a new token with BotFather:

/mybots → select your bot → API Token → Revoke current token

Then update the token in Snippbot settings.

Messages are delivered but formatting looks wrong

Snippbot uses MarkdownV2 by default. If you see raw asterisks or underscores in replies, switch to HTML mode in the config:

~/.snippbot/config.toml

[channels.telegram]
parse_mode = "HTML"

Caution

In production, your webhook URL must use HTTPS with a valid TLS certificate (not self-signed). Telegram does not deliver events to plain HTTP endpoints or to endpoints with untrusted certificates. Use Caddy, certbot, or ngrok.

Note

Telegram delivers webhook events with a retry policy: if your server does not respond with HTTP 200, Telegram retries at 1s, 3s, 10s, 30s, and 5-minute intervals. Snippbot acknowledges events immediately so retries are typically not triggered.