Build Your Own Operator Console
Build an operator console on the Platform API and SDK: sign operators in, find live runs, take over text and phone conversations, and hand back.
Build an operator screen that lets a person watch live conversations, step in, and hand them back to the agent. This guide uses the Platform API and the Platform SDK for TypeScript (@amigo-ai/platform-sdk). Every call also works over HTTP with the same credentials, and the main calls include a curl version.
It is written for the engineers who build an operator experience on the Platform API, such as solutions engineers who put together a working screen for a customer deployment and developers who add operator controls to their own tools. With the sign-in used in this guide, operators use the Developer Console twice: to accept their workspace invitation and to approve the sign-in that authorizes your app. Every other step uses the API.
What You Build
A sign-in on your server that gives each operator their own identity token.
A list of live runs, where a run is one conversation on any channel, that shows which ones an operator can take over.
A text panel with the conversation, a hold that stays renewed while the operator is present, a composer that stages one reply at a time, and a handback button.
A phone panel that joins in listen mode, asks for explicit confirmation before the operator speaks to the caller, sends guidance, and hands back.
Error messages, a record of what operators did, and exit paths that hand the run back.
Before You Start
You need:
A workspace enabled for operators. Check access with one call.
An operator user. A person who signs in to the workspace with the
operator,admin, orownerrole. Those roles holdOperator:Update, which every control call needs. Thememberandviewerroles do not. Invite the person with the role you want. They accept the invitation in the Developer Console.An operator profile for that person. Register it with the email address the person signs in with and, for phone calls, a phone number in E.164 format. Registering needs
Operator:Create, which themember,admin, andownerroles hold.For phone calls, a line that allows the number. The operator's phone number must be in the line's
allowed_forwarding_numbers, in the same E.164 form. Whoever provisions the line sets the list. See Control Voice Calls.A platform-managed voice service for phone takeover. A service whose
session_providerisgpt_realtimedoes not support takeover or guidance. See Session Provider and Check the Runtime.Your workspace ID and region hosts. The examples use the US production hosts. Use the hosts for your region from Regions & Endpoints.
The SDK, on your server. Node.js 20 or later and
npm install @amigo-ai/platform-sdk. Staging a text reply withruns.authorTurnneeds version 0.116.0 or later. Renewing a hold withruns.renewTakeoverand reading a staged reply withruns.getAuthoredTurnneed 0.127.0 or later. Every SDK call in this guide runs on your server (see How the Pieces Fit). For setup, see Installation and Configuration.
Text conversations need no phone number and no line setup.
Check Access
Call a read operation with the credential you plan to use. A workspace that is not enabled returns the beta 403.
operators.list needs only Operator:View, so any role can run it. Any other error, including a different 403 such as a credential that belongs to another workspace, propagates so you can handle it.
How the Pieces Fit
Your console has two parts: the operator's browser and a small server you run. A browser page on your own domain cannot call the Platform API or the Identity API directly, so the browser talks only to your server. Your server signs the operator in, keeps their tokens in that operator's session, and calls the Platform API with the operator's identity token. Every SDK call on this page runs on your server.
Sign-in, sessions, and token handling on your server
Identity, tokens, roles, and permissions
The queue and its staffing rules: who sees which runs, in what order
Runs, each run's takeover eligibility, the operator roster, and a priority-ranked queue for phone calls
Transcript views
Conversation and call data
The reply composer for text conversations, and renewal of the hold while an operator is present
The hold on a text run, which keeps the agent silent, and one staged reply at a time, sent as its own message
The confirmation before an operator speaks, and the LIVE banner
Pausing and resuming the agent, and the phone connection: dialing the operator, muting, and removing them
A handback on every exit path
The handback that resumes the agent
Staffing, monitoring disclosures, and your own action log
Operator-attributed audit records
Two Ways to Address a Control
The same takeover can be requested by run or by operator.
Path
/v1/{workspace_id}/runs/{run_id}/...
/v1/{workspace_id}/operators/{operator_id}/...
Channels
Phone, SMS, WhatsApp, email, web, and iMessage, with one call shape
Phone calls, keyed by call_sid
Operations
takeover, takeover/renew, switch-mode, handback, authored-turn (stage and read), guidance
join-call, leave-call, switch-mode, send-guidance, wrap-up, briefing, plus the roster and the queue
SDK
client.runs
client.operators
Use the run-addressed operations for control: every run carries a server-computed takeover object, and one call shape covers every channel. Use the operator-addressed operations for the roster, the queue, briefings, and wrap-ups. Their contracts are on Runs and Operators.
Sign the Operator In
Every control call acts as one operator, and that operator is the signed-in user. The platform enforces three things on the run-addressed operations and on join-call, leave-call, switch-mode, send-guidance, and wrap-up:
An identity token. Send the operator's own Bearer token from sign-in. A workspace API key is refused with
403and the messageIdentity JWT required for this operation.Permission. The token's workspace role must include
Operator:Update:operator,admin, orowner.The right operator. The
operator_idin the request must be the signed-in user's own operator, the one you registered for that person. Any other id gets403, whatever the caller's role. There is no impersonation and no admin override, so your console has no operator picker.
An API key still makes the calls your server needs for itself:
The operator's identity token
On your server, in that operator's session. The browser holds only your own session cookie.
Every control call for that operator, and the reads in the next row
A workspace API key
On your server only
Reads: list runs, get a run, the run summary, the state of a staged reply, list and get operators, the queue, and briefings. It can also register and update operators when the key's role allows it, and open the event stream
Your server forwards the operator's token on every control call. Use the API key only for the reads and roster work the server does on its own behalf. See Choose Credentials.
Get the Operator's Token
The device authorization flow signs an operator in through your server. Your server asks the Identity API for a code, and your page shows the code and link to the operator. The operator approves the sign-in on the Developer Console's device page, and the SDK returns an access token and a refresh token for the workspace. Your server keeps both in that operator's session. If your operators sign in through your organization's identity provider, exchange the provider's authorization code at the token endpoint instead; see SSO Login.
Each operator needs a user in the workspace with a role that holds
Operator:Update.TokenManagerrefreshes the access token before it expires. CalloperatorClientfor each batch of requests so the client carries the current token.Show the operator
issuance.user_codeandissuance.verification_uri_complete.Keep tokens on your server, in that operator's session, and out of URLs and logs.
For the flow's details, other sign-in options, and multi-workspace users, see Authentication & API Keys.
Register the Operator Profile
The profile ties the signed-in user to the phone number the platform dials. A person with Operator:Create registers it once per operator, and registration returns the operator's id.
Register the email address the person signs in with. The platform ties the operator to the signed-in user through it. An email is unique in the workspace and fixed once registered, so a wrong address needs a new operator.
The phone number is required for phone calls and ignored for text. Leave
connection_methodatphone. Operators hear phone calls on their phone, and no other audio connection exists.The profile
role(operator,supervisor, oradmin) describes the person. Permissions come from the workspace role, not from this field.Keep the returned
idin your own record for the person. Every control call names it asoperator_id, and the platform accepts it only from that person's own token.
Find Runs That Need a Human
A run is one conversation on any channel, identified by a stable run_id. The platform does not decide which runs need a person. Your staffing rules do. The platform gives you the inventory, each run's eligibility, and for phone calls a priority-ranked queue.
Read these fields on each run:
status
running is live. paused is a text run that an operator holds, for as long as the hold lasts. Both match the live filter. A phone call with an operator on it stays running. A dormant run is idle and cannot be taken over.
channel
voice, sms, whatsapp, email, web, or imessage.
takeover
eligible, mode_options, and reason, plus held_by while an operator holds a text run. Voice offers listen and takeover. Every other channel offers takeover only. When eligible is false, reason is short text you can show as the disabled-state explanation. held_by gives the holder's operator_id, since, and expires_at, the end of the hold unless it is renewed. eligible stays true on a held run.
session_provider
The voice runtime. concurrence is platform-managed, and gpt_realtime is the realtime provider. It is null when no runtime was recorded for the run, so offer phone controls only when it is concurrence.
source_call_sid
The call's handle for phone runs. Use it for the operator-addressed operations and the observer stream.
source_conversation_id
The conversation to read for text runs.
Check the Runtime
Phone takeover and guidance work on platform-managed voice calls, so check session_provider in addition to takeover: offer them only when it is concurrence. For a gpt_realtime call, show the run for monitoring and offer neither control. canTakeOver in the snippet above applies both checks.
Rank Phone Calls
client.operators.getQueue() returns active phone calls ranked by priority_score, each with priority_reasons (high_risk, long_wait, safety_concern, or looping) and context such as wait_seconds. Match an item to its run on call_sid, which is the run's source_call_sid.
Watch for Changes
The workspace event stream tells you when to refresh. It is best-effort, so treat events as hints and read state from the Runs API. Open one stream on your server and push refresh hints to each operator's browser. A workspace allows a limited number of simultaneous streams, so do not open one per tab.
call.started, call.ended
A phone call began or ended. call.ended carries escalated.
call.escalated
An operator joined a call that had no open escalation, which opened one. trigger and reason say why.
text.started, text.completed
A text session began or ended.
Events carry identifiers and metadata, not message text. The SDK reconnects on its own and sends the last event ID it received, so the stream replays recent events you missed, on a best-effort basis. Ignore event types you do not handle. Open the stream with your workspace API key: a client built from an operator's token cannot reconnect after that token expires. When onError fires, the SDK has stopped retrying, so open the stream again with a new client. A too_many_streams error means the workspace has too many streams open. Close the ones you do not need. The SSE Events page describes the stream and its connection frames.
Take Over a Text Conversation
Text takeover uses the same calls on SMS, WhatsApp, email, web, and iMessage runs, and takeover.eligible says which runs accept them. There is no listen mode, because there is no live audio. Watching a text run is a read of its conversation and changes nothing. Takeover is what holds the run: the run is paused, and the agent does not reply while the hold lasts, apart from the emergency reply and the case where the platform cannot confirm the hold, both described in While an Operator Holds a Run. A hold lasts 90 seconds and ends by itself unless your console renews it, so a closed tab or a lost connection hands the conversation back to the agent about 90 seconds after the last renewal.
Check eligibility.
takeover.eligibleis true andmode_optionsincludestakeover. Apausedrun is held:takeover.held_bynames the operator, when they took the run, and when the hold ends unless it is renewed. Offer takeover on arunningrun, and on apausedrun whoseheld_by.operator_idis the signed-in operator's, to resume their panel. A different operator's takeover on a held run is refused with409.Take over. The run becomes
paused. The response carriesheld_by,hold_token, andlease_seconds, which is 90. Keep thehold_tokenin the operator's session on your server and send it back exactly as received: it is opaque, so do not parse or reformat it. If the conversation ended before the takeover took hold, the call returns409. If another operator holds the run, the call returns409withdetail.coderun_held:detail.held_bygives who holds it, since when, and until when, anddetail.operator_namenames them. Show the holder to the operator.Renew the hold. While the operator is present, renew at least every 30 seconds with the
hold_token. Each renewal moves the end of the hold to 90 seconds from the renewal, so one failed renewal does not end the hold. A renewal does not take a run. If the hold is gone because it was handed back, ran out, or another operator took the run, the renewal returns409withdetail.codehold_lost: stop renewing, tell the operator that the agent may have replied, and let them take over again on purpose. The holder can also call takeover again, which keeps the hold and returns the samehold_token, so it recovers a token you lost. Renew with the token rather than by taking over again, because a takeover that reaches the platform after a handback holds the run again.Show the conversation. Read it with
source_conversation_idwhile the panel is open. The person's messages appear in it while the run is held, and the agent does not answer them (see While an Operator Holds a Run for the exceptions). Reads are limited to 60 per minute per credential, so poll at a measured pace.Stage a reply. The operator writes a reply of 1 to 4,000 characters. Staging needs a hold that the operator owns: without one, the call returns
409withdetail.codeno_hold. The platform hands the reply to the agent, which sends it as its own message in the conversation.Read what became of the reply. Read its state until it is
consumedorexpired, then stage the next reply. A run has one reply waiting at a time. See How a Staged Reply Behaves.Hand back. The hold ends, the run returns to
running, and the agent answers the person's next message. A handback discards a reply that is still waiting, so show the operator when one is before they hand back. Only the operator who holds the run, or an admin or owner acting as their own operator, can hand back a held run. Anyone else gets403and the hold stays. Handing back a run that nobody holds succeeds and changes nothing.
The contracts are in Take Over a Run, Renew a Hold, Author a Non-Voice Turn, Read a Staged Reply, and Hand a Run Back.
While an Operator Holds a Run
A message from the person is recorded and shown in the conversation. The agent does not reply to it and does not run tools for it.
The hold is best effort. When the platform cannot confirm it as a message arrives, the agent answers that message as it would without a hold, so the person is not left in silence. Read the conversation to see what was sent.
While the platform can confirm the hold, a message that it recognizes as describing a medical emergency or self-harm gets an authored emergency reply. Recognition covers a limited set of phrasings in English and Spanish and can miss others, and a message it does not recognize gets no reply from the agent. Show the operator each new message as it arrives, because the operator who holds a run is the one answering it.
When the hold ends, whether by a handback or because nobody renewed it, the agent does not go back over what the person wrote in the meantime. It answers the person's next message, with the held messages in context. Have the operator answer the person before they hand back.
A conversation that your own application drives through the conversation API takes a turn or a poll while an operator holds it. The turn is recorded,
conversation.statusispaused, andoutputis empty, or holds the emergency reply when the platform sends one. The operator's replies are not in a turn or poll response: read them with List Conversation Turns. A close returns409until the hold ends. See Concurrency.
How a Staged Reply Behaves
The platform hands the reply to the agent before the call returns, and the agent sends it as its own message.
staged: truemeans the reply was handed over, not that it was sent. The response carriesreply_idandexpires_at.A run has one reply waiting at a time. Staging another while one waits returns
409withdetail.codereply_pendingand the waitingreply_id. A reply waits up to 2 minutes and is sent only while the operator who staged it still holds the run. A reply that is not sent in that time expires, and a handback discards it.GET .../authored-turnreads what became of the last reply on the run.stateisnone(no reply is on record),pending(it waits to be sent),consumed(it was taken to be sent), orexpired(it ran out of time, or a handback discarded it). The response also carriesreply_id,operator_id,staged_at, andexpires_at. Poll it while a reply ispending, at a pace inside the read limit, and keep the composer locked until the state isconsumedorexpired.consumedmeans the platform took the reply to send it, and it sends it at most once. It does not confirm that the channel delivered it: if the send fails after the reply was taken, the platform does not send it again, and the state still readsconsumed. Look for the reply as an agent message in the conversation before you stage the same text again.A reply that cannot be handed to the agent is discarded, so its state reads
expiredand the operator can stage another. The call returns an error, anddetail.codesays why. See Handle Errors.On a web conversation that an external user session owns, no agent runs for the person. The response has
waits_for_personset to true, and the reply is sent when the person next sends a message or polls, before it expires. It then appears in the conversation's turns. The response to that message or poll does not carry it.
Take Over a Phone Call
On a phone call the operator joins by phone. The platform dials the number on the operator's profile and adds that leg to the call. Your console controls the call and can show a live transcript. It does not carry audio.
Check eligibility and runtime. The run is
voice,takeover.mode_optionsincludeslistenandtakeover, andsession_providerisconcurrence.Brief the operator.
client.operators.createBriefing(operatorId, { call_sid })returns a structured briefing built from call intelligence and entity context.Join in listen mode. Pass
mode: 'listen'explicitly. The default istakeover, which suspends the agent from the moment of the join. In listen mode the operator's phone rings, and they hear the call while muted. The agent continues. Joining is idempotent for the same operator. A second operator on the same call gets409.Follow along. The operator hears the call on their phone. To show a live transcript, subscribe from your server to the call's observer stream, which accepts the operator's identity token or a workspace API key, and send the lines to the browser. See Observer Events. Keep Go live disabled until the operator has answered: the stream reports a
participant_joinedevent withparticipant_roleoperatorwhen they do.Send guidance when needed. Guidance can interrupt the agent's current speech and steer its next reply without adding operator audio. Check the returned
status.deliveredmeans a live session received it.deduplicatedmeans an identical guidance was just sent.queued_no_subscribermeans no session was listening, andfailedandunknownmean delivery was not confirmed.Confirm, then go live. Switch to
takeoveronly after the operator confirms. The agent's speech and turn processing stop while the operator drives.Hand back. The operator leaves, the agent resumes in the same call, with what was said during the takeover as context when the platform captured it, and your console records a wrap-up.
Join in listen mode and send guidance:
Go live after confirmation, and return to listening:
Hand back and record the outcome:
The contracts are in Take Over a Run, Switch Mode, Send Guidance, and Record Operator Wrap-Up.
Go-Live Confirmation
The API does not supply a confirmation flow. Your console provides one, because going live puts a person's voice on a call with a caller. Make it explicit:
Name the caller and the service, and say that the operator will speak to the caller and the agent will stop.
Require a deliberate action. Do not trigger it from a keyboard shortcut or a default-focused button.
Show a persistent LIVE banner while the operator is in takeover, with a Stop talking control that returns to listen mode.
Tell the operator when to speak. Mode changes take a moment to reach the call, so show a switching state until the response returns.
What the Phone Connection Does
The join response means the platform placed the call to the operator's phone. The operator answers on their phone. Carrier conditions can delay the leg.
A mode switch needs the
participant_call_sidfrom the join response. Keep it, and the current mode, in your own session record. After a page reload, repeating the join withmode: 'listen'returns the sameparticipant_call_sidfor the same operator, but itsmodeechoes the request rather than the call's current mode.If the operator hangs up, the agent resumes. Hand back removes the operator's leg and resumes the agent.
Recorded turns can carry
speaker_idandspeaker_roleto attribute caller, agent, and operator speech. Tolerate missing or ambiguous speaker metadata.
Verify the Flow
Run each flow once on a test workspace before you show it to anyone.
Text
Run these steps on a test conversation of each channel you plan to staff.
After takeover,
GET /runs/{run_id}showsstatuspaused, andtakeover.held_bynames your operator.While the run is held, send a message as the person. It appears in the conversation, and the agent does not reply. A conversation your application drives through the conversation API accepts the turn, reads
paused, and returns an emptyoutput.Stage a reply. It appears in the conversation as an agent message, and
GET /runs/{run_id}/authored-turnreadsconsumed.Stop renewing and wait 90 seconds. The run reads
runningagain, and a renewal returns409withhold_lost.Take over again, then hand back. The status is
running. Send a message as the person: the agent answers it.Clean up: hand back, then close the test conversation.
Phone
After a listen join, the operator's phone rings and the operator hears the call. Once they answer, the call's observer stream reports
participant_joinedwithparticipant_roleoperator.After go-live, the agent stops speaking.
After handback, the operator's leg ends and the agent keeps the call.
Clean up: hand back, end the test call, and record a wrap-up.
Test phone takeover on a real phone call to a test line whose allowlist includes your test operator's number. A browser test call or a simulation is not a phone call: its run reports takeover.eligible as false, and a join on it is refused. In production, real callers and real operators replace the test line and the test numbers.
Handle Errors
Branch on the status, then show your own text. Log the detail in the body with the request_id for support, except on 422, where detail can echo what the operator typed. On 409, detail names the reason the request was refused. A hold or reply conflict on a text run carries an object with a code, listed after the table. Any other 409 carries text your console can show.
401
The token is missing, invalid, or expired.
Refresh the token, or send the operator back to sign-in.
403
The workspace is not enabled: Operators is a beta feature that is not enabled for this workspace.
"Operators is not enabled for this workspace." Hide the operator screens and point to your Concurrence representative.
403
A workspace API key was used: Identity JWT required for this operation.
A developer error. Send the operator's token.
403
The request names another operator: You may only perform operator actions as your own operator identity.
"You can only act as yourself." Remove any operator picker.
403
The role lacks Operator:Update, the token belongs to another workspace, or the call belongs to another workspace.
"Your role cannot do this."
403
A handback of a held text run by an operator who does not hold it and is not an admin or owner: Only the operator who holds this run, or an admin or owner, can hand it back.
"Another operator holds this conversation."
404
The run is not live in this workspace, no operator profile exists for the id, or the call or the operator's leg was not found. A handback after the operator already left a call also returns 404.
"This conversation is not live." Refresh the list. If the profile is missing, ask an admin to register one.
409
The channel does not support the action, the conversation ended before takeover, the operator has no phone number, another operator is on the call, the call or the operator's leg already ended, or a text run's hold or staged reply conflicts with the request. Only the hold and reply conflicts carry a detail.code. The other causes carry text. A close on a held conversation also returns 409.
Show the reason from detail, or your own text for its code, then refresh the run.
422
The phone number is not in the line's allowed_forwarding_numbers, a mode other than listen or takeover was sent, or the text is empty or longer than 4,000 characters (guidance: 5,000).
Show fixed text, and do not show or log detail. For a number problem, tell the operator to ask whoever provisions the line.
429
The credential exceeded a rate limit.
Wait for Retry-After, then retry.
502
A telephony or voice runtime failure, or the platform could not take, renew, or release the hold, stage or send the reply, or look the run up. On a staged reply, detail.code says whether sending it again is safe.
"That did not go through." Check the run, then retry.
503
The voice runtime, the identity service, or the platform is unavailable, or the run is busy. A busy run answers with Retry-After.
Retry shortly.
504
Telephony or the voice runtime did not respond in time. The outcome can be unclear, and the operator's phone may still ring.
Check the run before you retry.
On a text run, these errors carry an object in detail, and detail.code says what happened:
detail.code
Status
Call
What it means
run_held
409
Take over
Another operator holds the run. detail.held_by gives who, since when, and until when, and detail.operator_name names them. Either can be null. Show the holder and offer no takeover.
hold_lost
409
Renew
The hold was handed back, ran out, or another operator took the run. Stop renewing and tell the operator.
no_hold
409
Stage a reply
The operator has no live hold on the run. Take over first.
reply_pending
409
Stage a reply
A reply is already waiting, and detail.reply_id names it. Stage again once its state is not pending.
conversation_not_active, reply_expired, channel_routing_unavailable, reply_not_deliverable
409
Stage a reply
The reply could not be handed to the agent, and it was not sent. channel_routing_unavailable means the person has not written recently enough for the platform to reach them on this channel.
agent_unreachable
502 or 503
Stage a reply
The reply was not sent. Sending it again is safe.
agent_rejected_request
502
Stage a reply
The platform's request to send the reply was refused. The reply was not sent, and sending it again will not help.
conversation_read_failed
502
Stage a reply
Nothing was staged or sent. Sending the reply again is safe.
delivery_unconfirmed
502
Stage a reply
The reply may have been sent. Read the conversation before you send it again.
A busy run answers takeover, renew, handback, and stage with 503 and no code. Retry after the seconds in Retry-After.
Correct the request before you retry a 409 or 422. A join on a call that is not a phone call is refused with 409, and a mode switch or handback with 422, so check takeover.eligible first. The Platform SDK error classes carry statusCode, detail, and requestId.
What Is Recorded
Operator actions are recorded against the operator who took them, when the record can be written. The operator audit log lists a takeover, a handback, a staged reply, guidance, and a mode switch. A record holds identifiers and the outcome, and the channel and mode where they apply. A staged reply and guidance are recorded with 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. A renewal that the platform refused because the hold had ended is recorded.The log is refreshed about every 15 minutes, so an action appears in it after that delay. To confirm an action the operator just took, read the run or the reply's state, not the log. See Query the Operator Audit Log.
A wrap-up records an
outcomeofresolved,escalated, ortransferredand up to 2,000 characters of notes.
Records are best-effort: one that cannot be written does not fail the action. Keep your own record of what your console sent, including text takeovers, handbacks, and staged replies, in your system of record.
Production Checklist
Confirm before an operator speaks. Build the go-live confirmation and the LIVE banner. Pass
mode: 'listen'on every phone join.One operator per run. A second join on a call returns
409. A second takeover on a held text run returns409withdetail.coderun_held, and the platform names the holder, so your console does not need to claim a run first.Track who is on which call. Your console decides how many calls an operator can be on. Joining a call does not change the operator's profile
status, and a takeover by run does not check it, so keep your own record of who is on which call.Renew only while an operator is present. A hold that is renewed does not end, so a console that keeps renewing from an unattended screen keeps the agent silent on that conversation. Renew from your server on a timer tied to the operator's session, and stop when the session shows no input for the idle limit you set.
Hand back on every exit. Hand back on sign-out, an idle timeout, an error boundary, and page close, so the agent answers again at once instead of after the hold runs out. A hold ends when it is handed back or not renewed. A closing tab cannot make a normal request, so have the page send a beacon to your server (below) and let the server hand the run back.
Give supervisors a way to find held runs. List
status=pausedruns on a supervisor screen to find held text runs:takeover.held_bynames the operator, since when, and until when. A phone call with an operator on it staysrunning, so track those from the joins your console makes, and flag the ones held longer than your policy allows. A hold ends when its holder hands it back or stops renewing it. To release one sooner, a supervisor with theadminorownerrole hands the run back as their own operator, which needs an operator profile of their own.Design for repeats. A takeover repeated by the holder keeps the hold, and one from another operator returns
409. A repeated handback succeeds, and so does a handback on a run nobody holds. On a phone call a second operator's join returns409, and a handback returns404once the operator has left. A staged reply is sent at most once, as described in How a Staged Reply Behaves. Identical guidance sent twice in a short window is reported asdeduplicated.Stay inside the rate limits. Control calls (takeover, renew, handback, switch mode, authored turn, guidance, join, leave, wrap-up) allow 10 requests per minute. Reads allow 60. A run-addressed call is counted per credential, run, and operation, and an operator-addressed call per credential and operation. Renewing every 30 seconds uses 2 of the 10 requests a minute that the renew operation allows. Back off on
429and honorRetry-After. Poll rarely and use the event stream as a hint. See Rate Limits.Handle PHI in your UI. Transcripts, caller numbers, entity names, and staged text can contain protected health information. Keep them out of URLs, analytics, error trackers, and logs. Apply your own access controls and retention to anything your console stores.
Disclose monitoring where required. Do not rely on the platform to tell the caller that an operator has joined or is listening. Your organization decides what disclosure policy or law requires.
Plan for no operator. Takeover needs a person who is available. Define what happens when none is: a configured transfer, a callback task, or a bounded agent response. See Operators and Escalation.
Check the runtime. Offer phone takeover and guidance only for
session_providerconcurrence.
The handback on page close has two halves. In the operator's browser, send a beacon to your own server when the page is hidden. The beacon carries your session cookie, so treat the route like any other state-changing route in your app:
On your server, the route behind /operator/handback finds that operator's session, builds the client with operatorClient, and hands the run back with client.runs.handBack(runId, { operator_id }), as in the snippets above, and stops that run's renewal timer. The platform refuses a handback from an operator who does not hold the run, so a stale session cannot release another operator's hold.
Operations Used
Read a text conversation
GET /v1/{workspace_id}/conversations/{conversation_id}
conversations.get
Brief the operator
POST /v1/{workspace_id}/operators/{operator_id}/briefing
operators.createBriefing
Stage a reply
POST /v1/{workspace_id}/runs/{run_id}/authored-turn
runs.authorTurn
Read a staged reply
GET /v1/{workspace_id}/runs/{run_id}/authored-turn
runs.getAuthoredTurn
Record a wrap-up
POST /v1/{workspace_id}/operators/{operator_id}/wrap-up
operators.wrapUp
Reference
Runs: the run-addressed operations, takeover eligibility, and rate limits.
Operators: the operator-addressed operations.
SSE Events and Observer Events: the event catalogs.
Voice Agent: the observer stream and session event injection.
Authentication & API Keys and Choose Credentials: sign-in, tokens, and roles.
Platform SDK: installation, configuration, and error handling.
Operate and Improve a Workflow: where operator work fits in a run investigation.
Last updated
Was this helpful?

