Channel setup — per-provider guide

How to connect an agent to each of the 82 channel transports: which credentials go where, what to configure in the provider's console, and each provider's caveats. The dashboard Channels page collects everything below; the same fields apply via the Admin API (POST /v1/projects/{projectId}/channels and the admin-key mirror) with the body { type, agentId, config, secret }.

The shared model

Every connector stores three buckets:

Creating a connector mints a signed inbound URL — register it as the provider's webhook/callback endpoint. Rotating the connector invalidates old URLs.

Telegram and Discord register themselves. For those two the server performs that registration for you at create time, using the bot token you supplied — setWebhook for Telegram, the /ask slash command for Discord — and reports the outcome as a provision object on the create response (the dashboard renders it under the inbound-URL banner). A rotate, or a PATCH that replaces the secret, re-registers for the same reason it has to: the rotate invalidates the old inbound URL, so a provider still pointing at it would deliver nothing while the connector looked healthy. So does a config edit that changes something the provider itself holds — for Discord, config.slashCommand (the command name) and config.applicationId (where it is registered); without that, renaming the command saved green while Discord kept serving the old name. A config edit the provider never sees, and any Telegram config edit, still costs nothing (Telegram registration is the inbound URL plus the secret token, both already covered). Pass autoProvision: false to manage registration yourself. Registration never blocks the write — if the provider is down or the token is wrong, the connector is still created and provision.manualCommand carries the exact command to run by hand. GET verification handshakes (Meta hub.challenge, WeChat echostr, Twitter CRC, Feishu url_verification, QQ op-13, Slack url_verification, Discord PING) are answered automatically.

When inboundSecret is optional, it is not decorative. Most adapters verify the provider's signature/bearer only once you have supplied the credential — until then the signed inbound URL is the only gate, and the end-user identity in the request body is taken at face value. Anyone holding that URL can therefore speak as any user of the connector, including addressing a companion instance another connector (or an SDK /v1/sessions mint) created on the same agent, since instances are keyed by the end-user id. Four transports refuse an unconfigured inbound outright — slack, discord, activitypub, nostr (the last two by explicit opt-in flags). For every other transport: set the inbound secret, and treat the inbound URL as a credential (it is shown once at create and on rotate; rotating invalidates the old one).

Fast-ACK model: providers enforce short webhook response windows (Slack 3s, WeChat/WeCom/Kakao ~5s, Alexa ~8s) while a real agent turn takes 5–60s. Every transport with an out-of-band send API acks the webhook immediately and delivers the reply asynchronously; redeliveries are deduped by each provider's stable event id. The two voice assistants (below) are the exception — they have no out-of-band path.

Webhook-ready (live on save)

Support inboxes & team chat (the intercom template)

The agent answers a per-conversation surface — a support inbox or a bot-token team chat. All are born closed: the platform always authenticates (a webhook HMAC signature, a bot bearer, or an outgoing-webhook body token), so inboundSecret is required and inbound refuses without it. The agent replies as a teammate/operator; the platform's own outbound messages are the echo guard.

Developer platforms (issue / PR / ticket / forum threads)

The agent answers in a comment thread. These surfaces are inherently rooms, so each sets inherentlyGroup — group mode is ON by default, keyed on the thread and mention-gated: set config.wakeWords (the bot's handle) so the agent answers when addressed rather than replying to every comment (config.groupMode: false opts out). All are born closed (webhook signature or a mandatory shared token).

Business-account providers

These need the provider's verified/business account before credentials exist. Multi-part app credentials go in Protocol credentials (secret.extra).

Bridge transports (Pouchy's managed relay)

Persistent-connection networks served by Pouchy's managed relay worker (the platform operator runs one shared instance; deployments without RELAY_BRIDGE_URL have these transports configured-but-dormant). Nothing here is a component you deploy.

Discord: interactions only, and what that means

Discord has two delivery models and Pouchy uses the serverless-friendly one.

An Interactions Endpoint URL receives exactly one class of event: user interactions — slash commands and context-menu actions. It does not receive ordinary chat messages. Those travel over the Gateway, a persistent WebSocket the client must hold open, which a serverless runtime cannot do.

Two consequences worth stating plainly, because both look like bugs:

1. Typing a normal message at the bot in a Discord channel does nothing. That is the transport, not a fault — the message never reaches the endpoint. Users talk to the agent with /ask <message>.
2. With no slash command registered, the connector is inert. The endpoint is configured and validating PINGs, but there is nothing for a user to invoke. This is why the server now registers /ask at create time; before that, a correctly configured connector could sit silent with nothing obviously wrong.

The adapter's parseInbound does understand a Gateway-shaped message payload (content, with the bot-mention/wake-word addressing rules and the bot-loop guard), so a self-hosted Gateway client that forwards MESSAGE_CREATE to the inbound URL works today. Pouchy's managed relay (below) does not carry Discord — it hosts the transports that have no webhook option at all. Adding Discord there would trade the serverless model for an always-on socket per connector, which is a deliberate open question, not an oversight.

Web widget visitor identity

The web transport is the only one whose end-user identity is client-asserted: the inbound route is CORS * by design (that is what lets a browser POST from your page and read the reply inline), so the visitorId in the body is whatever the caller typed. Two consequences, and what the platform does about each.

Your visitors can never reach another origin's companion. A web connector's instances are keyed under a reserved web: namespace, so an asserted visitorId cannot resolve to the instance a Telegram/Slack/email inbound or a POST /v1/sessions mint created for the same agent — even when the raw strings are identical. This is enforced in the transport, not by convention, and a regression is a failing test (web-namespace.test.ts). Instances also carry an originTransport stamp from the moment they are created, and a client-asserted inbound that tries to adopt an instance a verified path minted is refused with 403 plus a channel.origin_refused audit row.

Within your own widget, ids are still only as good as you make them. Nothing stops one of your visitors from claiming another's visitorId. So:

• Never use a guessable or enumerable id. Sequential ids (user_4211), email addresses, phone numbers and any id you also use on another channel are all bad choices. Use a per-visitor random token (a UUID) that your server issues and the browser cannot invent.

• Better: turn on config.verifyVisitor. Set an inboundSecret on the connector, then have your server — which already knows who is signed in — send a signature alongside the id:

  visitorHmac = hex( HMAC-SHA256( inboundSecret, visitorId ) )
  

  POST body: { "visitorId": "...", "visitorHmac": "...", "text": "..." }. Only your backend can mint that value, so a visitorId can no longer be typed by hand. This is the same "identity verification" pattern Intercom and Crisp use.

  The flag is off by default and enabling it is a wire change: once it is on, an unsigned or wrongly-signed request is refused with 401 and the connector shows a Failing health chip in the dashboard — so roll the signature out in your page before you tick the box.

  It also fails closed if the connector has no inboundSecret, so every write plane refuses that combination with a 400 (#136): the dashboard's create form, its config editor, and POST/PATCH on both /v1/projects/{id}/channels and /v1/admin/channels. That includes the case where the flag is already on and a PATCH replaces the secret without carrying inboundSecret forward — secrets are stored as one blob, so such a patch would otherwise silently drop the key the verifier needs. Turning the flag back off is always allowed, secret or not.

Migration note (#135). The web: namespace changed web instance identity. Conversations that widgets held under the old bare id still exist but are no longer reachable from the widget — those visitors start a fresh companion. Nothing else moved: other transports, /v1/sessions and the schedule sweep key exactly as before.

Delivery semantics (all transports)

• Inbound events are deduped on (connector, eventId) for 24h; a failed turn releases the claim so the provider's redelivery is the recovery path.
• Outbound sends are bounded (8s), SSRF-guarded, and non-idempotent-safe: an ambiguous timeout is NOT retried (no double-posting); provider-level errors reported inside HTTP-200 bodies (WeChat errcode, Slack ok:false, Viber status) are detected and audited.
• Every delivery failure writes a channel.delivery_failed audit row (Logs → audit); async turns that never delivered write channel.async_undelivered.
• Group mode (config.groupMode) shares one agent brain per room with a mention/wake-word gate; see channel-group-mode.md.

Attachments (images & files)

Attachment messages become part of the agent turn on transports whose adapter implements media fetch — currently Feishu (image / file / rich-post messages), Telegram (photos and documents, caption preserved), Slack (file_share uploads), Discord (gateway-bridged message attachments), LINE (images, files and voice notes via the content API), WhatsApp (image / document messages, caption preserved), Messenger / Instagram (attachment CDN urls), Twilio MMS/RCS (MediaUrl parts), OnlyFans/Fansly (signed CDN urls), Sendblue iMessage (media_url) and Zalo (attachment urls). Images reach the model as vision input; PDFs, audio and image files ride through the same server-side understanding pipeline the knowledge upload uses (text extraction / vision transcription / STT), and the extracted content is appended to the user turn. Nothing to configure — the downloads authenticate with the connector's existing credentials (Feishu tenant token, Telegram/Slack/LINE/WhatsApp bot or channel token, Twilio account credentials; Slack additionally needs the files:read OAuth scope on the bot token).

Bounds: at most 4 attachments per message are processed (4 images / 2 extracted files per turn); images cap at 8MB, files at 20MB (Telegram's Bot API itself stops at 20MB). An attachment that can't be fetched or read is reported to the model as a readable note — the agent will say what it couldn't open and why, instead of silently ignoring the message. On transports without a media adapter the agent is told an attachment arrived that this channel cannot read yet, so it can answer honestly.