Webex Calling: Getting Started with Call Control APIs
September 13, 2023The Webex Calling platform has a comprehensive set of APIs and webhook events that developers can leverage to build powerful integrations. For some great examples of 3rd party Webex Calling integrations, be sure to check out the current listings on Webex App Hub.
On the administrator level, there are the Provisioning APIs that power Webex integrations before calls are made, for managing users, devices, locations, and telephony settings. Administrators can also utilize the analytics and report APIs to retrieve call data and generate call detail reports after calls are made.
Sitting next to those administrator endpoints are the user level Call Control APIs that perform calling actions and provide information during calls. Besides the APIs, Webex provides a comprehensive set of webhooks that send actionable, real-time event data for user call-status changes. Together, the Call Control APIs and webhook events can power a variety of use cases for custom calling clients, dynamic call routing, and populating agent dashboards & widgets. Do note that the Voice Messaging APIs for voicemail functionality are also included in the user level Calling endpoints, however, the focus of this article will be the Call Control APIs.
Get Familiar with the Call Control APIs
The Call Control API endpoints essentially fall within three categories – call connection, mid-call actions, and call details/history. Let’s take a closer look at the endpoints in each of these categories.
Call Connection APIs
This group of APIs pertain to actions that happen before an outbound call is initiated or an inbound phone is answered:
- Dial – Initiates an outbound call to a specified number or address for click-to-call functionality. Webex responds with a unique
callId
, which needs to be included for every command pertaining to that call and acallSessionId
, which is used to associate multiple calls that are part of a common session. - Answer – Simply answers an incoming call on the user’s primary device using
callId
of the inbound call. Webex responds with a204/No Content
on success. - Pickup – This command pertains to users assigned to a pickup group, to answer any ringing line within their pickup group. Webex responds with a
callId
and acallSessionId
. - Reject – Declines an inbound call for a specified
action
choice:busy (default)
,temporarilyUnavailable
, orignore
. Webex responds with a204/No Content
on success. - Divert – This command has optional parameters to transfer a call to another
destination
or directlytoVoicemail
as it is answered. Webex responds with a204/No Content
on success.
Mid-Call Actions APIs
This group of APIs are for actions during active (connected) calls:
- Hold & Resume – These commands work together, to put a call on and off hold using the
callId
. Webex responds with a204/No Content
on success. - Transfer – Command to have up to two active calls (
callId1
andcallId2)
be transferred to a single destination. Can be used for a variety of transfer types including attended transfers, consultative transfers, supervised transfers, and mute transfers. - Park & Retrieve – The
park
command puts a call on hold with a specified destination or automatically within their call park group. Webex responds to this API request with data about theparkedAgainst
party that will pick up the call. The call is picked-up at the new destination using theretrieve
command and Webex responds with acallId
and acallSessionId
. - Start & Stop Recording – This recording feature must first be enabled for the user by an administrator. These commands work together, to start and stop a call recording using the
callId
. Webex responds with a204/No Content
on success. - Pause & Resume Recording – These commands work together, to temporarily pause call recording and resume a paused call recording using the
callId
. Webex responds with a204/No Content
on success. - Transmit DTMF – Send DTMF signals to a call using the
callId
. Signals are limited to this set of digits:[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, *, #, A, B, C, D]
and a pause can be added between digits by using a comma (~ 1 sec for each pause). - Push – This command is only for users with executive assistant services enabled, to hand off active calls from a designated assistant to the executive user.
- Barge In – The barge-in feature, which must first be enabled by an administrator, allows users to join another users’ active call. This command starts a new call to perform the barge-in, terminating at the destination that is specified in the
target
parameter. Webex responds with a201/Created
on success. - Hangup – Command for a user to disconnect a call using the
callId
. Webex responds with a204/No Content
on success.
Call Details/History APIs
This group of read-only APIs returns call lists and details, which can be used to create agent dashboards, widgets, and other call logging components:
- List Calls – This endpoint responds with a listing of active calls for the user.
- Get Call Details – This endpoint returns detailed data of an active call for the user using the
callId
. - List Call History – This endpoint returns a list of call history for user for the 20 most recent records. The results can optionally be filtered by call types:
placed
,missed
, andreceived
. This is the lone non-administrator endpoint that provides information about past calls.
Get Familiar with the Call Control Webhooks
Webex also has a variety of webhooks for Calling users. Webhook events that use the telephony_calls
resource will provide notifications about call status changes. For example, to be notified when an inbound call is received, you would utilize the telephony_calls/created
event. The notification from Webex is sent in JSON payload with basic data about the call that can be used by an integration to create follow-up actions. In this scenario, the payload from Webex may look something like this:
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"created": "2023-08-23T12:34:56Z",
"event": "created",
"resource": "telephony_calls",
"data": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"direction": "inbound",
"from": {
"name": "Pat Garner",
"number": "+14075554444"
},
"to": {
"name": "Harrison Greeley",
"number": "+17165552222"
},
"start_time": "2023-08-23T12:34:56Z",
"duration": 0,
"status": "ringing"
}
}
Additionally, by utilizing webhook filtering options you can further customize integrations to receive notifications that are only relevant to the use case. Calling webhook filters can limit notifications to a particular call personality, call state, person, or call type.
Get a Webex Dev Sandbox Enabled for Webex Calling
Now that we’re more familiar with all the commands available in the Call Control APIs, the next step is to get a Webex Developer Sandbox, configure it for Webex Calling, and create test users. It’s important to note that you will first need to obtain phone numbers from a PSTN provider to make test calls on the Dev Sandbox. The help article linked above (for configuring Webex Calling) has more information on how to add PSTN numbers to the Webex Sandbox.
Get the Postman Collection
With the sandbox configured for Calling and the test users all set, you can start testing right away using Postman and the Postman collection for Webex Calling, which demonstrates the following functional scenarios:
- Create an outbound (Click to Dial) call, confirm it can be received, then carry out a basic
hold
andresume
operation. - Answer an inbound call (UserA calls apiUser), initiate another call from the same user (apiUser calls UserB) and perform a ‘Consult Transfer’ (apiUser transfers the call to connect UserA with UserB)
- Answer an inbound call (UserA calls apiUser) and
Divert
(blind transfer) the call to apiUser's voicemail. - Answer an inbound call,
park
the call on another destination andretrieve
the call back to apiUser. - Answer an inbound call,
start recording
,pause recording
,resume recording,``stop recording
, then end the call.The apiUser must be enabled for ‘Call Recording’ in Control Hub and with the ‘On Demand’ Call Recording option selected. Also, to get the the apiUser information, you must be provisioned by a Call Recording provider, such as Dubber.
- Retrieve Call History of the apiUser (missed calls, placed calls and received calls).
- Basic example usage of the voice message APIs.
Start Testing
An access token is needed to make API calls on behalf of the test user. The easiest way to get the access token is to login to developer.webex.com with the test user’s credentials, then copy the personal access token from the Getting Started guide. In Postman, this value is used as the Bearer
token in the Authorization
header for making Webex API requests. Keep in mind that when you’re creating an actual calling application, you’ll need to get your access token via an OAuth integration and set the proper scopes to access the APIs.
Next, log in to the Webex app or Webex Calling Chrome Extension using the same test user credentials from above. The test user is now a “live agent” ready to make and receive calls at the number you assigned to in the sandbox’s Control Hub. Any phone capable of making and receiving PSTN calls (like your cell phone) can be the other party for test calls.
With a test user logged in and a phone ready for testing, API calls can now be made in Postman (or another client) to initiate a call or answer incoming calls for the test user. Additional phones and/or devices will be needed to test functions that require additional call legs, such as transfers.
Additional Resources
If you ever find yourself facing challenges or need assistance while working with the Calling APIs, don't hesitate to reach out to our awesome Developer Support team. Remember, we're here to help you every step of the way, whether you're troubleshooting issues, seeking guidance on APIs and integrations, or simply need some clarification on a topic.
Additionally, be sure to check out the growing Webex Calling APIs Vidcast collection where you will find a variety of helpful videos for developers to quickly get familiarized with the Webex Calling platform.