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.js with NPM
• REST API

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

Copy
npm install --save dashbot

Include Dashbot

Use the API key created above.

Copy
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:

where the intent object includes:

and the intent input object has fields:

The images field contains image objects that have the fields:

The buttons field contains button objects that have the fields:

The postback includes the fields:

and the button click object includes:

See below for an example.

Log whenever your webhook is called

Copy
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

Copy
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:

Copy
{
  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:

Copy
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:

Copy
{
  "text": "Hi, bot",
  "userId": "USERID_01",
  "platformJson": {
    "whateverJson": "any JSON specific to your platform can be stored here"
  }
}

Sample cURL

Copy
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:

Copy
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:

Copy
{
  "text": "Hello, my human pet",
  "userId": "USERIDHERE123123",
  "platformJson": {
    "whateverJson": "any JSON specific to your platform can be stored here"
  }
}

Sample cURL

Copy
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

Copy
{
  "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?”

Copy
{
  "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”

Copy
{
  "name": "WEATHER_QUERY",
  "inputs": [
    {
      "name": "city",
      "value": "San Francisco"
    }
  ]
}

Append the Intent JSON to the original message

Copy
{
  "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

Copy
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

Copy
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.”

Copy
{
  "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”

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

Append the Intent JSON to the original message

Copy
{
  "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

Copy
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

Copy
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

Copy
const messageForDashbot = {
  "text": "Hi, this is a confusing message for the bot.",
  "userId": "USERIDHERE123123"
}

Becomes:

Copy
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

Copy
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:

Copy
{
  "name": "trackMeEvent",
  "type": "customEvent",
  "userId": "967295313370594",
  "extraInfo": {
    "start": 1500504070512,
    "difference": 374,
    "end": 1500504070886
  }
}

Sample cURL

Copy
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

Copy
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:

Copy
{
  "name": "boughtSandwich",
  "type": "revenueEvent",
  "userId": "967295313370594",
  "amount": 17.45,
  "metadata": {
    "productName": "Ham Sandwich",
    "sku": "abc123123"
  }
}

Sample cURL

Copy
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

Copy
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:

Copy
{
  "name": "Launched Detail Page",
  "type": "pageLaunchEvent",
  "userId": "967295313370594",
  "extraInfo": {
    "url": "https://www.dashbot.io/"
  }
}

Sample cURL

Copy
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

Copy
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:

Copy
{
  "name": "sharedLink",
  "type": "shareEvent",
  "userId": "967295313370594",
  "sharedMessage": {
    "text": "come check out this bot"
  }
}

Sample cURL

Copy
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.

Copy
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:

Copy
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’.

Copy
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’.

Copy
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’.

Copy
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.