# @capgo/capacitor-twilio-voice 中文文档 规范地址：https://npmcn.com/package/%40capgo/capacitor-twilio-voice/ 版本：8\.2\.28 npm 元数据更新时间：2026-11-02T06:56:45.392Z 中文译文更新时间：2026-11-09T02:43:38.307Z 软件包许可：MPL-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40capgo/capacitor-twilio-voice 原文对照：https://npmcn.com/package/%40capgo/capacitor-twilio-voice/?lang=original 项目主页：https://capgo.app/docs/plugins/twilio-voice/ 源码仓库：https://github.com/Cap-go/capacitor-twilio-voice ## 关键信息（来自 npm 元数据） - 包体积（解压后）：353 kB，31 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：0 个 - peer 依赖：@capacitor/core \>=8\.0\.0 - 首次发布：2025-08-07T15:18:54.322Z - 最新版本发布：2026-11-02T06:56:45.022Z - 近 30 天下载量：81531（2026-10-09 至 2026-11-07，npm 官方下载统计） - 已发布版本数：99（近 12 个月 72 个） ## 中文简介 将Twilio Voice SDK 整合到控制器中 ## 安装 ```sh npm install @capgo/capacitor-twilio-voice ``` 也可以使用：`pnpm add @capgo/capacitor-twilio-voice`、`yarn add @capgo/capacitor-twilio-voice`、`bun add @capgo/capacitor-twilio-voice` ## README ## Twilio 语音插件 在您的 Capacitor app 中使用 Twilio Voice SDK 制作并接收电话,在 iOS 上使用 CallKit ,并在 Android 上使用本地呼叫通知. [![Capgo - Build Capacitor apps with AI, ship updates instantly](https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-twilio-voice)](https://capgo.app/?ref=plugin_twilio_voice) **队长**:在几分钟内将修正推给您的 Capacitor 用户,在没有Mac的情况下构建已签名的iOS和Android apps,并在一击中回滚. ## [\*免费开始\*](https://capgo.app/register/?ref=plugin_twilio_voice) 14天无限自由审判. 不需要信用卡 > 🤖 **建筑与AI编码代理?** 安装 [Capgo 技能](https://capgo.app/skills/?ref=plugin_twilio_voice) 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 `@capgo/capacitor-twilio-voice` 在您的电容应用程序中: `npx skills add Cap-go/capgo-skills`。然后问你的经纪人: _加上@capgo/capor-twilio-voice到我的Capacitor应用上_ [代理设置指南](https://capgo.app/agents/?ref=plugin_twilio_voice) • 妇女 [主机磁共振](https://capgo.app/docs/ai/mcp/?ref=plugin_twilio_voice) ![@capgo/capacitor-twilio-voice for Capacitor apps](https://raw.githubusercontent.com/Cap-go/capacitor-twilio-voice/main/assets/github-social-preview.png) ## 主要特点 - **电话**数字 : `makeCall()`, (中文(简体) ), `acceptCall()`, (中文(简体) ), `rejectCall()` 财务报告和审定财务报表 `endCall()`。 。 。 . - **待命控制**数字 : `muteCall()`, (中文(简体) ), `setSpeaker()` 财务报告和审定财务报表 `getCallStatus()`。 。 。 . - **来电**:由PushKit和CallKit在iOS和Firebase Messaging在Android上的推取调用邀请. - **活动**:邀请,鸣叫,接通,断开,再接并拨打质量警告. - **会议**数字 : `login()` 带有Twilio访问符, `isLoggedIn()` 财务报告和审定财务报表 `logout()`。 。 。 . - **平台**: iOS和Android. 互联网档案馆的存檔,存档日期2013-12-21. 在网上不可用. `login()`, (中文(简体) ), `isLoggedIn()` 财务报告和审定财务报表 `getCallStatus()` 丢入网络. ## 文档 这里有最完整的医生: [https://capgo.app/docs/plugins/twilio-voice/ (中文(简体) )](https://capgo.app/docs/plugins/twilio-voice/) ## 兼容性 | 插件版本 | 电容兼容性 | 维护 | | --- | --- | --- | | 联合国 | 联合国 | ✅ | | 页:1 | 页:1 | 应要求 | | 页:1 | 页:1 | ❌ | | 页:1 | 页:1 | ❌ | > **说明:** 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的 Capacitor 安装的版本( 如 Capacitor 8 的插件 v8) 。 只有最新的主要版本得到积极维护. ## 安装 您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 : ```bash npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins ``` 然后使用下列提示: ```text Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-twilio-voice` plugin in my project. ``` 如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令: ```bash npm install @capgo/capacitor-twilio-voice npx cap sync ``` ## iOS 设置 ### 1\. 安装插件 ```bash npm install @capgo/capacitor-twilio-voice npx cap sync ``` ### 2\. 设置 `CustomCapacitorViewController.swift` 从 `example-app/ios/App/App/CustomCapacitorViewController.swift` 给您的 `ios/App/App/CustomCapacitorViewController.swift` 文档. 3. 修改 `AppDelegate.swift` 添加以下内容到 `AppDelegate.swift`数字 : ```diff import UIKit import Capacitor + import PushKit + import CapgoCapacitorTwilioVoice @UIApplicationMain - class AppDelegate: UIResponder, UIApplicationDelegate { + class AppDelegate: UIResponder, UIApplicationDelegate, PKPushRegistryDelegate { var window: UIWindow? + var pushKitEventDelegate: PushKitEventDelegate? + var voipRegistry = PKPushRegistry.init(queue: DispatchQueue.main) func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { // Override point for customization after application launch. + + /* + * Your app must initialize PKPushRegistry with PushKit push type VoIP at the launch time. As mentioned in the + * [PushKit guidelines](https://developer.apple.com/documentation/pushkit/supporting_pushkit_notifications_in_your_app), + * the system can't deliver push notifications to your app until you create a PKPushRegistry object for + * VoIP push type and set the delegate. If your app delays the initialization of PKPushRegistry, your app may receive outdated + * PushKit push notifications, and if your app decides not to report the received outdated push notifications to CallKit, iOS may + * terminate your app. + */ + initializePushKit() + + guard let viewController = UIApplication.shared.windows.first?.rootViewController as? CustomCapacitorViewController else { + fatalError("Root view controller is not Capacitor view controller") + } + + viewController.passPushKitEventDelegate = { delegate in + self.pushKitEventDelegate = delegate + } + + // self.pushKitEventDelegate = viewController + return true } + + func initializePushKit() { + voipRegistry.delegate = self + voipRegistry.desiredPushTypes = Set([PKPushType.voIP]) + } // ... (existing lifecycle methods remain the same) ... + // MARK: PKPushRegistryDelegate + func pushRegistry(_ registry: PKPushRegistry, didUpdate credentials: PKPushCredentials, for type: PKPushType) { + NSLog("pushRegistry:didUpdatePushCredentials:forType:") + + if let delegate = self.pushKitEventDelegate { + delegate.credentialsUpdated(credentials: credentials) + } + } + + func pushRegistry(_ registry: PKPushRegistry, didInvalidatePushTokenFor type: PKPushType) { + NSLog("pushRegistry:didInvalidatePushTokenForType:") + + if let delegate = self.pushKitEventDelegate { + delegate.credentialsInvalidated() + } + } + + /** + * Try using the `pushRegistry:didReceiveIncomingPushWithPayload:forType:withCompletionHandler:` method if + * your application is targeting iOS 11. According to the docs, this delegate method is deprecated by Apple. + */ + func pushRegistry(_ registry: PKPushRegistry, didReceiveIncomingPushWith payload: PKPushPayload, for type: PKPushType) { + NSLog("pushRegistry:didReceiveIncomingPushWithPayload:forType:") + + if let delegate = self.pushKitEventDelegate { + delegate.incomingPushReceived(payload: payload) + } + } + + /** + * This delegate method is available on iOS 11 and above. Call the completion handler once the + * notification payload is passed to the `TwilioVoiceSDK.handleNotification()` method. + */ + func pushRegistry(_ registry: PKPushRegistry, didReceiveIncomingPushWith payload: PKPushPayload, for type: PKPushType, completion: @escaping () -> Void) { + NSLog("pushRegistry:didReceiveIncomingPushWithPayload:forType:completion:") + + if let delegate = self.pushKitEventDelegate { + delegate.incomingPushReceived(payload: payload, completion: completion) + } + + if let version = Float(UIDevice.current.systemVersion), version >= 13.0 { + /** + * The Voice SDK processes the call notification and returns the call invite synchronously. Report the incoming call to + * CallKit and fulfill the completion before exiting this callback method. + */ + completion() + } + } } ``` ### 3\. 编辑 `Main.storyboard` 将视图控制器更改为 `CustomCapacitorViewController` 内 `Main.storyboard`。 。 。 . ```diff - + ``` 在示例应用程序中查看更多细节. ### 4\. 设置 `Info.plist` 添加以下内容到 `ios/App/App/Info.plist`数字 : ```xml NSMicrophoneUsageDescription This app uses the microphone for voice calls UIBackgroundModes voip audio ``` 5. 请确保您在 Xcode 中具备以下功能 : - 推动通知 - 背景模式 6. 生成 Push 通知的证书 要生成 Push 通知的证书, 您需要遵循这些步骤 : 1. 为您的应用程序创建签名证书 . ```bash openssl genrsa -out ALDsigning.key 2048 ``` 2. 生成签名请求 . ```bash openssl req -new -key ALDsigning.key -out csr3072ALDSigning.certSigningRequest -subj "/emailAddress=example@example.com, CN=Example Name, C=IE" ``` 请上传到您的苹果开发者账户 [这里](https://developer.apple.com/account/resources/certificates/add)搜索 `Create a new VoIP Services Certificate` 3. 下载由苹果提供的文件. 4. 从已下载的文件中提取 .p12 文件 . ```bash openssl pkcs12 -export -out voip_services.p12 -inkey ALDsigning.key -in voip_services.cer ``` 5. 导出 `cert.pem` 财务报告和审定财务报表 `key.pem` 来自.p12文件的文件. ```bash openssl pkcs12 -in voip_services.p12 -nokeys -out cert.pem -nodes openssl pkcs12 -in voip_services.p12 -nocerts -out key.pem -nodes ``` 6. 上传 `cert.pem` 财务报告和审定财务报表 `key.pem` 文件为twilio. ```bash npx twilio api:chat:v2:credentials:create --type=apn --sandbox --friendly-name="voice-push-credential (sandbox)" --certificate="$(cat /Users/your_username/Documents/twilio-voip/cert.pem)" --private-key="$(cat /Users/your_username/Documents/twilio-voip/key.pem)" ``` ## Android 设置 ### 1\. 消防基地设置 将 Firebase 添加到您的 Android 项目中 : 1. 添加 `google-services.json` 改为 `android/app/` 2. 添加 `CapacitorApplication.java` 改为 `android/app/src/main/java/YOUR_APP_PACKAGE/CapacitorApplication.java` 复制内容 `example-app/android/app/src/main/java/com/example/plugin/CapacitorApplication.java` 给您的 `android/app/src/main/java/YOUR_APP_PACKAGE/CapacitorApplication.java` 文档. 3. 导入 `androidx.webkit:webkit` 内 `build.gradle` (单元:app) ```diff dependencies { + implementation 'androidx.webkit:$androidxWebkitVersion' } ``` 4. 修改 `MainActivity.java` 添加以下内容到 `MainActivity.java`数字 : ```diff package com.example.plugin; import android.net.Uri; import android.os.Bundle; import android.webkit.ValueCallback; import androidx.webkit.WebViewCompat; import androidx.webkit.WebViewFeature; import com.getcapacitor.BridgeActivity; import com.getcapacitor.JSExport; import com.getcapacitor.Logger; import com.getcapacitor.PluginHandle; + import java.util.ArrayList; + import java.util.Collections; import ee.forgr.capacitor_twilio_voice.CapacitorTwilioVoicePlugin; public class MainActivity extends BridgeActivity { @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); + + this.bridge.registerPluginInstance(CapacitorTwilioVoicePlugin.getInstance()); + ArrayList pluginHandles = new ArrayList<>(); + pluginHandles.add(this.bridge.getPlugin("CapacitorTwilioVoice")); + String pluginJS = JSExport.getPluginJS(pluginHandles); + if (WebViewFeature.isFeatureSupported(WebViewFeature.DOCUMENT_START_SCRIPT)) { + String allowedOrigin = Uri.parse(this.bridge.getAppUrl()).buildUpon().path(null).fragment(null).clearQuery().build().toString(); + try { + WebViewCompat.addDocumentStartJavaScript(this.getBridge().getWebView(), pluginJS, Collections.singleton(allowedOrigin)); + } catch (IllegalArgumentException ex) { + Logger.warn("Invalid url, using fallback"); + } + } } } ``` 5. 在 JS 中注册插件 ```diff + import { CapacitorTwilioVoice } from '@capgo/capacitor-twilio-voice'; + import { Capacitor } from '@capacitor/core'; + Capacitor.registerPlugin('CapacitorTwilioVoice'); ``` 6. 添加 `android:name="CapacitorApplication"` 页:1 `application` 标记在 `android/app/src/main/AndroidManifest.xml` 7. 添加以下内容到 `android/app/src/main/AndroidManifest.xml`数字 : ```xml ``` 记住,这样可以让应用程序在屏幕被锁定时被访问. ## Twilio 设置 - [iOS 设置](https://www.twilio.com/docs/voice/sdks/ios/get-started) - [Android 设置](https://www.twilio.com/docs/voice/sdks/android/get-started) ## 呼叫者名称显示器( CapactorTwilioCaller)Name 默认情况下,来电会显示来电者的电话号码或客户端ID. 您可以通过通过一个 `CapacitorTwilioCallerName` 参数从您的 TwiML 后端显示友好名称 . ### 后端设置 当生成您的 TwiML 响应时 `` 拨号,加号 `CapacitorTwilioCallerName` 参数 : ```java // Java example (see exemple-backend for full implementation) Parameter callerNameParam = new Parameter.Builder() .name("CapacitorTwilioCallerName") .value("John Doe") .build(); Client client = new Client.Builder(identity) .parameter(callerNameParam) .build(); Dial dial = new Dial.Builder() .client(client) .build(); ``` ```javascript // Node.js example const VoiceResponse = require('twilio').twiml.VoiceResponse; const response = new VoiceResponse(); const dial = response.dial(); dial.client({ name: 'CapacitorTwilioCallerName', value: 'John Doe' }, identity); ``` ### 如何运作 1. 当您的后端收到来电时, 它会生成 TwiML 以引导呼叫 2. 包含 `CapacitorTwilioCallerName` 带有调用者显示名的参数 3. 插件会自动提取此参数,并将其用于: - iOS CallKit 接通的呼叫屏幕 - Android 收到呼叫通知 - 这个 `from` 输入 `callInviteReceived` 事件 - 这个 `pendingInvites` 阵列 `getCallStatus()` 若为 `CapacitorTwilioCallerName` 不提供,插件会倒回呼叫者的电话号码或客户端ID. ## 使用量 ### 认证 #### `login(options: { accessToken: string })` 使用 JWT 访问令牌认证 Twilio : - 自动验证符号过期 - 为应用程序重新启动安全存储令牌 - VoIP 推进通知的注册 - **说明**: 插件将拒绝过期的符号 #### `logout()` 记录当前用户并清理全部会话数据 : - VoIP 驱动通知的未注册者 - 清除存储的访问令牌 - 结束任何活动呼叫 - 恢复所有调用状态 #### `isLoggedIn()` 检查用户是否正在登录一个有效的( 未过期) 符号 . 回返情况: `{ isLoggedIn: boolean, hasValidToken: boolean, identity?: string }` 这个 `identity` 字段包含如果登录的话从 JWT 符号中提取的用户身份. #### `makeCall(options: { to: string })` 启动向外呼叫。 需要通过 `login()`。 。 。 . #### `acceptCall(options: { callSid: string })` 接受接通电话. #### `rejectCall(options: { callSid: string })` 拒绝来电. #### `endCall(options?: { callSid?: string })` 结束活动呼叫或特定呼叫. #### `muteCall(options: { muted: boolean, callSid?: string })` 哑或解出麦克风. #### `setSpeaker(options: { enabled: boolean })` 启用或禁用扬声器 。 在Android上,使用Twilio AudioSwitch来管理耳机,扬声器和连接设备(头套,蓝牙等)之间的音频路由. #### `getCallStatus()` 获得当前呼叫状态. #### `checkMicrophonePermission()` 检查是否获得麦克风许可 . #### `requestMicrophonePermission()` 请求用户的麦克风许可. ### 活动听众 ```typescript import { CapacitorTwilioVoice } from '@capgo/capacitor-twilio-voice'; // Registration events CapacitorTwilioVoice.addListener('registrationSuccess', (data) => { console.log('Successfully registered:', data); }); CapacitorTwilioVoice.addListener('registrationFailure', (data) => { console.error('Registration failed:', data); }); // Call events CapacitorTwilioVoice.addListener('callInviteReceived', (data) => { console.log('Incoming call from:', data.from); }); CapacitorTwilioVoice.addListener('callConnected', (data) => { console.log('Call connected:', data); }); CapacitorTwilioVoice.addListener('callDisconnected', (data) => { console.log('Call ended:', data); }); CapacitorTwilioVoice.addListener('callRinging', (data) => { console.log('Call is ringing:', data); }); CapacitorTwilioVoice.addListener('callReconnecting', (data) => { console.log('Call reconnecting:', data); }); CapacitorTwilioVoice.addListener('callReconnected', (data) => { console.log('Call reconnected:', data); }); CapacitorTwilioVoice.addListener('callQualityWarningsChanged', (data) => { console.log('Quality warnings:', data); }); ``` ## JWT 托肯管理公司 ### 调试格式 插件预计 Twilio 以 JWT 格式使用此结构访问符 : ```json { "iss": "your-account-sid", "exp": 1234567890, "grants": { "voice": { "outgoing": { "application_sid": "your-app-sid" }, "push_credential_sid": "your-push-credential-sid" }, "identity": "user-identity" } } ``` ### 托肯验证 - 键自动验证为过期 - 无效或过期的符号将被拒绝 - 使用 `isLoggedIn()` 以检查符号状态 ### 后端集成 从您的后端服务器获取访问令牌 : ```typescript async function fetchAccessToken(identity: string): Promise { const response = await fetch(`/accessToken?identity=${identity}`); return response.text(); } ``` ## 测试要求 ### iOS 模拟器限制 - VoIP 推动通知在 iOS 模拟器中无效 - 使用物理 iOS 设备来测试来电 - 模拟器和装置中的调用 ### Android 模拟器 - 需要谷歌游戏服务 - Firebase 消息在Android模拟器中与 Google API 工作 ## 处理错误 插件提供了详细的错误信息 : ```typescript try { await CapacitorTwilioVoice.makeCall({ to: '+1234567890' }); } catch (error) { console.error('Call failed:', error); } ``` 常见错误情况 : - **无效的符号**: 检查令牌格式并过期 - **没有麦克风许可**: 调用 `requestMicrophonePermission()` - **网络问题**: 验证互联网连接 - **无效的电话号码**: 使用E.164格式(+1234567890) ## 安全说明 - 访问令牌存储在安全设备存储中 - 键在使用前自动验证 - 生产大楼没有敏感数据记录 - 总是使用 HTTPS 从后端获取符号 ## 平台支持 | 平台 | 支助 | 页:1 | | --- | --- | --- | | iOS系统 | ✅ | 需要iOS 13.0+ (英语) | | 机器人 | ✅ | 需要 API 级别 23+ | | 网页 | ❌ | 不予支持 | ## API 密码 - [`login(...)`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-login) - [`logout()`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-logout) - [`isLoggedIn()`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-isloggedin) - [`makeCall(...)`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-makecall) - [`acceptCall(...)`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-acceptcall) - [`rejectCall(...)`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-rejectcall) - [`endCall(...)`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-endcall) - [`muteCall(...)`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-mutecall) - [`setSpeaker(...)`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-setspeaker) - [`getCallStatus()`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-getcallstatus) - [`checkMicrophonePermission()`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-checkmicrophonepermission) - [`requestMicrophonePermission()`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-requestmicrophonepermission) - [`addListener('callInviteReceived', ...)`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-addlistenercallinvitereceived-) - [`addListener('callConnected', ...)`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-addlistenercallconnected-) - [`addListener('callInviteCancelled', ...)`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-addlistenercallinvitecancelled-) - [`addListener('outgoingCallInitiated', ...)`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-addlisteneroutgoingcallinitiated-) - [`addListener('outgoingCallFailed', ...)`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-addlisteneroutgoingcallfailed-) - [`addListener('callDisconnected', ...)`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-addlistenercalldisconnected-) - [`addListener('callRinging', ...)`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-addlistenercallringing-) - [`addListener('callReconnecting', ...)`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-addlistenercallreconnecting-) - [`addListener('callReconnected', ...)`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-addlistenercallreconnected-) - [`addListener('callQualityWarningsChanged', ...)`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-addlistenercallqualitywarningschanged-) - [`addListener('registrationSuccess', ...)`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-addlistenerregistrationsuccess-) - [`addListener('registrationFailure', ...)`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-addlistenerregistrationfailure-) - [`removeAllListeners()`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-removealllisteners) - [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-getpluginversion) - [接口](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-interfaces) - [类型异名](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-type-aliases) ### 登录(...) ```typescript login(options: { accessToken: string; }) => Promise<{ success: boolean; }> ``` 使用访问令牌认证Twilio Voice的用户. 访问令牌应在您的后端服务器上使用您的 Twilio 证书生成 . 必须通过Twilio Voice发出和接收电话. | 参数 | 类型 | 说明 | | --- | --- | --- | | **`options`** | `{ accessToken: string; }` | \- 配置对象 | **回返情况:** `Promise<{ success: boolean; }>` * * * ### 登录( c) ```typescript logout() => Promise<{ success: boolean; }> ``` 从 Twilio Voice 中记录当前用户和未注册者 . 这将断开任何正在运行的电话并阻止设备接收 新的呼叫通知. **回返情况:** `Promise<{ success: boolean; }>` * * * ### isLoggedIn () (中文(简体) ) ```typescript isLoggedIn() => Promise<{ isLoggedIn: boolean; hasValidToken: boolean; identity?: string; }> ``` 检查用户是否正在登录, 是否有有效的访问符 . **回返情况:** `Promise<{ isLoggedIn: boolean; hasValidToken: boolean; identity?: string; }>` * * * ### 调用(...) ```typescript makeCall(options: { to: string; displayName?: string; callerId?: string; }) => Promise<{ success: boolean; callSid?: string; }> ``` 启动发送到电话号码或客户端的电话. 用户在打电话前必须登录。 电话会被接通 通过你的Twilio后端配置. | 参数 | 类型 | 说明 | | --- | --- | --- | | **`options`** | `{ to: string; displayName?: string; callerId?: string; }` | \- 配置对象 | **回返情况:** `Promise<{ success: boolean; callSid?: string; }>` * * * ### 接受呼叫(...) ```typescript acceptCall(options: { callSid: string; }) => Promise<{ success: boolean; }> ``` 接通电话. 应响应“邀请接收”事件. | 参数 | 类型 | 说明 | | --- | --- | --- | | **`options`** | `{ callSid: string; }` | \- 配置对象 | **回返情况:** `Promise<{ success: boolean; }>` * * * ### 拒绝呼叫(...) ```typescript rejectCall(options: { callSid: string; }) => Promise<{ success: boolean; }> ``` 拒绝接听电话. 应响应“邀请接收”事件. 打电话者会听到忙碌的信号,或者被引导到语音邮件. | 参数 | 类型 | 说明 | | --- | --- | --- | | **`options`** | `{ callSid: string; }` | \- 配置对象 | **回返情况:** `Promise<{ success: boolean; }>` * * * ### 端点呼叫(...) ```typescript endCall(options: { callSid?: string; }) => Promise<{ success: boolean; }> ``` 结束一个主动呼叫. 如果不提供 callSid, 这将结束当前活动的调用 . | 参数 | 类型 | 说明 | | --- | --- | --- | | **`options`** | `{ callSid?: string; }` | \- 配置对象 | **回返情况:** `Promise<{ success: boolean; }>` * * * ### 哑声(...) ```typescript muteCall(options: { muted: boolean; callSid?: string; }) => Promise<{ success: boolean; }> ``` 在主动通话时发出静音或解密麦克风. 哑声后,对方不会听到你的麦克风的声音. | 参数 | 类型 | 说明 | | --- | --- | --- | | **`options`** | `{ muted: boolean; callSid?: string; }` | \- 配置对象 | **回返情况:** `Promise<{ success: boolean; }>` * * * ### 设置语法(...) ```typescript setSpeaker(options: { enabled: boolean; }) => Promise<{ success: boolean; }> ``` 启用或禁用扬声器模式 . 启用后, 音频会通过设备的扬声器而不是耳机进行路由 . | 参数 | 类型 | 说明 | | --- | --- | --- | | **`options`** | `{ enabled: boolean; }` | \- 配置对象 | **回返情况:** `Promise<{ success: boolean; }>` * * * ### 获取呼叫状态( C) ```typescript getCallStatus() => Promise<{ hasActiveCall: boolean; isOnHold: boolean; isMuted: boolean; callSid?: string; callState?: string; pendingInvites: CallInvite[]; activeCallsCount: number; }> ``` 获取活动呼叫的当前状态 . 这可以提供实时信息 关于呼叫状态,哑声状态, 持有状态,并呼叫识别器. **回返情况:** `Promise<{ hasActiveCall: boolean; isOnHold: boolean; isMuted: boolean; callSid?: string; callState?: string; pendingInvites: CallInvite[]; activeCallsCount: number; }>` * * * ### 麦克风 ```typescript checkMicrophonePermission() => Promise<{ granted: boolean; }> ``` 检查是否获得麦克风许可 . 此不请求权限, 只检查当前权限状态 . **回返情况:** `Promise<{ granted: boolean; }>` * * * ### 麦克风 ```typescript requestMicrophonePermission() => Promise<{ granted: boolean; }> ``` 请求用户的麦克风许可 . 在iOS和Android上,如果允许,这将显示系统权限对话框 尚未获准。 如果先前被拒绝,用户可能需要 在系统设置中授予它. **回返情况:** `Promise<{ granted: boolean; }>` * * * ### 添加倾听器( “ call Invite received ” ,...) ```typescript addListener(eventName: 'callInviteReceived', listenerFunc: (data: CallInvite) => void) => Promise ``` 收听来电通知. 当另一个用户或电话号码打给你时,此事件会被开除. 您应该拨打接受呼叫或拒绝呼叫. | 参数 | 类型 | 说明 | | --- | --- | --- | | **`eventName`** | `'callInviteReceived'` | \- 活动名称(“请收信”) | | **`listenerFunc`** | `(data: [CallInvite](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-callinvite)) => void` | \- 处理事件的召回功能 | **回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-pluginlistenerhandle)>` * * * ### 添加倾听器( “ callConnected ” ,...) ```typescript addListener(eventName: 'callConnected', listenerFunc: (data: { callSid: string; }) => void) => Promise ``` 听电话连接的事件. 此事件在呼叫( 来或出) 成功时启动 连接和音频可以被听到. | 参数 | 类型 | 说明 | | --- | --- | --- | | **`eventName`** | `'callConnected'` | \- 活动名称 (“ callConnected ” ) | | **`listenerFunc`** | `(data: { callSid: string; }) => void` | \- 处理事件的召回功能 | **回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-pluginlistenerhandle)>` * * * ### 添加倾听器( 调用 Invite 已取消 ).. ```typescript addListener(eventName: 'callInviteCancelled', listenerFunc: (data: { callSid: string; reason: 'user_declined' | 'remote_cancelled'; }) => void) => Promise ``` 听电话邀请取消活动. 当接收到的电话邀请被取消时,此事件即告解除 回答,要么是打电话者挂断,要么是用户拒绝. | 参数 | 类型 | 说明 | | --- | --- | --- | | **`eventName`** | `'callInviteCancelled'` | \- 活动名称( 叫做“ Invite Cancelled ” ) | | **`listenerFunc`** | `(data: { callSid: string; reason: 'user_declined' | 'remote_cancelled'; }) => void` | \- 处理事件的召回功能 | **回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-pluginlistenerhandle)>` * * * ### 添加收听器( 已启动) ```typescript addListener(eventName: 'outgoingCallInitiated', listenerFunc: (data: { callSid: string; to: string; source: 'app' | 'system'; displayName?: string; }) => void) => Promise ``` 听听即将开始的电话活动. 此事件在程序启动时启动 或来自系统(如iOS上的CallKit,Android上的Telecom). | 参数 | 类型 | 说明 | | --- | --- | --- | | **`eventName`** | `'outgoingCallInitiated'` | \- 活动名称('退出CallInitated') | | **`listenerFunc`** | `(data: { callSid: string; to: string; source: 'app' | 'system'; displayName?: string; }) => void` | \- 处理事件的召回功能 | **回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-pluginlistenerhandle)>` * * * ### 添加收听器( '退出CallFlied', ...) ```typescript addListener(eventName: 'outgoingCallFailed', listenerFunc: (data: { callSid: string; to: string; reason: 'missing_access_token' | 'connection_failed' | 'no_call_details' | 'microphone_permission_denied' | 'invalid_contact' | 'callkit_request_failed' | 'unsupported_intent'; displayName?: string; }) => void) => Promise ``` 正在发送的呼叫失败事件. 此事件因各种原因无法连接而启动 例如缺少证书、许可问题或网络问题. | 参数 | 类型 | 说明 | | --- | --- | --- | | **`eventName`** | `'outgoingCallFailed'` | \- 活动名称( '退出Call Fault' ) | | **`listenerFunc`** | `(data: { callSid: string; to: string; reason: 'missing_access_token' | 'connection_failed' | 'no_call_details' | 'microphone_permission_denied' | 'invalid_contact' | 'callkit_request_failed' | 'unsupported_intent'; displayName?: string; }) => void` | \- 处理事件的召回功能 | **回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-pluginlistenerhandle)>` * * * ### 添加倾听器( “ 调用断开连接 ” ,...) ```typescript addListener(eventName: 'callDisconnected', listenerFunc: (data: { callSid: string; error?: string; }) => void) => Promise ``` 听电话断开事件. 正常情况下或由于出错,此事件在呼叫结束时被解除. | 参数 | 类型 | 说明 | | --- | --- | --- | | **`eventName`** | `'callDisconnected'` | \- 事件名称( “ call Disconnect ” ) | | **`listenerFunc`** | `(data: { callSid: string; error?: string; }) => void` | \- 处理事件的召回功能 | **回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-pluginlistenerhandle)>` * * * ### 添加倾听器( “ calling ” ,...) ```typescript addListener(eventName: 'callRinging', listenerFunc: (data: { callSid: string; }) => void) => Promise ``` 听电话响起事件. 当另一端的电话响起时,此事件即被发射. | 参数 | 类型 | 说明 | | --- | --- | --- | | **`eventName`** | `'callRinging'` | \- 活动名称("叫Ring") | | **`listenerFunc`** | `(data: { callSid: string; }) => void` | \- 处理事件的召回功能 | **回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-pluginlistenerhandle)>` * * * ### 添加倾听器( “ 调用重联 ” ,...) ```typescript addListener(eventName: 'callReconnecting', listenerFunc: (data: { callSid: string; error?: string; }) => void) => Promise ``` 听电话重联事件. 当一个电话失去连接而Twilio试图 重新连接。 电话尚未中断, 但音频可能会被中断 . | 参数 | 类型 | 说明 | | --- | --- | --- | | **`eventName`** | `'callReconnecting'` | \- 事件名称 (“ reconnection” ) | | **`listenerFunc`** | `(data: { callSid: string; error?: string; }) => void` | \- 处理事件的召回功能 | **回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-pluginlistenerhandle)>` * * * ### 添加倾听器( “ reconnected ” ,...) ```typescript addListener(eventName: 'callReconnected', listenerFunc: (data: { callSid: string; }) => void) => Promise ``` 听电话重联事件. 当一个呼叫在连接丢失后成功重新连接时,此事件会被启动 . 在此事件之后, 音频应正常恢复 . | 参数 | 类型 | 说明 | | --- | --- | --- | | **`eventName`** | `'callReconnected'` | \- 事件名称 (“ reconnected ” ) | | **`listenerFunc`** | `(data: { callSid: string; }) => void` | \- 处理事件的召回功能 | **回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-pluginlistenerhandle)>` * * * ### 添加倾听器( 调用“ 质量警告” 更改 ,...) ```typescript addListener(eventName: 'callQualityWarningsChanged', listenerFunc: (data: { callSid: string; currentWarnings: string[]; previousWarnings: string[]; }) => void) => Promise ``` 听电话 质量警告事件. 当调用质量发生变化时, 此事件会开火, 并给出警告 可能的问题,如高焦虑,包丢失,或低音频水平. | 参数 | 类型 | 说明 | | --- | --- | --- | | **`eventName`** | `'callQualityWarningsChanged'` | \- 事件名称(称为“ 质量警告” ) | | **`listenerFunc`** | `(data: { callSid: string; currentWarnings: string[]; previousWarnings: string[]; }) => void` | \- 处理事件的召回功能 | **回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-pluginlistenerhandle)>` * * * ### 添加倾听器( “ 注册成功 ” ,...) ```typescript addListener(eventName: 'registrationSuccess', listenerFunc: () => void) => Promise ``` 倾听成功注册活动. 当设备与 Twilio Voice 成功注册时, 此事件会被发射 准备打电话接听 这通常发生在成功之后 以有效的访问符登录. | 参数 | 类型 | 说明 | | --- | --- | --- | | **`eventName`** | `'registrationSuccess'` | \- 事件名称(“注册成功”) | | **`listenerFunc`** | `() => void` | \- 处理事件的召回功能 | **回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-pluginlistenerhandle)>` * * * ### 添加倾听器( “ 注册失败 ” ,...) ```typescript addListener(eventName: 'registrationFailure', listenerFunc: (data: { error: string; }) => void) => Promise ``` 登记失败事件. 当设备无法与Twilio Voice注册时, 通常由于无效或过期的访问符、网络问题,或 Twilio的服务问题. | 参数 | 类型 | 说明 | | --- | --- | --- | | **`eventName`** | `'registrationFailure'` | \- 事件名称(“注册失败”) | | **`listenerFunc`** | `(data: { error: string; }) => void` | \- 处理事件的召回功能 | **回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-pluginlistenerhandle)>` * * * ### 删除所有收听器( ) ```typescript removeAllListeners() => Promise ``` 删除所有已注册事件听众 . 当组件卸载时或当您想要清理时,此功能可用于清理 重置全部事件处理 . * * * ### 获取 PluginVersion () ```typescript getPluginVersion() => Promise<{ version: string; }> ``` 获取本地 Capacitor 插件版本 **回返情况:** `Promise<{ version: string; }>` * * * ### 接口 #### 调用邀请 代表即将收到的电话邀请. 此接口描述已收到的呼叫邀请的数据结构 但尚未接受或拒绝。 同一结构用于 `callInviteReceived` 事件和情况 `pendingInvites` 数组返回 `getCallStatus()`。 。 。 . | Prop | 类型 | 说明 | | --- | --- | --- | | **`callSid`** | `string` | 收到的呼叫邀请的独特标识符 | | **`from`** | `string` | 呼叫者的电话号码或客户身份标识(可能包括自定义的呼叫者名称) | | **`to`** | `string` | 电话号码或客户身份 | | **`customParams`** | `[Record](https://npmcn.com/package/%40capgo/capacitor-twilio-voice/#readme-record)` | 自定义参数随呼叫邀请相传 | #### 插件听筒 | Prop | 类型 | | --- | --- | | **`remove`** | `() => Promise` | ### 类型异名 #### 记录 构造 T 类型 K 的一组属性类型 `{ [P in K]: T; }` ## 常见问题 ### @capgo/capacitor-twilio-voice 是什么？ 将Twilio Voice SDK 整合到控制器中 ### 如何安装 @capgo/capacitor-twilio-voice？ 在项目目录运行 npm install @capgo/capacitor-twilio-voice，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @capgo/capacitor-twilio-voice 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @capgo/capacitor-twilio-voice 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @capgo/capacitor-twilio-voice 可以商用吗？ @capgo/capacitor-twilio-voice 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。 ### @capgo/capacitor-twilio-voice 的下载量有多少？ 根据 npm 官方下载统计，@capgo/capacitor-twilio-voice 在 2026/10/09 – 2026/11/07 这 30 天内被下载 81,531 次，日均约 2,718 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @capgo/capacitor-twilio-voice 还在维护吗？ 最新版本 8\.2\.28 发布于 2026/11/02（7 天前）；至今共发布 99 个版本，其中过去 12 个月发布了 72 个；首次发布于 2025/08/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。