Skip to content

Conversations & Transcripts ​

Read a conversation's full transcript over the management API — the same turns, tool activity and attachments your team sees in the Studio. Use it to build an admin transcript viewer, feed a QA pipeline, or archive conversations into your own system.

Every operation here needs an API key with the conversations:read scope.

OperationEndpoint
List conversationsGET /api/v1/conversations
Get one conversationGET /api/v1/conversations/{id}
Get its transcriptGET /api/v1/conversations/{id}/events

List and get conversations ​

GET /api/v1/conversations returns data: your 200 most recently active conversations, newest activity first, and has_more: true when older conversations exist beyond them. It takes no paging or filter parameters — for search, filters and page counts use Cases, and for voice calls use Calls.

Each conversation carries:

FieldMeaning
idConversation id — the one every other operation takes
customer_idThe customer it belongs to
workflow_idThe agent that handled it, when one did
statusactive, ended, resolved, escalated or abandoned
channel_startedThe channel it began on
channelsEvery channel it has used
summaryPresent once a summary has been written
created_at / updated_atTimestamps

GET /api/v1/conversations/{id} returns the same shape for one conversation, or 404 not_found.

Get a transcript ​

http
GET /api/v1/conversations/{id}/events
Authorization: Bearer sk_…

Events come back oldest-first. By default each one carries a compact, safe summary:

FieldMeaning
idEvent id
event_typeWhat happened — user_message, ai_response, tool_call, tool_result, file_upload, and more
actoruser, ai, human_agent or system
channelWhere the turn happened
created_atTimestamp
textMessage text, on message events
tool_name, tool_statusOn tool events

Asking for more detail ​

Richer payloads are opt-in, so the default response stays small and unchanged for anything you have already built. Pass include with a comma-separated list:

ValueAdds
tool_iotool_input and tool_output on tool events, plus error detail and latency
filesfile_name, mime_type, file_size and a short-lived signed file_url on file_upload events
structuredA structured WhatsApp message as readable words plus the typed object (see below)
deliveryDelivery facts on delivery events and on messages you sent through the API (see below)
http
GET /api/v1/conversations/{id}/events?include=tool_io,files

Attachment links are generated fresh each time you read and expire shortly after, so fetch a file when you need it rather than storing the link.

include=structured ​

Applies to a template, media or interactive WhatsApp message sent with POST /messages, and to an AI WhatsApp reply that is a message envelope such as {"type":"text","body":"…"}.

  • text becomes readable: the body plus the options for buttons, list and cta_url messages, or a label such as [template: order_update] or a media caption.
  • message carries the typed object. Its type is one of text, template, buttons, list, cta_url, image, video, audio, document, location or reaction.

Prose replies, customer messages and other channels are returned as written.

include=delivery ​

  • On delivery_status events: status (sent, delivered, read, failed or suppressed), message_id (the provider's id — the same one the message.status webhook carries) and error when it failed.
  • On a message you sent through the API: origin (public_api_outbound for a POST /messages or POST /outbound send), message_id (the provider's id) and outbound_message_id (the id returned by POST /messages).

Use these to match a send to its transcript event exactly.

tool_status describes the CALL, not the outcome

success means the tool was reached and returned. A tool that ran fine and answered "no such order" is still success. Read tool_output for what it actually said.

Paging ​

ParameterDefaultNotes
limit100Maximum 1000
after—ISO timestamp; returns events strictly after it
before—ISO timestamp; returns events strictly before it
event_type—Comma-separated filter, e.g. user_message,ai_response

The response carries has_more, and when more remain, next_after — pass that straight back as after to walk a long conversation page by page.

bash
curl -H "Authorization: Bearer sk_…" \
  "https://<your-workspace>-api.perfox.ai/api/v1/conversations/$ID/events?limit=200&include=tool_io"

While a person holds a call and the AI is muted, any turn the muted AI produced is left out of the transcript — the customer never heard it.

If your workspace has PII redaction switched on, tool output was already redacted before it was stored, so what you receive is the redacted form.