DevNet 1056 WIT Spark API and Chat Bot Workshop

Editor's Notes

• #6: Tessa Mero Adrienne Moherek
• #7: What is DevNet? DevNet is Cisco’s developer program created about 3 years ago. Our purpose is to provide developers with the tools, the resources, and the code they need to build innovative, network-enabled solutions. We go to programming events and all types of conferences to show you how to use some of Cisco’s APIs. We absolutely love getting attention on @CiscoDevNet. A wonderful colleague of mine is amazing at her social media work on all of our DevNet accounts. She gets excited when you tweet at her. Even more excited if you ask for stickers!
• #10: From progammable web…. For decades, most computer software--programs that provide data like contact information or functionality like image editing--has been conceived and written with one type of user in mind: a human. No matter what chain of events is taking place under the hood of software, a human user is traditionally at the end of that chain. That end user invariably consumes that data and/or functionality through a user interface (UI)—one that’s designed to make the act of consumption as easy and even enjoyable as possible.  But what if that same data and/or functionality could be just as easily consumed by another piece of software? In this case, the UI concerns are very different. After all: Software doesn’t have eyes, emotions or intuition, so it doesn’t need an enjoyable, intuitive graphical user interface. However, as with a UI tailored to humans, software needs an interface that makes it easy to consume data and/or functionality. Enter, application programming interfaces, or APIs.  An API is geared for consumption by software, which is why APIs are often explained in the mainstream media as a technology that allows applications (software programs) to talk to one another. In this context, the terms “application,” “software,” “machines” and “computers” are virtually interchangeable. For example, APIs are often discussed as being machine-readable interfaces (versus human-readable). 
• #11: From progammable web…. For decades, most computer software--programs that provide data like contact information or functionality like image editing--has been conceived and written with one type of user in mind: a human. No matter what chain of events is taking place under the hood of software, a human user is traditionally at the end of that chain. That end user invariably consumes that data and/or functionality through a user interface (UI)—one that’s designed to make the act of consumption as easy and even enjoyable as possible.  But what if that same data and/or functionality could be just as easily consumed by another piece of software? In this case, the UI concerns are very different. After all: Software doesn’t have eyes, emotions or intuition, so it doesn’t need an enjoyable, intuitive graphical user interface. However, as with a UI tailored to humans, software needs an interface that makes it easy to consume data and/or functionality. Enter, application programming interfaces, or APIs.  An API is geared for consumption by software, which is why APIs are often explained in the mainstream media as a technology that allows applications (software programs) to talk to one another. In this context, the terms “application,” “software,” “machines” and “computers” are virtually interchangeable. For example, APIs are often discussed as being machine-readable interfaces (versus human-readable). 
• #12: But what about when the user is another software system? The software returns results via the API and the Software asks for data or takes action by interacting with the API.
• #14: Why are API’s so important? Most companies today have several different software they need to use, including sales, accounting, CRM, a project management system, etc. To have the software all work together is becoming a more important thing for both synergy and financial reasons and is making tasks much easier for work processes. They can also create their own tool to enhance their software, making their customers happier. QUESTION: What is your favorite app?
• #15: As you can see that the amount of API’s out has exponentially increased over time. In 2016, there has been more than 50 million API requests made and 30,000 available API’s out there. From 2015 to 2016, it has doubled in growth from 15,000 to 30,000 and only exponentially increasing.
• #18: Imagine what life might be like without such a standard. For example, with no plug, matching socket or standard particulars (often called specifications), we might have to hard-wire appliances into the walls of buildings. This would involve gathering the required tools, unsheathing all the wires and splicing the wires together. Of course, we would also need to know something about the wires coming out of the wall. Moving an appliance from one location to another would be a major undertaking in disconnection and reconnection. Note: Just give an example of what it’s like to have one tool and not the other , when it only works with both combined.
• #20: QUESTION: What other apps use Google Maps? Think about the way Yelp, for instance, displays nearby restaurants on a Google Map in its app APIs do all this by “exposing” some of a program’s internal functions to the outside world in a limited fashion. That makes it possible for applications to share data and take actions on one another’s behalf without requiring developers to share all of their software’s code.  APIs simplify all that by limiting outside program access to a specific set of features—often enough, requests for data of one sort or another. Feel free to think of them as doors, windows or levers if you like. Whatever the metaphor, APIs clearly define exactly how a program will interact with the rest of the software world APIs make possible a sprawling array of Web-service “mashups,” in which developers use mix and match APIs from the likes of Google or Facebook or Twitter to create entirely new apps and services. In many ways, the widespread availability of APIs for major services is what’s made the modern Web experience possible. APIs are often referred to as an engine of innovation.
• #23: When your browser visits a web server, it comes back with a prepared html from the requested page.
• #24: So you make a request and you get an http response. QUESTION: Is a 200 OK responses good or bad?
• #25: Here are some common HTTP status codes that you will get when you request a web page. When you make a request with an API, you also get a response back with a status code. Usually you will be hoping for 200 OK.
• #26: It’s simple: Your App and Their App requesting data to and from each other.
• #27: You can have your app ask for a list of “Spark Rooms”. Cisco Spark will prepare a list of rooms and send it back to you.
• #28: Then your response will come back as 200 OK and you’ll see the list of Spark rooms successfully from the API provider.
• #30: GET – get POST – create PUT – update DELETE – delete Your app will use one of these methods for each request
• #31: QUESTION: Who is familiar with HTTP? REST is an easy to use architectural style that uses HTTP. If you are familiar with HTTP then you practically already know REST. It is independent of programming languages. So you can use Python, JavaScript, Java, etc. Use REST APIs to build web apps or mobile apps and even bots.
• #34: Alright, now that we have skimmed through the major parts of a REST API, let’s do the fun hands on stuff Who here has Spark account already Setup?
• #35: QUESTION: Who has used Spark? Part of Cisco Collaboration tool , single unified experience With Spark you can call message or meet. The beauty about spark messaging is it is encrypted end to end. Each room has its own certificate. Not to mention all messages are persistent which makes it easier to search and look for information The most important thing, Spark has an API . And this is why we are here
• #36: Spark API has the capability to interact with people , memberships , rooms , messages, teams and for automation and bot creation webhook. If you would like to learn more about Spark API outside of this session, visit the learning labs in the DevNet Zone We have 3 different Spark Learning Labs that are tailored to take you from pulling basic room/people information all the way to creating a webhook and app integration. Highly recommend to come see us there
• #37: Here are the different areas you can use “Get, POST, PUT, DELETE” methods. You can work with People, Rooms, Memberships, Messages, Teams, and work with webhooks. Now, let’s work with a few of these! QUESTION: What method is missing in /Messages?
• #39: From progammable web…. For decades, most computer software--programs that provide data like contact information or functionality like image editing--has been conceived and written with one type of user in mind: a human. No matter what chain of events is taking place under the hood of software, a human user is traditionally at the end of that chain. That end user invariably consumes that data and/or functionality through a user interface (UI)—one that’s designed to make the act of consumption as easy and even enjoyable as possible.  But what if that same data and/or functionality could be just as easily consumed by another piece of software? In this case, the UI concerns are very different. After all: Software doesn’t have eyes, emotions or intuition, so it doesn’t need an enjoyable, intuitive graphical user interface. However, as with a UI tailored to humans, software needs an interface that makes it easy to consume data and/or functionality. Enter, application programming interfaces, or APIs.  An API is geared for consumption by software, which is why APIs are often explained in the mainstream media as a technology that allows applications (software programs) to talk to one another. In this context, the terms “application,” “software,” “machines” and “computers” are virtually interchangeable. For example, APIs are often discussed as being machine-readable interfaces (versus human-readable). 
• #41: But what about when the user is another software system? The software returns results via the API and the Software asks for data or takes action by interacting with the API.
• #42: Let’s get a list of Spark rooms that you are in using the Spark developer interactive document.
• #43: We’re going to login to the documents so that we can retrieve a list of rooms programmatically.
• #50: Congratulations! You made your first API request.
• #52: From progammable web…. For decades, most computer software--programs that provide data like contact information or functionality like image editing--has been conceived and written with one type of user in mind: a human. No matter what chain of events is taking place under the hood of software, a human user is traditionally at the end of that chain. That end user invariably consumes that data and/or functionality through a user interface (UI)—one that’s designed to make the act of consumption as easy and even enjoyable as possible.  But what if that same data and/or functionality could be just as easily consumed by another piece of software? In this case, the UI concerns are very different. After all: Software doesn’t have eyes, emotions or intuition, so it doesn’t need an enjoyable, intuitive graphical user interface. However, as with a UI tailored to humans, software needs an interface that makes it easy to consume data and/or functionality. Enter, application programming interfaces, or APIs.  An API is geared for consumption by software, which is why APIs are often explained in the mainstream media as a technology that allows applications (software programs) to talk to one another. In this context, the terms “application,” “software,” “machines” and “computers” are virtually interchangeable. For example, APIs are often discussed as being machine-readable interfaces (versus human-readable). 
• #54: But what about when the user is another software system? The software returns results via the API and the Software asks for data or takes action by interacting with the API.
• #62: Note that adding your Spark Token into a Web page is not something you want to do Rather have it dynamically injected
• #65: We will also be working with Postman. It is a free browser plugin with Chrome and makes it easy to make API requests and examine your responses. You will want to use this tool for other APIs that don’t have an interractive document.
• #66: You can see we are fetching data of all of the rooms you are a member of.
• #67: Okay let’s look at how to make an API call in Postman.
• #68: You will use this token to authenticate your request. This tells the Spark web server who is making the request
• #69: Okay so let’s look at JSON . JSON is great cause it is universal, regardless of which laguage you chose to write yoru code , i can garantee you will find a json parsing library. If it is not already built into the language iteself. It is very easy to use and simple to read/ easy on the eyes Okay let’s quickly go through the basic structure of a json Start of Square Brackets Each element is an object, in this case it is an Array of objects Then you get key value pair. Another great tool to use is jsonlint.com to check your json , especially if you are doing a POST to an API, you need to make sure your JSON is properly formatted otherwise it will fail
• #74: This will be the final of what we will see. The Hello World Bot. ToDo: switch out image to one that says Hello Tessa Mero
• #76: Bot assistance preinstalled in Windows versions from 1997 to 2003.
• #77: Talk about Siri as a bot
• #78: Amazon echo as a bot
• #79: Amazon Alexa integrating with the Tesla Model S. Make commands to make other things do things. Jason Geocke from Cisco doing this integration.
• #80: Chat bots are becoming more popular and will become the future of technology. * Use Case: Customer service interactions. The bot is an AI to grab information and package it and put it in front of a human to finish the interaction.
• #82: “I’ve analyzed the Silicon Valley Bot Startup trend and created a handy venn diagram to help explain it” Bots are designed to solve a problem you have in your work flow or business.
• #83: You can create or use existing plugins to extend your chat bot to do things. Such as the SmartSheet (which is a competitor of google spreadsheets), to send notifications when there is a change in your spreadsheet. It also lists the commands you can make to trigger activities. Mention Spark Innovation Fund?
• #84: In our company Spark Chats, we have a room with a MemeBot that one of my colleagues created. You type a few words, followed by the name of the meme to trigger it, and the bot will create a meme. (There’s an API for retrieving meme images and overlaying the text).
• #86: A bot can do things as itself. It has its own account and authentication. If you do an integration, it’s going to complete tasks as YOU.
• #87: For example, the Out of Office Assistant integration. It lists the requests you can do with it.
• #88: In the Spark API scope, you can see the different levels of access that your integration can require. You can find all of this in the API documentation. We also have a collection of POSTMAN calls. Just ask us later for more information.
• #89: In this way, it’s its own entity, which is an authentication on your account.
• #91: Go to developer.ciscospark.com and click on Sign Up on the far right top corner.
• #93: Log in at “Spark for Developers” and open the "My Apps" menu.
• #94: You will access the “New Bot” creation form below. Fill in a name, a unique email identifier, and specify a publicly accessible image URL with a minimal resolution of 512x512 pixels. Feel free to pick this image example for the sake of this lab. (http://bit.ly/SparkBot-512x512) Note that you will not be authorized to pick the email "[email protected]" as it is already reserved. Make sure to replace future mentions to the bot email you have chosen.
• #95: Give people some time to type this URL in or find their own bot picture they want to use
• #96: Click “Add Bot” to get your Cisco Spark Bot created. Your Bot's access token is displayed. Paste it in a safe place as it won’t show up again, and we will use it in steps 2 and 3 of this lab. Note that a Cisco Spark Bot access token lasts 100 years. If you ever loose or reveal it, you can come back to this Bot details page and regenerate an access token. The previously issued token will be automatically deprecated.
• #97: Your bot can now be added to any Cisco Spark Room by specifying its email: [email protected] in our example. Go to your Cisco Spark client, and create a new room with your Bot as a participant.
• #98: Go into your Spark app. You can now add your bot to the chat. Even though you can chat with your bot, you won’t see him answer... as we haven’t connected it yet to any custom code logic. We’ll work on this in the next steps.
• #100: For the sake of this lab, we will clone an existing code sample, and leverage the Cloud9 platform to deploy our own version of a Cisco Spark bot. Sign up at https://c9.io/signup. Create a new private Workspace. Make sure to create it as private so that the access token - we will set later - does not get disclosed. Fill in the "Clone from Git" field with the URL of our code sample: https://github.com/CiscoDevNet/node-sparkbot-samples. Make sure to pick the Node.js template, and click "Create worspace".
• #101: Fill out the form to create your first workspace. Create your workspace name, description. Set it to private, and enter the Github URL. (Closer look at the URL on the next slide). Now click on “Create Workspace”
• #103: After a minute, your workspace will be ready to use. Congrats, You now have at hand a fully functional nodejs development environment with your own copy of a Cisco Spark Bot!
• #104: Go to the shell terminal at the bottom of the IDE, and type “npm install”. The nodejs libraries used by our code sample get downloaded to your Cloud9 workspace. In the File Explorer, look for the “helloworld.js” file in the “examples” directory. Double click the file to make it the current editable source code in your workspace. Now click the "Run" button in the top menu to launch an instance of your code. The Cloud9 console displays an error, as we have not specified the Cisco Spark identity under which our code should run. Now comes time to configure our bot.
• #105: Click the ENV button at the bottom right of the Cloud9 terminal, and create two variables: DEBUG with "sparkbot*" as a value: this variable activates logs, SPARK_TOKEN with your bot’s token value: paste the token generated in step 1.
• #106: Finally, click on the wheel to restart your bot, and check your logs look similar to the snapshot below.
• #107: As we created our Cloud9 workspace as private, we will now need to take an extra step to make our bot accessible from Cisco Spark. Click on the "Share" link in the upper right corner, close to your avatar. As the popup shows up, click the "Public" checkbox facing the "Application" links to share. Click Yes when the pop up appears.
• #108: In this section, we will create REST Webhooks so that our bot starts receiving traffic from Cisco Spark. 
• #109: Look for your bot public URL in the Cloud9 terminal. It appears run after the mention "Your code is running at ", and is formatted as: https://replace-with-your-cloud9-project-name.c9users.io/. Open your bot public URL. Note that the snapshot you see leverages the Chrome plugin “JSON viewer” as mentioned in the pre-requisites. If you look attentively to the JSON data above, you will see your bot is running under the Cisco Spark Identity of the Bot Account you created earlier. Moreover, the “listeners” section lists the events your bot can take action on. 
• #110: Open the list of Webhooks supported by Cisco Spark, and look for the event entries needed by your bot: Messages / Created: a new message got posted into a room Memberships / Created: someone joined a room that you are in Click on the Webhooks entry in the API Reference section on the left, and select the “Post” method. This will drive you to the Create a Webhook form. Fill in the fields as shown in the screenshot: Authorization header: change the access token to your bot’s, and do NOT remove the "Bearer " prefix, targetUrl: paste the public URL of your bot on Cloud9, resource and event: make sure to fill in the “messages” and “created” values, as it is only default placeholders you see in the form, last fields “Secret” and “Filter” are optional. Leave them blank.
• #111: Then click “Run” and check the response in the right panel. As your Cisco Spark API call completes successfully, you will see a green “200/success” displayed, and your Webhook will be assigned a unique identifier (check the “id” field). This webhook is fired every time a new message is added to a Cisco Spark room your bot is a member of. Now, let's create our second Webhook, in order to receive an event every time our bot is added to a room. On the same form, modify the value of the "resource" field: replace “messages” with “memberships”. Click “Run” again, and check your second Webhook got successfully created, with the “200 / success” message. Then click “Run” and check the response in the right panel. As your Cisco Spark API call completes successfully, you will see a green “200/success” displayed, and your Webhook will be assigned a unique identifier (check the “id” field). This webhook is fired every time a new message is added to a Cisco Spark room your bot is a member of.
• #112: Now, let's create our second Webhook, in order to receive an event every time our bot is added to a room. On the same form, modify the value of the "resource" field: replace “messages” with “memberships”. Click “Run” again, and check your second Webhook got successfully created, with the “200 / success” message.
• #113: In the previous steps, you deployed a Cisco Spark bot sample on Cloud9, launched a new instance under the identity of the Bot Account you created, and created Webhooks to start receiving events at your bot public URL on Cloud9. Now comes time to chat with your bot.
• #114: Reach to the Cisco Spark room you created in step 1. Enter /hello. Check your bot's response!
• #115: As introduced in previous labs, Cisco Spark Bots MUST be mentioned in “Group” rooms in order to be notified. Open the “Create a Room” form. Fill in the form with a title. Do NOT modify the token in the Authorization header, so that the room gets created under your personal Cisco Spark identity. Check the result is a "200/success", and the room type is set to “Group”. As you're the only participant in the room for now, Cisco Spark created a "Group" room to let you add participants later.
• #116: Now, open your favorite Cisco Spark client, and reach to the newly created room. Invite your bot to the conversation by adding it as a participant, with the email address you created in step 1. Type /hello. You do not get any answer as your bot is not mentioned. Now mention your bot... and what for its answer!
• #117: What about extending your bot! If you have a fully functional development environment at your disposal, we suggest you start by adding a few breakpoints in your bot main file "helloworld.js", and restart your bot in debug mode. Then, you'll want to add some commands of your own. If you’re looking for some inspiration, take a look at these examples. For the sake of this lab, we leveraged a nodejs bot framework that hides most of the complexity of listening to messages and taking action as commands are fired. Note that several other nodejs Bot frameworks exist for Cisco Spark, from basic to advanced and in various languages. As an example, Nick Marus’s flint framework is a nodejs bot framework that embeds interesting features such as automated creation of the Webhooks required by your bot... certainly worth a try...