sinch-voice-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sinch Voice API

Overview

概述

The 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.

Sinch Voice API允许你通过REST以编程方式发起、接收和控制语音呼叫。它使用SVAML（Sinch Voice应用标记语言）通过回调事件定义呼叫流程。

Agent Instructions

Agent使用说明

Before generating code, you MUST ask the user:

Approach — SDK or direct API calls (curl/fetch/requests)?
Language — Node.js, Python, Java, .NET, curl?

When generating SDK code, fetch the corresponding SDK reference page for accurate method signatures, or use the bundled examples:

Node.js examples | Python examples | Java examples | .NET examples

When generating direct API calls, use the Voice API Reference (Markdown) for request/response schemas.

在生成代码之前，你必须询问用户：

实现方式 — 使用SDK还是直接调用API（curl/fetch/requests）？
开发语言 — Node.js、Python、Java、.NET还是curl？

生成SDK代码时，请获取对应的SDK参考页面以确保方法签名准确，或使用提供的示例：

Node.js示例 | Python示例 | Java示例 | .NET示例

生成直接API调用代码时，请参考Voice API参考文档（Markdown）获取请求/响应架构。

Getting Started

快速开始

Authentication

身份验证

See the sinch-authentication skill. The Voice API uses Application Key + Application Secret (not project-level OAuth2).

Basic Auth:

Authorization: Basic base64(APPLICATION_KEY:APPLICATION_SECRET)

Signed Requests (production): HMAC-SHA256 signing. See Authentication Guide.

请查看sinch-authentication技能。Voice API使用应用密钥+应用密钥密码（而非项目级OAuth2）。

基础认证：

Authorization: Basic base64(APPLICATION_KEY:APPLICATION_SECRET)

签名请求（生产环境）：HMAC-SHA256签名。请参考身份验证指南。

Base URLs

基础URL

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

区域	基础URL
全球（默认）	`https://calling.api.sinch.com`
北美	`https://calling-use1.api.sinch.com`
欧洲	`https://calling-euc1.api.sinch.com`
东南亚1	`https://calling-apse1.api.sinch.com`
东南亚2	`https://calling-apse2.api.sinch.com`
南美	`https://calling-sae1.api.sinch.com`

配置端点（号码、回调）使用：

https://callingapi.sinch.com

SDK Installation

SDK安装

Language	Package	Install
Node.js	`@sinch/sdk-core`	`npm install @sinch/sdk-core`
Java	`com.sinch.sdk:sinch-sdk-java`	Maven dependency
Python	`sinch`	`pip3 install sinch`
.NET	`Sinch`	`dotnet add package Sinch`

语言	包名	安装命令
Node.js	`@sinch/sdk-core`	`npm install @sinch/sdk-core`
Java	`com.sinch.sdk:sinch-sdk-java`	Maven依赖
Python	`sinch`	`pip3 install sinch`
.NET	`Sinch`	`dotnet add package Sinch`

First API Call: TTS Callout

首次API调用：TTS呼叫发起

bash

curl -X POST "https://calling.api.sinch.com/calling/v1/callouts" \
  -H "Content-Type: application/json" \
  -u "YOUR_APPLICATION_KEY:YOUR_APPLICATION_SECRET" \
  -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:

javascript

import { SinchClient } from "@sinch/sdk-core";

const sinch = new SinchClient({
  applicationKey: "YOUR_APPLICATION_KEY",
  applicationSecret: "YOUR_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.

bash

curl -X POST "https://calling.api.sinch.com/calling/v1/callouts" \
  -H "Content-Type: application/json" \
  -u "YOUR_APPLICATION_KEY:YOUR_APPLICATION_SECRET" \
  -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示例：

javascript

import { SinchClient } from "@sinch/sdk-core";

const sinch = new SinchClient({
  applicationKey: "YOUR_APPLICATION_KEY",
  applicationSecret: "YOUR_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);

更多示例请查看呼叫发起参考文档或内置示例。

Key Concepts

核心概念

SVAML (Sinch Voice Application Markup Language)

SVAML（Sinch Voice应用标记语言）

SVAML controls call flow. Every SVAML response has:

instructions (array): Multiple tasks — play audio, record, set cookies
action (object): Exactly ONE routing/control action

Full reference: SVAML Actions | SVAML Instructions | Bundled SVAML Reference

SVAML用于控制呼叫流程。每个SVAML响应包含：

instructions（数组）：多个任务——播放音频、录音、设置Cookie
action（对象）：恰好一个路由/控制操作

完整参考：SVAML操作 | SVAML指令 | 内置SVAML参考文档

Actions (one per response)

操作（每个响应包含一个）

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

操作	描述
`hangup`	终止呼叫
`continue`	继续呼叫设置（ACE响应，用于无需重路由的情况）
`connectPstn`	连接到PSTN号码。支持 `amd` 进行答录机检测
`connectMxp`	连接到Sinch SDK（应用内）端点
`connectConf`	通过 `conferenceId` 连接到会议室
`connectSip`	连接到SIP端点
`connectStream`	连接到WebSocket服务器进行实时音频流（封闭测试版——请联系Sinch启用）
`runMenu`	支持DTMF输入的IVR菜单（支持 `enableVoice` 进行语音输入）
`park`	保持呼叫并循环播放提示音

Instructions (multiple per response)

指令（每个响应可包含多个）

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

指令	描述
`playFiles`	播放音频文件，通过 `#tts[]` 实现TTS，通过 `#ssml[]` 实现SSML
`say`	合成并播放文本转语音内容
`sendDtmf`	发送DTMF音调
`setCookie`	在会话的回调事件之间持久化键值对状态
`answer`	接听呼叫（向INVITE发送SIP 200 OK，开始计费）。在未接听的呼叫上播放提示音前必须执行此操作
`startRecording`	开始录音。支持 `transcriptionOptions` 进行自动转录
`stopRecording`	停止正在进行的录音

Callback Events

回调事件

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.

事件	触发条件	SVAML响应
ICE	Sinch平台接收到呼叫	需要
ACE	被叫方接听呼叫	需要
DiCE	呼叫断开	不需要（仅为通知事件，用于日志记录）
PIE	`runMenu` 产生的DTMF/语音输入	需要
Notify	通知事件（例如录音完成）	不需要

请查看回调参考文档获取事件架构，或查看内置回调参考文档获取完整字段表和JSON示例。

Callout Types

呼叫发起类型

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

Callout flags:

enableAce

(default

false

enableDice

(default

false

enablePie

(default

false

) control which callbacks fire.

方法	使用场景
`ttsCallout`	发起呼叫并播放合成语音。支持 `text` 或高级 `prompts` （ `#tts[]` 、 `#ssml[]` 、 `#href[]` ）
`conferenceCallout`	发起呼叫并连接到会议室
`customCallout`	通过内联ICE/ACE/PIE实现完整的SVAML控制

呼叫发起标志：

enableAce

（默认

false

）、

enableDice

（默认

false

）、

enablePie

（默认

false

）用于控制触发哪些回调事件。

REST Endpoints

REST端点

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

以

/calling/v1/

开头的路径使用上述表格中的区域基础URL。以

/v1/configuration/

开头的路径使用

https://callingapi.sinch.com

。

方法	端点	描述
POST	`/calling/v1/callouts`	发起呼叫（TTS、会议或自定义类型）
PATCH	`/calling/v1/calls/id/{callId}`	使用SVAML更新进行中的呼叫（仅支持PSTN/SIP）
GET	`/calling/v1/calls/id/{callId}`	获取呼叫信息
PATCH	`/calling/v1/calls/id/{callId}/leg/{callLeg}`	管理呼叫分支（仅支持PlayFiles/Say操作）
GET	`/calling/v1/conferences/id/{conferenceId}`	获取会议信息
DELETE	`/calling/v1/conferences/id/{conferenceId}`	踢出所有参会者
PATCH	`/calling/v1/conferences/id/{conferenceId}/{callId}`	静音/取消静音/保持参会者
DELETE	`/calling/v1/conferences/id/{conferenceId}/{callId}`	踢出指定参会者
GET	`/v1/configuration/numbers`	列出号码及其功能
POST	`/v1/configuration/numbers`	将号码分配给应用
DELETE	`/v1/configuration/numbers`	解除号码与应用的关联
GET/POST	`/v1/configuration/callbacks/applications/{applicationkey}`	获取/更新回调URL

Common Patterns

常见模式

IVR Menu (SVAML)

IVR菜单（SVAML）

json

{
  "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)" }
      ]
    }]
  }
}

json

{
  "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)" }
      ]
    }]
  }
}

Conference with Recording

带录音的会议

json

{
  "instructions": [
    { "name": "startRecording", "options": { "notificationEvents": true } }
  ],
  "action": {
    "name": "connectConf",
    "conferenceId": "myRoom",
    "moh": "ring"
  }
}

json

{
  "instructions": [
    { "name": "startRecording", "options": { "notificationEvents": true } }
  ],
  "action": {
    "name": "connectConf",
    "conferenceId": "myRoom",
    "moh": "ring"
  }
}

PSTN Forward with AMD

带AMD的PSTN呼叫转移

json

{
  "action": {
    "name": "connectPstn",
    "number": "+14045009000",
    "cli": "+14045001000",
    "maxDuration": 3600,
    "amd": { "enabled": true }
  }
}

json

{
  "action": {
    "name": "connectPstn",
    "number": "+14045009000",
    "cli": "+14045001000",
    "maxDuration": 3600,
    "amd": { "enabled": true }
  }
}

Executable Scripts

可执行脚本

Bundled Node.js scripts (no external dependencies, uses Basic Auth):

bash

export SINCH_APPLICATION_KEY="your-app-key"
export SINCH_APPLICATION_SECRET="your-app-secret"
export SINCH_VOICE_REGION="global"  # optional

Script	Description	Example
`make_tts_call.cjs`	TTS callout	`node scripts/make_tts_call.cjs --to +14045005000 --text "Hello"`
`make_conference_call.cjs`	Conference callout	`node scripts/make_conference_call.cjs --to +14045005000 --conference-id myRoom`
`get_call_info.cjs`	Get call details	`node scripts/get_call_info.cjs --call-id CALL_ID`
`list_numbers.cjs`	List voice numbers	`node scripts/list_numbers.cjs`

内置Node.js脚本（无外部依赖，使用基础认证）：

bash

export SINCH_APPLICATION_KEY="your-app-key"
export SINCH_APPLICATION_SECRET="your-app-secret"
export SINCH_VOICE_REGION="global"  # 可选

脚本	描述	示例
`make_tts_call.cjs`	TTS呼叫发起	`node scripts/make_tts_call.cjs --to +14045005000 --text "Hello"`
`make_conference_call.cjs`	会议呼叫发起	`node scripts/make_conference_call.cjs --to +14045005000 --conference-id myRoom`
`get_call_info.cjs`	获取呼叫详情	`node scripts/get_call_info.cjs --call-id CALL_ID`
`list_numbers.cjs`	列出语音号码	`node scripts/list_numbers.cjs`

Gotchas and Best Practices

注意事项与最佳实践

Callback URL must be publicly accessible. Use ngrok for local dev. Configure in Dashboard under Voice app settings.
ONE action per SVAML response. Multiple instructions are fine. Chain callbacks for sequential actions (ICE → ACE → PIE).
ACE not sent for in-app destinations. ACE is not issued when destination type is
```
username
```
, only for PSTN/SIP. Setting
```
enableAce: true
```
has no effect for in-app destinations.
DiCE is fire-and-forget. Informational only. No SVAML response expected. Use for logging/cleanup.
Regional endpoints matter. Wrong region increases latency. Conference rooms have regional scope — force all participants to the same region for cross-region conferences.
Instruction ordering matters. Array order = execution order. Place
```
answer
```
before
```
playFiles
```
; place
```
startRecording
```
before the connecting action.
Max call duration: 14400 seconds (4 hours). Set
```
maxDuration
```
on
```
connectPstn
```
/
```
connectSip
```
for shorter limits.
Validate callback signatures in production. HMAC-SHA256 signature in
```
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.

AMD on
connectPstn
.

amd: { enabled: true, async: true/false }

for answering machine detection.

startRecording
transcription.

transcriptionOptions: { enabled: true, locale: "en-US" }

for auto-transcription.

Conference DTMF options.

conferenceDtmfOptions

conferenceCallout

connectConf

with modes:

ignore

(default),

forward

detect

(sends PIE).

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.

回调URL必须可公开访问。本地开发时可使用ngrok。在控制台的Voice应用设置中配置。
每个SVAML响应只能包含一个action。可以包含多个指令。通过链式回调实现顺序操作（ICE → ACE → PIE）。
应用内目标不会触发ACE。当目标类型为
```
username
```
时，不会触发ACE事件，仅PSTN/SIP目标会触发。为应用内目标设置
```
enableAce: true
```
无效。
DiCE是通知型事件。仅用于信息告知，无需返回SVAML响应。可用于日志记录或清理操作。
区域端点很重要。错误的区域会增加延迟。会议室具有区域范围——跨区域会议需确保所有参会者使用同一区域。
指令顺序影响执行顺序。数组顺序即为执行顺序。在
```
playFiles
```
前执行
```
answer
```
；在连接操作前执行
```
startRecording
```
。
最大呼叫时长：14400秒（4小时）。可在
```
connectPstn
```
/
```
connectSip
```
中设置
```
maxDuration
```
以缩短时长限制。
生产环境需验证回调签名。
```
Authorization
```
头中的HMAC-SHA256签名。请参考回调签名。
使用
setCookie
存储状态。在ICE、ACE、PIE、DiCE事件之间的呼叫会话中携带键值对。
connectMxp
不支持录音。
```
startRecording
```
/
```
stopRecording
```
指令在使用
```
connectMxp
```
时会被忽略。
runMenu
默认值。
```
barge
```
:
```
true
```
（提示音播放期间可接受输入）。
```
timeoutMills
```
:
```
5000
```
毫秒。

connectPstn
的AMD功能。

amd: { enabled: true, async: true/false }

用于答录机检测。

startRecording
的转录功能。

transcriptionOptions: { enabled: true, locale: "en-US" }

用于自动转录。

会议DTMF选项。
```
conferenceCallout
```
/
```
connectConf
```
中的
```
conferenceDtmfOptions
```
支持模式：
```
ignore
```
（默认）、
```
forward
```
、
```
detect
```
（触发PIE）。
TTS呼叫发起需要
cli
。API接受不带
```
cli
```
参数的TTS呼叫发起并返回呼叫ID，但呼叫永远无法接通。
```
cli
```
是显示给被叫方的来电号码——请使用已验证的号码或控制台分配给应用的号码，格式为E.164（例如
```
"+14151112223333"
```
）。测试时，请在Sinch控制台注册并使用应用分配的免费号码。请参考分配你的号码。

sinch-voice-api

Original

Translation

Sinch Voice API

Sinch Voice API

Overview

概述

Agent Instructions

Agent使用说明

Getting Started

快速开始

Authentication

身份验证

Base URLs

基础URL

SDK Installation

SDK安装

First API Call: TTS Callout

首次API调用：TTS呼叫发起

Key Concepts

核心概念

SVAML (Sinch Voice Application Markup Language)

SVAML（Sinch Voice应用标记语言）

Actions (one per response)

操作（每个响应包含一个）

Instructions (multiple per response)

指令（每个响应可包含多个）

Callback Events

回调事件

Callout Types

呼叫发起类型

REST Endpoints

REST端点

Common Patterns

常见模式

IVR Menu (SVAML)

IVR菜单（SVAML）

Conference with Recording

带录音的会议

PSTN Forward with AMD

带AMD的PSTN呼叫转移

Executable Scripts

可执行脚本

Gotchas and Best Practices

注意事项与最佳实践

Links

相关链接