WhatsApp and Telegram

WhatsApp and Telegram reach the Hub through webhooks: the provider posts each message to your hub, Hubzoid checks who sent it, and the agent answers in the same chat. Unlike Slack, the webhook address is public, so a contact list in the hub decides who may talk to the agent at all.

When to use thisCopy Anchor Link

Use these surfaces for people who work from a phone: store staff, field coordinators, a manager on the move. Each person gets the same Hub as the web chat, limited to the numbers you list.

How a message is handledCopy Anchor Link

Every inbound route lives under /webhooks/<hub>/<surface>, for example https://hub.example.com/webhooks/stock-desk/whatsapp. The <hub> part is the hub's folder name in lowercase, with anything other than letters and digits turned into hyphens.

The provider gets its 200 ok straight away and the work runs in the background, because Meta and Telegram redeliver when an answer is slow. The duplicate check absorbs those redeliveries.

After the checks, the message goes to the bridge's OpenAI-compatible API with the sender's email and groups from the contact list, the surface name (whatsapp or telegram) and the recent history of that chat.

Run the inbound serverCopy Anchor Link

hubzoid run my-hub --whatsapp --telegram

Combine the flags freely with --slack and --webhook. Each surface starts only when its variables are set. A missing one is named in a warning and that surface is skipped, while the rest of the hub keeps running.

All inbound surfaces share one server on a loopback port, 127.0.0.1:8100 by default (HUBZOID_INBOUND_PORT). The hub's public port forwards /webhooks/<hub> to it, so the providers need only reach your public HTTPS address. See Single server for putting a hub behind a public address.

For a separate process or a systemd unit:

hubzoid inbound run my-hub
hubzoid inbound systemd my-hub > /etc/systemd/system/hubzoid-inbound@my-hub.service

The inbound server needs the hub's bridge running. hubzoid inbound systemd accepts --user and --python like the Slack unit, and the unit requires hubzoid@my-hub.service. The /webhooks/<hub> route on the public port is added only when hubzoid run starts the inbound surfaces itself. When the inbound server runs on its own, route /webhooks/<hub> to its port in your reverse proxy.

Under a gateway, every hub with an inbound surface gets its own /webhooks/<hub> route on the shared front door. Give each of those hubs a different HUBZOID_INBOUND_PORT. The gateway refuses to start two inbound hubs on the same port. If two hubs share a folder name and the gateway had to rename one, pin the path segment with HUBZOID_HUB_SLUG.

The contact listCopy Anchor Link

The contact list lives in the hub's identity/ folder. It is the allowlist: a number that is not on it gets nothing.

phone,email,groups,store
+44 7700 900101,asha@example.com,stock-lead,harbor
447700900102,ben@example.com,,market-street
447700900103,carmen@example.com,stock-lead;finance,head-office

Header names ignore case and surrounding spaces. Blank rows are skipped. Rows that share an email combine their groups, so one person can have several numbers. The file is reread when it changes, so an edit applies to the next message with no restart. Save it in one step (write a new file, then rename) so a half-written file is never read. If the file cannot be read, every lookup denies.

The same list also adds groups on other surfaces: a person who signs in to the web chat or connects over MCP with the same email gets the list's groups on top of their own. It never opens the MCP front door.

A contact list backed by your own systemCopy Anchor Link

To look people up in a CRM or directory instead, put a function in identity/access.py. It wins over the CSV when both exist.

def resolve(surface, handle):
    """handle is the sender's phone number. Return a record or None."""
    row = staff_directory.find_by_phone(handle)
    if row is None:
        return None
    return {"email": row.email, "groups": row.roles}


def groups_for_email(email):
    """Optional. Lets the web chat and MCP use the same groups."""
    row = staff_directory.find_by_email(email)
    return row.roles if row else []

Returning None, or raising an error, denies the sender. Without groups_for_email, the function is only ever asked about phone numbers.

Unknown senders and fixed repliesCopy Anchor Link

The handshake and refusal replies are fixed text sent without the model. Override any of them per hub in .env.

WhatsAppCopy Anchor Link

WhatsApp uses the Meta WhatsApp Cloud API.

WHATSAPP_VERIFY_TOKEN=any-string-you-choose
WHATSAPP_APP_SECRET=<Meta app secret, from App settings, Basic>
WHATSAPP_TOKEN=<Graph API access token>
WHATSAPP_PHONE_NUMBER_ID=<from WhatsApp API setup>

All four are required. In Meta's configuration:

What Hubzoid does with each delivery:

• Every POST must carry a valid X-Hub-Signature-256, an HMAC-SHA256 of the exact request body under your app secret. Anything else gets 403.
• Messages are deduplicated by message id.
• Text, quick-reply buttons, interactive button and list replies, images, documents, audio, voice notes, video and stickers are accepted. A caption travels as the message text.
• The incoming message is marked as read with a typing indicator while the agent works. WhatsApp cannot edit a sent message, so the answer arrives in one piece when it is complete.
• Replies are converted to WhatsApp formatting: bold, strikethrough and monospace. Headings become bold lines, links become label: url, and tables are wrapped in a monospace block. A reply is capped at 4,096 characters with a note to ask for the rest.

TelegramCopy Anchor Link

TELEGRAM_BOT_TOKEN=<token from @BotFather>
TELEGRAM_WEBHOOK_SECRET=any-string-you-choose

Register the webhook once, with the secret Telegram will echo back on every delivery:

curl "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setWebhook?url=https://hub.example.com/webhooks/stock-desk/telegram&secret_token=<TELEGRAM_WEBHOOK_SECRET>"

Every POST must carry the secret in X-Telegram-Bot-Api-Secret-Token or it gets 403. Updates are deduplicated by update id.

Verification by shared numberCopy Anchor Link

Telegram does not reveal a phone number on ordinary messages, so each person verifies once:

1. They send /start. The bot answers with a one-tap Share my number button.
2. They tap it. Hubzoid accepts only the sender's own contact, looks the number up in the contact list and stores the link between their Telegram id and that number under <hub>/.inbound/telegram-bindings/.
3. From then on their messages resolve through the stored number. Removing their row from the contact list removes their access.

A Telegram bot cannot message someone first, so share the bot's link with your team another way, for example by email.

What Hubzoid does with each message:

• A typing indicator stays on while the agent works.
• The answer streams in by editing one message, at most once per INBOUND_STREAM_INTERVAL seconds (1.0 by default, never below 0.8 because Telegram limits edits). Set TELEGRAM_STREAM=false to send the answer once instead.
• Photos (the largest size), documents, voice notes, audio, video and video notes are accepted, with any caption as the text.
• Replies use Telegram's HTML formatting with real links, capped at 4,096 characters.

AttachmentsCopy Anchor Link

Media on either surface follows the same path as the web chat and Slack. Hubzoid downloads the file from the provider and stores it in the chat's uploads folder, <hub>/.hubzoid/chats/<chat_id>/uploads/.

• Images are shown to the model directly, and the reference stays in history so follow-up questions can use them.
• Other files are read with read_upload when the agent needs them.
• Voice notes and audio are stored and referenced. The agent understands them only if the hub provides a transcription tool.
• Files larger than HUBZOID_MAX_UPLOAD_BYTES (25 MiB by default), or files that fail to download, are skipped without failing the message.

Attachments flow inbound only. The agent answers with text.

History and limitsCopy Anchor Link

WhatsApp and Telegram do not resend the conversation, so the inbound server keeps it. Each chat's recent turns are stored in the hz_inbound_history table of the hub database and sent with every new message.

• History is isolated per chat (whatsapp-<number>, telegram-<id>). Two senders never see each other's conversation.
• Only the visible answer is saved, without reasoning or tool output.
• Messages from one chat are handled one at a time, in order, so a quick second message sees the first answer. Different chats run in parallel.
• History rows are keyed by chat, not by hub. Give each inbound hub its own hub database rather than pointing several at one DATABASE_URL.

Restricted tools on these surfacesCopy Anchor Link

Restricted tools are off on whatsapp and telegram by default. To let verified people use them, add the surfaces to the complete list and grant the permission:

HUBZOID_RESTRICTED_SURFACES=owui,web,api,mcp,workflow,whatsapp,telegram

The setting replaces the default list, so keep the entries you still want. The access check runs in the bridge, so restart the hub after changing it. When the hub's access is managed in the Console, the contact list's email must also hold Use this agent for the person to chat at all.

Generic webhooksCopy Anchor Link

The same inbound server can also receive machine events, such as an alert, a CI result or a form submission, at /webhooks/<hub>/<name>. That surface verifies a shared secret or an HMAC signature, stores each event as a file for a scheduled task to act on. It never talks to the model directly and never replies. Setup and the on_webhook: trigger are covered in Webhooks.

ReferenceCopy Anchor Link

Next stepsCopy Anchor Link

Read this page as Markdown