---
title: "Conversaciones"
description: "Cómo empieza, se responde, se le pasa a tu equipo y se cierra una conversación de Raíz, y cómo leer su transcripción, sus archivos, su análisis y sus hechos."
---

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

# Conversaciones

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

1. **Empieza.** Un contacto llama o escribe (`direction: inbound`), o tu organización se comunica con él (`outbound`), por ejemplo en una [campaña](/developers/raiz/campaigns/). `origin` dice cómo.
2. **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.
3. **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.
4. **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](/developers/raiz/contacts/) 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](/developers/raiz/data/#definiciones) 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`](/api/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.

```bash
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`](/api/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`](/api/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`](/api/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`.

```bash
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`](/api/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](/developers/raiz/data/#historial-de-cambios) registra quién la eliminó. Una abierta responde `409 CONVERSATION_OPEN`.

## Buscar y contar

[`raiz.conversations.list`](/api/raiz/conversations/list/) busca conversaciones, y [`raiz.conversations.count`](/api/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](/developers/raiz/contacts/#perfiles-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`.

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