Add automation with Dialogflow

Dialogflow is a natural language understanding (NLU) tool that processes user input, maps it to known intents, and responds with appropriate replies. There are two editions of Dialogflow. By integrating your Business Messages agent with Dialogflow ES, you can easily create simple automation to jumpstart your agent development. By integrating with Dialogflow CX, you can create advanced automation for more complex conversations.

Business Messages agents support direct integrations with

Dialogflow ES: intent matching and FAQ bots
Dialogflow CX: intent matching and live agent handoff

To integrate a Business Messages agent with other features of Dialogflow ES or Dialogflow CX, refer to each product's documentation.

When a user sends a message to an agent that has a Dialogflow integration, Business Messages passes the user message to Dialogflow and sends Dialogflow's response to the agent in the message's dialogflowResponse object. You can configure agents to automatically send Dialogflow's response to the user without any action on your part. See Auto-responses for details.

Dialogflow integration

Before you can leverage Dialogflow-based automation through Business Messages, you need to enable the Dialogflow integration.

Prerequisites

To get started, you need

a Business Messages agent
a Dialogflow agent in the Global region with a root language of English (en)

If you don't have a Dialogflow agent, create one.

Dialogflow ES

Before you can enable a Dialogflow ES integration, you need your Dialogflow agent's project ID. To locate the project ID,

Navigate to the Dialogflow Console.
Select the Dialogflow agent you want to connect to Business Messages, then click the gear icon next to the agent name.
Under Google Project, note the Project ID value.

Dialogflow CX

Before you can enable a Dialogflow CX integration, you need your Dialogflow agent's project ID and agent ID. To locate these IDs,

Navigate to the Dialogflow CX Console.
Select your Dialogflow project.
In the agent selector, click the overflow menu next to your Dialogflow agent.
Click Copy name. This copies the full name of your agent in the following format: projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID.
Note the project ID and agent ID values.

Enable the integration

In the Business Communications Developer Console, navigate to Integrations.
For Dialogflow, click Enable integration.
Click Connect existing model.
For Dialogflow edition, select the edition to enable.
Enter your Dialogflow agent's project ID.
To enable Dialogflow CX, also enter your Dialogflow agent's agent ID.
If you want Business Messages to automatically respond to users with Dialogflow responses, select Enable auto-response.
Click Next.
Copy the service account email. This account connects your Business Messages and Dialogflow agents.
In the Google Cloud Console, select your Dialogflow project.
Navigate to IAM permissions.
Click Add, and enter the service account email for New principals.
For Select a role, select Dialogflow Console Agent Editor.
Click Add another role and select Dialogflow API Client.
Click Save.
In the Business Communications Developer Console, click Next.
Click Start integration.

It takes about two minutes to connect Business Messages and Dialogflow.

Update the integration

In the Business Communications Developer Console, navigate to Integrations.
Click the gear icon next to Dialogflow.
Toggle Enable auto-response, depending on whether or not you want Business Messages to automatically respond to users with Dialogflow responses.

Switch between Dialogflow editions

A Business Messages agent can only support one Dialogflow integration at a time. To switch from one Dialogflow edition to another, you need to disable the current integration before enabling the new one.

Disable the integration

In the Business Communications Developer Console, navigate to Integrations.
Click the gear icon next to Dialogflow.
Click Disable integration.
Click Disable.

It takes about one minute to disable an existing Dialogflow integration.

Enable a new Dialogflow integration by following these steps.

Intent matching

After you enable the Dialogflow integration for a Business Messages agent, your agent can use your Dialogflow project's configured intents to understand and respond to user questions without you having to write code. To learn more about intents, see the documentation for Dialogflow ES and Dialogflow CX.

Configure your Dialogflow intents for every conversational option you intend to support through automation. Business Messages agents rely on Dialogflow to understand user messages.

When calling the Dialogflow APIs, Business Messages passes the user message payload to your intents and your fulfillment webhook. When a user message is matched with an intent, you can access this payload in Struct format in the business_messages_payload field within QueryParameters.

The payload contains all fields from the user message except for DialogflowResponse.

For Dialogflow CX, Business Messages also passes a session parameter called channel with value google_business_messages to your intents and you can reference it in your agent with the following format: $session.params.channel.

This parameter can be used to add conditionals to your Dialogflow fulfillments in order to support multiple channels in the same Dialogflow agent.

For more on query parameters, see the Dialogflow ES and Dialogflow CX references.

Prerequisites

When creating NLU models within Dialogflow, you can configure different response types for an intent. Business Messages supports the Default response, which can include the following:

Text
Custom payload
Live agent handoff (Dialogflow CX only)

A custom payload must match a valid Business Messages JSON message response object. When configuring custom payload responses for an intent, Business Messages ignores the following fields:

name
messageId
representative

See the following sample responses.

Text with suggestions

{
  "text": "Hello World!",
  "fallback": "Hello World!\n\nReply with \"Hello\" or \"Hi!\"",
  "suggestions": [
    {
      "reply": {
        "text": "Hello",
        "postbackData": "hello-formal"
      }
    },
    {
      "reply": {
        "text": "Hi!",
        "postbackData": "hello-informal"
      }
    }
  ]
}

Rich card

{
  "fallback": "Hello, world!\nSent with Business Messages\n\nReply with \"Suggestion #1\" or \"Suggestion #2\"",
  "richCard": {
    "standaloneCard": {
      "cardContent": {
        "title": "Hello, world!",
        "description": "Sent with Business Messages.",
        "media": {
          "height": "TALL",
          "contentInfo":{
            "altText": "Google logo",
            "fileUrl": "https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png",
            "forceRefresh": "false"
          }
        },
        "suggestions": [
          {
            "reply": {
              "text": "Suggestion #1",
              "postbackData": "suggestion_1"
            }
          },
          {
            "reply": {
              "text": "Suggestion #2",
              "postbackData": "suggestion_2"
            }
          }
        ]
      }
    }
  }
}

Rich card carousel

{
  "fallback": "Card #1\nThe description for card #1\n\nCard #2\nThe description for card #2\n\nReply with \"Card #1\" or \"Card #2\"",
  "richCard": {
    "carouselCard": {
      "cardWidth": "MEDIUM",
      "cardContents": [
        {
          "title": "Card #1",
          "description": "The description for card #1",
          "suggestions": [
            {
              "reply": {
                "text": "Card #1",
                "postbackData": "card_1"
              }
            }
          ],
          "media": {
            "height": "MEDIUM",
            "contentInfo": {
              "fileUrl": "https://my.files/cute-dog.jpg",
              "forceRefresh": false
            }
          }
        },
        {
          "title": "Card #2",
          "description": "The description for card #2",
          "suggestions": [
            {
              "reply": {
                "text": "Card #2",
                "postbackData": "card_2"
              }
            }
          ],
          "media": {
            "height": "MEDIUM",
            "contentInfo": {
              "fileUrl": "https://my.files/elephant.jpg",
              "forceRefresh": false
            }
          }
        }
      ]
    }
  }
}

Live agent handoff

{
  "metadata": {}
}

FAQ bots

After you enable a Dialogflow ES integration for a Business Messages agent, you can create an FAQ bot. When you supply questions and answers as a supported knowledge document, Business Messages and Dialogflow create the necessary infrastructure to understand and respond to user questions without you having to write code.

To see an FAQ bot in action, chat with the Business Messages FAQ Bot.

Prerequisites

Before you create an FAQ bot, you need your questions and answers available as a knowledge document (max 50 MB): a publicly available HTML file or a CSV file.

Generally, knowledge documents

Can include limited Markdown in answers, as specified in Rich text.
Have a maximum size of 50 MB.
Shouldn't exceed 2000 question/answer pairs.
Don't support duplicate questions with different answers.

For HTML files,

Files from public URLs must have been crawled by the Google search indexer, so that they exist in the search index. You can check this with the Google Search Console. Note that the indexer doesn't keep your content fresh. You must explicitly update your document when the source content changes.
Dialogflow removes HTML tags from content when creating responses. Because of this, it's best to avoid HTML tags and use plain text when possible.
Files with a single question/answer pair aren't supported.

For CSV files,

Files must have questions in the first column and answers in the second, with no header.
Files must use commas as delimiters.

Create an FAQ bot

In the Business Communications Developer Console, navigate to Integrations.
Under Knowledge base (FAQ), click Create knowledge base.
Enter a name for the knowledge base, then click Next.
Select a Mime type.
Add a knowledge document.
- If you chose HTML for Mime type, enter the publicly accessible URL for your FAQ in URL.
- If you chose CSV for Mime type, click Upload and select your CSV file.
Click Add and finish.

To add additional documents to an FAQ bot, click the Add documents button.

Once you follow these steps, Business Messages includes the dialogflowResponse object in user messages it sends to your agent. If you enable auto-response, Business Messages responds to the user with the question/answer pair that has the highest matchConfidence score when compared to the user's message.

Auto-responses

If you enable auto-response during the Dialogflow integration, Business Messages automatically responds to the user via Dialogflow. Your Business Messages agent responds with the highest confidence level match. With a Dialogflow ES integration, if there are matches to both an FAQ answer and a custom intent, Business Messages responds with the match that has the highest confidence level.

Business Messages marks all auto-responded messages as coming from BOT representatives. If your agent supports live agents, Business Messages suspends automatic responses after REPRESENTATIVE_JOINED events and resumes automatic responses after REPRESENTATIVE_LEFT events. See Handoff from bot to live agent.

Auto-respond with an FAQ answer

With a Dialogflow ES integration, if an FAQ answer has the highest confidence level, Business Messages maps the answer to a text message. If there is a related but different answer available, the message displays a "View another answer" suggestion. If not, the message includes a question and suggested replies asking if the message satisfied the user's request.

Auto-respond with an intent response

Intent responses can include one or more of the following responses.

Dialogflow ES: Text, Custom payload
Dialogflow CX: Text, Custom payload, Live agent handoff

If an intent response has the highest confidence level match, the following applies.

If the response has at least one Text value, Business Messages maps this value to a text message.
If the response has at least one Custom payload with a valid Business Messages JSON object structure, Business Messages creates a message using the provided JSON object.
If the response has at least one Live agent handoff response, see Auto-respond with a live agent request.

Because Dialogflow can include multiple responses within one intent match, Business Messages sends each Text, Custom payload, or Live agent handoff response as a separate message. If there are multiple messages in an intent match, but some of them are malformed, Business Messages only sends valid messages as auto-responses.

Auto-respond with a live agent request

Dialogflow CX supports the Live agent handoff response. It signals that the conversation should be handed off to a human representative, and it lets you pass custom metadata for your handoff procedure. If an intent response has the highest confidence level match, and it includes a Live agent handoff, Business Messages sends a live agent requested event to your webhook. To handle this event, see Handoff from bot to live agent.

Auto-respond with a fallback message

If Dialogflow doesn't get a high confidence level match, Business Messages sends a fallback response. Fallbacks are handled differently in Dialogflow ES and Dialogflow CX.

Dialogflow ES

For FAQ bots, if there's no match to an FAQ answer, Business Messages sends a fallback message that it couldn't find an answer.

For configured intents, if there's no match to an intent response, Business Messages sends a fallback intent response. You can use the fallback text provided by Dialogflow, or configure the fallback with additional text and custom payloads.

Here's an example of a fallback intent response that your webhook can receive:

{
  "intentResponses": [
    {
      "intentName": "projects/df-integration/agent/intents/12345",
      "intentDisplayName": "Default Fallback Intent",
      "intentDetectionConfidence": "1.0",
      "fulfillmentMessages": [
        {
          "text": "One more time?"
        }
      ]
    }
  ]
}

Dialogflow pre-populates intent_name and intent_display_name.

Dialogflow CX

Dialogflow CX handles fallback intent responses as built-in events. If there's no match to an intent response, Business Messages sends a fallback message from the No-match default event in Dialogflow. You can use the fallback text provided by Dialogflow, or configure the fallback with additional text, custom payloads, and live agent handoff options.

Here's an example of a fallback intent response that your webhook can receive:

{
  "intentResponses": [
    {
      "intentName": "sys.no-match-default",
      "intentDisplayName": "Default Fallback Intent",
      "intentDetectionConfidence": "0.3",
      "fulfillmentMessages": [
        {
          "text": "I missed that, say that again?"
        }
      ]
    }
  ]
}

Business Messages hard-codes intent_name and intent_display_name.

Dialogflow-specific fields

After you enable the Dialogflow integration, user messages the agent receives include the dialogflowResponse object. Your webhook receives payloads for all user messages regardless of whether or not Business Messages automatically responded to the message on your behalf. To check for an auto-response, see the value of the autoResponded field and decide if you need to respond to the user.

Dialogflow ES

...
"dialogflowResponse": {
  "queryText": "TEXT",
  "intentResponse": {
    "intentName": "INTENT_ID",
    "intentDisplayName": "INTENT_NAME",
    "intentDetectionConfidence": "CONFIDENCE_NUMERIC",
    "fulfillmentMessages": [{
      "text": "FULFILLMENT_TEXT",
      "jsonPayload": "JSON",
      "error": "ERROR_STATUS",
    }],
  "faqResponse": {
    "userQuestion": "USER_QUESTION",
    "answers": [{
      "faqQuestion": "FAQ_QUESTION",
      "faqAnswer": "FAQ_ANSWER",
      "matchConfidenceLevel": "CONFIDENCE_LEVEL",
      "matchConfidence": "CONFIDENCE_NUMERIC",
    }],
  },
  "autoResponded": "BOOLEAN",
  "autoRespondedMessages": [{
    "message": "MESSAGE_JSON",
    "responseSource": "SOURCE",
  }],
},
...

Field	Description
`queryText`	The original conversational query text. If automatic spelling correction is enabled for the Dialogflow model, `queryText` contains the corrected user input.
`intentName`	The unique identifier of the matched intent.
`intentDisplayName`	The name of the matched intent.
`intentDetectionConfidence`	The numeric confidence rating in the match between `queryText` and `intentName`.
`text`	A text response.
`jsonPayload`	A custom payload response. This string matches the custom payload defined in Dialogflow. If the payload does not have a valid Business Messages JSON object structure, `error` describes the issue.
`error`	A description of an error with an intent fulfillment message.
`userQuestion`	The question the user asked, as parsed by Dialogflow.
`faqQuestion`	A question from Dialogflow matched to the user's question.
`faqAnswer`	An answer from Dialogflow matched to the user's question.
`matchConfidenceLevel`	The level of confidence in the match between `userQuestion` and `faqQuestion`.
`matchConfidence`	The numeric confidence rating in the match between `userQuestion` and `faqQuestion`.
`autoResponded`	Whether or not Business Messages automatically responded to the user with an answer from Dialogflow.
`message`	The payload of the autoresponse.
`responseSource`	The source of the autoresponse. See `ResponseSource`.

Dialogflow CX

...
"dialogflowResponse": {
  "queryText": "TEXT",
  "intentResponse": {
    "intentName": "INTENT_ID",
    "intentDisplayName": "INTENT_NAME",
    "intentDetectionConfidence": "CONFIDENCE_NUMERIC",
    "fulfillmentMessages": [{
      "text": "FULFILLMENT_TEXT",
      "jsonPayload": "JSON",
      "error": "ERROR_STATUS",
      "liveAgentHandoff": {
        "metadata": {}
      }
    }],
  "autoResponded": "BOOLEAN",
  "autoRespondedMessages": [{
    "message": "MESSAGE_JSON",
    "responseSource": "SOURCE",
  }],
},
...

Field	Description
`queryText`	The original conversational query text. If automatic spelling correction is enabled for the Dialogflow model, `queryText` contains the corrected user input.
`intentName`	The unique identifier of the matched intent.
`intentDisplayName`	The name of the matched intent.
`intentDetectionConfidence`	The numeric confidence rating in the match between `queryText` and `intentName`.
`text`	A text response.
`jsonPayload`	A custom payload response. This string matches the custom payload defined in Dialogflow. If the payload does not have a valid Business Messages JSON object structure, `error` describes the issue.
`error`	A description of an error with an intent fulfillment message.
`liveAgentHandoff`	Custom metadata for your live agent handoff procedure.
`autoResponded`	Whether or not Business Messages automatically responded to the user with an answer from Dialogflow.
`message`	The payload of the autoresponse.
`responseSource`	The source of the autoresponse. See `ResponseSource`.