Webex Teams Markdown

Posted on  by admin
The information on this page pertains to the legacy version of Botkit, 0.7 and below and may be out of date! Documentation for the new v4+ version of Botkit can be found here.

Table of Contents

Note: Documentation for the legacy, pre-rebrand Cisco Spark version of Botkit is here.

Getting Started

  1. Create a Botkit powered Node app:

    • Or: Use the command line tool:

Teams and teamwork, together at last. Meet, create and communicate all in one platform designed to fit the way you work. The Cisco Webex App Hub is your hub to discover integrations and bots to use with the Cisco Webex Teams app. 4 different methods to remove Webex, both Webex Meetings and Webex Teams, including deleting an account and cleaning the registry afterwards.

Working with Webex

Botkit receives messages from the Cisco Webex cloud platform using webhooks, and sends messages using their APIs. This means that your bot application must present a web server that is publicly addressable. Everything you need to get started is already included in Botkit.

To connect your bot to Webex, get an access token here. In addition to the access token,Webex bots require a user-defined secret which is used to validate incoming webhooks, as well as a public_address which is the URL at which the bot application can be accessed via the internet.

Each time the bot application starts, Botkit will register a webhook subscription.Botkit will automatically manage your bot's webhook subscriptions, but if you plan on having multiple instances of your bot application with different URLs (such as a development instance and a production instance), use the webhook_name field with a different value for each instance.

Bots in Webex are identified by their email address, and can be added to any space in any team or organization. If your bot should only be available to users within a specific organization, use the limit_to_org or limit_to_domain options.This will configure your bot to respond only to messages from members of the specific organization, or whose email addresses match one of the specified domains.

The full code for a simple Webex bot is below:

Create a Controller

When creating the Botkit controller, there are several platform-specific options available.

Botkit.webexbot

ArgumentDescription
public_addressrequired the root url of your application (https://mybot.com)
access_tokenrequired token provided by Webex for your bot
secretrequired secret for validating webhooks originate from Webex
webhook_nameoptional name for webhook configuration on Webex side. Providing a name here allows for multiple bot instances to receive the same messages. Defaults to 'Botkit Firehose'
limit_to_orgoptional organization id in which the bot should exist. If user from outside org sends message, it is ignored
limit_to_domainoptional email domain (@howdy.ai) or array of domains [@howdy.ai, @botkit.ai] from which messages can be received

Webex Specific Events

All events listed here should be expected, in the format resource.event - for example, rooms.created.

In addition, the following custom Botkit-specific events are fired:

EventDescription
direct_messageBot has received a message as a DM
direct_mentionBot has been mentioned in a public space
self_messageBot has received a message it sent
user_space_joina user has joined a space in which the bot is present
bot_space_jointhe bot has joined a new space
user_space_leavea user has left a space in which the bot is present
bot_space_leavethe bot has left a space

Message Formatting

Webex supports both a text field and a markdown field for outbound messages. Read here for details on Webex's markdown support.

To specify a markdown version, add it to your message object:

Attaching Files

Files can be attached to outgoing messages in one of two ways.

Specify URL

If the file you wish to attach is already available online, simply specify the URL in the files field of the outgoing message:

Send Local File

If the file you wish to attach is present only on the local server, attach it to the message as a readable stream:

Receiving files

Your bot may receive messages with files attached. Attached files will appear in an array called message.data.files.

Botkit provides 2 methods for retrieving information about the file.

bot.retrieveFileInfo(url, cb)

ParameterDescription
urlurl of file from message.data.files
cbcallback function in the form function(err, file_info)

The callback function will receive an object with fields like filename, content-type, and content-length.

bot.retrieveFile(url, cb)

ParameterDescription
urlurl of file from message.data.files
cbcallback function in the form function(err, file_content)

The callback function will receive the full content of the file.

Teams

Starting Direct Messages

Webex's API provides several ways to send private messages to users -by the user's email address, or by their user id. These may be used in the case where theuser's email address is unknown or unavailable, or when the bot should respond to the actorinstead of the sender of a message.

For example, a bot may use these methods when handling a bot_space_join eventin order to send a message to the user who invited the bot (the actor) instead ofthe bot itself (the sender).

Webex Teams Markdown Software

NOTE: Core functions like bot.startPrivateConversation() work as expected,and will create a direct message thread with the sender of the incoming_message.

bot.startPrivateConversationWithPersonId()

ParameterDescription
personIdthe personId of the user to whom the bot should send a message
cbcallback function in the form function(err, file_content)

Use this function to send a direct message to a user by their personId, whichcan be found in message and event payloads at the following location:

bot.startPrivateConversationWithActor())

ParameterDescription
incoming_messagea message or event that has an actorId defined in message.original_message.actorId
cbcallback function in the form function(err, file_content)

Webex rebrand

Back in April 2018, Cisco announced a rebrand from Cisco Spark to Webex.In May 2018, starting with version 0.6.17, Botkit reflected this rebrand by updated 'Spark' mentions from the framework API.

For backward compatibility purposes, several references are now marked as deprecated, but still supported (except for Typescript code). Please migrate your code if your find references to:

  • Botkit.sparkbot() => Botkit.webexbot()
  • controller.config.ciscospark_access_token => controller.config.access_token: a warning shows up in the console if your code is still using this option.

Breaking changes

  • bot.type now equals 'webex' instead of 'ciscospark': there should not be any impact in your code.
  • the webhook HTTP endpoint automatically created and exposed by Botkit has been changed from '/ciscospark/receive' to '/webex/receive'. Note that this change can have an impact for the Webex Cloud platform to reach your bot if the traffic to your bot is routed by a reverse proxy. To avoid any bot to break, the Botkit Webex connector will expose an HTTP endpoint with the deprecated '/ciscospark/receive' path if the 'ciscospark_access_token' configuration property is detected.

Webex Teams Markdown Tutorial

Is something missing or out of date?

This file is managed on Github. click here to view the source, and send us a pull request with your improvements!

Incoming webhooks let you post messages in Webex Teams spaces when an event occurs in another service that supports webhooks. Webhook events trigger in near real-time allowing your Webex Teams spaces to stay in sync with events happening outside of Webex Teams.

Webex Teams Markdown

To use incoming webhooks, simply connect this integration to your Webex Teams account, create a new webhook below, and configure your service to post messages to the provided URL. The incoming webhook URL expects an HTTP request with a JSON payload which includes the message in either a plaintext field or Markdown-formatted field.

Webex Teams Markdown Strikethrough

To send a plaintext message, make an HTTP POST to the URL and provide the message body in the text field of the request:

curl -X POST -H 'Content-Type: application/json' ∖
-d '{'text' : 'This is a message from a Cisco Webex Teams incoming webhook.'}' ∖ ''>https://api.ciscospark.com/v1/webhooks/incoming/<incoming_webhook_url>'

Webex Teams Markdown Emoji

To send a formatted message, make an HTTP POST to the URL and provide the message body (in Markdown format) in the markdown field:

curl -X POST -H 'Content-Type: application/json' ∖
-d '{'markdown' : 'This is a formatted message from a Cisco Webex Teams incoming webhook.'}' ∖ ''>https://api.ciscospark.com/v1/webhooks/incoming/<incoming_webhook_url>'.

Webex Teams Microsoft Edge

See our Webex Teams for Developer documentation about formatting messages for more examples of how you can create richly-formatted messages in Webex Teams.