Google Assistant
Text
For basic text messages
bot.say('Hello world!');
Text messages can contain both text and speech tags. This allows for a distinction between what is printed in thread, and what is read out loud to the user.
Note: the speech tag will only be used if the user interacts with the bot with his/her voice.
const msg = {
text: 'this will be printed on the screen',
speech: 'this will be read aloud',
};
bot.say([msg]);
The speech tag can also contain SSML
const msg = {
text: 'this will be printed on the screen',
speech: '<speak>Hello!<break time="1s" />Welcome to the<sub alias="Content Management System">CMS</sub></speak>',
};
bot.say([msg]);
Text Rules
- 640 character limit per message
- At most 2 text messages per state
Audio
To play an audio file, use the audio tag
const audioMessage = {
audio: 'https://actions.google.com/sounds/v1/cartoon/magic_chime.ogg'
};
bot.say([auidioMessage]);
Audio files can also be played along with text using SSML.
const audioMessage = {
text: 'a cat purring',
speech: '<speak><audio src="https://actions.google.com/sounds/v1/animals/cat_purr_close.ogg"><desc>a cat purring</desc>PURR (sound didn\'t load)</audio></speak>',
};
bot.say([audioMessage]);
Audio Rules
The following are the currently supported settings for audio:
- Format: MP3 (MPEG v2)
24K samples per second
24K ~ 96K bits per second, fixed rate- Format: Opus in Ogg
24K samples per second (super-wideband)
24K - 96K bits per second, fixed rate- Format (deprecated): WAV (RIFF)
PCM 16-bit signed, little endian
24K samples per secondFor all formats
- Single channel is preferred, but stereo is acceptable.
- 120 seconds maximum duration.
- 5 megabyte file size limit.
- Source URL must use HTTPS protocol.
Images
Images can be sent using the imageUrl tag
const imageUrl = 'https://yourImageUrl.jpg';
bot.say([{ imageUrl }]);
Note
GIFs are supported
Carousels
Carousels prompt a user to select an item from a horizontally paging list.
Carousel cards are built with the following keys
Key | type | Description |
---|---|---|
title | string | title of the card |
subtitle | string | subtitle of the card |
imageUrl | string | the image to be shown on the card |
imgAccessibilityText | string | (optional) a short description of the card's image |
buttons | array | (optional) an array of length 1 containing an object with a key of meta |
meta | object | (optional) alternative to buttons array an object with some meta data |
const elements = [
{
title: 'location 1',
subtitle: '0.5 miles away',
imageUrl: 'https://location1.png',
// place meta information inside a button array
buttons: [{ meta: { phoneNumber: '555-787-1122' } }],
},
{
title: 'location 2',
subtitle: '2 miles away',
imageUrl: 'https://location2.png',
imgAccessibilityText: 'a brightly lit retail store',
// alternatively, can put meta as a top level key
meta: { phoneNumber: '555-238-6789' },
},
{
title: 'location 3',
subtitle: '4.5 miles away',
imageUrl: 'https://location3.png',
imgAccessibilityText: 'a brightly lit retail store',
// or no button meta at all
},
];
bot.say([{ text: 'I found some locations near you.' }, { elements }]);
Carousel Rules
- Must be lead by a text message
- GIFs are supported
- Maximum 10 items
- Minimum 2 items
- Card title required and must be unique
- Image and subtitle optional
- Subtitles have 4 line maximum
If your carousel contains only 1 card, it will be sent as a Basic Card
In addition to the keys available to carousel cards, Basic Cards can also contain:
Key | type | Description |
---|---|---|
body | string | (optional) offers a space for a more detailed description |
imageDisplayOptions | string | (optional) options for cropping/fitting the image into the card. Values include DEFAULT, WHITE, and CROPPED |
const card = [
title: 'awesome card',
subtitle: 'awesome subtitle',
body: 'click the button below to watch our website redesign!',
imageUrl: 'https://stickers.snaps.photo/54e4ead2f161850300207080/production/594c1f23f40c99030d4be657.jpg',
imgAccessibilityText: 'the flatiron building',
imageDisplayOptions: 'CROPPED',
buttons: [
{
title: 'our new website',
url: 'https://www.google.com',
},
],
];
const elements = [card];
bot.say([{ text: 'here\'s a basic card!' }, { elements }]);
Basic Card Rules
- Must be lead by a text message
- The card's button must be a url button
- Image and or text body required
- Title, subtitle, link button optional
- Text body must not contain a link
- With an image, text body is limited to 10 lines
- Without an image, text body is limited to 15 lines
List Views
List views prompt a user to select an item from a vertical list.
Unlike Carousels, List Views are objects that have and array of 'cards'. On each card the following keys are allowed.
Key | type | Description |
---|---|---|
title | string | title of the card |
subtitle | string | (optional) subtitle of the card |
imageUrl | string | (optional) the image to be shown on the card |
imgAccessibilityText | string | (optional) a short description of the card's image |
buttons | array | (optional) an array of length 1 containing an object with a key of meta |
meta | object | (optional) alternative to buttons array an object with some meta data |
const listView = {
cards: [
{
title: 'option 1',
subtitle: 'hello',
imageUrl: 'https://image1.png',
buttons: [{meta: { data: 5 } }],
},
{
title: 'option 2',
subtitle: 'hello',
imageUrl: 'https://image2.png',
meta: { data: 5 },
},
{
title: 'option 3',
subtitle: 'hello',
imageUrl: 'https://image3.png',
imgAccessibilityText: 'my emoji',
},
],
};
bot.say([{ text: 'here is a list!' }, { listView }]);
List View Rules
- Maximum 30 cards
- Minimum 2 cards
- Card titles required must be unique
Suggestion Chips
Similar to quick replies, suggestion chips help to guide the user.
Chip selections are received as free text, not as a postback.
const options = [{ title: 'pick me!' }, { title: 'no, pick me!'}];
bot.say([{ text: 'here are some chips.' }], options);
Suggestion Chip Rules
- Must be lead by a text message
- Maximum 8 per state
Link Out Chips
Simply a suggestion chip that links out. They can exist on their own or with standard suggestion chips.
const options = [];
options.push({ title: 'first option'}); // regular chip
options.push({ title: 'Google', url: 'https://www.google.com'}); // link out chip
bot.say([{ text: 'here\'s a link out chip.' }], options);
Link Out Chip Rules
- Only 1 per state
- Must be lead by a text message
- Will always appear after suggestion chips
- Chip's title will always be prepended with "Open "
Permissions
Permissions are a way of obtaining information from the user. After a permission request is made, Google takes control of the conversation for a turn. Once the user has accepted/denied the permission, control is given back to the bot with the result.
Permission requests require a request context and a permission array. The context is displayed just before the prompt as a separate text bubble.
Supported permission types:
- NAME (first and last name)
- EMAIL (email address)
- DEVICE_PRECISE_LOCATION (lat/lng)
bot.say([
{
permissionRequest: {
requestContext: 'To show weather forcasts near you,',
permissions: ['DEVICE_PRECISE_LOCATION'],
}
},
]);
If the user agrees to the request, the results can be found on context.session
- first_name
- last_name
- lat
- long
Final Response
In some situations, it's appropriate for the bot to terminate the conversation (perhaps the user fails to pass through an age gate).
A response can be marked as a final response by passing a message object with the key of finalResponse into the message array. The user should never be prompted for input with a final response.
bot.say([
{ finalResponse: true },
{ text: 'goodbye' },
]);
Updated over 4 years ago