Voice: the Voice API
Place and control calls from your code: dial with detection, connect on answer, speak, play, gather, record, stream, transfer.
Every call is a leg with an id. You start a leg with POST /v1/voice/calls (or an inbound call starts one for you), then send it commands; everything that happens to it arrives at your webhook. Your client_state, if you send one, comes back on every event for that leg, so your server never has to look anything up.
Placing a call
curl https://api.dialerseat.com/v1/voice/calls \
-H "Authorization: Bearer dsk_live_..." \
-H "Content-Type: application/json" \
-d '{
"connection_id": "conn_7f3a...",
"from": "+12145550100",
"to": "+15125550142",
"answering_machine_detection": "detect_beep",
"link_to": "v3:agent-leg...",
"bridge_on_answer": true,
"timeout_secs": 25,
"time_limit_secs": 3600,
"client_state": "bGVhZDo0Mg=="
}'- to: a US number or a SIP address. from: a number on your account.
- connection_id: the SIP connection or voice application placing it.
- answering_machine_detection: off by default; see Answering-machine detection.
- link_to and bridge_on_answer: connect this leg to another live leg (an agent) the instant it is answered.
- park_after_unbridge: self keeps this leg up when the other side hangs up, for the next call; otherwise both end together.
- timeout_secs: how long it rings, 5 to 120 (30 by default). time_limit_secs: a hard stop, up to 14,400 (four hours).
- record: record-from-answer. client_state: up to 4,096 base64 characters.
The power dialer pattern
This is how DialerSeat's own dialer works. Dial the agent's browser or phone first and leave that leg up. For each lead, dial with link_to the agent's leg, bridge_on_answer and detection on. A person who answers is connected at once; a machine is detected and hung up, and the agent never hears it. With park_after_unbridge: self on the agent's leg, the agent stays connected between leads.
Commands
- answer: Pick up an inbound call that is ringing your application.
- reject: Turn an inbound call away with busy or rejected, before answering.
- hangup: End the call.
call.hangupfollows with the cause. - bridge: Connect this call to another live call so the two parties hear each other.
- transfer: Send the call to a new number or SIP address and drop out of it.
- speak: Read text to the call in a chosen voice.
- playback_start: Play an MP3 or WAV from a URL, once or on a loop.
- playback_stop: Stop what is playing.
- gather_using_speak: Read a prompt and collect keypad digits, with a timeout and a terminating key.
- gather_using_audio: Play a recording and collect keypad digits.
- gather_stop: End a gather early.
- send_dtmf: Press keys on the far end, for an IVR or an extension.
- record_start: Record the call, one channel or two, to MP3 or WAV.
- record_stop: Stop and save.
call.recording.savedfollows with the file. - record_pause: Pause, for example while a card number is read.
- record_resume: Carry on recording into the same file.
- streaming_start: Send the call's audio, live, to your WebSocket: for transcription or an AI agent.
- streaming_stop: Stop the stream.
- client_state_update: Replace the state DialerSeat echoes back on every event for this call.
- refer: Ask a SIP endpoint to take the call elsewhere.
A command sent at the wrong moment, such as speak before the call is answered or record_stop with nothing recording, is refused with invalid_state and a plain reason, never silently ignored.
How calls end
call.hangup carries the hangup_cause, the SIP code and who hung up (caller, callee, api or system). The causes: normal_clearing, user_busy, no_answer, call_rejected, unallocated_number, timeout, time_limit, originator_cancel, destination_out_of_order, invalid_number_format, insufficient_balance, channel_limit, spend_limit, not_allowed_destination, unspecified.
Related:DialerSeat Voice: numbers, SIP and a voice API, Voice: numbers, porting and 911, Voice: SIP trunking and Voice: answering-machine detection.