Node Cisco Spark Client

node-sparkclient is node Cisco Spark module. It provides a simple way to work with the Cisco Spark APIs

Installation

npm install node-sparkclient

Usage

This module assumes you have received an access token from the Cisco Spark Oauth2 service.

The Cisco Spark Client Library Functions

Pagination

All list api function calls support pagination. To get the next page of results, simply call the specific list function with 'next' as the first parameter. Examples below.

Create the Spark Client object

CiscoSparkClient(accessToken)

    var sparkClient = new CiscoSparkClient('Kjc0YTA5MWUtZTJlYi00NzNhLWI2NGQtYzAxOGJkZjat27ZlMzZkY2U2OWQtNTdi')

Room Functions

Rooms are virtual meeting place where people post messages and collaborate to get work done. This API is used to manage the rooms themselves.

CiscoSparkClient.listRooms(maxRooms, callback)

    sparkClient.listRooms(10, function(err, rooms) {
        if (!err) {
            for (i=0;i<rooms.items.length;i++) {
                console.log(rooms.items[i].id)
                console.log(rooms.items[i].title)
                console.log(rooms.items[i].created)
                console.log(rooms.items[i].lastActivity)
            }
            //get the next 10 rooms
            sparkClient.listRooms("next", function(err, rooms) {
                //do something else here
                for (i=0;i<rooms.items.length;i++) {
                    console.log(rooms.items[i].id)
                    console.log(rooms.items[i].title)
                    console.log(rooms.items[i].created)
                    console.log(rooms.items[i].lastActivity)
                }
            })
        }
    })

CiscoSparkClient.createRoom(title, callback)

    sparkClient.createRoom("My New Room", function(err, room) {
        if (!err)
            console.log(room.id)
            console.log(room.title)
            console.log(room.created)
    })

CiscoSparkClient.updateRoom(roomId,title, callback)

    sparkClient.updateRoom("Y2lzY29zcGFyazovL3VzL1JPT00vY2ZjNmY5NzAtYTAzNi0xMWU1LWJlOGYtODVmMTM2MmM4YWZk", "New Title", function(err, room) {
        if (!err)
            console.log(room.id)
            console.log(room.title)
            console.log(room.created)
    })

CiscoSparkClient.getRoom(roomId, callback)

    sparkClient.getRoom("Y2lzY29zcGFyazovL3VzL1JPT00vNDAyNjRhZjAtOWVlYy0xMWU1LTkwOGEtODUyZTZhOGJlMTBh", function(err, room) {
        if (!err)
            console.log(room.id)
            console.log(room.title)
            console.log(room.created)
            console.log(room.lastActivity)
    })

CiscoSparkClient.deleteRoom(roomId, callback)

    sparkClient.deleteRoom("Y2lzY29zcGFyazovL3VzL1JPT00vNDAyNjRhZjAtOWVlYy0xMWU1LTkwOGEtODUyZTZhOGJlMTBh", function(err, response) {
        if (!err)
            console.log(response.message)
    })

Message Functions

Messages are how we communicate in a room. In Spark, each message is displayed on its own line along with a timestamp and sender information. Use this API to list, create, and delete messages.

CiscoSparkClient.listMessages(roomId, [queryParams], callback)

    queryParams = {}  // Query Parameters are optional
    queryParams.before = '2015-12-11T22:44:10.511Z'
    queryParams.beforeMessage = 'Y2lzY29zcGFyazovL3VzL01FU1NBR0UvYjFjYjExZjAtYTA1OC0xMWU1LThjYTUtZjc1OTUwNjk2NzZk'
    queryParams.max = 10
 
    sparkClient.listMessages("Y2lzY29zcGFyazovL3VzL1JPT00vZjcwZjQ0ODAtYTA1Ny0xMWU1LTg4MTktODNkODA5ZDZlZjc2", queryParams, function(err, messages) {
        if (!err)
            for (i=0;i<messages.items.length;i++) {
                console.log(messages.items[i].id)
                console.log(messages.items[i].roomId)
                console.log(messages.items[i].personId)
                console.log(messages.items[i].personEmail)
                console.log(messages.items[i].created)
                console.log(messages.items[i].text)
                //If Spark message contains files, messages.items[i].files will be an array of URLs to the document(s) in that message
                //Like in the Spark client, a user can only access file URLs for documents in rooms they are a member of
                if (messages.items[i].files) {
                    for (x=0;x<messages.items[i].files.length;x++) {
                        fileURL = messages.items[i].files[x]
                        console.log(fileURL)
                    }
                }
            }
             //support for pagination
             sparkClient.listMessages("next",function(err,messages){
                // do something here
             })
    })

CiscoSparkClient.createMessage(personOrRoomId, messageText, [messageParams], callback)

If creating a message is successful, a response object will be returned containing the message parameters returned above for listMessages

    messageParams = {}  // Message Parameters are optional
    messageParams.file = 'https://web.ciscospark.com/images/logo_spark_256px.png'  // The file to attach to the message.  
 
    //You can also directly upload a file by passing in a file buffer, in which case the returned Spark response will include the file ID. When directly uploading a file you must specify a filename.
 
    var data = fs.readFileSync('document.xlsx');
    messageParams.file = data
    messageParams.filename = 'My uploaded file.xlsx'
 
    //To set the type of your messageText to HTML or Markdown set messageParams.html messageParams.markdown to true.  If both are set, message will be sent as markdown.
    //messageParams.html = true
 
    // for a direct 1:1 message just use the users email address as the first parameter or person id
    sparkClient.createMessage('marfeder@cisco.com', 'Hello!', messageParams, function(err, response) {
        if (!err)
            console.dir(response.id)
    })
 
    // or send to a room by using the room id as the first parameter
    sparkClient.createMessage('Y2lzY29zcGFyazovL3VzL1JPT00vZjcwZjQ0ODAtYTA1Ny0xMWU1LTg4MTktODNkODA5ZDZlZjc2', 'Hello!', messageParams, function(err, response) {
            if (!err)
                console.dir(response.id)
        })

CiscoSparkClient.getMessage(messageId, callback)

    sparkClient.getMessage("Y2lzY29zcGFyazovL3VzL01FU1NBR0UvYjEzN2Y5YjAtYTA1OC0xMWU1LThjYTUtZjc1OTUwNjk2NzZk", function(err, message) {
        if (!err) {
            console.log(message.id)
            console.log(message.roomId)
            console.log(message.personId)
            console.log(message.personEmail)
            console.log(message.created)
            console.log(message.text)
            //If Spark message contains files, message.files will be an array of URLs to the document(s) in that message
            //Like in the Spark client, a user can only access file URLs for documents in rooms they are a member of
            if (message.files) {
                for (x=0;x<messages.files.length;x++) {
                    fileURL = messages.files[x]
                    console.log(fileURL)
                }
            }
        }
   })

CiscoSparkClient.deleteMessage(messageId, callback)

    sparkClient.deleteMessage("Y2lzY29zcGFyazovL3VzL01FU1NBR0UvYjEzN2Y5YjAtYTA1OC0xMWU1LThjYTUtZjc1OTUwNjk2NzZk", function(err, response) {
        if (!err)
            console.log(response.message)
    })

CiscoSparkClient.getFile(fileURL, callback)

    // Get fileInfo and fileData from a file URL returned by the getMessage function.  fileInfo is a JSON object containing the fileName, contentType, and contentLength in bits.  fileData is a buffer object containing the unencoded binary data.
    sparkClient.getFile("https://api.ciscospark.com/v1/contents/Y2lzY29zcGFyazovL3VzL0NPTlRFTlQvMDVmOGMwNDAtNDFiNy0xMmY1LTc0NDctOWM3ZTQ5M2U2MzJiLzA", function (err, fileInfo, fileData) {
    	if (!err) {
            console.log(fileInfo.fileName)
            console.log(fileInfo.contentType)
            console.log(fileInfo.contentLength)
            path = './'+fileInfo.fileName
            fs.writeFile(path,filedata, function(err){
                if (err) throw err;
                console.log('Saved file to '+path)
            })
        }
    })

CiscoSparkClient.getFileInfo(fileURL, callback)

    // To save bandwidth and performance, get information about a file without actually retrieving the file.  Requires a file URL returned by the getMessage function or from an inbound Webhook.  JSON object containing the fileName, contentType, and contentLength in bits.
    sparkClient.getFileInfo("https://api.ciscospark.com/v1/contents/Y2lzY29zcGFyazovL3VzL0NPTlRFTlQvMDVmOGMwNDAtNDFiNy0xMmY1LTc0NDctOWM3ZTQ5M2U2MzJiLzA", function (err, filename) 
    {
    	if (!err) {
    		console.log(fileInfo.fileName)
            console.log(fileInfo.contentType)
            console.log(fileInfo.contentLength)
    	}
    })

People Functions

People are registered users of the Spark application. Currently, people can only be searched with this API.

CiscoSparkClient.listPeople(emailOrName, [maxResults], callback)

sparkClient.listPeople("marcello",2,function(err,people){
     if (!err)
          for (i=0;i<people.items.length;i++) {
            console.log(people.items[i].id)
            console.log(people.items[i].emails)
            console.log(people.items[i].displayName)
            console.log(people.items[i].avatar)
            console.log(people.items[i].created)
 
          }
 
        //support for pagination
        sparkClient.listPeople("next",function(err,people){
           // do something here
        })
 
})

CiscoSparkClient.getPerson(personId, callback)

sparkClient.getPerson("Y2lzY29zcGFyazovL3VzL1BFT1BMRS83M2YwNThiZS01MTRjLTQ5OTAtYTkyZi00MWNlY2M4NWFiMzc", function(err, person) {
    if (!err) {
         console.log(person.id)
         console.log(person.emails)
         console.log(person.displayName)
         console.log(person.avatar)
         console.log(person.created)
    }
})

CiscoSparkClient.getMe(callback)

sparkClient.getMe(function(err, me) {
    if (!err) {
         console.log(me.id)
         console.log(me.emails)
         console.log(me.displayName)
         console.log(me.avatar)
         console.log(me.created)
    }
})

Membership Functions

Memberships represent a person's relationship to a room. Use this API to list members of any room that you're in or create memberships to invite someone to a room. Memberships can also be updated to make someone a moderator or deleted to remove them from the room. Just like in the Spark app, you must be a member of the room in order to list its memberships or invite people.

CiscoSparkClient.listMemberships(roomId, [queryParams], callback)

queryParams = {}  // Query Parameters are optional
queryParams.max = 10
 
// refine the search by personId or personEmail
// queryParams.personId = 'Y2lzY29zcGFyazovL3VzL1BFT1BMRS83M2YwNThiZS01MTRjLTQ5OTAtYTkyZi00MWNlY2M4NWFiMzc'
// queryParams.personEmail = 'marfeder@cisco.com'
 
sparkClient.listMemberships("Y2lzY29zcGFyazovL3VzL1JPT00vZjcwZjQ0ODAtYTA1Ny0xMWU1LTg4MTktODNkODA5ZDZlZjc2", queryParams, function(err, memberships) {
    if (!err)
        for (i=0;i<memberships.items.length;i++) {
            console.log(memberships.items[i].id)
            console.log(memberships.items[i].personId)
            console.log(memberships.items[i].personEmail)
            console.log(memberships.items[i].roomId)
            console.log(memberships.items[i].isModerator)
            console.log(memberships.items[i].isMonitor)
            console.log(memberships.items[i].created)
        }
        //support for pagination
        sparkClient.listMemberships("next",function(err,memberships){
           // do something here
        })
 
})

CiscoSparkClient.createMembership(roomId, emailOrId, isModerator, callback)

 
// You can add a person to a room with only their email address
sparkClient.createMessage(Y2lzY29zcGFyazovL3VzL1JPT00vZjcwZjQ0ODAtYTA1Ny0xMWU1LTg4MTktODNkODA5ZDZlZjc2,'marfeder@cisco.com', false, function(err, response) {
    if (!err)
        console.dir(response.message)
})
 
// or you can add a person to a room with their id
sparkClient.createMessage('Y2lzY29zcGFyazovL3VzL1JPT00vZjcwZjQ0ODAtYTA1Ny0xMWU1LTg4MTktODNkODA5ZDZlZjc2', 'Y2lzY29zcGFyazovL3VzL1BFT1BMRS83M2YwNThiZS01MTRjLTQ5OTAtYTkyZi00MWNlY2M4NWFiMzc', false, function(err, response) {
     if (!err)
        console.dir(response.message)
})

CiscoSparkClient.getMembership(membershipId, callback)

 
sparkClient.getMembership("Y2lzY29zcGFyazovL3VzL01FTUJFUlNISVAvNzNmMDU4YmUtNTE0Yy00OTkwLWE5MmYtNDFjZWNjODVhYjM3OmY3MGY0NDgwLWEwNTctMTFlNS04ODE5LTgzZDgwOWQ2ZWY3Ng", function(err, membership) {
    if (!err) {
         console.log(membership.id)
         console.log(membership.personId)
         console.log(membership.personEmail)
         console.log(membership.roomId)
         console.log(membership.isModerator)
         console.log(membership.isMonitor)
         console.log(membership.created)
    }
 
})

CiscoSparkClient.updateMembership(membershipId, isModerator, callback)

sparkClient.updateMembership("Y2lzY29zcGFyazovL3VzL01FTUJFUlNISVAvNzNmMDU4YmUtNTE0Yy00OTkwLWE5MmYtNDFjZWNjODVhYjM3OmY3MGY0NDgwLWEwNTctMTFlNS04ODE5LTgzZDgwOWQ2ZWY3Ng", true, function(err, membership) {
    if (!err)
         console.log(membership.id)
         console.log(membership.personId)
         console.log(membership.personEmail)
         console.log(membership.roomId)
         console.log(membership.isModerator)
         console.log(membership.isMonitor)
         console.log(membership.created)
})

CiscoSparkClient.deleteMembership(membershipId, callback)

sparkClient.deleteRoom("Y2lzY29zcGFyazovL3VzL01FTUJFUlNISVAvNzNmMDU4YmUtNTE0Yy00OTkwLWE5MmYtNDFjZWNjODVhYjM3OmY3MGY0NDgwLWEwNTctMTFlNS04ODE5LTgzZDgwOWQ2ZWY3Ng", function(err, response) {
    if (!err)
        console.log(response.message)
})

Team Functions

Teams are groups of people with a set of rooms that are visible to all members of that team. This API is used to manage the teams themselves. Teams are created and deleted with this API. You can also update a team to change its team, for example. Teams are by design "moderated" and the user creating a Team is automatically a moderator. To administer a team through this API you must be a moderator of that team.

To manage people in a team, see the Team Membership API functions. To manage team rooms, see the Room API functions.

CiscoSparkClient.listTeams(maxTeams, callback)

    sparkClient.listTeams(5, function(err, teams) {
        if (!err) {
            for (i=0;i<teams.items.length;i++) {
                console.log(teams.items[i].id)
                console.log(teams.items[i].name)
                console.log(teams.items[i].created)
            }
            //get the next 5 teams
            sparkClient.listTeams("next", function(err, teams) {
                //do something else here
                for (i=0;i<teams.items.length;i++) {
                    console.log(teams.items[i].id)
                    console.log(teams.items[i].name)
                    console.log(teams.items[i].created)
                }
            })
        }
    })

CiscoSparkClient.createTeam(name, callback)

    sparkClient.createTeam("My New Team", function(err, team) {
        if (!err)
            console.log(team.id)
            console.log(team.name)
            console.log(team.created)
    })

CiscoSparkClient.updateTeam(teamId,name, callback)

    sparkClient.updateTeam("Y2lzY29zcGFyazovL3VzL1RFQU0vMTIyY2dkYTEtNDMyOC0xMmU2LTlmYTgtNjE2NWNhMmNhNDU5", "New Team Name", function(err, team) {
        if (!err)
            console.log(team.id)
            console.log(team.name)
            console.log(team.created)
    })

CiscoSparkClient.getTeam(teamId, callback)

    sparkClient.getTeam("Y2lzY29zcGFyazovL3VzL1RFQU0vMTIyY2dkYTEtNDMyOC0xMmU2LTlmYTgtNjE2NWNhMmNhNDU5", function(err, team) {
        if (!err)
            console.log(team.id)
            console.log(team.name)
            console.log(team.created)
    })

CiscoSparkClient.deleteTeam(teamId, callback)

    sparkClient.deleteTeam("Y2lzY29zcGFyazovL3VzL1RFQU0vMTIyY2dkYTEtNDMyOC0xMmU2LTlmYTgtNjE2NWNhMmNhNDU5", function(err, response) {
        if (!err)
            console.log(response.message)
    })

Team Membership Functions

Similarly to how room memberships function, users can also be members of a team. Use this API to list members of any team that you're in, or create memberships to add someone to a team. Memberships can also be updated to make someone a moderator or deleted to remove them from the team.

Just like in the Spark app, you must be a member of the team in order to list its memberships or invite people.

CiscoSparkClient.listTeamMemberships(teamId, [queryParams], callback)

 
// Query Parameters are optional to refine the search or set max results
// queryParams.max = 10
 
queryParams = {}  
queryParams.max = 5
 
sparkClient.listTeamMemberships("Y2lzY29zcGFyazovL3VzL1RFQU0vMTIyY2dkYTEtNDMyOC0xMmU2LTlmYTgtNjE2NWNhMmNhNDU5",queryParams, function(err, teamMemberships) {
    if (!err)
        for (i=0;i<teamMemberships.items.length;i++) {
            console.log(teamMemberships.items[i].id)
            console.log(teamMemberships.items[i].teamId)
            console.log(teamMemberships.items[i].personId)
            console.log(teamMemberships.items[i].personEmail)
            console.log(teamMemberships.items[i].personDisplayName)
            console.log(teamMemberships.items[i].isModerator)
            console.log(teamMemberships.items[i].created)
        }
        //support for pagination
        sparkClient.listTeamMemberships("next",function(err,teamMemberships){
            //Do something with next results
            if (!err) {
                for (i=0;i<teamMemberships.items.length;i++) {
                    
                    console.log(teamMemberships.items[i].id)
                    console.log(teamMemberships.items[i].personDisplayName)
                }
            }
           
        })
 
})

CiscoSparkClient.createTeamMembership(roomId, emailOrId, isModerator, callback)

 
//You can add a person to a team with only their email address
sparkClient.createTeamMembership("Y2lzY29zcGFyazovL3VzL1RFQU0vZWE3MjdmMTAtNTQ1ZS0xMWU2LTljMjAtZjc2N2Y3ZTY3ZGE1","marfeder@ciscospark.com", true, function(err, response) {
    if (!err)
        console.log(response.id)
        console.log(response.teamId)
        console.log(response.personId)
        console.log(response.personEmail)
        console.log(response.personDisplayName)
        console.log(response.isModerator)
        console.log(response.created)
})
 
// or you can add a person to a room with their id
sparkClient.createTeamMembership("Y2lzY29zcGFyazovL3VzL1JPT00vZjcwZjQ0ODAtYTA1Ny0xMWU1LTg4MTktODNkODA5ZDZlZjc2", "Y2lzY29zcGFyazovL3VzL1BFT1BMRS83M2YwNThiZS01MTRjLTQ5OTAtYTkyZi00MWNlY2M4NWFiMzc", false, function(err, response) {
     if (!err)
        console.dir(response.message)
})

CiscoSparkClient.getTeamMembership(membershipId, callback)

//Get a specific Team Membership
sparkClient.getTeamMembership("Y2lzY29zcGFyazovL3VzL1RFQU1fTUVNQkVSU0hJUC9kOTMyNGE3MS00MmQ3LTQyYjUtOGI3Zi03MWM1MTY3NTY2ZWY6ZWE3MjdmMTAtNTQ1ZS0xMWU2LTljMjAtZjc2N2Y3ZTY3ZGE1", function(err, membership) {
    if (!err) {
        console.log(membership.id)
        console.log(membership.teamId)
        console.log(membership.personId)
        console.log(membership.personEmail)
        console.log(membership.personDisplayName)
        console.log(membership.isModerator)
        console.log(membership.created)
    }
})

CiscoSparkClient.updateTeamMembership(membershipId, isModerator, callback)

//Update a users team membership to set and/or remove moderator privileges
sparkClient.updateTeamMembership("Y2lzY29zcGFyazovL3VzL1RFQU1fTUVNQkVSU0hJUC9kOTMyNGE3MS00MmQ3LTQyYjUtOGI3Zi03MWM1MTY3NTY2ZWY6ZWE3MjdmMTAtNTQ1ZS0xMWU2LTljMjAtZjc2N2Y3ZTY3ZGE1", false, function (err, membership) {
    if (!err) {
        console.log(membership.id)
        console.log(membership.teamId)
        console.log(membership.personId)
        console.log(membership.personEmail)
        console.log(membership.personDisplayName)
        console.log(membership.isModerator)
        console.log(membership.created)
    }
})

CiscoSparkClient.deleteTeamMembership(membershipId, callback)

//Remove a user from a team
sparkClient.deleteTeamMembership("Y2lzY29zcGFyazovL3VzL1RFQU1fTUVNQkVSU0hJUC9kOTMyNGE3MS00MmQ3LTQyYjUtOGI3Zi03MWM1MTY3NTY2ZWY6ZWE3MjdmMTAtNTQ1ZS0xMWU2LTljMjAtZjc2N2Y3ZTY3ZGE1", function(err, response) {
    if (!err)
        console.log(response.message)
})

Webhook Functions

Webhooks allow your app to be notified via HTTP when a specific event occurs on Spark. For example, your app can register a webhook to be notified when a new message is posted into a specific room. Events trigger in near real-time allowing your app and backend IT systems to stay in sync with new content and room activity.

CiscoSparkClient.listWebhooks(max, callback)

sparkClient.listWebhooks(5, function(err, webhooks) {
    if (!err)
        for (i=0;i<webhooks.items.length;i++) {
            console.log(webhooks.items[i].id)
            console.log(webhooks.items[i].name)
            console.log(webhooks.items[i].resource)
            console.log(webhooks.items[i].event)
            console.log(webhooks.items[i].targetUrl)
            console.log(webhooks.items[i].filter)
        }
        //support for pagination
        sparkClient.listWebhooks("next",function(err,webhooks){
           // do something here
        })
 
 
})

CiscoSparkClient.createWebhook(name, target, roomId, [webhookParams], callback)

sparkClient.createWebhook("MyNewWebhook", "https://www.tpcal.me/post", "Y2lzY29zcGFyazovL3VzL1JPT00vZjcwZjQ0ODAtYTA1Ny0xMWU1LTg4MTktODNkODA5ZDZlZjc2", function(err,webhook){
       if (!err) {
           console.log(webhook.id)
           console.log(webhook.name)
           console.log(webhook.resource)
           console.log(webhook.event)
           console.log(webhook.targetUrl)
           console.log(webhook.filter)
       }
})

CiscoSparkClient.getWebhook(webhookId, callback)

sparkClient.getWebhook("Y2lzY29zcGFyazovL3VzL1dFQkhPT0svNDY3ODBhMTUtNTg1Yy00OWQ1LTkyOGYtZWRhMDEwZDIwNzcx", function(err, webhook) {
       if (!err) {
           console.log(webhook.id)
           console.log(webhook.name)
           console.log(webhook.resource)
           console.log(webhook.event)
           console.log(webhook.targetUrl)
           console.log(webhook.filter)
       }
})

CiscoSparkClient.updateWebhookfunction(webhookId, name, target, callback)

sparkClient.updateWebhook("Y2lzY29zcGFyazovL3VzL1dFQkhPT0svNDY3ODBhMTUtNTg1Yy00OWQ1LTkyOGYtZWRhMDEwZDIwNzcx","NewName","https://www.tpcall.me/newpost", function(err, webhook) {
       if (!err) {
           console.log(webhook.id)
           console.log(webhook.name)
           console.log(webhook.resource)
           console.log(webhook.event)
           console.log(webhook.targetUrl)
           console.log(webhook.filter)
       }
})

CiscoSparkClient.deleteWebhook(webhookId, callback)

sparkClient.deleteWebhook("Y2lzY29zcGFyazovL3VzL1dFQkhPT0svNDY3ODBhMTUtNTg1Yy00OWQ1LTkyOGYtZWRhMDEwZDIwNzcx", function(err, response) {
    if (!err)
        console.log(response.message)
})

node-sparkclient