Channels · Telegram · ~5 min

Connect a Telegram bot

Wire a Telegram bot into Humane in five steps. Once installed, every message a user sends the bot is verified by Telegram's secret token, parsed into an interaction with channel = "telegram", and routed through the same Brain pipeline your SDK calls use.

1. Get a bot token from @BotFather

Open Telegram, message @BotFather, send/newbot, and follow the prompts. BotFather replies with a bot token that looks like123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11. Copy it — you'll paste it in the next step. The token is the only credential Telegram trusts, so treat it like a password.

2. Create the channel in Humane

From the dashboard: Channels → Connect Telegram, paste the bot token, give it a label, click Create. Or from the SDK:

python
from humane_ai import HumaneClient

client = HumaneClient(api_key="hx_...")

channel = client.channels.create_telegram(
    bot_token="123456:ABC-DEF...",   # from @BotFather
    label="Support bot",
    auto_reply=True,
)

print(channel.id)                    # mc_2nE9...
print(channel.webhook_url_hint)      # /api/ingress/telegram/mc_2nE9...
print(channel.webhook_secret)        # shown ONCE — store it
print(channel.telegram_set_webhook_curl)  # ready-to-run curl, if you want it
Save the webhook_secret now
The response includes webhook_secret (and a ready-to-run telegram_set_webhook_curl) — both are shown once. We only store a hashed copy server-side. If you lose it, rotate via client.channels.update(id, ...).

3. Tell Telegram where to send updates

You have two options.

Option A — Let Humane call setWebhook for you

In the dashboard: click Register webhook with Telegram automatically. Via the SDK:

python
client.channels.register_telegram_webhook(
    channel.id,
    public_base_url="https://your-host.com",
)

Humane builds the full URL (https://your-host.com/api/ingress/telegram/{channel.id}), calls Telegram's setWebhook with the storedsecret_token, and returns Telegram's response. public_base_url is the externally-reachable origin of your Humane deployment — no trailing slash.

Option B — Call setWebhook yourself

If you'd rather drive Telegram's API directly, the response from step 2 includes a ready telegram_set_webhook_curl. Or assemble it by hand:

bash
curl -X POST 'https://api.telegram.org/bot<BOT_TOKEN>/setWebhook' \
  -d 'url=https://your-host.com/api/ingress/telegram/<integration_id>' \
  -d 'secret_token=<webhook_secret>'

Telegram should respond with {"ok": true}. From that moment on, every update Telegram sends will arrive at the ingress endpoint carrying the X-Telegram-Bot-Api-Secret-Tokenheader for verification.

4. How requests are authenticated

On every inbound POST to/api/ingress/telegram/{integration_id} we compare X-Telegram-Bot-Api-Secret-Token to the stored hash for that channel. Match → handled. No match (or missing header) → 401. Telegram is the only party that knows the secret, so forged requests cannot reach the Brain pipeline.

Non-message updates return 200 ignored
Edited messages, channel posts, chat-member updates — anything that isn't a plain user message returns200 {status: "ignored"}. That signals Telegram "received, don't retry" without producing noise in your analytics.

5. Verification

Confirm the wiring works end to end:

  1. Open Telegram on any device and search for your bot by handle.
  2. Send it a message — anything: hello.
  3. The bot should reply within a few seconds with an LLM-generated response (assuming auto_reply is on).
  4. In the dashboard, Users now has an end-user withchannel = "telegram" and an interaction carrying the mood / safety / memory snapshot.
Bot doesn't reply?
Check Telegram'sgetWebhookInfo(curl 'https://api.telegram.org/bot<BOT_TOKEN>/getWebhookInfo'):last_error_messagetells you exactly why delivery failed. The most common cause is the ingress URL pointing at a host Telegram can't reach (private IP, self-signed cert, or wrong domain).
Previous
Messaging Channels
Next
WhatsApp Setup