Cisco Webex API Essential Guide

What type of API does Cisco Webex provide?

REST API

1. The Webex APIs are RESTful. They use HTTP methods like GET, POST, PUT, and DELETE to perform actions on resources.

2. The API endpoints use base URLs like /messages and accept request parameters in either JSON or x-www-form-urlencoded formats.

3. The Webex REST API requires authentication using an Authorization HTTP header with an access token.

GraphQL API

1. The Search API for Webex Contact Center is a GraphQL-powered REST API that provides access to historical and real-time data.

2. This GraphQL API is used for reporting and analytics purposes in the Webex Contact Center.

Other API Types

1. There are also some REST APIs specifically for reporting in Webex Contact Center, such as Queue Statistics API, Agent Statistics API, and Agent Activities API.

2. There is mention of a SOAP API for Webex Meetings Network-Based Recording (NBR) Web Services. However, this appears to be a legacy or specific-use API rather than the primary API for Webex.

Summary

The primary API type for Cisco Webex is REST. While there are some specific use cases that employ GraphQL (for Webex Contact Center reporting) and SOAP (for Webex Meetings NBR), the main Webex platform APIs are RESTful.

Does the Cisco Webex API have webhooks?

Yes, the official Cisco Webex API does support webhooks. Here are the key points about Webex webhooks:

Webhook Support

1. Webex provides a Webhooks API that allows you to subscribe to events in Webex and receive notifications when those events occur.

2. Webhooks allow your application to receive real-time data from Webex, keeping you updated on the state of your resources (e.g., rooms, messages, memberships).

Event Types

You can subscribe to various types of events in Webex, including:

1. Messages: Created, updated, or deleted.
2. Rooms: Created, updated, or deleted.
3. Memberships: Created, updated, or deleted.
4. Meetings: Started, ended (not available for Webex for Government).
5. Meeting Participants: Joined, left (not available for Webex for Government).

Filtering Webhooks

1. You can add filters to your webhooks to narrow down the data you receive.
2. Filters can be combined using the "&" symbol.
3. Examples of filters include:
   • roomId: To receive notifications for a specific room
   • personEmail: To receive notifications for actions by a specific person
   • roomType: To filter by room type

Creating Webhooks

To create a webhook, you need to provide:

1. A name for the webhook
2. A targetUrl where you'll receive the notifications
3. The resource you want to monitor (e.g., messages, rooms)
4. The event type (e.g., created, updated, deleted)
5. Optional filters to narrow down the notifications

Best Practices

1. Ensure your targetUrl is publicly accessible and can respond with a successful HTTP status code (2xx).
2. Be aware of webhook limits: 30,000 webhooks per user for personal webhooks, and 1 org-wide webhook with the ability to register additional webhooks for different resources and filters.
3. Handle disabled webhooks by monitoring their status and reactivating them if necessary.

Security

You can add a secret when creating a webhook, which Webex will use to generate an HMAC-SHA1 signature for each payload, allowing you to verify that the webhook came from Cisco.

In summary, the Cisco Webex API offers robust webhook support, allowing you to subscribe to a wide range of events and receive real-time notifications about changes in your Webex resources.

Rate Limits and other limitations

Here are the key points about the API rate limits for the Cisco Webex API:

General Rate Limiting Information

• The Webex API implements rate limiting to maintain appropriate service levels for all users [1].

• Rate limiting policies are fine-grained and often overlap, making them complex to document exactly [1].

• Most REST APIs enforce a rate limit of around 300 requests per minute, with higher dynamic quotas for the /people and /messages APIs [1].

Handling Rate Limit Errors

• When an API rate limit is hit, the API returns a 429 Too Many Requests response [1].

• The 429 response includes a Retry-After header indicating how long to wait before retrying the request [1].

• Applications should implement logic to handle 429 errors and respect the Retry-After header [1].

Specific API Limits

• The Create a Meeting API has a limit of 3,000 calls per 24 hours [2].

• There is a general limit of 2,400 requests per minute per account across the whole API [2].

Recommendations for Large Workloads

• Don't use end-user accounts for large workloads - use dedicated admin or bot accounts instead [1].

• Bot accounts have less restrictive rate limits than end-user accounts [1].

• Partition concurrent API workloads across separate users, as rate limits are shared per user [1].

Additional Notes

• Rate limits may vary depending on the specific API call and resource intensity [3].

• The rate limiting system uses a rolling count strategy rather than resetting after a fixed time period [2].

• Webex is collecting usage data to establish baselines and may adjust rate limits in the future [4].

In summary, while there are some specific documented limits, the overall rate limiting system is complex and dynamic. Applications should be designed to gracefully handle 429 errors and implement appropriate retry logic.

Latest API Version

Based on the search results provided, I couldn't find a specific mention of the most recent version of the Cisco Webex API. However, I can provide some relevant information about the Webex API:

Current API Versions

1. The Webex REST API is the modern API for Webex services [^2].

2. For Webex Meetings, there are XML API versions mentioned, with the latest versions being:

   • XML API 41 (and later) [^4]
   • XML API 11.0 for Webex Business Suite 32 [^3]

Key Points

• The Webex REST API provides direct access to the Cisco Webex Platform, allowing developers to create spaces, search for people, post messages, and more [^2].

• Authentication for the Webex REST API requires a Webex account backed by Cisco Webex Common Identity (CI) [^2].

• For Webex Meetings, there are different XML API versions for different Webex Business Suites [^3].

• Cisco has been decommissioning older XML API versions. For example, XML API 10.0.0 for T31 sites was planned to be decommissioned in the 41.9.0 update [^4].

Best Practices

1. Use the most recent API version available for your specific Webex service (REST API for general Webex services, latest XML API for Webex Meetings).

2. Keep track of API updates and deprecations through Cisco's developer documentation and release notes.

3. Ensure your authentication methods are up-to-date, especially if transitioning from classic Webex sites to Control Hub managed sites [^4].

4. When using XML APIs, make sure to use the correct URL format: https://{siteName}.webex.com/WBXService/XMLService [^4].

While I couldn't provide the exact most recent version number, this information should help you understand the current state of Webex APIs and guide you towards using the most appropriate and up-to-date version for your needs.

[^2]: Getting Started with the Webex REST API [^3]: Webex Meetings Release Notes [^4]: Cisco Webex Meetings API Updates Overview (API 41)

How to get a Cisco Webex developer account and API Keys?

To get a developer account for Cisco Webex and create an API integration, follow these steps:

1. Create a Webex Account

If you don't already have one, sign up for a free Webex account at developer.webex.com.

2. Log in to the Webex Developer Portal

Go to developer.webex.com and log in with your Webex credentials.

3. Create a New Integration

1. Click on your avatar in the top right corner and select "My Webex Apps".
2. Click the "Create new App" button.
3. Select "Create an Integration" from the app type options.

4. Configure Your Integration

Provide the following information:

• Name for your integration
• Icon (select or upload)
• Description of your app
• Redirect URI (where users will be redirected after granting permission)
• OAuth scopes (define the level of access your integration needs)

5. Complete the Registration

Click the "Add Integration" button at the bottom of the page.

6. Obtain Integration Credentials

After successful registration, you'll receive:

• Client ID
• Client Secret (copy and store securely, as it's only shown once)
• OAuth Authorization URL

What can you do with the Cisco Webex API?

Based on the search results provided, here is a list of data models you can interact with using the Cisco Webex API, along with what is possible for each:

Messaging and Collaboration

• Spaces
  • Create a Webex space and invite people
  • Post messages in a Webex space
  • Get Webex space history
  • Be notified in real-time when new messages are posted
• Messages
  • Send messages containing text, attachments, or both
  • Retrieve messages from spaces
• People
  • Search for people in your company
• Teams
  • Create and manage teams

Devices and Room Systems

• Devices
  • Execute commands on Webex RoomOS devices

Contact Center

• Entry Points
  • Configure entry points for incoming contacts
• Queues
  • Manage queues for routing contacts
• Teams
  • Configure teams of agents
• Users
  • Manage user accounts for agents and supervisors
• User Profiles
  • Set up profiles for different user types
• Agent Profiles
  • Configure specific profiles for agents
• Address Books
  • Manage contact lists
• Idle Codes
  • Set up codes for agent idle states

Reporting and Analytics

• Queue Statistics
  • Retrieve statistics on queue performance
• Agent Statistics
  • Get data on agent performance
• Agent Activities
  • Track agent activities
• Call Recordings
  • Access and manage call recordings
• Search API (GraphQL)
  • Query historical and real-time data across multiple fields

Webhooks

• Real-time webhooks
• Tasks webhooks
• Agent webhooks

Meetings

• Recordings
  • Access and manage meeting recordings
  • Retrieve metadata (chat, Q&A, polling, participant information)
• Meeting Management
  • Schedule and manage meetings

Authentication and Authorization

• OAuth 2.0 authentication
• Personal access tokens
• Bot tokens
• Integration tokens
• Guest issuer tokens

This list covers the main data models and capabilities exposed by the Cisco Webex API. Each of these areas allows for various operations such as creating, reading, updating, and deleting (CRUD) data, as well as more specialized actions specific to each domain.