# sinch voice

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 participants
```

All 17 leaf commands accept `-a, --app-key <key>` where applicable (defaults to the authenticated app) and `--json` for machine-readable output.

## sinch voice applications

### sinch voice applications callbacks get

Get the webhook callback URLs configured for a Voice application.


```sh
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 |


### sinch voice applications callbacks set

Set the primary (and optionally fallback) callback URL for a Voice application.


```sh
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**


```sh
sinch voice applications callbacks set https://fn-abc123.functions.sinch.com
```

### sinch voice applications numbers

> **NOTE:** 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`.


#### sinch voice applications numbers list

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.


```sh
sinch voice applications numbers list [options]
```

| Option | Description |
|  --- | --- |
| `-a, --app-key <key>` | Filter to numbers currently routed to this app |
| `--json` | Output as JSON |


#### sinch voice applications numbers get

Query metadata (country, type, rate) for any phone number. Returns number details, **not** app-routing information.


```sh
sinch voice applications numbers get <number> [--json]
```

#### sinch voice applications numbers assign

Assign one or more numbers to a Voice application.


```sh
sinch voice applications numbers assign <numbers...> [-a <key>] [--capability voice|sms] [--json]
```

#### sinch voice applications numbers unassign

Un-assign a number from a Voice application.


```sh
sinch voice applications numbers unassign <number> [-a <key>] [--capability voice|sms] [--json]
```

## sinch voice callouts

Initiate outbound voice calls.

### sinch voice callouts tts

Place a text-to-speech outbound call.


```sh
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**


```sh
sinch voice callouts tts +15551234567 "Your package is arriving today" --voice en-US
```

### sinch voice callouts conference

Call a phone number and connect them to a conference room. Creates the conference if it doesn't exist.


```sh
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 |


### sinch voice callouts custom

Place a custom callout driven by inline SVAML (Sinch Voice Application Markup Language). At least one of `--ice`, `--ace`, or `--pie` is required.


```sh
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**


```sh
sinch voice callouts custom +15551234567 --ice @./ice-payload.json
```

## sinch voice calls

Query and control in-progress calls. These methods apply to PSTN / SIP calls only.

### sinch voice calls get

Get information about an ongoing or completed call.


```sh
sinch voice calls get <call-id> [--json]
```

### sinch voice calls hangup

Hang up an in-progress call (thin wrapper around `voice calls update` with the hangup SVAML action).


```sh
sinch voice calls hangup <call-id> [--json]
```

### sinch voice calls update

Send a SVAML body to an in-progress call.


```sh
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 |


#### SVAML body shape

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 missing `action` is rejected with `errorCode: 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.).


#### Actions verified against `calls update`

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.

#### Example: hang up a live call


```sh
sinch voice calls update <call-id> --svaml '{"action":{"name":"hangup"}}'
```

Or equivalently, the thin wrapper:


```sh
sinch voice calls hangup <call-id>
```

#### Example: say text to a live call mid-flight

`Say` is an instruction and must be wrapped with a required `action`. The minimal "speak and keep going" shape:


```sh
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-leg` with `--leg callee` instead (that endpoint is designed for per-leg audio injection).


### sinch voice calls manage-leg

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.


```sh
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 `Say` and `PlayFiles` on this endpoint was not fully reverse-engineered during the voice CLI rewrite's smoke testing — several payload variants returned `400 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.


## sinch voice conferences

Manage conference rooms and their participants. Participants are identified by their per-leg call ID (from `conferences get`), not by phone number.

### sinch voice conferences get

Get the participant list for a conference.


```sh
sinch voice conferences get <conference-id> [--json]
```

### sinch voice conferences kick

Remove a single participant from a conference.


```sh
sinch voice conferences kick <conference-id> <call-id> [--json]
```

### sinch voice conferences kick-all

Remove all participants from a conference. Prompts for confirmation by default.


```sh
sinch voice conferences kick-all <conference-id> [--yes] [--non-interactive] [--json]
```

### sinch voice conferences manage

Mute/unmute or hold/resume a conference participant. Exactly one action flag is required.


```sh
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.

## Authentication

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.