Setting a webhook for the bot

Webhooks let Telegram deliver updates to your Laravel application so the bot can respond to chat commands and button clicks. Telegram accepts only a public https URL, so local development needs a tunnel such as ngrok, Cloudflare Tunnel, Expose, or a similar HTTPS endpoint.

Local development through a tunnel

1. Start the Laravel application:

php artisan serve

2. Open a public https tunnel to the same port. For the default php artisan serve setup, this is usually port 8000:

ngrok http 8000

3. Copy the public tunnel URL and add it to .env. You can set the full APP_URL, or only the webhook domain used by Telegraph:

APP_URL=https://example.ngrok-free.app
TELEGRAM_WEBHOOK_DOMAIN=https://example.ngrok-free.app
TELEGRAPH_WEBHOOK_SECRET=your-secret-token

Do not commit real bot tokens or webhook secrets. For production, use a secret manager or protected environment variables.

4. If the application uses cached config, clear the cache before registering the webhook:

php artisan config:clear

5. Register the webhook. The argument is required when the database contains more than one bot:

php artisan telegraph:set-webhook {bot_id} --secret="${TELEGRAPH_WEBHOOK_SECRET}"

Laravel .env values are not exported to the shell automatically. If you use ${TELEGRAPH_WEBHOOK_SECRET} in a CLI command, first run export TELEGRAPH_WEBHOOK_SECRET="your-secret-token" in the current shell session or pass the placeholder value explicitly.

Telegraph registers a route like https://example.ngrok-free.app/telegraph/{token}/webhook unless TELEGRAPH_WEBHOOK_URL is overridden. If the tunnel is restarted and the URL changes, update .env, run php artisan config:clear, and run telegraph:set-webhook again.

If the webhook does not receive updates, the route returns 401/403, or debug-webhook shows an old URL, use Troubleshooting Telegraph onboarding.

Verify registration

Check which URL Telegram currently knows:

php artisan telegraph:debug-webhook {bot_id}

For local troubleshooting, you can temporarily enable a detailed dump of incoming webhook updates:

TELEGRAPH_WEBHOOK_DEBUG=true

Do not leave detailed webhook debug enabled in production unless it is strictly needed: payloads can contain user data.

Programmatic setup

A webhook can be registered programmatically through the bot model's registerWebhook() method:

/** @var TelegraphBot $bot */
$bot->registerWebhook(
    secretToken: config('telegraph.webhook.secret'),
)->send();

The end-to-end local development flow with an HTTPS tunnel, webhook secret, and /start handler is covered in Build your first Telegram bot with Telegraph.

For the dropPendingUpdates, maxConnections, and secretToken parameters, see the webhook registration reference.