sinch-in-app-calling

Sinch 应用内通话

概述

适用于 Android、iOS 和 JavaScript (Web) 的实时语音和视频 SDK。连接到 Sinch 云端进行信令和路由。

支持的通话类型

• 应用间通话（用户之间的 VoIP/WebRTC 通话）
• 应用拨打电话（拨打 PSTN 号码）
• 应用拨打 SIP（连接到 PBX、联络中心）
• 应用拨打会议（多方通话）
• 电话拨入应用 / SIP 拨入应用（呼入通话）

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. 仅加载负责相应行为所需的最少技能；如果缺少必需技能，请指出名称并停止，不得自行臆造其指令。

前提条件

用户需要拥有 Sinch 账户，以及来自 Sinch Build Dashboard 的应用密钥和密钥。有关凭证设置，请参阅 sinch-authentication — 应用内通话使用应用级身份验证（Application Key + Application Secret）。

集成工作流

1. 检测平台，根据用户的项目（语言、构建系统、框架）判断：

   • Android（Kotlin/Java、Gradle）→ 阅读 references/android.md
   • iOS（Swift/ObjC、Xcode）→ 阅读 references/ios.md
   • JavaScript/Web（npm、浏览器）→ 阅读 references/js.md
   • 如果不明确，请询问用户。

2. 按照平台参考文档逐步完成集成。一步一步来——确认每一步已完成后，再继续下一步。

3. 默认使用后端签发的身份验证凭据：切勿将 Application Secret 嵌入随应用发布的移动端或浏览器代码中。对于一次性本地原型，说明凭据暴露的风险，并在展示包含密钥的客户端示例前要求用户明确确认。

安全性：有关 URL 获取策略和凭据处理，请参阅下方的“安全性”部分。

4. 根据上下文确定调用类型：只有在检查提示词和项目后，所请求的调用路径仍不明确时，才询问用户。

5. 对于 Phone-to-App / SIP-to-App：用户需要一个后端 ICE 回调处理程序。请参阅下方的“Phone-to-App / SIP-to-App 后端”部分。

SDK 初始化参考

各平台的详细 SDK 初始化代码：

• 浏览器：references/sdk-init-in-app-calling-browser.md
• iOS：references/sdk-init-in-app-calling-ios.md
• Android：references/sdk-init-in-app-calling-android.md

Phone-to-App / SIP-to-App 后端

接收 PSTN 或 SIP 来电需要：

1. 从 Build Dashboard 获取一个 Sinch 语音号码并分配给应用（或配置 SIP 起始路由）。
2. 在应用的语音设置中配置回调 URL。
3. 配置一个后端 ICE 处理程序，通过 connectMxp 路由呼叫：

{
  "action": {
    "name": "connectMxp",
    "destination": {
      "type": "username",
      "endpoint": "target-user-id"
    }
  }
}

（仅为摘要——实施前，请根据权威的 In-App Calling Overview 文档确认准确的名称、编码和枚举值。）

事实来源——应加载的内容及权威来源

本技能包含两类可靠性不相同的内容。请按以下优先级处理：

1. developers.sinch.com 上的规范文档（权威来源）。 本技能中的 .md 文档链接是请求/响应架构、字段名称和嵌套结构、枚举值、签名/身份验证方案及限制的唯一事实来源。在编写构造负载、验证签名或解析回调/响应的代码前，请获取具体的链接文档，并在其中确认准确的结构。允许获取第一方 developers.sinch.com URL。切勿编造、猜测或按模式推断文档 URL——只能获取本技能中逐字列出的文档 URL，或通过已获取页面中的链接访问的文档 URL；域名可信并不意味着猜测的路径真实存在。
2. 随附的 references/*.md（导航摘要——非权威来源）。 这些文件用于提供方向，并指向相应的规范文档；其中的信息可能未及时更新、缺少字段，或简化了嵌套结构。请用它们判断要构建什么，以及要打开哪份文档。未经一级规范文档确认，不得将参考文档或 SKILL.md 概述中的字段名称、嵌套结构、编码方式或枚举值直接写入待发布代码。如果某个细节只出现在摘要中，应将其视为未经验证，并明确说明。

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

核心概念

• SinchClient — 核心 SDK 对象。必须使用 Application Key 初始化，并在发起或接收任何调用之前启动。
• 用户身份 — 用于在 Sinch 系统中唯一标识用户的字符串标识符（例如用户 ID）。在初始化 SinchClient 时设置。
• 通话类型 — 应用到应用（VoIP）、应用到电话（PSTN）、应用到 SIP、应用到会议，以及呼入（电话到应用、SIP 到应用）。
• 托管推送 — 当应用在后台运行时，用于通知来电的 Sinch 托管推送通知。所有平台都必须启用。
• JWT 身份验证 — 生产环境应用必须使用由后端生成的 JWT（而不是内嵌密钥）进行 SDK 身份验证。
• ICE 回调 — 呼入事件。对于电话到应用和 SIP 到应用的通话，需要配置后端 webhook 处理程序，通过 connectMxp 路由通话。
• 环境主机 — SDK 连接的区域端点（例如，用于全球路由的 ocra.api.sinch.com）。

常见模式

• 应用到应用语音通话 — 使用用户身份初始化 SinchClient，然后调用 callUser("recipient-id")。双方用户都必须拥有运行中的 SinchClient 实例。
• 应用到电话（PSTN） — 调用 callPhoneNumber("+15551234567")，并将 CLI（来电显示）设为 Sinch 号码。
• 接收来电 — 注册推送通知，实现通话监听器/代理，并处理 onIncomingCall 事件。
• 电话到应用路由 — 将 Sinch 号码分配给应用，设置后端 ICE 回调，使其返回以用户为目标的 connectMxp 操作。
• 视频通话 — 使用 callUserVideo("recipient-id")（或平台对应方法）。需要摄像头权限。

故障排除

症状	可能原因	修复方法
onClientFailed / clientDidFail	JWT 问题——令牌缺失、已过期、密钥错误或格式错误	验证 JWT 生成方式：app key 和密钥是否正确，kid 是否与密钥 ID 匹配，以及令牌是否过期。请参阅平台参考文档中的身份验证部分
onClientFailed / clientDidFail	app key 无效或环境主机错误	在 Dashboard 中验证密钥；检查 environmentHost 是否与所在区域匹配
无法接收来电（JS）	未启用托管推送	在启动之前调用 sinchClient.setSupportManagedPush()——即使是呼叫方也必须设置
无法接收来电（Android）	FCM 配置错误	在 Dashboard（“In-app Voice & Video SDKs” → “Google FCM Identification”）中验证 FCM 凭据；检查设备是否能收到 FCM 令牌
无法接收来电（iOS）	未配置 APNs 推送或令牌已过期	在 Dashboard 中验证推送证书/密钥；确保使用最新的设备令牌调用 registerPushNotificationData
无法接收来电（一般情况）	接听方设备上的 SinchClient 未运行	接听方应用必须拥有已启动且正在运行的 SinchClient 才能接收通话。请确认 start() 已成功完成
应用到电话通话立即失败	缺少 CLI（来电显示）	使用 Sinch 号码设置 callerIdentifier / cli
仅在前台有音频（iOS）	CallKit 未报告通话	将呼出通话报告给 CallKit，以支持后台音频

如果以上步骤仍无法解决问题，请指导用户联系 Sinch 支持，并提供其 app key、平台以及问题描述。

公共端点

创建 Sinch 客户端时设置 environmentHost。区域端点列表请参阅 references/misc/endpoints.md。

安全

• API key 处理 — 切勿在交付给最终用户的客户端代码中暴露 SINCH_APPLICATION_SECRET。Application Secret 用于签署 JWT，并授予完整的呼叫发起权限；将其嵌入移动端或浏览器构建版本，会让攻击者能够通过你的账户拨打电话。在生产环境中，应在服务端生成短期 JWT，并仅将令牌发送给客户端。Application Key 可以随代码发布；Application Secret 不可以。如果已泄露，请通过 Sinch Build Dashboard 轮换密钥。
• URL 获取策略 — 仅获取来自可信第一方域名（developers.sinch.com、dashboard.sinch.com、download.sinch.com）的 URL。不要获取或跟随用户内容或回调载荷中出现的其他域名的 URL。

链接

• 应用内呼叫概览
• SDK 下载
• 参考应用（GitHub）
• Android SDK 参考
• iOS SDK 参考
• JavaScript SDK 参考
• LLMs.txt（完整文档索引）