Enhance your Chatbot Experience with Rich Attachments

Published in

RingCentral Developers

6 min readAug 26, 2017

We are always working on improving the RingCentral Glip user experience and we’re excited to announce two new capabilities to enhance your experience:

Post Attachments — Format posts with consistent and easy to read layout
File Upload API — Upload files with automatic rendering of specific message types including images

The screenshots below give some indication of the user experience possible with these new features.

Post Attachments example post

File Upload API example post

Post Attachments

Glip Post Attachments allow you to attach additional content to posts with formatting and color indicators to more easily convey a large amount of information. This is available with both Inbound Webhooks and via the REST API. Specifically you can:

add up to 20 attachments per post, each rendered as its own section
add an author, title, pretext, text to each attachment
select a color for each attachment to indicate importance or subject
render short metadata using the fields property
render photos and images

Notes

A maximum of 20 attachment objects are allowed per payload
All fields except *text* have a char limit of 300 bytes
The Glipdown flavor of Markdown is used
The Inbound Webhook and REST API have slightly different schemas as shown below

Post Attachment parameters

The post attachment has a number of properties that are displayed in the following locations for a webhook message below. The REST API has a similar layout.

Inbound Webhook Request Example

Here is an example message body for an inbound webhook:

{
  "icon": "https://example.com/post_icon.png",
  "title": "**Title of the post**",
  "body": "Body of the post",
  "attachments": [
    {
      "color": "#00ff2a",
      "pretext": "Attachment pretext appears before the attachment block",
      "author_name": "Author Name",
      "author_link": "https://example.com/author_link",
      "author_icon": “https://example.com/author_icon.png",
      "title": "Attachment Title",
      "title_link": "https://example.com/title_link",
      "fields": [
        {
          "title": "Field 1",
          "value": "A short field",
          "short": true
        },
        {
          "title": "Field 2",
          "value": "[A linked short field](https://example.com)",
          "short": true
        },
        {
          "title": "Field 3",
          "value": "A long, full-width field with *formatting* and [a link](https://example.com)"
        }
      ],
      "text": "Attachment text",
      "image_url": "https://example.com/congrats.gif",
      "footer": "Attachment footer and timestamp",
      "footer_icon": "https://example.com/footer_icon.png",
      "ts": 1503723350
    }
  ]
}

Here is some example code:

Go: github.com/grokify/go-glip/…/examples/test_webhook

REST API Post Message Example

Here is the same message with slightly different property names for a API request:

{
  "text": "Body of the post",
  "attachments": [
    {
      "type": "Card",
      "fallback": "Attachment fallback text",
      "color": "#00ff2a",
      "intro": "Attachment intro appears before the attachment block",
        "author": {
          "name": "Author Name",
          "uri": "https://example.com/author_link",
          "iconUri": "https://upload.wikimedia.org/wikipedia/commons/thumb/f/fd/000080_Navy_Blue_Square.svg/1200px-000080_Navy_Blue_Square.svg.png"
        },
      "title": "Attachment Title",
      "text": "Attachment text",
      "imageUri": "https://media3.giphy.com/media/l4FssTixISsPStXRC/giphy.gif",
      "thumbnailUri": "http://clipart-library.com/img/1415947.jpg",
      "fields": [
        {
          "title": "Field 1",
          "value": "A short field",
          "style": "Short"
        },
        {
          "title": "Field 2",
          "value": "[A linked short field](https://example.com)",
          "style": "Short"
        },
        {
          "title": "Field 3",
          "value": "A long, full-width field with *formatting* and [a link](https://example.com)",
          "style": "Long"
        }
      ],
      "footnote": {
        "text": "Attachment footer and timestamp",
        "iconUri": "http://www.iconsdb.com/icons/preview/red/square-ios-app-xxl.png",
        "time": "2018-01-05T18:52:35.993311508-08:00"
      }
    }
  ]
}

Here is some example code:

Go: github.com/grokify/go-ringcentral/…/examples/glip_post_attachment

Property Descriptions

Use these parameters to customize the appearance of a message.

fallback — A string of default text that will be rendered in the case that the client does not support Interactive Messages (Currently there are no Glip Clients that do not support this.)

color — A Hex color code that determines the color of the side border of the Interactive Message.

pretext — A string that will display directly above the Message.

author — A set of properties that will render an author section at the top of the message

author_name — The actual author name string
author_link— Used to link the authors name. Will only work when author_name is present.
author_icon — A url to an image up to 82x82px that will display to the left of the author’s name. Will only work when author_name is present.

"author_name": "Author Name",
"author_link": "https://example.com/author_link",
"author_icon": "https://example.com/author_icon.png",

title— A set of properties that will render a title under the author if author is set.

title — The actual title string
title_link— Used to linkify the title

"title": "Attachment Title",
"title_link": “https://fexample.com/title_link",

text — A large string field (up to 1000 chars) to be displayed as the body of a message (markdown)

fields — An array of objects that will render indvidual subsections within a message

title — A string that will display as the title for an individual field.
value — A string that will display under the field title (Markdown)
short — A boolean used to flag fields that should span the width of the message, Defaults to false (Not full width)

"fields”: [
  {
    "title": "Field 1",
    "value": "A short field",
    "short": true
  },
  {
    "title": "Field 2",
    "value": "[A linked short field](https://example.com)",
    "short": true
  },
  {
    "title": "Field 3",
    "value": "A long, full-width field with *formatting* and [a link](https://example.com)"
  }
],

image_url—A string url used to display a single image at the bottom of a message. We currently support GIF, JPEG and PNG. Glip only support “HTTPS” Url’s. If the URL is a http url we show a placeholder.

thumb_url — A string url used to display a thumbnail to the right of a message (82x82)

footer — A set of properties that will render a footer under the message.

footer — A string used to be displayed as the body of the footer.
footer_icon — A URL used to display a 32x32px icon to the left of the footer
ts — A Unix timestamp to be formatted and displayed to the right of the footer

"footer": "Attachment footer and timestamp",
"footer_icon": "https://example.com/footer_icon.png",
"ts": 1503714729

Markdown Support

Glip supports a simple form of Markdown for formatting the body of incoming messages. The following are supported for post attachments in addition to post bodies.

*italics*
**bold**
[a link](http://example.com)
> quote
_underline_
* bullet

File Upload API

The File Upload API works in a similar fashion to uploading a file from the app and can be used to upload various file formats including images and audio files. Images will be displayed with an image preview within Glip. To post file you can either post a file to Glip and then attach the file to a group.

Single Shot API

This API allows you to post an image into a Glip team with a single API call.

POST /restapi/v1.0/glip/files?groupId=111111&name=myfile.png
Content-Type: image/png
Content-Disposition: attachment; filename="myscreenshot.png"<binary_image_data>

Post and Link APIs

If you want to link the same file to multiple groups, you can post the file, get a fileId and then link that fileId to multiple groups via their groupId numbers.

Posting a file

POST /restapi/v1.0/glip/files?name=myfile.png
Content-Type: image/png
Content-Disposition: attachment; filename="myfile.png"myscreenshot<binary_image_data>

It is also possible to post files using multipart/form-data

POST /restapi/v1.0/glip/filesContent-Type: multipart/form-data; boundary=----WebKitFormBoundarybFBd5PasSjZLCvRz------WebKitFormBoundaryDDa2mRgtxjQwxBeqContent-Disposition: form-data; name="file_1"; filename="myscreenshot.png"1------WebKitFormBoundaryDDa2mRgtxjQwxBeqContent-Type: image/jpeg/// Binary content

Linking a file

Linking an existing file will let you post the same file to multiple groups without uploading duplicates.

POST /restapi/v1.0/glip/posts
Content-Type: application/json{
  "groupId": "111111",
  "attachments": [
    {
      "id": "222222",
      "attachmentType": "File"
    }
  ]
}

Support

Please try it out and let us know how it works for you! Our team is available and happy to assist:

Glip Help: https://help.glip.com
Developer Community: https://devcommunity.ringcentral.com
Stack Overflow: https://stackoverflow.com/questions/tagged/ringcentral