API Documentation

This page contains information about SparkBot’s internals. Bot authors may not find it terribly useful, SparkBot hackers will.

SparkBot

class sparkbot.SparkBot(spark_api, root_url=None, logger=None, skip_receiver_setup=None, custom_receiver_resources={})

Bases: object

A bot for Cisco Webex Teams

SparkBot automatically creates a webhook for itself and will delete any other webhooks on its bot account. To do this, it uses the root_url parameter or WEBHOOK_URL in the environment to know its public URL.

SparkBot has a help command built in by default. These may be overridden using the command() decorator and providing the “help” argument and a function with your desired behavior on calling help. See Writing Commands for more information on writing commands.

Parameters:
  • spark_api (ciscosparkapi.CiscoSparkAPI) – CiscoSparkAPI instance that this bot should use
  • root_url (str) – The base URL for the SparkBot webhook receiver. May also be provided as WEBHOOK_URL in the environment.
  • logger (logging.Logger) – Logger that the bot will output to
  • skip_receiver_setup ("all", "webhook") – Set to “all” or “webhook” to skip setting up a receiver when instancing SparkBot. “all” skips creating the receiver and the webhook. “webhook” creates a receiver but does not register a webhook with Webex Teams.
  • custom_receiver_resources – dict containing custom resources for the receiver. Pass a dict of Falcon resource(s) with the endpoint you would like them hosted at as the key. For example, {"/my_endpoint": EndpointResource} will serve EndpointResource at /my_endpoint.
my_help_all()

Returns a markdown-formatted list of commands that this bot has. This function is used by the default “help” command to show the full list.

my_help(commandline)

Returns the help of the command given in commandline. Calls my_help_all() if no command is given or is all. Called by a user by typing help. This function is the default “help” command and can be removed using remove_help().

command(command_strings=[], fallback=False)

Decorator that adds a command to this bot.

Parameters:
  • command_strings (list or str) – Callable name(s) of command. When a bot user types this (these), they call the decorated function. Pass a single string for a single command name. Pass a list of strings to give a command multiple names.
  • fallback (bool) – False by default, not required. If True, sets this command as a “fallback command”, used when the user requests a command that does not exist.
Raises:
  • CommandSetupError – Arguments or combination of arguments was incorrect. The error description will have more details.
  • TypeError – Type of arguments was incorrect.
command_dispatcher(user_request)

Executes a command for the user’s request.

This method is called by the receiver when a command comes in. It uses the information in the user_request to execute a command (using execute_command()) and send its reply back to the user.

Parameters:user_request (ciscosparkapi.WebhookEvent) – Event where the user called the bot
create_callback(respond, room_id)

Pre-fills room ID in the function given by respond

Adds the room ID as the first argument of the function given in respond, simplifying the ‘callback’ experience for bot developers.

Parameters:
  • respond – The method to add the room ID to
  • room_id – The ID of the room to preset in respond
execute_command(command_str, **kwargs)

Runs the command given by ‘command_str’ if it exists with the possible arguments in **kwargs.

Note that execute_command is “dumb”. It does not enforce the return type of a command function. It will happily return anything that the bot writer’s command does. Contrast to command_dispatcher() which checks whether a command (executed by this function) returns either a Generator or a str.

Parameters:
  • command_str (str) – The ‘command’ that the user wants to run. Should match a command string that has previously been added to the bot.
  • commandline (list) – The user’s complete message to the bot parsed into a list of tokens by shlex.split().
  • event (ciscosparkapi.WebhookEvent) – ciscosparkapi.WebhookEvent object describing the request causing this command.
  • caller (ciscosparkapi.Person) – The user who sent the message we’re processing.
  • room_id (str) – The ID of the room that the message we’re processing was sent in.
Keyword Arguments:
 

Each keyword argument sent here will be used as a possible argument for commands. For example, the keyword argument commandline= will allow a command function (the ones defined with command()) to take an argument by the name commandline. The current list can be found at List of recognized keywords.

If a logger is defined, SparkBot will raise a warning if an argument is requested but not provided by the kwargs given to this function. This means that there is either a typo in the argument on the command function or command_dispatcher() has failed to do its job correctly (the first is more likely).
remove_help()

Removes the help command from the bot

This will remove the help command even if it has been overridden.

send_message(spark_room, markdown)

Sends a message to a Teams room.

Parameters:
  • markdown – Markdown formatted string to send
  • spark_room – The room that we should send this response to, either CiscoSparkAPI.Room or str containing the room ID

Default receiver

The receiver waits for a request from Webex Teams and executes sparkbot.SparkBot.command_dispatcher() when one comes in.

class sparkbot.receiver.ReceiverResource(bot)

Bases: object

on_post(req, resp)

Receives messages and passes them to the sparkbot instance in BOT_INSTANCE

sparkbot.receiver.create(bot, **kwargs)

Creates a falcon.API instance with the required behavior for a SparkBot receiver.

Currently the API webhook path is hard-coded to /sparkbot

Parameters:bot – sparkbot.SparkBot instance for this API instance to use
Keyword Arguments:
 Additional arguments may be used to specify more resources that should be exposed by the SparkBot receiver. For example, "/my_webhook"=[Falcon resource] will expose your Falcon resource at /my_webhook on the server.
sparkbot.receiver.random_bytes(length)

Returns a random bytes array with uppercase and lowercase letters, of length length