OpenClaw Telegram Webhook vs Polling: Which to Use and How to Set Up

Polling vs Webhook: How They Work

Telegram offers two ways for bots to receive messages. Understanding the difference is important for choosing the right mode for your OpenClaw deployment.

Polling (getUpdates): OpenClaw repeatedly calls Telegram's getUpdates API endpoint to check for new messages. This is a pull model — OpenClaw asks Telegram "any new messages?" every 1-2 seconds. When there are new messages, Telegram returns them in the response. When there are none, it returns an empty response (or holds the connection open for up to 30 seconds in long-polling mode before returning empty).

Webhook (setWebhook): OpenClaw registers a URL with Telegram. When a new message arrives, Telegram immediately sends an HTTP POST request to that URL with the message data. This is a push model — Telegram tells OpenClaw about new messages the instant they arrive. No polling, no delay, no wasted requests.

The performance difference is meaningful. With polling, there is an average latency of 0.5-2 seconds between a user sending a message and OpenClaw receiving it, depending on the poll interval. With webhooks, the latency is typically under 100 milliseconds — essentially instant.

Polling also generates more network traffic. Even when no messages are being sent, OpenClaw makes a request to Telegram every poll interval. With the default 1-second interval, that is 86,400 requests per day even if nobody sends a single message. Webhook mode generates zero traffic during idle periods.

When to Use Each Mode

The rule of thumb: if you have a public HTTPS URL, use webhook mode. If you do not, use polling mode. Polling is perfectly adequate for personal and low-traffic deployments. Webhook mode is recommended for production.

Setting Up Polling Mode

Polling is the default mode and requires minimal configuration. You only need your Telegram bot token.

Create a bot via BotFather if you have not already:

1. Open Telegram and search for @BotFather
2. Send /newbot
3. Follow the prompts to set a name and username
4. Copy the bot token (looks like 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz)

Add the bot token to your OpenClaw environment:

OPENCLAW_TELEGRAM_ENABLED=true
OPENCLAW_TELEGRAM_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
OPENCLAW_TELEGRAM_MODE=polling

Restart OpenClaw:

docker compose down && docker compose up -d

That is it. OpenClaw will start polling Telegram for new messages immediately. Send a message to your bot in Telegram and it should respond within 1-2 seconds.

You can adjust the polling interval with:

OPENCLAW_TELEGRAM_POLL_INTERVAL=1000

The value is in milliseconds. The default is 1000 (1 second). Increasing it to 2000 or 3000 reduces network traffic but increases average latency. Decreasing it below 1000 can trigger Telegram's rate limits on the getUpdates endpoint.

Setting Up Webhook Mode

Webhook mode requires a public HTTPS URL. If your OpenClaw instance is on a VPS with a domain name and SSL, here is the setup:

OPENCLAW_TELEGRAM_ENABLED=true
OPENCLAW_TELEGRAM_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
OPENCLAW_TELEGRAM_MODE=webhook
OPENCLAW_TELEGRAM_WEBHOOK_URL=https://your-domain.com/api/channels/telegram/webhook

When OpenClaw starts with webhook mode configured, it automatically calls Telegram's setWebhook API to register your URL. You can verify the webhook is registered:

curl https://api.telegram.org/bot1234567890:ABCdefGHIjklMNOpqrsTUVwxyz/getWebhookInfo

The response should show your URL, the pending update count, and the last error (if any). A successful setup looks like:

{
  "ok": true,
  "result": {
    "url": "https://your-domain.com/api/channels/telegram/webhook",
    "has_custom_certificate": false,
    "pending_update_count": 0,
    "max_connections": 40,
    "ip_address": "your.server.ip"
  }
}

If the last_error_message field is present, Telegram encountered an error trying to deliver a message to your webhook. Common errors include SSL certificate issues, connection refused (port not open), and timeout (server too slow to respond).

Important: You must configure a webhook secret token to prevent unauthorized requests to your webhook endpoint. Set:

OPENCLAW_TELEGRAM_WEBHOOK_SECRET=your-random-secret-here

Generate a random secret with: openssl rand -hex 32

OpenClaw passes this secret to Telegram when registering the webhook, and Telegram includes it in the X-Telegram-Bot-Api-Secret-Token header of every webhook request. OpenClaw verifies the header matches before processing the message. Without this, anyone who discovers your webhook URL could send fake messages to your bot.

SSL Certificate Configuration

Telegram requires HTTPS for webhook URLs. No exceptions. You need a valid SSL certificate on the domain or IP address used in your webhook URL.

Option 1: Let's Encrypt with Caddy (recommended). Caddy automatically provisions and renews Let's Encrypt certificates. If you are using Caddy as a reverse proxy (which is the recommended setup for OpenClaw on a VPS), SSL is handled automatically with zero configuration.

Example Caddyfile:

your-domain.com {
  reverse_proxy localhost:3008
}

That is the entire Caddy configuration. It automatically obtains and renews an SSL certificate for your-domain.com and proxies traffic to OpenClaw on port 3008.

Option 2: Let's Encrypt with Nginx. If you prefer Nginx, use Certbot to obtain a Let's Encrypt certificate:

sudo certbot --nginx -d your-domain.com

Certbot configures Nginx with the certificate and sets up automatic renewal.

Option 3: Self-signed certificate. Telegram supports self-signed certificates, but you need to upload the certificate to Telegram when setting the webhook. OpenClaw supports this with:

OPENCLAW_TELEGRAM_WEBHOOK_CERT=/app/data/cert.pem

OpenClaw will include this certificate file when calling setWebhook. Self-signed certificates work but require more maintenance and configuration. Use Let's Encrypt instead if possible.

Switching Between Modes

Switching from polling to webhook (or vice versa) is a two-step process:

Polling to Webhook:

1. Update your environment variables: change OPENCLAW_TELEGRAM_MODE to webhook and add OPENCLAW_TELEGRAM_WEBHOOK_URL
2. Restart OpenClaw: docker compose down && docker compose up -d

OpenClaw automatically registers the webhook with Telegram on startup. It also automatically deletes any existing webhook when starting in polling mode, so switching back is equally simple.

Webhook to Polling:

1. Change OPENCLAW_TELEGRAM_MODE to polling
2. Restart OpenClaw

OpenClaw calls Telegram's deleteWebhook API and starts polling. Any messages that were pending in the webhook queue will be delivered via the next getUpdates call.

Troubleshooting

Webhook registered but no messages received: Check that your firewall allows incoming HTTPS traffic on port 443 (or whatever port your reverse proxy listens on). Also verify your reverse proxy is correctly forwarding to OpenClaw's port (default 3008).

"SSL certificate problem" in Telegram webhook info: Your SSL certificate is invalid, expired, or self-signed without being uploaded to Telegram. Use getWebhookInfo to see the specific error. If using Let's Encrypt, check that Certbot/Caddy auto-renewal is working.

Polling works but webhook does not: This usually means your server is not reachable from the internet. Verify by accessing your webhook URL from an external network: curl https://your-domain.com/api/channels/telegram/webhook. You should get a response (even an error response) rather than a connection timeout.

Duplicate messages with webhook: If Telegram does not receive a 200 OK response from your webhook within ~60 seconds, it retries the delivery. This can cause duplicate message processing if your agent takes too long to respond. Set OPENCLAW_TELEGRAM_WEBHOOK_ACK_IMMEDIATELY=true to acknowledge the webhook request immediately and process the message asynchronously.

Frequently Asked Questions

Should I use polling or webhook for OpenClaw Telegram?

Use polling if you are running OpenClaw locally, behind a firewall, or on a network without a public IP. Use webhook if you have a public HTTPS URL — webhooks deliver messages instantly with zero latency, while polling has a 1-2 second delay. Webhook mode also uses less bandwidth and CPU.

Does OpenClaw Telegram webhook require SSL?

Yes. Telegram requires HTTPS for webhook URLs. You need a valid SSL certificate — self-signed certificates work but require extra configuration. The easiest approach is to use a reverse proxy like Caddy or Nginx with Let's Encrypt for free automatic SSL certificates.

How do I switch from Telegram polling to webhook in OpenClaw?

Set OPENCLAW_TELEGRAM_MODE=webhook and OPENCLAW_TELEGRAM_WEBHOOK_URL=https://your-domain.com/api/channels/telegram/webhook in your environment variables. Restart OpenClaw, and it will automatically register the webhook URL with Telegram's API.

Can I use Telegram webhook with OpenClaw on a home network?

Not directly, because Telegram needs to reach your server via a public HTTPS URL. However, you can use a tunneling service like Cloudflare Tunnel (free) or ngrok to expose your local OpenClaw instance to the internet. Cloudflare Tunnel is recommended for production use as it provides a stable URL and does not require port forwarding.