Channels
Operations tagged Channels in the public API.
About Channels
A channel connects a chatbot to a messaging platform — telegram, whatsapp, facebook (Messenger), instagram, slack, discord, line, viber, wechat or sms (Twilio) — so the chatbot answers people there. A chatbot has at most one channel per platform, addressed by the platform name.
Lifecycle. POST /chatbots/{chatbotId}/channels/{platform} checks the credentials with the platform and registers the chatbot's webhook. The channel is then active — or pending on WhatsApp, Messenger, Instagram and WeChat until the platform verifies the webhook; the verify token that step asks for is shown in the dashboard's channel settings, not by /v1. POST …/verify re-checks the credentials (error on failure). DELETE disconnects: the channel stays readable as inactive. Conversations that arrive through a channel are read through /conversations, where channel names the platform.
IDs you will meet.
platform— the path key of every single-channel operation.id— the channel's integer id;nullin the list for a platform the chatbot never connected (status: not_connected).
IDs on this page
- Chatbot id
<CHATBOT_ID> - Integer.
Get it from
- GET /v1/chatbots returns it as
data[].id - POST /v1/chatbots returns it as
id - GET /v1/chatbots/by_handle/{handle} returns it as
id - Webhook chatbot.created carries it as
data.object.id - In the dashboard, it is the number in a chatbot's address:
/dashboard/chatbots/{id}.
- GET /v1/chatbots returns it as
- Channel platform
<PLATFORM> - One of
telegram,whatsapp,facebook,instagram,slack,discord,line,viber,wechat,sms. Another value is 404NOT_FOUND.Get it from
- GET /v1/chatbots/{chatbotId}/channels returns it as
data[].platform
- GET /v1/chatbots/{chatbotId}/channels returns it as
List a chatbot's channels
Returns one entry per messaging platform, always all ten and in a fixed order, so the list doubles as the catalogue of platforms you can connect. A platform the chatbot never connected comes back with
status: not_connected and id: null; a disconnected one keeps its row with status: inactive. The list is not paginated.- Required scope
- channels:read
- Idempotency
- Read-only
- Rate limits
Before you call
Integer.chatbotId(path)Chatbot idPlaceholder in the samples:
<CHATBOT_ID>Get it from
- GET /v1/chatbots returns it as
data[].id - POST /v1/chatbots returns it as
id - GET /v1/chatbots/by_handle/{handle} returns it as
id - Webhook chatbot.created carries it as
data.object.id - In the dashboard, it is the number in a chatbot's address:
/dashboard/chatbots/{id}.
- GET /v1/chatbots returns it as
Path parameters
chatbotIdintegerRequiredThe chatbot id.
Responses
- 200Success.
objectstringRequiredAlways
listdataarray of any ofRequiredhas_morebooleanRequirednext_cursoranynullableRequiredprevious_cursoranynullableRequiredurlstringRequired
- 400A tenant selector header named a tenant other than the API key's own (
ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digitX-Account-Idother than the key owner's id or, whileworkspaces.context_enabledis on, anX-Workspace-Idother than the key's workspace (ws_prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numericX-Account-Id, is ignored; a key cannot switch tenants, so send neither.Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
- 401Missing or invalid API key.
Error codesUNAUTHENTICATED
- 403The API key is missing a required scope.
Error codesACCOUNT_SUSPENDEDINSUFFICIENT_SCOPE
- 404The resource does not exist on this account.
Error codesNOT_FOUND
- 429Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
- 500Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR
Request
curl
curl -X GET 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>/channels' \
-H "Authorization: Bearer <YOUR_KEY>" \
-H "Content-Type: application/json"Response
Example 200 response
json
{
"object": "list",
"data": [
{
"object": "channel",
"id": 1,
"chatbot_id": 1,
"platform": "telegram",
"status": "active",
"connection_mode": "credentials",
"bot_username": "acme_support_bot",
"webhook_url": "https://api.agentency.com/webhooks/telegram/int_example",
"connected_at": "2026-01-01T00:00:00+00:00",
"total_messages": 128,
"total_users": 17,
"last_activity_at": null,
"error_code": null
},
{
"object": "channel",
"id": null,
"chatbot_id": 1,
"platform": "whatsapp",
"status": "not_connected",
"connection_mode": null,
"bot_username": null,
"webhook_url": null,
"connected_at": null,
"total_messages": 0,
"total_users": 0,
"last_activity_at": null,
"error_code": null
},
{
"object": "channel",
"id": null,
"chatbot_id": 1,
"platform": "facebook",
"status": "not_connected",
"connection_mode": null,
"bot_username": null,
"webhook_url": null,
"connected_at": null,
"total_messages": 0,
"total_users": 0,
"last_activity_at": null,
"error_code": null
},
{
"object": "channel",
"id": null,
"chatbot_id": 1,
"platform": "instagram",
"status": "not_connected",
"connection_mode": null,
"bot_username": null,
"webhook_url": null,
"connected_at": null,
"total_messages": 0,
"total_users": 0,
"last_activity_at": null,
"error_code": null
},
{
"object": "channel",
"id": null,
"chatbot_id": 1,
"platform": "slack",
"status": "not_connected",
"connection_mode": null,
"bot_username": null,
"webhook_url": null,
"connected_at": null,
"total_messages": 0,
"total_users": 0,
"last_activity_at": null,
"error_code": null
},
{
"object": "channel",
"id": null,
"chatbot_id": 1,
"platform": "discord",
"status": "not_connected",
"connection_mode": null,
"bot_username": null,
"webhook_url": null,
"connected_at": null,
"total_messages": 0,
"total_users": 0,
"last_activity_at": null,
"error_code": null
},
{
"object": "channel",
"id": null,
"chatbot_id": 1,
"platform": "line",
"status": "not_connected",
"connection_mode": null,
"bot_username": null,
"webhook_url": null,
"connected_at": null,
"total_messages": 0,
"total_users": 0,
"last_activity_at": null,
"error_code": null
},
{
"object": "channel",
"id": null,
"chatbot_id": 1,
"platform": "viber",
"status": "not_connected",
"connection_mode": null,
"bot_username": null,
"webhook_url": null,
"connected_at": null,
"total_messages": 0,
"total_users": 0,
"last_activity_at": null,
"error_code": null
},
{
"object": "channel",
"id": null,
"chatbot_id": 1,
"platform": "wechat",
"status": "not_connected",
"connection_mode": null,
"bot_username": null,
"webhook_url": null,
"connected_at": null,
"total_messages": 0,
"total_users": 0,
"last_activity_at": null,
"error_code": null
},
{
"object": "channel",
"id": null,
"chatbot_id": 1,
"platform": "sms",
"status": "not_connected",
"connection_mode": null,
"bot_username": null,
"webhook_url": null,
"connected_at": null,
"total_messages": 0,
"total_users": 0,
"last_activity_at": null,
"error_code": null
}
],
"has_more": false,
"next_cursor": null,
"previous_cursor": null,
"url": "/v1/chatbots/1/channels"
}Retrieve a channel
Returns the chatbot's channel on one platform: its
status, the platform account it is connected to (bot_username), the webhook_url the platform posts to, its message and user counts and, after a failure, an error_code. A platform the chatbot never connected is 404 NOT_FOUND; a disconnected one is returned with status: inactive.- Required scope
- channels:read
- Idempotency
- Read-only
- Rate limits
Before you call
Integer.chatbotId(path)Chatbot idPlaceholder in the samples:
<CHATBOT_ID>Get it from
- GET /v1/chatbots returns it as
data[].id - POST /v1/chatbots returns it as
id - GET /v1/chatbots/by_handle/{handle} returns it as
id - Webhook chatbot.created carries it as
data.object.id - In the dashboard, it is the number in a chatbot's address:
/dashboard/chatbots/{id}.
- GET /v1/chatbots returns it as
One ofplatform(path)Channel platformtelegram,whatsapp,facebook,instagram,slack,discord,line,viber,wechat,sms. Another value is 404NOT_FOUND.Placeholder in the samples:
<PLATFORM>Get it from
- GET /v1/chatbots/{chatbotId}/channels returns it as
data[].platform
- GET /v1/chatbots/{chatbotId}/channels returns it as
Path parameters
chatbotIdintegerRequiredThe chatbot id.platformstringRequiredThe messaging platform, e.g.telegram.
Responses
- 200
ChannelResourceobjectstringRequiredAlways
channelidintegerRequiredThe channel id. Single-channel operations address the channel byplatforminstead.chatbot_idintegerRequiredThe chatbot that answers on this channel.platformstringRequiredThe messaging platform.Possible values
telegramwhatsappfacebookinstagramslackdiscordlineviberwechatsmsstatusstringRequiredactive(answering),pending(waiting for the platform to verify the webhook),error(the last check or delivery failed; seeerror_code) orinactive(disconnected).Possible values
activeinactivependingerrorconnection_modestringRequiredHow the channel was connected:credentials(pasted credentials, the only mode/v1creates),oauthorembedded_signup(dashboard sign-in flows).Possible values
credentialsoauthembedded_signupbot_usernamestringnullableRequiredThe platform account the chatbot answers as (bot username, page name or phone number);nullwhen the platform reports none.webhook_urlstringnullableRequiredThe URL the platform delivers messages to. Paste it into the platform's app settings when the channel ispending;nullonce disconnected.connected_atstringnullableRequiredWhen the channel was connected (ISO 8601, UTC).total_messagesintegerRequiredMessages the channel has carried.total_usersintegerRequiredPlatform chats that have messaged the chatbot here: one per chat, counted when its conversation starts.last_activity_atstringnullableRequiredWhen the channel last carried a message (ISO 8601, UTC);nullbefore the first.error_codestringnullableRequiredWhy the last failure happened:auth_failed(credentials rejected or revoked),rate_limited,unreachable,not_found(the bot or chat is gone on the platform) orunknown;nullwhen there was none.Possible values
auth_failedrate_limitedunreachablenot_foundunknownnull
- 400A tenant selector header named a tenant other than the API key's own (
ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digitX-Account-Idother than the key owner's id or, whileworkspaces.context_enabledis on, anX-Workspace-Idother than the key's workspace (ws_prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numericX-Account-Id, is ignored; a key cannot switch tenants, so send neither.Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
- 401Missing or invalid API key.
Error codesUNAUTHENTICATED
- 403The API key is missing a required scope.
Error codesACCOUNT_SUSPENDEDINSUFFICIENT_SCOPE
- 404The resource does not exist on this account.
Error codesNOT_FOUND
- 429Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
- 500Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR
Request
curl
curl -X GET 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>/channels/<PLATFORM>' \
-H "Authorization: Bearer <YOUR_KEY>" \
-H "Content-Type: application/json"Response
Example 200 response
json
{
"object": "channel",
"id": 1,
"chatbot_id": 1,
"platform": "telegram",
"status": "active",
"connection_mode": "credentials",
"bot_username": "acme_support_bot",
"webhook_url": "https://api.agentency.com/webhooks/telegram/int_example",
"connected_at": "2026-01-01T00:00:00+00:00",
"total_messages": 128,
"total_users": 17,
"last_activity_at": null,
"error_code": null
}Connect a channel
Connects the chatbot to a messaging platform with that platform's credentials, sent as the JSON body, and returns the channel. The credentials are checked with the platform first (rejected ones are 422
CHANNEL_CONNECTION_FAILED, an unreachable platform 503 CHANNEL_UNREACHABLE), then the chatbot's webhook is registered. Credentials are stored encrypted and never returned; keys the platform does not take are dropped.
platform
Body
telegram
bot_token (from BotFather, 123456:ABC…)
whatsapp
access_token, phone_number_id, app_secret
facebook, instagram
page_access_token, app_secret
slack
bot_token (xoxb-…), signing_secret
discord
bot_token, public_key (64 hex characters)
line
channel_access_token, channel_secret
viber
auth_token
wechat
app_id, app_secret
sms (Twilio)
account_sid (AC…), auth_token, from_number (E.164)
Telegram, Slack, Discord, LINE, Viber and SMS come back active. WhatsApp, Messenger, Instagram and WeChat come back pending until the platform verifies the webhook: paste webhook_url into the platform's app settings together with the verify token shown in the dashboard's channel settings (/v1 does not return it). Connecting a platform the chatbot already has reconnects it with the new credentials.
A chatbot holds a capped number of active or pending channels (3 by default): connecting another platform at the cap is 402 CHANNEL_LIMIT_REACHED (details.max_connected) with nothing written; reconnecting a platform the chatbot already has never takes a new slot. 402 INTEGRATIONS_NOT_AVAILABLE when the plan has no channel integrations; 404 FEATURE_DISABLED when messaging channels are switched off on this deployment. A second connect for the same chatbot while another is still running is 409 CHANNEL_CONNECT_BUSY: nothing is written, no platform is called, and the refusal is not stored for Idempotency-Key replay.- Required scope
- channels:write
- Idempotency
- Accepts Idempotency-Key
- Webhook events
- channel.connected
- Rate limits
Before you call
Integer.chatbotId(path)Chatbot idPlaceholder in the samples:
<CHATBOT_ID>Get it from
- GET /v1/chatbots returns it as
data[].id - POST /v1/chatbots returns it as
id - GET /v1/chatbots/by_handle/{handle} returns it as
id - Webhook chatbot.created carries it as
data.object.id - In the dashboard, it is the number in a chatbot's address:
/dashboard/chatbots/{id}.
- GET /v1/chatbots returns it as
One ofplatform(path)Channel platformtelegram,whatsapp,facebook,instagram,slack,discord,line,viber,wechat,sms. Another value is 404NOT_FOUND.Placeholder in the samples:
<PLATFORM>Get it from
- GET /v1/chatbots/{chatbotId}/channels returns it as
data[].platform
- GET /v1/chatbots/{chatbotId}/channels returns it as
Path parameters
chatbotIdintegerRequiredThe chatbot id.platformstringRequiredThe messaging platform to connect, e.g.telegram.
Header parameters
Idempotency-KeystringOptionalMakes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key withIdempotency-Replayed: true; a retry while the first request runs is 409IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422IDEMPOTENCY_KEY_REUSED; a malformed key is 400INVALID_IDEMPOTENCY_KEY.Min length:
16Max length:128Pattern:^[A-Za-z0-9_-]+$
Responses
- 200
ChannelResourceobjectstringRequiredAlways
channelidintegerRequiredThe channel id. Single-channel operations address the channel byplatforminstead.chatbot_idintegerRequiredThe chatbot that answers on this channel.platformstringRequiredThe messaging platform.Possible values
telegramwhatsappfacebookinstagramslackdiscordlineviberwechatsmsstatusstringRequiredactive(answering),pending(waiting for the platform to verify the webhook),error(the last check or delivery failed; seeerror_code) orinactive(disconnected).Possible values
activeinactivependingerrorconnection_modestringRequiredHow the channel was connected:credentials(pasted credentials, the only mode/v1creates),oauthorembedded_signup(dashboard sign-in flows).Possible values
credentialsoauthembedded_signupbot_usernamestringnullableRequiredThe platform account the chatbot answers as (bot username, page name or phone number);nullwhen the platform reports none.webhook_urlstringnullableRequiredThe URL the platform delivers messages to. Paste it into the platform's app settings when the channel ispending;nullonce disconnected.connected_atstringnullableRequiredWhen the channel was connected (ISO 8601, UTC).total_messagesintegerRequiredMessages the channel has carried.total_usersintegerRequiredPlatform chats that have messaged the chatbot here: one per chat, counted when its conversation starts.last_activity_atstringnullableRequiredWhen the channel last carried a message (ISO 8601, UTC);nullbefore the first.error_codestringnullableRequiredWhy the last failure happened:auth_failed(credentials rejected or revoked),rate_limited,unreachable,not_found(the bot or chat is gone on the platform) orunknown;nullwhen there was none.Possible values
auth_failedrate_limitedunreachablenot_foundunknownnull
- 400A tenant selector header named a tenant other than the API key's own (
ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digitX-Account-Idother than the key owner's id or, whileworkspaces.context_enabledis on, anX-Workspace-Idother than the key's workspace (ws_prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numericX-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honoursIdempotency-Keyalso returnsINVALID_IDEMPOTENCY_KEYwhen that header is not 16–128[A-Za-z0-9_-]characters.Error codesACCOUNT_SELECTOR_NOT_SUPPORTEDINVALID_IDEMPOTENCY_KEY
- 401Missing or invalid API key.
Error codesUNAUTHENTICATED
- 402A billing gate refused the request (plan limit, monthly AI budget or message credits). See
error.code. - 403The API key is missing a required scope.
Error codesACCOUNT_SUSPENDEDINSUFFICIENT_SCOPE
- 404The resource does not exist on this account.
Error codesFEATURE_DISABLEDNOT_FOUND
- 409The request conflicts with the current resource state.
Error codesCHANNEL_CONNECT_BUSYIDEMPOTENCY_IN_FLIGHT
- 422Validation failed. See
error.details.Error codesCHANNEL_CONNECTION_FAILEDIDEMPOTENCY_KEY_REUSEDVALIDATION_FAILED
- 429Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
- 500Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR
- 503HTTP 503.
Error codesCHANNEL_UNREACHABLE
Request
curl
curl -X POST 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>/channels/<PLATFORM>' \
-H "Authorization: Bearer <YOUR_KEY>" \
-H "Content-Type: application/json"Response
Example 200 response
json
{
"object": "channel",
"id": 1,
"chatbot_id": 1,
"platform": "telegram",
"status": "active",
"connection_mode": "credentials",
"bot_username": "acme_support_bot",
"webhook_url": "https://api.agentency.test/webhooks/telegram/ch_example",
"connected_at": "2026-01-01T00:00:00+00:00",
"total_messages": 0,
"total_users": 0,
"last_activity_at": null,
"error_code": null
}Disconnect a channel
Stops the chatbot answering on the platform: the stored credentials are cleared, the webhook is unregistered where the platform allows it, and the channel stays readable with
status: inactive (the response says deleted: true). Reconnect with POST /chatbots/{chatbotId}/channels/{platform}. Conversations that came through the channel are kept.
A platform the chatbot never connected is 404 NOT_FOUND; 404 FEATURE_DISABLED when the platform's connector is switched off on this deployment.- Required scope
- channels:write
- Idempotency
- Accepts Idempotency-Key
- Webhook events
- channel.disconnected
- Rate limits
Before you call
Integer.chatbotId(path)Chatbot idPlaceholder in the samples:
<CHATBOT_ID>Get it from
- GET /v1/chatbots returns it as
data[].id - POST /v1/chatbots returns it as
id - GET /v1/chatbots/by_handle/{handle} returns it as
id - Webhook chatbot.created carries it as
data.object.id - In the dashboard, it is the number in a chatbot's address:
/dashboard/chatbots/{id}.
- GET /v1/chatbots returns it as
One ofplatform(path)Channel platformtelegram,whatsapp,facebook,instagram,slack,discord,line,viber,wechat,sms. Another value is 404NOT_FOUND.Placeholder in the samples:
<PLATFORM>Get it from
- GET /v1/chatbots/{chatbotId}/channels returns it as
data[].platform
- GET /v1/chatbots/{chatbotId}/channels returns it as
Path parameters
chatbotIdintegerRequiredThe chatbot id.platformstringRequiredThe messaging platform, e.g.telegram.
Header parameters
Idempotency-KeystringOptionalMakes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key withIdempotency-Replayed: true; a retry while the first request runs is 409IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422IDEMPOTENCY_KEY_REUSED; a malformed key is 400INVALID_IDEMPOTENCY_KEY.Min length:
16Max length:128Pattern:^[A-Za-z0-9_-]+$
Responses
- 200Success.
objectstringRequiredAlways
channelidintegerRequireddeletedbooleanRequired
- 400A tenant selector header named a tenant other than the API key's own (
ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digitX-Account-Idother than the key owner's id or, whileworkspaces.context_enabledis on, anX-Workspace-Idother than the key's workspace (ws_prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numericX-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honoursIdempotency-Keyalso returnsINVALID_IDEMPOTENCY_KEYwhen that header is not 16–128[A-Za-z0-9_-]characters.Error codesACCOUNT_SELECTOR_NOT_SUPPORTEDINVALID_IDEMPOTENCY_KEY
- 401Missing or invalid API key.
Error codesUNAUTHENTICATED
- 403The API key is missing a required scope.
Error codesACCOUNT_SUSPENDEDINSUFFICIENT_SCOPE
- 404The resource does not exist on this account.
Error codesFEATURE_DISABLEDNOT_FOUND
- 409The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
- 422Validation failed. See
error.details.Error codesIDEMPOTENCY_KEY_REUSED
- 429Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
- 500Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR
Request
curl
curl -X DELETE 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>/channels/<PLATFORM>' \
-H "Authorization: Bearer <YOUR_KEY>" \
-H "Content-Type: application/json"Response
Example 200 response
json
{
"object": "channel",
"id": 1,
"deleted": true
}Check a channel's connection
Calls the platform with the stored credentials and reports whether they still work (
healthy). A failure sets the channel's status to error (its error_code says why); a success sets it back to active, except that a pending channel stays pending until the platform has verified its webhook. It emits no webhook event.
A platform the chatbot never connected is 404 NOT_FOUND; 404 FEATURE_DISABLED when the platform's connector is switched off on this deployment.- Required scope
- channels:write
- Idempotency
- Accepts Idempotency-Key
- Webhook events
- None
- Rate limits
Before you call
Integer.chatbotId(path)Chatbot idPlaceholder in the samples:
<CHATBOT_ID>Get it from
- GET /v1/chatbots returns it as
data[].id - POST /v1/chatbots returns it as
id - GET /v1/chatbots/by_handle/{handle} returns it as
id - Webhook chatbot.created carries it as
data.object.id - In the dashboard, it is the number in a chatbot's address:
/dashboard/chatbots/{id}.
- GET /v1/chatbots returns it as
One ofplatform(path)Channel platformtelegram,whatsapp,facebook,instagram,slack,discord,line,viber,wechat,sms. Another value is 404NOT_FOUND.Placeholder in the samples:
<PLATFORM>Get it from
- GET /v1/chatbots/{chatbotId}/channels returns it as
data[].platform
- GET /v1/chatbots/{chatbotId}/channels returns it as
Path parameters
chatbotIdintegerRequiredThe chatbot id.platformstringRequiredThe messaging platform, e.g.telegram.
Header parameters
Idempotency-KeystringOptionalMakes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key withIdempotency-Replayed: true; a retry while the first request runs is 409IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422IDEMPOTENCY_KEY_REUSED; a malformed key is 400INVALID_IDEMPOTENCY_KEY.Min length:
16Max length:128Pattern:^[A-Za-z0-9_-]+$
Responses
- 200Success.
objectstringRequiredAlways
channel_verificationidintegerRequiredplatformstringRequiredhealthybooleanRequired
- 400A tenant selector header named a tenant other than the API key's own (
ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digitX-Account-Idother than the key owner's id or, whileworkspaces.context_enabledis on, anX-Workspace-Idother than the key's workspace (ws_prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numericX-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honoursIdempotency-Keyalso returnsINVALID_IDEMPOTENCY_KEYwhen that header is not 16–128[A-Za-z0-9_-]characters.Error codesACCOUNT_SELECTOR_NOT_SUPPORTEDINVALID_IDEMPOTENCY_KEY
- 401Missing or invalid API key.
Error codesUNAUTHENTICATED
- 403The API key is missing a required scope.
Error codesACCOUNT_SUSPENDEDINSUFFICIENT_SCOPE
- 404The resource does not exist on this account.
Error codesFEATURE_DISABLEDNOT_FOUND
- 409The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
- 422Validation failed. See
error.details.Error codesIDEMPOTENCY_KEY_REUSED
- 429Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
- 500Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR
Request
curl
curl -X POST 'https://api.agentency.com/v1/chatbots/<CHATBOT_ID>/channels/<PLATFORM>/verify' \
-H "Authorization: Bearer <YOUR_KEY>" \
-H "Content-Type: application/json"Response
Example 200 response
json
{
"object": "channel_verification",
"id": 1,
"platform": "telegram",
"healthy": true
}