Conversations

Conversations are the calls and chats your agents have handled. Use these endpoints to pull call logs into your own CRM or analytics.

List conversations

Returns conversations across your agents, newest first, with cursor pagination.

GET /conversations

agentId

string

Filter to one agent. Use the agent’s providerAgentId (from List agents).

callSuccessful

string

Filter by outcome: success, failure, or unknown.

pageSize

number

default:"30"

Results per page, 1–100.

cursor

string

The nextCursor from a previous response, to fetch the next page.

curl "https://intent-weasel-655.eu-west-1.convex.site/api/v1/conversations?pageSize=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

data

array

Show conversation

conversationId

string

The conversation’s unique id.

agentId

string

The voice-provider agent id that handled it.

agentName

string | null

The agent’s name.

startTimeUnixSecs

number

Start time as a Unix timestamp (seconds).

callDurationSecs

number

Duration in seconds.

messageCount

number

Number of messages exchanged.

status

string

The conversation status.

callSuccessful

string

success, failure, or unknown.

callSummaryTitle

string | null

A short generated title.

mainLanguage

string | null

The primary language detected.

direction

string | null

inbound, outbound, or null.

rating

number | null

Rating, if any.

nextCursor

string | null

Pass back as cursor to get the next page.

hasMore

boolean

Whether more pages remain.

{
  "data": [
    {
      "conversationId": "conv_2601...",
      "agentId": "agent_7901...",
      "agentName": "Front desk",
      "startTimeUnixSecs": 1751880000,
      "callDurationSecs": 74,
      "messageCount": 12,
      "status": "done",
      "callSuccessful": "success",
      "callSummaryTitle": "Booked a cleaning",
      "mainLanguage": "en",
      "direction": "inbound",
      "rating": null
    }
  ],
  "nextCursor": "abc123",
  "hasMore": true
}

Keep following nextCursor until hasMore is false. A page can occasionally come back empty while hasMore is true — that’s expected; just request the next page.

Get a conversation

Returns one conversation with its full transcript and analysis.

GET /conversations/{id}

string

required

The conversation id.

string

The conversation id.

agentId

string

The voice-provider agent id.

agentName

string | null

The agent’s name.

status

string

The conversation status.

startTimeUnixSecs

number

Start time (Unix seconds).

callDurationSecs

number

Duration in seconds.

callCostUsd

number | null

Estimated cost of the call in US dollars.

callSuccessful

string

success, failure, or unknown.

summary

string | null

A summary of the conversation.

title

string | null

A short generated title.

mainLanguage

string | null

The primary language detected.

direction

string | null

inbound, outbound, or null.

phoneCall

object | null

Show properties

direction

string

inbound or outbound.

externalNumber

string

The other party’s number.

agentNumber

string

The agent’s number.

dynamicVariables

object

Variables passed into the agent at the start of the call.

dataCollection

array

Show item

name

string

The data point’s name.

value

string | null

The collected value.

transcript

array

Show turn

role

string

user, agent, or tool.

message

string | null

What was said.

timeInCallSecs

number

Seconds into the call.

curl https://intent-weasel-655.eu-west-1.convex.site/api/v1/conversations/conv_2601... \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "conv_2601...",
  "agentId": "agent_7901...",
  "agentName": "Front desk",
  "status": "done",
  "startTimeUnixSecs": 1751880000,
  "callDurationSecs": 74,
  "callCostUsd": 0.0084,
  "callSuccessful": "success",
  "summary": "Caller booked a cleaning for next Tuesday.",
  "title": "Booked a cleaning",
  "mainLanguage": "en",
  "direction": "inbound",
  "phoneCall": {
    "direction": "inbound",
    "externalNumber": "+15551234567",
    "agentNumber": "+12089745876"
  },
  "dynamicVariables": {},
  "dataCollection": [
    { "name": "appointment_type", "value": "cleaning" }
  ],
  "transcript": [
    { "role": "agent", "message": "Hi, thanks for calling Acme Dental!", "timeInCallSecs": 0 }
  ]
}

Getting started

Your brand

Clients

Building agents

Chat & embedding

Calendar

API

Billing your clients

Account & billing

List conversations

Get a conversation

​List conversations

​Get a conversation

List conversations

Get a conversation