Connect a channel
POST/v1/projects/:project_id/channels
Connect a channel. The required fields depend on channel; no credential is ever returned.
Discord (channel: discord) — supply application_id and bot_token, plus the modes selecting which Gateway flows to serve (direct messages, and/or @mention-opens-a-thread). The token is checked with Discord first: 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. Returns 501 when this deployment does not enable Discord channels.
X (channel: x) — supply the bot's bot_token (X developer portal, Chat bots) and the consumer_key and consumer_secret of the app that issued it. naturali then registers its own webhook on that app, subscribes it to the bot's incoming direct messages and registers the bot's chat encryption key, keeping the private key sealed: replies are end-to-end encrypted, and the project never handles keys, webhooks or ciphertext. Pass chat_private_keys and chat_key_version instead to keep a key the bot already registered. 400 INVALID_BOT_TOKEN or 400 INVALID_CONSUMER_CREDENTIALS when X rejects a credential, 409 BOT_IN_USE when another channel holds the bot, 502 X_PROVISIONING_FAILED when X refuses the webhook or the subscription (an app holds a limited number of webhooks), 429 X_KEY_REGISTRATION_LIMITED when the bot used its few daily key registrations, 502 X_UNAVAILABLE when X cannot be reached. Returns 501 when this deployment does not enable X channels.
WhatsApp (default) — one of two credential paths, both filling the same write-only secret:
-
BYOT (
credential_source: byot, default) — supplyphone_number_idandaccess_tokenfrom your own Meta app. The number is read with the token first:400 INVALID_ACCESS_TOKENwhen Meta rejects the token,400 PHONE_NUMBER_NOT_ACCESSIBLEwhen it cannot reach that number,502 META_UNAVAILABLEwhen Meta fails. The token's app is then subscribed to the WABA Meta reports as the number's owner, which is thewaba_idstored:400 WABA_NOT_MANAGEABLEwhen the token cannot subscribe to it. -
Embedded signup (
credential_source: embedded_signup) — supplycodeandwaba_idfrom the Meta popup; naturali exchanges thecodefor the token, subscribes its app to the WABA and registers the number for sending when it is not yet, so the customer never hands over a token. Returns501on deployments where Meta App credentials are not configured.
The project's plan limits how many channels it may hold. At the limit this responds 403 with PLAN_LIMIT_REACHED, whose meta carries the plan and the limit, before any credential is acquired. Only active channels count, so disabling one frees allowance without deleting it.
Request
Responses
- 201
- 400
- 401
- 403
- 404
- 409
- 429
- 501
- 502
Channel created.
The request was malformed or failed validation.
Missing or invalid credentials.
The credential is scoped to a different project, or the caller's role in the project does not carry this action.
The resource does not exist (existence is not leaked).
The request conflicts with the resource's current state.
X_KEY_REGISTRATION_LIMITED — the X bot used its daily chat key registrations; meta.reset_at says when it may register again.
The requested path is not enabled on this deployment (e.g. embedded signup, or a Discord or X channel, where it is not enabled).
The upstream runtime, or Meta, could not complete the operation.