Conversations | Arbol AI Docs

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

It starts. A contact calls or writes (direction: inbound), or your organization reaches out (outbound), for example in a campaign. origin says how.
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.
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.
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 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 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 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.

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

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 deletes a closed conversation: it leaves every list and report, its transcript and facts are kept, and the change history records who deleted it. An open one answers 409 CONVERSATION_OPEN.

Find and count

raiz.conversations.list finds conversations, and 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.
`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.