sinch-sdks

Sinch SDK

概览

涵盖所有 Sinch 产品的 SDK 安装和客户端初始化的跨领域技能。确定正确的 SDK，并提供各语言的初始化代码。

有关身份验证设置（凭据、OAuth2、Basic auth、签名请求），请参阅 sinch-authentication。有关应用内通话 SDK（Browser、iOS、Android），请参阅 sinch-in-app-calling。

Agent 指令

策略门控 sinch-shared-policy@5（sha256:4864cf0fa8d6）： 以下策略摘要具有约束力，必须按原文执行。在实施或实时执行之前，每次对话都要阅读完整的 Sinch 共享策略一次；如果此对话中已加载完全相同 ID、版本和指纹的策略，则跳过；如果版本更新或指纹不同，则重新阅读。本技能的规范操作路由位于其 Agent 指令和链接部分。

Sinch 策略摘要（具有约束力）：

1. 每次对话加载一次共享策略；跳过具有相同 ID、版本和指纹的重复副本。
2. 根据请求和工作区推断产品、语言、区域和环境；仅在确有阻碍时才提出一个合并问题。优先使用官方 Sinch SDK，除非请求或工作区另有要求，或者没有官方 SDK 支持该语言或操作。
3. 代码生成的批准不等于执行批准。对每项操作进行分类（只读／可逆／计费／破坏性），并在执行计费或破坏性调用前获得明确批准。
4. B 级事实——端点路径、方法、字段名称、枚举值、限制、Webhook 负载、签名算法、SDK 签名——使用前必须在当前会话中获取对应的规范文档。
5. 内置脚本、参考资料和示例属于 C 级：仅供说明，不能作为架构依据。绝不可将示例值提升为生产默认值。
6. 如果某条路由尚未解决，或规范文档获取失败，则按顺序沿解析阶梯继续查找：重新搜索已获取的文档（原始内容，不得使用摘要）、查阅 https://developers.sinch.com/llms.txt、跟进第一方链接、重试一次——然后再停止处理。绝不可猜测文档 URL，也绝不可用记忆、搜索摘要或内置文件替代。
7. 维护证据清单，将每个已获取来源与其授权的字段和声明对应起来。
8. 限制所有轮询和重试（退避、抖动、硬性上限）；重试计费或破坏性操作前检查状态；报告超时时应标记为未知，而非失败。
9. 分别报告验证级别（lint → 单元测试 → 模拟契约测试 → 沙盒 → 实时 → 端到端）；HTTP 2xx 不代表已交付。说明未执行的级别。
10. 仅加载负责该行为的最小技能集；如果缺少必需技能，应指出该技能并停止，而不是自行编造指令。

如果用户未指定语言或平台，请先询问——不同语言的 SDK 和初始化模式有所不同。使用下表路由到相应的参考资料。

真相来源——应加载哪些内容，以及哪些内容具有权威性

此技能包含两类可靠性不等的内容。请遵循以下优先级：

1. developers.sinch.com 上的规范文档（权威）。 此技能中的 .md 文档链接是确认准确的请求/响应架构、字段名称和嵌套结构、枚举值、签名/身份验证方案及限制的唯一事实来源。在编写用于构造有效负载、验证签名或解析回调/响应的代码之前，请先获取对应的链接文档，并在其中确认确切结构。根据 Security/URL policy，允许获取 developers.sinch.com 的一方 URL。切勿编造、猜测或按模式推断文档 URL——只能获取此技能中原文列出的文档 URL，或通过已获取页面上的链接找到的 URL；域名可信，并不代表猜测的路径真实存在。
2. 随附的 references/*.md（导航性摘要——不具权威性）。 这些内容用于指引你找到正确的规范文档；它们可能更新滞后、遗漏字段或简化嵌套结构。可用它们来决定要构建什么以及要打开哪篇文档。未经一级文档确认，不要将参考资料或 SKILL.md 概述中的字段名称、嵌套结构、编码方式或枚举值直接写入交付的代码。如果某项细节只出现在摘要中，应将其视为未经验证，并明确说明。

快速规则：编写代码 → 加载文档。 切勿引用只在摘要中看到的确切字段、标头、枚举值或编码方式。

SDK 安装

语言	包	安装	身份验证范围
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	NuGet 包	项目 + 应用程序

应用内通话使用单独的客户端 SDK，而非 @sinch/sdk-core。请参阅 sinch-in-app-calling。

各 SDK 支持的产品

并非所有 SDK 都支持所有产品。针对特定产品推荐 SDK 前，请先查看此表。

产品	Node.js	Java	.NET	Python
Conversation API	✅	✅	⚠	⚠
Voice API	✅	✅	✅	✅
Verification API	✅	✅	✅	✅
Numbers API	✅	✅	✅	✅
Number Lookup API	✅	❌	❌	✅
Elastic SIP Trunking	✅	❌	❌	❌
Fax API	✅	❌	⚠	❌
Provisioning API	✅	❌	❌	❌
10DLC Registration	❌	❌	❌	❌

✅ = 支持，⚠ = 部分支持/预览版，❌ = 不可用（请使用直接 HTTP 调用）

如果用户选择的 SDK 不支持某个产品，请引导用户改用直接 HTTP 调用。

SDK 初始化参考

有关特定语言的初始化代码，请使用以下参考资料：

• Node.js：references/sdk-init-node.md
• Python：references/sdk-init-python.md
• Java：references/sdk-init-java.md
• .NET：references/sdk-init-dotnet.md

如果语言未知，请先询问。SDK 会自动处理令牌刷新。

核心概念

@sinch/sdk-core — 统一的 Node.js SDK，涵盖所有项目级和应用级 Sinch API。也提供单独的软件包（例如 @sinch/voice、@sinch/verification）。

sinch（Python） — Python SDK（v2.0.0+），涵盖项目级和应用级 API。

sinch-sdk-java — Java SDK（v2.0.0+），可通过 Maven Central 获取。

项目级初始化 — 使用 projectId、keyId、keySecret。适用于 Conversation、Numbers、Fax、EST、10DLC、Number Lookup、Provisioning。

应用级初始化 — 使用 applicationKey、applicationSecret。适用于 Voice、Verification、In-App Calling。

多产品客户端 — 在单个 SinchClient 中提供项目凭据和应用凭据，以访问所有 API。

Conversation 区域 — 使用 Conversation API 时必须显式设置。可选值：us、eu、br。Python SDK v2.0.0+ 和 Java SDK v2.0.0+ 必须设置；建议在 Node.js 和 .NET 中设置。（仅为摘要——实现前请对照权威的 Sinch Developer Docs 文档确认确切名称、编码和枚举值。）

常见模式

• 项目级快速入门 — 使用项目凭据初始化 SinchClient。请参阅特定语言的参考文档。
• 应用级快速入门 — 使用应用密钥/密钥秘密初始化 SinchClient。请参阅特定语言的参考文档。
• 多产品客户端 — 将两组凭据传递给单个客户端实例。
• 区域化 Conversation API — 初始化时设置 conversationRegion（Python/Java 中必须设置，其他语言中建议设置）。

注意事项

• 并非所有 SDK 都支持所有产品 — 推荐 SDK 前请查看产品覆盖表。对于不支持的产品，请直接使用 HTTP 调用。
• 必须设置 Conversation 区域 — 如果未设置 conversation_region，Python 和 Java SDK 会在运行时失败。Node.js 和 .NET 尚未强制要求设置，但应显式设置。
• Voice/Verification 使用应用凭据 — 这些凭据与项目访问密钥是分开的。
• SDK 会自动刷新 OAuth2 令牌 — 使用 SDK 时无需手动处理令牌过期。

链接

• npm：@sinch/sdk-core
• PyPI：sinch
• Maven：sinch-sdk-java
• NuGet：Sinch
• Sinch Developer Docs
• LLMs.txt（完整文档索引）