---
title: "Channels"
description: "The WhatsApp numbers, phone numbers and website chats where Raíz agents talk to patients, and how to add them, assign an agent and switch their traffic."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.getarbol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Channels

A channel is a place where patients reach your organization and where your agents answer them: a WhatsApp number, a phone number or a chat on your website. For each channel you choose the agent that answers there, and whether it takes calls and messages from people (inbound), lets your organization start conversations (outbound), or both.

## Kinds of channel

| `channelType` | What it is | Its agent |
| --- | --- | --- |
| `whatsapp` | A WhatsApp number, which the business connects through a setup link. | A text agent |
| `voice` | A phone number for calls: one the platform already owns, or your own number and carrier over SIP. | A voice agent |
| `web` | A chat, a form or both on your websites, and optionally on a page of its own. | A text agent |

An agent whose modality doesn't fit the channel is refused with `422 CHANNEL_AGENT_MISMATCH`.

## Add a channel

[`raiz.channels.create`](/api/raiz/channels/create/) takes the `channelType` and, optionally, a `name`, an `agentId` and the `inboundEnabled` and `outboundEnabled` switches; with an agent, traffic is on by default. The call isn't idempotent: after an unknown outcome, [list the channels](/api/raiz/channels/list/) before trying again. Over [MCP](/en/developers/mcp/) it adds only web channels and answers `403 CHANNEL_CREATION_IN_APP` for the others: add WhatsApp and phone numbers with the REST API or in the Raíz Dashboard.

### WhatsApp

1. **Create the channel.** It starts `pending`, and the answer carries a setup link in `setup.url`, with its expiry in `setup.expiresAt`.

   ```bash
   curl https://api.getarbol.com/v1/raiz/channels \
     --request POST \
     --header "Authorization: Bearer $ARBOL_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{
       "channelType": "whatsapp",
       "name": "Front desk",
       "agentId": "agt_01jd8x5k2m7q9r3t6v8w0y4z1b"
     }'
   ```

2. **Give the link to the person who manages your WhatsApp number, and to no one else.** Anyone with the link can connect a number to this channel. That person connects the number at the link.

3. **Verify the channel.** Once the number is connected, send the `channelId` to [`raiz.channels.verify`](/api/raiz/channels/verify/). The channel becomes `active`, with the number as its `address`. If the link had expired, the answer carries a new one in `setup`, ready to send again.

To replace a link that was lost or must go to someone else, [`raiz.channels.renewSetup`](/api/raiz/channels/renew-setup/) issues a new one and the previous one stops working. If the number is already connected, it completes the channel as `raiz.channels.verify` does and returns no link. If another channel already has the number, verifying answers `409 CHANNEL_ENDPOINT_IN_USE`.

### Phone numbers

A `voice` channel takes an `endpoint` and is connected at once. `"kind": "platform_number"` uses a number the platform already owns, given as `phoneNumber` in E.164 (`+` and digits), with an optional `label`. `"kind": "sip_trunk"` uses your own number and carrier, over SIP:

| Field | What you provide |
| --- | --- |
| `phoneNumber` | Required. The number, in E.164. |
| `address` | Required. The SIP host or IP address your carrier receives calls at, with an optional port. |
| `transport` | `auto`, `udp`, `tcp` or `tls`. |
| `mediaEncryption` | `disabled`, `allowed` or `required`. |
| `username`, `password` | Your trunk's digest credentials, if it uses them. They're used once, to connect, and never stored. |
| `label` | Up to 120 characters. |

### Web chat

A `web` channel takes its whole `widget` configuration, in which only `title` and `allowedOrigins`, the exact origins allowed to embed it (up to 20, such as `https://www.example.com`), are required. `mode` is `chat` (a conversation), `form` (a form only) or `form-chat` (the form, then the conversation), with up to 40 form `fields`. `publicLink: true` also serves it on its own hosted page. Texts, colors, fonts, attachments, voice messages, daily limits and up to 6 more agents a visitor may pick are part of the configuration too; see [the reference](/api/raiz/channels/create/). By default the agent doesn't use its integration tools with anonymous visitors (`allowBusinessTools`).

Create it with `"inboundEnabled": false` to review it before visitors can reach it. Its `publication` says whether it's `live`, the `url` of its hosted page, and the `problems` that keep it from being live: `CHANNEL_INACTIVE`, `PAUSED` (inbound is off), `AGENT_REQUIRED`, `AGENT_PAUSED` or `NOT_PLACED` (no hosted page and no https site may embed it).

## Assign an agent and switch traffic

[`raiz.channels.update`](/api/raiz/channels/update/) changes a channel. Fields you leave out stay as they are.

| Field | What it does |
| --- | --- |
| `agentId` | The agent that answers here. `null` stops inbound automation; a WhatsApp number can still send outbound notifications. |
| `inboundEnabled` | Answer calls and messages from people. Off, inbound traffic is ignored and a web widget is switched off. |
| `outboundEnabled` | Let your organization start calls or WhatsApp conversations from this channel. |
| `aiCoveragePercent` | WhatsApp: the share of new inbound conversations, from 0 to 100, assigned to the AI. At `0` your team handles them. Conversations already assigned keep their assignment. |
| `businessHours` | WhatsApp: when the number attends. See [below](#business-hours-on-whatsapp). |
| `profile` | WhatsApp: the business profile people see: `about`, `address`, `description`, `email`, `vertical` and up to two `websites`. Read it with `expand=profile` on [`raiz.channels.get`](/api/raiz/channels/get/). |
| `widget`, `widgetLogo` | Web: the complete new widget configuration, and a logo (PNG, JPEG or WebP, up to 256 KiB, base64-encoded; `null` removes it). |
| `name`, `expectedVersion` | A name for people, and the `version` you read. |

Inbound traffic needs an assigned agent, and so does outbound traffic on phone and web channels; only WhatsApp sends outbound notifications without one. Otherwise the update answers `409 CHANNEL_AGENT_REQUIRED`. A channel is `ready` when it's active and its traffic is enabled.

### Business hours on WhatsApp

`businessHours` says when a WhatsApp number attends, whichever agent answers it: up to 28 `windows`, each with `days` (`MO` to `SU`) and `from` and `to` as `HH:MM`, plus `closedDates` such as holidays and a `timeZone` (the organization's when `null`). Outside them the AI doesn't answer, and whoever writes receives `outsideHoursMessage` once per closed period, or the approved template in `outsideHoursTemplate`. `closingGraceMinutes` (15, 30, 60 or 120) keeps attending a conversation in progress at closing time. `null` removes the hours, and the number attends at all hours.

## Status

| `status` | Meaning |
| --- | --- |
| `pending` | A WhatsApp number whose setup the business hasn't finished. |
| `active` | Connected. |
| `degraded` | Connected, but the last check with the provider failed. `raiz.channels.verify` checks again. |

[`raiz.channels.list`](/api/raiz/channels/list/) filters channels by `agentId`, `channelType` and `status`, newest first.

## Remove a channel

[`raiz.channels.delete`](/api/raiz/channels/delete/) removes a channel, and its conversations remain. A phone number stops receiving and placing calls, and a WhatsApp number stops sending messages to Raíz. To stop a channel for a while instead, switch its traffic off. Deleting is REST only, not offered on MCP.

## Errors

| Status | `code` | Meaning |
| --- | --- | --- |
| `409` | `CHANNEL_AGENT_REQUIRED` | Inbound traffic requires an assigned agent; outbound traffic does too, except on WhatsApp. |
| `409` | `CHANNEL_ENDPOINT_IN_USE` | Another channel already uses this number or endpoint. |
| `409` | `CHANNEL_TYPE_MISMATCH` | The operation or field doesn't apply to this channel's type. |
| `409` | `INVALID_STATE` | The channel isn't in a state that allows this, such as renewing the setup of a channel that isn't pending. |
| `422` | `CHANNEL_AGENT_MISMATCH` | Phone numbers need a voice agent; WhatsApp and web chat need a text agent. |

See every operation's codes in the [Channels reference](/api/raiz/tags/channels/).

Source: https://docs.getarbol.com/en/developers/raiz/channels/index.mdx