> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/developer-guide/platform-api/conversations/operators.md).

# Operators

Human-in-the-loop call monitoring, takeover, escalation management, and operator analytics.

Operators are human agents who can monitor, join, and take over live voice calls. The operator system provides escalation management, live call monitoring, and operator-action audit records built on the platform's [world model](https://docs.concurrence.com/developer-guide/platform-api/data-world-model.md). Operators can also take over live text conversations through the [Runs API](https://docs.concurrence.com/developer-guide/platform-api/conversations/runs.md#operator-takeover).

{% hint style="warning" %}
**Beta.** Operators is a beta feature. A workspace must be enabled for it before it can call the operations on this page or the run takeover operations on [Runs](https://docs.concurrence.com/developer-guide/platform-api/conversations/runs.md#operator-takeover). Any other workspace gets `403` with the message `Operators is a beta feature that is not enabled for this workspace`. Ask your Concurrence representative to enable it.
{% endhint %}

{% hint style="info" %}
**Custom operator interfaces.** Use these APIs to build the screens an operator works in. [Build Your Own Operator Console](https://docs.concurrence.com/developer-guide/guides/build-an-operator-console.md) walks through one end to end. This page documents the operator-scoped endpoints (`/operators/{operator_id}/...`). The [Runs API](https://docs.concurrence.com/developer-guide/platform-api/conversations/runs.md#operator-takeover) addresses controls by channel-neutral `run_id`. Both paths act on supported underlying sessions. Confirm runtime support and operator access before implementing your own intervention interface. A route in the public schema does not establish support on every voice provider.
{% endhint %}

<figure><img src="https://1651797362-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2YwM0LHtEGLt9S21OyC3%2Fuploads%2Fgit-blob-056076cb328ae2291818f0855a842a6815508a42%2Foperator-console-architecture.svg?alt=media" alt="Your operator console has two parts: the operator&#x27;s browser and a server you run. The server receives the operator&#x27;s token from the Identity API and calls the Platform API over REST for runs, operators, and real-time events. The Platform API enforces permission, eligibility, and audit and controls the agent runtime. On voice, the platform dials the operator&#x27;s phone into the call."><figcaption><p>You build the operator console: a browser screen and the server behind it. The platform enforces permission, eligibility, and audit, runs the conversation, and dials the operator's phone on voice calls. Your console carries no audio.</p></figcaption></figure>

## Operator Lifecycle

<figure><img src="https://1651797362-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2YwM0LHtEGLt9S21OyC3%2Fuploads%2Fgit-blob-a037e3f04d855e4fedecd6142f200377079cb750%2Foperator-takeover.svg?alt=media" alt="On supported phone runtimes an operator can listen, take over while the agent pauses, and return control so the agent can resume with captured handback context."><figcaption><p>Operators join by phone on supported runtimes. The API controls listening, takeover, and handback.</p></figcaption></figure>

* **Listen mode**: the operator monitors the call silently. The AI agent continues handling the conversation. The operator is muted at the telephony level.
* **Takeover mode**: the AI agent's audio output is muted (speaker suppressed) and the operator speaks directly with the caller. Agent speech and turn processing are suspended while the operator drives. When the operator leaves the call from takeover, the agent resumes in the same session with what was said during the takeover, the caller's and the operator's turns, as context for its next reply. Switching back to listen also resumes the agent without re-initializing the session. Control and telephony propagation can add delay.

**Mode switching**: toggling between listen and takeover requests changes to the telephony mute state and agent speaker mute without recreating the underlying session. The change takes effect after the relevant control and telephony updates propagate. During takeover, the caller's speech and the operator's, which comes through a dedicated per-participant transcription stream, are captured for the handback when transcription succeeds.

## Connection Methods

Voice operators join by phone. The platform dials the phone number in the operator profile and adds the answered leg to the existing conference. Registering or updating an operator with a number that has an extension, such as `+16095550199x123`, returns `422`, so enter the direct number. A number that is a public emergency or N11 short code (211 through 911, and 988) returns `422` too. Your integration provides controls and displays available transcripts, and the phone carries audio. Operators do not join through browser WebRTC.

<figure><img src="https://1651797362-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2YwM0LHtEGLt9S21OyC3%2Fuploads%2Fgit-blob-b0ae0b52fb84942af5bc18484186da162ccd488f%2Foperator-voice-takeover-flow.svg?alt=media" alt="On a voice call the platform dials the operator&#x27;s phone. In listen mode the operator is muted, the agent stays active, and guidance goes to the agent as text the caller does not hear. After your console confirms going live, switching to takeover unmutes the operator and pauses the agent. Leaving, hanging up, or handing back resumes the agent."><figcaption><p>In listen mode the operator is muted, and the caller hears them only in takeover mode. Guidance goes to the agent as text, and your console owns the go-live confirmation.</p></figcaption></figure>

The join operation's `mode` defaults to `takeover`, so request `listen` explicitly when the operator should monitor silently first, and implement a confirmation step before requesting takeover. The API does not supply a user-interface confirmation flow.

Joining is idempotent for the same operator and call. A different operator attempting to join an already occupied call receives a conflict response.

## Supported Runtimes <a href="#supported-runtimes" id="supported-runtimes"></a>

Takeover and guidance work on platform-managed voice calls. A call that runs on `gpt_realtime` does not support them. A live `gpt_realtime` call can appear in the run list, so check the run's `session_provider` and offer these controls only when it is `concurrence`. See [Takeover Eligibility](https://docs.concurrence.com/developer-guide/platform-api/conversations/runs.md#takeover-eligibility).

## Credentials <a href="#credentials" id="credentials"></a>

Operator actions run as the signed-in operator. Join call, switch mode, leave call, send guidance, and wrap-up need:

* the operator's identity token, because a workspace API key is refused with `403` and the message `Identity JWT required for this operation`;
* the `Operator:Update` permission, which the `operator`, `admin`, and `owner` roles carry and the `member` and `viewer` roles do not, and
* an `operator_id` that is the caller's own operator. No role can act as another operator.

The read operations on this page (queue, escalations, performance, audit log, briefing, and the operator list and detail) need `Operator:View` and accept a workspace API key. Registering an operator needs `Operator:Create`, which the `member`, `admin`, and `owner` roles carry, and updating one needs `Operator:Update`. Both accept a workspace API key whose role holds the permission. See [Sign the Operator In](https://docs.concurrence.com/developer-guide/guides/build-an-operator-console.md#credentials) for how an operator's token is obtained and which credential belongs where.

## Operator Call Errors

Operator actions run as the operator named in the path. Join call, switch mode, leave call, send guidance, and wrap-up need a credential that belongs to that operator: the credential's user must be that operator. A credential acting as another operator, or one with no user identity, gets `403`.

Join call, switch mode, and leave call act on the live call through telephony and report failures by cause:

| Status | When                                                                                                                                                                                                 |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `403`  | The credential isn't the operator in the path, the credential is a workspace API key, the workspace isn't enabled for the beta, or the call belongs to another workspace.                            |
| `404`  | The operator, the active call, or the operator's leg on the call wasn't found.                                                                                                                       |
| `409`  | The call has already ended or the operator's leg has left the conference, another operator is already on the call, the operator is already on a call, or the operator's profile has no phone number. |
| `422`  | The request was refused, for example an operator phone number that isn't in the line's `allowed_forwarding_numbers`, a malformed call ID, or a mode other than `listen` or `takeover`.               |
| `502`  | Any other telephony or voice runtime failure.                                                                                                                                                        |
| `503`  | The voice runtime is unavailable.                                                                                                                                                                    |
| `504`  | Telephony or the voice runtime did not respond in time.                                                                                                                                              |

If muting a listen-mode operator fails after their phone was dialed, the platform removes that leg before it returns the error, so the operator is not left on the call unmuted. A `504` can leave the outcome unclear, so check the call before you retry. Correct the request before you retry a `409` or `422`.

## Three-Party Speaker Resolution

When an operator is on the call, three participants produce audio simultaneously. Speaker attribution uses a priority chain:

Speaker resolution prefers detected operator speech, then detected caller speech, and otherwise uses the caller as the default. This attribution rule does not replace the operator’s listen or takeover mode.

Recorded turns can carry `speaker_id` and `speaker_role` to support transcript attribution in three-party conversations. Clients should still tolerate missing or ambiguous speaker metadata when a stream or persistence step is incomplete.

## Escalations

An escalation hands a call to a human. There are two paths:

| Path                      | How It Happens                                                                                                                                                                                                                                                                                                                              |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Operator join**         | An integration requests operator join in listen or takeover mode. Joining a call that has no open escalation creates one with trigger `operator`.                                                                                                                                                                                           |
| **Agent call forwarding** | The agent's context graph reaches a forwarding action (`forward_call`) and transfers the caller to a human phone number - for example when the caller asks for a person or the flow requires human judgment. See [call forwarding](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#call-forwarding). |

### Escalation Lifecycle

An escalation starts as requested. An operator joining the call establishes connection, and returning to listen can hand control back. Completion is recorded when the call ends or the operator completes the escalation. A request alone does not prove that an operator joined.

**Dual-entity event writes**: supported escalation events are written to the call entity and operator entity when both writes succeed, enabling independent state recomputation for each. The call entity tracks escalation history; the operator entity tracks availability and performance.

**Event chain**: successful escalation events can supersede the previous event (`escalation.requested` → `escalation.connected` → `escalation.handback` → `escalation.completed`), forming a versioned event history.

| Event                  | Written When                               | Key Data                                           |
| ---------------------- | ------------------------------------------ | -------------------------------------------------- |
| `escalation.requested` | Escalation created                         | `escalation_id`, trigger, trigger source, reason   |
| `escalation.connected` | Operator joins and takes over              | Operator entity ID, connection type, response time |
| `escalation.handback`  | Operator returns to listen mode            | Agent resumes                                      |
| `escalation.completed` | Call ends or operator explicitly completes | `handle_time_seconds`, outcome                     |

## Operator Flow

1. Join the active call in the selected mode.
2. Switch to takeover to speak with the caller while the agent pauses.
3. Return to listen to let the agent resume. Use supported guidance when needed.
4. Leave the call and inspect retained operator evidence.

Use the operation references above for the exact controls.

## Operator Guidance

Operators in listen mode can send text guidance to the agent without taking over the call. SDK: `client.operators.sendGuidance(operatorId, body)`, or `client.runs.sendGuidance(runId, body)` by run.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/operators/{operator\_id}/send-guidance" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

```json
{
  "call_sid": "CA1234...",
  "message": "Ask for their insurance ID before confirming the appointment"
}
```

The guidance is injected into the active session as a `guidance` event type. When delivery succeeds, the session can interrupt current agent speech and incorporate the guidance into its next response. Delivery does not guarantee exact response timing or that the model will follow the instruction verbatim. This is distinct from operator takeover: the operator does not speak directly to the caller.

**Permission**: requires `Operator:Update` on the operator entity, and the credential must belong to that operator (see [Operator Call Errors](#operator-call-errors)). The operator must belong to the same workspace as the call.

**How it works**: the platform delivers the guidance to the active voice session as an injected event (see [session event injection](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#session-event-injection)). The operator's identity is recorded in the call transcript as the event sender.

**Delivery status**: the response `status` is one of `delivered`, `queued_no_subscriber`, `deduplicated`, `failed`, or `unknown`. `delivered` confirms that a live session received the guidance. `queued_no_subscriber` means no active session was listening, for example because the call ended or the session was still starting, so the guidance was not delivered. `deduplicated` means an identical guidance for the same call was suppressed within a short window. `failed` and `unknown` mean delivery could not be confirmed. None of them shows that the agent followed the instruction. See also [session event injection](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent.md#session-event-injection).

## Dashboard & Analytics

These are API views for an integration, not current Developer Console pages.

| View                 | Description                                                                                    |
| -------------------- | ---------------------------------------------------------------------------------------------- |
| **Escalation Stats** | Aggregation by period (`day`, `week`, `month`) and dimension (`status`, `trigger`, `operator`) |
| **Performance**      | Operator rankings by response time, resolution rate, and average handle time                   |

## Audit Log

The supported lifecycle actions below emit world model events when their event writes succeed, providing an operator-action audit record:

| Action              | Event Written           | Entities Updated                       |
| ------------------- | ----------------------- | -------------------------------------- |
| Join call           | `operator.joined_call`  | Call + Operator (status → busy)        |
| Switch to takeover  | `operator.mode_changed` | Call (audit)                           |
| Switch to listen    | `operator.mode_changed` | Call (audit)                           |
| Leave call          | `operator.left_call`    | Call + Operator (status → online)      |
| Complete escalation | `escalation.completed`  | Call + Operator (handle time recorded) |

**Dual-entity writes**: supported escalation events are written to both entities when both writes succeed, enabling entity-scoped queries for a call or operator without a cross-entity join. This design does not establish an API latency or computational-complexity guarantee.

### Run Takeover Actions <a href="#run-takeover-actions" id="run-takeover-actions"></a>

The run-addressed operations on [Runs](https://docs.concurrence.com/developer-guide/platform-api/conversations/runs.md#operator-takeover) record these events against the operator who took the action:

| Action                                                                   | Event                                                   |
| ------------------------------------------------------------------------ | ------------------------------------------------------- |
| Take over a run, or a takeover refused because another operator holds it | `operator.takeover_started`                             |
| A renewal refused because the hold had ended                             | `operator.takeover_renewed` with a `result` of `failed` |
| Hand back a run, or take over a run whose earlier hold had ended         | `operator.handback`                                     |
| Stage a reply                                                            | `operator.authored_turn`                                |
| Send guidance                                                            | `operator.guidance_sent`                                |
| Switch mode                                                              | `operator.mode_switched`                                |

Events carry identifiers and the outcome, and the channel where the run is known. The takeover, hand back, staged reply, and mode switch events also carry a `result`: `ok` or `failed`, and `staged` for a reply that was handed to the agent. A guidance event carries its delivery status. A staged reply and guidance carry their length and a content fingerprint, not their text. A renewal that succeeds, and a takeover that the holder repeats, are not recorded: the end of the hold is on the run, in `takeover.held_by`.

[The audit log](#query-the-operator-audit-log) is refreshed about every 15 minutes, so an action appears in it after that delay. The log cannot confirm an action an operator has just taken, so read the run or the reply's state instead. The `action` filter takes these event names.

## Entity Types

### Operator Entity

Projected state from operator events:

| Field                       | Description                                                |
| --------------------------- | ---------------------------------------------------------- |
| `status`                    | Current availability (online, busy, offline)               |
| `profile`                   | Name, contact info                                         |
| `total_escalations_handled` | Lifetime count of escalations handled                      |
| `avg_handle_time_seconds`   | Average escalation duration                                |
| `last_call_at`              | Timestamp of the operator's last completed escalation call |
| `last_status_change`        | Timestamp of the last availability transition              |

### Call Entity (Escalation Fields)

The call entity's projected state includes escalation-specific fields:

| Field               | Description                                                                                                |
| ------------------- | ---------------------------------------------------------------------------------------------------------- |
| `escalation.status` | Current escalation state (none, requested, connected, handback, completed)                                 |
| `escalation`        | Escalation detail: trigger, trigger source, requested/connected/completed timestamps, wait and handle time |
| `human_segments`    | Operator speech transcripts captured during takeover                                                       |
| `audit`             | Operator action audit summary (event count, latest event)                                                  |

## Operator API

### Get the Operator Dashboard

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/operators/dashboard" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Get Operator Performance

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/operators/performance" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### List Active Escalations

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/operators/escalations/active" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Get Escalation Statistics

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/operators/escalations/stats" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### List Escalation Events

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/operators/escalations" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Query the Operator Audit Log

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/operators/audit-log" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Get an Operator Call Transcript

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/operators/calls/{call\_sid}/transcript" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Get the Operator Queue

SDK: `client.operators.getQueue()`

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/operators/queue" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Generate an Operator Briefing

SDK: `client.operators.createBriefing(operatorId, { call_sid })`

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/operators/{operator\_id}/briefing" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Join a Call

SDK: `client.operators.joinCall(operatorId, body)`

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/operators/{operator\_id}/join-call" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Leave a Call

SDK: `client.operators.leaveCall(operatorId, body)`

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/operators/{operator\_id}/leave-call" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Switch Operator Mode

SDK: `client.operators.switchMode(operatorId, body)`

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/operators/{operator\_id}/switch-mode" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Record Operator Wrap-Up

SDK: `client.operators.wrapUp(operatorId, body)`

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/operators/{operator\_id}/wrap-up" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Register an Operator

SDK: `client.operators.create(body)`

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/operators" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### List Operators

SDK: `client.operators.list()`

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/operators" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Get an Operator

SDK: `client.operators.get(operatorId)`

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/operators/{operator\_id}" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Update an Operator

SDK: `client.operators.update(operatorId, body)`

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/operators/{operator\_id}" method="patch" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

## Rate Limits

Each read operation on this page allows 60 requests per minute. Each write operation (register, update, briefing, join, leave, switch mode, send guidance, and wrap-up) allows 10. Limits are enforced per authenticated credential and operation. Successful limit checks return `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. A `429` response also returns `Retry-After`. The run takeover operations have their own counts. See [Runs](https://docs.concurrence.com/developer-guide/platform-api/conversations/runs.md#rate-limits).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/developer-guide/platform-api/conversations/operators.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
