iOS SDK V2 - Reference

The Plivo iOS SDK allows you to create applications capable of making and receiving calls in your iOS app. This document gives an overview of different classes and methods available in Plivo iOS SDK v2.

Initialization of Application

Registering an endpoint

The following code demonstrates registering an endpoint using a Plivo SIP URI and its password.

NSString *username = @"Tatooine";
NSString *password = @"Jabba";
PlivoEndpoint *endpoint = [[PlivoEndpoint alloc] init];
[endpoint login:username AndPassword:password];

Access to Microphone

We have to provide Microphone access before making an outbound call or receiving an incoming call using AVFoundation

import AVFoundation

//Request Record permission
let session = AVAudioSession.sharedInstance()
if (session.responds(to: #selector(AVAudioSession.requestRecordPermission(_:)))) {
    AVAudioSession.sharedInstance().requestRecordPermission({(granted: Bool)-> Void in
        if granted {
            print("granted AVAudioSession permission")
            do {
                try session.setCategory(AVAudioSession.Category.playAndRecord, mode: .default, options: [])
                try session.setActive(true)
            }
            catch {
                print("Couldn't set Audio session category")
            }
        } else{
            print("not granted AVAudioSession permission")
        }
    })
}

Examples for basic call actions

Making an outbound call

The following code demonstrates making an outbound call from the SDK.

NSString *toURI = @"sip:Coruscant@phone.plivo.com";
PlivoOutgoing *outgoing = [endpoint createOutgoingCall];
[outgoing call:toURI];

Receiving a call

The following code demonstrates receiving an incoming call in the SDK.

(void)onIncomingCall:(PlivoIncoming*)incoming
{
    *// Answer the call*
    [incoming answer];
}

Note: For more information on implementing incoming call in your iOS application, see the push notification section.

Classes and Methods

Class: PlivoEndpoint (PlivoEndpoint.h)

PlivoEndpoint (PlivoEndpoint.h) class allows you to register a Plivo SIP Endpoint. Once an endpoint is registered, you can make or receive calls using the endpoint. Following are the methods available in the PlivoEndpoint class.

Method 1: Registering an Endpoint

If the endpoint is successfully registered, a notification will be sent to the registerSuccess delegate. In case of a failure, a notification is sent to the registerFailure delegate.

(void)login:(NSString*) username AndPassword:(NSString*) password;

Usage

func login(withUserName userName: String, andPassword password: String) {
    UtilClass.makeToastActivity()
    endpoint.login(userName, andPassword: password)
}

Method 2: Unregister an Endpoint

This method is used to unregister an endpoint.

(void)logout;

Method 3: Create Object for initiating Outbound calls

Calling this method returns a PlivoOutgoing object, linked to the registered endpoint. Calling this method on an unregistered PlivoEndpoint object returns an empty object.

(PlivoOutgoing*)createOutgoingCall;

Class: PlivoOutgoing (PlivoOutgoing.h)

PlivoOutgoing class contains methods to make and control an outbound call.

Method 1: Initiate Outbound calls

Calling this method on the PlivoOutgoing object with the SIP URI would initiate an outbound call.

(void)call:(NSString *)sipURI error:(NSError **)error;

Method 2: Initiate Outbound calls with custom SIP headers

Calling this method on the PlivoOutgoing object with the SIP URI would initiate an outbound call with custom SIP headers.

(void)call:(NSString *)sipURI headers:(NSDictionary *)headers error:(NSError **)error;

Usage

func call(withDest dest: String, andHeaders headers: [AnyHashable: Any], error: inout NSError?) -> PlivoOutgoing {
	/* construct SIP URI , where kENDPOINTURL is a contant contaning domain name details*/
	let sipUri: String = "sip:\(dest)\(kENDPOINTURL)"
	/* create PlivoOutgoing object */
	outCall = (endpoint.createOutgoingCall())!
	/* do the call */
	outCall?.call(sipUri, headers: headers, error: &error)
	return outCall!
}

//To Configure Audio
func configureAudioSession() {
	endpoint.configureAudioDevice()
}

Method 3: Mute a call

Calling this method on the PlivoOutgoing object mutes the call.

(void)mute;

Usage

func onIncomingCall(_ incoming: PlivoIncoming) {
..

// assign incCall var
 incCall = incoming
}
// to mute incoming call
if (incCall != nil) {
 incCall?.mute()
 }

Method 4: Unmute a call

Calling this method on the PlivoOutgoing object unmutes the call.

(void)unmute;

Usage

if (incCall != nil) {

 incCall?.unmute()

}

Method 5: Send Digits

Calling this method on the PlivoOutgoing object with the digits sends DTMF on that call. DTMF input only supports 0-9 , *, and #.

(void)sendDigits:(NSString*)digits;

Usage

func getDtmfText(_ dtmfText: String) {

    if (incCall != nil) {

        incCall?.sendDigits(dtmfText)

        ..

    }

}

Method 6: Hangup a call

Calling this method on the PlivoOutgoing object would hang up the call.

(void)hangup;

Usage

if (self.incCall != nil) {
    print("Incoming call - Hangup");
    self.incCall?.hangup()
    self.incCall = nil
}

Method 7: Hold a call

Calling this method on the PlivoOutgoing object disconnects the audio devices during an audio interruption.

(void)hold;

Usage

if (incCall != nil) {
    incCall?.hold()
}
if (outCall != nil) {
    outCall?.hold()
}
Phone.sharedInstance.stopAudioDevice()

Method 8: Unhold a call

Calling this method on the PlivoOutgoing object reconnects the audio devices after an audio interruption.

(void)unhold;

Description

Usage

if (incCall != nil) {
	 incCall?.unhold()
}
if (outCall != nil) {
	 outCall?.unhold()
}
Phone.sharedInstance.startAudioDevice()

Class: PlivoIncoming(PlivoIncoming.h)

PlivoIncoming class contains methods to handle incoming call. An object of this class will be received on the following delegate.

(void)incomingCall:(PlivoIncoming*) incoming;

Method 1: Answer an Incoming call

Calling this method on the PlivoIncoming object answers the call.

(void)answer;

Usage

func provider(_ provider: CXProvider, perform action: CXAnswerCallAction) {
  //Answer the call
   incCall?.answer()
  outCall = nil
  action.fulfill()

Method 2: Reject an Incoming call

Calling this method on the PlivoIncoming object rejects the call.

(void)reject;

Usage

if (self.incCall != nil) {
    print("Incoming call - Reject");
    self.incCall?.reject()
    self.incCall = nil
}

PlivoEndpoint Delegates

Delegate 1: On Login

Delegate

(void)onLogin;

Description When registration to an endpoint is successful.

Parameters Error details

Return Value None

Delegate 2: Handling Login Failure

Delegate

(void)onLoginFailure;

Description This delegate gets called when registration to an endpoint fails.

Parameters None

Return Value None

Delegate 3: Handling Login Failure with Errors

Delegate

(void)onLoginFailedWithError:(NSError *)error;

Description This delegate gets called when registration to an endpoint fails.

Parameters Error details

Return Value None

Delegate 4: On Incoming Call

Delegate

(void)onIncomingCall:(PlivoIncoming*)incoming;

Description This delegate gets called when a call is incoming

Parameters Incoming object

Return Value None

Delegate 5: On Incoming Call

Delegate

(void)onIncomingCall:(PlivoIncoming*)incoming;

Description This delegate gets called when there is an incoming call to a registered endpoint

Parameters Incoming object

Return Value None

Delegate 6: On Incoming Call Rejected

Delegate

(void)onIncomingCallRejected:(PlivoIncoming*)incoming;

Description On an incoming call, if the call is disconnected by the caller, this delegate would be triggered with the PlivoIncoming object.

Parameters Incoming object

Return Value None

Delegate 7: On Incoming Call Hangup

Delegate

(void)onIncomingCallHangup:(PlivoIncoming*)incoming;

Description On an incoming call, if the call is disconnected by the caller after being answered, this delegate would be triggered with the PlivoIncoming object.

Parameters Incoming object

Return Value None

Delegate 8: On Incoming Digit

Delegate

(void)onIncomingDigit:(NSString*)digit;

Description On an active endpoint, this delegate would be called with the digit received on the call.

Parameters String for DTMF digit

Return Value None

Delegate 9: On Outgoing Call Answer

Delegate

(void)onOutgoingCallAnswered:(PlivoOutgoing*)call;

Description When an outgoing call is answered, this delegate would be called with the PlivoOutgoing object.

Parameters Outgoing object

Return Value None

Delegate 9: On Outgoing Call Ringing

Delegate

(void)onOutgoingCallRinging:(PlivoOutgoing*)call;

Description When an outgoing call is ringing, this delegate would be called with the PlivoOutgoing object.

Parameters Outgoing object

Return Value None

Delegate 10: On Outgoing Call Rejected

Delegate

(void)onOutgoingCallRejected:(PlivoOutgoing*)call;

Description When an outgoing call is rejected by the called number, this delegate would be called with the PlivoOutgoing object.

Parameters Outgoing object

Return Value None

Delegate 11: On Outgoing Call Rejected

Delegate

(void)onOutgoingCallHangup:(PlivoOutgoing*)call;

Description When an outgoing call is disconnected by the called number after the call has been answered.

Parameters Outgoing object

Return Value None

Delegate 12: On Outgoing Call Invalid

Delegate

(void)onOutgoingCallInvalid:(PlivoOutgoing*)call;

Description When an outgoing call is made to an invalid number, this delegate would be called with the PlivoOutgoing object.

Parameters Outgoing object

Return Value None

Receiving Incoming SIP Headers

You can receive custom SIP headers on an incoming call as a part of the PlivoIncoming object on the ‘onIncomingCall’ delegate. For example:

(void)onIncomingCall:(PlivoIncoming*)incoming
{
    if ([incoming.extraHeaders count] > 0) {
        NSLog(@"-- Incoming call extra headers --");
        for (NSString *key in incoming.extraHeaders) {
            NSString *value = [incoming.extraHeaders objectForKey:key];
            NSLog(@"%@ => %@", key, value);
        }
    }
    *// Answer the call here.*
}

Resetting your Endpoint

You must manually reset the endpoint object and create a new object for the following two cases:

  • Your application goes in and out of network connectivity.
  • Your application became active after coming up from the background.

An example for the same is provided below.

(void)applicationDidBecomeActive:(UIApplication *)application
{
    [PlivoEndpoint resetEndpoint];
    self.endpoint = [[PlivoEndpoint alloc] init];
}

Methods supporting Pushkit and Callkit in PlivoEndpoint

APIs for pushkit Integration

Method 1: Register Token

This method is used to register the device token for VOIP push notifications.

(void)registerToken:(NSData*)token;

Method 2: Relay Push Notification

pushInfo is the NSDictionary object forwarded by the apple push notification.

(void)relayVoipPushNotification:(NSDictionary *)pushInfo;

Usage

func pushRegistry(_ registry: PKPushRegistry, didReceiveIncomingPushWith payload: PKPushPayload, forType type: PKPushType)
{          
	Phone.sharedInstance.relayVoipPushNotification(payload.dictionaryPayload)
	payload.dictionaryPayload contains below info:
	{
	    alert = "plivo";
	    callid = "ABC-456-DEF-789-GHI";
	    sound = default;
	}
	Pass the payload.dictionaryPayload to relayVoipPushNotification API and then you will receive incoming calls the same way.
}

APIs for Callkit Integration

Following are the three apis that are required for Apple Callkit integration.

Method 1: Configure Audio Session

This method is used to Configure audio session before the call.

(void)configureAudioSession

Method 2: Start Audio Device

Depending on the call status (Hold or Active) you’ll want to start or stop processing the call’s audio. Use this method to signal the SDK to start audio I/O units when receiving the audio activation callback from CallKit.

(void)startAudioDevice

Method 3: Stop Audio Device

Depending on the call status(Hold or Active) you’ll want to start, or stop processing the call’s audio , use this method to signal the SDK to stop audio I/O units when receiving deactivation or reset callbacks from CallKit

(void)configureAudioSession

Usage

To Configure Audio

func configureAudioSession() {

    endpoint.configureAudioDevice()

}

Start the Audio service to handle audio interruptions use AVAudioSessionInterruptionTypeBegan and AVAudioSessionInterruptionTypeEnded.

func startAudioDevice() {
    endpoint.startAudioDevice()
}
func stopAudioDevice() {
    endpoint.stopAudioDevice()
}

To turn on the speakers

do {
	try audioSession.overrideOutputAudioPort(AVAudioSessionPortOverride.speaker)
} catch let error as NSError {
    print("audioSession error: \(error.localizedDescription)")
}

To turn off the speakers

set AVAudioSessionPortOverride:none