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
- input – object
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\"}}" } } }}