How to Create a Cisco Webex Bot Account and Send Messages with TypeScript

Introduction

In this article, I will introduce how to create a Cisco Webex Teams Bot account and provide sample code for implementing a process to send messages to a room from Node.
In this industry, many might use Slack as a communication tool, but Cisco Webex related services are also very convenient as they include features like video conferencing and calling.

What is Cisco Webex Teams in the first place?

• Reference: Cisco Webex Teams

Below is a quote:

Whether on the go, at a desk, or in a meeting room, Webex Teams helps speed up projects, strengthen relationships, and solve business challenges. It provides all the team collaboration tools needed to keep work moving and integrates with the other tools you use to simplify your work.

In short, it is a type of communication tool.
Since it is often confused with Microsoft's Teams, it is sometimes referred to as Webex Teams without abbreviation.

Just like Slack, you can create Bot accounts and customize them freely.

Bot Creation Procedure

Let's jump right into creating a Bot account.

Prerequisites

The following tasks are assumed to be completed:

• Creation of a Teams account

Log in to the Developer Site

Access Cisco Webex for Developers.
The following screen will be displayed, so log in using Log in at the top right of the screen.

Create a New App

In Cisco Webex Teams, Bots, OAuth authentication applications, etc., are managed collectively in the form of an App.
Since the goal this time is "Bot creation," click the My Webex Apps menu at the top right to transition to the App list screen.

By clicking the Create New App button at the top of the list screen, you will be asked what type of App you want to create (see the figure below).

Select Create Bot in the center here.

Enter Bot Information

Next, enter the information regarding the Bot.

Information required for input is as follows:

• Bot Name: Bot name (Japanese)
• Bot Username: The name specified when mentioning (ends with @webex.bot)
• Icon: Icon (select from default or a JPEG or PNG of 512px square)
• Description: Overview

Once input is complete, click Add Bot at the bottom of the screen to create the Bot.

Obtain Access Token

If created successfully, the following will be displayed.

What is displayed here is the "Access Token" string required when using the Bot.
Preparation for using the Bot is now complete.

Implementation

Next, we will send a message to a target room using the Bot account.
Message sending is performed using the REST API.

• Reference: Cisco Webex for Developers

Installing Axios

We will use axios to communicate with the API this time.
axios is a well-known HTTP client library that runs on Node.js.

• Reference: GitHub | axios

Install it with the following command:

yarn add axios

Obtaining the Target Room ID

Before implementing the actual sending process, we will obtain the target room ID for sending.
In Webex Teams, both one-on-one messages and group messages are managed in units called rooms.

Room retrieval is done via the /rooms endpoint.
Also, since this endpoint only retrieves rooms where the Bot is participating, make sure to add the Bot to the target room.
*In the case of a one-on-one room, you need to not only add it but also send a message as shown in the figure below.

import axios from 'axios';

// Teams Bot access token
const TEAMS_BOT_ACCESS_TOKEN = "【Access token obtained earlier】";

// Start processing
(async () => {
  axios
    .get("https://api.ciscospark.com/v1/rooms", {
      headers: {
        "Content-Type": "application/json",
        Authorization: "Bearer " + TEAMS_BOT_ACCESS_TOKEN,
      },
    })
    .then((res) => {
      // res.data contains an array of room information the Bot is participating in
      if (res.data.items && res.data.items.length > 0) {
        res.data.items.forEach((room) => {
          console.log(`Room Name: ${room.title}, Room ID: ${room.id}`);
        });
      }
    });
})();

When executed, the room information where the Bot is participating will be output to the console as follows.
Choose and note down your preferred room ID from this list.

Room Name: AAA, Room ID: 【Room ID for AAA】
Room Name: BBB, Room ID: 【Room ID for BBB】
Room Name: CCC, Room ID: 【Room ID for CCC】

Sending a Message to the Target Room ID

Next, we will send a message to the target room.
Message sending is performed using the /messages endpoint.

Webex Teams allows the use of markdown in messages.

import axios from 'axios';

// Teams Bot access token
const TEAMS_BOT_ACCESS_TOKEN = "【Access token obtained earlier】";
// Teams destination room ID
const TEAMS_ROOM_ID = "【Target room ID】";

// Start processing
(async () => {
  
  let markdown = `# markdown is available \r\n`;
  markdown += `You can write \r\n`;
  markdown += `**like this**`;
  
  // Notify Teams
  axios.post(
    "https://api.ciscospark.com/v1/messages",
    {
      roomId: TEAMS_ROOM_ID,
      markdown: markdown,
    },
    {
      headers: {
        "Content-Type": "application/json",
        Authorization: "Bearer " + TEAMS_BOT_ACCESS_TOKEN,
      },
    }
  );
})();

Upon execution, a message from the Bot account arrived in the target room as shown below.

Summary

In this article, I introduced everything from creating a Cisco Webex Teams Bot account to implementing message sending to a room.
As a more advanced application, you can also build an interactive Bot using Webhooks.

In any case, the source code provided this time is just a base; the key lies in what kind of messages you send from the Bot.
For example, there are many potential uses, such as "notifying daily tasks" or "integrating with something like GitHub to notify commits or merge requests."

If there are any regular users of Cisco Webex Teams, I hope this article proves useful.