XML API DeprecationGetting StartedREST API BasicsComplianceWebhooksWebex APIs
Webex Assistant Skills
Full API Reference
API Changelog


Give Webex users access to outside services right from their Webex spaces. Bots help users automate tasks, bring external content into the discussion, and gain efficiencies.

Create a Bot

anchorBots Explained

Bots are similar to regular Webex users. They can participate in 1-to-1 and group spaces and users can message them directly or add them to a group space. A special badge is added to a bot's avatar in the Webex clients so users know they're interacting with a bot instead of a human.

A bot can only access messages sent to it directly. In group spaces, bots must be @mentioned to access the message. In 1-to-1 spaces, a bot has access to all messages from the user.

Bots do not, however, perform actions within Webex on behalf of a Webex user. If you're creating an application that needs to participate in Webex and perform actions with a user's account, check out Integrations.

anchorTypes of Bots

Bots come in all different shapes and sizes. Here are some ideas for a few different types of bots you can make:


Notifier bots typically respond to events in external services and post a summary in Webex. For example, a GitHub Bot may listen for commits on a particular repo and post the committer's name and comment into a Webex space set aside for this purpose. Or a Deal Bot that lives in an account-specific space and posts updates from a CRM along with relevant news about the company like a product launch or earnings report.


Controller bots act as a text-based remote control for external services. For example, a Jira Bot may allow software engineers and product managers to control or query information from the popular bug tracking system Jira, all from the comfort of a Webex space.

Controller bots are generally passive, waiting for someone in the room to issue a command. In group rooms, bots can only see messages in which they are mentioned (1:1 rooms bots can see all messages as they are automatically "mentioned"). Your users are required to mention the bot preceding the command like @jira find WEBSITE-22 where @jira is the bot's name.

Currently, the Webex SDKs do not support extracting commands from messages. You'll need to parse it out after the mention. Future versions of the Webex SDKs will have built-in support for commands. Keep your eyes on the blog for updates.


Virtual assistants are the holy grail of chatbots. At minimum, an assistant should understand natural language, allowing the user to ask it questions as they would to a human.

Recent advancements in NLP (Natural Language Processing) have made understanding natural language requests not only possible, but quite accessible to the average developer. Most notably, Google launched Google Cloud Natural Language API in the summer of 2016, providing syntax parsing, sentiment analysis and deep noun classification.

Responding to natural language is a good first step but a truly exceptional assistant bot will be conversational, using past interactions to contextualize the most recent query. This is a very complex problem domain; luckily there are companies like Dialogflow providing a conversational platform built specifically for bots.

anchorCreating a Webex Bot

Creating a Webex Bot is super easy. If you're logged in, select My Webex Apps from the menu under your avatar at the top of this page, click "Create a New App" then "Create a Bot" to start the wizard.

You'll be asked to provide some basic information about the bot: bot name, bot username, and an icon. These fields are end-user facing, so make them as descriptive as possible. Only the bot's first name will be shown when mentioned in messages, so try to avoid spaces in the bot name. The description will be shown to users if you submit your bot to the Webex App Hub.

Webex App Hub is not supported for Webex for Government (FedRAMP)

Once you've filled out the registration form click "Add Bot", and if everything goes smoothly you're all set! You'll be given an access token for the new bot. This access token will be used to authenticate your bot with the Webex REST API.

The bot's access token will only be displayed once. Make sure to scroll down on the confirmation page, copy the token and keep it somewhere safe. If you misplace it, you can always generate a new one by finding the bot in My Webex Apps and selecting "Regenerate Access Token" from the edit page.

anchorResponding to Events

After creating a bot, you can use its access token with the Webex REST APIs to perform actions as the bot, such as sending a message with an interactive card to someone. To respond to events within Webex, such as someone sending your bot a message or adding it to a group space, you'll need to configure webhooks. Webhooks will let you know when an activity has occurred so you can take action. Check out the Webhooks Guide for more information about configuring webhooks.

With cards, you can give your users even more ways to interact with your bot or service, right in the Webex clients. Use the Buttons and Cards Designer to quickly create and prototype cards for your bot. See the Buttons and Cards Guide for more information about cards.

anchorDifferences Between Bots and People

One key difference between Webex Bots and regular users is that, in group spaces, bots only have access to messages in which they are mentioned. This means that messages:created webhooks only fire when the bot is mentioned in a space.

Also, listing messages requires that you specify a special ?mentionedPeople=me query parameter.

In addition people have a personId that must be resolved via /people, bots have a Bot Id and a personId. The Bot Id is shown in the apps page and is usually only known to the developer. The bot's personId can be looked up via the bot's email address in /people.

GET /messages?mentionedPeople=me&roomId=SOME_INTERESTING_ROOM
Authorization: Bearer THE_BOTS_ACCESS_TOKEN
anchorBot Frameworks & Tools

There are several bot frameworks that can greatly simplify the bot development process by abstracting away the low-level communications with the Webex REST API, such as creating and sending API requests and configuring webhooks. Instead, you can focus on the building the interaction and business logic of your bot.

Flint is an open source bot framework with support for regex pattern matching for messages and more.

Botkit is a popular open source bot framework with advanced conversational support as well as integrations with a comprehensive array of natural language processing and storage providers. You can get started with Botkit by cloning the Webex Botkit Starter Kit.

The Cisco Webex Ambassador program has links to several more open source bot starter kits. Keep your eyes on our blog for updates and news about our community-supported tools!