Add interactive messages to chat - Amazon Connect

Add interactive messages to chat

Interactive messages are rich messages that present a prompt and pre-configured display options for a customer to choose. These messages are powered by Amazon Lex and configured through Amazon Lex using a Lambda.

Tip

If you have integrated with Apple Messages for Business, see Interactive Message Types on the Apple website.

Validation limits

The string field limits (for example, title, subtitle, etc.) are expected to be enforced by the client (that is, a custom built interface or the hosted communications widget). The SendMessage API checks only that the total size of the string is less than 20KB.

  • When you use the hosted communications widget without customizing it, if the string exceeds field limits, it is truncated on the user interface and an ellipsis (...) is appended. You can determine how to enforce field limits by customizing the widget.

  • If you are integrating with other platforms (such as Apple Messages for Business), review the limits in this topic for Amazon Connect, and review the limits in the documentation for the other platform. For example, quick replies are not supported on older versions of iOS.

All other field limits must be followed for the message to be successfully sent.

Message display templates

Amazon Connect provides the following message display templates for you to use to render information to customers in a chat:

These templates define how the information is going to render, and what information is surfaced in the chat interface. When interactive messages are sent through chat, flows validate that the message format follows one of these templates.

List picker template

Use the list picker template to present the customer with a list of up to six choices. Each choice can have its own image.

The following images show two examples of how the list picker template renders information in a chat.

  • One image shows three buttons, each one with the name of a fruit in text: apple, orange, banana.

  • The second image shows a picture of a store and then under it, three buttons, each one with the name, image, and price of the fruit.


                The list picker template rendering information in a chat.

The following code is the list picker template that you can use in your Lambda. Note the following:

  • Bold text is a mandatory parameter.

  • In some cases, if the parent element exists in the request and it isn't mandatory/bold, but the fields in it are, then the fields are mandatory. For example, see data.replyMessage structure in the following template. If the structure exists, title is mandatory. Otherwise complete replyMessage is optional.

{ "templateType":"ListPicker", "version":"1.0", "data":{ "replyMessage":{ "title":"Thanks for selecting!", "subtitle":"Produce selected", "imageType":"URL", "imageData":"https://interactive-msg.s3-us-west-2.amazonaws.com/fruit_34.3kb.jpg", "imageDescription":"Select a produce to buy" }, "content":{ "title":"What produce would you like to buy?", "subtitle":"Tap to select option", "imageType":"URL", "imageData":"https://interactive-msg.s3-us-west-2.amazonaws.com/fruit_34.3kb.jpg", "imageDescription":"Select a produce to buy", "elements":[ { "title":"Apple", "subtitle":"$1.00", "imageType":"URL", "imageData":"https://interactive-message-testing.s3-us-west-2.amazonaws.com/apple_4.2kb.jpg" }, { "title":"Orange", "subtitle":"$1.50", "imageType":"URL", "imageData":"https://interactive-message-testing.s3-us-west-2.amazonaws.com/orange_17.7kb.jpg", }, { "title":"Banana", "subtitle":"$10.00", "imageType":"URL", "imageData":"https://interactive-message-testing.s3-us-west-2.amazonaws.com/banana_7.9kb.jpg", "imageDescription":"Banana" } ] }

List picker limits

The following table lists the limits for each of the list picker elements, should you choose to build your own Lambda from scratch. The mandatory parameters are in bold.

To send unlimited options, implement action buttons in your application. For more information, see Implementation of action buttons in interactive message list picker/panel.

Parent field Field Required Minimum characters Maximum characters Other requirement

templateType

Yes

Valid template type

data

Yes

version

Yes

Must be "1.0"

data

content Yes
replyMessage No

content

title Yes

1

400

Should be a description for promptless templates

elements Yes

1 item

10 items

This is an array of elements. Maximum 10 elements in the array. To send unlimited elements, use the action buttons feature.

subtitle No

0

400

imageType No

0

50

Must be "URL"

imageData No

0

200

Must be a valid publicly accessible URL

imageDescription No

0

50

referenceId No

String. Only required for action button feature.

listId No

String. Only required for action button feature.

preIndex No

Number. Only required for action button feature.

nextIndex No

Number. Only required for action button feature.

templateIdentifier No

Number. Should be an UUID. This field is required if List Picker/Panel is being used in a Carousel.

elements

title Yes

1

400

subtitle No

0

400

imageType No

0

50

Must be "URL"

imageData No

0

200

Must be a valid publicly accessible URL

imageDescription No

0

50

Cannot exist without an image

actionDetail No

Only required for action button feature. Must be "PREVIOUS_OPTIONS" or "SHOW_MORE".

replyMessage

title Yes

1

400

subtitle No

0

400

imageType No

0

50

Must be "URL"

imageData No

0

200

Must be a valid publicly accessible URL

imageDescription No

0

50

Cannot exist without an image

Time picker template

The time picker template is useful for enabling customers to schedule appointments. You can provide up to 40 timeslots to the customer in a chat.

The following images show two examples of how the time picker template renders information in a chat.

  • One image shows one date, and under it, one time slot.

  • The second image shows one date, and under it, two time slots.


                The time picker template rendering information in a chat.

The following code is the time picker template that you can use in your Lambda. Note the following:

  • Bold text is a mandatory parameter.

  • In some cases, if the parent element exists in the request and it isn't mandatory/bold, but the fields in it are, then the fields are mandatory. For example, see data.replyMessage structure in the following template. If the structure exists, title is mandatory. Otherwise complete replyMessage is optional.

{ "templateType":"TimePicker", "version":"1.0", "data":{ "replyMessage":{ "title":"Thanks for selecting", "subtitle":"Appointment selected", }, "content":{ "title":"Schedule appointment", "subtitle":"Tap to select option", "timeZoneOffset":-450, "location":{ "latitude":47.616299, "longitude":-122.4311, "title":"Oscar", "radius":1, }, "timeslots":[ { "date" : "2020-10-31T17:00+00:00", "duration": 60, }, { "date" : "2020-11-15T13:00+00:00", "duration": 60, }, { "date" : "2020-11-15T16:00+00:00", "duration": 60, } ], } } } }

Time picker limits

The following table lists the limits for each of the time picker elements. Use this information if you choose to build your own Lambda from scratch. The mandatory parameters are in bold.

Parent field Field Required Minimum characters Maximum characters Other requirement

templateType

Yes

Valid template type

data

Yes

version

Yes

Must be "1.0"

data

replyMessage No
content Yes

replyMessage

title

Yes

1

400

Should be description for promptless templates

subtitle No

0

400

content

title

Yes

1

400

Should be description for promptless templates

subtitle No

0

200

timezone offset No

-720

840

This is an optional field when not set. Our sample client defaults to the user's timezone. If set, this displays per the timezone entered. The field should be an integer representing the number of minutes from GMT, specifying the timezone of the event's location.

location No

timeslots Yes

1

40

This is an array of timeslots. Maximum of 40 elements in the array.

location

longitude Yes

-180

180

Must be double

latitude Yes

-90

90

Must be double

title Yes

1

400

radius

No

0

200

timeslots

date Yes

Should be in ISO-8601 time format: YYYY-MM-DDTHH.MM+00.00

For example:

"2020-08-14T21:21+00.00"

duration Yes

1

3600

Panel template

By using the panel template, you can present the customer with up to 10 choices under one question. However, you can include only one image, rather than an image with each choice.

The follow image shows an example of how the panel template renders information in a chat. It shows an image at the top of the message, and under the image it shows a prompt that asks How can I help? Tap to select option. Under the prompt three options are displayed to the customer: Check self-service options, Talk to an agent, End chat.


                The panel template rendering information in a chat.

The following code is the panel template that you can use in your Lambda. Note the following:

  • Bold text is a mandatory parameter.

  • In some cases, if the parent element exists in the request and it isn't mandatory/bold, but the fields in it are, then the fields are mandatory. For example, see data.replyMessage structure in the following template. If the structure exists, title is mandatory. Otherwise, complete replyMessage is optional.

{ "templateType":"Panel", "version":"1.0", "data":{ "replyMessage":{ "title":"Thanks for selecting!", "subtitle":"Option selected", }, "content":{ "title":"How can I help you?", "subtitle":"Tap to select option", "imageType":"URL", "imageData":"https://interactive-msg.s3-us-west-2.amazonaws.com/company.jpg", "imageDescription":"Select an option", "elements":[ { "title":"Check self-service options", }, { "title":"Talk to an agent", }, { "title":"End chat", } ] } } }

Panel limits

The following table lists the limits for each of the panel elements, should you choose to build your own Lambda from scratch. The mandatory parameters are in bold.

To send unlimited options, implement action buttons in your application. For more information, see Implementation of action buttons in interactive message list picker/panel.

Parent field Field Required Minimum characters Maximum characters Other requirement

templateType

Yes

Valid template type

data

Yes

version

Yes

Must be "1.0"

data

replyMessage No
content Yes

content

title Yes

1

400

Should be a description for promptless templates

subtitle No

0

400

elements Yes

1 item

10 items

This is an array of elements. Maximum 10 elements in the array.

imageType No

0

50

Must be "URL"

imageData No

0

200

Must be a valid publicly accessible URL

imageDescription No

0

50

Cannot exist without an image

referenceId No

String. Only required for action button feature.

listId No

String. Only required for action button feature.

preIndex No

Number. Only required for action button feature.

nextIndex No

Number. Only required for action button feature.

templateIdentifier No

Number. Should be an UUID. This field is required if List Picker/Panel is being used in a Carousel.

elements

title Yes

1

400

actionDetail No

Only required for action button feature. Must be "PREVIOUS_OPTIONS" or "SHOW_MORE".

replyMessage

title Yes

1

400

subtitle No

0

400

Quick reply template

Use quick reply messages to get simple responses from customers and them to customers in an in-line list. You can present customers with up to 5 options in one quick reply message. Images are not supported for quick replies.

The following image shows an example of how the quick reply template renders information in a chat.


                The panel template rendering information in a chat.

The following code is the quick reply template that you can use in your Lambda.

{ "templateType": "QuickReply", "version": "1.0", "data": { "content": { "title": "Which department would you like?", "elements": [ { "title": "Billing" }, { "title": "Cancellation" }, { "title": "New Service" } ] } } }

Quick reply limits

The following table lists the limits for each of the quick reply elements. Use this information if you choose to build your own Lambda from scratch. The mandatory parameters are in bold.

Field Required Minimum characters Maximum characters Other requirement

templateType

Valid template type

data

Yes

version

Yes

Must be "1.0"

content

Yes
title Yes

1

400

Should be a description for promptless templates

elements Yes

2 item

10 items

This is an array of elements. Minimum 2 elements and maximum 10 elements in the array.

title Yes

1

200

Use carousels to display up to 5 list pickers or panels to customers in a single message. Similar to the list picker and time picker, you can add more options to the carousel by using the SHOW_MORE feature.

The following GIF shows an example of how the carousel template renders information in a chat. Customers scroll through the carousel of images by using the left and right arrows.


                A carousel in a customer's chat experience.

The following image shows two Learn More hyperlinks, which are examples of carousel picker hyperlink elements.


                A carousel picker with hyperlinks.

The following code is the carousel template that you can use in your Lambda.

{ "templateType": "Carousel", "version": "1.0", "data": { "content": { "title": "View our popular destinations", "elements": [ { "templateIdentifier": "template0", "templateType": "Panel", "version": "1.0", "data": { "content": { "title": "California", "subtitle": "Tap to select option", "elements": [ { "title": "Book flights" }, { "title": "Book hotels" }, { "title": "Talk to agent" } ] } } }, { "templateIdentifier": "template1", "templateType": "Panel", "version": "1.0", "data": { "content": { "title": "New York", "subtitle": "Tap to select option", "elements": [ { "title": "Book flights" }, { "title": "Book hotels" }, { "title": "Talk to agent" } ] } } } ] } } }

For hosted communications widget users:

  • The selections on the carousel template result in a JSON string response structured like the following example, to be sent back to Lambda (other interactive message types return regular string response with only selectionText value):

    { templateIdentifier: "template0", listTitle: "California", selectionText: "Book hotels" }
  • In carousels, you can provide hyperlinks in the list picker/panel elements. To create a hyperlink instead of a button, include the following additional fields for the element that should be a hyperlink:

    { title: "Book flights", ... type: "hyperlink", url: "https://www.example.com/Flights" }

The following table lists the limits for each of the carousel elements. Use this information if you choose to build your own Lambda from scratch. The mandatory parameters are in bold.

Parent field Field Required Minimum characters Maximum characters Other requirement

templateType

Yes

Valid template type

data

Yes

version

Yes

Must be "1.0"

data

content Yes

content

title Yes

1

400

Should be a description for promptless templates

elements Yes

2 item

5 items

This is an array of either list pickers or panel templates. Only one interactive message type is accepted per carousel. Each element should include the top-level field templateIdentifier. Minimum 2 templates and maximum 5 templates in the array.

Note

For the best customer experience, we recommend that each template has consistent use of images/number of elements.

omitTitleFromCarouselResponse No

Boolean - Optionally respond with "SelectionText" instead of the default "PickerTitle: SelectionText".

carouselIsVertical No

Boolean - Optionally render Carousel elements with vertical scroll.

You can add rich formatting to the titles and subtitles of your chat messages. For example, you can add links, italics, bold, numbered lists, and bulleted lists. You use markdown to format your text.

The following image of a chat box shows an example list picker with rich formatting in the title and subtitle.

  • The title How can we help? aws.amazon.com is bold and contains a link.

  • The subtitle contains italics and bold text, a bulleted list, and a numbered list. It also shows a plain link, text link, and sample code.

  • The bottom of the chat box shows three list picker elements.


                A chat box, a title with a link, a subtitle with lists and links.

How to format text with markdown

You can write title and subtitle strings in a multi-line format, or in a single line with `\r\n` line break characters.

  • Multi-line format: The following code sample shows how to author lists in markdown in a multi-line format.

    const MultiLinePickerSubtitle = `This is some *emphasized text* and some **strongly emphasized text** This is a bulleted list (multiline): * item 1 * item 2 * item 3 This is a numbered list: 1. item 1 2. item 2 3. item 3 Questions? Visit https://plainlink.com/faq [This is a link](https://aws.amazon.com) This is \`\` ` const PickerTemplate = { templateType: "ListPicker|Panel", version: "1.0", data: { content: { title: "How can we help?", subtitle: MultiLinePickerSubtitle, elements: [ /* ... */ ] } } }
  • Single line format: The following example shows how to author a subtitle in a single line by using `\r\n` line break characters.

    const SingleLinePickerSubtitle = "This is some *emphasized text* and some **strongly emphasized text**\r\nThis is a bulleted list:\n* item 1\n* item 2\n* item 3\n\nThis is a numbered list:\n1. item 1\n2. item 2\n3. item 3\n\nQuestions? Visit https://plainlink.com/faq\r\n[This is a link](https://aws.amazon.com)\r\nThis is `<code/>`"; const PickerTemplate = { templateType: "ListPicker|Panel", version: "1.0", data: { content: { title: "How can we help?", subtitle: SingleLinePickerSubtitle, elements: [ /* ... */ ] } } }

The following example shows how format italics and bold text with markdown:

This is some *emphasized text* and some **strongly emphasized text**

The following example shows how to format text as code with markdown:

This is `<code />`

How to format links with markdown

To create a link, use the following syntax:

[aws](https://aws.amazon.com)

The following examples show two ways you can add links with markdown:

Questions? Visit https://plainlink.com/faq

[This is a link](https://aws.amazon.com)