Get messages in a conversation

GET

/api/conversations/{id}/messages

• Production

Returns the 50 most recent messages in the conversation, oldest first. Includes messages from all participants (customer, AI agent, human agent, system). For email conversations, the content contains the parsed email body.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string format: uuid

The unique identifier of the conversation.

Responses

200

Returns the 50 most recent messages in the conversation, oldest first.

Chronologically ordered list of messages in a conversation.

Array<object>

A single message in a conversation.

object

id

required

Unique identifier for the message.

string format: uuid

direction

required

Whether the message came from the customer (inbound) or was sent by oHallo (outbound).

string

Allowed values: inbound outbound

speaker

required

Who produced the message. On voice channels every message is inbound, so use this to distinguish the caller from the assistant.

string | null

Allowed values: caller ai tool human_operator system

body

required

The message text.

string

sentAt

required

When the message was sent.

string format: date-time

turnId

The conversation turn this message belongs to. Present when the message is part of a turn.

string format: uuid

fromAddress

Sender address, when the channel provides one.

string

channel

required

The channel the message arrived on or was sent through.

string

subject

Subject line, for channels that have one such as email.

string

404

No conversation exists with the given ID in the authenticated tenant. An API key restricted to a brand or workspace receives the same answer for a conversation in a workspace outside its restriction.

Standard error response returned by all endpoints on failure.

object

error

required

A human-readable error message describing what went wrong.

string

Example

Conversation not found

code

A machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.

string

Example

key_lock

missing_scopes

On a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.

Array<string>

Example

[
  "mcp:write"
]

entryId

On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.

string format: uuid

Example

11223344-5566-4788-99aa-bbccddeeff00

connectionId

On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.

string

undeclaredTools

On the same 422: the tool names the connection does not declare.

Array<string>

Example

[
  "get_orders"
]

declaredTools

On the same 422: the tools the connection declares.

Array<string>

Example

[
  "get_order",
  "search_orders"
]