sparkbot-starterkit v0.8.0
Yet Another Unofficial StarterKit to create Cisco Spark bots in NodeJS
A minimal NodeJS Starter Kit to create your own Spark bot, with few dependencies and goal to keep them at a minimum (Express that's it). Started after @CiscoDevNet SmartCity Paris and @TADHack London hackathons, to bootstrap dev teams in minutes.
Note that the StarterKit implements both Cisco Spark webhooks mecanisms: REST webhook and incoming integrations (see below for details). Moreover, the StarterKit allows to implement both simultaneously for ultimate flexbility.
New to Cisco Spark ?
- Spark is Cisco's Cloud Collaboration Services, which unifies team collaboration for the enterprise,
- start with the Web Client (signup, enjoy the free chat service, with end to end securiy and integrated video).
Looking for a more advanced Spark Bot Engine ? check Nick Marus's flint and quickstart.
Quick start
Create a Cisco Spark "Outgoing Webhook" integration pointing to https://myawesomebot.localtunnel.me/integration and run the following commands on your local machine.
# In a bash shell
> npm install sparkbot-starterkit
> cd sparkbot-starterkit
> node tests/no-config.js
no configuration => starting up as an incoming integration...
Cisco Spark bot started on port: 8080
# In a second bash shell
> npm install -g localtunnel
> lt -s myawesomebot -p 8080
your url is: http://myawesomebot.localtunnel.meStart an incoming integration Bot
Create the myfirstbot.js file below or pick an example from directory.
var SparkBot = require("sparkbot-starterkit");
// Starts a Webhook as an incoming integration, listening at :8080/integration
var bot = new SparkBot();
// This function will be called every time a new message is posted into Spark
bot.register(function(message) {
//
// ADD YOUR CUSTOM CODE HERE
//
console.log("New message from " + message.personEmail + ": " + message.text)
});You're all set, let's run your sparkbot
# if you are running OSX
> sudo npm install express sparkbot-starterkit
# if you are running Windows
> npm install express sparkbot-starterkit
# launch your spark bot, default to port 8080
# note: your cisco spark token can be retreived by clicking on your account picture (upper right corner of the [developer documentation](https://developer.ciscospark.com/getting-started.htm))
> node myfirstbot.js
No configuration => starting up as an incoming integration...
Cisco Spark bot started on port: 8080
# open a second console and check your bot is running by hitting your sparkbot health resource:
# open in a web browser http://localhost:8080/ping/
# or use a back command such as curl, [httpie](https://github.com/jkbrzt/httpie), or [bat](https://github.com/astaxie/bat)
# OSX note: if localhost doesn't work for you, try 127.0.0.1
> curl http://localhost:8080/ping/
{"message":"Congrats, your bot is up and running","since":"2016-07-06T23:20:50.296Z","integrationURI":"/integration","webhookURI":null}Start a REST webhook Bot
Create the myfirstbot.js file below or pick an example from directory.
var SparkBot = require("sparkbot-starterkit");
var config = {
/// Cisco Spark API token, note that it is mandatory for webhooks to decode new messages
token: process.env.SPARK_TOKEN,
webhookURI: "/webhook"
};
// Starts a Webhook as an incoming integration, listening at :8080/integration
var bot = new SparkBot(config);
// This function will be called every time a new message is posted into Spark
bot.register(function(message) {
//
// ADD YOUR CUSTOM CODE HERE
//
console.log("New message from " + message.personEmail + ": " + message.text)
});You're all set, let's run your sparkbot
# if you are running OSX
> sudo npm install express sparkbot-starterkit
# if you are running Windows
> npm install express sparkbot-starterkit
# launch your spark bot, default to port 8080
# note: your cisco spark token can be retreived by clicking on your account picture (upper right corner of the [developer documentation](https://developer.ciscospark.com/getting-started.htm))
> SPARK_TOKEN=XXXXXXXXXXXXX node myfirstbot.js
Cisco Spark bot started on port: 8080
# open a second console and check your bot is running by hitting your sparkbot health resource:
# open in a web browser http://localhost:8080/ping/
# or use a back command such as curl, [httpie](https://github.com/jkbrzt/httpie), or [bat](https://github.com/astaxie/bat)
# OSX note: if localhost doesn't work for you, try 127.0.0.1
> curl http://localhost:8080/ping/
{"message":"Congrats, your bot is up and running","since":"2016-07-06T23:33:15.535Z","integrationURI":null,"webhookURI":"/webhook"}How to expose your bot to the Web
# if you're running your bot on a private network, install localtunnel
> npm install -g localtunnel
# launch a tunnel and expose your http://localhost:8080 endpoint
# note1: maje sure top choose a name that will not collide with another bot developer !
# note2: once you'll have your bot successfully setup, you'll may want to run localtunnel forever:
# ex: while true; do lt -s sparkbot -p 8080; done
> lt -s sparkbot -p 8080
your url is: https://sparkbot.localtunnel.me
# check everything is running ok by hitting your sparkbot health resource
# open in a web browser https://sparkbot.localtunnel.me/ping/
# or use a back command such as curl, [httpie](https://github.com/jkbrzt/httpie), or [bat](https://github.com/astaxie/bat)
> curl -v -X GET https://sparkbot.localtunnel.me/ping
* ...
* NPN, negotiated HTTP1.1
* ...
* SSL connection using TLSv1.2 / ECDHE-RSA-AES256-GCM-SHA384
* ...
HTTP/1.1 200 OK
{
"message":"Congrats, your bot is up and running",
"isWebhook":true,
"isIntegration":false,
"URI":"http://localhost:8080/webhook"
}How to attach your bot to a Spark room
CiscoSpark defines 2 types of webhooks:
- HTTP webhooks : receive all events fired by a Spark Room, 'NewMessage' is the only event fired as of April 2016 (more coming),
- outgoing integrations : receive new message events fired by a Spark Room.
The bot proposed by the StarterKit proposes 2 endpoints /webhook and /integration so that you can pick one or another way to attach the bot to a Spark Room.
to attach a REST Webhook to a Spark Room:
Attaching a REST webhook to a Spark room is explained in the Cisco Spark developer documentation
Quick setup:
- lists your rooms, choose one, pick its room id,
- add a webhook with a filter for the roomId above, and with a targetUrl pointing to your /webhook endpoint, ex: https://sparkbot.localtunnel.me/webhook.
Take DevNet Learning lab for a step by step tutorial.
to attach an Outgoing integration to a Spark Room:
Outgoing integrations can be created directly from the Cisco Spark web client. Note: you may also use the REST API /webhooks/outgoing resource.
Quick setup:
- launch the Web client,
- pick a Room, look for the integrations pane on the right,
- create a new integration of type "outgoing webhook" with a targetUrl pointing to your bot /integration URI, ex: https://sparkbot.localtunnel.me/integration.
Troubleshooting
For debugging purpose, you may want to use a WebAPI Traffic inspector.
If you're looking for options, Windows users generally use Fiddler.
Linux and Mac users may give a try to smartproxy: an experimental #golang traffic capture tool.
https://sparkbot.localtunnel.me
<-internet->
http://localhost:9090
<-lan->
:8080Simply pick a binary for your platform, and run through these following steps.
// download a Windows exe or Mac / Linux binary, set as executable, launch
> mv smartproxy.mac smartproxy
> chmod 755 smartproxy
> ./smartproxy --capture
// by default smartproxy routes traffic from localhost:9090 to localhost:8080
// the capture option let you to see incoming traffic
// launch a tunnel to local port 9090
> lt -s sparkbot -p 9090
// your bot is now exposed publically at https://sparkbot.localtunnel.me/
// launch your bot, defaults to port 8080
> SPARK_TOKEN=XXXXXXXXXX node server.js
// chat in the spark room
// now examine traffic by opening http://localhost:9090/traffic with a web browser
// select an HTTP request/response
// look at the smartproxy console to get the request and response payloads