Skip to main content

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) — supply phone_number_id and access_token from your own Meta app. The number is read with the token first: 400 INVALID_ACCESS_TOKEN when Meta rejects the token, 400 PHONE_NUMBER_NOT_ACCESSIBLE when it cannot reach that number, 502 META_UNAVAILABLE when Meta fails. The token's app is then subscribed to the WABA Meta reports as the number's owner, which is the waba_id stored: 400 WABA_NOT_MANAGEABLE when the token cannot subscribe to it.

  • Embedded signup (credential_source: embedded_signup) — supply code and waba_id from the Meta popup; naturali exchanges the code for 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. Returns 501 on 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​

Channel created.