TwilioVoiceSDK

@brief The current logging level used by the SDK.

@discussion The default logging level is TVOLogLevelError. TwilioVoiceSDK and its components use NSLog internally.

@brief Specify reporting statistics to Insights.

@discussion Sending stats data to Insights is enabled by default.

@brief The edge value is a Twilio Edge name that corresponds to a geographic location of Twilio infrastructure that the client will connect to.

@discussion The default value roaming automatically selects an edge based on the latency between client and available edges. roaming requires the upstream DNS to support RFC7871. See Global Low Latency requirements for more information.

edge value must be specified before calling TwilioVoiceSDK.handleNotification().

See the new Edge names for possible values.

@brief The TVOAudioDevice used to record and playback audio in a Call.

@discussion If you wish to provide your own TVOAudioDevice then you must set it before performing any other actions with the SDK like connecting to a Call. It is also possible to change the device when you are no longer connected to any Calls and have destroyed all other SDK objects.

@brief The TVOLogger used for logging.

@discussion If you wish to provide your own TVOLogger then you can set it by using this property. Please refer to the changelog to see an example how this property can be set using a custom logger.

@brief Returns the version of the SDK.

@brief Sets the logging level for an individual module.

@brief Retrieve the log level for a specific module in the TwilioVoice SDK.

@brief Registers for Twilio VoIP push notifications.

@discussion Registering for push notifications is required to receive incoming call notification messages through Twilio’s infrastructure. Once successfully registered, the registered binding has a time-to-live(TTL) of 1 year. If the registered binding is inactive for 1 year it is deleted and push notifications to the registered identity will not succeed. However, whenever the registered binding is used to reach the registered identity the TTL is reset to 1 year. A successful registration will ensure that push notifications will arrive via the APNs for the lifetime of the registration device token provided by the APNs instance.

Your app must initialize PKPushRegistry with PushKit push type VoIP at the launch time. As mentioned in the PushKit guidelines, 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.

If the registration is successful the completion handler will contain a Null NSError. If the registration fails, the completion handler will have a nonnull NSError with UserInfo string describing the reason for failure.

Insights

** An example of using the registration API **

  - (void)pushRegistry:(PKPushRegistry *)registry
  didUpdatePushCredentials:(PKPushCredentials *)credentials
           forType:(NSString *)type {
      [TwilioVoiceSDK registerWithAccessToken:accessToken
                                  deviceToken:credentials.token
                                   completion:^(NSError *error) {
          if(error != nil) {
              NSLog("Failed to register for incoming push: %@\n\t  - reason: %@", [error localizedDescription], [error localizedFailureReason]);
          } else {
              NSLog("Registration successful");
          }
      }];

The maximum number of characters for the identity provided in the token is 121. The identity may only contain alpha-numeric and underscore characters. Other characters, including spaces, or exceeding the maximum number of characters, will result in not being able to place or receive calls.

To specify a home region where your data is stored, use the twr specifier in the access token header as the example below:

{
  "alg": "HS256",
  "typ": "JWT",
  "cty": "twilio-fpa;v=1",
  "twr": "au1"
}

This can also be done by using the Twilio helper libraries when generating the access token. Here is an example of using the Twilio Node.js helper library:

const accessToken = new twilio.jwt.AccessToken( credentials.accountSid, credentials.apiKeySid, credentials.apiKeySecret, { identity, ttl, region: ‘au1’, }, );

Note that the home region configuration is only scoped to one registration request.

- parameter: accessToken Twilio Access Token.
- parameter: deviceToken The push registry token raw data for Apple VoIP Service.
- parameter: completion Callback block to receive the result of the registration.

@brief Unregisters from Twilio VoIP push notifications.

@discussion Call this method when you no longer want to receive push notifications for incoming Calls.

If the unregistration is successful the completion handler will contain a Null NSError. If the unregistration fails, the completion handler will have a nonnull NSError with UserInfo string describing the reason for failure.

Insights

** An example of using the unregistration API **

   [TwilioVoiceSDK unregisterWithAccessToken:accessToken
                                 deviceToken:deviceToken
                                  completion:^(NSError *error) {
       if(error != nil) {
           NSLog("Failed to unregister for incoming push: %@\n\t  - reason: %@", [error localizedDescription], [error localizedFailureReason]);
       } else {
           NSLog("Unregistration successful");
       }
   }];

The maximum number of characters for the identity provided in the token is 121. The identity may only contain alpha-numeric and underscore characters. Other characters, including spaces, or exceeding the maximum number of characters, will result in not being able to place or receive calls.

To specify a home region where your data is stored, use the twr specifier in the access token header as the example below:

{
  "alg": "HS256",
  "typ": "JWT",
  "cty": "twilio-fpa;v=1",
  "twr": "au1"
}

This can also be done by using the Twilio helper libraries when generating the access token. Here is an example of using the Twilio Node.js helper library:

const accessToken = new twilio.jwt.AccessToken( credentials.accountSid, credentials.apiKeySid, credentials.apiKeySecret, { identity, ttl, region: ‘au1’, }, );

Note that the home region configuration is only scoped to one registration request.

 - parameter: accessToken Twilio Access Token.
 - parameter: deviceToken The push registry token raw data for Apple VoIP Service.
 - parameter: completion Callback block to receive the result of the unregistration.

@brief Processes an incoming VoIP push notification payload.

@discussion This method will synchronously process call notification payload and call the provided delegate on the same dispatch queue.

@discussion If you are specifying an edge value via the TwilioVoiceSDK.edge property you must do so before calling this method.

Twilio sends a call notification via Apple VoIP Service. The notification type is encoded in the dictionary with the key twi_message_type and the value twilio.voice.call.

A call notification is sent when someone wants to reach the registered identity. Passing a call notification into this method will result in a callInviteReceived: callback with a <TVOCallInvite> object and return YES.

To ensure that a cancellation is reported via the [TVONotificationDelegate cancelledCallInviteReceived:error:] callback, the TVOCallInvite must be retained until the call is accepted or rejected.

Insights

** An example of using the handleNotification API **

 @interface CallViewController () <PKPushRegistryDelegate, TVONotificationDelegate, TVOCallDelegate, ... >

 // property declarations

 @end

 @implementation CallViewController

 // ViewController setup and other code ...

 #pragma mark - PKPushRegistryDelegate

 - (void)pushRegistry:(PKPushRegistry *)registry
     didReceiveIncomingPushWithPayload:(PKPushPayload *)payload
     forType:(NSString *)type {
         NSLog(@"Received incoming push: %@", payload.dictionaryPayload);

         if ([type isEqualToString:PKPushTypeVoIP]) {
             if (![TwilioVoiceSDK handleNotification:payload.dictionaryPayload delegate:self]) {
                 NSLog(@"The push notification was not a Twilio Voice push notification");
         }
     }
 }

 #pragma mark - TVONotificationDelegate methods

 - (void)callInviteReceived:(TVOCallInvite *)callInvite {
     // handle call invite
 }

 - (void)cancelledCallInviteReceived:(TVOCancelledCallInvite *)cancelledCallInvite {
     // handle cancelled call invite
 }

 @end

@brief Processes an incoming VoIP push notification payload.

@discussion This method will synchronously process call notification payload and call the provided delegate on the same dispatch queue.

@discussion If you are specifying an edge value via the TwilioVoiceSDK.edge property you must do so before calling this method.

Twilio sends a call notification via Apple VoIP Service. The notification type is encoded in the dictionary with the key twi_message_type and the value twilio.voice.call.

A call notification is sent when someone wants to reach the registered identity. Passing a call notification into this method will result in a callInviteReceived: callback with a <TVOCallInvite> object and return YES.

To ensure that a cancellation is reported via the [TVONotificationDelegate cancelledCallInviteReceived:error:] callback, the TVOCallInvite must be retained until the call is accepted or rejected.

Insights

** An example of using the handleNotification API **

 @interface CallViewController () <PKPushRegistryDelegate, TVONotificationDelegate, TVOCallDelegate, TVOCallMessageDelegate ... >

 // property declarations

 @end

 @implementation CallViewController

 // ViewController setup and other code ...

 #pragma mark - PKPushRegistryDelegate

 - (void)pushRegistry:(PKPushRegistry *)registry
     didReceiveIncomingPushWithPayload:(PKPushPayload *)payload
     forType:(NSString *)type {
         NSLog(@"Received incoming push: %@", payload.dictionaryPayload);

         if ([type isEqualToString:PKPushTypeVoIP]) {
             if (![TwilioVoiceSDK handleNotification:payload.dictionaryPayload delegate:self callMessageDelegate:self]) {
                 NSLog(@"The push notification was not a Twilio Voice push notification");
         }
     }
 }

 #pragma mark - TVONotificationDelegate methods

 - (void)callInviteReceived:(TVOCallInvite *)callInvite {
     // handle call invite
 }

 - (void)cancelledCallInviteReceived:(TVOCancelledCallInvite *)cancelledCallInvite {
     // handle cancelled call invite
 }

 @end

@brief Make an outgoing Call.

@discussion This method is guaranteed to return a <TVOCall> object. It’s possible for the returned Call to either succeed or fail to connect.

If you are specifying an edge value via the TwilioVoiceSDK.edge property you must do so before calling this method.

The <TVOCallDelegate> will receive the Call state update callbacks. The callbacks are listed here.

If connect fails, call:didFailToConnectWithError or call:didDisconnectWithError callback is raised with an NSError object. [error localizedDescription], [error localizedFailureReason] and [error code] provide details of the failure.

If any authentication error occurs then the SDK will receive one of the following errors.

If any connection fails because of any other error then the SDK will receive one of the following errors.

Insights

If connection fails then an error event will be published.

** An example of using the connectWithAccessToken:delegate: API **

  @interface CallViewController () <TVOCallDelegate, ... >

  // property declarations

  @end

  @implementation CallViewController

  // ViewController setup and other code ...

  - (void)makeCall:(NSString*)accessToken
      self.call = [TwilioVoiceSDK connectWithAccessToken:accessToken delegate:self];
  }

  #pragma mark - TVOCallDelegate

  - (void)callDidStartRinging:(TVOCall *)call {
      NSLog(@"Call is ringing at called party %@", call.to);
  }

  - (void)call:(TVOCall *)call didFailToConnectWithError:(NSError *)error {
      NSLog("Failed to Connect the Call: %@\n\t  - reason: %@", [error localizedDescription], [error localizedFailureReason]);
  }

  - (void)call:(TVOCall *)call didDisconnectWithError:(NSError *)error {
      if (error) {
          NSLog(@"Call disconnected with error: %@", error);
      } else {
          NSLog(@"Call disconnected");
      }
  }

  - (void)callDidConnect:(TVOCall *)call {
      NSLog(@"Call connected.");
  }

  @end

The maximum number of characters for the identity provided in the token is 121. The identity may only contain alpha-numeric and underscore characters. Other characters, including spaces, or exceeding the maximum number of characters, will result in not being able to place or receive calls.

To specify a home region where your data is stored, use the twr specifier in the access token header as the example below:

{
  "alg": "HS256",
  "typ": "JWT",
  "cty": "twilio-fpa;v=1",
  "twr": "au1"
}

This can also be done by using the Twilio helper libraries when generating the access token. Here is an example of using the Twilio Node.js helper library:

const accessToken = new twilio.jwt.AccessToken( credentials.accountSid, credentials.apiKeySid, credentials.apiKeySecret, { identity, ttl, region: ‘au1’, }, );

Note that the home region configuration is only scoped to one call.

 - parameter: accessToken The access token.
 - parameter: delegate A `<TVOCallDelegate>` to receive Call state updates.

 - returns: A `<TVOCall>` object.

 - see: TVOCall
 - see: TVOCallDelegate

@brief Make an outgoing Call.

@discussion This method is guaranteed to return a <TVOCall> object. It’s possible for the returned Call to either succeed or fail to connect. Use the <TVOConnectOptions> builder to specify Call parameters and UUID.

@discussion If you are specifying an edge value via the TwilioVoiceSDK.edge property you must do so before calling this method.

The <TVOCallDelegate> will receive the Call state update callbacks. The callbacks are same as connectWithAccessToken:delegate: API.

If connect fails, call:didFailToConnectWithError or call:didDisconnectWithError callback is raised with an NSError object. [error localizedDescription], [error localizedFailureReason] and [error code] provide details of the failure. The error codes are same as connectWithAccessToken:delegate: API.

Insights

If connection fails then an error event will be published.

** An example of using the connectWithAccessToken:delegate API **

   @interface CallViewController () <TVOCallDelegate, ... >

   // property declarations

   @end

   @implementation CallViewController

   // ViewController setup and other code ...

   - (void)makeCall:(NSString *)accessToken uuid:(NSString *)uuid to:(NSString *)phoneNumber
       NSMutableDictionary *params = [NSMutableDictionary dictionary];

       if ([to length] > 0) {
           params[@"Mode"] = @"Voice";
           params[@"PhoneNumber"] = phoneNumber;
       }

       TVOConnectOptions *connectOptions = [TVOConnectOptions optionsWithAccessToken:accessToken
           block:^(TVOConnectOptionsBuilder *builder) {
               builder.params = params;
               builder.uuid = uuid;
       }];

       self.call = [TwilioVoiceSDK connectWithOptions:connectOptions delegate:self];
   }

   #pragma mark - TVOCallDelegate

   - (void)callDidStartRinging:(TVOCall *)call {
       NSLog(@"Call is ringing at called party %@", call.to);
   }

   - (void)call:(TVOCall *)call didFailToConnectWithError:(NSError *)error {
       NSLog("Failed to Connect the Call: %@\n\t  - reason: %@", [error localizedDescription], [error localizedFailureReason]);
   }

   - (void)call:(TVOCall *)call didDisconnectWithError:(NSError *)error {
       if (error) {
           NSLog(@"Call disconnected with error: %@", error);
       } else {
           NSLog(@"Call disconnected");
       }
   }

   - (void)callDidConnect:(TVOCall *)call {
       NSLog(@"Call connected.");
   }

@end

To specify a home region where your data is stored, use the twr specifier in the access token header as the example below:

 {
   "alg": "HS256",
   "typ": "JWT",
   "cty": "twilio-fpa;v=1",
   "twr": "au1"
 }

 This can also be done by using the Twilio helper libraries when generating the access token. Here is an example of using the Twilio Node.js helper library:

const accessToken = new twilio.jwt.AccessToken( credentials.accountSid, credentials.apiKeySid, credentials.apiKeySecret, { identity, ttl, region: ‘au1’, }, );

 Note that the home region configuration is only scoped to one call.

  - parameter: options The connect options.
  - parameter: delegate A `<TVOCallDelegate>` to receive Call state updates.

  - returns: A `<TVOCall>` object.

  - see: TVOCall
  - see: TVOCallDelegate
  - see: TVOConnectOptions

@brief Run a preflight test.

@brief Run a preflight test.

Undocumented