Have an account?

  •   Personalized content
  •   Your products and support

Need an account?

Create an account

Cisco Webex for Developers White Paper

Island of Content

Available Languages

Download Options

  • PDF
    (684.7 KB)
    View with Adobe Reader on a variety of devices
Updated:December 16, 2020

Available Languages

Download Options

  • PDF
    (684.7 KB)
    View with Adobe Reader on a variety of devices
Updated:December 16, 2020
 

 

Introduction to the Webex collaboration platform

The Cisco Webex® platform provides users with multiple ways to communicate and share documents and other content. It features a real-time, online meeting experience as well as non-real-time collaboration spaces for chat and content sharing.

Cisco provides a range of Webex apps that run on PCs (Windows, Mac, and Linux), mobile devices (iOS and Android) and in web browsers. Cisco also provides a range of hardware devices, providing a high-quality video meeting experience. Every day, millions of users meet, share, and collaborate using the Webex platform via these different apps and devices.

This paper describes the two different ways integrations work in the Webex ecosystem. The first is about how you, as a developer, can extend Cisco’s own first-party Webex applications by using well-defined extensibility points to surface your own functionality within these applications. The second is how you can use functionality provided by the Webex platform to enhance your own applications and surface Webex functionality there.

The Webex platform provides a range of integration options that allow an external application to:

     Interact with Webex users

     Bring the application’s functionality and information into Webex

     Offer Webex functionality within the external application

We will provide an overview of some of the integration options available to the application developer, but before we start let’s describe the concept of “spaces” that the Webex experience is built around. If you are already a seasoned user of spaces in Webex (formerly Webex Teams), then feel free to jump ahead to the next section.

Spaces

Spaces are the hub for collaborating with the Webex platform. A space represents a virtual conversation between people, specifically the participants of the space. If you want to work with other people on a new project, you create a “space” for that project in the Webex app and add the other people who are working on the project as participants of the space. You give it a name that reflects the subject of the discussion and collaboration. The space is a venue—a gathering place for all your collaboration on the subject. You can send messages; share documents, screenshots, whiteboard sketches; and much more. You can even schedule a meeting in that space so that the other participants are invited to meet in the context of the overall conversation.

When two users want to communicate directly, they can use the direct message space that is created automatically when either one initiates a chat with the other. Sometimes this is referred to as their “one-to-one” space. A direct message space is the ongoing conversation between two people; a place to chat, call, meet, share and whiteboard. In a direct message space, the name for the space you see is the name of the other participant (i.e., if Alice and Bob have a direct message space, Alice sees it as the “Bob” space and Bob sees it as the “Alice” space).

Interacting with Webex users

While a space is usually a conversation between people, an application can participate in a space too. This opens many opportunities to allow users to interact with other business applications and to receive notifications from applications in a more natural way, without them having to do an explicit context switch to the other application.

Let’s use an example to illustrate some of the opportunities for integrating an application workflow directly into Webex.

Imagine a group of people working together on a project. They have created a Webex space that they will use to collaborate on the project (exchanging messages and files, scheduling and joining project meetings, etc.). They also use an external project management web application—let’s call it “SuperProjectManager”—to manage the project. They can use this app to:

     Create a project plan

     Define and track major milestones

     Define, assign, and track sub-tasks

Webex provides a mechanism for the SuperProjectManager application to be added to the project space as a virtual participant—a “bot”. Once added, SuperProjectManager can post messages to the space for the other participants to see, such as notifications when the project plan has been updated or when a milestone has been achieved or missed.

Using messages in the space, SuperProjectManager, users can make queries for project information and the application can post the summary directly back to the space for all to see.

When a task is created in SuperProjectManager, the application can post the details of the unassigned task to the space, even including a button that a user who wants to pick up the task could click to accept the task directly.

If a user has been on vacation for a week, when they come back, they can quickly catch up on the project by reading through the activity in the space, including messages from both users and SuperProjectManager.

If a user updates a task in SuperProjectManager, they can give it permission to cross-post their update on their behalf to the Webex space, rather than having to provide the update in both places.

Users can add website shortcuts to SuperProjectManager (or other web pages) to the space, making that content available right there, as a tab in the project space in Webex, where people are discussing and meeting about it.

Webex provides extensibility mechanisms for all these use cases. The first two we will cover are called “bots” and “integrations”. These are mechanisms whereby an application can participate in a space directly.

Bots

An external application can act as an independent participant in a Webex space, represented as a bot. So, in addition to people who are working together on a project being able to interact with each other in the space, they can also interact with an application through its virtual participant—its bot.

Typically, a bot represents an application as a whole, not an individual human user. This is in contrast to an “integration,” which we’ll cover later.

Other participants can send messages to a bot and the bot can respond to those messages. A bot can also post unsolicited messages to the space. By doing so, it can notify the space participants of updates or events from the external application.

Importantly, a bot can only access messages in a space that are specifically directed to it. A message is directed to a bot by explicitly @mentioning the bot in the message. A user can also create a 1:1 space with a bot. In that case, the bot is the only other participant in the space and thus, all messages are implicitly directed to the bot (i.e., no @mention required for the bot to read the message). Bot participants in a space are also clearly marked as such by having a “bot” label overlayed on the avatar. This makes is easy to distinguish a bot from normal participants.

The bot’s posts to the space can be simple text or an interactive card. Interactive cards are built using the open adaptive cards format. The cards can contain rich content, including text, images, and even buttons that allow the user to interact directly with the bot’s application. We’ll cover these buttons and cards and their capabilities in a later section.

Basic steps to implement a bot

1.     Create a Webex identity.

Just like a human Webex user, the bot needs an identity that includes:

    Display name – This is the name other participants will see in the space (e.g., “Project Tracker”).

    Username – This is the unique username for the bot (e.g., “superprojectmanager@webex.bot”). Users add the bot to a space using this username.

    Icon – This is an avatar image to represent the bot.

You can create your bot’s identity in the system using https://developer.webex.com/my-apps/new/bot.

You just need to provide some basic information (username, display name, avatar, description) and Webex will create the identity and provide the access token (credential) your application needs to access Webex as the bot.

Once the bot’s identity is created, you can add it to a space, and even send it messages. Of course, nothing interesting will happen until we connect it to the application.

2.     Register a webhook to receive notifications.

In order to be notified of events in Webex that are directed to your bot, your application needs to implement a webhook. A webhook is an HTTP callback that Webex uses to pass notifications to your application. For example, when someone mentions the bot in a space, Webex can notify the application using its registered webhook. Your app registers a webhook using the /v1/webhooks REST API. See how to create a webhook at: https://developer.webex.com/docs/api/v1/webhooks/create-a-webhook

When you register a webhook, you specify which resource it wants to monitor. For example, the resources a bot may be interested in include:

a.   Messages – for example, a new message was posted in a space

b.   Memberships – such as when the bot was added to a new space

c.   attachmentActions – for example, a user interacted with one of the bot’s cards

An application can register a single webhook to receive all notifications (the “firehose” approach, resource = “all”) or choose to partition the notifications by registering multiple webhooks. Each webhook can specify a particular resource to monitor and, if required, further refine the notifications it receives by using a filter (e.g., to only receive the messages notifications from a particular space).

Learn more about webhooks at the Webex developer website: https://developer.webex.com/docs/api/guides/webhooks

At this point, our bot can be added to a space and will be notified when something interesting happens. It has no way to post something into the space or respond to a message though. So, let’s do that in step 3.

3.     Webex APIs

The Webex platform provides a broad range REST APIs. Your application can call these Webex APIs to pass information into Webex, such as sending a message. You have the option of calling REST APIs directly (see https://developer.webex.com/docs/api/getting-started). Alternatively, you can use an SDK such as the Cisco® Webex JS SDK (see https://webex.github.io/webex-js-sdk/), which provides a convenient, higher-level abstraction.

Adding a bot to a space

As described earlier, a bot is a participant in a space, so you can add a bot to a space just like you would add any other user.

1.     Adding internal bots by name – If the bot was created by a user within your organization, the easiest way to add it to a space is to follow the normal flow for adding people to a space and search for the bot by name (e.g., “SuperProjectManager bot”).

2.     Adding bots by username – Users and bots from other organizations aren’t in your organization’s directory, so you can’t search for them by name. However, in the same way an external human participant can be added to a space using their email address, you can add a bot by using its username (e.g., “superprojectmanager@webex.bot”).

3.     If you want your bot to be found and used by Webex users in general, regardless of their organization, you should submit it to Webex App Hub: https://apphub.webex.com/. Webex App Hub provides a directory of bots and integrations for others to use. We’ll cover more details about Webex App Hub in a later section.

Buttons and cards

In addition to text-based messages, bots and integrations can interact with users by sending them interactive cards. The cards are defined using the open “adaptive cards” format (https://adaptivecards.io/). This format allows you to layout the card, including:

     Using container structures such as columns

     Adding multiple text fields with different styles

     Adding images

     Adding simple input controls

     Adding action buttons

Think of it as a lightweight UI framework for your application’s messages. An important aspect of the format is that most of the details are specified in relative or symbolic terms, rather than explicit values. For example, font sizes aren’t specified in point sizes, they are specified with values like “Small”, “Medium”, and “Large”. Colors aren’t specified with values like “red” or “green”; instead they are specified as semantic values such as “Accent”, “Good”, “Warning”, or “Attention”. The advantage of this approach is that the actual rendering of the cards can be adapted to suit your screen’s size, the UI theme you are using, etc.

Figure 1 shows an example of a card that our “SuperProjectManager bot” might send to the project space when a new, unassigned task is created in the SuperProjectManager application.

Example of a card a bot may send to a space

Figure 1.               

Example of a card a bot may send to a space

You can see a number of the features of a card in this example, including:

     An image

     Fields in columns

     Different sizes and styles of text

     An input box where the user can enter information (the date)

     An action button (“I’ll do it!”)

As mentioned in the bot section earlier, your application can register a webhook for the resource “attachmentActions” in order to be notified when a user interacts with the card.

Note, the firehose webhook for “all” resource will not receive attachmentActions notifications. The application must explicitly register a webhook for card notifications.

The webhook payload itself will contain the ID of the attachmentAction. Your application will need to retrieve the content using the Attachment Actions API: https://developer.webex.com/docs/api/v1/attachment-actions.

The payload of the attachmentAction contains several useful fields, which make it easy to incorporate the card into a workflow. These include:

     The ID of the person who interacted with the card

     The ID of the space the card is in

     The ID of the card message itself

     The content of all the card’s inputs (e.g., the contents of the date input box when the user clicked the “I’ll do it!” button in the card shown in Figure 1).

Cards are really powerful tools that allow your application to get users’ attention, step them through workflows, and present information in an intuitive, graphical way. They also allow the user to communicate with your application without ever leaving the space. In short, they can extend your application’s UI right into Webex.

Reivew our developer’s guide to using cards in Webex online: https://developer.webex.com/docs/api/guides/cards.

We have a convenient, interactive cards designer where you can lay out the card, see the results graphically in the designer, and have it generate the JSON card definition for you automatically. You can try it out online: https://developer.webex.com/buttons-and-cards-designer

There is even a Card School bot (cardSchool@webex.bot). Just add it to a space and it will teach you more about how to use cards in Webex.

Integrations

An integration is a virtual agent that acts on behalf of a real Webex user who has explicitly delegated the permission to do so to the application.

Continuing our “SuperProjectManager” application example, consider the case where a user is updating a task in SuperProjectManager with their progress. Instead of having to manually post the same status into the project’s Webex space for their team to see and discuss, it would be more convenient and efficient for the SuperProjectManger application to post the updated status directly into the Webex space on the user’s behalf. This type of delegated activity, acting on behalf of a user, is what integrations are used for.

Posting a message on behalf of a user is just a simple example. In theory, an integration can be implemented to perform any Webex feature interaction that a user can perform themselves (e.g., schedule a meeting, create spaces, start a call, add or remove participants from spaces, send and receive messages). Obviously “with great power comes great responsibility”, so a mechanism is required whereby the user can explicitly control the amount of power granted to the application. When a user adds an integration, they get to choose the sets of features, categorized as “scopes”, that the application will have permission to access on their behalf. An integration should only request the minimum set of scopes required to perform its task(s).

In our example, the “SuperProjectManager task updater” integration only requires a single scope: spark:messages_write.

End-user flow for using an integration

To add an integration, a user needs to give the application a Webex token that it can use on their behalf. We use a standard OAuth flow to achieve this goal.

The user flow starts by logging into the external application. In some application-specific way, the user chooses to connect it to Webex. When they do so, the application brings them to a Webex authorization page where they are prompted to log in and asked to approve the specific access that the integration has requested. In our example, in which “SuperProjectManager task updater” integration requests “spark:messages_write”, the user will be asked to allow the application to “Post and delete messages on your behalf”.

If the user grants their approval, they are redirected back to the application and the application is given an authorization code. The application exchanges the authorization code for tokens that it can use to interact with Webex “as the user”.

Find a more detailed explanation and walkthrough of the whole process at the developer site: https://developer.webex.com/blog/real-world-walkthrough-of-building-an-oauth-webex-integration.

A user can rescind the permission granted to an application at any time by visiting https://idbroker.webex.com/idb/profile#/tokens. The link is provided in the general settings page in the Webex apps.

If the integration is on App Hub, the user can also disconnect the integration by visiting the “My Webex Integrations” page on App Hub https://apphub.webex.com/my-integrations.

Developer flow for creating an integration

1.     Add the UI to your application to allow the user to connect it to Webex. This will initiate the OAuth flow described previously, bringing the user to https://webexapis.com/v1/authorize. The query includes, among other things, the redirect URI to pass the authorization code to.

2.     Add a handler to the application for receiving the authorization code at the redirect URI and to exchange it for refresh and access tokens: https://developer.webex.com/docs/integrations#getting-an-access-token

3.     Create the integration in https://developer.webex.com/my-apps/new/integration

Enter the basic details of the application, which include:

a.   The name of the integration

b.   An icon for the integration (the avatar)

c.   One or more redirect URIs for the application (step 2)

d.   The scopes that the application requires

4.     Add logic to the application that calls Webex APIs, using the access token to act on behalf of the user. As with the bot implementation, this can either be direct access to the Webex REST APIs or through the use of an SDK such as the Webex JS SDK.

5.     (Optional) Implement a webhook to register for notifications on behalf of the user. See description under the Bots section covered earlier in this paper.

6.     (Optional) Submit the integration to Webex App Hub: https://developer.webex.com/docs/app-hub-submission-process.

You can find detailed documentation on integrations at the Webex Developer site: https://developer.webex.com/docs/integrations.

Admin apps

Thus far, we have discussed mechanisms for your applications to interact directly with other Webex participants. You can also create application integrations that perform administrative tasks rather than interacting directly with other users. Some examples of the type of tasks an admin app can perform include:

1.     On-boarding (creating) or de-provisioning (deleting) Webex users

2.     Enforcing enterprise compliance rules (e.g., a Cloud Access Security Broker)

3.     Data loss protection (DLP)

From a technical perspective, an admin app is simply a sub-category of an integration. It is created and granted access in the same way as any other integration app. The key difference is that the tasks carried out by admin apps typically require special administrator or compliance officer permissions. The scopes required to call the APIs associated with these tasks (typically prefixed with “spark-admin:” or “spark-compliance:”) can only be delegated by admin or compliance users who have those permissions.

For further information about creating admin or compliance application integrations see:

     Admin API Guide: https://developer.webex.com/docs/api/guides/admin-api

     Compliance and Events API Guide: https://developer.webex.com/docs/api/guides/compliance

Cisco Webex App Hub

Publishing your bots and integrations so that others can find and use them

If you want to share your bots and integrations so that any Webex customer can discover them and start using them to bring your application’s features to their Webex users, you should consider submitting your bots and integrations for inclusion on Cisco Webex App Hub: https://apphub.webex.com/

Bots and integrations don’t have to be published on App Hub for your customers to use them. However, publishing does provide a good way for your customers to discover them and even for new customers to discover your applications.

There are some basic requirements for your bot or integration to be published on App Hub. Read the details of what’s required online: https://developer.webex.com/docs/app-hub-submission-process

Accessing the Webex collaboration platform features in your application

Cisco Webex JS SDK

The Cisco Webex JS SDK provides a convenient JavaScript abstraction that applications can use to interact with the Webex platform. As described earlier, it can be used in a server-based application on Node.js, such as those implementing a bot or an integration. It can also be used to develop a browser-based application. In fact, Cisco’s Webex Teams web application is implemented using the Webex JS SDK.

It provides access to a very broad set of Webex features, including:

     Scheduling and joining Webex audio and video meetings

     Calling other Webex app users

     Creating and joining spaces

     Adding and removing participants from spaces

     Sending and receiving rich messages

Getting ready to use the SDK

The Cisco Webex JS SDK can be found online at https://webex.github.io/webex-js-sdk/and includes detailed documentation.

The SDK is a collection of node modules you can use directly in your node application. To install it, use:

npm install –save webex

The Webex JS SDK is also fully browser compatible.

To use the SDK in a browser, you’ll need a bundle. We recommend using Browserify or webpack to create one. We also provide a pre-built, minified version of the SDK that you can find links to on Github: https://github.com/webex/webex-js-sdk#a-note-on-browser-usage.

Authentication

There are three mechanisms you can use to authenticate. The simplest thing to do to try out the SDK is to log into the https://developer.webex.com/ portal and grab an access token:

     Under REST API, API Reference, click on the link for any API and you should see an option to “Try it”.

     Once you click on “Try it” you’ll be taken to a screen where you’ll have the option of copying an access token, which will be valid for 12 hours from the time you logged into the developer portal. Figure 2 provides a screenshot of what it looks like.

Authorized access token screenshot

Figure 2.               

Authorized access token screenshot

     If you are running Node.js, you can simply create an environment variable with the developer portal access token. For example:
WEBEX_ACCESS_TOKEN=$YOUR_TOKEN_FROM_THE_PORTAL node index.js

In the browser, you can set it directly in code. For example:

// index.js

const webex = window.Webex.init({

  credentials: {

   access_token: `YOUR_TOKEN_FROM_THE_PORTAL`

  }

});

Clearly this is just to get you going locally. For production use, you’ll need to implement one of the other authentication mechanisms: the OAuth 2.0 implicit grant flow or the OAuth 2.0 authorization code grant flow. For both of these, you’ll need to register an OAuth client. You do that by following the steps for creating an integration described earlier in this paper (https://developer.webex.com/my-apps/new/integration). You can find more details on implementing the OAuth flows on the Webex resource site in Github: https://webex.github.io/webex-js-sdk/guides/browsers/.

Usage

The Webex JS SDK offers a very broad set of features through convenient APIs. For example, the API to create a new space is:

webex.rooms.create({ title: 'The best space ever!' })

Rather than go through a long list of API examples here, you can find full details at the SDK page: https://webex.github.io/webex-js-sdk/.

You can also find further documentation, including some handy samples, about using it in the browser at: https://developer.webex.com/docs/sdks/browser, and with Node.js at: https://developer.webex.com/docs/sdks/node.

Webex widgets

If you simply want to embed Webex messaging and video calling in your browser-based application, there’s an even easier path: you can simply use the ready-made Webex widgets Cisco provides (Figure 3).

Webex widgets provided by Cisco

Figure 3.               

Webex widgets provided by Cisco

There are two widgets available: the “space” widget and the “recents” widget. The widgets are built using React and Redux on top of the Webex JS SDK. They are stylable, so that you can have them fit in seamlessly with the rest of your application’s user interface.

Authentication

The authentication mechanisms for the widgets are the same as for the Webex JS SDK (OAuth 2.0 implicit grant and authorization code grant flows). Once again, you’ll need to create an OAuth client for your app by creating an integration (https://developer.webex.com/my-apps/new/integration) and will need to request the spark:all scope.

Space widget

The “space widget” provides the basic functionality you get in a Webex space. It includes:

     Audio and video calling

     Messaging

    Send and receive messages (including markdown, mentions, etc.)

    Send and receive files

    1:1 and group spaces

    Space participant list

Recents widget

The “recents widget” provides a list of recent conversations, including both group spaces and direct (1:1) spaces. It highlights unread spaces and provides hooks so that your application can be notified about incoming calls, messages, and membership changes (e.g., when a user is added to a space). It also provides a hook to tell your application when a space in the list has been selected. Your application can use that hook to switch the context of the space widget to the newly selected space.

iOS SDK

The iOS SDK allows you to enhance your iOS application with Webex platform features. Features that you can incorporate using the SDK include:

     Making and receiving audio and video calls / meetings

     Screen-sharing (send and receive)

     Creating, joining, and participating in spaces and teams

     Sending and receiving rich messages (html, markdown, mentions)

     Sending and receiving files

     Cisco Unified Communications Manager (UCM audio and video calls coming in version 3 (estimated for release early 2021)

The iOS SDK is written in Swift 5 and requires iOS 11 or later.

The easiest way to add the iOS SDK to your app is by using CocoaPods. You can find step-by-step instructions in the “Getting started guide” at the Webex developers site: https://developer.webex.com/docs/sdks/ios.

You can find full documentation of the iOS SDK at: https://webex.github.io/webex-ios-sdk/

Authentication

Once again, apps that use iOS SDK use the OAuth 2.0 authorization flow. To start, you’ll need to create an OAuth client for your app by creating an integration (https://developer.webex.com/my-apps/new/integration) and will need to request the spark:all scope.

Note:       With version 3 of the Webex iOS SDK (estimated for release in early 2021) we will add a new “Mobile Integration” app type that will simplify this step.

The SDK provides an OAuthAuthenticator class to handle the authentication flow for you:

let authenticator = OAuthAuthenticator(clientId: yourClientId,
clientSecret: yourClientSecret, scope: “spark:all”, redirectUri:
yourRedirectUri)

let webex = Webex(authenticator: authenticator)

The yourRedirectUri in this code can be a custom URL scheme or a universal link back to your app, e.g., “SuperProjectManagerApp:authRedirect”. To learn more about linking to your app, see the Apple developer article: https://developer.apple.com/documentation/xcode/allowing_apps_and_websites_to_link_to_your_content.

iOS push notifications

When an iOS app that is using the Webex iOS SDK is in the foreground, the SDK maintains a websocket to the Webex platform to receive inbound notifications, such as for inbound calls and messages. However, when your app is in the background or not running, it can’t keep the websocket open for notifications.

If your app needs to receive a notification while it is not in the foreground, you will need to implement a cloud-accessible service that can act as a gateway, receiving webhook notifications from Webex and relaying them to your iOS app via the Apple Push Notification service.

The iOS SDK provides an API to allow the app to create a webhook, specifying the URL of your service where Webex should send the notifications. For example, this code creates a webhook for when a user is mentioned in a new message in a space that they are in:

webex.webhooks.create(name: "New message mentioning me",

  targetUrl: "https://example.com/messagewebhook",

  resource: "messages",

  event: "created",

  filter: "mentionedPeople=me")

When your service receives a webhook notification on behalf of a client, it needs to forward the notification to any currently registered iOS devices for that user. The body of the webhook POST the service receives will contain a “createdBy” field that contains the Webex ID (personId) of the Webex user that created the webhook. Your service will need to map that to the device tokens for the instances of the app that the user has, and send notifications to them via APNs.

The resource, event, and filter parameters are passed through to the webhooks API. You can find more details of the valid values and how they are used in the Webhooks guide: https://developer.webex.com/docs/api/guides/webhooks.

Android SDK

The Android SDK allows you to enhance your Android application with Webex platform features. Features that you can incorporate using the SDK include:

     Making and receiving audio and video calls / meetings

     Screen-sharing (send and receive)

     Creating, joining, and participating in spaces and teams

     Sending and receiving rich messages (html, markdown, mentions)

     Sending and receiving files

     Cisco UCM audio and video calls, coming in version 3 (early 2021)

At the time of writing, the Android SDK—version 2.6.0—requires Android API Level 21 or later and is built with Android SDK Tools 27.

You can find a Getting Started guide for the Android SDK at: https://developer.webex.com/docs/sdks/android

The Android SDK can be found on GitHub at: https://github.com/webex/webex-android-sdk.

The full reference documentation for the SDK can be found at: https://webex.github.io/webex-android-sdk/

We provide a full demo app implementation that can be used as a convenient reference at: https://github.com/webex/webex-android-sdk-example.

Authentication

Apps that use Android SDK use the OAuth 2.0 authorization flow. To start, you’ll need to create an OAuth client for your app by creating an integration (https://developer.webex.com/my-apps/new/integration) and will need to request the spark:all scope.

Note:       With version 3 of the Webex Android SDK, estimated for release in early 2021, we will add a new “Mobile Integration” app type that will simplify this step.

The SDK provides an OAuthWebViewAuthenticator class to handle the authentication flow with a WebView for you:

OAuthWebViewAuthenticator authenticator = new
OAuthWebViewAuthenticator(yourClientId, yourClientSecret,
“spark:all”, yourRedirectUri);

The yourRedirectUri in this code should link back to your app. You can learn more about deep links in the Android developer documentation at: https://developer.android.com/training/app-links/deep-linking.

Android push notifications

Similar to iOS (see the earlier section on iOS push notifications), if you want your Android app that is using the Webex Android SDK to receive Google Firebase Cloud Messaging (FCM) notifications, you will need to implement a cloud-accessible service that acts as a gateway, receiving webhook events from Webex and relaying them to the users’ devices via FCM.

The Webex Android SDK provides a WebHookClient for this purpose:

webex.webhooks().create(…)

REST APIs

The various SDKs just described are ultimately abstractions or wrappers that internally consume the Webex platform’s REST APIs. Thus, the REST APIs offer all the Webex platform features that are available to developers.

Authentication

Almost all the APIs require that you supply an access token in the Authentication HTTP header. An access token is obtained using an OAuth 2.0 authorization code grant flow, the basic steps of which were covered in the earlier “Integrations” section. Alternatively, a guest token can be used to provide temporary access to the platform to non-subscribed users. Details on how to create guest tokens is covered in the “Guest Issuer” section later in this paper.

Getting started with the REST APIs

The details of the REST APIs are far too broad to cover in this document. They are well documented on the Webex developer portal at: https://developer.webex.com/docs/api/getting-started.

Each API is described in detail, with every request parameter, response field, and error code documented. Example requests and responses are also provided. You can even test the API directly in the portal. (See Figure 4.) Once you log in, the portal provides you with a temporary access token that is pre-populated in the request; all you have to do is enter any required values and hit the Run button.

Screenshot of how to test APIs within the Webex developer portal

Figure 4.               

Screenshot of how to test APIs within the Webex developer portal

Extending Webex collaboration features to non-Webex users

Guest issuer

So far, this paper has focused on scenarios where integrations, the Webex JS SDK, and the widgets are used with pre-existing Webex users. However, the Webex platform also supports a mechanism that can open the functionality to users who don’t have a Webex account: guest users.

A “guest issuer” application can generate a token to allow a temporary, unregistered user to interact with full, paid Webex users within your organization. This provides a great way for your application to allow its users to exchange messages with, or even have a video call, with your Webex users.

How does it work?

Guest tokens use the JSON Web Token (JWT) standard (https://www.rfc-editor.org/rfc/rfc8725.html).

The first step in creating a token is to create a new “Guest Issuer” app in the Webex developer portal at: https://developer.webex.com/my-apps/new/guest-issuer.

All you need to provide is a name, and in return, you will receive a “guest issuer ID” and a “shared secret”.

Your application then creates two pieces of JSON—a header and a payload. For our purposes, the header has fixed content:

{

  "typ": "JWT",

  "alg": "HS256"

}

The payload has four fields:

1.     “sub” – This is the unique user ID for the user of your application. It can only contain numbers, letters, and hyphens.

2.     “name” – This is the display name of the guest user. This is the name that other Webex users will see for the guest.

3.     “iss” – This is the “guest issuer ID” that you received when you created the guest issuer app.

4.     “exp” – This is the time on and after which the token will not be accepted. The time must be specified in “Unix time” (the number of seconds since 00:00:00 UTC on January 1, 1970, minus leap seconds).

For example:

{

  "sub": "super-hero-001",

  "name": "Bruce Wayne",

  "iss": "Y2lzY29zcGFyazovL3Vz…wMC1jZDk5ZDQ5YWE3YjA",

  "exp": "1606756250"

}

Both header and payload are then encoded (base64url), combined (concatenated, separated by a “.”), and hashed (HMACSHA256) using the “shared secret” you received when you created the guest issuer app. The result is a guest token that your application’s guest can use to interact with Webex users.

For full details on how to generate a guest token see the guest issuer documentation online at: https://developer.webex.com/docs/guest-issuer.

How does your application use a guest token?

Webex JS SDK

The Webex JS SDK provides an API for this purpose:

webex.authorization.requestAccessTokenFromJwt({jwt:
“the_guest_token”})

Widgets

The widgets can also be initialized directly with a guest token instead of an access token. For example, you can initialize the space widget as follows:

webex.widget(someElementForWidget).spaceWidget({

  guestToken: ‘the_guest_token’,

  destinationId: ‘the_space_id’,

  destinationType: ‘spaceId’});

Mobile SDKs

The iOS SDK provides a JWTAuthenticator to use in place of the OAuthAuthenticator:

   let authenticator = JWTAuthenticator()

   let webex = Webex(authenticator: authenticator)

   ...

   if !authenticator.authorized {

   authenticator.authorizedWith(jwt: yourJwt)

   }

Similarly, the Android SDK provides a similar JWTAuthenticator for this purpose.

REST APIs

If you want to use the REST APIs directly, you will need to exchange the guest JWT token for an access token. To do that, you need to POST to the following API with the guest token in the authorization header:

https://webexapis.com/v1/jwt/login

The response will contain the access token (“token”) and the amount of time in seconds until it expires (“expiresIn”). Note, unlike the JWT “exp” field, “expiresIn” is a duration, not a Unix time.

Learn more