Dialogflow Integration

Overview

Kommunicate provide a codeless integration with Dialogflow. You can easily integrate your Dialogflow agent form bot section in Kommunicate dashboard. In this section, learn how to:

Integration using Dialogflow ES

  1. Login to Dialogflow console.
  2. Select your Agent from dropdown in left panel.
  3. Click on setting button. It will open a setting page for agent.
  4. Inside general tab search for GOOGLE PROJECTS and click on the Project ID, it will be redirected to the Google Cloud console.
  5. Then you have to enable the Dialogflow API for your project and create a service account key. Please refer the below links.

Select a project where the Dialogflow API should be enabled.

Dialogflow ES

Once the API is enabled, click 'Go to credentials'

Dialogflow ES

In the 'Add credentials to your project' section, click What credentials do I need?

Dialogflow ES

Provide a Service account name.

Dialogflow ES

Select a role for the project as 'Owner'

Dialogflow ES

  1. Once the Service account name and project role is selected, click Continue. Service account and key in JSON format will be created and it will get automatically downloaded.

Dialogflow ES

  1. Upload the key file in Kommunicate dashboard.

On successful integration, the bot will be given an ID(botId) and will be listed under Manage Bots section. The botId will be used to identify the bot in the Kommunicate system.

Integration using Dialogflow CX

  1. Before Dialogflow CX integration with Kommunicate, first make sure you have created a project and Dialogflow CX Agent from Dialogflow CX console
  2. Then you have to enable the Dialogflow API for your project and create a service account key. Please refer the below links.

Create an agent

Dialogflow CX

Dialogflow CX

Build your Dialogflow CX chatbot

Build your Dialogflow CX chatbot as per your requirements, once the chatbot building is completed, tap on Agent Settings option to create a service account

Dialogflow CX

Create a Service Account

Dialogflow CX

Dialogflow CX

In the following step, you will be giving the ROLE to service account, select Owner/Editor as a ROLE.

Dialogflow CX

Once ROLE assignment is done, proceed to create a JSON key for Integration.

Create a JSON Key

Click on Manage Keys and Add a JSON key

Dialogflow CX

Dialogflow CX

Once you click on CREATE, JSON file will be downloaded, upload the service account key file in Kommunicate dashboard along with the AGENT ID

To get the Agent Id:

Go to Dialogflow CX console >> Select the Project >> In the Agent you have created ‘Copy ID’

It will be in the following format, projects/test-covid-rwvr/locations/global/agents/e2c5d8a3-f416-4f32-bfc9-d986d540abd here the Agent Id is e2c5d8a3-f416-4f32-bfc9-d986d540abdb Copy the Agent Id

Dialogflow CX

Enter the Agent Id in Kommunicate Dashboard and then Save and proceed

Dialogflow CX

To get the Environment Id:

Open the Dialogflow CX Console >> Choose your GCP project >> Select your agent >> Click the Manage tab.

Environment-id-1

Click Environments

Environment-id-2

Create button and provide information

Environment-id-3

Environment-id-4

To copy an environment resource name that includes the environment ID, click the copy button near the right side of an environment in the list.

Environment-id-5

The environment name is displayed as follows:

projects/name-of-project/locations/us-central1/agents/54ccf3c4-6c41-9664-4b14-a40f5f0775b6/environments/507ba9c1-c034-8747-bd72-c939698c057e

Here the environment Id is 507ba9c1-c034-8747-bd72-c939698c057e

Environment-id-6

Enter the Environment Id in Kommunicate Dashboard and thenSave and proceed

On successful integration, the bot will be given an ID(botId) and will be listed under Manage Bots section. The botId will be used to identify the bot in the Kommunicate system.

Rich messages

You can implement the rich messages using Google Assistant and the Custom payload.

Google Assistant

Use the Google Assistant to implement rich messages as it is an easier and simpler way to add rich messages without writing any code.

Please check out the following flow to add the Rich Messages:

Suggestion Chips

User Input Section

User Input section

Select Google Assistant

Visit the Response section on Dialogflow and select the Google Assistant as given in the below image:

Select Google Assistant

Add Rich message Type

Add the Rich message type


Add Suggestion Chips

Add the type of rich message you want to use, we have selected the suggestion chips.

Add suggestion chips
Add the buttons as explained in the images, end-user will select one of the them.


Suggestion chips on widget

This is how it looks on widget side

Error you might come across during the implementation

Refer to the image



Link Button

Create a link button to navigate users to specified links. For example if you click on Rich Messaging (Rich messaging is a suggestion chip shown in above example) it will redirect the user to specified link.

Follow the given instructions to create the Link button:

Create the new intent with the training phrase Rich Messaging and add the link button as given in the following image:

Add the traning phrase

Select the link button as a Rich message type as shown below:

Add link button

Link button on widget

Link-button


Dialogflow custom payload

Pass the Rich Messages metadata as custom payload in Dialogflow to render Rich Messages while using a Dialogflow bot. See how to set up Rich Messages in Dialogflow bot here.

Dialogflow fulfillment

Rich messages can be used with the Dialogflow fulfillment.

Send message API

You can use Send message API to add Rich Messages.

Pass Custom data to bot platform

Note: This feature is supported by only Dialogflow V2 APIs and only works if you're using dialogflow Fulfillment Library to handle your dialogflow bot requests. To know more about dialogflow fulfillment you can check out the official documentation.

Kommunicate allows you to send custom data to your Dialogflow bot. Create a chatContext object (having all the data you wish to pass to bot platform) and update it to Kommunicate settings by calling Kommunicate.updateChatContext method.

Custom data can be passed to bot platform using rich message as well, click here to view more details.

The chat context object will be sent along with every message user sends. The best place to call this method is the onInit method you pass in the installation script.

Note: For ReactJS use - window.Kommunicate.updateChatContext(chatContext);

var chatContext = {
  "key1":"value1",
  "key2":"value2"
}
Kommunicate.updateChatContext(chatContext);

Dialogflow will send this data in the configured webhook in originalDetectIntentRequest param.

"originalDetectIntentRequest": {
   "payload": {
     "key1": "value1",
     "key2": "value2"
   }
 }

Getting response using Inline Editor

The user details passed in chatContext object from Kommunicate chat widget can be accessed from Dialogflow’s fulfillment code. This data is available in the request object as part of originalDetectIntentRequest parameter.

Example:

...
exports.dialogflowFirebaseFulfillment = functions.https.onRequest((request, response) => {const agent = new WebhookClient({request,response});
            console.log('Dialogflow Request headers: ' + JSON.stringify(request.headers));
            console.log('Dialogflow Request body: ' + JSON.stringify(request.body));
            console.log('Data passed as chatContext from Kommunicate is: ' +JSON.stringify(request.body.originalDetectIntentRequest));
...

Follow the instructions in the respective platform section to accomplish the same on mobile SDKs. For more information, check the following

  1. Android
  2. iOS
  3. ReactNative
  4. Ionic/Cordova

Welcome message from bots

When a conversation is routed through the bot, it will trigger a WELCOME event to the Dialogflow bot. You can enable default welcome intent in Dialogflow or create a custom event WELCOME.

This message is different from the Welcome Message you set in Kommunicate dashboard. If Welcome Message for bot and humans (configured from the dashboard) both are enabled, both welcome message will be sent to the users. We recommend disabling the Welcome Message from the dashboard in this case.

Custom Welcome messages from bots

When a new conversation is started and routed through the Dialogflow bot, Kommunicate triggers the Default Welcome Intent configured in Dialogflow console. However, you can customize a welcome message and set a different welcome message for your conversations dynamically. The events can be created on the Dialogflow console and pass the event in customWelcomeEvent parameter.

call this parameter in the onInit method you pass in the installation script.

...
onInit: function (status, data) {
            if (status == "success") { 
                Kommunicate.updateSettings({ "customWelcomeEvent": "welcome_event_for_home_page" }); 
            }
        }
...

User's can update this setting dynamically when certain events occur on their website. This setting will be applied to all the new conversations that started after the update i.e. The conversation started after the setting is updated will trigger the new welcome event.

Also, this setting can be used to show different welcome messages on different pages of your website.

Skip Dialogflow welcome message

Skip the 'WELCOME' event from dialogflow by setting

 "skipBotEvent":'["WELCOME_EVENT"]'

Skip Dialogflow welcome message through Settings

var defaultSettings = {
      "skipBotEvent": '["WELCOME_EVENT"]',
};
Kommunicate.updateSettings(defaultSettings);

Skip Dialogflow welcome message for a specific conversation

var conversationDetail = {
    "skipBotEvent":'["WELCOME_EVENT"]'
};
            
Kommunicate.startConversation(conversationDetail, function (response) { });

Send attachments and location to bot

When a user attaches a file or shares location, Kommunicate dispatches an event KOMMUNICATE_MEDIA_EVENT to your bot along with the attached file information. To receive the attachment detail you have to add KOMMUNICATE_MEDIA_EVENT to an intent and enable the fulfillment. This configuration looks like below in dialogflow dashboard: send attachment to bot step 1

If you have enabled the fulfillment in Dialogflow, you will receive the following data in originalDetectIntentRequest parameter.

This is sample JSON for file attachment:

{
    "attachments": [{
        "payload": {
            "size": "Size in bytes",
            "name": "Name of the file",
            "url": "URL of the file"
        },
        "type": "image/png" // media type (in form of type/subtype) . Use the regex 'type/*' to get the generic type
    }]
}

Sample JSON for the location message

{
    "attachments": [{
        "payload": {
            "lat": "Latitude",
            "lon": "Longitude"
        },
        "type": "location"
    }]
}

Make the bot multilingual

Note: Multilingual agents are supported only with Dialogflow V2 APIs

Kommunicate allows you to integrate your multilingual bot so that your bot can reply in the user's language. You need to pass the user's language tag to Kommunicate.

Language tags follow the HTTP/1.1 specification, section 3.10. Kommunicate will send this information with every message to the integrated bot platform. You can use the below method to update the user's language:


Kommunicate.updateUserLanguage("en-US");

You can call this method when kommunicate SDK is initialized. For example, if you are using web SDK you can put this inside onInit callback function in Kommunicate installation script.

Ask users their preferred language

You can configure your bot to let the user select their preferred language. Set below JSON as custom payload in dialogflow.

{
  "message": "Please select your language",
  "platform": "kommunicate",
  "metadata": {
    "contentType": "300",
    "templateId": "6",
    "payload": [
      {
        "title": "Hindi",
        "message": "Hindi",
        "updateLanguage": "hi"
      },
      {
        "title": "English",
        "message": "English",
        "updateLanguage": "en"
      }
    ]
  }
}

you can pass any language tag supported by dialogflow in updateLanguage parameter.

Multilingual Dialogflow agents

When you integrate a Dialogflow bot, Kommunicate sets US English(en-US) the default language. This setting will be overridden by the user's language. Here is the list of languages supported by Dialogflow.

You need to pass the appropriate language tag in Kommunicate.updateUserLanguage("languageTag") method. Once this is set, only intents created in this language will be matched against user queries. If none of the intents is matched, Default Fallback Intent will be triggered. Here is more information on creating multilingual agent in Dialogflow.

Update user's timezone

Dialogflow provides system entities to parse the data from user's query. When working with date-time you might need to consider the users timezone and send it to dialogflow. This can be done by updating the user's timezone by calling Kommucniate.updateUserTimezone method. You need to pass the timezone id as registered in IANA timezone db.

Kommunicate.updateUserTimezone("asia/calcutta");  // Kommunicate supports only timezone ids registered in IANA timezone database.

You can call this method when kommunicate SDK is initialized. For example, if you are using web SDK you can put this inside onInit callback function in Kommunicate installation script.

Working with Dialogflow fulfillment

This feature is only available with Dialogflow V2 APIs.

Fulfillment lets your Dialogflow agent call business logic on an intent-by-intent basis. Dialogflow supports two ways to configure the fulfillment for an agent. More information on the fulfillment configuration is available on Dialogflow docs.

  1. Custom webhook
  2. Create a webhook with the inline editor

Custom webhook

A webhook is a web server endpoint that you create and host. When an intent with fulfillment enabled is matched, Dialogflow will make an HTTP POST request to your webhook with a JSON object containing information about the matched intent. And your webhook should respond back with instructions for what Dialogflow should do next. More about the request and response format is available in Dialogflow docs. Then Dialogflow wraps webhook response into the response object depending on the API version you are using and send it to the client.

Kommunicate looks for the fulfillmentMessages array in webhook response. The element in this array can be a text message or a rich message supported by kommunicate. Every element is treated as an independent message and rendered into UI according to the data present.

Below is the sample fullfilmentMessage array for Dialogflow V2 APIs:

{
    "fulfillmentMessages": [{
        "payload": {
            "message": "Object1- this object renders the link button on the UI",
            "platform": "kommunicate",
            "metadata": {
                "contentType": "300",
                "templateId": "3",
                "payload": [{
                        "type": "link",
                        "url": "www.google.com",
                        "name": "Go To Google"
                    },
                    {
                        "type": "link",
                        "url": "www.facebook.com",
                        "name": "Go To Facebook"
                    }
                ]
            }
        }
    }, {
        "payload": {
            "message": "Object2 - this object renders this text string on the UI",
            "platform": "kommunicate"
        }
    }]
}

Create a webhook with the inline editor

Dialogflow provides some libraries designed to assist with building a fulfillment webhook. Below is the node js function with dialogflow fulfillment library which render the specified rich messages on kommunicate chat UI.

'use strict';
 
const functions = require('firebase-functions');
const {WebhookClient} = require('dialogflow-fulfillment');
const {Payload} = require('dialogflow-fulfillment');
 
process.env.DEBUG = 'dialogflow:debug'; // enables lib debugging statements
 
exports.dialogflowFirebaseFulfillment = functions.https.onRequest((request, response) => {
  const agent = new WebhookClient({ request, response }); 
  function welcome(agent) {
    agent.add(new Payload("PLATFORM_UNSPECIFIED", [{
      "message": "Do you want more updates?",
      "platform": "kommunicate",
      "metadata": {
        "contentType": "300",
        "templateId": "6",
        "payload": [
          {
            "title": "Yes",
            "message": "Cool! send me more."
          },
          {
            "title": "No ",
            "message": "Don't send it to me again"
          }
        ]
      }
    }]));
  }
 
  let intentMap = new Map();
  intentMap.set('Default Welcome Intent', welcome);
  agent.handleRequest(intentMap);
});

Here are the more samples for different rich messages.

Note: This payload is only for inline editor. For webhook, please use this payload.

Working with custom actions

Actions are the triggers which tell Kommunicate to perform certain tasks. A bot can request an action for Kommunicate to perform the below task:

Fetch the human agent's availability status

Your bot can make a request to fetch the human agent's availability status. This information can be useful to decide if there are any human agents available to respond to the user's query. The bot can handover the conversation based on this information.

The bot makes this request by passing actionRequest parameter along with the action name fetchAgentAvailability in the custom payload. This parameter should be used with replyMetadata so that your bot will get the response of the action along with the message reply.

Here is an example to understand this:

Assume, you have designed a button Talk to Human. When a user clicks on this button, you want to handover the conversation only if your human agents are online. If none of the agents are online you want to display some other message. Here is the custom payload for this kind of button:

{
    "platform": "kommunicate",
    "metadata": {
        "contentType": "300",
        "templateId": "6",
        "payload": [{
            "title": "Talk to Human",
            "message": "I want to talk to a human",
            "replyMetadata": {
                "actionRequest": "fetchAgentAvailability"
            }
        }]
    }
}

When the user clicks on this button, Kommunicate will send the action response to your bot platform. See a sample response below:

{
"actionResponse": [{
        "payload": {
          "availabilityStatus": "away" // possible values - online, offline, away
        },
        "name": "fetchAgentAvailability"
      }],
}

Possible values for availability status are:

  • online - if at least one agent is online
  • away - if no agent is online and at least one agent is away
  • offline - if none of the agents is neither online nor away.

Dialogflow, further, sends this data to your Webhook as the part of originalDetectIntentRequest. You can get this information and decide whether to handover the conversation to any of the human agents or send any other message.

Enable/disable attachment based on the bot response

You can enable or disable the chat widget attachment icon based on the bot response. Use KM_ENABLE_ATTACHMENT property in metadata.

Note: By default the chat widget attachment icon will be enabled. You can disable it from kommunicateSettings object by setting attachment parameter to false.

This is the sample JSON to enable attachment

[{
  "message": "Please share the document",// This is your trigger message to ask for attachments from the user. You can customize the message accordingly
  "metadata": {
    "KM_ENABLE_ATTACHMENT": true 
  }
}]

This is the sample JSON to disable attachment

[{
  "message": "Thanks for sharing the document",// This is your trigger message to disable the attachment icon from the chat widget. You can use this to disable the attachment icon once the user has shared the documents.
  "metadata": {
    "KM_ENABLE_ATTACHMENT": false 
  }
}]

Extract WhatsApp Number in Dialogflow CX

This process consists of two major steps.

  1. Webhook call
  2. Number Extraction

Enable webhook call for your intent

Enable the webhook call for the intent in which you want to get the user's phone number. Open your intent in Dialogflow, then on the right side you will see “Fulfillment”, here, enable toggle saying “Enable webhook”.

Webhook call for Dialogflow CX

Get the phone number

Whenever this particular intent will be triggered, the whole payload consisting of multiple details will be sent to your server. The payload is like this:

{
    "detectIntentResponseId": "516196b7-69d4-4e0b-8a98-381853f64eff",
    "intentInfo": {
      "lastMatchedIntent": "projects/shantnu-test-wxkp/locations/us-central1/agents/c5fdf777-ea8f-4ba3-9fa1-aec8db3b1fa3/intents/627dabd0-31ec-4c1f-a292-0e209423cdb8",
      "displayName": "templateid7",
      "confidence": 1.0
    },
    "pageInfo": {
      "currentPage": "projects/shantnu-test-wxkp/locations/us-central1/agents/c5fdf777-ea8f-4ba3-9fa1-aec8db3b1fa3/flows/00000000-0000-0000-0000-000000000000/pages/START_PAGE",
      "displayName": "Start Page"
    },
    "sessionInfo": {
      "session": "projects/shantnu-test-wxkp/locations/us-central1/agents/c5fdf777-ea8f-4ba3-9fa1-aec8db3b1fa3/sessions/67423633"
    },
    "fulfillmentInfo": {
      "tag": "1"
    },
    "messages": [{
      "payload": {
        "message": "This is the sample json for list template",
        "platform": "kommunicate",
        "metadata": {
          "payload": {
            "headerImgSrc": "URL for header image",
            "elements": [{
              "description": "Description for the list item",
              "action": {
                "type": "link",
                "url": "https://www.google.com"
              },
              "imgSrc": "Thumbnail icon for list item",
              "title": "List item 1"
            }],
            "headerText": "Header text.",
            "buttons": [{
              "name": "See us on facebook",
              "action": {
                "type": "link",
                "url": "https://www.facebook.com"
              }
            }]
          },
          "contentType": "300",
          "templateId": "7"
        }
      },
      "responseType": "HANDLER_PROMPT",
      "source": "VIRTUAL_AGENT"
    }],
    "payload": {
      "from": "whatsapp:+919874543210",
      "applicationId": "27ce844bfc691713a25abf5bdcdffa574",
      "groupId": "67423633",
      "messageSource": "1",
      "botId": "df-cx-flmt-test-yw0vb",
      "attachments": []
    },
    "text": "templateid7",
    "languageCode": "en-US"
  }

In this payload, notice req.body.payload.from which is "whatsapp:+919874543210"

User's phone number is present along with extra characters. You can use this to get the phone number. A javascript example would be like:


"whatsapp:+919874543210".split(":")[1];** OR **const phoneNumber = req.body.payload.from.split(":")[1];

Voila! You have the phone number.

Dialogflow CX Webhook

Using webhooks in Dialogflow CX is easy.

  1. Enable the webhook for your intent. If you have created a webhook already, you can select the webhook you want to use or create a new one.

Enable the Dialogflow CX

Details Dialogflow CX Webhook

  1. You can also create the webhooks under Manage Section.

Manage Dialogflow CX Webhook

Here is an example of a webhook and response is being rendered on Kommunicate UI:

This is a sample payload sent from webhook:

{
    "fulfillmentResponse": {
        "messages": [{
                "payload": {
                    "message": "Showing the text for the example buttons",
                    "platform": "kommunicate",
                    "metadata": {
                        "contentType": "300",
                        "templateId": "6",
                        "payload": [{
                                "title": "Button 1",
                                "message": "Message for Example 1."
                            },
                            {
                                "title": "Button 2",
                                "message": "Message for Example 2"
                            },
                            {
                                "title": "Button 3",
                                "message": "Message for long button"
                            }
                        ]
                    }
                }
            },
            {
                "payload": {
                    "message": "Showing the text for the Links",
                    "platform": "kommunicate",
                    "metadata": {
                        "contentType": "300",
                        "templateId": "3",
                        "payload": [{
                                "type": "link",
                                "url": "https://www.google.com",
                                "name": "Go To Google"
                            },
                            {
                                "type": "link",
                                "url": "https://www.facebook.com",
                                "name": "Go To Facebook",
                                "openLinkInNewTab": false
                            }
                        ]
                    }
                }
            }
        ]
    }
}

Here it how it looks on Kommunicate Chatbot UI:

Manage Dialogflow CX Webhook

Please refer to Dialogflow documents for more information:

Webhook

Fulfillment Response

Merge Behaviour

Dialogflow ES Webhook & Fulfillment

← Bot setupLex Integration →