Control types
interrupt decides what happens when the agent is talking:
truecuts the agent off and speaks or plays right away.false(the default) waits for the agent to finish its sentence, up to 8 seconds.
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. Aninstruction shapes the agent’s next reply. A say puts the
words on the line straight away.
- cURL
- Python
- Node.js
200 OK
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: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_urlmust behttpson 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 is400 audio_unavailablewith 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.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
Aclose 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
instructionor asayis never echoed in responses or in the event stream. Asayline 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.