Dashbot Universal API

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 an API key

Here is a quick video guide on how to generate you Dashbot API keys.

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: 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 information	Number

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 an API key

Here is a quick video guide on how to generate you Dashbot API keys

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