Integrating with Amazon Alexa enables voice interaction with customers. Analyzing voice interaction logs can enhance user request understanding and voice application responsiveness.
Welcome to the Alexa documentation for Dimension! Integrating Dimension 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 Dimension via NPM
npm install --save dimensionlabs
Include Dimension and use the API key created above.
const dimension = require('dimension')(process.env.DIMENSION_API_KEY).alexa;
Wrap your handler in the Dimension handler call
before:
exports.handler = skillBuilder
.addRequestHandlers(
LaunchRequestHandler,
...
HelpIntentHandler,
CancelAndStopIntentHandler,
SessionEndedRequestHandler
)
.addErrorHandlers(ErrorHandler)
.lambda();
after:
exports.handler = dimension.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 Dimension.
We have added Dimension 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 Dimension via NPM
npm install --save dimensionlabs
Include Dimension. Use the API key created above.
const dimension = require('dimension')(process.env.DIMENSION_API_KEY).alexa;
Wrap your handler in the Dimension 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 = dimension.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 Dimension.
We have added Dimension 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 Dimension via NPM
npm install --save dimensionlabs
Include Dimension
Use the API key created above.
const dimension = require('dimension')(process.env.DIMENSION_API_KEY).alexa;
Log whenever your webhook is called, and whenever you send a response
app.use(bodyParser.json())
...
app.post('/alexa', (req, res) => {
dimension.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': {}
};
dimension.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) {
dimension.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': {}
};
dimension.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 Dimension Ruby Gem
gem install dimension
Initialize Dimension
Use the API key created above.
@appToken = process.env.DIMENSION_API_KEY
@dba = Dimension::DimensionSDK.new(appToken, requestBody['session'])
Re-initialize on new session (user)
Use the API key created above.
@dba = Dimension::DimensionSDK.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 Dimension Python SDK
pip install dimension
Import the Dimension library
from dimension import alexa
Initialize Dimension
Use the API key created above.
dba = alexa.alexa(os.environ.get(DIMENSION_API_KEY))
Notice in this example, you set the environment variable DIMENSION_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 Dimension Python SDK
pip install dimension
Import the Dimension library
from dimension import alexa
Initialize Dimension
Use the API key created above.
dba = alexa.alexa(os.environ.get('DIMENSION_API_KEY'))
Notice in this example, you set the environment variable DIMENSION_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.dimensionlabs.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.dimensionlabs.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.dimensionlabs.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.dimensionlabs.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 Dimension
https://tracker.dimensionlabs.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.dimensionlabs.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.
