Calling Supplementary Services

Introduction

This document helps in understanding the supplementary services like hold, resume, blind transfer and consult transfer which are available in the Calling SDK.

Once an inbound/outbound call is in an established state, we have the above-mentioned supplementary services available. To trigger these services we need the call instance, which is created when a call is initialized. Refer to the [Incoming-and-Outgoing-Calls](https://github.com/webex/webex-js-sdk/wiki/Incoming-and-Outgoing-Calls) to understand more about how call instance is created.

The call instance provides us with the doHoldResume and completeTransfer methods. 

Public APIs

doHoldResume

The API puts the call on hold or resumes based on the current state of the call. If the call is connected the call will be put on hold. If the call is already held doHoldResume will resume the call.

Parameters	--
Returns	void

// Assuming the call(inbound/outbound) is already established and we have the call instance.

call.doHoldResume() // call is put on hold

call.doHoldResume() // call is resumed

Post this listen for events on the call object to track the further progress of the call.

If hold action is successful Calling SDK emits a 'held' event. We can listen to this event on the call object.

call.on("held",  (callId: CallId) => {
    // Add code to handle successful hold
}); 

If hold action is not successful Calling SDK emits a 'hold_error' event. We can listen to this event on the call object.

call.on("hold_error", (error: CallError) => {
    // Add code to handle hold error
});

If resume action is successful Calling SDK emits a 'resumed' event. We can listen to this event on the call object.

call.on("resumed",  (callId: CallId) => {
    // Add code to handle successful resume
});

if resume action is not successful Calling SDK emits a 'resume_error' event. We can listen to this event on the call object.

call.on("resume_error", (error: CallError) => {
    // Add code to handle resume error
}); 

completeTransfer

The API is used to initiate call transfers. Calling SDK supports two types of transfers: blind transfer and consult transfer. The API accepts 3 arguments transferType, transferCallID, transferTarget.

Parameters	Name Description Values Required  transferType  Type of transfer. transferType controls which type of transfer is triggeref   enum TransferType BLIND CONSULT Yes transferCallId Call Id where the current call will be merged for consult transfers. CallId<string> No transferTarget Destination for blind transfer. string No
Returns	void

Blind Transfer

Blind transfer involves transferring a call to a destination without first consulting with the new user, to whom we are transferring the call to. To initiate a blind transfer we need to set the transferType to 'BLIND' and provide the transferTarget. For blind transfer transferTarget is a mandatory argument, if not provided transfer will fail. transferCallId is not required for blind transfer.

const call = line.makeCall()
const destination = '123456789'
call.completeTransfer(TransferType.BLIND, undefined, destination); // Note: transferCallId is used for consult transfer, should be undefined for blind transfer

Consult Transfer

Consult transfer involves consulting with the new user before transferring the call to them. To initiate a consult transfer we need to set the transferType to 'CONSULT' and provide the transferCallId. For consult transfer transferCallId is a mandatory argument, if not provided transfer will fail. transferTarget is not required for consult transfer.

A typical consult transfer flow is given below.

1. UserA calls UserB. At this point, any of the users can transfer the call.
2. Let's assume UserB wants to transfer the call. UserB will first have to put UserA on hold.
3. Now UserB will be able to dial out to UserC.
4. Once UserC answers, UserB and UserC will be in a connected call while UserA is on hold.
5. UserB can initiate the consult transfer using completeTransfer API.
6. CallId between UserA and UserB is the transferCallId here hence pass this in the API.
7. If the transfer is successful, UserA and UserC will be on a call and UserB will get disconnected from both the calls.

//callAB -> call between UserA and UserB
//callBC -> call between UserB and UserC

//UserA calls UserB
const callAB = line.makeCall() 

//UserB puts UserA on hold
callAB.doHoldResume() 

//UserB calls UserC
const callBC = line.makeCall() 

//UserB completes the transfer
callAB.completeTransfer(TransferType.CONSULT, CallBC.getCallId())

If transfer is not successful Calling SDK emits a 'transfer_error' event. We can listen to this event on the call object.

call.on("transfer_error", (error: CallError) => {
    // Add code to handle transfer error
}); 

CallError object contains the following members:

• message: ErrorMessage - Description of error in the callingClient
• context: ErrorContext
• type: ERROR_TYPE Type of error in the callingClient.
• correlationId: string - Correlation ID of the call that faced the issue
• errorLayer: ERROR_LAYER - Layer at which error occurred 'media' or 'call_control'

sendDigit

This API is used to send a DTMF digit on an established call, one example where this is required is when interacting with an IVR navigation. Users may send DTMF digits corresponding to menu options.

API accepts a string representing the DTMF digit to be sent during the active call as a parameter.

Parameters	string
Returns	void