---
title: "Canales"
description: "Los números de WhatsApp, los números de teléfono y los chats de sitio web donde los agentes de Raíz hablan con los pacientes, y cómo agregarlos, asignarles un agente y controlar su tráfico."
---

> 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.

# Canales

Un canal es un lugar donde los pacientes se comunican con tu organización y donde tus agentes les responden: un número de WhatsApp, un número de teléfono o un chat en tu sitio web. Para cada canal eliges el agente que responde ahí, y si recibe llamadas y mensajes de las personas (entrante), si le permite a tu organización iniciar conversaciones (saliente), o ambas cosas.

## Tipos de canal

| `channelType` | Qué es | Su agente |
| --- | --- | --- |
| `whatsapp` | Un número de WhatsApp, que la empresa conecta con un enlace de configuración. | Un agente de texto |
| `voice` | Un número de teléfono para llamadas: uno que la plataforma ya tiene, o tu propio número y operador por SIP. | Un agente de voz |
| `web` | Un chat, un formulario o ambos en tus sitios web, y opcionalmente en una página propia. | Un agente de texto |

Un agente cuya modalidad no corresponde al canal se rechaza con `422 CHANNEL_AGENT_MISMATCH`.

## Agregar un canal

[`raiz.channels.create`](/api/raiz/channels/create/) recibe el `channelType` y, opcionalmente, un `name`, un `agentId` y los interruptores `inboundEnabled` y `outboundEnabled`; con un agente, el tráfico queda activado por defecto. La llamada no es idempotente: después de un resultado desconocido, [lista los canales](/api/raiz/channels/list/) antes de intentarlo de nuevo. Por [MCP](/developers/mcp/) solo agrega canales web y responde `403 CHANNEL_CREATION_IN_APP` para los demás: agrega los números de WhatsApp y de teléfono con la API REST o en la app de Raíz.

### WhatsApp

1. **Crea el canal.** Empieza en `pending`, y la respuesta trae un enlace de configuración en `setup.url`, con su vencimiento en `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": "Recepción",
       "agentId": "agt_01jd8x5k2m7q9r3t6v8w0y4z1b"
     }'
   ```

2. **Dale el enlace a la persona que administra tu número de WhatsApp, y a nadie más.** Cualquiera que tenga el enlace puede conectar un número a este canal. Esa persona conecta el número en el enlace.

3. **Verifica el canal.** Una vez conectado el número, envía el `channelId` a [`raiz.channels.verify`](/api/raiz/channels/verify/). El canal pasa a `active`, con el número como su `address`. Si el enlace había vencido, la respuesta trae uno nuevo en `setup`, listo para enviar de nuevo.

Para reemplazar un enlace que se perdió o que debe ir a otra persona, [`raiz.channels.renewSetup`](/api/raiz/channels/renew-setup/) emite uno nuevo y el anterior deja de funcionar. Si el número ya está conectado, completa el canal como lo hace `raiz.channels.verify` y no devuelve ningún enlace. Si otro canal ya tiene el número, la verificación responde `409 CHANNEL_ENDPOINT_IN_USE`.

### Números de teléfono

Un canal `voice` recibe un `endpoint` y se conecta de inmediato. `"kind": "platform_number"` usa un número que la plataforma ya tiene, dado como `phoneNumber` en E.164 (`+` y dígitos), con una `label` opcional. `"kind": "sip_trunk"` usa tu propio número y operador, por SIP:

| Campo | Qué das |
| --- | --- |
| `phoneNumber` | Obligatorio. El número, en E.164. |
| `address` | Obligatorio. El host SIP o la dirección IP en la que tu operador recibe las llamadas, con un puerto opcional. |
| `transport` | `auto`, `udp`, `tcp` o `tls`. |
| `mediaEncryption` | `disabled`, `allowed` o `required`. |
| `username`, `password` | Las credenciales digest de tu troncal, si las usa. Se usan una vez, para conectar, y nunca se guardan. |
| `label` | Hasta 120 caracteres. |

### Chat web

Un canal `web` recibe toda su configuración de `widget`, en la que solo son obligatorios `title` y `allowedOrigins`, los orígenes exactos que pueden insertarlo (hasta 20, como `https://www.example.com`). `mode` es `chat` (una conversación), `form` (solo un formulario) o `form-chat` (el formulario y luego la conversación), con hasta 40 `fields` de formulario. `publicLink: true` también lo sirve en su propia página alojada. Los textos, los colores, las fuentes, los adjuntos, los mensajes de voz, los límites diarios y hasta 6 agentes más que un visitante puede elegir también forman parte de la configuración; consulta [la referencia](/api/raiz/channels/create/). Por defecto, el agente no usa sus herramientas de integración con visitantes anónimos (`allowBusinessTools`).

Créalo con `"inboundEnabled": false` para revisarlo antes de que los visitantes puedan llegar a él. Su `publication` dice si está `live`, la `url` de su página alojada y los `problems` que le impiden estar publicado: `CHANNEL_INACTIVE`, `PAUSED` (el tráfico entrante está desactivado), `AGENT_REQUIRED`, `AGENT_PAUSED` o `NOT_PLACED` (no tiene página alojada y ningún sitio https puede insertarlo).

## Asignar un agente y controlar el tráfico

[`raiz.channels.update`](/api/raiz/channels/update/) cambia un canal. Los campos que omites se quedan como están.

| Campo | Qué hace |
| --- | --- |
| `agentId` | El agente que responde aquí. `null` detiene la automatización entrante; un número de WhatsApp todavía puede enviar notificaciones salientes. |
| `inboundEnabled` | Responder las llamadas y los mensajes de las personas. Desactivado, el tráfico entrante se ignora y un widget web se apaga. |
| `outboundEnabled` | Permitir que tu organización inicie llamadas o conversaciones de WhatsApp desde este canal. |
| `aiCoveragePercent` | WhatsApp: la proporción de conversaciones entrantes nuevas, de 0 a 100, que se asigna a la IA. En `0`, las atiende tu equipo. Las conversaciones ya asignadas conservan su asignación. |
| `businessHours` | WhatsApp: cuándo atiende el número. Consulta [más abajo](#horario-de-atención-en-whatsapp). |
| `profile` | WhatsApp: el perfil de empresa que ven las personas: `about`, `address`, `description`, `email`, `vertical` y hasta dos `websites`. Léelo con `expand=profile` en [`raiz.channels.get`](/api/raiz/channels/get/). |
| `widget`, `widgetLogo` | Web: la configuración de widget nueva completa, y un logo (PNG, JPEG o WebP, hasta 256 KiB, codificado en base64; `null` lo quita). |
| `name`, `expectedVersion` | Un nombre para las personas, y la `version` que leíste. |

El tráfico entrante necesita un agente asignado, y también el tráfico saliente en los canales de teléfono y web; solo WhatsApp envía notificaciones salientes sin agente. Si no, la actualización responde `409 CHANNEL_AGENT_REQUIRED`. Un canal está `ready` cuando está activo y su tráfico está habilitado.

### Horario de atención en WhatsApp

`businessHours` dice cuándo atiende un número de WhatsApp, sea cual sea el agente que lo responde: hasta 28 `windows`, cada una con `days` (de `MO` a `SU`) y `from` y `to` en formato `HH:MM`, además de `closedDates`, como los festivos, y una `timeZone` (la de la organización cuando es `null`). Fuera de ese horario la IA no responde, y quien escribe recibe `outsideHoursMessage` una vez por cada periodo cerrado, o la plantilla aprobada de `outsideHoursTemplate`. `closingGraceMinutes` (15, 30, 60 o 120) sigue atendiendo una conversación en curso a la hora de cierre. `null` quita el horario, y el número atiende a toda hora.

## Estado

| `status` | Significado |
| --- | --- |
| `pending` | Un número de WhatsApp cuya configuración la empresa no ha terminado. |
| `active` | Conectado. |
| `degraded` | Conectado, pero la última verificación con el proveedor falló. `raiz.channels.verify` vuelve a verificar. |

[`raiz.channels.list`](/api/raiz/channels/list/) filtra los canales por `agentId`, `channelType` y `status`, del más reciente al más antiguo.

## Eliminar un canal

[`raiz.channels.delete`](/api/raiz/channels/delete/) elimina un canal, y sus conversaciones se conservan. Un número de teléfono deja de recibir y hacer llamadas, y un número de WhatsApp deja de enviarle mensajes a Raíz. Para detener un canal por un tiempo, desactiva su tráfico en su lugar. Eliminar es solo por REST; no se ofrece en MCP.

## Errores

| Estado | `code` | Significado |
| --- | --- | --- |
| `409` | `CHANNEL_AGENT_REQUIRED` | El tráfico entrante requiere un agente asignado; el saliente también, excepto en WhatsApp. |
| `409` | `CHANNEL_ENDPOINT_IN_USE` | Otro canal ya usa este número o endpoint. |
| `409` | `CHANNEL_TYPE_MISMATCH` | La operación o el campo no aplica al tipo de este canal. |
| `409` | `INVALID_STATE` | El canal no está en un estado que lo permita, como renovar la configuración de un canal que no está pendiente. |
| `422` | `CHANNEL_AGENT_MISMATCH` | Los números de teléfono necesitan un agente de voz; WhatsApp y el chat web, un agente de texto. |

Consulta los códigos de cada operación en la [referencia de Channels](/api/raiz/tags/channels/).

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