Dashbot

Amazon Alexa Integrations

Amazon Alexa Integrations

Welcome to the Alexa documentation for Dashbot!

Integrating Dashbot into your Alexa skill is quick and easy. Select Amazon Alexa on the left and choose the option that best matches your environment. If you have any questions, comments, or suggestions, please feel free to contact us.

Lambda Integration with Skills SDK v2 and NPM

Create a Skill API key

Each Skill needs its own API key for tracking.

Create a Skill to get an API key.

Install Dashbot via NPM

npm install --save dashbot

Include Dashbot and use the API key created above.

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

Wrap your handler in the Dashbot handler call

before:

exports.handler = skillBuilder
  .addRequestHandlers(
    LaunchRequestHandler,
    ...
    HelpIntentHandler,
    CancelAndStopIntentHandler,
    SessionEndedRequestHandler
  )
  .addErrorHandlers(ErrorHandler)
  .lambda();

after:

exports.handler = dashbot.handler(
  skillBuilder
  .addRequestHandlers(
    LaunchRequestHandler,
    ...
    HelpIntentHandler,
    CancelAndStopIntentHandler,
    SessionEndedRequestHandler
  )
  .addErrorHandlers(ErrorHandler)
  .lambda()
);

You’re all set!

Example

Using the Alexa Skills Kit SDK for Node.js and AWS Lambda, it is easy to integrate Dashbot.

We have added Dashbot to these three sample Alexa Skills:

Lambda Integration with Skills SDK and NPM

Create a Skill API key

Each Skill needs its own API key for tracking.

Create a Skill 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).alexa;

Wrap your handler in the Dashbot handler call

before:

exports.handler = (event, context, callback) => {
  const alexa = Alexa.handler(event, context);
  alexa.appId = APP_ID;
  alexa.resources = languageString;
  alexa.registerHandlers(newSessionHandlers, startStateHandlers, triviaStateHandlers, helpStateHandlers);
    alexa.execute();
};

after:

exports.handler = dashbot.handler(
  (event, context, callback) => {
    const alexa = Alexa.handler(event, context);
    alexa.appId = APP_ID;
    alexa.resources = languageString;
    alexa.registerHandlers(newSessionHandlers, startStateHandlers, triviaStateHandlers, helpStateHandlers);
    alexa.execute();
  }
);

You’re all set!

Example

Using the Alexa Skills Kit SDK for Node.js and AWS Lambda, it is easy to integrate Dashbot.

We have added Dashbot to these three sample Alexa Skills:

Alexa Webhook Integration with NPM

Create a Skill API key

Each Skill needs its own API key for tracking.

Create a Skill 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).alexa;

Log whenever your webhook is called, and whenever you send a response

app.use(bodyParser.json())
...
app.post('/alexa', (req, res) => {
  dashbot.logIncoming(req.body);
  ...
  const responseBody = {
    'version': '1.0',
    'response': {
      'outputSpeech': {
        'type': 'PlainText',
        'text': 'Hello World!'
      },
      'card': {
        'content': 'Hello World!',
        'title': 'Hello World',
        'type': 'Simple'
      },
      'shouldEndSession': true
    },
    'sessionAttributes': {}
  };
  dashbot.logOutgoing(req.body, responseBody);
  res.send(responseBody);
}

Example

View a sample.

Sending outbound Intents (optional)

Optionally send outbound Intents to be able to rollup messages based on the response.

Add the Intent to the responseBody

app.use(bodyParser.json())
...
app.post('/alexa', function(req, res) {
  dashbot.logIncoming(req.body);
  ...
  const responseBody = {
    'intent': {
       'name' : 'WEATHER_RESPONSE',
       'inputs' : [
         {
           'name': 'forecast',
           'value': '68 and sunny',
         }
       ]
     },
    'version': '1.0',
    'response': {
      'outputSpeech': {
        'type': 'PlainText',
        'text': 'Hello World!'
      },
      'card': {
        'content': 'Hello World!',
        'title': 'Hello World',
        'type': 'Simple'
      },
      'shouldEndSession': true
    },
    'sessionAttributes': {}
  };
  dashbot.logOutgoing(req.body, responseBody);
  res.send(responseBody);
}

Ruby Gem

Create a Skill API key

Each Skill needs its own API key for tracking.

Create a Skill to get an API key.

Install Dashbot Ruby Gem

gem install dashbot

Initialize Dashbot

Use the API key created above.

@appToken = process.env.DASHBOT_API_KEY
@dba = Dashbot::DashbotSDK.new(appToken, requestBody['session'])

Re-initialize on new session (user)

Use the API key created above.

@dba = Dashbot::DashbotSDK.new(appToken, requestBody['session'])

Track requests

@vi.track(requestBody['request']['intent']['name'] , requestBody['request'], response.build_response)

Python SDK

Create a Skill API key

Each Skill needs its own API key for tracking.

Create a Skill to get an API key.

Install Dashbot Python SDK

pip install dashbot

Import the Dashbot library

from dashbot import alexa

Initialize Dashbot

Use the API key created above.

dba = alexa.alexa(os.environ.get(DASHBOT_API_KEY))

Notice in this example, you set the environment variable DASHBOT_API_KEY to your api key.

Log incoming requests

dba.logIncoming(incomingRequest)

Log outgoing response

Pass both the incoming request and the response

dba.logOutgoing(incomingRequest, response)

Alexa Python SDK (with Flask)

Create a Skill API key

Each Skill needs its own API key for tracking.

Create a Skill to get an API key.

Install Dashbot Python SDK

pip install dashbot

Import the Dashbot library

from dashbot import alexa

Initialize Dashbot

Use the API key created above.

dba = alexa.alexa(os.environ.get('DASHBOT_API_KEY'))

Notice in this example, you set the environment variable DASHBOT_API_KEY to your api key.

Create the Global Request & Response Interceptors

from ask_sdk_core.serialize import DefaultSerializer


ds=DefaultSerializer()


@sb.global_request_interceptor()
def request_logger(handler_input):
    serializedRequest=ds.serialize(handler_input.request_envelope)
    dba.logIncoming(serializedRequest)


@sb.global_response_interceptor()
def response_logger(handler_input, response):
    serializedRequest=ds.serialize(handler_input.request_envelope)
    serializedResponse=ds.serialize(response)
    dba.logOutgoing(serializedRequest,serializedResponse)

REST API

Create a Skill API key

Each Skill needs its own API key for tracking.

Create a Skill to get an API key.

There are two integration points as outlined below.

1. When Alexa posts to your webhook endpoint

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

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

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

The data to POST should pass the following data:

{
  "event": {
    "version": "1.0",
    "session": {
      "new": false,
      "sessionId": "amzn1.echo-api.session.abcde1b7-aee0-41e6-8192-f6faaed9f5ef",
      "application": {
        "applicationId": "amzn1.echo-sdk-ams.app.123456-d0ed-0000-ad00-000000d00ebe"
      },
      "attributes": {},
      "user": {
        "userId": "amzn1.account.AM12347HF3FAM1B261HK7FFM3A2"
      }
    },
    "request": {
      "type": "IntentRequest",
      "requestId": "amzn1.echo-api.request.123123a-733e-4e89-893a-fdcb77e2ef0d",
      "timestamp": "2015-05-13T12:34:56Z",
      "intent": {
        "name": "airportinfo",
        "slots": {
          "AIRPORTCODE": {
            "value": "JFK",
            "name": "AIRPORTCODE"
          }
        }
      }
    }
  }
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
     -d '{"event":{"version":"1.0","session":{"new":false,"sessionId":"amzn1.echo-api.session.abcde1b7-aee0-41e6-8192-f6faaed9f5ef","application":{"applicationId":"amzn1.echo-sdk-ams.app.123456-d0ed-0000-ad00-000000d00ebe"},"attributes":{},"user":{"userId":"amzn1.account.AM12347HF3FAM1B261HK7FFM3A2"}},"request":{"type":"IntentRequest","requestId":"amzn1.echo-api.request.123123a-733e-4e89-893a-fdcb77e2ef0d","timestamp":"2015-05-13T12:34:56Z","intent":{"name":"airportinfo","slots":{"AIRPORTCODE":{"value":"JFK","name":"AIRPORTCODE"}}}}}}'
     'https://tracker.dashbot.io/track?platform=alexa&v=11.1.0-rest&type=incoming&apiKey=API_KEY_HERE'

Notice on line 3, you must replace the placeholder API_KEY_HERE with your api key.

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

2. When your Skill sends a message

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

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

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

The data to POST should pass the following data:

{
  "event": {
    "version": "1.0",
    "session": {
      "new": false,
      "sessionId": "amzn1.echo-api.session.abcde1b7-aee0-41e6-8192-f6faaed9f5ef",
      "application": {
        "applicationId": "amzn1.echo-sdk-ams.app.123456-d0ed-0000-ad00-000000d00ebe"
      },
      "attributes": {},
      "user": {
        "userId": "amzn1.account.AM12347HF3FAM1B261HK7FFM3A2"
      }
    },
    "request": {
      "type": "IntentRequest",
      "requestId": "amzn1.echo-api.request.6919844a-733e-4e89-893a-fdcb77e2ef0d",
      "timestamp": "2015-05-13T12:34:56Z",
      "intent": {
        "name": "airportinfo",
        "slots": {
          "AIRPORTCODE": {
            "value": "JFK",
            "name": "AIRPORTCODE"
          }
        }
      }
    }
  },
  "response": {
    "version": "1.0",
    "sessionAttributes": {},
    "response": {
      "shouldEndSession": true,
      "outputSpeech": {
        "type": "SSML",
        "ssml": "<speak>The weather at JFK is 68 and sunny.</speak>"
      }
    }
  }
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
     -d '{"event":{"version":"1.0","session":{"new":false,"sessionId":"amzn1.echo-api.session.abcde1b7-aee0-41e6-8192-f6faaed9f5ef","application":{"applicationId":"amzn1.echo-sdk-ams.app.123456-d0ed-0000-ad00-000000d00ebe"},"attributes":{},"user":{"userId":"amzn1.account.AM12347HF3FAM1B261HK7FFM3A2"}},"request":{"type":"IntentRequest","requestId":"amzn1.echo-api.request.6919844a-733e-4e89-893a-fdcb77e2ef0d","timestamp":"2015-05-13T12:34:56Z","intent":{"name":"airportinfo","slots":{"AIRPORTCODE":{"value":"JFK","name":"AIRPORTCODE"}}}}},"response":{"version":"1.0","sessionAttributes":{},"response":{"shouldEndSession":true,"outputSpeech":{"type":"SSML","ssml":"The weather at JFK is 68 and sunny."}}}}'
     'https://tracker.dashbot.io/track?platform=alexa&v=11.1.0-rest&type=outgoing&apiKey=API_KEY_HERE'

Notice on line 3, you must replace the placeholder API_KEY_HERE with your api key.

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

3. Outbound Intents (Optional)

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

Define Intent

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

Append the Intent JSON to the original message

{
  "event": {
    "version": "1.0",
    "session": {
      "new": false,
      "sessionId": "amzn1.echo-api.session.abcde1b7-aee0-41e6-8192-f6faaed9f5ef",
      "application": {
        "applicationId": "amzn1.echo-sdk-ams.app.123456-d0ed-0000-ad00-000000d00ebe"
      },
      "attributes": {},
      "user": {
        "userId": "amzn1.account.AM12347HF3FAM1B261HK7FFM3A2"
      }
    },
    "request": {
      "type": "IntentRequest",
      "requestId": "amzn1.echo-api.request.6919844a-733e-4e89-893a-fdcb77e2ef0d",
      "timestamp": "2015-05-13T12:34:56Z",
      "intent": {
        "name": "airportinfo",
        "slots": {
          "AIRPORTCODE": {
            "value": "JFK",
            "name": "AIRPORTCODE"
          }
        }
      }
    }
  },
  "response": {
    "intent": {
      "name": "WEATHER_RESPONSE",
      "inputs": [
        {
          "name": "forecast",
          "value": "68 and sunny"
        }
      ]
    },
    "version": "1.0",
    "sessionAttributes": {},
    "response": {
      "shouldEndSession": true,
      "outputSpeech": {
        "type": "SSML",
        "ssml": "<speak>The weather at JFK is 68 and sunny.</speak>"
      }
    }
  }
}

Post the complete message to Dashbot

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

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

Sample cURL

curl -X POST -H "Content-Type: application/json"
     -d '{"event":{"version":"1.0","session":{"new":false,"sessionId":"amzn1.echo-api.session.abcde1b7-aee0-41e6-8192-f6faaed9f5ef","application":{"applicationId":"amzn1.echo-sdk-ams.app.123456-d0ed-0000-ad00-000000d00ebe"},"attributes":{},"user":{"userId":"amzn1.account.AM12347HF3FAM1B261HK7FFM3A2"}},"request":{"type":"IntentRequest","requestId":"amzn1.echo-api.request.6919844a-733e-4e89-893a-fdcb77e2ef0d","timestamp":"2015-05-13T12:34:56Z","intent":{"name":"airportinfo","slots":{"AIRPORTCODE":{"value":"JFK","name":"AIRPORTCODE"}}}}},"response":{"intent":{"name":"WEATHER_RESPONSE","inputs":[{"name":"forecast","value":"68 and sunny"}]},"version":"1.0","sessionAttributes":{},"response":{"shouldEndSession":true,"outputSpeech":{"type":"SSML","ssml":"The weather at JFK is 68 and sunny."}}}}'
     'https://tracker.dashbot.io/track?platform=alexa&v=11.1.0-rest&type=outgoing&apiKey=API_KEY_HERE'

Notice on line 3, you must replace the API_KEY_HERE placeholder with your api key.

Example

View a complete example.

Advanced Integrations

The following lists some more advanced integration methods tailored to specific use cases.

Cloudwatch Logs

This integration path follows from creating an Alexa application via a separate service within AWS (such as AWS Lambda).

Requirements:

  • Alexa application is hosted separately from the Alexa Developer Console
  • aws-cli on host machine
  • permissions and connection to AWS Cloudwatch Logs from host machine
  • Dashbot library with peer dependency dashbot-logger on the host machine

Configure Dashbot Library

In your lambda function that handles Alexa Skills requests, call the logIntegration method on the dashbot alexa object and pass configuration options as specified by the dashbot-logger library. You are required to set the parameter logGroupName that you specify when creating your CloudFormation stack below.

const dashbot = require("dashbot")(
  "YOUR_DASHBOT_API_KEY"
).alexa.logIntegration({ logGroupName: "YOUR_LOG_GROUP_NAME" })

Cloudformation Stack

Once you create the stack, you will have your Alexa Skills Lambda function log to the Cloudwatch Logs log-group. The log in your newly created log-group will then be passed to Dashbot!

Alexa Specific Usage

Alexa Outgoing Intents (Optional)

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.setOutgoingIntent({
  "name": "WEATHER_RESPONSE",
  "inputs": [
    {
      "name": "forecast",
      "value": "68 and sunny"
    }
  ]
});

Special NotHandled Intent

By passing the NotHandled intent, this will allow you to see which interactions were not handled by your skill

Log NotHandled Intent via NPM

dashbot.setNotHandled();

Tracking Events in a Conversation

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=alexa&v=11.1.0-rest&type=event&apiKey=API_KEY_HERE

Make sure to set the ‘Content-Type’ header to ‘application/json’ and 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=alexa&v=11.1.0-rest&type=event&apiKey=API_KEY_HERE'

Notice on line 3, you must replace the placeholder API_KEY_HERE with your api key.

Tracking Revenue Events

Post to the endpoint

https://tracker.dashbot.io/track?platform=alexa&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=alexa&v=11.1.0-rest&type=event&apiKey=API_KEY_HERE'

Notice on line 3, you must replace the placeholder API_KEY_HERE with your api key.

Tracking Page Launch Events

Post to the endpoint

https://tracker.dashbot.io/track?platform=alexa&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=alexa&v=11.1.0-rest&type=event&apiKey=API_KEY_HERE'

Notice on line 3, you must replace the placeholder API_KEY_HERE with your api key.

Tracking Share Events

Post to the endpoint

https://tracker.dashbot.io/track?platform=alexa&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=alexa&v=11.1.0-rest&type=event&apiKey=API_KEY_HERE'

Notice on line 3, you must replace the placeholder API_KEY_HERE 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
  • Experiment Group, for A/B Testing
  • Favorite Book
  • Location

To send Custom User MetaData

To pass custom metadata, set the dashbotUser session attribute

'NewIntent': function () {
 //generate a new fact using an array of available facts (data)
  ...
 this.attributes.dashbotUser = {
  favoriteBook: 'Harry Potter'
 }
 ...
 this.emit(':responseReady');
}

Or, in the outgoing JSON:

"dashbot_timestamp": 1529391516389,
 "event": {
  ...
 },
 "response": {
  "version": "1.0",
  "response": {
   "shouldEndSession": false,
   "outputSpeech": {
    "type": "SSML",
    "ssml": "<speak> <audio src="https://s3.amazonaws.com/volley-voice-service-prod/output_1ca64570533a435a28316bafaa766fdc.mp3" /> </speak>"
   },
   "reprompt": {
    "outputSpeech": {
     "type": "SSML",
     "ssml": "<speak> <audio src="https://s3.amazonaws.com/volley-voice-service-prod/reprompt_1ca64570533a435a28316bafaa766fdc.mp3" /> </speak>"
    }
   }
  },
  "sessionAttributes": {
   "dashbotUser": {
    "favoriteBook": "Harry Potter"
   },
   ...
  }
 }
}

Alexa User Exclusion

In certain cases, you may want to exclude certain user IDs (test users, internal users) from your analytics at Dashbot. For other platforms, you may simply exclude these users yourself, based on the User ID, but if you are using our Alexa integration, that is not possible.

So, we have added a configurable method to exclude a list of user IDs.

To pass this list, modify the dashbot call to pass the list of user IDs to ignore.

const ignoreUserIds = [
  'userID-123123123',
  'userID-234234234'
];
const dashbot = require('dashbot')(
  process.env.DASHBOT_API_KEY,
  { ignoreUserIds }
).alexa;

Device Capabilities Report

Dashbot has a powerful Device Capabilities Report that will tell you how many of your users are accessing your skill with a display capable device.

In order to see data for this, however, you must enable the Display Interface for your skill prior to submission to Amazon.

In order to do this, go to your Alexa Developer Console, and under the “Interfaces” menu, turn on the “Display Interface” selection

Once this is enabled, you will see a Device Capability report that looks like this:

Edit this page on GitHub

Prev

Report

Next

Lex

On this page