Back to Details

sinch-elastic-sip-trunking

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Sinch Elastic SIP Trunking API

Sinch Elastic SIP Trunking API

Overview

概述

The Sinch Elastic SIP Trunking (EST) API lets you programmatically provision SIP trunks and route voice traffic between customer infrastructure and the PSTN. The core workflow is: create a trunk, authorize it (ACL or credentials), attach endpoints, assign phone numbers.
Sinch Elastic SIP Trunking (EST) API允许你以编程方式配置SIP中继，并在客户基础设施与PSTN之间路由语音流量。核心工作流程为：创建中继、授权（ACL或凭证）、关联端点、分配电话号码。

Agent Instructions

Agent操作说明

Before generating code, ask the user these clarifying questions:
  1. Direction — Do you need inbound (receive calls from PSTN), outbound (send calls to PSTN), or both?
  2. Auth method for the trunk (if outbound or both) — ACL-based (static IPs) or Credential-based (digest auth / dynamic IPs)?
  3. Endpoint type (if inbound or both) — Static endpoint (fixed IP/port) or Registered endpoint (SIP UA registers dynamically)?
  4. Language — curl, Node.js SDK, Python, Java, .NET?
Only ask questions 2-3 when relevant to the user's direction. Wait for answers, then follow the matching workflow below.
在生成代码之前，请向用户询问以下澄清问题：
  1. 方向 — 你需要呼入（接收来自PSTN的呼叫）、呼出（向PSTN发起呼叫），还是两者都需要？
  2. 中继的认证方式（如果是呼出或两者都需要） — 基于ACL（静态IP）还是基于凭证（摘要认证/动态IP）？
  3. 端点类型（如果是呼入或两者都需要） — 静态端点（固定IP/端口）还是注册端点（SIP UA动态注册）？
  4. 语言 — curl、Node.js SDK、Python、Java、.NET？
仅在与用户的需求方向相关时询问问题2-3。等待用户回复后，遵循以下匹配的工作流程。

Decision Tree

决策树

User wants EST →
├─ Outbound only
│  ├─ Static IPs   → Workflow A (Trunk + ACL)
│  └─ Dynamic IPs  → Workflow E (Trunk + Credential List / Digest Auth)
├─ Inbound only
│  ├─ Static IP    → Workflow B (Trunk + Static Endpoint + Phone Number)
│  └─ Dynamic IP   → Workflow D (Trunk + Credential List + Registered Endpoint + Phone Number)
└─ Both           → Workflow C (Trunk + ACL/Creds + Endpoint + Phone Number)
User wants EST →
├─ Outbound only
│  ├─ Static IPs   → Workflow A (Trunk + ACL)
│  └─ Dynamic IPs  → Workflow E (Trunk + Credential List / Digest Auth)
├─ Inbound only
│  ├─ Static IP    → Workflow B (Trunk + Static Endpoint + Phone Number)
│  └─ Dynamic IP   → Workflow D (Trunk + Credential List + Registered Endpoint + Phone Number)
└─ Both           → Workflow C (Trunk + ACL/Creds + Endpoint + Phone Number)

Critical Rules

关键规则

  1. Dependency order matters. Creating resources out of order causes failures. 
    Create Trunk
    → 
    Create ACL/Credentials
    → 
    Link to Trunk
    → 
    Assign Phone Numbers
    → 
    Create Endpoint
  2. The Domain Trap. Never send SIP INVITEs to 
    trunk.pstn.sinch.com
    . ALWAYS use 
    {your-hostname}.pstn.sinch.com
    .
  3. 60-second propagation. After linking ACLs or Credentials, wait 60 seconds before testing.
  4. Lower priority = higher preference. Endpoint 
    priority: 1
    is primary; 
    priority: 100
    is failover.
  5. PUT replaces the entire object. Omitted fields become 
    null
    .
  1. 依赖顺序至关重要。资源创建顺序错误会导致失败。 
    Create Trunk
    → 
    Create ACL/Credentials
    → 
    Link to Trunk
    → 
    Assign Phone Numbers
    → 
    Create Endpoint
  2. 域名陷阱。切勿将SIP INVITE发送到
    trunk.pstn.sinch.com
    。请始终使用
    {your-hostname}.pstn.sinch.com
    。
  3. 60秒传播时间。关联ACL或凭证后，请等待60秒再进行测试。
  4. 优先级越低，优先级越高。端点
    priority: 1
    为主用；
    priority: 100
    为故障转移。
  5. PUT会替换整个对象。省略的字段会变为
    null
    。

Getting Started

快速开始

Authentication

认证

See sinch-authentication for full auth setup. EST uses OAuth2 client credentials (production) or Basic Auth (testing only, rate-limited).
完整的认证设置请参见sinch-authentication。EST使用OAuth2客户端凭证（生产环境）或基础认证（仅用于测试，有速率限制）。

SDK Installation

SDK安装

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

First API Call — Create a Trunk

首次API调用 — 创建中继

bash
curl -X POST "https://elastic-trunking.api.sinch.com/v1/projects/YOUR_PROJECT_ID/trunks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-trunk", "hostName": "my-trunk"}'
Response includes 
sipTrunkId
and 
hostName
— use 
{hostName}.pstn.sinch.com
for all SIP routing.
For SDK examples, see the Getting Started Guide.
bash
curl -X POST "https://elastic-trunking.api.sinch.com/v1/projects/YOUR_PROJECT_ID/trunks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-trunk", "hostName": "my-trunk"}'
响应包含
sipTrunkId
和
hostName
— 所有SIP路由请使用
{hostName}.pstn.sinch.com
。
有关SDK示例，请参见快速开始指南。

Key Concepts

核心概念

  • Trunk: Connection between your infrastructure and Sinch. Has a 
    hostName
    used in SIP routing.
  • SIP Endpoint: Where inbound calls go. Static (fixed IP) or Registered (dynamic, requires Credential List).
  • ACL: Authorizes outbound by source IP (CIDR notation, e.g. 
    203.0.113.10/32
    ).
  • Credential List: Username/password pairs. Used for registered endpoint auth (inbound) or digest auth (outbound).
  • Phone Numbers: E.164 DIDs assigned to a trunk for inbound routing.
  • 中继（Trunk）：你的基础设施与Sinch之间的连接。拥有一个用于SIP路由的
    hostName
    。
  • SIP端点：呼入呼叫的目标地址。分为静态（固定IP）或注册（动态，需要凭证列表）。
  • ACL：通过源IP（CIDR表示法，例如
    203.0.113.10/32
    ）授权呼出。
  • 凭证列表：用户名/密码对。用于注册端点认证（呼入）或摘要认证（呼出）。
  • 电话号码：分配给中继的E.164格式DID号码，用于呼入路由。

Workflows

工作流程

Workflow A: Outbound Only (ACL-based)

工作流程A：仅呼出（基于ACL）

  • 1. Create trunk
  • 2. Create ACL with your source IPs
  • 3. Link ACL to trunk
  • 4. Wait 60 seconds
  • 5. Verify: 
    GET /trunks/{trunkId}/accessControlLists
    — confirm ACL appears
API docs: Create trunk → Create ACL → Link ACL to trunk → List ACLs for trunk
  • 1. 创建中继
  • 2. 创建包含你的源IP的ACL
  • 3. 将ACL关联到中继
  • 4. 等待60秒
  • 5. 验证：
    GET /trunks/{trunkId}/accessControlLists
    — 确认ACL已显示
API文档：创建中继 → 创建ACL → 将ACL关联到中继 → 列出中继的ACL

Workflow B: Inbound Only (Static Endpoint)

工作流程B：仅呼入（静态端点）

  • 1. Create trunk
  • 2. Create static SIP endpoint on trunk
  • 3. Assign phone number(s) to trunk
  • 4. Verify: 
    GET /trunks/{trunkId}/endpoints
    and 
    GET /trunks/{trunkId}/phoneNumbers
API docs: Create trunk → Create SIP endpoint → Get phone numbers
  • 1. 创建中继
  • 2. 在中继上创建静态SIP端点
  • 3. 为中继分配电话号码
  • 4. 验证：
    GET /trunks/{trunkId}/endpoints
    和 
    GET /trunks/{trunkId}/phoneNumbers
API文档：创建中继 → 创建SIP端点 → 获取电话号码

Workflow C: Bidirectional (Both Inbound + Outbound)

工作流程C：双向（呼入+呼出）

  • 1. Create trunk
  • 2. Create ACL and/or Credential List → Link to trunk
  • 3. Create SIP endpoint on trunk
  • 4. Assign phone numbers to trunk
  • 5. Wait 60 seconds before testing
  • 6. Verify: 
    GET /trunks/{trunkId}/accessControlLists
    , 
    GET /trunks/{trunkId}/endpoints
    , 
    GET /trunks/{trunkId}/phoneNumbers
API docs: Create trunk → Create ACL → Link ACL to trunk → Create SIP endpoint → Get phone numbers
  • 1. 创建中继
  • 2. 创建ACL和/或凭证列表 → 关联到中继
  • 3. 在中继上创建SIP端点
  • 4. 为中继分配电话号码
  • 5. 测试前等待60秒
  • 6. 验证：
    GET /trunks/{trunkId}/accessControlLists
    、
    GET /trunks/{trunkId}/endpoints
    、
    GET /trunks/{trunkId}/phoneNumbers
API文档：创建中继 → 创建ACL → 将ACL关联到中继 → 创建SIP端点 → 获取电话号码

Workflow D: Inbound with Registered Endpoint (Credential-based)

工作流程D：呼入（带注册端点，基于凭证）

  • 1. Create trunk
  • 2. Create credential list with username/password
  • 3. Create registered endpoint on trunk (references a username from the credential list)
  • 4. Assign phone number(s) to trunk
  • 5. Configure SIP UA to REGISTER to 
    {hostname}.pstn.sinch.com
  • 6. Verify: 
    GET /trunks/{trunkId}/endpoints
    and 
    GET /trunks/{trunkId}/phoneNumbers
API docs: Create trunk → Credential Lists → Create SIP endpoint → Get phone numbers
  • 1. 创建中继
  • 2. 创建包含用户名/密码的凭证列表
  • 3. 在中继上创建注册端点（引用凭证列表中的用户名）
  • 4. 为中继分配电话号码
  • 5. 配置SIP UA向
    {hostname}.pstn.sinch.com
    发起REGISTER请求
  • 6. 验证：
    GET /trunks/{trunkId}/endpoints
    和 
    GET /trunks/{trunkId}/phoneNumbers
API文档：创建中继 → 凭证列表 → 创建SIP端点 → 获取电话号码

Workflow E: Outbound Only (Digest Auth / Credential-based)

工作流程E：仅呼出（摘要认证/基于凭证）

  • 1. Create trunk
  • 2. Create credential list with username/password
  • 3. Link credential list to trunk
  • 4. Wait 60 seconds
  • 5. Verify: 
    GET /trunks/{trunkId}/credentialLists
    — confirm credential list appears
API docs: Create trunk → Credential Lists → Add credential list to trunk → List credential lists for trunk
  • 1. 创建中继
  • 2. 创建包含用户名/密码的凭证列表
  • 3. 将凭证列表关联到中继
  • 4. 等待60秒
  • 5. 验证：
    GET /trunks/{trunkId}/credentialLists
    — 确认凭证列表已显示
API文档：创建中继 → 凭证列表 → 将凭证列表关联到中继 → 列出中继的凭证列表

SIP Header Rules (Outbound)

呼出SIP头规则

HeaderValueNotes
From
sip:+1E164@{your-hostname}.pstn.sinch.com
Must be your trunk domain. Wrong domain → 403. Use E.164 format.
To
sip:+1E164@{your-hostname}.pstn.sinch.com
Destination in E.164 + your trunk domain. In most cases, same as Request-URI.
Request-URI
sip:+1E164@{your-hostname}.pstn.sinch.com
Destination in E.164 + your trunk domain. In most cases, same as To.
头字段值说明
From
sip:+1E164@{your-hostname}.pstn.sinch.com
必须是你的中继域名。域名错误会返回403。使用E.164格式。
To
sip:+1E164@{your-hostname}.pstn.sinch.com
目标地址采用E.164格式+你的中继域名。大多数情况下与Request-URI相同。
Request-URI
sip:+1E164@{your-hostname}.pstn.sinch.com
目标地址采用E.164格式+你的中继域名。大多数情况下与To相同。

Gotchas and Best Practices

注意事项与最佳实践

  1. CIDR notation — ACL entries require CIDR (
    /32
    for single IP, 
    /24
    for range).
  2. Country permissions — US/Canada enabled by default. Other countries blocked; use 
    updateCountryPermissions
    .
  3. Project ID ≠ App Key — EST uses 
    projectId
    , not the Voice Application Key.
  4. Default CPS limit — 1 call per second. Exceeding it → 603. Contact Sinch to increase.
  5. Teardown order — Delete in reverse: unassign phone numbers → delete endpoints → unlink ACLs/credentials → delete trunk. Deleting out of order can orphan resources.
  1. CIDR表示法 — ACL条目需要使用CIDR格式（单个IP用
    /32
    ，IP段用
    /24
    ）。
  2. 国家权限 — 美国/加拿大默认启用。其他国家默认被阻止；请使用
    updateCountryPermissions
    开启。
  3. Project ID ≠ App Key — EST使用
    projectId
    ，而非语音应用密钥。
  4. 默认CPS限制 — 每秒1次呼叫。超过限制会返回603。请联系Sinch提升限制。
  5. 销毁顺序 — 按相反顺序删除资源：解绑电话号码 → 删除端点 → 取消关联ACL/凭证 → 删除中继。顺序错误可能导致资源残留。

Troubleshooting

故障排除

For SIP error codes and debugging runbooks, see references/diagnostics.md.
Quick reference:
  • 401 → Credential mismatch in Credential List
  • 403 → IP not in ACL, or wrong 
    From
    domain
  • 404 → Using wrong SIP domain (must be 
    {hostname}.pstn.sinch.com
    )
  • 503 → No active endpoint on trunk
有关SIP错误码和调试手册，请参见references/diagnostics.md。
快速参考：
  • 401 → 凭证列表中的凭证不匹配
  • 403 → IP不在ACL中，或
    From
    域名错误
  • 404 → 使用了错误的SIP域名（必须为
    {hostname}.pstn.sinch.com
    ）
  • 503 → 中继上无活动端点

References

参考资料

Links

链接