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.jsno 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 8080your url is: http://myawesomebot.localtunnel.me
Start 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/integrationvar bot = new SparkBot();// This function will be called every time a new message is posted into Sparkbot.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.jsNo 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 messagestoken: process.env.SPARK_TOKEN,webhookURI: "/webhook"};// Starts a Webhook as an incoming integration, listening at :8080/integrationvar bot = new SparkBot(config);// This function will be called every time a new message is posted into Sparkbot.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.jsCisco 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 8080your 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->:8080
Simply 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