Telegram (messaging channel)
Connect a Telegram bot as a messaging channel: send messages and receive them as webhooks
The telegram-channel integration runs a Telegram bot for you: Tenklo holds its connection to the Bot API and turns what it receives into webhooks, and you send messages with the same /channels API as a WhatsApp (QR code) number.
Use the Telegram integration instead to call the Bot API yourself through the proxy.
Tenklo reads the bot's updates with getUpdates and deletes any webhook set on it. Don't use a bot that something else already reads.
Quickstart
In Tenklo, go to Integrations -> Configure New Integration -> Telegram (messaging channel). There is nothing to configure.
Go to Connections -> Add Test Connection -> Authorize, and enter the bot token from @BotFather. Tenklo checks it with getMe and starts the bot.
The bot can only message a chat that wrote to it first. Use the chat id from a message.received webhook:
curl -X POST https://api.tenklo.dev/channels/messages \
-H 'Authorization: Bearer <ENVIRONMENT-API-KEY>' \
-H 'Connection-Id: <CONNECTION-ID>' \
-H 'Provider-Config-Key: <INTEGRATION-ID>' \
-H 'Content-Type: application/json' \
-d '{ "to": { "kind": "contact", "externalId": "123456789" }, "content": { "kind": "text", "text": "Hello" } }'API and webhooks
The bot uses the same API and webhooks as a WhatsApp number: see API and Webhooks. The /channels/... paths are the same endpoints as /whatsapp/....
What differs on Telegram:
externalIdis the Telegram chat id: a user's id for a contact, the group's (negative) id for a group.message.statusonly reportsSENTorFAILED: the Bot API has no delivery or read receipts.groups.syncedlists the groups and channels the bot has seen, since the Bot API can't list a bot's chats. It also arrives unprompted when the bot joins or leaves one.- A revoked token disconnects the bot with
SESSION_INVALID: the connection is flagged with an error and anauthwebhook is sent. Update the token with a reconnect session.
Self-hosting
The integration needs the Telegram gateway (packages/telegram-gateway), which runs from the same image as the server:
node packages/telegram-gateway/dist/app.js| Variable | Server | Gateway | Description |
|---|---|---|---|
TELEGRAM_GATEWAY_URL | ✓ | Where the server reaches the gateway, e.g. http://tenklo-telegram:3011. | |
TELEGRAM_GATEWAY_SECRET | ✓ | ✓ | Shared secret (32+ characters): authenticates the commands and events, and seals the bot tokens sent to the gateway. |
TELEGRAM_GATEWAY_EVENTS_URL | ✓ | The server's event endpoint, e.g. http://tenklo-server:3003/internal/telegram/events. | |
TELEGRAM_S3_ENDPOINT, TELEGRAM_S3_REGION, TELEGRAM_S3_ACCESS_KEY, TELEGRAM_S3_SECRET_KEY, TELEGRAM_S3_BUCKET | ✓ | S3-compatible bucket for media (it can be the WhatsApp gateway's). | |
NANGO_DB_*, NANGO_REDIS_URL | ✓ | The same database and Redis as the server. |
Keep the gateway on the internal network: only the server needs to reach it.