Manage Sinch Voice applications, place outbound calls, query call state, and control conferences. All commands require voice application credentials (Application Key + Application Secret), which you add during sinch auth login.
The command tree mirrors the @sinch/voice SDK's four namespaces:
sinch voice
├── applications — callbacks + number assignments
├── callouts — outbound calls (TTS, conference dial-in, custom SVAML)
├── calls — query and control in-progress calls
└── conferences — manage conference rooms and participantsAll 17 leaf commands accept -a, --app-key <key> where applicable (defaults to the authenticated app) and --json for machine-readable output.
Get the webhook callback URLs configured for a Voice application.
sinch voice applications callbacks get [options]| Option | Description |
|---|---|
-a, --app-key <key> | Application key (defaults to the authenticated app) |
--json | Output as JSON |
--curl | Also print the equivalent curl command |
Set the primary (and optionally fallback) callback URL for a Voice application.
sinch voice applications callbacks set [url] [options]| Option | Description |
|---|---|
[url] | Primary URL. Prompts if omitted and interactive. |
-a, --app-key <key> | Application key |
--primary-only | Only set the primary URL, leave fallback unset |
--fallback <url> | Explicit fallback URL (default: same as primary) |
--non-interactive | Fail if URL is missing instead of prompting |
--debug | Print full error details on failure |
--json | Output as JSON |
Example
sinch voice applications callbacks set https://fn-abc123.functions.sinch.comNOTE: These commands manage numbers attached to a Voice application — i.e. which DIDs route to this app's webhook. This is not the same as the account-wide number inventory managed by
sinch numbers.
List voice-capable numbers on your account and their current application assignments. Pass -a to filter client-side to numbers bound to a specific app.
sinch voice applications numbers list [options]| Option | Description |
|---|---|
-a, --app-key <key> | Filter to numbers currently routed to this app |
--json | Output as JSON |
Query metadata (country, type, rate) for any phone number. Returns number details, not app-routing information.
sinch voice applications numbers get <number> [--json]Assign one or more numbers to a Voice application.
sinch voice applications numbers assign <numbers...> [-a <key>] [--capability voice|sms] [--json]Un-assign a number from a Voice application.
sinch voice applications numbers unassign <number> [-a <key>] [--capability voice|sms] [--json]Initiate outbound voice calls.
Place a text-to-speech outbound call.
sinch voice callouts tts <destination> <text> [options]| Option | Description |
|---|---|
<destination> | Phone number (+15551234567), sip:addr, or bare username |
<text> | Text to speak (≤600 characters) |
--voice <locale> | TTS voice or locale (default en-US) |
--cli <number> | Caller ID to display to the callee |
--dtmf <seq> | DTMF tones after pickup (0-9, #, w = 500ms pause) |
--domain <domain> | pstn or mxp (default: inferred from destination) |
--enable-ace | Request an ACE callback when the call is answered |
--enable-dice | Request a DiCE callback when the call disconnects |
--enable-pie | Request a PIE callback after menu interaction |
--json | Output as JSON |
Example
sinch voice callouts tts +15551234567 "Your package is arriving today" --voice en-USCall a phone number and connect them to a conference room. Creates the conference if it doesn't exist.
sinch voice callouts conference <destination> <conference-id> [options]| Option | Description |
|---|---|
--cli <number> | Caller ID |
--greeting <text> | Spoken greeting before joining |
--locale <locale> | TTS locale for the greeting |
--moh <music> | Music on hold while alone: ring, music1, music2, music3 |
--max-duration <seconds> | Maximum call duration |
--dtmf <seq> | DTMF tones after pickup |
--domain <domain> | pstn or mxp |
--json | Output as JSON |
Place a custom callout driven by inline SVAML (Sinch Voice Application Markup Language). At least one of --ice, --ace, or --pie is required.
sinch voice callouts custom [destination] [options]| Option | Description |
|---|---|
--ice <svaml> | ICE SVAML: inline JSON string or @path/to/file.json |
--ace <svaml> | ACE SVAML: inline JSON or @file.json |
--pie <svaml> | PIE SVAML: inline JSON or @file.json |
--cli <number> | Caller ID |
--dtmf <seq> | DTMF tones after pickup |
--max-duration <seconds> | Maximum call duration |
--json | Output as JSON |
Example
sinch voice callouts custom +15551234567 --ice @./ice-payload.jsonQuery and control in-progress calls. These methods apply to PSTN / SIP calls only.
Get information about an ongoing or completed call.
sinch voice calls get <call-id> [--json]Hang up an in-progress call (thin wrapper around voice calls update with the hangup SVAML action).
sinch voice calls hangup <call-id> [--json]Send a SVAML body to an in-progress call.
sinch voice calls update <call-id> --svaml <json-or-@file> [--json]| Option | Description |
|---|---|
<call-id> | The unique call ID |
--svaml <svaml> | SVAML body: inline JSON or @path/to/file.json (required) |
--json | Output as JSON |
The body is a JSON object with two fields:
action— required. The top-level call-control directive that runs after all instructions finish. An empty or missingactionis rejected witherrorCode: 40001 "SVAML 'action' must not be empty."instructions— optional. An array of things to run before the action (say text, play a file, start recording, etc.).
These are actions confirmed against a live call on a PSTN leg. The endpoint accepts only a narrow subset of the full SVAML action list — actions that re-route a call (for example connectPstn, connectMxp, connectConf) are rejected with errorCode: 40003 "Unknown SVAML action '<name>'" and are intended for initial-call routing via ICE callback responses, not for runtime updates of a connected call.
| Action | Works? | Notes |
|---|---|---|
{"name": "hangup"} | ✅ | Terminates the call. calls get afterwards shows reason: MANAGERHANGUP. |
{"name": "continue"} | ✅ | No-op "keep going" action. Used as a placeholder when instructions do the real work. |
{"name": "Say", ...} | ❌ | Say is an instruction, not an action. See example below for the correct wrapping. |
{"name": "connectPstn", ...} | ❌ | Re-routing is not supported on runtime updates. Use callouts custom to place a new leg instead. |
{"name": "park"} | ❌ | Not recognized on this endpoint. |
Case variants of connectPstn (ConnectPstn, ConnectPSTN, connectPSTN) all return the same 40003 error — the server preserves the name verbatim in the response.
sinch voice calls update <call-id> --svaml '{"action":{"name":"hangup"}}'Or equivalently, the thin wrapper:
sinch voice calls hangup <call-id>Say is an instruction and must be wrapped with a required action. The minimal "speak and keep going" shape:
sinch voice calls update <call-id> --svaml '{
"instructions": [
{"name": "Say", "text": "Your call is being transferred.", "locale": "en-US"}
],
"action": {"name": "continue"}
}'Note on conference audio paths: If the target call is a leg inside a conference, the server will accept this request (HTTP 200) but the Say audio may not be audible to the participant because the leg is mixed through the conference audio path. To play audio to a specific conference participant, use
sinch voice calls manage-legwith--leg calleeinstead (that endpoint is designed for per-leg audio injection).
Inject audio into a specific leg of a connected call. Intended for playing sound or speaking to one side of a PSTN / SIP call without affecting the other, including inside a conference.
sinch voice calls manage-leg <call-id> --leg caller|callee|both --svaml <json-or-@file> [--json]| Option | Description |
|---|---|
<call-id> | The unique call ID |
--leg <leg> | Which leg receives the audio: caller, callee, or both (required) |
--svaml <svaml> | SVAML body with PlayFiles or Say instructions (required) |
--json | Output as JSON |
The manage-leg endpoint is the SVAML-injection counterpart to calls update: instead of controlling call-control state, it plays audio into a specific leg's RTP path. Per the Sinch API docs only PlayFiles and Say instructions are valid here; other instruction types will be rejected by the server.
Known gap: The exact request-body layout for
SayandPlayFileson this endpoint was not fully reverse-engineered during the voice CLI rewrite's smoke testing — several payload variants returned400 Bad Request. See the Sinch SVAML reference at </docs/voice/api-reference/svaml/> for the authoritative shapes. Known-working examples will be added here as they are confirmed in production.
Manage conference rooms and their participants. Participants are identified by their per-leg call ID (from conferences get), not by phone number.
Get the participant list for a conference.
sinch voice conferences get <conference-id> [--json]Remove a single participant from a conference.
sinch voice conferences kick <conference-id> <call-id> [--json]Remove all participants from a conference. Prompts for confirmation by default.
sinch voice conferences kick-all <conference-id> [--yes] [--non-interactive] [--json]Mute/unmute or hold/resume a conference participant. Exactly one action flag is required.
sinch voice conferences manage <conference-id> <call-id> [--mute|--unmute|--hold|--resume] [--moh <music>] [--json]To play audio or speak text to a participant (as opposed to mute/hold them), use sinch voice calls manage-leg instead — those operations hit a different SDK method.
Voice commands use the Application Key + Application Secret that you provide during sinch auth login. The auth flow tests connectivity by calling getCallbackURLs — if that succeeds, all voice commands are ready to use.