Dialogflow Messenger fulfillment

When creating a custom card fulfillment, you can create Text Responses and Custom Payloads. The text responses are used for plain text and Markdown agent responses, and the custom payloads are used for rich responses. The custom payload format for all response types has the following basic structure:

{
  "richContent": [
    [
      {
        "type": "type-id",
        ...
      },
      {
        "type": "type-id",
        ...
      }
    ],
    [
      {
        "type": "type-id",
        ...
      },
      {
        "type": "type-id",
        ...
      }
    ]
  ]
}

Note that the richContent value allows one outer and multiple inner arrays. Responses within an inner array are bound together in a single visual card. When the outer array contains multiple inner arrays, multiple cards are shown—one for each inner array.

The remaining subsections describe the various types of responses you can configure for a custom payload.

Text response

Dialogflow Messenger text screenshot

The text response supports plain text and Markdown. Here are a few Markdown examples:

  • *Italic*
  • **Bold**
  • # Title
  • [Link text](Link URL)
  • ![](Image URL)

  • Tables:

    Header 1 | Header 2
    -------- | --------
    Cell 1   | Cell 2
    

Info response type

Dialogflow Messenger info type screenshot

The info response type is a simple title card that users can click or touch.

The following table describes the fields:

Name Type Description
type string Response type: "info"
title string Card title
subtitle string Card subtitle
image object Image
image.rawUrl string Public URL for image
anchor object Anchor to follow when element is clicked
anchor.href string URL of the anchor
anchor.target string Target of the anchor, defaults to _blank

For example:

{
  "richContent": [
    [
      {
        "type": "info",
        "title": "Info item title",
        "subtitle": "Info item subtitle",
        "image": {
          "rawUrl": "https://example.com/images/logo.png"
        },
        "anchor": {
          "href": "https://example.com"
        }
      }
    ]
  ]
}

Description response type

Dialogflow Messenger description type screenshot

The description response type is an informative card that can have multiple lines of text.

The following table describes the fields:

Name Type Description
type string Response type: "description"
title string Card title
text array<string> Array of strings, where each string is rendered on a new line

For example:

{
  "richContent": [
    [
      {
        "type": "description",
        "title": "Description title",
        "text": [
          "This is text line 1.",
          "This is text line 2."
        ]
      }
    ]
  ]
}

Image response type

Dialogflow Messenger image type screenshot

The image response type is an image card that users can click or touch.

The following table describes the fields:

Name Type Description
type string Response type: "image"
rawUrl string Public URL for image
accessibilityText string Alt text for image

For example:

{
  "richContent": [
    [
      {
        "type": "image",
        "rawUrl": "https://example.com/images/logo.png",
        "accessibilityText": "Example logo"
      }
    ]
  ]
}

The following CSS variables can be provided:

Properties Input policy Default value Description
df-messenger-image-border-radius Optional 8px Border radius of the image

Video response type

Dialogflow Messenger video type screenshot

The video response type renders a video element that can either be a direct video from URL, played directly in the messenger, or a link to a video.

Name Type Description
type string Response type: "video"
title string Optional video title
source object The video's source
source.type string A type of video source, either link or raw
source.anchor object Anchor to follow when element is clicked
source.embeddedPlayer string A link type video may be embedded rather than link to the player's web page. This is only implemented for a known set of players, supports youtube.
source.thumbnail object Thumbnail to show for the anchor
source.thumbnail.rawUrl string The URL of the thumbnail
source.rawUrl string URL for a raw type video

For example:

{
  "richContent": [
    [
      {
        "type": "video",
        "source": {
          "type": "link",
          "anchor": {
            "href": "https://www.youtube.com/watch?v=cNfINi5CNbY"
          }
        }
      }
    ]
  ]
}

The following CSS variables can be provided:

Properties Input policy Default value Description
df-messenger-video-width Optional auto Width of a video (limited by max-width\: 100%)
df-messenger-video-height Optional auto Height of a video
df-messenger-video-embed-width Optional 560px Width of an embedded video (limited by max-width\: 100%)
df-messenger-video-embed-height Optional 315px Height of an embedded video
df-messenger-video-border Optional 1px solid #e0e0e0 Border of the video
df-messenger-video-border-radius Optional 8px Border radius of the video

Button response type

Dialogflow Messenger button type screenshot

The button response type is a small button with an icon that users can click or touch.

The following table describes the fields:

Name Type Description
type string Response type: "button"
icon object Icon for button
icon.type string Icon from the Material icon library. The default icon is an arrow
icon.color string Color hexcode
image object Image for the button, takes priority over icon
image.rawUrl string Public URL for image
mode string Optional, if set to "blocking", user input is disabled until the user clicks the button
text string Button text
anchor object Anchor to follow when element is clicked
anchor.href string URL of the anchor
anchor.target string Target of the anchor, defaults to _blank
event object Dialogflow event that is triggered when the button is clicked.

For example:

{
  "richContent": [
    [
      {
        "type": "button",
        "icon": {
          "type": "chevron_right",
          "color": "#FF9800"
        },
        "mode": "blocking",
        "text": "Button text",
        "anchor": {
          "href": "https://example.com"
        },
        "event": {
          "event": ""
        }
      }
    ]
  ]
}

The following CSS variables can be provided:

Properties Input policy Default value Description
df-messenger-button-border Optional none Border of a button
df-messenger-button-border-radius Optional 8px Border radius of a button
df-messenger-button-font-color Optional #1f1f1f Text color of a button
df-messenger-button-font-family Optional "Google Sans", "Helvetica Neue", sans-serif Font family of a button
df-messenger-button-font-size Optional 14px Font size of a button
df-messenger-button-padding Optional 12px Padding of a button
df-messenger-button-icon-spacing Optional 12px Space between button icon and text
df-messenger-button-icon-font-size Optional 24px Size of the button icon
df-messenger-button-image-size Optional 24px Size of the button image
df-messenger-button-image-offset Optional 0 Offset of the button image, allows negative values to offset padding
df-messenger-button-text-align Optional center Text align of a button
df-messenger-button-text-wrap Optional normal Use nowrap to disallow multi-line buttons

List response type

Dialogflow Messenger list type screenshot

The list response type is a card with multiple options users can select from.

The response contains an array of list and divider response types. The following table describes the list type:

Name Type Description
type string Response type: "list"
title string Option title
subtitle string Option subtitle
event object Dialogflow event that is triggered when the option is clicked
anchor object Anchor to follow when element is clicked
anchor.href string URL of the anchor
anchor.target string Target of the anchor, defaults to _blank
image object Image
image.rawUrl string Public URL for image

The following table describes the divider type:

Name Type Description
type string Response type: "divider"

For example:

{
  "richContent": [
    [
      {
        "type": "list",
        "title": "List item 1 title",
        "subtitle": "List item 1 subtitle",
        "event": {
          "event": ""
        }
      },
      {
        "type": "list",
        "title": "List item 2 title",
        "subtitle": "List item 2 subtitle",
        "event": {
          "event": ""
        }
      }
    ]
  ]
}

The following CSS variables can be provided:

Properties Input policy Default value Description
df-messenger-list-padding Optional 16px Padding of a list element
df-messenger-list-inset Optional 0 Additional horizontal "inset" of the list element (in addition to the padding), to control the expansion of the border between elements
df-messenger-list-spacing Optional 10px Vertical space between list elements
df-messenger-list-border-bottom Optional 1px solid #e0e0e0 Border between list elements

Accordion response type

Dialogflow Messenger accordion type screenshot

The accordion response type is a small card that a user can click or touch to expand and reveal more text.

The following table describes the fields:

Name Type Description
type string Response type: "accordion"
title string Accordion title
subtitle string Accordion subtitle
image object Image
image.rawUrl string Public URL for image
text string Accordion text

For example:

{
  "richContent": [
    [
      {
        "type": "accordion",
        "title": "Accordion title",
        "subtitle": "Accordion subtitle",
        "image": {
          "rawUrl": "https://example.com/images/logo.png"
        },
        "text": "Accordion text"
      }
    ]
  ]
}

Suggestion chip response type

Dialogflow Messenger chips type screenshot

The suggestion chip response type provides the end-user with a list of clickable suggestion chips.

The following table describes the fields:

Name Type Description
type string Response type: "chips"
options array<object> Array of Option objects
options[].mode string Optional, if set to "blocking", user input is disabled until the user clicks the chip
options[].text string Option text
options[].image object Optional, option Image
options[].image.rawUrl string Option public URL for image
options[].anchor object Optional, Anchor to follow when element is clicked
options[].anchor.href string URL of the anchor
options[].anchor.target string Target of the anchor, defaults to _blank

For example:

{
  "richContent": [
    [
      {
        "type": "chips",
        "options": [
          {
            "mode": "blocking",
            "text": "Chip 1",
            "image": {
              "rawUrl": "https://example.com/images/logo.png"
            },
            "anchor": {
              "href": "https://example.com"
            }
          },
          {
            "text": "Chip 2",
            "image": {
              "rawUrl": "https://example.com/images/logo.png"
            },
            "anchor": {
              "href": "https://example.com"
            }
          }
        ]
      }
    ]
  ]
}

The following CSS variables can be provided:

Properties Input policy Default value Description
df-messenger-chips-spacing Optional 10px Space above the chips to the preceding message
df-messenger-chips-border-color Optional #e0e0e0 Border color of a chip
df-messenger-chips-border-color-hover Optional #e0e0e0 Border color of a chip when hovered
df-messenger-chips-border-radius Optional 999px Border radius of a chip
df-messenger-chips-background Optional white Background of a chip
df-messenger-chips-background-hover Optional rgba(68, 71, 70, 0.08) Background of a chip when hovered
df-messenger-chips-padding Optional 6px 16px Padding of a chip
df-messenger-chips-font-color Optional black Text color of a chip
df-messenger-chips-font-family Optional "Google Sans", "Helvetica Neue", sans-serif Font family of a chip
df-messenger-chips-font-size Optional 14px Text size of a chip
df-messenger-chips-font-weight Optional normal Font weight of a chip
df-messenger-chips-font-weight-hover Optional normal Font weight of a chip when hovered
df-messenger-chips-box-shadow Optional 0 2px 2px 0 rgba(0, 0, 0, 0.24) Box shadow of a chip
df-messenger-chips-content-align Optional flex-start Vertical alignment of the content (e.g. the image) in a chip
df-messenger-chips-text-wrap Optional nowrap Use normal to allow multi-line chips

Citations response type

Dialogflow Messenger citations type screenshot

The citations response type provides the end-user with a list of clickable citation links.

The following table describes the fields:

Name Type Description
type string Response type: "match_citations"
citations array<object> Array of Citation objects
citations[].title string Citation title
citations[].subtitle string Citation subtitle (currently ignored)
citations[].anchor object Anchor to follow when element is clicked
citations[].anchor.href string URL of the anchor
citations[].anchor.target string Target of the anchor, defaults to _blank

For example:

{
  "richContent": [
    [
      {
        "type": "match_citations",
        "citations": [
          {
            "title": "Source 1",
            "subtitle": "",
            "anchor": {
              "href": "https://example.com/1"
            }
          },
          {
            "title": "Source 2",
            "subtitle": "",
            "anchor": {
              "href": "https://example.com/2"
            }
          }
        ]
      }
    ]
  ]
}

The following CSS variables can be provided:

Properties Input policy Default value Description
df-messenger-citations-spacing Optional 10px Space above the citations to the preceding message
df-messenger-citations-message-display Optional block Defines display of the note above citations, allowed values are block or none
df-messenger-citations-message-font-color Optional #041e49 Text color of the note above citations
df-messenger-citations-message-font-size Optional 12px Text size of the note above citations
df-messenger-citations-flex-direction Optional row Flex direction property of the citations, recommended to use row (horizontal with line breaks) or column (vertical)
df-messenger-citations-border-color Optional #1a73e8 Border color of a citation
df-messeenger-citations-border-color-hover Optional #1a73e8 Border color of a citation when hovered
df-messenger-citations-border-radius Optional 4px Border radius of a citation
df-messenger-citations-padding Optional 8px Padding of a citation
df-messenger-citations-background Optional white Background of a citation
df-messenger-citations-background-hover Optional rgba(68, 71, 70, 0.08) Background of a citation when hovered
df-messenger-citations-font-color Optional #1a73e8 Text color of a citation
df-messenger-citations-font-family Optional "Google Sans", "Helvetica Neue", sans-serif Font family of a citation
df-messenger-citations-font-size Optional 11px Text size of a citation
df-messenger-citations-icon-font-size Optional 14px Text size of the icon of a citation
df-messenger-citations-font-weight Optional normal Font weight of a citation
df-messenger-citations-font-weight-hover Optional normal Font weight of a citation when hovered
df-messenger-citations-icon-spacing Optional 4px Space between icon and text in a citation
df-messenger-citations-box-shadow Optional none Box shadow of a citation

HTML response type

Dialogflow Messenger html type screenshot

The HTML response type provides the end-user with a HTML message.

The following table describes the fields:

Name Type Description
type string Response type: "html"
html string Text content of the message, supports HTML

Supported HTML tags:

  • a - Anchor element (used for creating hyperlinks)
  • b - Bold element (used for bolding text)
  • i - Italic element (used for italicizing text)
  • u - Underline element (used for underlining text)
  • h1 - Heading 1 element (used for the main heading of a page)
  • h2 - Heading 2 element (used for subheadings)
  • h3 - Heading 3 element (used for sub-subheadings)
  • p - Paragraph element (used for creating paragraphs of text)
  • br - Line break element (used for creating line breaks within a paragraph)
  • table - Table element (used for creating tables)
  • tr - Table row element (used for creating rows within a table)
  • thead - Table header element (used for creating a header within a table)
  • th - Table header data or cell element (used for creating cells within a table header row)
  • tbody - Table body element (used for creating a body within a table)
  • td - Table data or cell element (used for creating cells within a table row)
  • ul - Unordered list element (used for creating bulleted lists)
  • ol - Ordered list element (used for creating numbered lists)
  • li - List item element (used for creating items within a list)
  • img - Image element (used for showing an image, see also url-allowlist HTML customization)
  • div - Container element
  • span - Inline container element

For example:

{
  "richContent": [
    [
      {
        "type": "html",
        "html": "<b>Bold text</b> <i>Italic text</i> <u>Underlined text</u>"
      }
    ]
  ]
}

Styling HTML and Markdown

For anchor elements (HTML a element and Markdown link), the following CSS variables can be provided:

Properties Input policy Default value Description
df-messenger-link-decoration Optional underline Decoration of a link element
df-messenger-link-font-color Optional #0b57d0 Font color of an unvisited link element
df-messenger-link-visited-font-color Optional #0b57d0 Font color of a visited link element
df-messenger-link-hover-font-color Optional #0b57d0 Font color when hovering a link element
df-messenger-link-background Optional transparent Background of a link element
df-messenger-link-padding Optional 0 Padding of a link element
df-messenger-link-border Optional none Border of a link element
df-messenger-link-border-radius Optional 0 Border radius of a link element

For table elements (HTML table element and Markdown tables), the following CSS variables can be provided:

Properties Input policy Default value Description
df-messenger-table-font-size Optional 14px Text size in a table element
df-messenger-table-font-color Optional #1f1f1f Text color in a table element
df-messenger-table-align Optional left Alignment of text in a table cell
df-messenger-table-padding Optional 0 Padding in a table cell
df-messenger-table-border-collapse Optional separate Border collapse mode of a table, use separate to enable border-radius
df-messenger-table-border-radius Optional 0 Border radius of a table
df-messenger-table-header-border-radius Optional 0 Border radius of the table header
df-messenger-table-border-top Optional none Border top of a table row
df-messenger-table-border-top-first Optional none Border top of the first table row
df-messenger-table-border-bottom Optional none Border bottom of a table row
df-messenger-table-border-bottom-last Optional none Border bottom of the last table row
df-messenger-table-border-left Optional none Border left of a table cell
df-messenger-table-border-left-first Optional none Border left of the first table cell in a row
df-messenger-table-border-right Optional none Border right of a table cell
df-messenger-table-border-right-last Optional none Border right of the last table cell in a row
df-messenger-table-background Optional transparent Background of a table row
df-messenger-table-even-background Optional transparent Background of even numbered table rows
df-messenger-table-odd-background Optional transparent Background of odd numbered table rows
df-messenger-table-header-font-size Optional 14px Text size in a table header element
df-messenger-table-header-font-weight Optional bold Font weight in a table header element
df-messenger-table-header-font-color Optional #1f1f1f Text color in a table header element
df-messenger-table-header-align Optional left Alignment of text in a table header cell
df-messenger-table-header-padding Optional 0 Padding in a table header cell
df-messenger-table-header-border-top Optional none Border top of the table header row
df-messenger-table-header-border-bottom Optional none Border bottom of the table header row
df-messenger-table-header-border-left Optional none Border left of a cell in the table header row
df-messenger-table-header-border-left-first Optional none Border left of the first cell in the table header row
df-messenger-table-header-border-right Optional none Border right of a cell in the table header row
df-messenger-table-header-border-right-last Optional none Border right of the last cell in a table header row
df-messenger-table-header-background Optional transparent Background of the table header row

Custom Template response type

Dialogflow Messenger custom template type screenshot

The custom template response type renders a custom element defined on the customer's website. The element is not placed inside a card and always stands on its own.

The following table describes the fields:

Name Type Description
type string Response type: "custom_template"
name string Name of the custom element
payload Object Payload to pass to the custom element

For example:

{
  "richContent": [
    [
      {
        "type": "custom_template",
        "name": "custom-element-example",
        "payload": {
          "text": "Hello World"
        }
      }
    ]
  ]
}

On your website, the custom element needs to be registered under the exact name from the name field of the response. The payload field is passed to the custom element as dfPayload after construction (but before connectedCallback). The field may contain arbitrary JSON. In addition, dfResponseId is passed to the element.

Using the response from the example, here is an example implementation of a custom element:

class CustomElementExample extends HTMLElement {
  constructor() {
    super();
    // The `dfPayload` field will be provided before `connectedCallback` is
    // being called.
    this.dfPayload = null;
    // The `dfResponseId` field will be provided before `connectedCallback` is
    // being called.
    this.dfResponseId = null;
    // It is not strictly required but recommended to contain the custom
    // element in a shadow root.
    // https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot
    this.renderRoot = this.attachShadow({mode: 'open'});
  }

  /** Web component Lifecycle method. */
  connectedCallback() {
    const div = document.createElement('div');

    // The `.text` must match the payload's structure in `richContent.payload`.
    div.innerText = this.dfPayload.text;

    this.renderRoot.appendChild(div);
  }
}

(function() {
  // Registers the element. This name must match the name in
  // `richContent.payload`.
  customElements.define('custom-element-example', CustomElementExample);
})();

Combining response types

Dialogflow Messenger custom card screenshot

The individual rich message elements for Dialogflow Messenger can be used to construct a custom card to fit your needs.

Here's an example using some of the elements listed in the fulfillment section:

{
  "richContent": [
    [
      {
        "type": "image",
        "rawUrl": "https://example.com/images/logo.png",
        "accessibilityText": "Dialogflow across platforms"
      },
      {
        "type": "info",
        "title": "Dialogflow",
        "subtitle": "Build natural and rich conversational experiences",
        "anchor": {
          "href": "https://cloud.google.com/dialogflow/docs"
        }
      },
      {
        "type": "chips",
        "options": [
          {
            "text": "Case Studies",
            "anchor": {
              "href": "https://cloud.google.com/dialogflow/case-studies"
            }
          },
          {
            "text": "Docs",
            "anchor": {
              "href": "https://cloud.google.com/dialogflow/docs"
            }
          }
        ]
      }
    ]
  ]
}

The following CSS variables can be provided:

Properties Input policy Default value Description
df-messenger-card-background Optional white Background of a custom card
df-messenger-card-padding Optional 16px Padding of elements in a custom card
df-messenger-card-border Optional 1px solid #e0e0e0 Border of a custom card
df-messenger-card-border-radius Optional 8px Border radius of a custom card
df-messenger-card-border-top-left-radius Optional 8px Border radius top left of a custom card
df-messenger-card-border-top-right-radius Optional 8px Border radius top right of a custom card
df-messenger-card-border-bottom-left-radius Optional 8px Border radius bottom left of a custom card
df-messenger-card-border-bottom-right-radius Optional 8px Border radius bottom right of a card
df-messenger-card-stack-border-top-left-radius Optional 8px Border radius top left for consecutive custom cards overrides top left radius
df-messenger-card-stack-border-top-right-radius Optional 8px Border radius top right for consecutive custom cards overrides top right radius
df-messenger-card-stack-border-bottom-left-radius Optional 8px Border radius bottom left for consecutive custom cards overrides bottom left radius
df-messenger-card-stack-border-bottom-right-radius Optional 8px Border radius bottom right for consecutive custom cards overrides bottom right radius
df-messenger-card-box-shadow Optional 0 2px 2px 0 rgba(0, 0, 0, 0.24) Box shadow of a custom card