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

Embedded Apps 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

  • deviceType - The given device form factor. One of [DESKTOP | MOBILE | BROWSER].

webex.Application.isPrivateDataAvailable : boolean

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

  • isPrivateDataAvailable - Indicates 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

  • displayContext - Display 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

  • isShared - Indicates 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

  • capabilities - Indicates 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

  • sdkVersion - Indicates 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

  • theme - Indicates 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

  • about - General 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

  • language - Indicates 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

  • 0 - Operation completed successfully.
  • 1 - Call failed but arguments were incorrect.
  • 2 - Call failed due to invalid arguments.
  • 3 - Call to register an event failed because the event is already registered.
  • 4 - Call to register an event failed because the event name is unknown to the framework.
  • 5 - Call failed because it's not supported in the current context (Meeting or Space, for example).
  • 6 - Call failed because the feature is not supported.
  • 7 - Call 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.
  • SUCCESS - Operation completed successfully.
  • GENERIC_ERROR - Call failed but arguments were incorrect.
  • INVALID_ARGUMENT - Call failed due to invalid arguments.
  • EVENT_ALREADY_REGISTERED - Call to register an event failed because the event is already registered.
  • EVENT_UNKNOWN - Call to register an event failed because the event name is unknown to the framework.
  • BAD_CONTEXT - Call failed because it's not supported in the current context (Meeting or Space, for example).
  • NOT_SUPPORTED - Call failed because the feature is not supported.
  • NOT_INITIALIZED - Call 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

  • id string - Meeting 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.
  • title string - Title of the given meeting; blank if app.isPrivateDataAvailable is false.
  • startTime string - Start time of the given meeting, if available, for example, "2021-01-17T13:00:00.00Z". Blank if not available.
  • endTime string - End time of the given meeting if available, for example, "2021-01-17T13:00:10.00Z". Blank if not available.
  • conferenceId string - Conference 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.
  • userRoles Array.<string> - Represents the given users role(s). Can be 1 or more of these possible string values: "PARTICIPANT", "GUEST", "HOST", "COHOST", "PANELIST", and "PRESENTER".
  • meetingType string - Information 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

User

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

Properties

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

  • isShared boolean - Indicates 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

  • displayContext string - Indicates 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

  • theme string - Indicates the current theme, LIGHT or DARK.

meeting:infoChanged

Fired when meeting information has changed for the given meeting.

Properties

  • - Webex.Application.Meeting object.

meeting:roleChanged

Event fired when the role for the current participant changes.

Properties

  • userRoles string - User role.

space:infoChanged

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

Properties

  • webex.application.space