Webex Meetings

Release Notes 10.0.0

Important: The XML API 10.0.0 release changes some schema definitions. For the latest schema definitions, see the release notes announcements page. The features in this release are backward compatible with previous releases.

Overview

This release note describes the changes made in the release of Webex XML API 10.0.0. These changes apply to your integration with WBS 31. All features are backward compatible with existing integrations. The changes to the latest schema definitions are explained below.

What is New in this Release

This section describes the new features in XML API 10.0.0.

Rate Limiting of APIs

In order to protect the Webex services from denial of service attacks and possible developer errors that might overload the servers, throttling is introduced. API calls from all authenticated calls are going to be throttled based on the groups the APIs belongs to Useroperations, Meeting Writeoperations, Meeting Listoperations.

There are global limits as well as site-level limits (available on request and validation by Webex Product Management) for the number of APIs per minute per caller.

The rate limit will not be enforced in this release. Enforcement of the limit will be implemented later. This capability will first be implemented only to collect data and metrics. The reason for collecting data is to establish baselines of rate usage for each of the different kinds of API calls. We are doing this first before enforcing any limits in order to understand what constitutes normal usage.

When enforced, the limits will be enforced for a specific period of 60 seconds. This means that an API call that results in a rate limit error can still be submitted 60 seconds later when the specific API is once again available.

Note: A new error code introduced to indicate when an API caller hits a rate limit: 000045: API Rate Limit Reach

Affected APIs

All APIs that requires authentication.

Schema Changes

There is no change to schema related to this rate limit.

Example Error Message

The following XML snippet shows an example return message with error 000045: API Rate Limit Reached.

Code Snippet
Copy<?xml version="1.0" encoding="ISO-8859-1"?>
<serv:message
   xmlns:serv="http://www.webex.com/schemas/2002/06/service"
   xmlns:com="http://www.webex.com/schemas/2002/06/common"
   xmlns:ep="http://www.webex.com/schemas/2002/06/service/ep"
   xmlns:meet="http://www.webex.com/schemas/2002/06/service/meeting">
<serv:header>
  <serv:response>
    <serv:result>FAILURE</serv:result>
    <serv:reason>API rate limit reached</serv:reason>
    <serv:gsbStatus>PRIMARY</serv:gsbStatus>
    <serv:exceptionID>000045</serv:exceptionID>
  </serv:response>
</serv:header>
<serv:body>
<serv:bodyContent/>
</serv:body>
</serv:message>

Capability to Set/Update/Get Video Callback (XML API)

The Webex meeting client now includes the support for Video Callback. The XML API is enhanced to support this feature by supporting video endpoints along with audio endpoints. For example, just as there is a callback feature for phone numbers, the Webex product now supports callback to a video endpoint such as a Telepresence device. This release of the XML API supports this capability by providing videoCallback information (video callback SIP URLs), which can be set at the user’s preference. A default URL can also be set.

Affected APIs

  • setUser
  • getUser
  • createUser

setUser API

The setUser API now includes video callback information (SIP URLs). The schema has changed to include this information as part of the videoSystems element as shown in the following schema diagram.

If a video address is invalid in a videoCallback address field, the system returns an error (see example below). If more than one defaultFlag is set to true within the videoSystems element, the system returns an exceptionID of 999999 (see example below).

Example setUser Request

The following XML snippet shows an example setUser request that includes video callback information.

Code Snippet
Copy<?xml version="1.0" encoding="UTF-8"?>
<serv:message
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:serv="http://www.webex.com/schemas/2002/06/service"
   xsi:schemaLocation="http://www.webex.com/schemas/2002/06/service
   http://www.webex.com/schemas/2002/06/service/service.xsd">
   <header>
   <securityContext>
     <webExID>user1</webExID>
     <password>...</password>
     <siteName>...</siteName>
   </securityContext>
   </header>
   <body>
   <bodyContent xsi:type="java:com.webex.service.binding.user.SetUser">
     <webExId>user1</webExId>
     <videoSystems>
     <videoCallback>
       <systemName>my video 1</systemName>
       <address>mv1@test.com</address>
       <defaultFlag>true</defaultFlag>
     </videoCallback>
     <videoCallback>
       <systemName>my video 2</systemName>
       <address>mv2@test.com</address>
       <defaultFlag>false</defaultFlag>
     </videoCallback>
     </videoSystems>
   </bodyContent>
   </body>
</serv:message>

Example setUser Errors

If a video address is invalid in a videoCallback address field, the system returns the following error:

Code Snippet
Copy<?xml version="1.0" encoding="UTF-8"?>
<serv:message
 xmlns:serv="http://www.webex.com/schemas/2002/06/service"
 xmlns:com="http://www.webex.com/schemas/2002/06/common"
 xmlns:use="http://www.webex.com/schemas/2002/06/service/user">
 <serv:header>
 <serv:response>
 <serv:result>FAILURE</serv:result>
 <serv:reason>The video address is invalid</serv:reason>
 <serv:gsbStatus>PRIMARY</serv:gsbStatus>
 <serv:exceptionID>999999</serv:exceptionID>
 </serv:response>
 </serv:header>
 <serv:body>
 <serv:bodyContent/>
 </serv:body>
</serv:message>

If the videoSystems element is part of a request but the site CMR is disabled (site isEnableCET is false), the system returns the following error:

Code Snippet
Copy<?xml version="1.0" encoding="UTF-8"?>
<serv:message
 xmlns:serv="http://www.webex.com/schemas/2002/06/service"
 xmlns:com="http://www.webex.com/schemas/2002/06/common"
 xmlns:use="http://www.webex.com/schemas/2002/06/service/user">
 <serv:header>
 <serv:response>
 <serv:result>FAILURE</serv:result>
 <serv:reason>videoSystems cannot be set because site CET is disabled</serv:reason>
 <serv:gsbStatus>PRIMARY</serv:gsbStatus>
 <serv:exceptionID>999999</serv:exceptionID>
 </serv:response>
 </serv:header>
 <serv:body>
 <serv:bodyContent/>
 </serv:body>
</serv:message>

One of the video callback address fields must be set as the default callback address. In other words, one of the defaultFlag elements within a set of videoCallback elements must be set to true. If none of the defaultFlag elements are set to true, the system returns the following error:

Code Snippet
Copy<?xml version="1.0" encoding="UTF-8"?>
<serv:message
 xmlns:serv="http://www.webex.com/schemas/2002/06/service"
 xmlns:com="http://www.webex.com/schemas/2002/06/common"
 xmlns:use="http://www.webex.com/schemas/2002/06/service/user">
 <serv:header>
 <serv:response>
 <serv:result>FAILURE</serv:result>
 <serv:reason>One defaultFlag in videoCallback must be set as true</serv:reason>
 <serv:gsbStatus>PRIMARY</serv:gsbStatus>
 <serv:exceptionID>999999</serv:exceptionID>
 </serv:response>
 </serv:header>
 <serv:body>
 <serv:bodyContent/>
 </serv:body>
</serv:message>

Only one of the video callback address fields is allowed to be set as the default callback address. If more than one of the defaultFlag elements are set to true within a set of videoCallback elements, the system returns the following error:

Code Snippet
Copy<?xml version="1.0" encoding="UTF-8"?>
<serv:message
 xmlns:serv="http://www.webex.com/schemas/2002/06/service"
 xmlns:com="http://www.webex.com/schemas/2002/06/common"
 xmlns:use="http://www.webex.com/schemas/2002/06/service/user">
 <serv:header>
 <serv:response>
 <serv:result>FAILURE</serv:result>
 <serv:reason>Only one defaultFlag in videoCallback can be set as true</serv:reason>
 <serv:gsbStatus>PRIMARY</serv:gsbStatus>
 <serv:exceptionID>999999</serv:exceptionID>
 </serv:response>
 </serv:header>
 <serv:body>
 <serv:bodyContent/>
 </serv:body>
</serv:message>

getUser API

The getUser API generates a response that now includes the video callback URL if the site CMR is enabled (site isEnableCET is true). The schema for the getUser request message is not changed in this release.

Example getUser Response

The following XML fragment is an example of a response to a getUser request. The response contains video callback information in the videoSystems element.

Code Snippet
Copy<?xml version="1.0" encoding="UTF-8"?>
<serv:message
    xmlns:serv="http://www.webex.com/schemas/2002/06/service"
    xmlns:com="http://www.webex.com/schemas/2002/06/common"
    xmlns:use="http://www.webex.com/schemas/2002/06/service/user">
    <serv:header>
        <serv:response>
            <serv:result>SUCCESS</serv:result>
            <serv:gsbStatus>PRIMARY</serv:gsbStatus>
        </serv:response>
    </serv:header>
    <serv:body>
        <serv:bodyContent xsi:type="use:getUserResponse"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <use:firstName>John</use:firstName>
            <use:lastName>Doe</use:lastName>
...
...
            <use:videoSystems>
                <use:videoCallback>
                    <use:systemName>my video 1</use:systemName>
                    <use:address>mv1@test.com</use:address>
                    <use:defaultFlag>true</use:defaultFlag>
                </use:videoCallback>
                <use:videoCallback>
                    <use:systemName>my video 2</use:systemName>
                    <use:address>mv2@test.com</use:address>
                    <use:defaultFlag>false</use:defaultFlag>
                </use:videoCallback>
            </use:videoSystems>
...
        </serv:bodyContent>
    </serv:body>
</serv:message>

createUser API

The createUser API now includes video callback information (SIP URLs). The schema is changed to include this information as part of a createUser request message within the videoSystems element as shown in the following schema diagram. The schema for the response is not changed.

Example createUser Request

The following XML snippet shows an example createUser request that includes video callback information.

Code Snippet
Copy<?xml version="1.0" encoding="UTF-8"?>
<serv:message
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:serv="http://www.webex.com/schemas/2002/06/service"
 xsi:schemaLocation="http://www.webex.com/schemas/2002/06/service
 http://www.webex.com/schemas/2002/06/service/service.xsd">
 <header>
 <securityContext>
 <webExID>siteadmin</webExID>
 <password>...</password>
 <siteName>...</siteName>
 </securityContext>
 </header>
 <body>
 <bodyContent xsi:type="java:com.webex.service.binding.user.createtUser">
 <webExId>user1</webExId>
...
...
 <videoSystems>
 <videoCallback>
 <systemName>my video 1</systemName>
 <address>mv1@test.com</address>
 <defaultFlag>true</defaultFlag>
 </videoCallback>
 <videoCallback>
 <systemName>my video 2</systemName>
 <address>mv2@test.com</address>
 <defaultFlag>false</defaultFlag>
 </videoCallback>
 </videoSystems>
...
 </bodyContent>
 </body>
</serv:message>

setUser Error Messages

The errors related to valid address elements and defaultFlag elements is similar to the setUser API. If a video address is invalid in a videoCallbackaddress field, the system returns an error. If no defaultFlag is set to true or if more than one defaultFlag is set to true within the videoSystems element, the system returns an exceptionID of 999999. In other words, one and only one defaultFlag element must be set to true within a set of videoCallback elements.
If the site is not CMR enabled (the site has CMR enabled when the site isEnableCET element is set to true), and the createUser request contains a videoSystems element, the system will return an error. See the above setUser API examples of error messages that the system returns when the response message contains one of these errors.

Change To The ConfId Type (XML API)

The ConfID Java Type has been converted to a Long data type to accommodate more meeting numbers. While there is no schema change, we recommend casting ConfId in your Java-based integrations to a Long data type. There will be a separate communication sent before enabling this change on all sites, allowing for the change in the integrations.

Affected APIs

  • createUser
  • setUser
  • getSessionInfo

Capability to Set/Update/Get Tele-Conference Callback (XML API)

On the Webex Product, a site admin can set the initial call back numbers for a host. (See the Call-back Teleconferencing checkboxes in the following screenshot.)

NOTE: The labels on the end user panel are not the exact same wording as the schema elements:

  • Office phone corresponds to the schema element workPhoneCallback.
  • Cell phone corresponds to the schema element cellPhoneCallback.
  • Alternate phone 1 corresponds to the schema element pagerCallback.
  • Alternate phone 2 correponds to the schema element faxCallbac.

A host can modify and change those preferences as well. The XML API now supports this capability to set or update these callback numbers (for both site admins and hosts). Keep in mind that the site option for Call-back Teleconferencing must be enabled for the site in order for site admins and hosts to have this capability. A host can set the callback information from their account, under My Webex-> MyProfile menu. Each number can be enabled separately by checking the Call Me checkboxes. The following screenshot shows an example of a host's MyProfile panel.

Affected APIs

  • createUser
  • setUser
  • getUser

The <options> element of the createUser, setUser, and getUser APIs now have an additional 4 elements. For consistency, the names of the callback elements are similar to the existing phone-number-related elements.

Note:

Example createUser Request

The following XML snippet shows an example createUser request message including Teleconferencing Call-back numbers enabled (under options).

Code Snippet
Copy<bodyContent xsi:type="java:com.webex.service.binding.user.CreateUser">
 <webExId>simon_6</webExId>
 <email>sim_6@qa.webex.com</email>
 <firstName>Simona_6</firstName>
 <lastName>CallBack</lastName>
 <password>P@551234</password>
 <privilege>
 <host>true</host>
 <labAdmin>false</labAdmin>
 </privilege>
 <active>ACTIVATED</active>
 <phones>
 <phone>1,,,,,456789</phone>
 <mobilePhone>134567890</mobilePhone>
 <fax>1,234,23432432,,,,,</fax>
 <pager>,,,,,,,</pager>
 </phones>
 <options>
 <workPhoneCallback>true</workPhoneCallback>
 <cellPhoneCallback>true</cellPhoneCallback>
 <faxCallback>true</faxCallback>
 <pagerCallback>true</pagerCallback>
 </options>
</bodyContent>

Example setUser Request

The following XML snippet shows a fragment of an example setUser request message including options for Teleconferencing Call-back.

Code Snippet
Copy<bodyContent xsi:type="java:com.webex.service.binding.user.SetUser">
 <webExId>simon_5</webExId>
 <phones>
 <phone>1,,2323553,,,456789</phone>
 <mobilePhone>134567890</mobilePhone>
 <fax>1,234,23432432,,,,,</fax>
 <pager>,,,,,,,</pager>
 </phones>
 <options>
 <workPhoneCallback>true</workPhoneCallback>
 <cellPhoneCallback>true</cellPhoneCallback>
 <faxCallback>true</faxCallback>
 <pagerCallback>true</pagerCallback>
 </options>
</bodyContent>

Example getUser Response

The following XML snippet shows a fragment of an example response to a getUser request message indicating the state of the Teleconferencing Call-back options

Code Snippet
Copy<use:subscriptionOffice>true</use:subscriptionOffice>
 <use:workPhoneCallback>true</use:workPhoneCallback>
 <use:cellPhoneCallback>true</use:cellPhoneCallback>
 <use:faxCallback>false</use:faxCallback>
 <use:pagerCallback>false</use:pagerCallback>
</use:options>

Security Enhancement – Single Logout API (XML API)

The AuthenticateUser API provides a session ticket to the API caller. The sessionTicket element currently expires based on a configurable period of time. This release introduces the revokeSessionTicket API to allow integrators to expire the session ticket any time before that period. We recommend enhancing your integrations to expire the tokens and reduce the security risk of old tokens being hijacked or re-used.

Affected APIs

  • revokeSessionTicket

Capability to Set/Get/Update View Video Thumbnails Option for Training Center

Training Center has the capability to set the option for Viewing Video Thumbnails by default when a session is scheduled. This capability is now available through APIs when training is scheduled. This release adds the viewVideoThumbs element as an optional element defined within the enableOptionsType element.

The XML API allows the video thumbnails to be set during the scheduling of a Training Session. The following screenshot shows how these options appear in the end user's Session Options panel.

When the View video thumbnails option is enabled, the end user has the option in the Attendees panel to select Thumbnails in order to view thumbnail versions of the video.

Affected APIs

  • createTrainingSession
  • setTrainingSession
  • getTrainingSession

The createTrainingSession API and the setTrainingSession API can include the viewVideoThumbs element as part of a request message.

Auto-enable CMR for new users

A site level flag is introduced which allows auto-enablement of CMR when a new user is created. When this flag is set, even if API caller does not set the site isEnableCET to true, the system creates the user with CMR enabled (as long as the license capacity has not been reached).

Affected APIs

  • createUser

There is no change to the schema definition. This change affects only the behavior of the createUser API for a site which has the site-level flag isEnableCET set to true.

Support Join Restrictions For SSO sites

For a site using Single Sign-On (SSO) a host can schedule a meeting that requires SSO before joining the meeting. The getSessionInfo API is enhanced to set the flag joinRequiresAccount. This means that if the flag joinRequiresAccount is set to true, hosts can set meetings to require SSO from attendees for a specific session (Meeting Center, Training Center and Event Center). See the figures below for examples.

Affected APIs

  • getSessionInfo

There is no change to the schema definition. The behavior of the getSessionInfo API is changed to account for the possibility of an SSO site that requires sign-in. This change in behavior supports the site admin option called SSO authentication for Attendees (see the screenshot below).

The change in behavior to the getSessionInfo API supports the user option to require single sign-on authentication in order to join a meeting created in Meeting Center, Training Center, or Event Center. See the screenshots below for examples of how these options appear to the end user.

Example Meeting Center Panel SSO Option

If the site flag joinRequiresAccount is set to true, hosts can set set the option to Require attendees to sign in with single sign-on authentication before joining this meeting. You can see an example of this option in the following Meeting Center screenshot.

Example Training Center Panel SSO option

If the site flag joinRequiresAccount is set to true, hosts can set the option to Require attendees to sign in with single sign-on authentication before joining this session. You can see an example of this option in the following Training Center screenshot.

Example Event Center Panel SSO option

If the site flag joinRequiresAccount is set to true, hosts can set the option to Require attendees to sign in with single sign-on authentication before joining this event. You can see an example of this option in the following Event Center screenshot.

Support Event Center e-Commerce

Event can require payments by attendees. This is a feature already supported by the product. The API is enhanced to return the Session Fee associated with the event. Training Center already supports this feature. The same attribute will be enhanced to return Event Center Session Fees.

Affected APIs

  • getSessionInfo

There is no change to the schema definition. The behavior of the getSessionInfo API has changed to account for a value returned in the sessionFee element as part of an Event Center meeting.

The XML API schemas and release notes are available at the Cisco Webex Developer Portal:

XML API Reference

The URL API release notes are available at the Cisco Webex Developer Portal:

URL API Reference

Next