Message Attachments

Spark has native support for posting messages with file attachments. Using the Messages API you can send messages containing text, text with attachments, or just share a file with the room without any text. Message attachments are limited to 100MB each.

What you may not know is that Spark has special support for most PDFs, Microsoft Word, Microsoft PowerPoint, and most popular image formats. For these file types, Spark clients will render a preview in the room and a full view when clicked.

Here is the complete list of supported file types and extensions:

  • Microsoft Word (doc, docx)
  • Microsoft PowerPoint (ppt, pptx)
  • Adobe Portable Document Format (pdf)
  • JPEG (jpg, jpeg)
  • Windows Bitmap (bmp)
  • Graphics Interchange Format (gif)
  • Portable Network Graphics (png)

Send a Message with Attachments

Local File Attachments

To send local file attachments, simply post a message by including your access token in the Authorization header and the path to your local file with the files parameter. Optionally, you can also include a plain-text message with the attachment by using the text parameter. When uploading files directly from your local filesystem, your request will need to be a multipart/form-data request rather than JSON. Here's an example of using cURL to send a new message with a local file as a file attachment:

curl --request POST \
  --header "Authorization: Bearer ACCESS_TOKEN" \
  --form "files=@/home/desktop/example.png;type=image/png" \
  --form "roomId=Y2lzY2....." \
  --form "text=example attached" \
  https://api.ciscospark.com/v1/messages

You can also use the your favorite scripting language to send messages with local files. Here's an example of using Python with a local file:

import requests
from requests_toolbelt.multipart.encoder import MultipartEncoder

m = MultipartEncoder({'roomId': 'Y2lzY2.....',
                      'text': 'example attached',
                      'files': ('example.png', open('example.png', 'rb'),
                      'image/png')})

r = requests.post('https://api.ciscospark.com/v1/messages', data=m,
                  headers={'Authorization': 'Bearer ACCESS_TOKEN',
                  'Content-Type': m.content_type})

print r.text

Remote Attachments

Alternatively, if you have a file available via a publicly-accessible URL that you wish to share, you can use the URL as the value in the files JSON parameter instead of attaching your local file in a multipart message. The files parameter currently takes one URL as an input. A plain-text message can also be included in the text parameter. Here's an example of using cURL to send a new message with a remote file as a file attachment:

curl --request POST \
  --header "Authorization: Bearer ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"roomId":"Y2lzY2.....","text":"Example file","files":["http://www.example.com/images/media.png"]}' \
  https://api.ciscospark.com/v1/messages

Retrieve Message Attachments

Retrieving Message Details

In order to retrieve the file details such as filename and content-type, you can simply use a HEAD request with your access token in the Authorization header. This is particularly useful if you just want to verify the filename and type before downloading the content.

curl -I https://api.ciscospark.com/v1/contents/Y2lzY...... -H "Authorization: Bearer ACCESS_TOKEN"

HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Disposition: attachment; filename="example.png"
Content-Length: 44752
Content-Type: image/png

Retrieving Message Attachments

Files attached to a message are returned in the files property of the message object. To retrieve one of these files you should issue a GET request on the file URL including your Access Token in the Authorization header.

curl -H "Authorization: Bearer ACCESS_TOKEN" https://api.ciscospark.com/v1/contents/Y2lzY......