webex-js-sdk

Greenkeeper badge

npm
license
Build status

The Cisco Webex JS SDK

Upgrading from Cisco Spark to Webex?

This is a monorepo containing all officially maintained Cisco Webex JS SDK modules in the same repo.
webex is a collection of node modules targeting our external APIs.

Install

We test against the Active LTS (Long Term Support) version of Node.js and use npm@6 to run security audits.

To install the latest stable version of the SDK from NPM:

npm install --save webex

Usage

To use the SDK, you will need Cisco Webex credentials. If you do not already have a Cisco Webex account, visit
Cisco Webex for Developers to create your account and retrieve your access token.

See the detailed docs for more usage examples.

const Webex = require(`webex`);
const webex = Webex.init({
  credentials: {
    access_token: <your webex access token>
  }
});

// Create a room with the title "My First Room"
// Add Alice and Bob to the room
// Send a **Hi Everyone** message to the room
webex.rooms.create({ title: `My First Room` }).then(room => {
  return Promise.all([
    webex.memberships.create({
      roomId: room.id,
      personEmail: `alice@example.com`
    }),
    webex.memberships.create({
      roomId: room.id,
      personEmail: `bob@example.com`
    })
  ]).then(() =>
    webex.messages.create({
      markdown: `**Hi Everyone**`,
      roomId: room.id
    })
  );
});

A note on browser usage

We provide a built, minified version of the SDK, that includes window.Webex. You can access it via unpkg or jsdelivr.

<!-- unpkg -->
<script crossorigin src="https://unpkg.com/webex/umd/webex.min.js"></script>
<!-- jsdelivr -->
<script crossorigin src="https://cdn.jsdelivr.net/npm/webex/umd/webex.min.js"></script>

If you're already using a bundler (like Webpack or Rollup) you can simply import/require the package and use the above snippet and assign the initialized webex variable to window.webex.

For a quick example, we'll use Parcel to bundle the SDK for a website. For any more information and questions on how to use Parcel, please head to their website.

  1. Create index.js.
import { init as initWebex } from 'webex';

// Initialize the SDK and make it available to the window
const webex = (window.webex = initWebex({
  credentials: {
    access_token: <your webex access token>
  }
}));

// Create a room with the title "My First Room"
webex.rooms
  .create({
    title: 'My First Room!'
  })
  .catch((error) => {
    console.error(error);
  });

// Filter for "My First Room" from the last 10 rooms
webex.rooms
  .list({
    max: 10
  })
  .then((rooms) => {
    // Destructure room properties for its id (aliased to roomId) and title
    const { id: roomId, title } = rooms.items.filter(
      room => room.title === 'My First Room!'
    )[0];

    // Post message "Hello World!" to "My First Room!"
    webex.messages.create({
      roomId,
      text: 'Hello World!'
    });

    // Log the the room name and the message we created
    return webex.messages
      .list({ roomId, max: 1 })
      // Destructure promised value to get the text property from the first item in items array
      .then(({ items: [{ text }] }) =>
        console.log(`Last message sent to room "${title}": ${text}`)
      );
  })
  .catch((error) => {
    console.error(error);
  });
  1. Create index.html .
<html>
  <head>
    <title>Webex SDK for Browsers</title>
  </head>
  <body>
    <script src="./index.js"></script>
  </body>
</html>
  1. Add a compatible browser version for parcel to compile for
  • Add the browserlist property to your package.json. We're using the last two versions of both Chrome and Firefox in this example
"browserslist": [
  "last 2 Chrome versions"
  "last 2 Firefox versions"
]

NOTE: This is needed for parcel to correctly compile dependencies the SDK uses for the browser environment. The SDK uses the last 2 versions of Chrome and Firefox, so we're including it here too. You can use browserl.ist to configure your own setup

  1. Run parcel index.html in your terminal.
  2. Go to http://localhost:1234 and open the developer console to see the output.

Still using webex/env or ciscospark/env?

Samples

Sample code can be found in docs/samples. You can demo them by going to webex.github.io/webex-js-sdk/samples/ or you can run them yourself by following this guide in the Contribution Guide

Samples Hosted
Samples code webex.github.io/webex-js-sdk/

FedRAMP Environment

The webex JavaScript SDK is officially supporting FedRAMP environments.

To enable usage simply use the fedramp configuration setting when creating your webex instance:

const Webex = require('webex');
const webex = Webex.init({
  config: {
    fedramp: true,
  },
  credentials: {
    access_token: `<token>`,
  },
});

// Use sdk as normal
webex.rooms.list().then(console.log);

For more information on FedRAMP visit https://developer.webex.com/docs/fedramp-overview

Features that do not work in FedRAMP

  • Creating Guest tokens aka JWT tokens (not SDK limitation but environment limitation)

Contribute

Pull requests welcome. Please see CONTRIBUTING.md for more details about building the packages
and submitting pull requests for suggested changes.

Issues

Please reach out to our developer support team for any issues you may be experiencing with the SDK.

License

© 2016-2020 Cisco and/or its affiliates. All Rights Reserved.

See LICENSE for details.

View code on GitHub
  • Owner

  • Contributors

    +30Github contributors
  • Categories

  • Products

    Webex
  • Programming Languages

    JavaScript
  • License

    Other

Code Exchange Community

Get help, share code, and collaborate with other developers in the Code Exchange community.View Community
Disclaimer:
Cisco provides Code Exchange for convenience and informational purposes only, with no support of any kind. This page contains information and links from third-party websites that are governed by their own separate terms. Reference to a project or contributor on this page does not imply any affiliation with or endorsement by Cisco.