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:

ParameterDescriptionType
textRequired Text of the messageString
userIdRequired This should be the same userId for both incoming and outgoing messages. This is not the bot’s user IDString
intent(Optional) An object containing intent metadataObject
images(Optional) Urls to any imagesArray<Object>
buttons(Optional) Button options in the messageArray<Object>
postback(Optional) Record of any button clicksObject
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:
  • firstName
  • lastName
  • locale
  • timezone
  • gender
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
dashbot_timestamp(Optional) if you want to use your server timestamp you can send a unix-timestamp value see Advanced Usage for more informationNumber

where the intent object includes:

ParameterDescriptionType
namename of intentString
inputsintent inputsArray<Object>

and the intent input object has fields:

ParameterDescriptionType
nameinput nameString
valueinput valueString

The images field contains image objects that have the fields:

ParameterDescriptionType
urlurl of the imageString

The buttons field contains button objects that have the fields:

ParameterDescriptionType
idid of the buttonString
labellabel for the buttonString
valuevalue of the buttonString

The postback includes the fields:

ParameterDescriptionType
buttonClickButton click objectObject

and the button click object includes:

ParameterDescriptionType
buttonIdid of the clicked buttonString

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
    • 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