SparkBot API¶

Submodules¶

sparkbot.core module¶

class sparkbot.core.SparkBot(spark_api, root_url=None, logger=None)¶

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

my_help_all()¶: Returns a markdown-formatted list of commands that this bot has. Command, meant to be called by a bot user. Called by a user by typing “help”, “help all”, or “help-all”.

my_help(commandline)¶: Returns the help of the command given in commandline. Command, meant to be called by a bot user. Calls my_help_all() if no command (“”) is given or is all. Called by a user by typing help.

command(command_strings=[], fallback=False)¶

Decorator that adds a command to this bot.

Parameters:

command_strings (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.

commandworker(json_data)¶

Called by the bottle app when a command comes in. Glues together the behavior of SparkBot.

Parameters:	json_data – The blob of json that Spark POSTs to the webhook parsed into a dictionary

remove_help()¶

Removes the help command from the bot

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

respond(spark_room, markdown)¶

Sends a message to a Spark 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

class sparkbot.core.Command(function)¶

Bases: object

Represents a command that can be executed by a SparkBot

Parameters:	function – The function that this command will execute. Must return a str.

classmethod 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(commandline=None, event=None, caller=None, callback=None, room_id=None)¶

Executes this command’s function

Executes this Command’s target function using the given parameters as needed. All parameters are required for normal function, named parameters are used for ease of understanding of the written code.

Parameters:

commandline – shlex.split()-processed list of tokens which make up the bot user’s message
event – The webhook event that was sent to us by Webex Teams
caller (ciscosparkapi.Person) – The Person who pinged the bot to start this process
callback – Function to be used as a callback. Command.create_callback() is used to turn this into a partial function, so the first argument of this function must be a Spark room ID that the bot author will expect to act on.
room_id – The ID of the room that the bot was called in

Returns:

str, the desired reply to the bot user

sparkbot.receiver module¶

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)¶

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

sparkbot.receiver.random_bytes(length)¶: Returns a random bytes array with uppercase and lowercase letters, of length length

sparkbot.commandhelpers module¶

Helpful additional functionality for commands to take advantage of

sparkbot.commandhelpers.check_if_in_org(organization, person)¶

Ensures that the given person is inside the desired organization

Parameters:	api – CiscoSparkAPI instance to query Spark with. organization – The ID of the organization to find this user in person – The person to check against the organization. Must be CiscoSparkAPI.Person.

sparkbot.commandhelpers.check_if_in_team(api, team_id, person)¶

Checks if a person is in a given team

Parameters:	api – CiscoSparkAPI instance to query Spark with. team_id – The ID of the team to check for person – The person to check against the team

sparkbot.commandhelpers.get_person_by_email(api, person_email)¶

Gets a person by e-mail

Parameters:	api – CiscoSparkAPI instance to query Spark with. person_email – The e-mail address of the person to search for.
Returns:	ciscosparkapi.Person of found person
Raises:	ValueError if person_email is invalid or does not return exactly one person
Raises:	TypeError if argument types are incorrect

sparkbot.commandhelpers.get_person_by_spark_id(api, person_id)¶

Gets a person by their Spark ID

Parameters:	api – CiscoSparkAPI instance to query Spark with. person_id – The person’s unique ID from Spark
Returns:	ciscosparkapi.Person of found person

sparkbot.commandhelpers.is_group(api, room)¶

Determines if the specified room is a group (multiple people) or direct (one-on-one)

Parameters:	api – CiscoSparkAPI instance to query Spark with. room – The room to check the status of. May be a CiscoSparkAPI Room or a Spark room ID as a string.
Returns:	True if the room is a group, False if it is not.

sparkbot.commandhelpers.mention_person(person)¶

Creates a “mention” for the specified person.

Parameters:	person – The person to mention (must be CiscoSparkAPI.Person)
Returns:	String with the format “<@personId:[personId]\|[firstName]>”

sparkbot.commandhelpers.minargs(numargs, commandline)¶: Ensures that you have more than [numargs] arguments in [commandline]

Module contents¶

A chatbot base that makes it super easy to interface with Cisco Spark