-
Notifications
You must be signed in to change notification settings - Fork 352
Incoming and Outgoing Calls
- Introduction
- Call Object
- Inbound Calls
- Outbound Calls
- Call Disconnect
- Error Handling
- Call related public APIs
CallingClient module in Calling SDK provides inbound and outbound call functionality on registered lines. For every call, a call instance is created and then used to dial the call, listen for events. This document covers how we obtain the call instance and use it in inbound/outbound calls.
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.
| 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 |
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 | | resume_error | An error has occurred while placing call on resume | | transfer_error | An error has occurred while transferring the call |
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 Events
call.on("remote_media", (track: MediaStreamTrack) => {
// store remote audio received and use it to open media channel 2-way
});
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
});
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:
-
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 });
-
Caller triggers end() API available to initiate disconnect the call.
call.end();
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
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]"
},
}
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)
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]"
},
},
],
}
Caution
- Introducing the Webex Web Calling SDK
- Core Concepts
- Quickstart guide
- Authorization
- Basic Features
- Advanced Features
- Introduction
- Quickstart Guide
- Basic Features
- Advanced Features
- Multistream
- Migrating SDK version 1 or 2 to version 3