sinch-in-app-calling

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sinch In-App Calling

Sinch 应用内通话

Overview

概述

Real-time voice and video SDK for Android, iOS, and JavaScript (Web). Connects to Sinch's cloud for signaling and routing.

适用于Android、iOS和**JavaScript（网页端）**的实时语音与视频SDK，可连接至Sinch云服务进行信令与路由。

Supported call types

支持的通话类型

App-to-App (VoIP/WebRTC between users)
App-to-Phone (call PSTN numbers)
App-to-SIP (connect to PBXs, contact centers)
App-to-Conference (multi-party calls)
Phone-to-App / SIP-to-App (inbound calls)

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

Agent Instructions

Agent操作指南

Prerequisites

前提条件

The user needs a Sinch account with an application key and secret from the Sinch Build Dashboard. See sinch-authentication for credential setup — In-App Calling uses application-scoped auth (Application Key + Application Secret).

用户需要拥有Sinch账户，并从Sinch Build Dashboard获取应用密钥和应用密码。凭证设置可参考sinch-authentication —— 应用内通话使用应用范围的认证方式（应用密钥 + 应用密码）。

Integration workflow

集成流程

Detect the platform from the user's project (language, build system, framework):
- Android (Kotlin/Java, Gradle) → Read
```
references/android.md
```
- iOS (Swift/ObjC, Xcode) → Read
```
references/ios.md
```
- JavaScript/Web (npm, browser) → Read
```
references/js.md
```
- If unclear, ask the user.
Walk through the integration steps in the platform reference. Go step by step — confirm each step is in place before moving to the next.
Ask about auth approach: Can the Application Secret be embedded (prototyping only) or must JWTs come from a backend (production)?
Ask about call types: Which types does the user need? This determines which sections to cover.
For Phone-to-App / SIP-to-App: The user needs a backend ICE callback handler. See the "Phone-to-App / SIP-to-App backend" section below.

检测用户项目的平台（语言、构建系统、框架）：
- Android（Kotlin/Java、Gradle）→ 查看
```
references/android.md
```
- iOS（Swift/ObjC、Xcode）→ 查看
```
references/ios.md
```
- JavaScript/网页端（npm、浏览器）→ 查看
```
references/js.md
```
- 若不确定，询问用户。
按照平台参考文档逐步完成集成步骤。每完成一步后确认无误，再进行下一步。
询问认证方式：是否可以嵌入应用密码（仅适用于原型开发），还是必须从后端获取JWT（生产环境）？
询问通话类型：用户需要哪种类型的通话？这将决定需要覆盖哪些内容章节。
针对电话到应用 / SIP到应用场景：用户需要后端ICE回调处理器。请查看下方的“电话到应用 / SIP到应用后端”章节。

SDK Init References

SDK初始化参考

For detailed SDK initialization code per platform:

Browser: 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

各平台详细的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 backend

电话到应用 / SIP到应用后端

Receiving inbound PSTN or SIP calls requires:

A Sinch voice number from the Build Dashboard assigned to the app (or SIP origination configured).
A callback URL in the app's Voice settings.
A backend ICE handler that routes calls via
```
connectMxp
```
:

json

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

接收PSTN或SIP呼入通话需要：

从Build Dashboard获取一个Sinch语音号码并分配给应用（或配置SIP发起）。
在应用的语音设置中配置回调URL。
一个后端ICE处理器，通过
```
connectMxp
```
路由通话：

json

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

Key Concepts

核心概念

SinchClient — The core SDK object. Must be initialized with Application Key and started before any calls can be made or received.
User Identity — A string identifier (e.g., user ID) that uniquely identifies a user in the Sinch system. Set during
```
SinchClient
```
initialization.
Call Types — App-to-App (VoIP), App-to-Phone (PSTN), App-to-SIP, App-to-Conference, and inbound (Phone-to-App, SIP-to-App).
Managed Push — Sinch-managed push notifications for incoming calls when the app is backgrounded. Required on all platforms.
JWT Authentication — Production apps must use backend-generated JWTs (not embedded secrets) for SDK authentication.
ICE Callback — Incoming Call Event. A backend webhook handler required for Phone-to-App and SIP-to-App calls that routes calls via
```
connectMxp
```
.
Environment Host — Regional endpoint for the SDK connection (e.g.,
```
ocra.api.sinch.com
```
for global routing).

SinchClient —— SDK核心对象。必须使用应用密钥初始化并启动后，才能发起或接收通话。
用户身份 —— 字符串标识符（如用户ID），用于在Sinch系统中唯一标识用户。在
```
SinchClient
```
初始化时设置。
通话类型 —— 应用到应用（VoIP）、应用到电话（PSTN）、应用到SIP、应用到会议，以及呼入类型（电话到应用、SIP到应用）。
托管推送 —— 当应用处于后台时，Sinch托管的推送通知用于提醒呼入通话。所有平台均需启用。
JWT认证 —— 生产环境应用必须使用后端生成的JWT（而非嵌入的密码）进行SDK认证。
ICE回调 —— 呼入通话事件。电话到应用和SIP到应用场景需要后端Webhook处理器，通过
```
connectMxp
```
路由通话。
环境主机 —— SDK连接的区域端点（例如，全球路由使用
```
ocra.api.sinch.com
```
）。

Common Patterns

常见模式

App-to-App voice call — Initialize SinchClient with user identity, call
```
callUser("recipient-id")
```
. Both users must have active SinchClient instances.
App-to-Phone (PSTN) — Call
```
callPhoneNumber("+15551234567")
```
with a CLI (caller ID) set to a Sinch number.
Receive incoming calls — Register push notifications, implement call listener/delegate, handle
```
onIncomingCall
```
event.
Phone-to-App routing — Assign a Sinch number to the app, set up backend ICE callback that returns
```
connectMxp
```
action targeting the user.
Video calling — Use
```
callUserVideo("recipient-id")
```
(or platform equivalent). Requires camera permissions.

应用到应用语音通话 —— 使用用户身份初始化SinchClient，调用
```
callUser("recipient-id")
```
。通话双方必须都有活跃的SinchClient实例。
应用到电话（PSTN） —— 使用Sinch号码设置CLI（主叫ID），调用
```
callPhoneNumber("+15551234567")
```
。
接收呼入通话 —— 注册推送通知，实现通话监听器/委托，处理
```
onIncomingCall
```
事件。
电话到应用路由 —— 为应用分配Sinch号码，设置后端ICE回调，返回指向目标用户的
```
connectMxp
```
动作。
视频通话 —— 使用
```
callUserVideo("recipient-id")
```
（或平台等效方法）。需要相机权限。

Troubleshooting

故障排查

Symptom	Likely cause	Fix
`onClientFailed` / `clientDidFail`	JWT issue — token missing, expired, wrong secret, or malformed	Verify JWT generation: correct app key + secret, `kid` matches key ID, token not expired. See auth section in platform reference
`onClientFailed` / `clientDidFail`	Invalid app key or wrong environment host	Verify key in Dashboard; check `environmentHost` matches your region
No incoming calls (JS)	Managed push not enabled	Call `sinchClient.setSupportManagedPush()` before starting — required even for the caller side
No incoming calls (Android)	FCM misconfiguration	Verify FCM credentials in Dashboard ("In-app Voice & Video SDKs" → "Google FCM Identification"); check that the device receives FCM tokens
No incoming calls (iOS)	APNs push not configured or token stale	Verify push certificate/key in Dashboard; ensure `registerPushNotificationData` is called with a fresh device token
No incoming calls (general)	SinchClient not running on the receiver's device	The receiver's app must have an active, started SinchClient to receive calls. Verify `start()` completed successfully
App-to-Phone fails immediately	Missing CLI (caller ID)	Set `callerIdentifier` / `cli` with a Sinch number
Audio only in foreground (iOS)	CallKit not reporting calls	Report outgoing calls to CallKit for background audio

If the above steps don't resolve the issue, instruct the user to contact Sinch Support with their app key, platform, and a description of the problem.

症状	可能原因	解决方法
`onClientFailed` / `clientDidFail`	JWT问题 —— 令牌缺失、过期、密码错误或格式不正确	验证JWT生成：确保应用密钥和密码正确， `kid` 匹配密钥ID，令牌未过期。查看平台参考文档中的认证章节
`onClientFailed` / `clientDidFail`	无效的应用密钥或错误的环境主机	在Dashboard中验证密钥；检查 `environmentHost` 是否匹配你的区域
无呼入通话（JS）	未启用托管推送	在启动前调用 `sinchClient.setSupportManagedPush()` —— 即使是主叫方也需要启用
无呼入通话（Android）	FCM配置错误	在Dashboard中验证FCM凭证（“应用内语音与视频SDK” → “Google FCM标识”）；检查设备是否能接收FCM令牌
无呼入通话（iOS）	APNs推送未配置或令牌过期	在Dashboard中验证推送证书/密钥；确保使用最新的设备令牌调用 `registerPushNotificationData`
无呼入通话（通用）	接收方设备上的SinchClient未运行	接收方应用必须有活跃且已启动的SinchClient才能接收通话。验证 `start()` 是否成功完成
应用到电话通话立即失败	缺少CLI（主叫ID）	使用Sinch号码设置 `callerIdentifier` / `cli`
iOS仅前台有音频	CallKit未上报通话	将呼出通话上报至CallKit以支持后台音频

如果上述步骤无法解决问题，请指导用户联系Sinch Support，并提供其应用密钥、平台和问题描述。

Public endpoints

公开端点

Set

environmentHost

when creating the Sinch client:

Endpoint	Region
`ocra.api.sinch.com`	Global (auto-routed)
`ocra-euc1.api.sinch.com`	Europe
`ocra-use1.api.sinch.com`	North America
`ocra-sae1.api.sinch.com`	South America
`ocra-apse1.api.sinch.com`	South East Asia 1
`ocra-apse2.api.sinch.com`	South East Asia 2

创建Sinch客户端时设置

environmentHost

：

端点	区域
`ocra.api.sinch.com`	全球（自动路由）
`ocra-euc1.api.sinch.com`	欧洲
`ocra-use1.api.sinch.com`	北美
`ocra-sae1.api.sinch.com`	南美
`ocra-apse1.api.sinch.com`	东南亚1区
`ocra-apse2.api.sinch.com`	东南亚2区