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

Embedded Apps API Reference

anchorBasic Usage
anchor

To add the Embedded Apps Framework to your web application add the following to the <HEAD> of your app's main HTML page:

<script src="https://binaries.webex.com/static-content-pipeline/webex-embedded-app/v1/webex-embedded-app-sdk.js" defer></script>

In your app's main index.js file create a new Webex.Application instance and create a function to handle the onReady() promise when it resolves successfully.

var app = new window.Webex.Application();

app.onReady().then(function () {
  console.log('App is ready. App info:', app);
});
anchorClasses
anchor
Webex.Application

Main application object you use to set sharing URLs, register event listeners, and get information about the application and its context.

Example usage

var app = new window.Webex.Application();

app.onReady().then(() => { // Create event listeners app.listen() .then(() => { app.on("application:shareStateChanged", (event) => { // Call custom function handleShareStateChange(event); }) app.on("application:themeChanged", (event) => { // Call custom function handleThemeChange(event); }) });

Webex.Application.Context

Application context object that exposes methods for getting information about users, meetings, and spaces. It is exposed as a context property on the Webex Application instance.

Example usage

var app = new window.Webex.Application();

app.onReady().then(() => { app.context.getUser().then((user) => { console.log("getUser() promise resolved. User", user); } ).catch((error) => { console.log("getUser() promise failed " + error.message); }) });

Webex.Application

Main application object you use to set sharing URLs, register event listeners, and get information about the application and its context.

Example usage

var app = new window.Webex.Application();

app.onReady().then(() => {
  // Create event listeners
  app.listen()
    .then(() => {
      app.on("application:shareStateChanged", (event) => {
        // Call custom function
        handleShareStateChange(event);
      })
      app.on("application:themeChanged", (event) => {
        // Call custom function
        handleThemeChange(event);
      })
});

webex.Application.deviceType : string

Kind: instance constant of
Read only: true
Since: 1.1.0
Properties

NameDescription
deviceTypeThe given device form factor. One of [DESKTOP

webex.Application.isPrivateDataAvailable : boolean

Kind: instance constant of Read only: true Since: 1.1.0 Properties

NameDescription
isPrivateDataAvailableIndicates if real IDs for users, meetings, and spaces are available to the application (true), or if derived IDs are available (false) . See About Access to Private Data in Embedded Apps for more information.

webex.Application.displayContext : string

Kind: instance constant of Read only: true Since: 1.1.0 Properties

NameDescription
displayContextDisplay context in which the embedded app is running. One of the following strings: "MEETING_SIDEBAR", "MEETING_STANDALONE_WINDOW", "MEETING_MAINVIEW", or "SPACETAB". Default is "MEETING_SIDEBAR".

webex.Application.isShared : boolean

TRUE = share is ongoing; FALSE = share is not taking place.

Kind: instance constant of Read only: true Since: 1.1.0 Properties

NameDescription
isSharedIndicates if the embedded app’s link (specified using the app.setShareUrl() method) has been added to the meeting or space by the user.

webex.Application.capabilities : Array.<string>

A combination of TOUCH, SHARED_SYSTEM, MULTIPLE_USER_SYSTEM, and VIEW_ONLY.

Kind: instance constant of Read only: true Since: 1.1.0 Properties

NameDescription
capabilitiesIndicates the capabilities of the given device. Currently not in use and subject to change. An empty string array is returned.

webex.Application.sdkVersion : string

Kind: instance constant of Read only: true Since: 1.1.0 Properties

NameDescription
sdkVersionIndicates the SDK version the given meetings client implements. Example values: "1.x" for 41.6 to 41.9.

webex.Application.theme : string

Kind: instance constant of Read only: true Since: 1.1.0 Properties

NameDescription
themeIndicates the given theme of the given meetings client, either Theme.LIGHT, or Theme.DARK.

webex.Application.about : string

Kind: instance constant of Read only: true Since: 1.1.0 Properties

NameDescription
aboutGeneral information about the host. This format is subject to change and should only be used for diagnostic purposes.

webex.Application.language : string

Kind: instance constant of Read only: true Since: 1.1.0 Properties

NameDescription
languageIndicates the given language being used by the given meetings client. Example values: "en-US", "da-DK", etc.

webex.Application.setShareUrl(internalUrl, externalUrl, title, optionals) ⇒ Promise.<number>

Called by the initiator embedded app (the one specified by Start Page URL in the Developer Portal) to specify the URL of an app to share with meeting participants, or to add as a tab to a space.

  • Calling setShareUrl() in a meeting causes the Open Together button to appear in the initiator app's window. Clicking this button opens the specified URL for all meeting participants.
  • Calling setShareUrl() in a space causes the Add to Tab button to appear in the initiator app's window. Clicking this button adds the specified URL to the space as a new tab.

Notes:

  • The first parameter to setShareUrl() (internalUrl) is required and specifies the URL of an embedded app to open for meeting participants or add as a tab to a space. This app at this URL should integrate with the Embedded App Framework.

  • The second parameter (externalUrl) is optional and specifies the URL of a version of your application that does not integrate with the Embedded App Framework. In a space this URL is used for the "Open in Browser" and "Copy URL" menu items in the tab added to the space.

  • When invoked in a space context the initiator app must pass a value for the title parameter. If you don't want to provide an external URL for your application then pass an empty string for the second parameter, for example:

     app.setShareUrl("https://www.example.com/app/", "", "Tab name")

Kind: instance method of Returns: Promise.<number> - Index to the static ErrorCodes array. 0 = SUCCESS, 1 = GENERIC_ERROR, 2 = INVALID_ARGUMENT Since: 1.1.0

ParamTypeDescription
internalUrlstringURL of an application that integrates with the Embedded App Framework to share with meeting participants, or add as a tab to a space. (Max length: 2083 characters)
externalUrlstringURL of a version of your application that does not require the Embedded App Framework. This URL is opened in Messaging spaces when a user selects the Open in Browser or Copy URL tab menu items. (Max length: 2083 characters).
titlestringTitle of the window or tab, depending on whether the app is running in a meeting or space. (Max length 256 characters.)
optionalsobjectEmpty JSON object, not currently used.

webex.Application.clearShareUrl()

Kind: instance method of Summary: Clears the URL that was previously set using setShareUrl. Since: 1.1.0

webex.Application.on(eventName, callback)

Kind: instance method of Summary: Called when a given event is raised. Since: 1.1.0

ParamTypeDescription
eventNamestringone of the supported events
callbackfunctionFunction called when a given event is raised. Callback function will carry the event data.

webex.Application.off(eventName)

Kind: instance method of Summary: Stop listening to a given event. Since: 1.1.0

ParamTypeDescription
eventNamestringName of the event to stop listening to.

webex.Application.listen() ⇒ Promise.<void>

Kind: instance method of Summary: Register to listen for incoming events. Fulfill: Since: 1.1.0

webex.Application.stopListening()

Kind: instance method of Summary: Stop listening to all events. Since: 1.1.0

webex.Application.onReady() ⇒ Promise.<void>

Kind: instance method of Summary: Called when the Webex.Application object has been initialized and the SDK is ready for 3rd party consumption. Fulfill: Since: 1.1.0

Webex.Application.ErrorCodes

Enumeration of error codes returned by API methods.

Kind: static enum of Read only: true Since: 1.1.0 Properties

NameDefaultDescription
0SUCCESSOperation completed successfully.
1GENERIC_ERRORCall failed but arguments were incorrect.
2INVALID_ARGUMENTCall failed due to invalid arguments.
3EVENT_ALREADY_REGISTEREDCall to register an event failed because the event is already registered.
4EVENT_UNKNOWNCall to register an event failed because the event name is unknown to the framework.
5BAD_CONTEXTCall failed because it's not supported in the current context (Meeting or Space, for example).
6NOT_SUPPORTEDCall failed because the feature is not supported.
7NOT_INITIALIZEDCall failed because the framework has not initialized. Make sure your applications waits for the onReady() to resolve before making any method calls to the framework.
SUCCESS0Operation completed successfully.
GENERIC_ERROR1Call failed but arguments were incorrect.
INVALID_ARGUMENT2Call failed due to invalid arguments.
EVENT_ALREADY_REGISTERED3Call to register an event failed because the event is already registered.
EVENT_UNKNOWN4Call to register an event failed because the event name is unknown to the framework.
BAD_CONTEXT5Call failed because it's not supported in the current context (Meeting or Space, for example).
NOT_SUPPORTED6Call failed because the feature is not supported.
NOT_INITIALIZED7Call failed because the framework has not initialized. Make sure your applications waits for the onReady() to resolve before making any method calls to the framework.

Webex.Application.Context

Application context object that exposes methods for getting information about users, meetings, and spaces. It is exposed as a context property on the Webex Application instance.

Example usage

var app = new window.Webex.Application();

app.onReady().then(() =>  {
  app.context.getUser().then((user) => {
      console.log("getUser() promise resolved. User", user);
    }
  ).catch((error) => {
      console.log("getUser() promise failed " + error.message);
    })
});

webex.Application.Context.getUser() ⇒ | number

Returns a promise for a User object if successful, or a numeric error code if rejected. Example usage

 var app = new window.Webex.Application();
 app.onReady().then(() => {
   app.context.getUser().then((m) => {
     console.log('getUser()', m);
   }).catch((error) => {
     console.log('getUser() promise failed with error', Webex.Application.ErrorCodes[error]);
   });
 }

Kind: instance method of Fulfill: - A User object Reject: number - Index to the static ErrorCodes array. 0 = SUCCESS, 1 = GENERIC_ERROR Since: 1.1.0

webex.Application.Context.getMeeting() ⇒ | number

Returns a promise for a Meeting object if successful, or a numeric error code if rejected. A BAD_CONTEXT error code (5) is returned if the method is called outside the context of a Meeting (in a Space, e.g.).

Example usage

 var app = new window.Webex.Application();
 app.onReady().then(() => {
   app.context.getMeeting().then((m) => {
     console.log('getMeeting()', m);
   }).catch((error) => {
     console.log('getMeeting() promise failed with error', Webex.Application.ErrorCodes[error]);
   });
 }

Kind: instance method of Fulfill: - A Meeting object. Reject: number - Index to the static ErrorCodes array. 0 = SUCCESS, 1 = GENERIC_ERROR, 5 = BAD_CONTEXT Since: 1.1.0

webex.Application.Context.getSpace() ⇒ | number

Returns a promise for a Space object if successful, or a numeric error code if rejected. A BAD_CONTEXT error code (5) is returned if the method is called outside the context of a Space (in a Meeting, e.g.).

Example usage

 var app = new window.Webex.Application();
 app.onReady().then(() => {
   app.context.getSpace().then((m) => {
     console.log('getSpace()', m);
   }).catch((error) => {
     console.log('getSpace() promise failed with error', Webex.Application.ErrorCodes[error]);
   });
 }

Kind: instance method of Fulfill: - A Space object Reject: number - Index to the static ErrorCodes array. 0 = SUCCESS, 1 = GENERIC_ERROR, 5 = BAD_CONTEXT Since: 1.1.0

anchorType Definitions
anchor

Meeting

Represents a Meeting object returned by a call to app.context.getMeeting().

Properties

NameTypeDescription
idstringMeeting ID. If app.isPrivateDataAvailable is true the value is a real meeting ID, otherwise it's a derived meeting ID. Derived IDs are guaranteed to be consistent for all users of the meeting.
titlestringTitle of the given meeting; blank if app.isPrivateDataAvailable is false.
startTimestringStart time of the given meeting, if available, for example, "2021-01-17T13:00:00.00Z". Blank if not available.
endTimestringEnd time of the given meeting if available, for example, "2021-01-17T13:00:10.00Z". Blank if not available.
conferenceIdstringConference ID. A unique ID that's created when then the first participant joins a meeting. If app.isPrivateDataAvailable is true then the value is a real conference ID, otherwise it's a derived conference ID. Derived IDs are guaranteed to be consistent for all users of the meeting.
userRolesArray.<string>Represents the given users role(s). Can be 1 or more of these possible string values: "PARTICIPANT", "GUEST", "HOST", "COHOST", "PANELIST", and "PRESENTER".
meetingTypestringInformation about the meeting type. Can be one of: "MEETING", or "EVENT".

Space

Object that represents a Space object returned by a call to app.context.getSpace().

Properties

NameTypeDescription
idstringSpace ID. Can be a real space ID or a derived space ID. If app.isPrivateDataAvailable is true then the real ID is used, otherwise the derived ID is used.
titlestringTitle of the given space; blank if app.isPrivateDataAvailable is false.

User

Object that represents a User object returned by a call to app.context.getUser().

Properties

NameTypeDescription
idstringCan be a real user ID or a derived user ID if app.isPrivateDataAvailable is false.
orgIdstringOrganization ID. Can be a real organization ID or a derived org ID if app.isPrivateDataAvailable if false.
emailstringEmail of the given user or blank if app.isPrivateDataAvailable is false.
displayNamestringDisplay name of the given user or blank if app.isPrivateDataAvailable is false.
tokenstringJWT token for the given user.
anchorEvents
anchor

The following events are generated by the framework in response to modifications to application state, meeting or space details, or user roles.

application:shareStateChanged

Event fired when the sharing state of a shared URL changes. See Responding to Events for details on event handling.

Properties

NameTypeDescription
isSharedbooleanIndicates if sharing is taking place.

application:displayContextChanged

Event fired when the rendering context of the application changes, for example, when a user pops out the app from the sidebar to a new window. See Responding to Events for details on event handling.

Properties

NameTypeDescription
displayContextstringIndicates the new display context.

application:themeChanged

Event fired when the user selects a new application theme. See Responding to Events for details on event handling.

Properties

NameTypeDescription
themestringIndicates the current theme, LIGHT or DARK.

meeting:infoChanged

Fired when meeting information has changed for the given meeting.

Properties

TypeDescription
Webex.Application.Meeting object.

meeting:roleChanged

Event fired when the role for the current participant changes.

Properties

NameTypeDescription
userRolesstringUser role.

space:infoChanged

Event fired when space information changes, for instance the space title.

Properties

NameType
webex.application.space