Delete a channel

Remove a channel; its conversations remain. A phone number stops receiving and placing calls (the number stays in the platform account, where Arbol staff can release it); a WhatsApp number stops sending messages to Raíz. To pause traffic instead, switch it off with update_channel. Not an AI tool.

Scope: raiz:channels:write
Credentials: an API key, a client-credentials token or a person's access token
Effect: deletes
Limits: request body up to 32 KB, response up to 1 MB
CLI: arbol raiz channels delete · not available on MCP

DELETE

https://api.getarbol.com/v1/raiz/channels/{channelId}

Authorization

Authorization
string
required
Bearer <token>, where the token is an API key, a client-credentials token or a person's access token with the scope raiz:channels:write. Get an API key.

Path parameters

channelId
string
required
Channel id.

pattern: ^(?:chn_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))|(?:agc)_(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$

Request body JSON required

Returns

200

Successful operation.

JSON

success
boolean
required
data
object
required
- id
  string
  required
  The id of the deleted resource.
- deleted
  boolean
  required
}
error
null
required
metadata
object
required
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

400

INVALID_INPUT: The request does not match the published schema.
REPORT_FILTER_UNSUPPORTED: A filter does not apply to the selected report.
REPORT_RANGE_INVALID: The report range is invalid: from must not be after to.
INVALID_CURSOR: The cursor is malformed or belongs to a different list.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

401

UNAUTHORIZED: A valid access token is required.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

403

FORBIDDEN: The token does not authorize this operation.
CHANNEL_CREATION_IN_APP: An AI tool creates website chats and forms only. A person adds WhatsApp numbers and phone numbers in Settings → Channels, or through the REST API.
CONVERSATION_VIEW_AUTHOR_ONLY: Only the person who saved this view can make it private; it would disappear for the rest of the team.
WHATSAPP_CHANNEL_REFUSED: Only the WhatsApp Agent Worker delivers through this service, and only Agent messages of a WhatsApp conversation.
WIDGET_REFUSED: This widget session is unavailable.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

404

NOT_FOUND: The requested operation does not exist.
TEMPLATE_NOT_FOUND: The template does not exist in this channel's WhatsApp Business Account.
RESOURCE_NOT_FOUND: The requested resource does not exist in this organization.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

405

HTTP_METHOD_NOT_ALLOWED: The HTTP method is not supported for this resource.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

409

AGENT_NOT_TEXT: Only a text Agent can hold a web conversation.
CALL_IN_PROGRESS: A voice conversation closes by itself when its call ends; it cannot be closed by hand.
CONVERSATION_CLOSED: The conversation is closed. Start a new conversation to write again.
CONVERSATION_NOT_HANDED_OFF: The AI has not handed this conversation to the team, so there is nothing to give back to it.
CONVERSATION_OPEN: The conversation is still open. Close it first.
DAILY_REPORT_IN_PROGRESS: The daily report you asked for is still on its way; it arrives within a minute.
DEFINITION_NOT_ACTIVE: Facts can be asserted only under an active definition.
DEFINITION_RETIRED: The definition is retired and can no longer change.
DEFINITION_TYPE_LOCKED: The value type and subject of a definition cannot change once it has facts. Retire it and create a new one instead.
HANDOFF_ALREADY_CONTINUED: This handoff was already given back to the AI to continue. It continues once per handoff; a new escalation can be given back again.
REPLY_IN_PROGRESS: The Agent is still replying in this conversation. Try again once the reply is delivered.
OUTSIDE_CONTACT_HOURS: The profile's contact hours do not allow starting a conversation now. Try again within them.
PROVIDER_ACCOUNT_EXISTS: This provider account is already registered.
PROVIDER_ACCOUNT_IN_USE: Channels or Agents still use this provider account. Move them to another account first.
SOURCE_CONVERSATION_OPEN: A fact can cite only a closed conversation as its source.
SUPPRESSION_EXISTS: This organization already has this suppression rule.
TASK_NOT_RETRYABLE: This task cannot be retried: its kind never retries, or it already used every attempt. Start it again from its resource.
CHANNEL_AGENT_REQUIRED: Inbound traffic requires an assigned Agent. Outbound traffic requires one except on WhatsApp notification channels.
CHANNEL_ENDPOINT_IN_USE: Another channel already uses this number or endpoint.
CHANNEL_NOT_READY: The channel is not connected yet, or this kind of traffic is not enabled on it.
CHANNEL_TYPE_MISMATCH: This operation or field does not apply to this channel's type.
CONVERSATION_VIEW_LIMIT_REACHED: The organization already has 200 saved views. Delete one before saving another.
CONVERSATION_VIEW_NAME_TAKEN: Another saved view already has this name. Choose a different name.
TEMPLATE_NOT_APPROVED: The template is not approved for sending: it is pending review, rejected, paused or disabled.
WHATSAPP_AI_PAUSED: Automatic replies are paused or this conversation can no longer receive them.
WHATSAPP_MARKETING_STOPPED: The contact chose to stop receiving marketing messages from this business.
WHATSAPP_WINDOW_CLOSED: More than 24 hours passed since the contact last wrote. Start the conversation with an approved template.
PROVIDER_ACCOUNT_MISMATCH: The number and the Agent belong to different voice accounts. A voice Agent answers and dials only numbers of its own account.
PROVIDER_SECRET_UNAVAILABLE: The organization's connection to this integration couldn't complete the request. Don't retry it automatically; if it keeps happening, contact your Arbol team.
VOICE_AGENT_NOT_READY: The Agent cannot take calls yet: it must be an active voice Agent with instructions, published for calls.
VOICE_LINE_UNAVAILABLE: No voice line can place this call. Give an active outbound voice channel, or assign one to the Agent.
VOICE_NUMBER_IN_USE: This number is already connected to another voice service. Release it there first.
AGENT_IN_USE: The Agent still has channels or active campaigns. Unassign them before deleting it.
AGENT_MODALITY_LOCKED: The Agent's modality cannot change while it has channels or is published for calls. Create a new Agent instead.
BULLETIN_LIMIT_REACHED: The organization already has 30 bulletins in force or scheduled. End or delete one before adding another.
EVAL_CASES_UNAVAILABLE: The Agent has no kept evaluation case to replay, or a named case is not one of its kept cases.
EVAL_GATE_UNMET: This Agent requires a completed evaluation run of exactly this content, in which every case passed, before what its model reads changes. Create one with createEvalRun and send its id as evalRunId.
WIDGET_CONFLICT: The request cannot be repeated or another turn is active.
ADDRESS_IN_USE: Another contact in this organization already uses this address.
IDENTIFIER_IN_USE: Another contact in this organization already has this identity document.
INVALID_STATE: The resource is not in a state that allows this operation.
KEY_IN_USE: Another active resource in this organization already uses this key.
CONTACT_SUPPRESSED: A suppression rule of this organization forbids contacting this address.
VERSION_CONFLICT: The resource changed after it was read. Read it again and retry with the new version.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

413

REQUEST_TOO_LARGE: The request exceeds the allowed size.
IMPORT_FILE_TOO_LARGE: The import file is larger than 12 MB. Split it into several files.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

415

UNSUPPORTED_MEDIA_TYPE: The request content type is not supported.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

422

CONTACT_UNREACHABLE: The contact has no phone number. Give the destination number in to.
DAILY_REPORT_RECIPIENTS_MISSING: The daily report has no recipients. Add them in settings.dailyReport.recipients first.
DEFINITION_OPTIONS_INVALID: Only a definition whose value type is option has options; it needs at least one, and option keys must be unique.
FACT_SUBJECT_MISMATCH: The fact's subject (a contact or a conversation) does not match what its definition describes.
FACT_VALUE_INVALID: The value does not match the definition's value type, or names no active option.
IMPORT_FILE_INVALID: The import file is not valid base64 of UTF-8 text. Save the spreadsheet as CSV UTF-8 and try again.
IP_NETWORK_INVALID: The IP network is not a valid IPv4 or IPv6 address or CIDR block.
PROFILE_VARIABLE_MISSING: The profile's template parameters reference a variable that variables does not give.
TIME_ZONE_UNKNOWN: The time zone is not in the IANA time zone database.
CHANNEL_AGENT_MISMATCH: This Agent cannot serve this channel: voice channels need a voice Agent; WhatsApp and web channels need a text Agent.
TEMPLATE_HEADER_MISMATCH: The header file does not fit the template: a document header takes a PDF, an image header a JPEG or PNG, a video header an MP4, and a template without a media header takes no file.
TEMPLATE_HEADER_REQUIRED: The template's header is a document, image or video: send its file with the template.
TEMPLATE_PARAMETERS_MISMATCH: The number of parameters does not match the variables of the template's body.
TEMPLATE_UNSUPPORTED: The template needs header text variables, a location header or button parameters, which cannot be sent yet.
WHATSAPP_MEDIA_REJECTED: WhatsApp could not use the attachment. Check its type and size limits.
WHATSAPP_MESSAGE_UNSUPPORTED: This message cannot be sent on WhatsApp: it allows one attachment per message, up to three buttons or ten list options, and text of up to 4096 characters.
WHATSAPP_RECIPIENT_UNAVAILABLE: The recipient cannot receive WhatsApp messages from this number.
CALL_REJECTED: The call could not be placed. Check the destination number and the line.
PROVIDER_ACCOUNT_UNSUPPORTED: This deployment cannot use provider accounts of this provider yet; the platform's own account is used instead.
PROVIDER_CREDENTIALS_REJECTED: The organization's connection to this integration couldn't complete the request. Don't retry it automatically; if it keeps happening, contact your Arbol team.
VOICE_NUMBER_NOT_OWNED: The platform's telephony account does not own a voice-capable number with this value.
AGENT_PROCEDURES_INVALID: A procedure is incomplete, references a tool, document or procedure the Agent does not have, or breaks the structured step rules. issues says where.
AGENT_SETTINGS_INVALID: The settings do not apply to this Agent's modality, or two settings contradict each other.
BULLETIN_PERIOD_INVALID: A bulletin must end after it starts, and a new one must end in the future.
INTEGRATION_PROCEDURE_UNAVAILABLE: A procedure does not exist in this organization's connections, Raíz cannot run its connection, or the Agent is not a text Agent.
INTEGRATION_TOOL_UNAVAILABLE: An integration tool does not exist in this organization's connections, or Raíz cannot run it.
KNOWLEDGE_DOCUMENT_UNAVAILABLE: A Knowledge document does not exist in this organization.
KNOWLEDGE_FILE_INVALID: The file is not valid base64, exceeds the size limit or does not match its declared type.
KNOWLEDGE_KIND_MISMATCH: The change does not apply to this kind of Knowledge document.
WEBSITE_NOT_APPROVED: This website's origin is not approved for crawling in this deployment.
WIDGET_VOICE_UNHEARD: The voice message could not be understood. Record it again or write the message.
PROVIDER_REJECTED: The provider refused the request. Check the configuration and try again.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

429

RATE_LIMITED: The request rate limit was exceeded. Try again later.
WHATSAPP_RATE_LIMITED: WhatsApp is limiting messages from this number. Try again later.
WIDGET_LIMIT_REACHED: This widget reached its conversations or messages for today. It takes visitors again after 00:00 UTC.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

500

INTERNAL_ERROR: The service could not complete the operation.
WHATSAPP_CHANNEL_INTERNAL: The delivery outcome could not be read back. Asking again never sends the message twice.
WHATSAPP_NOT_SENT: The message was stored but never handed to WhatsApp. It was not sent.
WIDGET_INTERNAL: The request outcome could not be confirmed. Do not repeat it with a new identifier.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

502

OUTCOME_UNKNOWN: The operation may have been applied; check its result before repeating it.
WHATSAPP_DELIVERY_FAILED: WhatsApp did not deliver the message.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

503

UPSTREAM_UNAVAILABLE: The upstream service could not complete the request.
VOICE_UNAVAILABLE: Calls are unavailable right now. Try again in a few minutes.
FEEDBACK_PROPOSAL_UNAVAILABLE: A usable improvement could not be prepared. The Agent has not changed. Try again later.
INTEGRATIONS_UNAVAILABLE: The organization's integrations cannot be read right now. Try again shortly.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

504

UPSTREAM_TIMEOUT: The upstream service did not respond before its deadline.
WHATSAPP_DELIVERY_UNCONFIRMED: WhatsApp never confirmed whether the message was sent. It was not sent again.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}