Incoming and Outgoing Calls

• Introduction
• Call Object
  • Call Methods
  • Call Events
• Inbound Calls
• Outbound Calls
• Call Disconnect
• Error Handling
• Updating media
• 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

After the lines have been registered, you can utilize call functionality on any of these registered lines. To initiate a call, you can use the makeCall method when invoked on a specific line. When an inbound call is received by the client from Webex Calling, the Calling SDK dispatches an event, and within the event payload, a call instance is returned.

This call instance, provided by the Calling SDK, is of type ICall. It equips developers with a range of methods that enable them to perform specific actions and manage the call as it progresses 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 stream 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	void	Public
updateMedia	Updates the microphone stream used during the call	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	CorrelationId(string)
connect	The remote end has answered the call	CorrelationId(string)
established	Two-way media has now been established	CorrelationId(string)
remote_media	Remote media track received. Use this to play out remote media on client	Track object(MediaStreamTrack)
disconnect	Remote end has disconnected the call	CorrelationId(string)
held	Remote end has been put on hold successfully	CorrelationId(string)
resumed	Remote end has been put on hold successfully	CorrelationId(string)
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 the answer API available in Calling SDK to answer the call. API requires localAudioStream to be passed. 

call.answer({localAudioStream});

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 localAudioStream to be passed.

call.dial({localAudioStream});

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. Developer 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 call.
• type - Type of error in the call. This error can be either call control error or media error.
• correlationId - Correlation ID of the call that faced the issue.

Updating Media

While a call is in progress, it is possible to update media to allow a developer to switch from one device to another. In order to do this, the call object provides a function.

First, create a microphone stream using the new device ID.

  const constraints = {
    audio: true,
    deviceId: "DEVICE_ID"
  };

  const newStream  = await Calling.createMicrophoneStream(constraints);

Then, use this new stream to update the media in the call object.

  call.updateMedia(newStream);

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]"
         }, 
    },],
}