Channels

Inbound routing and outbound delivery for WhatsApp, Telegram, and Discord.

Overview

Channel support lets external chat systems send inbound events into Claw42, route each message to the correct agent session, and optionally deliver agent replies back to the provider. Phase 1 supports WhatsApp, Telegram, and Discord.

Inbound events use a single internal endpoint:POST /api/internal/channels/inbound.

Routing model

Every inbound message is normalized into a shared envelope, then resolved to an agent and session key. Session keys isolate context per channel peer/thread so conversations do not collide.

  • DM default: agent:<agentId>:main
  • Per-peer direct: agent:<agentId>:<provider>:direct:<peerId>
  • Groups/channels: provider + peer scoped session keys
  • Threads/topics append :thread:<id> or :topic:<id>

Provider account config

Channel account records are stored in channel_accounts. Outbound delivery reads config from JSON fields on that account.

  • WhatsApp URL: whatsappOutboundUrl
  • Telegram URL: telegramOutboundUrl
  • Discord URL: discordOutboundUrl
  • Fallback URL: outboundWebhookUrl
  • Provider token: <provider>OutboundAuthToken or outboundAuthToken
  • Optional mode override: deliveryMode = native (default) or webhook.
  • WhatsApp native keys: whatsappPhoneNumberId, whatsappAccessToken.
  • Telegram native key: telegramBotToken.
  • Discord native key: discordBotToken.
  • Queue payload supports rich delivery fields: attachments and options.

Security

  • Internal channel endpoint auth via bearer secret in production.
  • WhatsApp signature verification supports x-hub-signature-256.
  • Telegram webhook token verification supports x-telegram-bot-api-secret-token.
  • Discord interaction verification supports x-signature-ed25519 + x-signature-timestamp.
  • Inbound and outbound messages are idempotent by provider message ID.
  • Rollout gate: CHANNEL_GATEWAY_CANARY_TENANT_IDS controls tenant allowlist.

Current status

  • Inbound normalization + routing: implemented scaffold.
  • Agent webhook execution by resolved session: implemented.
  • Outbound provider delivery adapters + queue worker retries: implemented baseline.
  • Provider signature/token verification: implemented for WhatsApp, Telegram, Discord.
  • Dead-letter requeue endpoint: POST /api/internal/jobs/channel-delivery/requeue.
  • Queue diagnostics endpoint: GET /api/internal/channels/diagnostics.
  • Channel retention endpoint: POST /api/internal/jobs/channel-retention.
  • Admin APIs: /api/admin/channels/accounts and /api/admin/channels/bindings.
  • Live validation + rollout APIs: /api/admin/channels/validate and /api/admin/channels/rollout.
  • Admin queue/dead-letter dashboard: /admin/channels.
  • Delivery lifecycle emits health events into channel_health_events.
  • Smoke script: npm run channel:smoke -- whatsapp.
  • Full E2E tests: in progress.
Get Early Access