Incoming and Outgoing Calls

• Introduction
• Call Object
  • Call Methods
  • Call Events
• Inbound Calls
• Outbound Calls
• Call Disconnect
• Error Handling
• Call related public APIs
  • getCall()
  • getConnectedCall()
  • getActiveCalls()

Introduction

CallingClient module in Calling SDK provides inbound and outbound call functionality on registered lines. A call instance is created for every call and then used to dial the call and listen for events. This document covers how we obtain the call instance and use it in inbound/outbound calls.

Call Object

Once the lines are registered, call functionality is available on any of the lines. Use the makeCall method is invoked on a line. For inbound call, when the client receives a call from Webex Calling, a call instance is returned within the payload of an event from the Calling SDK.

The call instance provided by the Calling SDK is of type ICall. A call instance provides a variety of methods to the developer that take specific actions and move the call through various states.

Call Methods

Method	Description	Returns	Visibility
answer	Accepts or answers an incoming call from Webex Calling	void	Public
dial	Dials the outgoing call to the destination	void	Public
end	Ends an ongoing call	void	Public
sendDigit	Sends a DTMF digit on an established call	void	Public
mute	Mutes the local track of this call instance	void	Public
doHoldResume	Places the remote end of this call on hold/resume the call based on the current state of the call	void	Public
completeTransfer	Initiates a transfer towards a target (Phase 2)	void	Public

Call Events

Event	Description	Payload
incoming_call	Incoming call is received	Call Object (ICall)
caller_id	Remote end calling information determined	CallId
progress	Remote end is ringing or has provided a cut-through
connect	The remote end has answered the call
established	Two-way media has now been established
remote_media	Remote media track received. Use this to play out remote media on client
disconnect	Remote end has disconnected the call
held	Remote end has been put on hold successfully
resumed	Remote end has been put on hold successfully
call_error	An error has occurred in the call	Error object (CallError)
hold_error	An error has occurred while placing call on hold	Error object (CallError)
resume_error	An error has occurred while placing call on resume	Error object (CallError)
transfer_error	An error has occurred while transferring the call	Error object (CallError)

Inbound Calls

In order to receive incoming calls, listen for incoming call event on the line. 

line.on("incoming_call", (call: ICall) => {
    //  Call object received. Store this object and listen for events on the call
});

Once the call is received at the application, we can use answer API available in Calling SDK to answer the call. API requires localAudioTrack to be passed. 

call.answer({localAudioTrack});

Once the call is answered from the application side, listen for additional events received on call instance like remote media, call disconnect, caller ID update etc. More details on the events can be found in the Call Events section.

call.on("remote_media", (track: MediaStreamTrack) => {
    // store remote audio received and use it to open media channel 2-way
});

Outbound Calls

Create the call instance first for outbound calls using makeCall on the line object.

call = line.makeCall();

Trigger the dial() API available in SDK using that call instance to initiate the call. this API requires localAudioTrack to be passed.

call.dial({localAudioTrack});

Post that listen for events on call object to track the further progress of the call and establish 2-way audio.

call.on("progress", (correlationId: string) => {
    // Process call progress, this event indicates that call is ringing on called party side
});

call.on("connect", (correlationId: string) => {
    // Process connect event, this is received when call has been answered from the called party side
});

call.on("remote_media", (track: MediaStreamTrack) => {
    // Add code to store remote audio received and use it to open media channel 2-way
});

Call Disconnect

We can disconnect the call using the end API or we can listen for disconnect event coming from the other side.

Refer to the below examples:

1. Listen for disconnect event being received from SDK if called party disconnects the call. 

   call.on("disconnect", (correlationId: string) => {
   	// Add action to clear out the call on the application
   });

2. Caller triggers end() API available to initiate disconnect the call.

   call.end();

Error Handling

Calls will occasionally experience errors. An error event is emitted by the call object when it is encountered. Listen for below callError event to handle such scenarios.

call.on("call_error", (callError: CallError) => {
    // Handle the error received for the ongoing call
});

CallError object contains the following members:

• message - Description of error in the callingClient
• type - Type of error in the callingClient. This error can be either call control error or media error.
• correlationId - Correlation ID of the call that faced the issue

Call related public APIs

getCall()

This API helps in fetching a single call object that's active on a line. This API is provided on the line object.

Asynchronous	No
Parameters	CorrelationId of the call.
Returns	Call Object(ICall)

call = line.getCall(correlationId)

CallObject(ICall)

{
    "callId": <string>,
    "callerInfo": {}
    "connected": boolean,
    "correlationId": <string>,
    "destination": {
        "type": 'uri',
        "address": 'tel:5954'
    },
    "deviceId": <string>,
    "direction": "outbound" | "inbound",
    "earlyMedia": boolean,
    "held": boolean,
    "mobiusUrl": "https://mobius.aintm-m-5.int.infra.webex.com/api/v1/calling/web/",
    "muted": boolean,
    "origin": {
        "type": "uri",
        "address": "sip:[email protected]"
    },
}

getConnectedCall()

At a time only one call can be in the connected state even if there are multiple calls active among multiple lines. The remaining calls will be on Hold at this time. This API returns the call object which is in the Connected state. This API is provided on the CallingClient object as the information that which line has call in connected state is unknown. 

Asynchronous	No
Parameters	No parameters required
Returns	Call Object(ICall)

call = callingClient.getConnectedCall(correlationId)

getActiveCalls()

A line has the ability to support multiple calls at the same time. In order to fetch all the calls that are active in Calling SDK across all lines, this API can be used. It returns key-value pair where key is the lineId(deviceId) and it's value is array of call objects on that line. This API is provided on the CallingClient object.

Asynchronous	No
Parameters	No parameters required
Returns	LineToCallMap object

calls = callingClient.getActiveCalls()

Example for key-value pair which is returned by the above mentioned API:

LineToCallMap

{
    "ca3a511e-81b4-3155-ab47-ff7bd8c0c189": [
        {
            callId: "ce8badee-04cc-463f-a5cf-738b51157165",
            callerInfo: {}
            connected: true,
            correlationId: "0fa25099-01f0-44bc-b988-230c6ba2d25f",
            destination: {
                type: 'uri',
                address: 'tel:5954'
            },
            deviceId: "ca3a511e-81b4-3155-ab47-ff7bd8c0c189",
            direction: "outbound",
            earlyMedia: false,
            held: true,
            mobiusUrl: "https://mobius.aintm-m-5.int.infra.webex.com/api/v1/calling/web/",
            muted: false,
            origin: {
                type: "uri",
                address: "sip:[email protected]"
            }, 
        },
        {
            callId: "ce8badee-04cc-463f-a5cf-738b51157165",
            callerInfo: {}
            connected: false,
            correlationId: "0fa25099-01f0-44bc-b988-230c6ba2d25f",
            destination: {
                type: 'uri',
                address: 'tel:5954'
            },
            deviceId: "ca3a511e-81b4-3155-ab47-ff7bd8c0c189",
            direction: "inbound",
            earlyMedia: false,
            held: false,
            mobiusUrl: "https://mobius.aintm-m-5.int.infra.webex.com/api/v1/calling/web/",
            muted: false,
            origin: {
                type: "uri",
                address: "sip:[email protected]"
            }, 
        },
    ],
    "a1cff23f-b3b6-323c-b213-5e12371cfbd6": [
        {
            callId: "b951015c-4a93-428e-9c33-91d894807877",
            callerInfo: {}
            connected: true,
            correlationId: "e16dac14-64dc-4317-8be5-8bc807da44eb",
            destination: {
                type: 'uri',
                address: 'tel:5009'
            },
            deviceId: "a1cff23f-b3b6-323c-b213-5e12371cfbd6",
            direction: "outbound",
            earlyMedia: false,
            held: false,
            mobiusUrl: "https://mobius.aintm-m-5.int.infra.webex.com/api/v1/calling/web/",
            muted: false,
            origin: {
                type: "uri",
                address: "sip:[email protected]"
            }, 
        },
    ],
}