Webex Meetings > Develop and Test > XML API > Release Notes

XML API 10.0.0 Release Notes

Important: The XML API 10.0.0 release includes changes to some of the schema definitions. For more information, see the latest schema definitions on the release notes announcements page.
  

Overview

This release note describes the changes made with the release of Webex® XML API 10.0.0. Changes described in this release note are backward compatible with existing integrations. 

All features are backward compatible with existing integrations. There are some changes to the XML API 10.0.0 schema definitions as noted below.

Rate Limiting of APIs

Description

In order to protect the Webex services from denial of service attacks and possible developer errors that might overload the servers, throttling is being introduced. API calls from all authenticated calls are going to be throttled based on the groups the APIs belong to: User operations, Meeting Write operations, Meeting List operations.

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 time: 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 exists to indicate when an API caller hits a rate limit:

000045:  API Rate Limit Reach

Affected APIs

All APIs that require authentication

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.

<?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)

Description

The Webex meeting client now includes support for Video Callback. The XML API has been 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.

setUser API videoCallback element

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).

Sample setUser Request

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

<?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:

<?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:

<?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:

<?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:

<?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 has not changed in this release.

getUserResponse schema diagram

Sample 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. 
<?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 has 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 has not changed.

createUser API videoCallback schema diagram


Sample createUser Request
The following XML snippet shows an example createUser request that includes video callback information. 
<?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 videoCallback address 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 setUser API above for examples of error messages that the system returns when the response message contains one of these errors.

Change To The ConfId Type (XML API)

Description

The ConfID Java Type has been converted to a long, 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)

Description

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.) 

Site Admin page to set call-back teleconferencing

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 faxCallback

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.

Host account Call Me option

Affected APIs

createUser, setUser, getUser

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

NOTE:

Call-back Teleconferencing New Schema Elements

Example createUser Request
The following XML snippet shows an example createUser request message including Teleconferencing Call-back numbers enabled (under options). 
<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 
<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. 
<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)

Description

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

Description

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.

trainingEnableOptionsType

viewVideoThumbs 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.

Training Session options

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

Description

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

Description

For a site using Single Sign-On (SSO) a host can schedule a meeting that requires SSO before joining the meeting. The getSessionInfo API has been 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 has changed to account for the possibility of an SSO site that requies sign-in.  This change in behavior supports the site admin option called SSO authentication for Attendees (see the screenshot below).

Site Admin option for Require SSO Join

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.
Screenshot of Meeting Center option for single sign-on

ExampleTraining 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 session.  You can see an example of this option in the following Training Center screenshot.

Screenshot of Training Center option for single sign-on

Example Event 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 event.  You can see an example of this option in the following Event Center screenshot.

Screenshot of Event Center option for single sign-on

Support Event Center e-Commerce

Description

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.

Related Release Information

The XML API schemas and release notes are available at the Cisco Webex Developer Portal:
https://developer.cisco.com/site/collaboration/webex/webex-developer/develop-test/xml-api/reference/

The URL API release notes are available at the Cisco Webex Developer Portal:
https://developer.cisco.com/site/collaboration/webex/webex-developer/develop-test/url-api/reference/