Skip to main content

Channels

Connect an agent to WhatsApp, Discord, and other messaging surfaces.

Overview​

The customer configures the agent; the platform runs the conversation. A channel connection is established via embedded signup / OAuth / keys, and always carries a default — what answers when nothing else matches. A project's own route table can answer differently per surface and condition, and an address — the identifier a message arrived at — can override both for one identifier. Each conversation maps 1:1 to a Session.

Three kinds are connectable today — whatsapp, discord and x. They share everything above: the same channel, binding and conversation resources, the same address continuity. Only the transport differs, which is why adding a kind adds no concepts, just the fields that kind needs.

How many an account may hold depends on its plan

The billing owner's plan sets how many active channels all their projects may hold together — 1 on Free, 10 on Pro, 100 on Business, and by contract on Enterprise. Connecting one past that answers 403 PLAN_LIMIT_REACHED, with the plan and the limit in meta, before any credential is acquired — so a refused connect leaves nothing provisioned behind.

Only active channels count. Setting one to disabled frees allowance without deleting it or losing its configuration: a disabled channel stops routing and releases what it costs. Setting it back to active past the allowance answers the same 403 PLAN_LIMIT_REACHED.

After a downgrade, when the month ends, active channels past the new plan's allowance are disabled, oldest first. Disable the ones you don't need before then to choose which stay; an upgrade turns the disabled ones back on.

The limit applies to the formation channel resource too — both paths create a channel the same way.

See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Channels.

Data Model​

Channel​

FieldTypeDescription
idstringPublic channel ID (chan_ prefix).
project_idstringThe owning project.
channelwhatsapp | discord | xThe channel kind.
statusactive | disabled
credential_sourcebyot | embedded_signupHow the credential was obtained.
phone_number_idstring, nullableWhatsApp phone number id; inbound webhooks route on this. Null for non-WhatsApp channels.
waba_idstring, nullableWhatsApp Business Account id, when known.
display_phone_numberstring, nullableThe number as Meta displays it, read when the number was linked by embedded signup. Null for other channels and other credential sources.
verified_namestring, nullableThe business name Meta shows for the number, when known; null on the same terms as display_phone_number.
application_idstring, nullableDiscord application id — the tenant's app, one channel per app. The gateway worker holds one connection per channel. Null for non-Discord channels.
modesobject, nullableWhich Discord Gateway flows this channel serves; null for non-Discord channels. At least one must be enabled. * dms — the bot converses 1:1 in direct messages (the WhatsApp shape). Needs only the non-privileged DIRECT_MESSAGES intent. * mention_threads — an @mention in a server opens a thread, and the whole thread is one conversation. Reading the follow-up messages in the thread needs the privileged MESSAGE_CONTENT intent, which you enable on your own Discord app (Discord requires bot verification past ~100 servers), so it is off unless you ask for it.
bot_user_idstring, nullableX. The bot account's user id. Absent for other kinds.
usernamestring, nullableX. The bot account's handle, without @. Absent for other kinds.
chat_key_versionstring, nullableX. The version of the bot's registered chat encryption key. Absent for other kinds.
defaultobjectWhat an inbound message resolves to — a channel's default, a route, or an address's own action, one shape on all three. For a Discord channel, config.discord.allowed_role_ids / allowed_user_ids restrict who may invoke the agent in a server — either list admits, empty or absent lists mean everyone, decided before the agent is invoked so an unlisted member costs nothing.
max_context_messagesinteger, nullableThe most recent messages each conversation's session sends the model, taking precedence over the agent's own max_context_messages. Null defers to the agent.
has_credentialbooleanWhether an access token is on file (its value is never returned).
gateway_errorobject, nullableWhy Discord refused this channel's gateway connection, when it did: the worker stops retrying, so the channel stays silent until a PATCH changes bot_token, modes or status, which clears it. Null when there is none, and for non-Discord channels.
created_atstring (date-time)
updated_atstring (date-time)

Key Concepts​

The channel default​

Every channel carries a default action — agent (answer with an agent), oneshot (run an agent once, keeping nothing), message (deliver fixed text, no session created), or silence (answer nothing) — required on POST /v1/projects/{project_id}/channels and patchable through PATCH /v1/projects/{project_id}/channels/{channel_id}. It is what answers when nothing more specific does: no route matches, and the address has no action of its own. Connecting a channel without saying what it does is the misconfiguration, so it is caught here rather than discovered as silence in production. Connect a Discord channel connects one with an agent default.

An agent or oneshot default needs its writer to be able to run the agent: a narrowed key without agents:CreateAgentGeneration is 403, and a template is held to its deployer's authority.

The same three-field shape (action / agent_id or text / repeat) is what a route and an address carry too — one shape, learned once.

Dialogue or execution: agent and oneshot​

Both run an agent; they differ in what survives the message.

agent is a dialogue. The identity behind the message gets an address, an actor and a session, and every later message on that identity continues the same one — the agent reads what came before.

oneshot runs the agent once and keeps nothing: no address, no actor, no session, no channel conversation. Each message is answered on its own, and nothing accumulates to read back later. Choose it for work that is filed rather than discussed — an inbound that becomes a ticket, a capture, a notification — and agent whenever the answer depends on the history.

The difference shows up in more than cost. On Discord, a conversational agent owns the thread it opened, so every later message there is part of the conversation whether or not it mentions the bot. A oneshot registers no thread, so a mention is the only way in, every time.

What a contact's turn may do​

A contact's turn may run the channel's agent in that contact's conversation (oneshot: once), and nothing else. The agent acts within that, capped by its policy_ids (Execution identity), so with run_as: caller (the default) its http, mcp, naturali and pipeline tool calls, a tool using an OAuth connection included, are refused: the contact holds no tools:CallTool. Give an agent that acts on the project run_as: agent and the policy_ids it needs.

A reply the account cannot pay for​

A channel reply clears the same checks as a generation through the API: a managed model must carry a price, a negative balance stops managed generation, and a Free account stops at its run allowance.

When one refuses, the agent does not run and nothing is created for the turn. The contact gets a fixed line instead — "This assistant can't reply right now. Please try again later.", in Portuguese or Spanish when the action's language is one of them — which never says why. The reason goes to the project's billing owner by email, at most once a day, since they are the one who can clear it. Both agent and oneshot answer this way; a Discord oneshot that only reacts, or delivers nothing, stays silent as it would on any run.

Retrying a create is safe with an idempotency key​

A timeout on a create is ambiguous — the resource may or may not exist — and a duplicate both spends an active-channel allowance and leaves two channels answering the same inbound traffic. Passing idempotency_key in the body settles it: the first request under a key does the work and answers 201, and any later request carrying the same key answers 200 with that same channel, so an ambiguous failure can simply be retried.

The key is claimed within your account and never silently expires, so a retry days later still returns the original rather than creating a second. Reusing a key with a different body is 409 IDEMPOTENCY_KEY_REUSED — a key names one request. A retry arriving while the original is still running is 409 IDEMPOTENCY_REQUEST_IN_PROGRESS; retry once it has answered.

Derive the key from the thing you are creating rather than from the attempt — a key that changes per retry deduplicates nothing.

Do not bind an agent that has an output_schema​

A channel delivers the assistant's reply text verbatim to a person. An agent configured with an output_schema returns its answer as JSON, and a session turn has nowhere to put a parsed object — so the JSON arrives as the message text and the human on the other end reads {"approved":true}.

Structured output is for agents you call through POST /v1/projects/{project_id}/agents/{agent_id}/generate from your own code. Leave channel-facing agents unconstrained.

Who may connect one​

Every route needs the member role — see Membership and the billing owner.

Conversations​

GET /v1/projects/{project_id}/channels/{channel_id}/conversations lists conversations for a channel (filterable by identifier); each maps 1:1 to a session. A conversation is normally created by the inbound path, as a side effect of a real message. The one exception is the outbound-first case: POST /v1/projects/{project_id}/channels/{channel_id}/conversations opens one for an identifier that has not written yet, resolving the same three layers an inbound message would — a 409 when that does not land on an agent, because there is nothing to open. Connect a Discord channel reads the conversation and its messages after a real DM.

In the transcript GET /v1/projects/{project_id}/channels/{channel_id}/conversations/{conversation_id}/messages reads, an inbound message carries provider_message_id, the provider's own id for it (a WhatsApp wamid, a Discord message id) and the one its messages.received event named. A reply carries null.

DELETE /v1/projects/{project_id}/channels/{channel_id}/conversations/{conversation_id} forgets one dialogue: the conversation and its session go, while the address, its actor and its other conversations stay. The address's next message opens a fresh conversation. Erasing the address itself is DELETE /v1/projects/{project_id}/addresses/{identifier}.

Two things share the word "conversation"

A channel conversation is an address's dialogue on a channel, and it lives under the channel that owns it. The Conversations module is the runtime's own message thread — the transcript a session records into, which a channel conversation points at. The mapping is: channel conversation → session → conversation.

How much history the agent sees​

Every message in a conversation is answered with the session's history, which grows for as long as the contact keeps writing. max_context_messages caps it: each generation sends only the most recent messages, dropping the oldest, and the agent's instructions are always sent. It takes precedence over the agent's own max_context_messages; null defers to it.

A change applies to new conversations at once and to open ones on their next message. A value that is not a positive integer is 400 VALIDATION_FAILED. Combined with an agent's prompt caching, the window leaves only the instructions cacheable, since the history it sends changes every turn.

A number is connected through Meta's Embedded Signup, which has to run in the number owner's browser. When you are not that browser — an agent, a script, the Assistant — ask for a link instead with POST /v1/projects/{project_id}/channels/whatsapp/signup-links and hand it to the owner. They sign in with Meta and pick the business account and number. The dialog ends on naturali's app, where a signed-in member of the project confirms the number (POST /v1/channels/whatsapp/signup/complete); only then is it linked. A link opened by anyone else connects nothing.

Linking binds no agent. The channel starts with default: { action: silence } and answers nothing until you bind one with PATCH /v1/projects/{project_id}/channels/{channel_id} or a route.

naturali create-whatsapp-signup-link --project-id proj_V1StGXR8Z5jdHi6B

The link lasts 30 minutes. A number not yet registered for sending gets a two-step verification PIN that naturali generates and does not keep; reset it in WhatsApp Manager if you need it.

A case per WhatsApp contact​

A turn from a contact runs as that contact's actor, and the actor is forwarded to the agent's tools. Give the agent the actor_id-pinned tool, run_as: agent with policy_ids allowing its calls (What a contact's turn may do), and a playbook that declares the contact's company playbook as an upstream. The agent:

  1. lists the contact's cases with subject: "company";
  2. creates it when the list is empty;
  3. creates each month's case, with upstreams: { company: <that case id> }, and fills it.

Every call stays inside the contact's own cases: another contact's, or a case with no actor, answers 404. The month's case reads the company data, so it is asked for once.

Voice notes, images and files​

On WhatsApp and Discord, when a channel answers with an agent, a voice note is transcribed and an image or PDF is read, and the agent receives that text, labelled with what was sent and followed by any caption (on Discord, the message's text; every file on a message is read). The media is deleted once read, so it never joins the project's knowledge. Reading it is paid from credit like any conversion.

Video, stickers, locations and contacts, media over 25 MB, a failed conversion, and WhatsApp numbers linked before media was supported get a fixed line in the action's language asking for text instead. A channel set to silence stays silent.

Discord​

Discord adds two things no other kind has: modes, which picks whether the bot serves direct messages, server threads or both, and an allowlist deciding which server members may invoke it. Both — plus the Discord-side setup they depend on, the intents and permissions each flow needs, and why a Discord bot goes quiet — are on the Discord page.

X​

An x channel answers X Chat direct messages to a bot account. X Chat is end-to-end encrypted, so the channel holds the bot's chat keys and does every step a bot needs, from the three credentials it is given: the bot's bot_token (X developer portal → your app → Chat bots) and the consumer_key and consumer_secret of the app that issued it (Keys and tokens).

On connect, naturali reads the bot, registers a webhook on that app pointing at itself, subscribes it to the bot's incoming direct messages, and registers the bot's chat encryption key, keeping the private key sealed. Each message is then decrypted, routed like any other channel's — its address is x:dm:<sender user id> — and the reply is encrypted and sent. A first message from someone is a message request; the channel accepts it before replying.

X allows only a few chat key registrations per bot each day, so the key is registered last: a refused webhook or subscription spends none. When the budget is spent, connect answers 429 X_KEY_REGISTRATION_LIMITED with meta.reset_at. A bot that already registered a key keeps it by passing chat_private_keys and chat_key_version. Messages encrypted for an older key cannot be read. An X app holds a limited number of webhooks; when X refuses another, connect answers 502 X_PROVISIONING_FAILED with X's reason. Before registering, connect deletes the app's webhooks that point at an x channel that no longer exists. Deleting the channel deletes the subscription and the webhook; the key stays registered on the bot. The webhook URL of a deleted channel answers 404 to X's challenge.

Formations​

A channel is declarable as a channel resource in a formation template, beside the agent it answers with, so connecting a channel and the agent it routes to are one reviewable unit. Its properties are ChannelResourceProperties in the formations spec: the fields POST /v1/projects/{project_id}/channels takes, and the deploy produces the same row that call does.

parameters:
WhatsAppToken:
type: string
no_echo: true
resources:
SupportAgent:
type: agent
properties:
name: support
instructions: Answer questions about an order.
WhatsApp:
type: channel
properties:
channel: whatsapp
phone_number_id: '123456789'
access_token:
param: WhatsAppToken
default:
action: agent
agent_id:
ref: SupportAgent

Three things behave differently from a plain API call:

  • The credential is never stored. access_token, bot_token and code are write-only: the deploy sends them, then drops them from the snapshot it compares against on the next deploy, so a tenant credential never lands in the resource ledger and is never read back. Supply one through a no_echo parameter rather than inline.
  • Every deploy re-sends it. With nothing stored to compare against, the credential always reads as changed, so an update rotates it. That is safe — the rotation path replaces the stored credential and re-points the send tool before dropping the old one — but a redeploy is not a no-op for a channel the way it is for most resources. A WhatsApp token is read against its number first, so a deploy carrying one that cannot reach it fails and keeps the stored one.
  • channel cannot change. A channel's identity and its credential belong to the kind that acquired them, so switching kinds is refused; delete the resource and declare a new one.

A deploy does only what its deployer could do directly (Formations).

Examples​

Connect a WhatsApp channel:

naturali create-channel \
--project-id proj_V1StGXR8Z5jdHi6B \
--channel whatsapp \
--phone-number-id 109999999999999 \
--access-token "$WHATSAPP_ACCESS_TOKEN" \
--default '{ "action": "agent", "agent_id": "agent_V1StGXR8Z5jdHi6B" }'

The number is read with the token before anything is stored: 400 INVALID_ACCESS_TOKEN when Meta rejects the token, 400 PHONE_NUMBER_NOT_ACCESSIBLE when the token cannot reach that number, and 502 META_UNAVAILABLE when Meta fails. Only then is a number another channel already holds refused with 409 PHONE_NUMBER_IN_USE. The token's app is then subscribed to the WhatsApp Business Account Meta reports as the number's owner, so its inbound messages reach naturali, and that account is the stored waba_id: 400 WABA_NOT_MANAGEABLE when the token lacks whatsapp_business_management on it.

Connect a Discord app for DMs only — the default, and the one that needs no privileged intent:

naturali create-channel \
--project-id proj_V1StGXR8Z5jdHi6B \
--channel discord \
--application-id 1290000000000000009 \
--bot-token "$DISCORD_BOT_TOKEN" \
--default '{ "action": "agent", "agent_id": "agent_V1StGXR8Z5jdHi6B" }'

Connect an X bot:

naturali create-channel \
--project-id proj_V1StGXR8Z5jdHi6B \
--channel x \
--bot-token "$X_BOT_TOKEN" \
--consumer-key "$X_CONSUMER_KEY" \
--consumer-secret "$X_CONSUMER_SECRET" \
--default '{ "action": "agent", "agent_id": "agent_V1StGXR8Z5jdHi6B" }'

400 INVALID_BOT_TOKEN or 400 INVALID_CONSUMER_CREDENTIALS when X rejects a credential, and 409 BOT_IN_USE when another channel holds the bot, all before anything is provisioned.

The token is checked with Discord before anything is stored, on connect and on a PATCH of bot_token: 400 INVALID_BOT_TOKEN when Discord rejects it, 400 APPLICATION_MISMATCH when it belongs to another application, 502 DISCORD_UNAVAILABLE when Discord cannot be read (retry). A token reset later, or a flow needing an intent the app has not enabled, makes Discord refuse the connection; the channel then reads gateway_error (INVALID_BOT_TOKEN or disallowed_intents) until a PATCH of bot_token, modes or status clears it and reconnects.

Turn the thread flow on later, once MESSAGE_CONTENT is enabled on the app:

naturali update-channel \
--project-id proj_V1StGXR8Z5jdHi6B \
--channel-id chan_V1StGXR8Z5jdHi6B \
--modes '{ "dms": true, "mention_threads": true }'

Set the channel default to an agent, and restrict who may invoke it in a server:

naturali update-channel \
--project-id proj_V1StGXR8Z5jdHi6B \
--channel-id chan_V1StGXR8Z5jdHi6B \
--default '{
"action": "agent",
"agent_id": "agent_V1StGXR8Z5jdHi6B",
"config": { "discord": { "allowed_role_ids": ["1290000000000000042"] } }
}'

Per-surface and per-condition answers — a public agent in server threads, a different one in DMs, a paywall message until an identifier is admitted — are the route table and addresses.