Get a conversation

Read one conversation with its contact, Agent and channel, who works it (workers: each Agent and the team, and who answers now), title, summary, outcome, sentiment and current facts. Add expand=messages for the transcript, oldest first, each message with its author, the Agent's tool calls and quoted replies (continue with messagesCursor), and expand=recording for a short-lived link to the call recording.

Scopes: any one of raiz:conversations:read, raiz:conversations:write
Credentials: an API key, a client-credentials token or a person's access token
Effect: read-only; safe to retry
Limits: response up to 1 MB
CLI: arbol raiz conversations get · MCP tool: raiz_conversations_get

GET

https://api.getarbol.com/v1/raiz/conversations/{conversationId}

Authorization

Authorization
string
required
Bearer <token>, where the token is an API key, a client-credentials token or a person's access token with any one of the scopes raiz:conversations:read, raiz:conversations:write. Get an API key.

Path parameters

conversationId
string
required
Conversation id.

pattern: ^cnv_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$

Query parameters

expand
optional
string
Related data to include, comma-separated: messages, recording, diagnostics.

pattern: ^(messages|recording|diagnostics)(,(messages|recording|diagnostics))*$
messagesCursor
optional
string
Opaque cursor the messages expansion's pageInfo returned; omit it for its first page.

maxLength: 4096
messagesDirection
optional
forward
or
backward
Direction to traverse the messages expansion from the supplied cursor.

default: "forward"
messagesLimit
optional
integer
Maximum messages items in one page. Defaults to 100.

maximum: 100 · minimum: 1 · default: 100

Returns

200

Successful operation.

JSON

success
boolean
required
data
object
required
- agentId
  string | null
  required
  Agent id.
  
  pattern: ^agt_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
- agentName
  string | null
  required
- agentReplied
  boolean
  required
  The Agent said something to the contact.
- aiCoveragePercent
  integer
  required
  maximum: 100 · minimum: 0
- aiEnabled
  boolean
  required
  AI assignment for this episode. Manual changes affect only this conversation; recipient pauses still apply.
- aiPaused
  boolean
  required
  WhatsApp automatic replies are paused for this recipient. A pause ends when their open conversation closes, so the next one starts with the AI; a closed conversation keeps the state it ended with.
- aiPausedBy
  agent
  or
  operator
  or
  null
  required
  Who paused automatic replies for the recipient: the Agent, handing the conversation to a person, or an operator (a person of the organization who wrote to the contact or paused the AI). Null when not paused or unknown.
- analyzedAt
  string | null
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
- campaignId
  string | null
  required
  Campaign of a campaign attempt.
  
  pattern: ^cmp_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
- campaignRecipientId
  string | null
  required
  Campaign recipient of a campaign attempt.
  
  pattern: ^rcp_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
- channelAddress
  string | null
  required
  The organization's side: its number or URL.
- channelId
  string | null
  required
  Channel id.
  
  pattern: ^(?:chn_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))|(?:agc)_(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
- channelName
  string | null
  required
- channelType
  voice
  or
  whatsapp
  or
  web
  required
- closeReason
  completed
  or
  inactivity
  or
  handoff
  or
  migration
  or
  error
  or
  manual
  +1 more
  required
- contactId
  string | null
  required
  Contact id.
  
  pattern: ^cnt_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
- contactName
  string | null
  required
- contactProfileName
  string | null
  required
  The name the contact shows on WhatsApp (their profile name), as WhatsApp shares it; unverified. contactName is the contact's own name.
- counterpartAddress
  string | null
  required
  The contact's side: their number or address.
- createdAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
- deletedAt
  string | null
  required
  When the conversation was deleted. Only the changed feed (listConversations?sort=changed) lists deleted conversations, once, as tombstones; everywhere else this is null.
  
  format: date-time
- direction
  inbound
  or
  outbound
  required
- durationSeconds
  integer | null
  required
  minimum: 0
- endedAt
  string | null
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
- id
  string
  required
  Conversation id.
  
  pattern: ^cnv_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
- language
  string | null
  required
- lastMessageAt
  string | null
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
- messageCount
  integer
  required
  minimum: 0
- metadata
  object
  required
  Your own keys and labels for this resource (up to 50 keys of 40 characters; values up to 500 characters). Raíz never interprets them.
- operatorReplied
  boolean
  required
  A person of the organization wrote to the contact, in Raíz or in the WhatsApp Business app.
- origin
  inbound
  or
  manual
  or
  api
  or
  campaign
  or
  import
  or
  test
  required
  How it started: the contact reached out (inbound), a person of the organization started it (manual: in the Dashboard, or on WhatsApp in the WhatsApp Business app), a client through the API (api), a campaign, an import or a person-owned WhatsApp Agent trial (test).
- outcome
  success
  or
  failure
  or
  unknown
  or
  null
  required
- profileId
  string | null
  required
  The communication profile it was started from.
  
  pattern: ^prf_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
- recordingAvailable
  boolean
  required
- requestedBy
  string | null
  required
  Who started it with createConversation: the token's subject, a person's user id or <client id>@clients for a machine client. Null for inbound, campaign and imported conversations.
- sentiment
  positive
  or
  neutral
  or
  negative
  or
  null
  required
- startedAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
- status
  open
  or
  closed
  required
- subjectContactId
  string | null
  required
  The contact the conversation is about when it is not the counterpart (a patient a relative calls for).
  
  pattern: ^cnt_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
- summary
  string | null
  required
- summaryAuthor
  person
  or
  ai
  or
  system
  or
  import
  or
  provider
  or
  null
  required
  Who wrote the value.
- title
  string | null
  required
  The stored intent title, or null while there is insufficient context or generation is pending. Clients can show a localized placeholder from status and messageCount. A person's title is never replaced automatically.
- titleAuthor
  person
  or
  ai
  or
  system
  or
  import
  or
  provider
  or
  null
  required
  Who wrote the value.
- updatedAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
- version
  integer
  required
  minimum: 1
- workers
  array of
  required
  Who works the conversation for the organization, in the order each first wrote something the contact saw (those who have not yet, last): each Agent and the team that wrote in it and, while it is open or when nobody answered it, whoever has it (the assigned Agent while the AI handles it, the team otherwise). agentId is the Agent assigned now.
  
  One of the following:
  object
  object
- toolCalls
  object
  required
  count
  integer
  required
  The Agent's tool calls in the conversation.
  
  minimum: 0
  failed
  integer
  required
  How many of them failed.
  
  minimum: 0
  lastFailure
  required
  One of the following:
  RaizConversationToolFailure
  errorCode
  string | null
  required
  errorMessage
  string | null
  required
  What the tool answered when it failed, up to 500 characters; the transcript has all of it.
  
  toolName
  string
  required
  null
- analysisErrorCode
  string | null
  required
  The stable code of the latest failed analysis attempt; null before a failure or after a successful analysis. A failed attempt may be retried automatically.
- facts
  array of
  object
  required
  The current value of each definition for this subject (the newest assertion that was not rejected).
  
  author
  person
  or
  ai
  or
  system
  or
  import
  or
  provider
  required
  Who wrote the value.
  
  confidence
  number | null
  required
  How sure the AI was, from 0 to 1. Null for people.
  
  maximum: 1 · minimum: 0
  contactId
  string | null
  required
  The contact the fact is about, for contact facts.
  
  pattern: ^cnt_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  conversationId
  string | null
  required
  The conversation the fact is about, for conversation facts.
  
  pattern: ^cnv_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  createdAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  definition
  object
  required
  id
  string
  required
  Definition id.
  
  pattern: ^def_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  key
  string
  required
  kind
  attribute
  or
  assessment
  or
  category
  or
  metric
  required
  What the definition captures: an attribute (a datum), an assessment (a yes/no check of the conversation), a category (a classification such as the reason for contact) or a metric.
  
  name
  string
  required
  valueType
  text
  or
  number
  or
  boolean
  or
  date
  or
  option
  required
  id
  string
  required
  Fact id.
  
  pattern: ^fct_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  observedAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  optionLabel
  string | null
  required
  The option's label, for option facts.
  
  reviewStatus
  unreviewed
  or
  confirmed
  or
  rejected
  required
  value
  required
  A string (text), number, boolean, ISO date YYYY-MM-DD (date) or option key (option), per the definition's value type.
  
  One of the following:
  string
  number
  boolean
  null
  valueStatus
  known
  or
  unknown
  or
  not_applicable
  required
- messages
  optional
  object
  The transcript, oldest first, with tool calls and quoted replies. Present only when expanded.
  
  data
  array of
  object
  required
  Items admitted by this resource contract within the verified organization.
  
  agentId
  string | null
  required
  The Agent that wrote an Agent message. Null for every other role.
  
  pattern: ^agt_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  content
  string
  required
  The plain text of the parts.
  
  createdAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  deliveredAt
  string | null
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  deliveryErrorCode
  string | null
  required
  deliveryStatus
  sending
  or
  uncertain
  or
  sent
  or
  delivered
  or
  read
  or
  played
  +2 more
  required
  Delivery of an Agent or operator message on channels that report it; it only moves forward. uncertain: the provider did not confirm, and Raíz asks it again.
  
  generation
  object | null
  required
  How the AI produced an Agent message.
  
  firstTokenMs
  number | null
  required
  inputCachedTokens
  number | null
  required
  inputTokens
  number | null
  required
  model
  arbolito/agile
  or
  arbolito/balanced
  or
  arbolito/advanced
  or
  arbolito/top
  or
  null
  required
  The tier that wrote the message.
  
  modelCalls
  number | null
  required
  outputTokens
  number | null
  required
  reasoningTokens
  number | null
  required
  responseMs
  number | null
  required
  speechToTextMs
  number | null
  required
  textToSpeechMs
  number | null
  required
  id
  string
  required
  Message id.
  
  pattern: ^msg_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  memberId
  string | null
  required
  The person of the organization who wrote an operator message in Raíz: their member id, as Arbol Account lists it (account.members.list). Null when Raíz does not know who wrote it (the WhatsApp Business app, a machine client) and for every other role.
  
  maxLength: 255 · minLength: 1
  occurredAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  origin
  business_app
  or
  null
  required
  
  business_app: Where an operator message was written: business_app is the WhatsApp Business app (the phone app or WhatsApp Web) on a number Raíz shares. Null for messages written in Raíz and for every other role.
  
  parts
  array of
  required
  One of the following:
  object
  object
  object
  object
  object
  object
  object
  object
  object
  object
  object
  object
  position
  integer
  required
  Order in the transcript, from 0.
  
  minimum: 0
  readAt
  string | null
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  replyTo
  object | null
  required
  The message this one quotes.
  
  content
  string | null
  required
  Up to 280 characters.
  
  messageId
  string
  required
  Message id.
  
  pattern: ^msg_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  role
  string | null
  required
  role
  contact
  or
  agent
  or
  operator
  or
  system
  required
  object
  string
  required
  Discriminator for a resource list response.
  
  pageInfo
  object
  required
  Opaque navigation cursors for this page’s stable keyset order.
  
  hasNextPage
  boolean
  required
  Whether a later page exists in the current ordering.
  
  hasPreviousPage
  boolean
  required
  Whether an earlier page exists in the current ordering.
  
  nextCursor
  string | null
  required
  Opaque cursor for the next page, or null when there is none.
  
  previousCursor
  string | null
  required
  Opaque cursor for the previous page, or null when there is none.
- recording
  optional
  One of the following:
  RaizSignedUrl
  url
  string
  required
  The signed URL. Anyone holding it has access until it expires.
  
  format: uri · maxLength: 2048 · pattern: ^https://
  expiresAt
  string
  required
  When the URL stops working.
  
  format: date-time
  null
}
error
null
required
metadata
object
required
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

400

INVALID_INPUT: The request does not match the published schema.
INVALID_CURSOR: The cursor is malformed or belongs to a different list.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

401

UNAUTHORIZED: A valid access token is required.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

403

FORBIDDEN: The token does not authorize this operation.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

404

NOT_FOUND: The requested operation does not exist.
RESOURCE_NOT_FOUND: The requested resource does not exist in this organization.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

405

HTTP_METHOD_NOT_ALLOWED: The HTTP method is not supported for this resource.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

413

REQUEST_TOO_LARGE: The request exceeds the allowed size.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

415

UNSUPPORTED_MEDIA_TYPE: The request content type is not supported.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

429

RATE_LIMITED: The request rate limit was exceeded. Try again later.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

500

INTERNAL_ERROR: The service could not complete the operation.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

502

OUTCOME_UNKNOWN: The operation may have been applied; check its result before repeating it.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

503

UPSTREAM_UNAVAILABLE: The upstream service could not complete the request.
INTEGRATIONS_UNAVAILABLE: The organization's integrations cannot be read right now. Try again shortly.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

504

UPSTREAM_TIMEOUT: The upstream service did not respond before its deadline.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}