Google Assistant

Text


text

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 second
    

For 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

carousel

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

basic card

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.

list view

list view

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
  • email

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' },
]);

Google Assistant


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.