Webex Calling: Getting Started with Call Control APIs

The 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 3^rd 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 a callSessionId, 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 a 204/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 a callSessionId.
• Reject – Declines an inbound call for a specified action choice: busy (default), temporarilyUnavailable, or ignore. Webex responds with a 204/No Content on success.
• Divert – This command has optional parameters to transfer a call to another destination or directly toVoicemail as it is answered. Webex responds with a 204/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 a 204/No Content on success.
• Transfer – Command to have up to two active calls (callId1 and callId2) 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 the parkedAgainst party that will pick up the call. The call is picked-up at the new destination using the retrieve command and Webex responds with a callId and a callSessionId.
• 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 a 204/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 a 204/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 a 201/Created on success.
• Hangup – Command for a user to disconnect a call using the callId. Webex responds with a 204/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, and received. 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 and resume 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 and retrieve 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.