Skip to main content
Your backend can step into a call while it is in progress. It works on every voice call: phone calls you place, campaign and inbound calls, browser calls and realtime sessions.
Send controls from your backend with your API key. They never go in a browser.

Control types

interrupt decides what happens when the agent is talking:
  • true cuts the agent off and speaks or plays right away.
  • false (the default) waits for the agent to finish its sentence, up to 8 seconds.
A field that does not belong to the type, such as interrupt on an instruction or message on a say, is 400 invalid_request.

Tell the agent something, or say it now

Say the owner approves a discount while the agent is still negotiating on a phone call. An instruction shapes the agent’s next reply. A say puts the words on the line straight away.
200 OK
A say line becomes part of the conversation. It is in the transcript, and the agent knows it said it.

Play an audio clip

Give a link to the clip:
Or upload the file itself as multipart/form-data, with the clip in a file part named audio. Other controls are always sent as JSON.
  • The clip is WAV, MP3, OGG or FLAC, at most 2 MB and 60 seconds. It is converted to the call’s audio format, so a phone line and a browser both play it correctly.
  • audio_url must be https on a public host. Private and internal addresses are refused. The clip is fetched once, when you send the control, and redirects are not followed. If the fetch fails, the answer is 400 audio_unavailable with the reason, and nothing plays.
  • The agent is told a clip was played, so it can respond naturally if the caller reacts to it.
A caller who talks over a say line or a clip cuts it off, the same as any reply from the agent.

Responses

The request waits up to 3 seconds for the call to confirm the control.
Controls can be read for an hour after the call ends. Idempotency. Send an Idempotency-Key. A repeat with the same key returns the same control and is never delivered twice, so a retry cannot make the agent say something twice. The same key with a different body is 409 conflict. Events. The live event stream sends control.applied when a control takes effect, and control.completed when a say or play has finished on the line. Billing. Controls cost nothing extra. The call is billed per minute as usual.

Errors

Close or abort

A close control ends a call with a goodbye. To stop a call at once with no goodbye, use POST /v2/calls/{id}/abort.

Privacy

  • The text of an instruction or a say is never echoed in responses or in the event stream. A say line appears in the transcript, like anything the agent says.
  • A clip is used only to play it on that call. It is not kept after it has played.
  • If a clip carries a recorded voice, make sure you have the right to use it, and tell callers about recordings where your rules require it.