> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyreach.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Permissions and data access

> 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](/api-reference/authentication) for how tokens and scopes are issued, and [/organizations/roles-and-permissions](/organizations/roles-and-permissions) for how scopes map to roles.

## Scope tiers

| Scope                          | Grants                                                                                                                                    |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `conversations:read`           | 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`.

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

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

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

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

<Warning>
  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`.
</Warning>

## Write operations

`conversations:manage` is required for every state-changing conversation endpoint:

| Endpoint                                              | Action                                                                                       |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `POST /core/conversations`                            | Create a conversation. For telephone channels the call is enqueued via the campaign service. |
| `POST /core/conversations/{conversation_id}/messages` | Post a user message to a `text` conversation; the reply returns synchronously.               |
| `POST /core/conversations/{conversation_id}/end`      | End a `text` conversation (status becomes completed).                                        |
| `POST /core/conversations/import`                     | Bulk-import historical conversations.                                                        |

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

| Use case                                                    | Scope                           |
| ----------------------------------------------------------- | ------------------------------- |
| Dashboards and reporting that need only call metadata       | `conversations:read`            |
| Quality review, transcript export, recording playback       | `conversations:read_sensitive`  |
| Starting conversations, sending messages, importing history | `conversations:manage`          |
| Campaign-service dialing                                    | `conversations:dial` (internal) |

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    How tokens, scopes, and org headers work.
  </Card>

  <Card title="Roles and permissions" icon="user-shield" href="/organizations/roles-and-permissions">
    How scopes map to organization roles.
  </Card>
</CardGroup>