Dashbot
Universal (Any Platform) Integration
Universal (Any Platform) Integration
Welcome to the Universal documentation for Dashbot! Integrating Dashbot into your chatbot, web bot, SMS bot, voice application, or other conversational interface, is quick and easy.
If you have any questions, comments, or suggestions, please feel free to contact us.
Node Integration
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).universal;
Notice above, we assume you have set an environment variable DASHBOT_API_KEY
with your api key.
Whenever your bot sends, or receives data, log to Dashbot
Before diving into the code, the below tables explain the message format you will log to Dashbot.
Message Format
You can send the following fields:
Parameter | Description | Type |
---|---|---|
text | Required Text of the message | String |
userId | Required This should be the same userId for both incoming and outgoing messages. This is not the bot’s user ID | String |
intent | (Optional) An object containing intent metadata | Object |
images | (Optional) Urls to any images | Array<Object> |
buttons | (Optional) Button options in the message | Array<Object> |
postback | (Optional) Record of any button clicks | Object |
platformJson | (Optional) Send your platform-specific message JSON here. It will be available for viewing in your transcripts. Reporting on this data is available with our enterprise plan. | Object |
platformUserJson | (Optional) send any user-specific information (ie. zipcode, A/B test group, etc). Reporting on this data is available from audience builder, with our enterprise plan. If you use these exact field names, they will be used in the expected places on Dashbot reports:
| Object |
sessionId | (Optional) if you do not want Dashbot to calculate sessions based on the 5-minute message timeout, you may send sessionId instead. | String |
where the intent object includes:
Parameter | Description | Type |
---|---|---|
name | name of intent | String |
inputs | intent inputs | Array<Object> |
and the intent input object has fields:
Parameter | Description | Type |
---|---|---|
name | input name | String |
value | input value | String |
The images field contains image objects that have the fields:
Parameter | Description | Type |
---|---|---|
url | url of the image | String |
The buttons field contains button objects that have the fields:
Parameter | Description | Type |
---|---|---|
id | id of the button | String |
label | label for the button | String |
value | value of the button | String |
The postback includes the fields:
Parameter | Description | Type |
---|---|---|
buttonClick | Button click object | Object |
and the button click object includes:
Parameter | Description | Type |
---|---|---|
buttonId | id of the clicked button | String |
See below for an example.
Log whenever your webhook is called
const messageForDashbot = { "text": "Hi, bot", "userId": "USERIDHERE123123", "platformJson": { "whateverJson": "any JSON specific to your platform can be stored here" }};
dashbot.logIncoming(messageForDashbot);
Whenever you send a message, log the response
const messageForDashbot = { "text": "Hello, my human pet", "userId": "USERIDHERE123123", "platformJson": { "whateverJson": "any JSON specific to your platform can be stored here" }};
dashbot.logOutgoing(messageForDashbot);
Example
View sample code.
Integrate the REST API
Using the Universal integration, you can use Dashbot with any conversational user interface.
Create a bot API key
Each bot needs its own API key for tracking.
Create a bot to get an API key.
There are two integration points as outlined below. Before diving into the integration points, the message format section describes the payload you will be logging to Dashbot.
Message Format
You can send the fields listed above with the following as an example:
{ text: "I'd like to place an order for a pizza using 1 bitcoin", userId: "user01", intent: { name: "Order", inputs: [{ name: "Dish", value: "Pizza" }, { name: "Payment", value: "1 bitcoin" }], confidence: 1.0 }, images: [ "https://i.example.com/orders/pizza.png" ], buttons: [{ id: "=ay13.x", label: "Pizza", value: "pizza" }, { id: "=asdf2", label: "Drink", value: "drink" }], postback: { buttonClick: { buttonId: "=ay13.x" } }, platformJson: {}, platformUserJson: {}, sessionId: "1"}
1. When your bot receives a message
When your bot receives a message, post the data to the following endpoint:
https://tracker.dashbot.io/track?platform=universal&v=10.1.1-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:
{ "text": "Hi, bot", "userId": "USERID_01", "platformJson": { "whateverJson": "any JSON specific to your platform can be stored here" }}
Sample cURL
curl -X POST -H "Content-Type: application/json" <br></br>-d '{"text":"Hi, bot","userId":"USERIDHERE123123","platformJson":{"whateverJson":"any JSON specific to your platform can be stored here"}}' <br></br>'https://tracker.dashbot.io/track?platform=universal&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 all the fields listed at the top of the page.
2. When your bot sends a message
When your bot sends a message, POST to the following endpoint:
https://tracker.dashbot.io/track?platform=universal&v=11.1.0-rest&type=outgoing&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:
{ "text": "Hello, my human pet", "userId": "USERIDHERE123123", "platformJson": { "whateverJson": "any JSON specific to your platform can be stored here" }}
Sample cURL
curl -X POST -H "Content-Type: application/json" <br></br>-d '{"text":"Hello, my human pet","userId":"USERIDHERE123123","platformJson":{"whateverJson":"any JSON specific to your platform can be stored here"}}' <br></br>'https://tracker.dashbot.io/track?platform=universal&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.
Sample JSON with optional fields
{ "text": "Hello, my human pet", "userId": "USERIDHERE123123", "intent": { "name": "HELLO" }, "images": [{ "url": "https://media.giphy.com/media/mIZ9rPeMKefm0/giphy.gif" }], "platformUserJson": { "firstName": "Will", "lastName": "Robinson", "locale": "en_US", "timezone": "-8", "gender": "male" }, "platformJson": { "whateverJson": "any JSON specific to your platform can be stored here" }}
Note
This is just an example — we accept all the fields listed at the top of the page.
Example
View a complete example.
Advanced Usage
Intent Tracking
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
- confidence – float (optional) – the confidence value for your intent from 0.0 (completely uncertain) to 1.0 (completely certain)
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.
Adding an Intent for an inbound message
Example: “What is the weather in San Francisco?”
{ "text": "What is the weather in San Francisco?", "userId": "USERIDHERE123123", "platformJson": { "whateverJson": "any JSON specific to your platform can be stored here" }}
Define Intent
The message “What is the weather in San Francisco?” maps to the WEATHER_QUERY Intent with the “city” entity “San Francisco”
{ "name": "WEATHER_QUERY", "inputs": [ { "name": "city", "value": "San Francisco" } ]}
Append the Intent JSON to the original message
{ "text": "What is the weather in San Francisco?", "userId": "USERIDHERE123123", "platformJson": { "whateverJson": "any JSON specific to your platform can be stored here" }, "intent": { "name": "WEATHER_QUERY", "inputs": [ { "name": "city", "value": "San Francisco" } ], "confidence": 0.9766 }}
Post the complete message to Dashbot
https://tracker.dashbot.io/track?platform=universal&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.
Sample cURL
curl -X POST -H "Content-Type: application/json" -d '{"text":"What is the weather in San Francisco?","userId":"USERIDHERE123123","conversationId":"GROUPCHATID234","platformJson":{"whateverJson":"any JSON specific to your platform can be stored here"},"intent":{"name":"WEATHER_QUERY","inputs":[{"name":"city","value":"San Francisco"}]}}''https://tracker.dashbot.io/track?platform=universal&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.
Adding an Intent for an outbound message
Example: “The weather is 68 degrees and sunny.”
{ "text": "The weather is 68 and sunny.", "userId": "USERIDHERE123123", "platformJson": { "whateverJson": "any JSON specific to your platform can be stored here" }}
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" } ]}
Append the Intent JSON to the original message
{ "text": "The weather is 68 and sunny.", "userId": "USERIDHERE123123", "platformJson": { "whateverJson": "any JSON specific to your platform can be stored here" }, "intent": { "name": "WEATHER_RESPONSE", "inputs": [ { "name": "forecast", "value": "68 and sunny" } ] }}
Post the complete message to Dashbot
https://tracker.dashbot.io/track?platform=universal&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.
Sample cURL
curl -X POST -H "Content-Type: application/json" -d '{"text":"The weather is 68 and sunny.","userId":"USERIDHERE123123","conversationId":"GROUPCHATID234","platformJson":{"whateverJson":"any JSON specific to your platform can be stored here"},"intent":{"name":"WEATHER_RESPONSE","inputs":[{"name":"forecast","value":"68 and sunny"}]}}' 'https://tracker.dashbot.io/track?platform=universal&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.
Universal NotHandled Intent
It is very important to understand when a user says something to your bot that it does not understand.
By passing Dashbot the NotHandled Intent, you can take advantage of the Not Handled report.
For incoming messages that your bot does not handle, set the intent name to “NotHandled” to take advantage of this special report.
Add the NotHandled Intent to the JSON
Prior to sending the message to Dashbot, add an intent with the name NotHandled
const messageForDashbot = { "text": "Hi, this is a confusing message for the bot.", "userId": "USERIDHERE123123"}
Becomes:
const messageForDashbot = { "text": "Hi, this is a confusing message for the bot.", "userId": "USERIDHERE123123", "intent": { "name": "NotHandled" }}
Tracking 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
- referralEvent
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=universal&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=universal&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=generic&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=generic&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=generic&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=generic&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=generic&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=generic&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.
Live Person Takeover
Dashbot enables Live Person Takeover of bots to insert a real person into a session stream, improving engagement and increasing conversions.
When viewing a live session from the Transcripts report, you can send messages as if they are coming from the bot.
In order to take over the session, you need to pause the bot, otherwise the bot will continue to respond to subsequent messages from the user.
Bot Pause
The first step is to be able to pause the bot, so that when you insert a live person, the bot does not respond.
Create a Pause Webhook
Your webhook will receive two fields in the body:
- userId
- the user id of the session to pause
- if you send a conversation id, this will be the conversation id instead of the user id
- paused
- true = pause the bot
- false = unpause the bot
While the details of the implementation may vary, at a high level, your webhook should keep track of which user sessions are paused. Whenever a new message is received, check if the session is paused for that user, and if so, stop the bot from responding.
Example
This is basic example that maintains state in memory. For a more robust solution, save the state in a database or other persistent memory store.
const pausedUsers = {}app.post('/pause', jsonParser, (req, res) => { const { paused, userId } = req.body pausedUsers[userId] = paused res.send('ok')})
And then, check the status after receiving a message:
app.post('/webhook/', jsonParser, (req, res) => { dashbot.logIncoming(req.body); if (req.body.entry){ req.body.entry.forEach((entry) => { if (entry.messaging) { entry.messaging.forEach((event) => { const recipientId = event.sender.id; if (!pausedUsers[recipientId]) { // handle message if session is not paused for this userId [...] } } } } }}
Add the Webhook URL to your Account
Go to your Account page and select ‘edit’ next to the bot you want to add a pause webhook to.
Enter the URL in the field and click ‘save’.
http://mycoolnewbot.io/pause
All requests to your webhook will be signed with the Dashbot Secret Key, if provided.
Live Person Takeover
To send messages as your bot, you can provide a webhook to Dashbot. It is up to you to properly handle the webhook payload and send the right message to the right user.
Create a Webhook
Your webhook will receive two fields in the body:
- userId
- the user id of the session to pause
- in the case of a multi-user session, this is the last user id seen
- conversationId
- the conversation id. If you do not pass a conversationId, this will be the same as userId.
- apiKey
- the Dashbot API key — to let us know which of your bots to use
- text
- the text to send (that you entered in the text box)
The exact details of how you implement your webhook are up to you, but at a high level, with the data in this payload, you should have everyting you need to send the message to the right user or conversation.
Add the Webhook URL to your Account
Go to your Account page and select ‘edit’ next to the bot you want to add a send webhook to.
Enter the URL in the field and click ‘save’.
http://mycoolnewbot.io/liveperson
All requests to your webhook will be signed with the Dashbot Secret Key, if provided.
Try it out
Start a new session with your bot and open the session from the Live Transcripts report.
Click the ‘pause’ button to stop the bot from responding.
Type a message in the form. The message will be sent as if coming from the bot.
Try typing a message to the bot as a user. The bot should not respond after the pause button has been selected.
Click ‘unpause’ to unpause the bot and return it to normal functionality.
Now if you type a message to the bot as a user, the bot should respond.
Broadcast
Dashbot allows you to broadcast a message to your users for any Universal integration. We requested, Dashbot will broadcast a message to the webhook configured in your bot settings.
Sending a Broadcast
To send messages as your bot, you must provide a webhook to Dashbot. It is up to you to properly handle the webhook payload and send the right message to the right user.
Create a Webhook
Your webhook will receive four fields in the body:
- userId
- the user id to message
- apiKey
- the Dashbot API key — to let you know which of your bots to use
- text
- the text to send (that you entered in the text box)
- messageJson
- the JSON of the message to send (if you entered JSON) — or, if you entered text only, text will be in here as well.
The exact details of how you implement your webhook are up to you, but at a high level, with the data in this payload, you should have everyting you need to send the message to the right user or conversation.
Add the Webhook URL to your Account
Go to your Account page and select ‘edit’ next to the bot you want to add a send webhook to.
Enter the URL in the field and click ‘save’.
http://mycoolnewbot.io/sendMessage
All requests to your webhook will be signed with the Dashbot Secret Key, if provided.
Try it out
Go to the “Broadcasts” section for your bot on Dashbot — from there, you may create a new broadcast campaign and send a campaign to the selected segment of users. In order to create a segment, you will need to use Dashbot Audience Builder.
Edit this page on GitHub