Conversaciones | Arbol AI Docs

Una conversación es un intercambio con un contacto en un canal: una llamada telefónica, un chat de WhatsApp o un chat web. Raíz la guarda completa: quién la inició, quién respondió (el agente, tu equipo o ambos), cada mensaje, la grabación de la llamada cuando la hay, un título y un resumen, si se resolvió la solicitud del paciente y los datos que capturó el agente. Tu equipo lee las conversaciones para hacer seguimiento; tus sistemas las leen para actuar sobre lo que pidieron los pacientes.

Cómo transcurre una conversación

Empieza. Un contacto llama o escribe (direction: inbound), o tu organización se comunica con él (outbound), por ejemplo en una campaña. origin dice cómo.
Se responde. Responde el agente del canal. En WhatsApp, el agente puede pasarle la conversación a tu equipo, y las personas pueden tomarla; workers lista cada agente y el equipo, en el orden en que escribieron por primera vez, y quién responde ahora.
Se cierra. Una llamada se cierra cuando termina. Una conversación de texto se cierra después de settings.sessionCloseAfterMinutes del agente sin mensajes, o cuando alguien la cierra.
Se analiza. El cierre inicia el análisis de la conversación, que juzga si se resolvió la solicitud del contacto (outcome). analyzedAt dice cuándo terminó.

Qué contiene una conversación

Campo	Qué dice
`channelType`, `channelId`	Dónde ocurrió: `voice`, `whatsapp` o `web`.
`direction`, `origin`	Quién la inició. `origin` es `inbound` (el contacto), `manual` (una persona de tu organización, en la app de Raíz o en la app WhatsApp Business), `api` (un cliente, a través de la API), `campaign`, `import` o `test` (una prueba de un agente de WhatsApp).
`status`, `closeReason`	`open` o `closed`, y por qué se cerró: `completed`, `inactivity`, `handoff`, `migration`, `error` o `manual`.
`contactId`, `subjectContactId`	El contacto del otro lado, y aquel sobre quien trata cuando es otra persona, como un paciente por el que llama un familiar.
`agentId`, `workers`	El agente asignado ahora, y todos los que la atienden, con cuántos mensajes escribió cada uno y quién está respondiendo (`answering`).
`title`, `summary`	Generados, a menos que los haya escrito una persona; `titleAuthor` y `summaryAuthor` dicen quién. Un título o un resumen escrito por una persona nunca se reemplaza.
`outcome`, `sentiment`	`success`, `failure` o `unknown`; `positive`, `neutral` o `negative`.
`facts`	El valor actual de cada definición para esta conversación, como una evaluación (assessment): un juicio sobre la conversación, como una verificación de sí o no.
`metadata`	Tus propias claves y valores: hasta 50 claves de hasta 40 caracteres, con valores de hasta 500. Raíz nunca los interpreta.
`durationSeconds`, `recordingAvailable`	Para las llamadas.

Mensajes y archivos

raiz.conversations.get con expand=messages agrega la transcripción, del mensaje más antiguo al más reciente, hasta 100 mensajes por página (messagesLimit; messagesCursor para la siguiente). Cada mensaje tiene un role (contact, agent, operator para una persona de tu organización, o system), su texto plano en content y sus parts:

`type` de la parte	Qué contiene
`text`	Texto. En las llamadas, cada turno, con `interrupted` cuando a quien hablaba lo interrumpieron.
`file`	Una imagen, un video, un audio, una nota de voz, un documento, un sticker o una grabación, con una `url` de corta duración (hasta `urlExpiresAt`; vuelve a leer la conversación para obtener una nueva) y, para los audios y las notas de voz, una `transcript`.
`tool`	Una herramienta que llamó el agente, con su entrada, su salida y su `status`.
`template`	Un mensaje de plantilla de WhatsApp, con su `name` y su `language`.
`location`, `contact_card`, `actions`, `action_reply`, `reaction`, `event`, `email`, `unsupported`	Otro contenido que llevó el canal.

Los mensajes del agente y de los operadores llevan un deliveryStatus en los canales que lo informan: sending, uncertain, sent, delivered, read, played o failed. expand=recording agrega un enlace a la grabación de una llamada; cualquiera que tenga el enlace puede reproducirla hasta expiresAt, así que trátalo como la grabación misma.

curl "https://api.getarbol.com/v1/raiz/conversations/cnv_01jd8x8d5e6f7g8h9j0k1m2n3p?expand=messages" \
  --header "Authorization: Bearer $ARBOL_API_KEY"

Traspasos a tu equipo

En WhatsApp, el agente le pasa una conversación a tu equipo cuando no puede resolver una solicitud, cuando el contacto pide hablar con una persona o cuando se agota su presupuesto mensual. Las respuestas automáticas quedan entonces en pausa para ese contacto (aiPaused, con aiPausedBy: agent) hasta que una persona las reanuda o la conversación se cierra, y handling=escalated encuentra estas conversaciones. En una conversación de WhatsApp abierta, raiz.conversations.update controla la IA:

aiEnabled activa o desactiva la IA solo para esta conversación.
aiPaused pausa o reanuda las respuestas automáticas para este contacto hasta que se cierre su conversación abierta.

Al activar la IA o reanudarla, responde lo que el contacto escribió después de la última respuesta real. Para devolverle una conversación al agente con contexto, raiz.conversations.continue recibe una note opcional para el agente, que el contacto nunca ve, y el agente continúa de inmediato con la solicitud pendiente. Funciona una vez por traspaso, solo mientras la ventana de 24 horas de WhatsApp esté abierta (si no, 409 WHATSAPP_WINDOW_CLOSED), y solo por REST.

Cerrar y eliminar

raiz.conversations.update con "status": "closed" cierra una conversación (closeReason: manual) e inicia su análisis; una conversación cerrada se queda cerrada. La misma operación pone tu propio title o summary (null lo borra y lo mantiene vacío), establece metadata y mueve la conversación a otro contactId o subjectContactId.

curl https://api.getarbol.com/v1/raiz/conversations/cnv_01jd8x8d5e6f7g8h9j0k1m2n3p \
  --request PATCH \
  --header "Authorization: Bearer $ARBOL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "status": "closed",
    "metadata": { "ticket": "EXAMPLE-1042" }
  }'

Una llamada se cierra sola cuando termina (409 CALL_IN_PROGRESS), y un chat web no se puede cerrar mientras el agente está respondiendo (409 REPLY_IN_PROGRESS: vuelve a intentarlo en un momento). raiz.conversations.delete elimina una conversación cerrada: sale de todas las listas y reportes, su transcripción y sus hechos se conservan, y el historial de cambios registra quién la eliminó. Una abierta responde 409 CONVERSATION_OPEN.

Buscar y contar

raiz.conversations.list busca conversaciones, y raiz.conversations.count cuenta las mismas coincidencias hasta 10.000 (capped es true cuando hay al menos esa cantidad). Cada elemento ya lleva su título, su resumen, su resultado y su sentimiento. Ambas reciben estos filtros:

Filtro	Encuentra
`contactId`	Conversaciones con este contacto como interlocutor o como sujeto.
`agentId`, `channelId`, `campaignId`, `profileId`	El agente, el canal, la campaña o el perfil de contacto.
`channelType`, `origin`, `outcome`	Uno o más valores, separados por comas.
`status`, `conversationDirection`	`open` o `closed`; `inbound` u `outbound`.
`handling`	`ai` (la IA participa), `team` (en WhatsApp, solo tus personas) o `escalated` (la IA se la pasó al equipo).
`worker`	Quién la responde ahora: `ai` o `team`.
`startedAfter`, `startedBefore`	La hora de inicio, en RFC 3339.
`q`	Nombres, teléfonos, correos, documentos de identidad, texto de los mensajes, títulos y resúmenes, sin distinguir tildes ni mayúsculas.

sort es started (las más recientes primero, el valor por defecto), last_message (la actividad más reciente primero) o changed: un flujo de cambios de estado, resultado y análisis, de los más antiguos a los más recientes, que un sistema consulta desde el último pageInfo.nextCursor que guardó. Una conversación eliminada aparece una vez en ese flujo, con deletedAt.