---
title: "Conversations"
description: "How a Raíz conversation starts, is answered, handed to your team and closed, and how to read its transcript, media, analysis and facts."
---

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

# Conversations

A conversation is one exchange with a contact on one channel: a phone call, a WhatsApp chat or a web chat. Raíz keeps all of it: who started it, who answered (the agent, your team or both), every message, the call's recording when there is one, a title and a summary, whether the patient's request was resolved, and the data the agent captured. Your team reads conversations to follow up; your systems read them to act on what patients asked for.

## How a conversation goes

1. **It starts.** A contact calls or writes (`direction: inbound`), or your organization reaches out (`outbound`), for example in a [campaign](/en/developers/raiz/campaigns/). `origin` says how.
2. **It's answered.** The channel's agent answers. On WhatsApp, the agent may hand the conversation to your team, and people may take over; `workers` lists each agent and the team, in the order they first wrote, and who answers now.
3. **It closes.** A call closes when it ends. A text conversation closes after the agent's `settings.sessionCloseAfterMinutes` without messages, or when someone closes it.
4. **It's analyzed.** Closing starts the conversation's analysis, which judges whether the contact's request was resolved (`outcome`). `analyzedAt` says when it finished.

## What a conversation holds

| Field | What it says |
| --- | --- |
| `channelType`, `channelId` | Where it happened: `voice`, `whatsapp` or `web`. |
| `direction`, `origin` | Who started it. `origin` is `inbound` (the contact), `manual` (a person of your organization, in the Dashboard or the WhatsApp Business app), `api` (a client, through the API), `campaign`, `import` or `test` (a WhatsApp agent trial). |
| `status`, `closeReason` | `open` or `closed`, and why it closed: `completed`, `inactivity`, `handoff`, `migration`, `error` or `manual`. |
| `contactId`, `subjectContactId` | The [contact](/en/developers/raiz/contacts/) on the other side, and the one it's about when that's someone else, such as a patient a relative calls for. |
| `agentId`, `workers` | The agent assigned now, and everyone who works it, with how many messages each wrote and who is `answering`. |
| `title`, `summary` | Generated, unless a person wrote them; `titleAuthor` and `summaryAuthor` say who. A person's title or summary is never replaced. |
| `outcome`, `sentiment` | `success`, `failure` or `unknown`; `positive`, `neutral` or `negative`. |
| `facts` | The current value of each [definition](/en/developers/raiz/data/#definitions) for this conversation, such as an assessment: a judgement about the conversation, like a yes/no check. |
| `metadata` | Your own keys and values: up to 50 keys of up to 40 characters, values up to 500. Raíz never interprets them. |
| `durationSeconds`, `recordingAvailable` | For calls. |

## Messages and media

[`raiz.conversations.get`](/api/raiz/conversations/get/) with `expand=messages` adds the transcript, oldest first, up to 100 messages a page (`messagesLimit`; `messagesCursor` for the next). Each message has a `role` (`contact`, `agent`, `operator` for a person of your organization, or `system`), its plain text in `content`, and its `parts`:

| Part `type` | What it holds |
| --- | --- |
| `text` | Text. On calls, each turn, with `interrupted` when the speaker was cut off. |
| `file` | An image, video, audio, voice note, document, sticker or recording, with a short-lived `url` (until `urlExpiresAt`; read the conversation again for a fresh one) and, for audio and voice notes, a `transcript`. |
| `tool` | A tool the agent called, with its input, its output and its `status`. |
| `template` | A WhatsApp template message, with its `name` and `language`. |
| `location`, `contact_card`, `actions`, `action_reply`, `reaction`, `event`, `email`, `unsupported` | Other content the channel carried. |

Agent and operator messages carry a `deliveryStatus` on channels that report it: `sending`, `uncertain`, `sent`, `delivered`, `read`, `played` or `failed`. `expand=recording` adds a link to a call's recording; anyone who holds the link can play it until `expiresAt`, so treat it like the recording itself.

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

## Handoffs to your team

On WhatsApp, the agent hands a conversation to your team when it can't resolve a request, when the contact asks for a person, or when its monthly budget is spent. Automatic replies then stay paused for that contact (`aiPaused`, with `aiPausedBy: agent`) until a person resumes them or the conversation closes, and `handling=escalated` finds these conversations. On an open WhatsApp conversation, [`raiz.conversations.update`](/api/raiz/conversations/update/) controls the AI:

- `aiEnabled` turns the AI on or off for this conversation only.
- `aiPaused` pauses or resumes automatic replies for this contact until their open conversation closes.

Turning the AI on or resuming it answers what the contact wrote after the last real answer. To hand a conversation back with context, [`raiz.conversations.continue`](/api/raiz/conversations/continue/) takes an optional `note` for the agent, which the contact never sees, and the agent continues the pending request at once. It works once per handoff, only while WhatsApp's 24-hour window is open (`409 WHATSAPP_WINDOW_CLOSED` otherwise), and only over REST.

## Close and delete

[`raiz.conversations.update`](/api/raiz/conversations/update/) with `"status": "closed"` closes a conversation (`closeReason: manual`) and starts its analysis; a closed conversation stays closed. The same operation sets your own `title` or `summary` (`null` clears it and keeps it clear), sets `metadata`, and moves the conversation to another `contactId` or `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" }
  }'
```

A call closes by itself when it ends (`409 CALL_IN_PROGRESS`), and a web chat can't close while the agent is replying (`409 REPLY_IN_PROGRESS`: try again shortly). [`raiz.conversations.delete`](/api/raiz/conversations/delete/) deletes a closed conversation: it leaves every list and report, its transcript and facts are kept, and the [change history](/en/developers/raiz/data/#change-history) records who deleted it. An open one answers `409 CONVERSATION_OPEN`.

## Find and count

[`raiz.conversations.list`](/api/raiz/conversations/list/) finds conversations, and [`raiz.conversations.count`](/api/raiz/conversations/count/) counts the same matches up to 10,000 (`capped` is `true` when there are at least that many). Each item already carries its title, summary, outcome and sentiment. Both take these filters:

| Filter | Matches |
| --- | --- |
| `contactId` | Conversations with this contact as the counterpart or the subject. |
| `agentId`, `channelId`, `campaignId`, `profileId` | The agent, the channel, the campaign or the [contact profile](/en/developers/raiz/contacts/#contact-profiles). |
| `channelType`, `origin`, `outcome` | One or more values, comma-separated. |
| `status`, `conversationDirection` | `open` or `closed`; `inbound` or `outbound`. |
| `handling` | `ai` (the AI takes part), `team` (on WhatsApp, only your people) or `escalated` (the AI handed it to the team). |
| `worker` | Who answers it now: `ai` or `team`. |
| `startedAfter`, `startedBefore` | The start time, in RFC 3339. |
| `q` | Names, phones, emails, identity documents, message text, titles and summaries, ignoring accents and case. |

`sort` is `started` (newest first, the default), `last_message` (latest activity first) or `changed`: a feed of status, outcome and analysis changes, oldest first, that a system polls from the last `pageInfo.nextCursor` it saved. A deleted conversation appears in that feed once, with `deletedAt`.

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