Add automation with Dialogflow

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.

Enable the integration

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

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

Update the integration

1. In the Business Communications Developer Console, navigate to Integrations.
2. Click the gear icon next to Dialogflow.
3. 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

1. In the Business Communications Developer Console, navigate to Integrations.
2. Click the gear icon next to Dialogflow.
3. Click Disable integration.
4. 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": "Hello World!",
  "fallback": "Hello World!\n\nReply with \"Hello\" or \"Hi!\"",
  "suggestions": [
    {
      "reply": {
        "text": "Hello",
        "postbackData": "hello-formal"
      }
    },
    {
      "reply": {
        "text": "Hi!",
        "postbackData": "hello-informal"
      }
    }
  ]
}

{
  "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"
            }
          }
        ]
      }
    }
  }
}

{
  "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
            }
          }
        }
      ]
    }
  }
}

{
  "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

1. In the Business Communications Developer Console, navigate to Integrations.
2. Under Knowledge base (FAQ), click Create knowledge base.
3. Enter a name for the knowledge base, then click Next.
4. Select a Mime type.
5. 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.
6. 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.

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

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

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.

...
"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",
  }],
},
...

...
"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",
  }],
},
...