Dashbot

Google Assistant Documentation

Google Assistant Documentation

Welcome to the Google Assistant documentation for Dashbot! Integrating Dashbot into your Google Assistant app is quick and easy.

If you have any questions, comments, or suggestions, please feel free to contact us.

Google Dialogflow Integration with Google Actions NPM

Create a bot API key

Each bot needs its own API key for tracking.

Create a bot to get an API key.

Install Dashbot via NPM

npm install --save dashbot

Include Dashbot

Use the API key created above.

const dashbot = require('dashbot')(process.env.DASHBOT_API_KEY).google;

After creating a DialogflowApp object, pass it to Dashbot

const DialogflowApp = require('actions-on-google').DialogflowApp;
app.post('/', (request, response) => {
  const assistant = new DialogflowApp({request: request, response: response});
  dashbot.configHandler(assistant);
  ...
}

Examples

Here are two samples with Dashbot integrated:

Google Dialogflow with Firebase

Create a bot API key

Each bot needs its own API key for tracking.

Create a bot to get an API key.

Include the Dashbot NPM module in package.json

In the Dialogflow Inline Editor, include the npm module in package.json:

"dependencies": {
  ...
  "dashbot": "^11.1.0"
}

Include Dashbot

Use the API key created above.

'use strict';
const functions = require('firebase-functions');
const {dialogflow, BasicCard, SimpleResponse} = require('actions-on-google')
const dashbot = require('dashbot')(process.env.DASHBOT_API_KEY).google;

After creating a Dialogflow object, pass it to Dashbot

const app = dialogflow();
dashbot.configHandler(app);
...
//business logic
...
exports.dialogflowFirebaseFulfillment = functions.https.onRequest(app);

Google Dialogflow v1 with Firebase

DialogFlow has been updated to V2
DialogFlow V2 is now the default API. Google recommends migrating from V1. To integrate with v2 please go here

Google requires a paid Firebase plan
Google currently requires a paid Firebase plan in order to access an external API.

Create a bot API key

Each bot needs its own API key for tracking.

Create a bot to get an API key.

Include the Dashbot NPM module in package.json

In the Dialogflow Inline Editor, include the npm module in package.json:

"dependencies": {
 ...
 "dashbot": "^11.1.0"
}

Include Dashbot

Use the API key created above.

'use strict';
const functions = require('firebase-functions');
const DialogflowApp = require('actions-on-google').DialogflowApp;


const dashbot = require('dashbot')(process.env.DASHBOT_API_KEY).google;

After creating a DialogflowApp object, pass it to Dashbot

exports.dialogflowFirebaseFulfillment = functions.https.onRequest((request, response) => {
  const app = new DialogflowApp({request: request, response: response});
  dashbot.configHandler(app);
  ...
}

Google Integration with Actions SDK

Create a bot API key

Each bot needs its own API key for tracking.

Create a bot to get an API key.

Install Dashbot via NPM

npm install --save dashbot

Include Dashbot

Use the API key created above.

const dashbot = require('dashbot')(process.env.DASHBOT_API_KEY).google;

After creating an ActionsSdkApp object, pass it to Dashbot

Note
Earlier versions of the Google Actions SDK used an ActionsSdkAssistant object. The implementation is otherwise the same.

const ActionsSdkApp = require('actions-on-google').ActionsSdkApp;
function helloAction(request, response) {
  const assistant = new ActionsSdkApp({ request: request, response: response });
  dashbot.configHandler(assistant);
  ...
}

Example

View sample code for a Google Actions integration.

Dialogflow Integration without Google

Create a bot API key

Each bot needs its own API key for tracking.

Create a bot to get an API key.

Install Dashbot via NPM

npm install --save dashbot

Include Dashbot

Use the API key created above.

const dashbot = require('dashbot')(process.env.DASHBOT_API_KEY).google;

Log whenever your webhook is called

app.use(bodyParser.json())
...
app.post('/guessnumber', (request, response) => {
  dashbot.logIncoming(request.body);
  ...
}

Whenever you send a message, log the request and outgoing message

const msg = {
  speech: "I’m thinking of a number from 0 and 100. What’s your first guess?",
  data: { google: { expect_user_response: true } },
  contextOut: [
    {
      name:"game",
      lifespan:100,
      parameters:{
        answer:72
      }
    }
  ]
}
dashbot.logOutgoing(request.body, msg);
response.send(msg);

Example

View sample code.

Google Python SDK

Create a bot API key

Each bot needs its own API key for tracking.

Create a bot to get an API key.

Install Dashbot Python SDK

pip install dashbot

Import the Dashbot library

from dashbot import google

Initialize Dashbot

Use the API key created above.

dba = google.google(process.env.DASHBOT_API_KEY)

Log incoming requests

dba.logIncoming(incomingRequest)

Log outgoing response

Pass both the incoming request and the response

dba.logOutgoing(incomingRequest, response)

Google Integration with REST API

Note
If you’re using Node.js, the preferred integration is with our
NPM.

Create a bot API key

Each bot needs its own API key for tracking.

Create a bot to get an API key.

Integrate the REST API

There are two integration points as outlined below.

1. When Google posts to your webhook endpoint

When Google posts to your webhook endpoint, post the same data Google sent to you to the following endpoint:

https://tracker.dashbot.io/track?platform=google&v=11.1.0-rest&type=incoming&apiKey=API_KEY_HERE

Make sure to set the ‘Content-Type’ header to ‘application/json’ and to replace API_KEY_HERE with your api key.

The data to POST should pass the following data:

{
  "request_body": {
    "originalRequest": {
      "data": {
        "isInSandbox": true,
        "surface": {
          "capabilities": [
            {
              "name": "actions.capability.AUDIO_OUTPUT"
            },
            {
              "name": "actions.capability.SCREEN_OUTPUT"
            }
          ]
        },
        "user": {
          "locale": "en-US",
          "userId": "APhe68EDOxlex9HCuUj3gsZaWoZa"
        },
        "inputs": [
          {
            "rawInputs": [
              {
                "inputType": "KEYBOARD",
                "query": "talk to my test app"
              }
            ],
            "intent": "actions.intent.MAIN"
          }
        ],
        "conversation": {
          "type": "NEW",
          "conversationId": "1501533781539"
        }
      },
      "version": "2",
      "source": "google"
    },
    "result": {
      "actionIncomplete": false,
      "score": 1,
      "metadata": {
        "intentId": "abad66de-d382-4bf7-90e3-35f77ae83cc6",
        "webhookUsed": "true",
        "webhookForSlotFillingUsed": "false",
        "nluResponseTime": 1,
        "intentName": "Default Welcome Intent"
      },
      "resolvedQuery": "GOOGLE_ASSISTANT_WELCOME",
      "action": "input.welcome",
      "source": "agent",
      "contexts": [
        {
          "name": "google_assistant_welcome",
          "lifespan": 0
        },
        {
          "name": "actions_capability_screen_output",
          "lifespan": 0
        },
        {
          "name": "actions_capability_audio_output",
          "lifespan": 0
        },
        {
          "name": "google_assistant_input_type_keyboard",
          "lifespan": 0
        }
      ],
      "fulfillment": {
        "speech": "Hi!",
        "messages": [
          {
            "type": 0,
            "speech": "Hi!"
          }
        ]
      }
    },
    "id": "166fdebd-052f-4c08-85ef-ada758d8037f",
    "sessionId": "1501533781539",
    "lang": "en",
    "timestamp": "2017-07-31T20:43:01.572Z",
    "status": {
      "errorType": "success",
      "code": 200
    }
  }
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
     -d '{"request_body":{"originalRequest":{"data":{"isInSandbox":true,"surface":{"capabilities":[{"name":"actions.capability.AUDIO_OUTPUT"},{"name":"actions.capability.SCREEN_OUTPUT"}]},"user":{"locale":"en-US","userId":"APhe68EDOxlex9HCuUj3gsZaWoZa"},"inputs":[{"rawInputs":[{"inputType":"KEYBOARD","query":"talk to my test app"}],"intent":"actions.intent.MAIN"}],"conversation":{"type":"NEW","conversationId":"1501533781539"}},"version":"2","source":"google"},"result":{"actionIncomplete":false,"score":1,"metadata":{"intentId":"abad66de-d382-4bf7-90e3-35f77ae83cc6","webhookUsed":"true","webhookForSlotFillingUsed":"false","nluResponseTime":1,"intentName":"Default Welcome Intent"},"resolvedQuery":"GOOGLE_ASSISTANT_WELCOME","action":"input.welcome","source":"agent","contexts":[{"name":"google_assistant_welcome","lifespan":0},{"name":"actions_capability_screen_output","lifespan":0},{"name":"actions_capability_audio_output","lifespan":0},{"name":"google_assistant_input_type_keyboard","lifespan":0}],"fulfillment":{"speech":"Hi!","messages":[{"type":0,"speech":"Hi!"}]}},"id":"166fdebd-052f-4c08-85ef-ada758d8037f","sessionId":"1501533781539","lang":"en","timestamp":"2017-07-31T20:43:01.572Z","status":{"errorType":"success","code":200}}}'
     'https://tracker.dashbot.io/track?platform=google&v=11.1.0-rest&type=incoming&apiKey=API_KEY_HERE'

Notice, you must replace the placeholder API_KEY_HERE above with your api key.

Note
This is just an example — we accept any rich media that Google accepts.

2. When your bot sends a message

When your bot sends a message, POST to the following endpoint:

https://tracker.dashbot.io/track?platform=google&v=11.1.0-rest&type=outgoing&apiKey=API_KEY_HERE

Make sure to set the ‘Content-Type’ header to ‘application/json’ and to replace API_KEY_HERE with your api key.

The data to POST should pass the following data:

{
  "request_body": {
    "originalRequest": {
      "data": {
        "isInSandbox": true,
        "surface": {
          "capabilities": [
            {
              "name": "actions.capability.AUDIO_OUTPUT"
            },
            {
              "name": "actions.capability.SCREEN_OUTPUT"
            }
          ]
        },
        "user": {
          "locale": "en-US",
          "userId": "APhe68EDOxlex9HCuUj3gsZaWoZa"
        },
        "inputs": [
          {
            "rawInputs": [
              {
                "inputType": "KEYBOARD",
                "query": "talk to my test app"
              }
            ],
            "intent": "actions.intent.MAIN"
          }
        ],
        "conversation": {
          "type": "NEW",
          "conversationId": "1501533781539"
        }
      },
      "version": "2",
      "source": "google"
    },
    "result": {
      "actionIncomplete": false,
      "score": 1,
      "metadata": {
        "intentId": "abad66de-d382-4bf7-90e3-35f77ae83cc6",
        "webhookUsed": "true",
        "webhookForSlotFillingUsed": "false",
        "nluResponseTime": 1,
        "intentName": "Default Welcome Intent"
      },
      "resolvedQuery": "GOOGLE_ASSISTANT_WELCOME",
      "action": "input.welcome",
      "source": "agent",
      "contexts": [
        {
          "name": "google_assistant_welcome",
          "lifespan": 0
        },
        {
          "name": "actions_capability_screen_output",
          "lifespan": 0
        },
        {
          "name": "actions_capability_audio_output",
          "lifespan": 0
        },
        {
          "name": "google_assistant_input_type_keyboard",
          "lifespan": 0
        }
      ],
      "fulfillment": {
        "speech": "Hi!",
        "messages": [
          {
            "type": 0,
            "speech": "Hi!"
          }
        ]
      }
    },
    "id": "166fdebd-052f-4c08-85ef-ada758d8037f",
    "sessionId": "1501533781539",
    "lang": "en",
    "timestamp": "2017-07-31T20:43:01.572Z",
    "status": {
      "errorType": "success",
      "code": 200
    }
  },
  "message": {
    "data": {
      "google": {
        "expectUserResponse": true,
        "richResponse": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "Hello there! Let's chat. Ask me anything, or pat me, amuse me, or ask for help",
                "displayText": "Hello there! Let's chat..."
              }
            },
            {
              "basicCard": {
                "image": {
                  "accessibilityText": "welcome cat",
                  "url": "http://i.dashbot.io/cat/pepper-fb.png"
                },
                "formattedText": "Ask me anything, or pat me, amuse me, or ask for help"
              }
            }
          ],
          "suggestions": [
            {
              "title": "pat"
            },
            {
              "title": "amuse"
            },
            {
              "title": "help"
            }
          ]
        }
      }
    },
    "speech": "Hello there! Let's chat. Ask me anything, or pat me, amuse me, or ask for help",
    "contextOut": [
      {
        "name": "_actions_on_google_",
        "lifespan": 100
      }
    ]
  }
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
     -d '{"request_body":{"originalRequest":{"data":{"isInSandbox":true,"surface":{"capabilities":[{"name":"actions.capability.AUDIO_OUTPUT"},{"name":"actions.capability.SCREEN_OUTPUT"}]},"user":{"locale":"en-US","userId":"APhe68EDOxlex9HCuUj3gsZaWoZa"},"inputs":[{"rawInputs":[{"inputType":"KEYBOARD","query":"talk to my test app"}],"intent":"actions.intent.MAIN"}],"conversation":{"type":"NEW","conversationId":"1501533781539"}},"version":"2","source":"google"},"result":{"actionIncomplete":false,"score":1,"metadata":{"intentId":"abad66de-d382-4bf7-90e3-35f77ae83cc6","webhookUsed":"true","webhookForSlotFillingUsed":"false","nluResponseTime":1,"intentName":"Default Welcome Intent"},"resolvedQuery":"GOOGLE_ASSISTANT_WELCOME","action":"input.welcome","source":"agent","contexts":[{"name":"google_assistant_welcome","lifespan":0},{"name":"actions_capability_screen_output","lifespan":0},{"name":"actions_capability_audio_output","lifespan":0},{"name":"google_assistant_input_type_keyboard","lifespan":0}],"fulfillment":{"speech":"Hi!","messages":[{"type":0,"speech":"Hi!"}]}},"id":"166fdebd-052f-4c08-85ef-ada758d8037f","sessionId":"1501533781539","lang":"en","timestamp":"2017-07-31T20:43:01.572Z","status":{"errorType":"success","code":200}},"message":{"data":{"google":{"expectUserResponse":true,"richResponse":{"items":[{"simpleResponse":{"textToSpeech":"Hello there! Lets chat. Ask me anything, or pat me, amuse me, or ask for help","displayText":"Hello there! Let'"'"'s chat..."}},{"basicCard":{"image":{"accessibilityText":"welcome cat","url":"http://i.dashbot.io/cat/pepper-fb.png"},"formattedText":"Ask me anything, or pat me, amuse me, or ask for help"}}],"suggestions":[{"title":"pat"},{"title":"amuse"},{"title":"help"}]}}},"speech":"Hello there! Let'"'"'s chat. Ask me anything, or pat me, amuse me, or ask for help","contextOut":[{"name":"_actions_on_google_","lifespan":100}]}}'
     'https://tracker.dashbot.io/track?platform=google&v=11.1.0-rest&type=outgoing&apiKey=API_KEY_HERE'

Notice, you must replace the placeholder API_KEY_HERE above with your api key.

Note
This is just an example — we accept any rich media that Facebook accepts.

Example

View a complete example.

Google Integration with @assistant/conversation

Irrespective of how you deploy your webhook handler (via firebase or url), if you use the @assistant/conversation, you can integrate with Dashbot in the following manner.

Create a bot API key

Each bot needs its own API key for tracking.

Create a bot to get an API key.

Install Dashbot via NPM

npm install --save dashbot

Include Dashbot

Use the API key created above.

const dashbot = require('dashbot')(process.env.DASHBOT_API_KEY).google;

After creating an Conversation object, pass it to Dashbot

const { conversation } = require('@assistant/conversation');


const app = converastion();
dashbot.configHandler(app);


app.handle('greeting', conv => {
  ...
}

Custom User Metadata

In order to include custom user metadata such as user IDs, that you would like to see on the Dashbot platform, stringify a JSON object on the dashbot key in the user params section of the conversation object in an intent handler.

For example, the conversation object in the intent handler should look like the following:

app.handle('greeting', conv => {
    let message = 'Hi!';
    if (!conv.user.lastSeenTime) {
        message = 'Welcome back!';
    }
    conv.add(message);
    conv.user.params.dashbot = "{\"dashbotUser\":{\"userId\":\"USER ID HERE\"}}"
});

Advanced Usage

Pass Custom Outgoing Intents for Google

Outbound Intents are an optional, advanced feature.

With Intents, you can roll up similar messages your bot sends to quickly see the combined metrics.

Here is how we define an intent:

  • intent – object – (optional)
    • name – string
    • inputs – array
      • input – object
        • name – string
        • value – string

Intents can be sent for either inbound or outbound messages. Place the intent object at the root level of the JSON that you send for each inbound or outbound message, or use the NPM module.

Adding an Intent for an outbound message

Example: “The weather is 68 degrees and sunny.”

Define Intent

The message “The weather is 68 degrees and sunny.” maps to the WEATHER_RESPONSE Intent with the “forecast” entity “68 and sunny”

{
  "name": "WEATHER_RESPONSE",
  "inputs": [
    {
      "name": "forecast",
      "value": "68 and sunny"
    }
  ]
}

Log outbound Intent via NPM

dashbot.logOutgoingIntent({
  "name": "WEATHER_RESPONSE",
  "inputs": [
    {
      "name": "forecast",
      "value": "68 and sunny"
    }
  ]
});

Special NotHandled Intent

By passing the NotHandled intent, this will enable the special report to show you which messages were not handled by your skill

Log outbound Intent via NPM

dashbot.logOutgoingIntent({ "name": "NotHandled" });

Tracking Events in a Conversation

Events

You may wish to track certain events in conversations, such as:

  • External URL Clicks
  • Social Shares
  • Revenue
  • Anything else…

JSON Format

The JSON that you can send to track an event is:

  • name – string (required)
  • userId – string (required)
  • conversationId – string (optional)
  • type – enum (required)
    • customEvent
    • revenueEvent
    • shareEvent
    • pageLaunchEvent

For each event type, you can pass additional properties:
customEvent

  • extraInfo – object (optional)

revenueEvent

  • amount – number (required)
  • referenceNumber – string (optional)
  • metadata – object (optional)

pageLaunchEvent

  • extraInfo – object (optional)

shareEvent

  • sharedMessage – object (optional)

referralEvent

  • name – string (required)
  • ref – string the referral tag (optional)
  • source – string the referral source (eg. ADS, WEB) (optional)
  • ad_id – string an ID to identify the ad (optional)
  • referer_uri – string the URI that sent the referer(optional)

Tracking Custom Events

Post to the endpoint

https://tracker.dashbot.io/track?platform=google&v=11.1.0-rest&type=event&apiKey=API_KEY_HERE

Make sure to set the ‘Content-Type’ header to ‘application/json’ and to replace API_KEY_HERE with your api key.

The data to POST should pass the following data:

{
  "name": "trackMeEvent",
  "type": "customEvent",
  "userId": "967295313370594",
  "extraInfo": {
    "start": 1500504070512,
    "difference": 374,
    "end": 1500504070886
  }
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
     -d '{"name":"trackMeEvent","type":"customEvent","userId":"967295313370594","extraInfo":{"start":1500504070512,"difference":374,"end":1500504070886}}'
     'https://tracker.dashbot.io/track?platform=google&v=11.1.0-rest&type=event&apiKey=API_KEY_HERE'

Notice, you must replace the placeholder API_KEY_HERE above with your api key.

Tracking Revenue Events

Post to the endpoint

https://tracker.dashbot.io/track?platform=google&v=11.1.0-rest&type=event&apiKey=API_KEY_HERE

Make sure to set the ‘Content-Type’ header to ‘application/json’ and to replace API_KEY_HERE with your api key.

The data to POST should pass the following data:

{
  "name": "boughtSandwich",
  "type": "revenueEvent",
  "userId": "967295313370594",
  "amount": 17.45,
  "metadata": {
    "productName": "Ham Sandwich",
    "sku": "abc123123"
  }
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
     -d '{"name":"boughtSandwich","type":"revenueEvent","userId":"967295313370594","amount":17.45,"metadata":{"productName":"Ham Sandwich","sku":"abc123123"}}'
     'https://tracker.dashbot.io/track?platform=google&v=11.1.0-rest&type=event&apiKey=API_KEY_HERE'

Notice, you must replace the placeholder API_KEY_HERE above with your api key.

Tracking Page Launch Events

Post to the endpoint

https://tracker.dashbot.io/track?platform=google&v=11.1.0-rest&type=event&apiKey=API_KEY_HERE

Make sure to set the ‘Content-Type’ header to ‘application/json’ and to replace API_KEY_HERE with your api key.

The data to POST should pass the following data:

{
  "name": "Launched Detail Page",
  "type": "pageLaunchEvent",
  "userId": "967295313370594",
  "extraInfo": {
    "url": "https://www.dashbot.io/"
  }
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
     -d '{"name":"Launched Detail Page","type":"pageLaunchEvent","userId":"967295313370594","extraInfo":{"url":"https://www.dashbot.io/"}}'
     'https://tracker.dashbot.io/track?platform=google&v=11.1.0-rest&type=event&apiKey=API_KEY_HERE'

Notice, you must replace the placeholder API_KEY_HERE above with your api key.

Tracking Share Events

Post to the endpoint

https://tracker.dashbot.io/track?platform=google&v=11.1.0-rest&type=event&apiKey=API_KEY_HERE

Make sure to set the ‘Content-Type’ header to ‘application/json’ and to replace API_KEY_HERE with your api key.

The data to POST should pass the following data:

{
  "name": "sharedLink",
  "type": "shareEvent",
  "userId": "967295313370594",
  "sharedMessage": {
    "text": "come check out this bot"
  }
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
     -d '{"name":"sharedLink","type":"shareEvent","userId":"967295313370594","sharedMessage":{"text":"come check out this bot"}}'
     'https://tracker.dashbot.io/track?platform=google&v=11.1.0-rest&type=event&apiKey=API_KEY_HERE'

Notice, you must replace the placeholder API_KEY_HERE above with your api key.

Tracking Custom User Metadata

You can send any custom user metadata to build detailed audience segments.

Custom user metadata can be sent for both incoming and outgoing messages.

Examples of metadata that you might send:

  • Your own User ID
    • Store your User ID in userStorage.dashbotUser.userId
  • Experiment Group, for A/B Testing
  • Favorite Book
  • Location

To send Custom User MetaData

Note: if you are using the @assistant/conversation and integrating with dashbot through a fulfilment webhook handler, please refer to the Custom User Metadata section in Google Assistant Conversation

For Google dashbotUser should be set in the userStorage parameter which should be stringify’ed JSON (outgoing example)

{
  "dashbot_timestamp": 1528632520763,
  "request_body": {
    "originalRequest": {
      ...
    }
  },
  "message": {
    "speech": "This is the speech",
    "data": {
      "google": {
        "expect_user_response": true,
        "userStorage": "{\"dashbotUser\": {\"userId\":\"USER123\",\"favoriteBook\":\"Harry Potter\"}}"
      }
    }
  }
}
Edit this page on GitHub

Prev

Universal

Next

Rasa

On this page