Canales | Arbol AI Docs

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 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 antes de intentarlo de nuevo. Por 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.

Crea el canal. Empieza en pending, y la respuesta trae un enlace de configuración en setup.url, con su vencimiento en setup.expiresAt.

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"
  }'

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.
Verifica el canal. Una vez conectado el número, envía el channelId a 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 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. 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 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.
`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`.
`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 filtra los canales por agentId, channelType y status, del más reciente al más antiguo.

Eliminar un canal

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.