anchorWebex Meetings

Webex Meetings offers integrated audio, video, and content sharing with highly secure web meetings from the cloud. The Webex Meetings REST API allows developers to add basic Webex scheduling functionality to their custom applications or websites. You can:

• Create and manage meetings
• Add and manage meeting invitees
• Get and update meeting preferences, options, and other details
• Get, list, and delete recordings

anchorCreating and Using Webex Apps

The base URL for the Webex REST API is https://webexapis.com/v1/. Detailed information about each API resource and endpoint can be found in the API Reference.

The Meetings-related APIs can be used with Webex Integrations. If you aren't familiar with integrations, check out the Integrations Guide for more information. To create a new integration, select My Webex Apps from the menu under your avatar at the top of this page to get started.

To use the Webex REST API you'll need to be a Webex Meetings subscriber with a Webex account backed by Cisco Webex Common Identity (CI). If you currently use Webex, your account is backed by Common Identity. If you're using only Webex Meetings, your site will need to be on Common Identity.

anchorMeetings API Scopes

The table below lists all meetings APIs and their required scopes at different levels.

The spark:all scope is required for the Create a Meeting API when roomId is specified.

Guest users can interact with regular Webex users via tokens generated by a Guest Issuer application. The table below lists the meetings APIs for guest issuer and the required scopes.

anchorUser Level Authentication and Scopes

Webex REST API authentication is described in detail in the Integrations Guide. The following scopes are required to use the meetings-related API resources:

The spark:all scope is required for the Create a Meeting API when roomId is specified.

anchorAdmin/Organization Level Authentication and Scopes

Webex developers now have the ability to leverage admin level scopes in their integrations. These new scopes allow WebEx Admin grant scopes to integrations on behalf of other users. This allows developers and admins flexibility in creating integrations to meet their needs and can lessen the need for individual users of an integration to perform an OAuth grant.

Several conditions and restrictions apply to organizations that want to authorize an integration that utilizes these admin level scopes.

The spark:all scope is required for the Create a Meeting API when roomId is specified.

• The admin that authorizes the integration for an organization (meeting:admin_* scopes) must be a full org admin. This admin must also be a site admin for the site or sites that contain the users they wish the integration to be able to act on behalf of.
• Partners: Partner admins who are also full org admins for their own org are not permitted to authorize integrations that use these admin level scopes for their customer's org. They are however able to authorize these types of integrations in their own org as per the previous requirement.

In support of this functionality the admin must grant the integration the following admin scopes:

The admin feature applies to both CI-enabled or CI-linked Webex sites. The managed user account (host) does not need to be CI-enabled/CI-linked.

In support of this feature, the following will be allowed as query parameters on GET requests and as valid attributes in the request body of POST and PUT commands:

• hostEmail - When set as a query parameter on a GET request made by an admin, the response will be the meetings where the user of hostEmail is the meeting host or an invitee, not the meetings for the admin user. When set as part of the request body sent to a POST method by an admin, the specified user will be the host of the meeting if he belongs to a site managed by the admin user. When set as part of the request body sent to a PUT or PATCH method, the field is not editable and is only used to update or patch a meeting on behalf of the real meeting host. Please use the Reassign Meetings to a New Host API if you need to update the meeting host. The meeting will belong to the specified host's default site unless the siteUrl attribute is used to override this.
• siteUrl - optional - When set as a query parameter on a GET request, the response will be restricted to the meetings that belong to the specified site that are hosted by the caller of the API, or by the user specified via the hostEmail parameter. When set as part of the request body sent to a POST or PUT method, this attribute allows the caller of the API to create a meeting in a non-preferred site for a host whose account is associated with multiple sites.

Developers can become aware of the allowable values for siteUrl by querying the GET /meetingPreferences/sites API.

anchorCompliance Officer Level Authentication and Scopes

An administrator user can be associated with a specific role to become a Compliance Officer. The role of a compliance officer is to ensure that a company is conducting its business in full compliance with all laws and regulations that pertain to its particular industry, as well as professional standards, accepted business practices, and internal standards. The following scopes are required to use the meetings-related API resources as a Compliance Officer:

anchorScopes and User Roles

The table below lists the relationship between scopes and user roles:

anchorMeeting Series, Scheduled Meetings, and Meeting Instances

When using the Meetings and Meeting Invitees API resources, it's important to understand the difference between "meeting series", "scheduled meetings", and "meetings" objects. Each of these objects may be sent to or received from the API. To differentiate them, the value of the meetingType attribute in the object will be one of:

• meetingSeries – a container object that includes all of the scheduling information for a meeting
• scheduledMeeting – an object that represents the information associated with the scheduling information associated with a single instance of a meeting; a scheduledMeeting object can be thought of as a “child” of a meetingSeries object
• meeting – an object that represents a meeting that is currently happening or has happened in the past; this object is created only when a meeting starts

Both meeting series and scheduled meetings may be used with the API. For example, to invite an attendee to the series, use the ID of the meeting series with the Create a Meeting Invitee endpoint. Or, to invite someone to just one scheduled instance of a meeting, use the ID of the scheduled meeting instead.

anchorMeeting States

Different meeting states are available for each type of meeting object. See "Meeting Series, Scheduled Meetings, and Meeting Instances" above for more detail.

Meeting Series

• active – one or more future scheduled meetings exists for this series
• inProgress – an instance of this meeting is happening now or someone has joined meeting before the host and is waiting in the lobby
• expired – all scheduled instances of this meeting have passed

Scheduled Meeting

• scheduled – this meeting is scheduled in the future
• ready – this meeting is ready to start
• ended – this meeting was started and is now over
• missed – this meeting was scheduled in the past but never happened

Meeting

• lobby – a locked meeting has been joined by participants, but no hosts have joined
• inProgress – the meeting has been joined and unlocked
• ended – a meeting has concluded

anchorAvailable Meeting Attributes for Different Meeting States

The table below lists which meeting attributes are available for different meeting states when the meeting type is meetingSeries:

The table below lists which meeting attributes are available for different meeting states when the meeting type is scheduledMeeting:

The table below lists which meeting attributes are available for different meeting states when the meeting type is meeting:

anchorMeeting Lifecycle

Meeting Auto Delete

Auto Delete Options

There's a Delete from My Meetings when completed option in Webex page of classic view. It's invisible in Webex page of modern view and the default value is unchecked.

If the Delete from My Meetings when completed option is unchecked for a meeting, there will be a mandatory Delete after 180 days option for the meeting.

Auto Delete Cases

1. If the Delete from My Meetings when completed option is checked for a non-recurring meeting, the meeting will be deleted automatically after the scheduled end time.
2. If the Delete from My Meetings when completed option is unchecked for a non-recurring meeting, the meeting will be deleted automatically 180 days after the scheduled end time.
3. If the Delete from My Meetings when completed option is checked for a meeting series, the entire meeting series will be deleted automatically after the scheduled end time of the last scheduled meeting of the meeting series.
4. If the Delete from My Meetings when completed option is unchecked for a meeting series, the entire meeting will be deleted automatically 180 days after the scheduled end time of the last scheduled meeting of the meeting series.

Meeting Series Lifecycle

1. A meeting series is created.
2. A scheduled meeting of the meeting series is started, or someone has joined the meeting before the host and is waiting in lobby.
3. The ongoing scheduled meeting has ended, but it has not passed the scheduled end time of the last scheduled meeting of the meeting series, or the meeting has not yet been started and the participants which were previously waiting in lobby have left the meeting.
4. The ongoing scheduled meeting is ended, and it has passed the scheduled end time of the last scheduled meeting of the meeting series.
5. It has passed the scheduled end time of the last scheduled meeting of the meeting series.
6. The meeting series is deleted manually or automatically after it's been expired.
7. The meeting series is deleted manually.

Scheduled Meeting Lifecycle

1. The parent meeting series is created. Any scheduled meeting other than the first one of the meeting series is scheduled and it can be started in the future.
2. The parent meeting series is created. The first scheduled meeting of the meeting series is ready and it can be started immediately.
3. It has passed the scheduled end time of the previous scheduled meeting. The subsequent scheduled meeting becomes ready and it can be started immediately.
4. The previous ready scheduled meeting has been started and ended, and it has passed its scheduled end time. This scheduled meeting becomes ended.
5. The previous ready scheduled meeting has never been started, and it has passed its scheduled end time. This scheduled meeting becomes missed.
6. The scheduled meeting is deleted manually or it's deleted when the parent meeting series is deleted maunally.
7. The scheduled meeting is deleted manually or it's deleted when the parent meeting series is deleted maunally or automatically.
8. The scheduled meeting is deleted manually or it's deleted when the parent meeting series is deleted maunally.
9. The scheduled meeting is deleted manually or it's deleted when the parent meeting series is deleted maunally or automatically.

Meeting Lifecycle

1. A locked meeting has been joined by participants, but no hosts have joined.
2. The meeting has been started and not ended yet.
3. The participants in lobby have been admitted to meeting.
4. The meeting has ended.

anchorMeeting Template Locales

Meetings can be created by meeting templates. The list of meeting templates that is available for the authenticated user can be retrieved from List Meeting Templates API with different values of locale. All the locales supported by Webex are listed below:

anchorWarnings

Some Meetings REST APIs have temporary restrictions due to known backend limitations, but the APIs overall will not fail. Instead, a warning message will be returned in a "Warning" response header to indicate the restrictions. In the warning message, there'll be a link pointing to here and one or multiple codes to lookup in the table below:

anchorRestrictions on Updating a Meeting

When updating a meeting, there are different restrictions for different meeting types. It's important for a developer to understand these restrictions to avoid confusion and handle any restriction-related errors when they occur.

There are some general rules for updating a meeting. They are listed below.

Rule 1. start and end cannot be a time before the current time

This rule applies to meeting series and scheduled meeting.

When updating a meeting series or a scheduled meeting, the start and end in specified timezone cannot be a time before the current time. For example, assume that the current time is 2021-05-28T14:00:00+08:00, if update a meeting series, or a scheduled meeting with start of 2021-05-27T14:00:00+08:00 and timezone of Asia/Shanghai, it will fail saying that "Parameter 'start' or 'end' is before current time". Please note that the default timezone is UTC if not specified explicitly.

Rule 2. Limit for duration between start and end

This rule applies to meeting series and scheduled meeting.

Duration between start and end cannot be shorter than 10 minutes or longer than 24 hours.

Rule 3. Update is forbidden when an associated meeting instance is in progress

This rule applies to meeting series and scheduled meeting.

When a meeting instance is in-progress, its parent scheduled meeting and grandparent meeting series cannot be updated. In fact, when a meeting instance is in-progress, the state of the parent scheduled meeting is ready which means that currently this scheduled meeting is ready to join, and the state of the grandparent meeting series is inProgress which means that a meeting instance of the series is currently happening. Neither the parent scheduled meeting, nor the grandparent meeting series can be updated until the ongoing meeting instance is ended. If break this rule, it'll fail saying that "Meeting is in progress".

Rule 4. Update is forbidden for a meeting instance

This rule applies to meeting instance.

It's totally forbidden to update any meeting instance of any state. It fails with an error message like "Meeting ID '06263e1088604fc1b3ca17fbe49fe97d_I_195989045032040979' is not allowed for this API."

Rule 5. Update is forbidden to cross recurring interval

This rule applies to scheduled meeting.

What is a recurring interval

When a meeting series has been scheduled, each scheduled meeting of this meeting series has its own "territory of time". It means that any other scheduled meeting of the same meeting series cannot be updated to fall into the range of time of this scheduled meeting. Specifically, each scheduled meeting has its original timezone when the parent meeting series was scheduled. It can be an explicitly specified value such as Asia/Shanghai or UTC by default if not specified explicitly. Generally, the recurring interval of a scheduled meeting begins at 00:00:00 (inclusive) in the original timezone of the day of start, and ends at 00:00:00 (exclusive) in the original timezone of the day of the next scheduled meeting of the same meeting series. However, there's exception for the first and the last scheduled meeting of a meeting series. The first one has no beginning, and the last one has no end. It's explained in detail below with examples of daily meetings and weekly meetings. The rule for other meetings, e.g. yearly meetings, is similar.

1. Recurring intervals of a daily meeting series

Fig. 1 Recurring intervals of a daily meeting series

Fig. 1 illustrates the recurring intervals of a daily meeting series with four scheduled meetings.

• Recurring interval of d1: No beginning, to 2021-04-20T00:00:00+08:00 (exclusive).
• Recurring interval of d2: From 2021-04-20T00:00:00+08:00 (inclusive) to 2021-04-21T00:00:00+08:00 (exclusive).
• Recurring interval of d3: From 2021-04-21T00:00:00+08:00 (inclusive) to 2021-04-22T00:00:00+08:00 (exclusive).
• Recurring interval of d4: From 2021-04-22T00:00:00+08:00 (inclusive), no end.

2. Recurring intervals of a weekly meeting series

Fig. 2 Recurring intervals of a weekly meeting series

Fig. 2 illustrates the recurring intervals of a weekly meeting series with four scheduled meetings. Please note that recurring intervals of a weekly meeting can be of different lengths, and a single recurring interval may cross days.

• Recurring interval of w1: No beginning, to 2021-06-04T00:00:00+08:00 (exclusive).
• Recurring interval of w2: From 2021-06-04T00:00:00+08:00 (inclusive) to 2021-06-08T00:00:00+08:00 (exclusive).
• Recurring interval of w3: From 2021-06-08T00:00:00+08:00 (inclusive) to 2021-06-11T10:00:00+08:00 (exclusive).
• Recurring interval of w4: From 2021-06-11T10:00:00+08:00 (inclusive), no end.

3. Recurring intervals of the first and last scheduled meetings of a meeting series

Fig. 3 Recurring intervals of the first and last scheduled meetings of a meeting series

Please pay attention to the recurring intervals of the first and the last scheduled meetings of a meeting series:

• The recurring interval of the first scheduled meeting of a meeting series has no beginning. For instance, Fig. 3 illustrates recurring intervals of a daily meeting series with three scheduled meetings. The recurring interval of d1 which is highlighted in green has no beginning and ends at 2021-04-20T00:00:00+08:00 (exclusive). Therefore, d1 can be updated to d1-01 or d1-02.
• The recurring interval of the last scheduled meeting of a meeting series has no end. For instance, in Fig. 3, the recurring interval of d3 which is highlighted in blue begins at 2021-04-21T00:00:00+08:00 and has no end. Therefore, d3 can be updated to d3-01 or d3-02.

Cross-recurring-interval update is forbidden

Based on the recurring interval concept, cross-recurring-interval update is forbidden. If break this rule, it'll fail with an error message like "meeting.err.two_meeting_schedule_at_same_day". Specifically, meetings RESTful API examines start against crossing-recurring-interval behavior when updating a scheduled meeting, but it doesn't examine end against this rule.

1. Update scheduled meetings of a daily meeting series successfully

Fig. 4 Update scheduled meetings of a daily meeting series successfully

Fig. 4 illustrates non-cross-recurring-interval updates for scheduled meetings of a daily meeting series. All the updates in Fig. 4 are within the same recurring interval and succeed. For example:

• d1 to d1-s1: This update is within d1's recurring interval. It makes the previously missed d1 to be ready again.
• d2 to d2-s1: This update is within d2's recurring interval. It makes d2 a little earlier in the same day.
• d2 to d2-s2: This update is within d2's recurring interval. It makes d2 a little later in the same day.
• d4 to d4-s1: This update is within d4's recurring interval. It makes d4 a little earlier in the same day.
• d4 to d4-s2: This update is within d4's recurring interval. It makes d4 a little later in the same day.
• d4 to d4-s2: This update is within d4's recurring interval. It makes d4 a little later in the same day.
• d4 to d4-s3 or d4-s4: This update is within d4's recurring interval. It moves d4 to the next day or even later. However, they are both within the recurring interval of d4 since d4 is the last scheduled meeting of the parent meeting series. It doesn't break rule 5.

2. Update scheduled meetings of a daily meeting series crossing recurring interval

Fig. 5 Update scheduled meetings of a daily meeting series crossing recurring interval

Fig. 5 illustrates cross-recurring-interval updates for scheduled meetings of a daily meeting series. All the updates in Fig. 5 break rule 5 and fail. For example:

• d1 to d1-f1: This update moves d1 to a time before the current time and breaks rule 1.
• d2 to d2-f1: This update moves d2 to the previous day and breaks rule 5.
• d2 to d2-f2: This update moves d2 to the next day and breaks rule 5.
• d3 to d3-f4: This update moves d3 to two days later and breaks rule 5.
• d4 to d4-f2: This update moves d4 to two days ago and breaks rule 5.

3. Update scheduled meetings of a weekly meeting series successfully

Fig. 6 Update scheduled meetings of a weekly meeting series successfully

Fig. 6 illustrates non-cross-recurring-interval updates for scheduled meetings of a weekly meeting series. All the updates in Fig. 6 are within the same recurring interval and succeed. For example:

• w1 to w1-s1: This update is within w1's recurring interval. It moves the previously missed w1 to the next day and makes it ready again. It crosses day, but it doesn't cross recurring interval. So, it doesn't break rule 5.
• w1 to w1-s2: This update is within w1's recurring interval. It moves the previously missed w1 to two days later and makes it ready again. It crosses day, but it doesn't cross recurring interval. So, it doesn't break rule 5.
• w2 to w2-s1: This update is within w2's recurring interval. It moves w2 a little earlier in the same day.
• w2 to w2-s3: This update is within w2's recurring interval. It moves w2 three days later. It crosses day, but it doesn't cross recurring interval. So, it doesn't break rule 5.
• w4 to w4-s2: This update is within w4's recurring interval. It moves w4 to the two days later or even later than that. However, it's within w4's recurring interval since w4 is the last scheduled meeting of the parent meeting series. It doesn't break rule 5.

4. Update scheduled meetings of a weekly meeting series crossing recurring interval

Fig. 7 Update scheduled meetings of a weekly meeting series crossing recurring interval

Fig. 7 illustrates cross-recurring-interval updates for scheduled meetings of a weekly meeting series. All the updates in Fig. 7 break rule 5 and fail. For example:

• w1 to w1-f1: This update moves w1 to a time before the current time and breaks rule 1.
• w1 to w1-f2: This update moves w1 to the next recurring interval and breaks rule 5.
• w2 to w2-f1: This update moves w2 to the previous recurring interval and breaks rule 5.
• w2 to w2-f2: This update moves w2 to the next recurring interval and breaks rule 5.
• w2 to w2-f3: This update moves w2 to the last recurring interval and breaks rule 5.
• w4 to w4-f2: This update moves w4 to the second recurring interval and breaks rule 5.

5. Boundary cases

Fig. 8 Boundary cases

Meetings RESTful API examines start against crossing-recurring-interval behavior when updating a scheduled meeting, but it doesn't examine end against this rule. In other words, if the target start crosses recurring interval, the update breaks rule 5; if the target start doesn't cross recurring interval, it doesn't break rule 5.

Fig. 8 illustrates various boundary cases of updating a scheduled meeting of a daily meeting series. The upper part is moving d1 towards d2 and the lower part is moving d2 towards d1.

The upper part is forward boundary cases:

• d1 to d1-b1: This update doesn't cross recurring interval. It doesn't break rule 5.
• d1 to d1-b2: The target end is on the boundary but the target start doesn't cross boundary. It doesn't break rule 5.
• d1 to d1-b3: The target end is in the next recurring interval but the target start doesn't cross boundary. It doesn't break rule 5.
• d1 to d1-b4: The target start is on the boundary and the target end is in the next recurring interval. Since a recurring interval is left-inclusive and right-exclusive, it breaks rule 5.
• d1 to d1-b5: Both the target start and end are in the next recurring interval. It breaks rule 5.

The lower part is backward boundary cases:

• d2 to d2-b1: This update doesn't cross recurring interval. It doesn't break rule 5.
• d2 to d2-b2: The target start is on the boundary. Since a recurring interval is left-inclusive and right-exclusive, it doesn't break rule 5.
• d2 to d2-b3: The target start is in the previous recurring interval. It breaks rule 5.
• d2 to d2-b4: The target start is in the previous recurring interval and the target end is on the boundary. It breaks rule 5.
• d2 to d2-b5: Both the target start and end are in the previous recurring interval. It breaks rule 5.

Fig. 9 Cross-day cases

There're extreme situations where the parent meeting series was scheduled crossing-day. Fig.9 illustrates a daily meeting series of which the start is in some day while the end is in the next day. d2, d3 and d4 are successive scheduled meetings of the series. Here're the recurring intervals of d3 and d4:

• Recurring interval of d3: From 2021-04-20T00:00:00+08:00 (inclusive) to 2021-04-21T00:00:00+08:00 (exclusive).
• Recurring interval of d4: From 2021-04-21T00:00:00+08:00 (inclusive) to 2021-04-22T00:00:00+08:00 (exclusive).

The following updates break rule 5:

• d3 to d3-01: The target start is in the previous recurring interval. It breaks rule 5.
• d3 to d3-02: Same as above.
• d3 to d3-03: Same as above.
• d3 to d3-10: The target start is in the next recurring interval. It breaks rule 5.
• d3 to d3-11: Same as above.

Restrictions table

To summarize, the restrictions on updating a meeting of different types are listed in the table below: