APIs
Getting StartedREST API BasicsComplianceWebhooksWebex APIs
Admin
Calling
Devices
imiconnect
Meetings
Messaging
Webex Assistant Skills
Full API Reference
API Changelog

Calling Overview

With Webex Calling features, connecting with people is easier than ever.

anchorOverview
anchor

Webex Calling provides advanced telephony services for its users. The Webex Calling APIs provide an interface for third-party provisioning, which can be used to provision Webex Calling users. Call Controls provides information about active and past calls and can be used to perform call actions.

For more information about Webex Calling, see Webex Calling organization settings.

For more information about creating, updating, and removing a Webex calling user’s settings, see Create, update, and remove a Webex calling user’s settings.

What's possible with Webex Calling Provisioning APIs?

Retrieve a Webex Calling license Retrieve Locations Create a Webex Calling user & assign phone number, extension, location Delete a Webex Calling user Assign Webex Calling license to existing Webex user & specify phone number, extension, location Update phone number, extension for existing Webex Calling user Retrieve Webex Calling user with phone number, extension and location Query Webex Calling users by Location

What's possible with Webex Calling Call Controls?

Place a call (dial)Answer a call (answer)Reject an incoming call (reject)Hangup a call (hangup)Divert an incoming call (divert)Hold a call (hold)Resume a held call (resume)Transfer an active call (transfer)Park an active call (park)Retrieve a parked call (retrieve)Start Recording on a call (Start recording)Stop Recording on a call (Stop recording)Pause Recording on a call (Pause recording)Resume Recording on a call (Resume recording)List active callsGet the details for a specific active callGet the Call History

What's possible with Webex Calling Call Events?

Webex Calling uses webhooks to allow applications to receive real-time data concerning call status changes. The callIds and information in the Webhook notifications can be used in conjunction with the Webex Calling Call Controls API to build feature rich calling applications. For more information about Webhooks usage, see the Webex for Developers Webhooks Guide.

Postman Collection

In addition to the Call Controls API Reference, we've also put together a Webex Calling Postman collection which demonstrates the use of the Webex Calling API.

anchorProvisioning
anchor
Usage Notes

When creating, updating, or retrieving Webex Calling users:

The callingData query parameter must be set to "true" to retrieve Webex Calling details for the user when using the People API

When creating users:

To create a Webex Calling user, include the phoneNumber or extension, a Webex Calling license, and (optionally) the user's locationIdIf a locationId is not specified when creating a user with a phoneNumber or extension, or both, then the organization's default location will be usedIf the phone number is invalid, neither the phone number nor the extension will be created and associated with the person

When updating users:

You can only add a locationId when applying a new Calling license to an existing userIf you do not specify a locationId when adding a new Calling license to an existing user, the default will be usedYou cannot update the locationId for an existing Webex Calling user

Working with Phone Numbers:

Webex Calling APIs only support the primary phone number and not alternate phone numbersFor US Phone Numbers use the format without country code ([area code][number]), e.g. 5715551212. The following are not supported: e.g. +15715551212, 15715551212, 571-555-1212.Non-US numbers must use E.164 format ([country code][area code][number]), e.g. +335715551212

Authorization Scopes

Authorization scopes are required to provision users and work with Locations. For instructions on how to add these scopes to your app and for a full list of all available authorization scopes see the Integrations & Authorization Guide.

Scope
Usage
spark-admin:licenses_read
Access to read licenses available in your user's organizations
spark-admin:organizations_read
Access to read your user's organizations
spark-admin:people_read
Access to read your user's company directory
spark-admin:people_write
Access to write to your user's company directory
anchorCall Controls
anchor

Webex Calling users can perform the telephony actions listed above directly in the Webex Teams clients. The Call Controls API provides the ability to create clients and applications which implement the same functionality.

Authorization Scopes

Authorization scopes are required to read call information and perform call actions. For instructions on how to add these scopes to your app and for a full list of all available authorization scopes see the Integrations & Authorization Guide.

Scope
Usage
spark:calls_read
List all calls for rooms you are a part of
spark:calls_write
Allow users to invoke call commands on themselves
License Update

To ensure that the /licenses API is able to properly return consumedUnits for Webex Calling licenses the spark-admin:people_write scope is required in addition to the spark-admin:licenses_read scope.

With spark-admin:licenses_read and spark-admin:people_write scope shows(consumedUnits is properly returned):

{
  "id": "Y2lzY29zcGFyazovL3VzL0xJQ0VOU0UvMzMzYTMzYjEtNWNjYy00NTc1LTgyN2QtZmUyYjcyM2VhNDFmOkJDU1REXzE1OGE5ODFmLTFjNWQtNGY2Zi1hYjQxLTljYmYwZDZlOGNhZQ",
  "name": "Webex Calling - Standard Enterprise",
  "totalUnits": 100,
  "consumedUnits": 10,
  "subscriptionId": "trialSub.a4f96c28-3437-487f-825e-e6d209312b07"
}

With only the spark-admin:licenses_read scope shows(consumedUnits is always zero):

{
  "id": "Y2lzY29zcGFyazovL3VzL0xJQ0VOU0UvMzMzYTMzYjEtNWNjYy00NTc1LTgyN2QtZmUyYjcyM2VhNDFmOkJDU1REXzE1OGE5ODFmLTFjNWQtNGY2Zi1hYjQxLTljYmYwZDZlOGNhZQ",
  "name": "Webex Calling - Standard Enterprise",
  "totalUnits": 100,
  "consumedUnits": 0,
  "subscriptionId": "trialSub.a4f96c28-3437-487f-825e-e6d209312b07"
}