Version History

Version	Author	Update	Date
1.0	Yuchen Gao	Initial draft	12/31/2019
1.1	Yuchen Gao	Update text format to support potential multiple text records	12/31/2019
1.2	Yuchen Gao	Splits video and audio.	01/12/2020
1.3	Yuchen Gao	Add downloadable rich response type. Add “isError” field in text response type.	01/30/2020
1.4	Yuchen Gao	Add a new rich response type: link.	03/05/2020

Introduction

In this document we introduce the rich response format for our platform. Rich responses enables us to create responses of various types, including but not limited to text, images, videos, audios, cards, etc.

See the figure below for an example:

Supported Types

First Of All: Stages

A list named stage is returned per user query. An example is shown below.

{
  "stage": [
    {
      "text": {
        "text": ["Hello", "Howdy", "Hola"]
      }
    },
    {
      "image": {
        "title": "Image Title",
        "url": "https://www.sample.com/hello.png",
        "alt": "Some image."
      }
    }
  ]
}

All elements in this list must be of one of the response types among: text, image, video, audio, link, cards, quick reply and downloadable. Each response type will be explained in detail below.

Text

{
  "text": {
    "text": ["Response 1", "Response 2", "Response 3"],
    "isError": false
  }
}

Name	Type	Required	Description
text	List	Yes	Response in text. Randomly returning one of the elements.
isError	Boolean	No	If set to true, indicates that this text represents an error message.

Image

{
  "image": {
    "title": "Image Title",
    "url": "https://www.sample.com/img.png",
    "alt": "Some image."
  }
}

Name	Type	Required	Description
title	String	No	Optionally display title for the image.
url	String	Yes	Url of the image.
alt	String	No	Replacement text should the image fail to load.

Video

{
  "video": {
    "title": "Video Title",
    "url": "https://www.sample.com/video.flv",
    "alt": "Some video."
  }
}

Name	Type	Required	Description
title	String	No	Optionally display the title for the video.
url	String	Yes	Url of the video.
alt	String	No	Replacement text should the video fail to load.

Audio

{
  "audio": {
    "title": "Audio Title",
    "url": "https://www.sample.com/music.mp3",
    "alt": "Some audio."
  }
}

Name	Type	Required	Description
title	String	No	Optionally display the title for the audio.
url	String	Yes	Url of the audio.
alt	String	No	Replacement text should the audio fail to load.

Cards

Let’s first see couple examples:

The first example shows two messages, each containing a single card with multiple buttons, clicking on each button sends back a text to the chat window.

The second example (from facebook generic template example) shows that 3 cards (each with subtitles and two buttons) are displayed vertically, each with two buttons.

Here’s the formal definition for the card type:

{
   "cards":{
      "type":"horizontal",
      "cards":[
         {
            "title":"Card Title",
            "subtitle":"Card subtitles",
            "imageUrl":"http://www.sample.com/img.png",
            "imageAlt":"Card image here.",
            "buttons":[
               {
                  "text":"button text",
                  "postback":"https://qingyu.rsvp.ai/"
               },
               {
                  "text":"button text",
                  "postback":"send back text"
               }
            ]
         }
         {
            ...
         }
      ]
   }
}

Name	Type	Required	Description
type	Enum String (horizontal/vertical)	Yes	Whether multiple cards (if applicable) should be displayed horizontally or vertically. Defaults to horizontal.
cards	List	Yes	A list of cards to be displayed in the response.
--title	String	No	Optionally display title for each card.
--subtitle	String	No	Optionally display subtitles for each card.
--imageUrl	String	No	Url of the image in a card.
--imageAlt	String	No	Replacement text should the card image fail to load.
--buttons	List	No	A list of buttons to each card.
----text	String	Yes	Text to be displayed on the button.
----postback	String	Yes	A URL to open or the text to send back to chat.

Quick Reply

Quick replies are shortcut buttons shown usually beneath a response message, see the example below:

{
  "quickReplies": {
    "quickReplies": [
      {
        "text": "button text",
        "postback": "https://qingyu.rsvp.ai/"
      },
      {
        "text": "button text",
        "postback": "Send back text"
      }
    ]
  }
}

Name	Type	Required	Description
quickReplies	List	Yes	Url of the image in a card.
--text	String	Yes	Text to be displayed on the label.
--postback	String	Yes	A URL to open or the text to send back to chat.

Downloadable

A downloadable response type sends a response with a file that users can download.

{
  "downloadable": {
    "title": "Downloadable Title",
    "url": "https://www.sample.com/form.csv"
  }
}

Name	Type	Required	Description
title	String	No	Optionally display the title for the downloadable file.
url	String	Yes	Url of the downloadable file.

Link

A link response redirects users to a new web tab when clicked.

{
  "link": {
    "title": "Link Title",
    "text": "Click me!",
    "url": "https://www.sample.com"
  }
}

Name	Type	Required	Description
title	String	No	Optionally display the title for the link.
text	String	Yes	Displayed text for the link.
url	String	Yes	Url of the link.