Dialogflow Developer Guide

version: v2.0.0

This guide is intended for creative technologists and/or developers building a conversational assistant for AdLingo Ads on Dialogflow.

The objective of this developer guide is to guide you through building your Dialogflow conversational assistant to communicate with AdLingo's servers.

Authentication

Service account

Follow these steps to enable AdLingo to connect with your Dialogflow agent using a service account. Please use this for production bots. The alternative is using OAuth, which is covered in the next session.

  1. In the Dialogflow console for your project, go to your project settings and click on the "service account" link:


  1. Once in the Google Cloud console, "Create key" for Dialogflow’s service account


  1. Create a Service Account key of type JSON and download it. Then, upload it to a Google Cloud Storage bucket you own:


  1. Edit permissions for the uploaded file and share it with User dapio-prod@appspot.gserviceaccount.com, Reader access:


  1. Once this is setup, share the following with the AdLingo team via Ads Builder.:
  • Bucket name
  • JSON file path
  • Google Cloud project ID

NOTE: You may nest the JSON Service Account Key within a directory. You will need to share the path + the JSON file name in Ads Builder. Below is an example where the path + the JSON file name is df-creatives/df-v2-example-e6f703ebcf55.json.



OAuth

Follow these steps to enable AdLingo to connect with your Dialogflow agent using OAuth, where you (the user) logs in to your account to share your bot credentials with AdLingo. Please use this method only for bot development. This method of authentication can be error prone. Please use the service account method (above) for production bots. We have this solution since it is easier than setting up a service account.

  1. Visit Ads Builder Dialogflow OAuth.
  2. Ensure you are in the correct Workgroup by using the workgroup drop down (located in header).
  3. Fill out a bot name (for Ads Builder).
  4. Select the bot you want to enable with AdLingo.
  5. Enter the default welcome event (default WELCOME).
  6. Hit save.

Channel Data

When an agent session starts, AdLingo sends session data information that provides relevant information to the agent. You can send this information to your backend via a webhook or save it in contexts for later use during the session. The channel data is sent to your agent via event input parameters (see EventInput).

When reading parameters in:

  • Fullfillment: use EventInput name: input.welcome
  • Dialogflow visual editor: use #WELCOME.channelData.<parameter-name>

Parameters:

Please see AdLingo Developer Guide for a full list of parameters with descriptions and examples.

Fulfillments

If you use Dialogflow fulfillment for processing intents and delivering responses, use the following documentation to ensure that the response format is compatible with the AdLingo protocol: https://developers.google.com/actions/dialogflow/fulfillment.

See: https://github.com/actions-on-google/dialogflow-quickstart-nodejs/blob/master/responses/functions/index.js

Instructions

  1. Once in the Dialogflow webapp, click on the Fulfillment navigation tab in the lefthand pane.


  1. Enable the inline editor with the toggle. Toggle will illuminate blue and enable the code editor when enabled.


  1. Update the fulfillment with the appropriate code necessary.


The format is:

'use strict';

const {dialogflow} = require('actions-on-google');
const functions = require('firebase-functions');

const app = dialogflow({debug: true});

app.intent('Intent name', (conv) => {
  conv.ask({"payload": {
   "messages": [
     {
       "text": "text response",
       "type": "text"
     },
   ]
 }});
});

The messages key can be any type of messages found in the Message responses guide. Messages must follow guidelines and restrictions.


  1. Click on the Deploy button once complete with fulfillments.


  1. Click on the Intents button. Select the correct Intent once on the page.


  1. Scroll to the bottom of the intent until you see the Fulfillment section. Open the expansion panel, and Enable webhook call for this intent using the toggle. Toggle will illuminate blue.


  1. Click on the save button in the top right corner of the intents page.


Custom Payload

You can use Dialogflow's Custom Payload response instead of Fullfillment or the Visual Editor.

  1. Open an intent and scroll to the bottom under the Responses header.


  1. Ensure the Default tab remains selected, and tap the Add Responses button. Select Custom Payload.


  1. Add JSON message response as described in Message responses.


Example for you to copy:

{
  "messages": [
    {
      "text": "text response dt",
      "type": "text"
    }, {
      "title": "Title: this is a title",
      "subtitle": "This is a subtitle",
      "body": "This is a basic card body",
      "image": {
        "url":
          "https://storage.googleapis.com/actionsresources/logo_assistant_2x_64dp.png",
        "altText": "Image alternate text",
        "options": {
          "options": {
            "aspectRatio": "landscape"
          },
          "type": "imageOptions"
        },
        "type": "image"
      },
      "buttons": [{
        "label": "This is a button",
        "action": {
          "url": "https://assistant.google.com/",
          "type": "openUrl"
        },
        "type": "button"
      }],
      "type": "card"
    }
  ]
}

  1. Click save once complete with the intent.