Cisco Spark API with NodeJS: Getting Started

Last post I talked about getting started with Tropo’s NodeJS module. What I failed to mention is that there is also a Spark NodeJS Module. Using Spark with NodeJS is just as easy to work with and opens up a great deal of opportunities to integrate your work processes into communication channels in Spark.

But before we jump into code the best place to start is with the Spark Developer site. https://developer.ciscospark.com/.

There are a couple of reasons to visit the developer site besides the documentation for the various Spark API’s. Its also an easy way to grab your Spark access token so we can do some simple code examples without getting to hot and heavy with authentication. Once you login to the site on the far right click on your avatar to get your access token which we will need to do our first code samples.

image

Pretty simple so far. Now to make use of access token probably the easiest way is to set an environmental variable when you start your Node application from the terminal or cmd prompt. Below is the command to use to start you node app with your access token.

$CISCOSPARK_ACCESS_TOKEN=<your developer portal token> node ./server.js

Also don’t forget to install the NodeJS Cisco Spark Module. Check it out here https://www.npmjs.com/package/ciscospark. To install using npm:

$npm install ciscospark –save

One of the most basic examples is to request a list of rooms. I recently integrated an application I was building to log error output to a test Spark room but before I could do that I had to find out the room ID.  This simple example is a great way to do that.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// Fetch your 5 most recently created rooms
//
// Run with
// CISCOSPARK_ACCESS_TOKEN=<your developer portal token> node ./1-access-token.js

var ciscospark = require('ciscospark');
ciscospark.rooms.list({max: 5})
  .then(function(rooms) {
    console.log(rooms);
  })
  .catch(function(reason) {
    console.error(reason);
    process.exit(1);
  });

Using lodash we can then find the rooms you are after. In the example below we are call the Spark API to list our rooms and using using lodash to sort the JSON response to console log one room. If you haven't noticed yet the Spark Node SDK is making use of promises. Our examples are being kept pretty simple promises make working with the API a lot easier versus using callbacks.Also note our example uses a process.argv to access the command line and room name you enter when starting your node process. Also don’t forget your access token if you not authenticating using another method.

$CISCOSPARK_ACCESS_TOKEN=<your developer portal token> node ./server.js <room name>

If you

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
// Fetch your five most recently created rooms and log the first one with the title specified on the command line
//
// 1. Run npm install --save lodash
// 2. Run with
// node ./server.js <room name>

var lodash = require('lodash');

if (process.env.NODE_ENV !== 'production') {
  require('dotenv').config();
}

var ciscospark = require('ciscospark');
ciscospark.rooms.list({max: 5})
  .then(function(rooms) {
    var room = _.find(rooms, {title: process.argv[2]});
    console.log(room);
  })
  .catch(function(reason) {
    console.error(reason);
    process.exit(1);
  });

Our last example fetches the five last created rooms. Lets pause here for moment to cover that a little better. When you use the list rooms it calls your last created rooms not your last updated. Its an important distinction to make as you may have to pull a much larger list of rooms to get the room you require. Once we get our rooms we list the messages of the room with specified title.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// Fetch your five most recently created rooms and list the messages for the first room with the specified title
//
// Run with
// node ./server.js <room name>

var lodash = require('lodash');

if (process.env.NODE_ENV !== 'production') {
  require('dotenv').config();
}

var ciscospark = require('ciscospark');
ciscospark.rooms.list({max: 5})
  .then(function(rooms) {
    var room = _.find(rooms, {title: process.argv[2]});
    return ciscospark.messages.list({roomId: room.id});
  })
  .then(function(messages) {
    console.log(messages);
  })
  .catch(function(reason) {
    console.error(reason);
    process.exit(1);
  });

I hope you enjoyed our first look at the Spark SDK. Thanks to Ian Remmel for supplying the examples listed. Over the next few weeks and months I will be posting more examples of working with both Tropo and Spark SDK’s and API’s.

If you have built a Spark application let me know about it. I am excited to see what people are building in this exciting new era of communication API’s.

VoIPNorm

Going tropo with Cisco Tropo and NodeJS!

I have been working on a number of projects lately that have put me deep into API’s. Over the next few blog posts I am going to start sharing some of the stuff I have been up to with the new Spark API’s and also Tropo which has been around much longer. Both platforms are incredibly fun to work on experimenting with. While I make no claim as a software developer I will post code I have written hopefully not offending any real software developers out there.

For the last year or so I have been down the learning path of gaining some software development skills. This has not been easy. My purpose for these new skills is to be able to build prototypes and demonstrations for the use of Cisco’s API stack. Programming is a skill I have long thought I should have at least some ability in but to my dismay I never really knew where to start. So I took the traditional path of going to college. I won’t say it was a complete waste of time but after three or four programming classes I came to the realization that the University of Phoenix is not the right environment to learn programming. I can read a book and create crappy applications without paying $2K dollars a course on my own without UoP.

So after a lack lust UoP experience I was not sure what direction to head. I did have some web design skills but on the backend I was pretty sure learning another language outside of JavaScript was not what I was after. Luckily I have a peer that actually has extensive programming knowledge that suggested I take a look at NodeJS. He had been pushing me that way for a while but I was so engrossed in learning Java at the time I just never got around to it.

While I am not going to give a lesson on Node (there is already a ton of info on Node out there) most of the JavaScript code I have written or examples I will post on VoIPNorm are written for the Node framework. But before we head down that road let’s review:

What is Tropo?

From the FAQ on the website”":

With Tropo you can build nearly any voice application you can imagine, including speech-driven IVR, VoIP solutions and voice mashups. The code you write also works over text messaging. Check out our documentation and sample apps at: http://tropo.com/docs.

What to do first?

To get up and running in Tropo to develop your first app you will need to sign up for a developer account. Its pretty simple and painless. From there you can start either using the scripting engine to write some applications or dive right into using the WebAPI which once through the initial setup is a very powerful tool.

image

Topo has of course a bunch of examples in Node for use with the WebAPI (and other frameworks such as Ruby) on it documentation website. Some are a little dated but generally they all still function. Below is a basic answering a call on NodeJS using Tropo.


 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
var http = require('http');
var tropo_webapi = require('tropo-webapi');

var server = http.createServer(function (request, response) {
	
	var tropo = new TropoWebAPI();

	tropo.say("Welcome to Tropo!");
	
	response.end(TropoJSON(tropo));

}).listen(8000); 

To have this function you either need a working node server or some form of cloud container running Node. To make things easy Tropo does have its own NodeJS module that is available on NPM and examples on GitHub. If you are familiar with NPM its pretty simple to grab the module to install in your project:

~$ npm install tropo-webapi

If you plan to develop in Cloud9 to run your application from the cloud you will need a URL for your Tropo WebAPI app. Cloud9 gives you this which makes using Cloud9 a great way to develop Tropo applications. The Node workspace in Cloud9 uses the Express framework which is best to stick with the default template and strip out what you don’t need like SocketIO.

I am becoming a big fan of Cloud9 even though I still have NodeJS and Webstorm installed locally.

If you are looking to give Tropo a spin and are just after some simple demos using the Tropo Scripting API is a good place to start. The Scripting API is almost always where everyone starts out.

1
say("Welcome to Tropo!");

The JavaScript Tropo script example above produces the exact same results as the previous NodeJS example but of course you lose the flexibility of importing modules to extend Nodes functionality.

Tropo Scripting API versus WebAPI

Using the Scripting API is a great starting point but inevitably you will want to do more and link you application to other services such as Google, Box, Spark  and dare I say Slack or any other platform with API’s out there. The great thing is the Tropo WebAPI allows you to do that but it comes with doing more work to get a environment setup to start developing, but its worth it.

My environment for NodeJS with Tropo

I am using the following components/tools to develop with Tropo and NodeJS:

  • Cloud9 IDE using the NodeJS Express template. This is a great development environment with very little setup required. Each workspace you create in Cloud9 has its own unique URL which works well with Tropo.
  • Tropo WebAPI that is enabled for voice and SMS. To be enabled for outbound SMS Tropo requires you to lodge a ticket with their help desk. Just follow the process on the website.
  • Locally installed Webstorm IDE and NodeJS for quick development of utilities like a Google Places search or a ZIP code look up tool that you can embed in your Tropo application as you need them. Although Cloud9 is a great tool, sometimes you just need to build a small piece of code you will embed in a larger app later. I like using a local environment to do this.
  • Sublime Text is another handy tool I like to use although I am not an expert at using it. I know a lot of developers that like to work with Sublime instead of an IDE like WebStorm.

Of course my intent is not to build production like code (although in the future who knows) so your tools may vary but this is the tool set that got me working the fastest with NodeJS and Tropo. There are endless options though and I just noticed Visual Studio has a text editor that works with Node. So use what ever works for you if you already have some preferences.

I know with the explosion of API’s that are coming from Cisco and others in the industry that getting up to speed will be a steep learning curve. It was and still is for me which is why I am posting these lets get you started blog posts. I recognize that I am not a expert developer by any standard, I just stand on the shoulders of other that are. In saying that there are ways to do cool and fun projects without being a total dev geek. This is what I will be covering in follow up posts as I explore this myself. Feel free to post comments on code, tools or other things you find fun in the API space because there is a lot to learn and a million ways to do basically anything you can dream of.

VoIPNorm