This quick walkthrough is intended to give you a very simple Spark bot that responds to commands typed into a room with a few example responses – nothing too fancy, but easy to build on. The commands will be passed to the bot using mentions – so if I type into a room where the bot is a participant:
The bot will retrieve that command, process it, and send us back a message. We’ll go step by step from bot registration to code upload and testing.
Step 1: Create the Bot
To register a Bot, you’ll need to be logged in to Spark with a “real” user – each bot needs to be tied to an actual user account. Adding one is extra simple, however – just click here \and select “Create a Bot”; there’s only a couple fields to fill out:
Display Name is how you want the bot to show up in a room (like “Mr. Wayne”); Bot Username is the email address, since every Spark user is registered under an email – this should be similar to the Display Name, but it can be unique. Note that you are not populating the entire email – they will always end with @sparkbot.io, can’t make on with a gmail.com email or anything similar, so you’re just adding the prefix. The username prefix does need to be unique; if you don’t get a green check at the end of the @sparkbot.io reference, then the username was already taken. The Icon is the avatar for the bot, which will also show inside a room.
Once the bot is created, you’ll need to save the access token that is provided – keep it someplace safe. The token effectively never expires (it’s good for 100 years) but if you forget it, you’ll have to generate a new one. There’s no way to get it back.
Note: Because this is a bot, OAuth is not used in this process; no need to refresh tokens any specific period. Only time you’d need to do the regeneration is if you lose the token, as mentioned above.
Step 2: Add the Bot to a Room
Pick a room, any room! Either add the bot to a room you’re already in or have the bot create a new room using its access token – whatever you prefer. The bot just needs to be present in a room in order to read messages and send messages back to it.
Step 3: Create an Outbound Webhook
Your webhook URL needs to be accessible on the public Internet – if you want to use your local machine, you can use a service like Ngrok to make your personal machine accessible to the world on a specific port for free.
But that means the webhook only works when you machine is up and live. Alternatively, Amazon Web Services offers a free EC2 micro instance for 1 year and more professional tiers at varied pricing.
Once you have an endpoint to use, create the webhook using the request on this page.
Make sure that the bearer token used in creating the webhook is the bearer token of the bot. You’ll need to know the ‘roomId’ of the room the bot is hanging out in, and you’ll need to know your own ‘targetUrl’ (the Ngrok link or the AWS link in our examples above); you’ll also want to set the ‘resource’ to messages and the ‘event’ to created. Here’s what the Webhook should look like once it’s been created:
Check out the section in this link titled “Handling Requests from Spark” for more background info on webhooks.
Step 3b: The Code
The example webhook we just built sends all newly created messages in which the bot is mentioned to the server on port 10010 (all messages not directed to the bot are filtered out); we’ll use a simple Python program to handle them:
For each message that is sent (‘created’), the data that hits your server is in a JSON format, so parsing them is easy, thanks to the built-in ‘json’ python library. We have a ‘result’ object that has been JSON parsed and should contain a ‘text’ field, unless it’s something like an image someone posts in the Spark room. That means that we can now use the ‘text’ attribute of the result object to start looking for specific commands or messages! We want our bot to reply to a few commands, and everyone loves Batman, so how about these three:
Right after we print the result object, let’s add:
if'batman'in result.get('text', '').lower():
elif'batcave'in result.get('text', '').lower():
print"The Batcave is silent..."
elif'batsignal'in result.get('text', '').lower():
print"NANA NANA NANA NANA"
While it’s bat-tastic that our batbot can now recognize different commands, we want it to actually do something. Let’s have it reply to the Spark room if any of our three commands are found in the text of the Spark message. First, we’ll need a slightly different function (for HTTP POST), to send messages to a room. Add this below the “sendSparkGET” function:
With the above code added, we now have a reply to each of our commands! Even better, the use of our sendSparkPOST function passes the roomId of the room that issued the command, so we don’t have to worry about multiple webhooks from different rooms getting mixed up! To really make this bat worthy, we might want our functions to act a little differently from each other. Let’s have batcave echo the message, if any text is sent after batcave. For example, @MrWayne batcave Hello!, should send “Hello!” back to the room… and maybe we want the batsignal to really light up the Spark room with an image. Here’s the full code to make all the magic happen:
from itty import *
This method is used for:
-retrieving message text, when the webhook is triggered with a message
-Getting the username of the person who posted the message if a command is recognized
Don’t forget to fill in your Bot’s auth token above. For Mac and Linux systems, Python is installed by default. For Windows, it’s a pretty easy install, just make sure you look for version 2.7. To run the server application, open a command terminal, and navigate to the folder where you saved this Python script - we named ours bot_demo.py - then run:
As long as all of the right ports are available, you should see this in the terminal: