How conversation scopes control who sees transcripts and recordings.
Conversation endpoints are gated by four scope tiers. The scope on your token decides which columns the API returns: a read-only token sees only safe metadata, while a sensitive-read token additionally unlocks transcripts, summaries, recordings, and metadata. This page describes each tier and the exact field set behind it.The conversation routes live under the /core prefix. See /api-reference/authentication for how tokens and scopes are issued, and /organizations/roles-and-permissions for how scopes map to roles.
List and read conversations, restricted to safe columns only.
conversations:read_sensitive
Everything in read, plus transcript, summary, recording, and metadata fields.
conversations:manage
Create conversations, post text messages, end text conversations, and import historical conversations. Also satisfies the read endpoints.
conversations:dial
Internal only. Directly places a call via POST /core/conversations/dial. Granted exclusively to the campaign service.
GET /core/conversations and GET /core/conversations/{conversation_id} accept any of conversations:read, conversations:read_sensitive, or conversations:manage. The data they return still depends on whether the token carries conversations:read_sensitive.
A token with conversations:read (but not conversations:read_sensitive) receives only this set of columns on both the list and detail endpoints. Transcript, summary, recording, and metadata fields are never returned.
Field
Description
id
Conversation identifier.
organization_id
Owning organization.
direction
Inbound or outbound.
user_id
Associated user, if any.
agent_number
Agent phone number.
agent_id
Agent identifier.
agent_version_id
Agent version identifier.
web_widget_id
Web widget identifier, for chat conversations.
trunk_id
Telephony trunk identifier.
channel
Conversation channel (for example text).
duration
Conversation duration.
user_turn_count
Number of user turns.
status
Conversation status.
service_version
Service version that handled the conversation.
created_at
Creation timestamp.
updated_at
Last update timestamp.
The columns query parameter on the list endpoint lets you request a subset of fields. Without conversations:read_sensitive, requested columns are intersected with the safe set, so any sensitive columns you ask for are silently dropped.
A token with conversations:read_sensitive receives the full record on both list and detail. This unlocks the fields excluded from the safe set, including:
transcript
summary
recording
custom_metadata
system_metadata
If you need transcripts, recordings, or call metadata, the token must carry conversations:read_sensitive. A token with only conversations:read will return conversations with these fields absent.
A read-only token sees no transcripts by design. If your integration returns conversations with no transcript, summary, or recording, check that the token has conversations:read_sensitive and not just conversations:read.
POST /core/conversations/dial places a call immediately via telephony rather than enqueuing it, and requires conversations:dial. This scope is intended only for the campaign service M2M application. External callers should use POST /core/conversations to enqueue instead.
In the conversation detail page, the System Metadata panel is gated separately by the advanced_user scope. Operators without advanced_user do not see the system metadata panel even when viewing a conversation, while the rest of the detail view (transcript, summary, recording, custom metadata) follows the read scopes above.
