Version History

Version	Author	Update	Date
1.0	Yuchen Gao	Initial draft	12/31/2019
1.1	Yuchen Gao	Updated 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	Added downloadable rich response type. Add “isError” field in text response type	01/30/2020
1.4	Yuchen Gao	Added a new rich response type: link	03/05/2020

Introduction

This document introduces the rich response format for the platform. Rich responses enables the creation of 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 for each 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 following response types: text, image, video, audio, link, cards, quick reply and downloadable.

Text

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

Name	Type	Required	Description
text	List	Yes	Response in text. Randomly return 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	Display title for the image
url	String	Yes	URL of the image
alt	String	No	Alt tags if the image fails to load

Video

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

Name	Type	Required	Description
title	String	No	Display the title for the video
url	String	Yes	URL of the video
alt	String	No	Alt tags if the video fails to load

Audio

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

Name	Type	Required	Description
title	String	No	Display the title for the audio
url	String	Yes	URL of the audio
alt	String	No	Alt tags if the audio fail to load

Cards

Some example cards:

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) are displayed horizontally or vertically. Defaults to horizontal
cards	List	Yes	A list of cards to be displayed in the response
--title	String	No	Display title for each card
--subtitle	String	No	Display subtitles for each card
--imageUrl	String	No	URL of the image in a card
--imageAlt	String	No	Alt tags if the card image fail to load
--buttons	List	No	A list of buttons for 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	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	Display the title for the link
text	String	Yes	Displayed text for the link
url	String	Yes	URL of the link