This tutorial shows how to make an existing Spark bot more secure. If you are building your first bot, it is recommended you start with this tutorial. Then come back here once it’s up and running! If someone outside of your organization never interacted with your bot, they can’t just run a simple search to find it. However, if they know or guess the ‘email’ address of your bot, they will be able to add it to a space (formerly called room) and send it messages. The more bots that are out there, the higher the possibility of that happening! To prevent unwanted attention, there are three main ways to control access to your bot: 1. You can setup a space (formerly called room) filter when you create a webhook, which points to your bot application’s server.  If someone adds your bot to a Cisco Spark space, and the space does not fit the filter rule for any of the bot’s webhooks, the bot application server will not receive any messages from Spark.  For large enterprise bots that need access to many different spaces, that might not work out.  That’s okay— you can setup one webhook for your bot, with no filter, to receive all messages from any space to which it belongs, and use the following two methods to secure the bot. 2. Filter at the bot’s code level - JSON Payloads are sent from Cisco Spark via HTTP POST to your webserver, which is defined in your webhook (see Handling Requests from Cisco Spark).  When the JSON payload comes in, you can begin your server’s code by checking the incoming message’s data[“personId”] or data[“personEmail”] , compare it to a predefined list in your code or database, and handle accordingly.  You can also make a request to Spark with data[“personId”] to check other details, like the organization, to only allow people of a specific org.  Note: the OrgId that comes in with the webhook JSON Payload is the OrgId of the person that created the webhook. auth_users = [ 'tahanson@cisco.com ' ] my_org_id = "Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi8xZWI2NWZkZi05NjQzLTQxN2YtOTk3NC1hZDcyY2FlMGUxMGY" @post ( '/' ) def index(request): webhook = json.loads(request.body) requester = webhook[ 'data' ][ 'personEmail' ] if requester != bot_email: if requester in auth_users:             print "Authorized user!"             #Do stuff else :             print "Unauthorized user!"             #AND/OR check person's org: person = sendSparkGET( ' https://api.ciscospark.com/v1/people/ {0}' .format(webhook[ 'data' ][ 'personId' ])) if json.loads(person)[ 'orgId' ] == my_org_id:             print "User is a member of Org!"             #Do stuff else :             print "User it NOT a member of Org!" return "true" Note: Above code uses a function defined here. 3. Last, but not least, we have the webhook secret.  This should be used to prevent your bot from processing any POST request that does not come from your specific webhook.  This will block any of your other Spark webhooks, or Spark webhooks setup by other users trying to send to your bot’s webserver location. Here is a brief tutorial on using a webhook secret in Python. Everything together, here is a code snippet of all of these features combined: @post ( '/' ) def index(request): raw = request.body hashed = hmac.new(key, raw, hashlib.sha1) validatedSignature = hashed.hexdigest() print 'validatedSignature' , validatedSignature print 'X-Spark-Signature' , request.headers.get( 'X-Spark-Signature' ) returnVal = "" if validatedSignature == request.headers.get( 'X-Spark-Signature' ): webhook = json.loads(raw) print webhook[ 'data' ][ 'id' ] requester = webhook[ 'data' ][ 'personEmail' ] if requester != bot_email:             #get person information, specifically need the person's orgId             person = sendSparkGET( ' https://api.ciscospark.com/v1/people/ {0}' .format(webhook[ 'data' ][ 'personId' ]))             if json.loads(person)[ 'orgId' ] == my_org_id or requester in auth_users:                 result = sendSparkGET( ' https://api.ciscospark.com/v1/messages/ {0}' .format(webhook[ 'data' ][ 'id' ]))                 result = json.loads(result)                 in_message = result.get( 'text' , '' ).lower()                 in_message = in_message.replace(bot_name, '' )                 #echo the message back to the same room                 sendSparkPOST( " https://api.ciscospark.com/v1/messages " , { "roomId" : webhook[ 'data' ][ 'roomId' ], "text" : in_message})                 returnVal = "success" else :                 print "orgId does not match or person not in list of authorized users" else : print "Secret does not match!" return returnVal You can get the full, working example on Github.  You’ll just need to replace your desired orgId, bot name, and token values in the variables at the bottom of the file.  Let us know if you have any questions! - Taylor Hanson, Customer Support Engineer II ... View more

To protect the Spark environment, the API has rate limits in place for the different resources available for use, such as /messages and /rooms.  These limits will vary depending on the calls being made, how resource intensive that call is on the servers, and how many servers are actively in routing – and is subject to change as needed to protect all use cases from failing in the event of a large batch of requests.  So, what should be done if you want to make API calls very frequently, but don’t want to hit errors and lose requests by going over the rate limit?  The answer is to use the Retry-After Header that is returned with an HTTP 429 error.  The Retry-After header defines the number of seconds you’ll need to wait before sending API requests again. The app that follows pulls the list of rooms available to the user (using a single user or bot’s bearer token), as fast as possible.  Normally, it would be recommended to put some kind of wait time between continuous looping requests, to avoid hitting the rate limit entirely.  However, since that rate limit might be reached anyway depending on the resource availability, it’s important to handle for the likely possibility you’ll catch a 429 here and there. Basically, we make a call to https://api.ciscospark.com/v1/rooms continuously and look for an error.  If the error is a status code 429, we check the wait time relayed to us in the Retry-After header and sleep for the time specified before starting again.  If there’s an error, but it isn’t a 429, we break out of the loop because something else is wrong.  Maybe you had a bad bearer token, or maybe there is a general error with the format of the request. Since this code can run forever if implemented properly, you’ll need to Ctrl+C to kill it in the Terminal itself – make sure you don’t let it go on indefinitely or you could be flagged depending on how many requests are made and for how long. The initial portion of the application is making the call to the rooms resource to get the rooms over and over, whereas the latter section beginning with the line: except urllib2.HTTPError as e: defines what to do if a 429 error is encountered – print out the content of the error, and then extract the value of the Retry-After header for use in the sleep. Here’s the full app (it’s short so we’ll put the whole thing): import urllib2 import json import time def sendSparkGET(url):     request = urllib2.Request(url, headers={ "Accept" : "application/json" ,                                     "Content-Type" : "application/json" }) request.add_header( "Authorization" , "Bearer " +bearer)     response = urllib2.urlopen(request)     return response bearer = "BEARER_TOKEN_HERE" while True :     try :         result = sendSparkGET( ' https://api.ciscospark.com/v1/rooms ' )         print result.code, time.time(), result.headers[ 'Trackingid' ]     except urllib2.HTTPError as e:         if e.code == 429 :             print 'code' , e.code             print 'headers' , e.headers             print 'Sleeping for' , e.headers[ 'Retry-After' ], 'seconds' sleep_time = int(e.headers[ 'Retry-After' ])             while sleep_time > 10 : time.sleep( 10 ) sleep_time -= 10                 print 'Asleep for' , sleep_time, 'more seconds' time.sleep(sleep_time)         else :             print e, e.code             break It’s important to note that it’s possible to send a request after receiving a 429 without getting an error; there are many servers involved with handling a request, so just because you’ve hit the rate limit of one, does not mean you’ve hit the rate limit of all.  However, you’re probably pretty close to failing on every server, so it’s best to wait for the time described by Retry-After upon detecting the very first 429. The full code can be found on our Github. As always, if you have any questions, please contact devsupport@ciscospark.com 24/7/365 - we’re happy to help! Taylor Hanson, Customer Support Engineer II ... View more

If you’ve ever wondered, “How do I retrieve a file using the API – it’s just a URL with an encrypted ID!”, this example should hold the answer.  It uses a bot to download a file sent to a 1:1 room (a conversation between the bot and a single user), using a webhook.  If your bot is in a group room, it will only be able to retrieve files where the bot is explicitly mentioned, like @botname. For additional help creating a webhook, we recommend checking out our webhook blog and our simple (but complete) bot demo. Alternatively, if you’re using an access token retrieved using Oauth, you can retrieve the messages in a room with this function. In the Webhooks Explained page, the section titled Handling Requests from Spark describes the format of webhook messages.  When a file is sent to the 1:1 room with the bot, the webhook will send JSON to your server containing a files key, under the data element, in addition to the other attributes such as personEmail: {"resource": "messages", "name": "Web hook name", "created": "2016-07-12T18:24:17.179Z", "id": "Y2lzY29zcGFyazovL3VzL1dFQkhPT0svMWU3Y2Y4OGMtYTE4My00ZGQyL123456789", "filter": "roomId=Y2lzY29zcGFyazovL3VzL1JPT00vNmFjNjA0OTAtMDU3YS0xMW123456789", "targetUrl": " http://myurl.com ", "data": {"files": [" https://api.ciscospark.com/v1/contents/Y2lzY29zcGFyazovL3VzL0NPTlRFTlQvY2IyZDNhYjAtNWEzZS0xMWU2L12345678 "], "roomType": "group", "created": "2016-08-04T12:27:22.459Z", "personId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS84ZDUwY2M5NS0wMWMyLTQwZmUtOTU5OC1mZmE4M1234567", "personEmail": " person@example.com ", "roomId": "Y2lzY29zcGFyazovL3VzL1JPT00vNmFjNjA0OTAtMDU3YS0xMWU2LWEw123456789", "id": "Y2lzY29zcGFyazovL3VzL01FU1NBR0UvY2IyZDNhYjAtNWEzZS0xMWU123456789"}, "event": "created"} The files attribute is a list of URLs (one URL if only one file is sent in a single message, multiple URLs if more than one file is sent at the same time) that will be used to retrieve the actual files.  The URL for the file will be the request URL in your REST GET, and you’d just need to then pass the bot’s authentication token in a Bearer authorization header to retrieve the details (because who can view the file is limited to who is in the room – again though, in a group room, a bot’s permission is limited to messages in which it is also mentioned). Information and additional examples on retrieving messages is detailed here. The “Content-Disposition” header in the GET response is used to determine the file’s name and file type to be saved.  The file data is the entire body of the GET response.  There is no base 64 or other special encoding of the file data, so it can be written directly to the destination.  So if we were retrieving an image from our example above, we would run the GET on: https://api.ciscospark.com/v1/contents/Y2lzY29zcGFyazovL3VzL0NPTlRFTlQvY2IyZDNhYjAtNWEzZS0xMWU2L12345678 and we would get back: Cache-Control: no-cache Content-Disposition: attachment; filename="04_12_02.jpg" Content-Length: 264178 Content-Type: image/jpeg Date: Thu, 04 Aug 2016 20:09:05 GMT Server: Redacted Trackingid: NA_028c214f-a7dc-44e8-a8bd-f82373fbc860 X-Cf-Requestid: 317eaaad-b2cf-4651-5ce0-4dbdcc700abd Connection: close The below code is an app that receives the data from the webhook and - if the data contains a files key - attempts to download the files directly to the source folder from where it is run (so if the app is located in your /Documents/Files folder, it will download the file to /Documents/Files). from itty import * import urllib2 import json def sendSparkGET(url): request = urllib2.Request(url,                             headers={ "Accept" : "application/json" ,                                      "Content-Type" : "application/json" }) request.add_header( "Authorization" , "Bearer " +bearer) contents = urllib2.urlopen(request) return contents @post ( '/' ) def index(request): webhook = json.loads(request.body) if webhook[ 'data' ].has_key( 'files' ): for file_url in webhook[ 'data' ][ 'files' ]:             response = sendSparkGET(file_url)             content_disp = response.headers.get( 'Content-Disposition' , None )             if content_disp is not None :                 filename = content_disp.split( "filename=" )[ 1 ]                 filename = filename.replace( '"' , '' )                 with open(filename, 'w' ) as f:                     f.write(response.read())                     print 'Saved-' , filename             else :                 print "Cannot save file- no Content-Disposition header received." else : print "No files attached to retrieve!" return "true" ####CHANGE THIS VALUE##### bearer = "BOT_TOKEN_HERE" run_itty(server= 'wsgiref' , host= '0.0.0.0' , port= 10002 ) The full code can be found on our Github. As always, If you have any questions, please contact devsupport@ciscospark.com 24/7/365 - we’re happy to help! Taylor Hanson, Customer Support Engineer II ... View more

Uploading a remote file to a Cisco Spark room using a web-accessible URL is fairly self explanatory -  just supply the URL in the “files” field of a create message request: https://developer.ciscospark.com/endpoint-messages-post.html But this only works for files that are on the public Internet and can be downloaded by Spark's servers. Spark pulls the files down. However, if you want to push the file to Spark, for example to upload a file from your local hard drive, it gets a little more complicated. We’re making all of that easier now because we now support file upload via the Messages API. This means you no longer have to put your files on the public Internet for them to be attached. How it Works: The Spark API accepts file uploads as a MIME upload in the same way your web browser would upload a file in a web form. The two most important aspects are 1) to name the field to which you send "files" and 2) to set your Content-Type header to be multipart/form-data including a boundary. The boundary is part of the MIME specification and is essentially any string that won't appear in the binary encoding of the file; it’s used by the server to determine where the file content ends and the request starts. The final header would look something like this: Content-Type: multipart/form-data; boundary=12345678901234567890123456789012 In Python, it’s difficult to do everything required without the help of a couple of third party libraries.  We’ll use requests ( http://docs.python-requests.org/en/master/user/install/#install ) and requests-toolbelt ( https://github.com/sigmavirus24/requests-toolbelt ). pip install requests pip install requests-toolbelt Once you have those installed, the script itself is simple. from requests_toolbelt import MultipartEncoder import requests filepath    = '/Users/taylorhanson/Desktop/screenshot.png' filetype    = 'image/png' roomId      = 'SOME ROOM' token       = 'YOUR ACCOUNT BEARER TOKEN' url         = " https://api.ciscospark.com/v1/messages " my_fields={ 'roomId' : roomId,            'text' : 'Hello World' ,            'files' : ( 'screenshot' , open(filepath, 'rb' ), filetype)            } m = MultipartEncoder(fields=my_fields) r = requests.post(url, data=m,                   headers={ 'Content-Type' : m.content_type,                            'Authorization' : 'Bearer ' + token}) print r.json() Above, you’ll need to replace the variables with ones suitable for you, with the exception of the url .  The filetype and filepath are totally dependent on the file you are attempting to upload - a full path to the file is expected, and the first slash in the above filepath value represents root, so it’s “root” followed by ‘/Users/taylorhanson/Desktop/screenshot.png'. The roomId value can be found from the developer portal: https://developer.ciscospark.com/endpoint-rooms-get.html Your bearer token can be your personal one for testing, or one for a specific user via integrations: https://developer.ciscospark.com/authentication.html Or a bot: https://developer.ciscospark.com/add-app.html The complete code for the upload can be found on Github. If you have any questions, please contact devsupport@ciscospark.com 24/7/365 - we’re happy to help! Taylor Hanson, Customer Support Engineer II ... View more

The recently released advanced webhooks include the ability to define a “secret” in your webhook, which will pass along with your webhook as a header called “X-Spark-Signature”. This can be used to validate a request is coming from the Spark API and not from some other origin – more info can be found at the bottom of this page. In this blog, we’ll walk you through using the secret field, so you can start locking down your webhooks ASAP. First, you’ll need to create a webhook. Note the “secret” field in the list of options; to make it easy, we’ll use the passphrase listed in the example and set it to: somesupersecretphrase Next you’ll need to code up some logic that checks the secret when the webhook’s data is received. The following script shows very simple validation – just prints out a true if the secret matches. Here’s the Python code: from itty import * import hashlib import hmac @post ( '/' ) def index(request):     """     When messages come in from the webhook, they are processed here.     X-Spark-Signature - The header containing the sha1 hash we need to validate     request.body - the Raw JSON String we need to use to validate the X-Spark-Signature     """     raw = request.body     #Let's create the SHA1 signature     #based on the request body JSON (raw) and our passphrase (key)     hashed = hmac.new(key, raw, hashlib.sha1)     validatedSignature = hashed.hexdigest()     print 'validatedSignature' , validatedSignature     print 'X-Spark-Signature' , request.headers.get( 'X-Spark-Signature' )     print 'Equal?' , validatedSignature == request.headers.get( 'X-Spark-Signature' )     return "true" #Replace this with the secret phrase you used in the webhook creation key = "somesupersecretphrase" port = 10007 run_itty(server= 'wsgiref' , host= '0.0.0.0' , port=port) Which can also be grabbed from Github. Note the “key” field is the secret defined earlier when the webhook was created, which if it matches what’s sent in the webhook, will print ‘True’. This app alone won’t do much – all it’s going to do is confirm “Yep, that’s the right secret!” and then end. But if we combo it with our recent Bot example (Spark bot demo blog | Github repo) then we can validate the secret and use it in an if / else statement. If the secret matches, keep going, if it does not, end immediately. The complete code combining the above validation script and the bot script can be found on Github as well. From that app, here’s a snippet showing the relevant logic using validation:     raw = request.body     #Let's create the SHA1 signature     #based on the request body JSON (raw) and our passphrase (key)     hashed = hmac.new(key, raw, hashlib.sha1)     validatedSignature = hashed.hexdigest()     print 'validatedSignature' , validatedSignature     print 'X-Spark-Signature' , request.headers.get( 'X-Spark-Signature' )     if validatedSignature == request.headers.get( 'X-Spark-Signature' ):         …RUN THE APP…     else :         print "Secret does not match, verboten!" You can expand on all of the logic extensively, but for the basic use of a secret in a functional bot app, this covers what you need to know. If you have any questions, please contact devsupport@ciscospark.com 24/7/365 and we’ll be happy to help! Taylor Hanson, Customer Support Engineer II ... View more