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, call transcripts, and operator-action audit records built on the platform's world model.
Operator Lifecycle
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 or switches back to listen, the agent can resume 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. Operator transcripts during takeover can be captured as human_segment turns through a dedicated per-participant STT stream.
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. Your integration provides controls and displays available transcripts; the phone carries audio. Browser WebRTC operator joining and its access-token routes have been removed.
Request listen mode explicitly when the operator should monitor silently before taking over. Check the join operation's default in its embedded contract below, 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.
Three-Party Speaker Resolution
When an operator is on the call, three participants produce audio simultaneously. Speaker attribution uses a priority chain:
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:
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.
Escalation Lifecycle
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.
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
Operator Guidance
Operators in listen mode can send text guidance to the agent without taking over the call:
Inject operator guidance into an active call. The agent incorporates it into its next response.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Delivery status
Call SID the guidance was sent to
Operator or active call not found.
Validation Error
Voice agent service unavailable.
POST /v1/{workspace_id}/operators/{operator_id}/send-guidance HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 36
{
"call_sid": "text",
"message": "text"
}{
"status": "delivered",
"call_sid": "text"
}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. 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). The operator's identity is recorded in the call transcript as the event sender.
Delivery status: the response includes a status field. "delivered" confirms the session received the guidance; "failed" indicates the guidance could not be delivered. The "queued_no_subscriber" semantics (call ended or session not yet listening) apply only to the session event-injection endpoint documented in session event injection.
Dashboard & Analytics
These are API views for an integration, not current Developer Console pages.
Dashboard
Composite view: operator status counts, active escalation count, daily escalation stats, recent escalations
Active Escalations
Paginated queue of active escalations with trigger and call context
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
Call Transcript
Human-segment events for a specific operator's call participation
Audit Log
The supported lifecycle actions below emit world model events when their event writes succeed, providing an operator-action audit record:
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.
Entity Types
Operator Entity
Projected state from operator events:
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:
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
Live dashboard with operator status counts, active escalation queue, and today's escalation statistics.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
GET /v1/{workspace_id}/operators/dashboard HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful Response
{
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"operators": {
"total": 1,
"online": 1,
"busy": 1,
"offline": 1
},
"active_escalations": 1,
"escalations_today": {
"requested": 0,
"connected": 0,
"completed": 0,
"avg_wait_seconds": 1,
"avg_handle_time_seconds": 1
},
"recent_escalations": [
{
"call_entity_id": "123e4567-e89b-12d3-a456-426614174000",
"call_sid": "text",
"escalation_id": "text",
"status": "text",
"trigger": "text",
"trigger_source": "text",
"concept": "text",
"operator_type": "clinical",
"regulatory_basis": "text",
"immediate": true,
"risk_score": 1,
"requested_at": "text",
"connected_at": "text",
"wait_seconds": 1,
"operator_entity_id": "123e4567-e89b-12d3-a456-426614174000",
"caller_id": "text",
"direction": "inbound",
"phone_number": "text",
"started_at": "text"
}
]
}Get Operator Performance
Aggregate performance across all operators with per-operator breakdown.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
GET /v1/{workspace_id}/operators/performance HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful Response
{
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"total_operators": 1,
"online": 1,
"busy": 1,
"offline": 1,
"total_escalations_handled": 1,
"avg_handle_time_seconds": 1,
"operators": [
{
"operator_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"status": "online",
"total_escalations_handled": 1,
"avg_handle_time_seconds": 1,
"last_call_at": "text"
}
]
}List Active Escalations
List calls with active escalations (status: requested or connected).
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
50Successful Response
Validation Error
GET /v1/{workspace_id}/operators/escalations/active HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"items": [
{
"call_entity_id": "123e4567-e89b-12d3-a456-426614174000",
"call_sid": "text",
"escalation_id": "text",
"status": "text",
"trigger": "text",
"trigger_source": "text",
"concept": "text",
"operator_type": "clinical",
"regulatory_basis": "text",
"immediate": true,
"risk_score": 1,
"requested_at": "text",
"connected_at": "text",
"wait_seconds": 1,
"operator_entity_id": "123e4567-e89b-12d3-a456-426614174000",
"caller_id": "text",
"direction": "inbound",
"phone_number": "text",
"started_at": "text"
}
],
"has_more": true,
"continuation_token": null
}Get Escalation Statistics
Aggregated escalation statistics over a time period.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Time period: day, week, or month.
dayPossible values: Grouping dimension: status, trigger, or operator.
statusPossible values: Successful Response
Validation Error
GET /v1/{workspace_id}/operators/escalations/stats HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"period": "text",
"group_by": "text",
"buckets": [
{
"key": "text",
"count": 1
}
],
"total": 1
}List Escalation Events
List escalation lifecycle events for a workspace.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
50Successful Response
Validation Error
GET /v1/{workspace_id}/operators/escalations HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"items": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"event_type": "text",
"data": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"source": "text",
"confidence": 1,
"ingested_at": "2026-01-01T00:00:00.000Z",
"created_at": "2026-01-01T00:00:00.000Z"
}
],
"has_more": true,
"continuation_token": null
}Query the Operator Audit Log
Query audit events (operator actions) for a workspace.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
50Filter by operator entity UUID.
Filter by exact operator audit event type.
Successful Response
Validation Error
GET /v1/{workspace_id}/operators/audit-log HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"items": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"event_type": "text",
"data": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"source": "text",
"ingested_at": "2026-01-01T00:00:00.000Z",
"created_at": "2026-01-01T00:00:00.000Z"
}
],
"has_more": true,
"continuation_token": null
}Get an Operator Call Transcript
Per-speaker transcript segments from operator takeover sessions.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Call not found.
Validation Error
GET /v1/{workspace_id}/operators/calls/{call_sid}/transcript HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"call_entity_id": "123e4567-e89b-12d3-a456-426614174000",
"call_sid": "text",
"total_segments": 1,
"segments": [
{
"speaker_role": "text",
"transcript": "text",
"timestamp": "text",
"escalation_id": "text",
"confidence": 1
}
]
}Get the Operator Queue
Active calls ranked by operator priority: risk, wait time, emotion, loops, and safety concerns.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Rate limit exceeded.
GET /v1/{workspace_id}/operators/queue HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"queue": [
{
"call_sid": "text",
"caller_id": "",
"caller_phone": "text",
"service_id": "",
"service_name": "text",
"direction": "inbound",
"data_quality_flags": [
"text"
],
"started_at": "2026-01-01T00:00:00.000Z",
"priority_score": 1,
"priority_reasons": [
"high_risk"
],
"wait_seconds": 0,
"risk_score": 1,
"risk_level": "low",
"current_emotion": "text",
"current_valence": 1,
"current_state": "",
"turn_count": 0,
"escalation_active": false,
"entity_name": "text",
"brief_context": "text"
}
],
"total_active": 1
}Generate an Operator Briefing
Structured briefing for an operator about to join a call. Template-rendered from call intelligence and entity context.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Request for operator briefing on a specific call.
Successful Response
Structured operator briefing for a call.
Invalid operator_id.
Validation Error
Rate limit exceeded.
POST /v1/{workspace_id}/operators/{operator_id}/briefing HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 19
{
"call_sid": "text"
}{
"call_sid": "text",
"operator_id": "123e4567-e89b-12d3-a456-426614174000",
"sections": [
{
"title": "text",
"content": "text"
}
],
"generated_at": "2026-01-01T00:00:00.000Z"
}Join a Call
Add operator to an active call's Twilio Conference.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Request to join an active call as operator.
takeoverPossible values: Successful Response
Confirmation of operator joining a call's conference.
Twilio participant call SID
Twilio conference SID
Operator mode: listen or takeover
World entity ID of the operator
Operator or active call not found.
Operator is already on a call.
Validation Error
Voice agent service unavailable.
POST /v1/{workspace_id}/operators/{operator_id}/join-call HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 37
{
"call_sid": "text",
"mode": "takeover"
}{
"participant_call_sid": "text",
"conference_sid": "text",
"mode": "listen",
"operator_entity_id": "123e4567-e89b-12d3-a456-426614174000"
}Leave a Call
Remove operator from an active call's Twilio Conference.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Request to remove operator from an active call.
Successful Response
Operator or active call not found.
Validation Error
Voice agent service unavailable.
POST /v1/{workspace_id}/operators/{operator_id}/leave-call HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 19
{
"call_sid": "text"
}{
"success": true
}Switch Operator Mode
Switch between listen mode and takeover mode.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Request to toggle operator mode on an active call.
""Successful Response
New operator mode
Operator not found.
Validation Error
Voice agent service unavailable.
POST /v1/{workspace_id}/operators/{operator_id}/switch-mode HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 61
{
"call_sid": "text",
"participant_call_sid": "",
"mode": "listen"
}{
"mode": "listen"
}Record Operator Wrap-Up
Persist the outcome and notes from an operator's call intervention.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Request to record operator intervention wrap-up.
""Successful Response
Operator not found.
Validation Error
POST /v1/{workspace_id}/operators/{operator_id}/wrap-up HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 51
{
"call_sid": "text",
"outcome": "resolved",
"notes": ""
}{
"success": true
}Register an Operator
Create an operator entity with profile and initial offline status.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
clinicalPossible values: phonePossible values: operatorPossible values: Successful Response
Display name
Contact email
Operator specialization
Skill tags for routing
How the operator connects to calls
E.164 phone number for phone-based operators
Permission role
Current availability
ISO-8601 timestamp of last status transition
Call SID if currently on a call
Lifetime escalation count
Average escalation handle time in seconds
ISO-8601 timestamp of last call
When the operator was created
When the operator was last updated
Missing or invalid API key.
Insufficient permissions.
Validation Error
POST /v1/{workspace_id}/operators HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 144
{
"name": "text",
"email": "name@gmail.com",
"type": "clinical",
"skills": [
"text"
],
"connection_method": "phone",
"phone_number": "text",
"role": "operator"
}{
"id": "123e4567-e89b-12d3-a456-426614174000",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"email": "text",
"type": "clinical",
"skills": [
"text"
],
"connection_method": "browser",
"phone_number": "text",
"role": "operator",
"status": "online",
"last_status_change": "text",
"active_call_sid": "text",
"total_escalations_handled": 1,
"avg_handle_time_seconds": 1,
"last_call_at": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}List Operators
List all operator entities for a workspace.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
50Successful Response
Validation Error
GET /v1/{workspace_id}/operators HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"items": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"email": "text",
"type": "clinical",
"skills": [
"text"
],
"connection_method": "browser",
"phone_number": "text",
"role": "operator",
"status": "online",
"last_status_change": "text",
"active_call_sid": "text",
"total_escalations_handled": 1,
"avg_handle_time_seconds": 1,
"last_call_at": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}
],
"has_more": true,
"continuation_token": null
}Get an Operator
Get operator entity with computed state (profile, availability, performance).
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Display name
Contact email
Operator specialization
Skill tags for routing
How the operator connects to calls
E.164 phone number for phone-based operators
Permission role
Current availability
ISO-8601 timestamp of last status transition
Call SID if currently on a call
Lifetime escalation count
Average escalation handle time in seconds
ISO-8601 timestamp of last call
When the operator was created
When the operator was last updated
Operator not found.
Validation Error
GET /v1/{workspace_id}/operators/{operator_id} HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"email": "text",
"type": "clinical",
"skills": [
"text"
],
"connection_method": "browser",
"phone_number": "text",
"role": "operator",
"status": "online",
"last_status_change": "text",
"active_call_sid": "text",
"total_escalations_handled": 1,
"avg_handle_time_seconds": 1,
"last_call_at": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}Update an Operator
Update operator profile fields or status. Each change writes a world event.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Display name
Contact email
Operator specialization
Skill tags for routing
How the operator connects to calls
E.164 phone number for phone-based operators
Permission role
Current availability
ISO-8601 timestamp of last status transition
Call SID if currently on a call
Lifetime escalation count
Average escalation handle time in seconds
ISO-8601 timestamp of last call
When the operator was created
When the operator was last updated
Operator not found.
Validation Error
PATCH /v1/{workspace_id}/operators/{operator_id} HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 164
{
"name": "text",
"email": "name@gmail.com",
"type": "clinical",
"skills": [
"text"
],
"connection_method": "browser",
"phone_number": "text",
"role": "operator",
"status": "online"
}{
"id": "123e4567-e89b-12d3-a456-426614174000",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"email": "text",
"type": "clinical",
"skills": [
"text"
],
"connection_method": "browser",
"phone_number": "text",
"role": "operator",
"status": "online",
"last_status_change": "text",
"active_call_sid": "text",
"total_escalations_handled": 1,
"avg_handle_time_seconds": 1,
"last_call_at": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}Last updated
Was this helpful?