Welcome to the Google Assistant documentation for Dimension! Integrating Dimension 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 Dimension via NPM

npm install --save dimensionlabs

Include Dimension

Use the API key created above.

const dimension = require('dimension')(process.env.DIMENSION_API_KEY).google;

After creating a DialogflowApp object, pass it to Dimension

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

Examples

Here are two samples with Dimension 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 Dimension NPM module in package.json

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

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

Include Dimension

Use the API key created above.

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

After creating a Dialogflow object, pass it to Dimension

const app = dialogflow();
dimension.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 Dimension NPM module in package.json

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

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

Include Dimension

Use the API key created above.

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

const dimension = require('dimension')(process.env.DIMENSION_API_KEY).google;

After creating a DialogflowApp object, pass it to Dimension

exports.dialogflowFirebaseFulfillment = functions.https.onRequest((request, response) => {
  const app = new DialogflowApp({request: request, response: response});
  dimension.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 Dimension via NPM

npm install --save dimensionlabs

Include Dimension

Use the API key created above.

const dimension = require('dimension')(process.env.DIMENSION_API_KEY).google;

After creating an ActionsSdkApp object, pass it to Dimension

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 });
  dimension.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 Dimension via NPM

npm install --save dimensionlabs

Include Dimension

Use the API key created above.

const dimension = require('dimension')(process.env.DIMENSION_API_KEY).google;

Log whenever your webhook is called

app.use(bodyParser.json())
...
app.post('/guessnumber', (request, response) => {
  dimension.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
      }
    }
  ]
}
dimension.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 Dimension Python SDK

pip install dimension

Import the Dimension library

from dimension import google

Initialize Dimension

Use the API key created above.

dba = google.google(process.env.DIMENSION_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.dimensionlabs.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.dimensionlabs.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.dimensionlabs.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.dimensionlabs.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.dimensionlabs.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.dimensionlabs.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 Dimension 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 Dimension via NPM

npm install --save dimensionlabs

Include Dimension

Use the API key created above.

const dimension = require('dimension')(process.env.DIMENSION_API_KEY).google;

After creating an Conversation object, pass it to Dimension

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

const app = converastion();
dimension.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 Dimension platform, stringify
a JSON object on the dimension 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.dimension = "{\"dimensinoUser\":{\"userId\":\"USER ID HERE\"}}"
});

Google Integration with Dialogflow Messenger

Google has a plug and play Dialogflow Messenger that is currently in the beta phase.
You can see more information about it here.

After following the instructions on how to integrate the messenger into your site. We need to use Dimension's
Universal Integration Steps in order to properly receive incoming and outgoing messages within the chat.

Code Example

const dimension_apikey = "[YOUR_API_KEY]";
const dimension = require('dimension')(dimension_apikey).universal;

const dfMessenger = document.querySelector("df-messenger");

// for listening to messages typed by the user
dfMessenger.addEventListener("df-user-input-entered", function (e) {
  const userInput = e.detail.input;
  const incoming = {
    userId: "the_user_id", // replace this
    text: userInput,
    platformJson: e.detail
  }; 

  dimension.logIncoming(incoming);
});

// for listening to messages sent by the bot
dfMessenger.addEventListener("df-response-received", function (e) {
  const dfResponse = e.detail.response;
  const outgoing = {
    userId: "the_user_id", // replace this
    text: dfResponse.queryResult.fulfillmentText,
    platformJson: e.detail,
    intent: dfResponse.queryResult.intent
  };

  dimension.logOutgoing(outgoing);
});

Note that on the code examples above. We are showing how you might achieve it on your client-side JavaScript code.
However, this exposes your Dimension API Key. You can choose to call the Dimension API on your server code instead
to secure your API key.

After the above implementation, you should be able to see chat data flowing into Dimension.

React Example

You can check a code snippet example here for
what this might look like in React.

{
  "dimensionlabs_timestamp": 1528632520763,
  "request_body": {
    "originalRequest": {
      ...
    }
  },
  "message": {
    "speech": "This is the speech",
    "data": {
      "google": {
        "expect_user_response": true,
        "userStorage": "{\"dimensionUser\": {\"userId\":\"USER123\",\"favoriteBook\":\"Harry Potter\"}}"
      }
    }
  }
}