Skip to main content
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.

​
Scope tiers

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.

​
Safe columns

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.
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.

​
Sensitive fields

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.

​
Write operations

conversations:manage is required for every state-changing conversation endpoint: The messages and end endpoints are valid only for text conversations and on conversations that are still active; other states return 409.

​
Internal dial scope

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.

​
System Metadata in the dashboard

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.

​
Choosing a scope

Authentication

How tokens, scopes, and org headers work.

Roles and permissions

How scopes map to organization roles.