Incoming Calls and Registration for Push Notifications

How can my App receive calls?

To be able to receive incoming calls, you need to setup your push certificate in the Console and your app needs to register for incoming calls using [TwilioVoiceSDK registerWithAccessToken:deviceToken:completion]. Twilio will send you a push notification through APNS (Apple Push Notification Service). Check our quickstart implementation for how it is done.

Can the App receive incoming VoIP calls while it's not running or in the background?

Yes! See the FAQ “How can my App receive calls” to register for incoming calls. Once the app is registered, it will receive calls even when it’s in the background or not running.

How often should I register my device token?

The device token must be registered every time it changes or if the device has not received a push notification for 1 year. We recommend you implement the following logic:

  1. Invoke [TwilioVoiceSDK registerWithAccessToken:deviceToken:completion] the first time the App is launched
  2. Store the device token and the current time. This is necessary to determine if the device token has changed
  3. Implement PKPushRegistryDelegate and check when the token is updated or invalidated. Compare it to the token value stored in 2. If it has changed, invoke[TwilioVoiceSDK registerWithAccessToken:deviceToken:completion] and store the new device token value.
  4. Check when [TwilioVoiceSDK registerWithAccessToken:deviceToken:completion] was last invoked. If it has been over 6 months, register the token again to not let it expire.

What's the difference between an Access Token and a Device Token?

An Access Token is required to access Twilio's services. A device token is a token that identifies the device so it can receive a push notification.

  • アクセストークンを供給するエンドポイントを作成しましたが、着信通話のプッシュ通知に対する登録に失敗し続けるのはなぜですか?
    • Programmable Voice SDK用に、アクセストークンに VoiceGrant を追加しているか確認してください。
    • アクセストークンの作成に不正なAPIキーとシークレットを使用していた可能性があります。 APIキーが作成されたらこれを外部に公開しないよう管理してください。 またアクセストークンを作成するにはAPIキーとシークレット両方を使用してください。
    • Twilioによって許可されている最大有効期限は24時間、すなわち86,400秒です。 有効期限が <= (86400 -1) となっていることを確認してください。
    • APIキーとシークレットがメインアカウントとサブアカウントとの間で共有可能になっていません。
    • アクセストークンの identity が空ではないことを確認してください。
  • SDKが登録成功を知らせているにも関わらず、着信通話のプッシュ通知が受信されないのはなぜですか?
    • Twilio Programmable Voice iOS SDKでは、Twilioが開発者に代わってVoIPプッシュ通知を送信できるようにするため、AppleのVoIP Service証明書が必須です。 通常のAPNS証明書を使用する場合、TwilioはAppleのVoIP Serviceエンドポインとへのプッシュ通知の送信に失敗します。
    • VoIP Service証明書の作成には新鮮なCSR (証明書署名リクエスト) を使用してください。 前回のAPNS証明書の作成に使用されたCSRの使用は、VoIP Service証明書でサービスタイプの混乱を引き起こします。
    • 開発フェーズの期間中は、「sandbox」オプションのチェックをオンにした状態でプッシュクレデンシャルを作成し、Appのplistに「APS Environment: development」が存在するようにしてください。 AppのStoreへの申請準備が整ったら、plistを「APS Environment: production」に更新し、sandboxオプションのチェックをオフにした状態で別個のプッシュクレデンシャルを作成してください。
    • Please make sure you have not modified the device token requested using the PKPushRegistry and use it in the registration methods. Also be sure to notice that the description method on the NSData class has changed in iOS 13, and your code may need to be updated. To properly convert an NSData object to a String, use one of these examples:
    /* Obj-C */
    - (void)pushRegistry:(PKPushRegistry *)registry
            didUpdatePushCredentials:(PKPushCredentials *)credentials
                 forType:(NSString *)type {
                const unsigned *tokenBytes = [credentials.token bytes];
                self.deviceTokenString = [NSString stringWithFormat:@"<%08x %08x %08x %08x %08x %08x %08x %08x>",
                                  ntohl(tokenBytes[0]), ntohl(tokenBytes[1]), ntohl(tokenBytes[2]),
                                  ntohl(tokenBytes[3]), ntohl(tokenBytes[4]), ntohl(tokenBytes[5]),
                                  ntohl(tokenBytes[6]), ntohl(tokenBytes[7])];
        // Call registerWithAccessToken:deviceToken:completion: ...
    /* Swift */
    func pushRegistry(_ registry: PKPushRegistry, didUpdate credentials: PKPushCredentials, forType type: PKPushType) {
        let deviceToken = credentials.token.map { String(format: "%02x", $0) }.joined()
        self.deviceTokenString = deviceToken
        // Call registerWithAccessToken:deviceToken:completion: ...
  • I was using the iOS TwilioClient 1.2 SDK and just migrated to the Programmable Voice SDK. Why am I getting “Authentication error” using my Capability Token?
    • Programmable Voice SDKにおける認証には、Twilioアクセストークンと呼ばれる新しいトークン形式が必須です。 トークンを供給するエンドポイントでアプリケーションに対してアクセストークンを生成するよう更新してください。


  • pod install を実行しましたが、最新バージョンのSDKが見つかりません
    • Cocoapods v1.xを使用している場合は、新バージョンのVoice SDKをインストールする前に pod repo update を実行してください。
  • 「Include of non-modular header inside framework module 'TwilioVoiceClient’ (フレームワークモジュール『TwilioVoiceClient』内に非モジュラーヘッダーが含まれています) という出力があり、Swift AppにCocoapodsを使用したSDKのインストールが行えません。
    • Cocoapodsライブラリーを最新バージョンに更新してください。


  • CXStartCallAction リクエストを CXCallController に送信時に @"com.apple.CallKit.error.requesttransaction" - code: 1 エラーが発生し、SDKを使用して通話を発信できません。
    • AppのProject Settingsの Capabilities ページにアクセスし、Voice over IP オプションがオンになっているか確認してください。


  • 「failed to create audio device (オーディオデバイスの作成に失敗しました」というエラーが表示されるのはなぜですか?
    • Programmable Voice iOS SDKではシステムのオーディオデバイスのプロパティーにアクセスするため、AVAudioSession のカテゴリーが .playAndRecord である必要があります。 AVAudioSession に対して特別な操作の実行が必要な場合、通話の発着信に先立ってカテゴリーを .playAndRecord に戻すようにしてください。
  • 通話中にオーディオを録音できますか?
    • AVAudioRecorder を使用してアクティブな通話中にオーディオを録音することができますが、デバイスの入力ソースの録音のみが可能という制限があります。


My phone has been off for a while and when I turn it back on, I get calls that were already hung up

Note: The following does not apply to sdk versions 2.1 onwards and 5.0 onwards. The push notification sent to those versions will expire within 30 seconds.

Twilio Voice SDKs use push notifications (APNS, FCM/GCM) as a mechanism to notify the callee of an incoming call. However, a problem presents itself when the callee‘s device is offline or not reachable: the push notification services cache the notification and re-attempt delivery at a much later time. The delayed notification may arrive after the call has already been terminated. The callee‘s device will briefly alert the user of a call that has already terminated leading to a poor user experience. Twilio plans to address this issue in a later release. However, in the meantime the following is a proposal for a work around you can implement to avoid the poor user experience.

The following 4 step proposal allows an app developer to use time information as an additional criteria to determine whether or not to display a call notification to the user.

Step 1 Generate a UTC based timestamp on the TwiML Application Server based on the Unix epoch in milliseconds.

var timeInMS = Date.now()

Step 2 Add this generated timestamp to the used to reach the callee

Parameters can be sent to a callee by initiating a TwiML . Use the attribute to specify your key/value parameters as shown below. The value shown below is an example of a timestamp obtained in step 1. You must pass the value as string. Pass the time as custom parameters in TwiML

<?xml version="1.0" encoding="UTF-8"?>
        <Dial answerOnBridge="false" callerId="client:alice">
                <Parameter name="timestamp" value="1555825985"  />

When the call invite push message arrives to the callee it will have the specified parameters.

Step 3 Get the timestamp from the bundle or message provided by APNS when it arrives to the iOS application.

2.X SDKs

When receiving the push notification from Twilio, you can obtain the parameter from the bundle or message. The parameters are provided by APNS payload as the key: twi_params. The following shows how you can parse the contents of the data to get a map of the parameters you passed into the Dial. The “data” variable is the map provided by APNS

NSString *customParams = notificationPayload[@”twi_params”];
NSMutableDictionary *customParamsDict = [NSMutableDictionary dictionary];
If ([customParams length] > 0) {
    NSArray *paramPairs = [customParams componentsSeparatedByString:@"&"];
    for (NSString *param in paramPairs) {
        NSArray *keyValue = [param componentsSeparatedByString:@"="];
        if ([keyValue count] == 2) {
            NSString *decodedValue = [keyValue[1] stringByReplacingOccurrencesOfString:@"+" withString:@"%20"];
            customParamsDict[keyValue[0]] = [decodedValue stringByRemovingPercentEncoding];
3.X+ SDKs

When receiving the push notification from Twilio, you can obtain the parameter from TVOCallInvite with the following:

NSDictionary *customParameters = callInvite.customParameters;
NSString *timestamp = customParameters[@”timestamp”];

Step 4 Compare the UTC based timestamp to the UTC time on the device and discard the notification if the device time is significantly later than the timestamp generated by the server.

// Get the timestamp from the customParameters map and the current device time
NSUInteger timestampValue = [customParameters[@”timestamp”] unsignedIntegerValue];
NSDate now = [NSDate date];

// Compare the time difference
if ([now timeIntervalSince1970] > timestampValue + 60000) {
  // discard notification...
} else {
  // display notification...


How to file a support ticket or create a GitHub issue

弊社ではご意見やご質問、ことにデバッグに役立つ情報の添えられたものを歓迎し、迅速に診断およびお答えします。 Issueやサポートチケットの送信時には、以下についてお知らせいただけると幸いです:

  • 説明 - 実現しようとしていること、再現手順、発生し散る事象。
  • SDKのバージョン
  • SDKのverbose log - 弊社チームがデバッグを行う上で、SDKログは常に最良の資料になります。 SDKのログレベルの構成:
    /* Obj-C */
    [VoiceClient setLogLevel:TVOLogLevelVerbose];
    /* Swift */ 
    VoiceClient.logLevel = .verbose
  • TwilioのアカウントSID
  • TwilioのCall SID


サポートチケットよりGitHubでのIssueの発行 (英語) をお勧めします。 コミュニティー全体の利益となるためです。

GitHubのIssueにはいかなる機密情報も含めないようご注意ください。 認証トークン、署名用キーのシークレットなどが含まれます。 シークレットを共有する必要がある場合は、必ずtwilio_support@kddi-web.comにメールを送信するようにし、GitHubのIssueへの参照を含めるようにしてください。



We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.



        Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!


        Get link

        Get a free personal referral link here


        Give $10

        Your user signs up and upgrade using link


        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more