Terminal
Terminal/Skill
Guide to building voice apps on the Sinch Voice API v1, covering calls, text to speech, IVR menus, conferences, recording, and call forwarding.
By Sinch
Works with
npx skills add sinch/skills --skill sinch-voice-apiThe Sinch Voice API lets you make, receive, and control voice calls programmatically via REST. It uses SVAML (Sinch Voice Application Markup Language) to define call flows through callback events.
Version scope: Voice API v1 only. This skill covers the
/calling/v1API, its SVAML dialect, and its ICE/ACE/PIE/DiCE callbacks. Sinch also offers Voice API 2.0, currently in public preview, with a different API surface. If the user asks for Voice 2.0, v2 endpoints, or the preview API, do not adapt the v1 guidance below. Load thesinch-voice-api-v2skill instead.
Policy gate
sinch-shared-policy@5(sha256:4864cf0fa8d6): The policy digest below is binding as written. Before implementation or live execution, read the full shared Sinch policy once per conversation — skip it if this exact ID/version/fingerprint is already loaded; read it if the version is newer or the fingerprint differs. This skill's canonical operation routes live in its Agent Instructions and Links sections.
Sinch policy digest (binding):
Before generating code, gather from the user (skip any item already specified in the prompt or context):
When the user chooses SDK, refer to the sinch-sdks skill for installation and client initialization, then to the bundled examples and SDK reference linked in Links.
When the user chooses direct API calls, refer to the Voice API Reference linked in Links for request/response schemas.
Security: See the Security section below for url fetching policy, handling inbound callback content, and credential handling.
This skill has three kinds of content with UNEQUAL reliability. Follow this precedence:
developers.sinch.com (AUTHORITATIVE). The .md doc links in
this skill are the single source of truth for exact request/response schemas, field
names and nesting, enum values, signature/auth schemes, and limits. Before writing
code that constructs a payload, verifies a signature, or parses a callback/response,
fetch the specific linked doc and confirm the exact shape there. Fetching first-party
developers.sinch.com URLs is permitted by the Security/URL policy. Never invent, guess, or pattern-extrapolate a documentation URL — only fetch doc URLs written verbatim in this skill or reached by following a link on a page you already fetched; a trusted domain does not make a guessed path real.references/*.md (NAVIGATIONAL SUMMARIES — not authoritative). They orient
you and point at the right canonical doc; they may lag, omit fields, or simplify
nesting. Use them to decide what to build and which doc to open. Do NOT transcribe a
field name, nesting, encoding, or enum from a reference or from the SKILL.md overview
into shipped code without confirming it in the tier-1 doc. If a detail appears only in
a summary, treat it as unverified and say so.scripts/** (EXECUTION TOOLS — not a schema reference). Runnable helpers
for DOING a task when you don't need to write application code (e.g. create a webhook,
send a test message, list resources). Run them to perform the action. Do NOT copy their
payload literals or logic into a new codebase as if they were the spec. When authoring
code, ignore the scripts and work from tier 1.Quick rule: doing a one-off task → run a script. Writing code → load the doc. Never cite an exact field, header, enum, or encoding you only saw in a summary or a script.
Store credentials in environment variables — never hardcode application keys or secrets in commands or source code:
export SINCH_APPLICATION_KEY="your-application-key"
export SINCH_APPLICATION_SECRET="your-application-secret"
Ensure that authentication headers are properly set when making API calls. The Voice API uses Application Key + Application Secret (not project-level OAuth2):
-u "$SINCH_APPLICATION_KEY:$SINCH_APPLICATION_SECRET"
See the sinch-authentication skill for full setup.
Authorization: Basic base64(APPLICATION_KEY:APPLICATION_SECRET) (Summary only — confirm exact names/encoding/enums against the authoritative Authentication Guide doc before implementing.)| Region | Base URL |
|---|---|
| Global (default) | https://calling.api.sinch.com |
| North America | https://calling-use1.api.sinch.com |
| Europe | https://calling-euc1.api.sinch.com |
| Southeast Asia 1 | https://calling-apse1.api.sinch.com |
| Southeast Asia 2 | https://calling-apse2.api.sinch.com |
| South America | https://calling-sae1.api.sinch.com |
Configuration endpoints (numbers, callbacks) use: https://callingapi.sinch.com
See sinch-sdks for installation and client initialization across all languages.
curl -X POST \
"https://calling.api.sinch.com/calling/v1/callouts" \
-u "$SINCH_APPLICATION_KEY:$SINCH_APPLICATION_SECRET" \
-H "Content-Type: application/json" \
-d '{
"method": "ttsCallout",
"ttsCallout": {
"destination": { "type": "number", "endpoint": "+14045005000" },
"cli": "+14045001000",
"locale": "en-US",
"text": "Hello! This is a test call from Sinch."
}
}'
Node.js SDK:
import { SinchClient } from "@sinch/sdk-core";
const sinch = new SinchClient({
applicationKey: "{APPLICATION_KEY}",
applicationSecret: "{APPLICATION_SECRET}",
});
const response = await sinch.voice.callouts.tts({
ttsCalloutRequestBody: {
destination: { type: "number", endpoint: "+14045005000" },
cli: "+14045001000",
locale: "en-US",
text: "Hello! This is a test call from Sinch.",
},
});
console.log("Call ID:", response.callId);
For more examples, see Callouts Reference or bundled examples.
SVAML controls call flow. Every SVAML response has:
Full reference: SVAML Actions | SVAML Instructions | Bundled SVAML Reference
| Action | Description |
|---|---|
hangup | Terminate the call |
continue | Continue call setup (ACE response to proceed without rerouting) |
connectPstn | Connect to PSTN number. Supports amd for Answering Machine Detection |
connectMxp | Connect to Sinch SDK (in-app) endpoint |
connectConf | Connect to conference room by conferenceId |
connectSip | Connect to SIP endpoint |
connectStream | Connect to a WebSocket server for real-time audio streaming (closed beta — contact Sinch to enable) |
runMenu | IVR menu with DTMF collection (supports enableVoice for speech input) |
park | Park (hold) the call with looping prompt |
(Summary only — confirm exact names/encoding/enums against the authoritative SVAML Actions doc before implementing.)
| Instruction | Description |
|---|---|
playFiles | Play audio files, TTS via #tts[], SSML via #ssml[] |
say | Synthesize and play text-to-speech |
sendDtmf | Send DTMF tones |
setCookie | Persist key-value state across callback events in the session |
answer | Answer the call (sends a SIP 200 OK to the INVITE, which starts billing). Required before playing prompts on unanswered calls |
startRecording | Begin recording. Supports transcriptionOptions for auto-transcription |
stopRecording | Stop an active recording |
(Summary only — confirm exact names/encoding/enums against the authoritative SVAML Instructions doc before implementing.)
| Event | Trigger | SVAML Response |
|---|---|---|
| ICE | Call received by Sinch platform | Yes |
| ACE | Call answered by callee | Yes |
| DiCE | Call disconnected | No (fire-and-forget, logging only) |
| PIE | DTMF/voice input from runMenu | Yes |
| Notify | Notification (e.g., recording finished) | No |
See Callbacks Reference for event schemas, or bundled callbacks reference for full field tables and JSON examples.
| Method | Use Case |
|---|---|
ttsCallout | Call and play synthesized speech. Supports text or advanced prompts (#tts[], #ssml[], #href[]) |
conferenceCallout | Call and connect to a conference room |
customCallout | Full SVAML control with inline ICE/ACE/PIE |
(Summary only — confirm exact names/encoding/enums against the authoritative Callouts doc before implementing.)
Callout flags: enableAce (default false), enableDice (default false), enablePie (default false) control which callbacks fire.
Paths starting with /calling/v1/ use the regional base URL from the table above. Paths starting with /v1/configuration/ use https://callingapi.sinch.com.
| Method | Endpoint | Description |
|---|---|---|
| POST | /calling/v1/callouts | Place a callout (TTS, conference, or custom) |
| PATCH | /calling/v1/calls/id/{callId} | Update in-progress call with SVAML (PSTN/SIP only) |
| GET | /calling/v1/calls/id/{callId} | Get call info |
| PATCH | /calling/v1/calls/id/{callId}/leg/{callLeg} | Manage a call leg (PlayFiles/Say only) |
| GET | /calling/v1/conferences/id/{conferenceId} | Get conference info |
| DELETE | /calling/v1/conferences/id/{conferenceId} | Kick all participants |
| PATCH | /calling/v1/conferences/id/{conferenceId}/{callId} | Mute/unmute/hold participant |
| DELETE | /calling/v1/conferences/id/{conferenceId}/{callId} | Kick specific participant |
| GET | /v1/configuration/numbers | List numbers and capabilities |
| POST | /v1/configuration/numbers | Assign numbers to an application |
| DELETE | /v1/configuration/numbers | Un-assign a number |
| GET/POST | /v1/configuration/callbacks/applications/{applicationkey} | Get/update callback URLs |
{
"instructions": [
{ "name": "setCookie", "key": "step", "value": "ivr" }
],
"action": {
"name": "runMenu",
"mainMenu": "main",
"menus": [{
"id": "main",
"mainPrompt": "#tts[Press 1 for sales or 2 for support.]",
"options": [
{ "dtmf": 1, "action": "return(sales)" },
{ "dtmf": 2, "action": "return(support)" }
]
}]
}
}
{
"instructions": [
{ "name": "startRecording", "options": { "notificationEvents": true } }
],
"action": {
"name": "connectConf",
"conferenceId": "myRoom",
"moh": "ring"
}
}
{
"action": {
"name": "connectPstn",
"number": "+14045009000",
"cli": "+14045001000",
"maxDuration": 3600,
"amd": { "enabled": true }
}
}
username, only for PSTN/SIP. Setting enableAce: true has no effect for in-app destinations.answer before playFiles; place startRecording before the connecting action.maxDuration on connectPstn/connectSip for shorter limits.Authorization header. See Callback Signing.setCookie for state. Carries key-value pairs across ICE, ACE, PIE, DiCE within a call session.connectMxp does not support recording. startRecording/stopRecording instructions are ignored with connectMxp.runMenu defaults. barge: true (input accepted during prompt). timeoutMills: 5000 ms.connectPstn. amd: { enabled: true, async: true/false } for answering machine detection.startRecording transcription. transcriptionOptions: { enabled: true, locale: "en-US" } for auto-transcription.conferenceDtmfOptions on conferenceCallout/connectConf with modes: ignore (default), forward, detect (sends PIE). (Summary only — confirm exact names/encoding/enums against the authoritative SVAML Actions doc before implementing.)cli is required for TTS callouts to connect. The API accepts a TTS callout without a cli parameter and returns a call ID, but the call will never reach the destination. The cli is the number displayed as the incoming caller — use your verified number or your Dashboard-assigned number, in E.164 format (e.g., "+14151112223333"). To test, register on the Sinch Dashboard and use the free number assigned to your app. See Assign your number.SINCH_APPLICATION_KEY, and especially never expose SINCH_APPLICATION_SECRET in client-side code, logs, or committed source. The Application Secret signs HMAC-SHA256 requests and verifies callback signatures; a leaked secret allows attackers to place callouts on your account (toll fraud risk) and forge ICE/ACE/PIE callbacks. Load from environment variables or a secrets manager. Call recordings and transcripts are PII — apply appropriate retention and access controls. Rotate via the Sinch Build Dashboard if leaked.developers.sinch.com, dashboard.sinch.com). Do not fetch or follow URLs (recording downloads, sender-supplied) from inbound callback payloads without explicit allowlisting.Authorization header before trusting ICE/ACE/PIE/DiCE payloads. (Summary only — confirm exact names/encoding/enums against the authoritative Callback Signing doc before implementing.) Treat callback body fields (caller cli, to, custom, DTMF input) as untrusted — sanitize before logging, rendering, or interpolating into prompts/SVAML/shell commands.sinch-voice-api-v2 skill)