Dashbot

SMS Documentation

Welcome to the SMS documentation for Dashbot! Integrating Dashbot into your SMS chatbot is quick and easy.

If you have any questions, comments, or suggestions, please feel free to contact us.

SMS Integration with NPM

Create a bot API key

Each bot needs its own API key for tracking.

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).sms;

Whenever your bot sends, or receives data, log to Dashbot

Message Format

You can send the following fields:

text – string – (required)
userId – string – (required) – should be the SAME userId for both incoming and outgoing messages this is NOT the bot’s user ID
intent – object – (optional)
- name – string
- inputs – array
  - input – object
    - name – string
    - value – string
images – array – (optional)
- image – object
  - url – string
buttons – array – (optional)
- button – object
  - id – string
  - label – string
  - value – string
postback – object (optional)
- buttonClick – object
  - buttonId – string
platformJson – object (optional) – send ALL of your platform-specific JSON here. It will be available for viewing in your transcripts.

Log whenever your webhook is called

const messageForDashbot = {
  "text": "Hi, bot",
  "userId": "+14155551234",
  "platformJson": {
    "whateverJson": "any JSON specific to your platform can be stored here -- if you are using Twilio, put the req.body here"
  }
};
dashbot.logIncoming(messageForDashbot);

Whenever you send a message, log the response

const messageForDashbot = {
  "text": "Hello, my human pet",
  "userId": "+14155551234",
  "platformJson": {
    "whateverJson": "any JSON specific to your platform can be stored here -- if you are using Twilio, put the req.body here"
  }
};
dashbot.logOutgoing(messageForDashbot);

Example

View sample code for complete example.

SMS Integration with REST API

Create a bot API key

Each bot needs its own API key for tracking.

Create a bot to get an API key.

Integrate the REST API

There are two integration points as outlined below.

1. When bot posts to your webhook endpoint

When your bot receives a message, post the data to the following endpoint:

https://tracker.dashbot.io/track?platform=sms&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.

The data to POST should pass the following data:

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

Sample cURL

curl -X POST -H "Content-Type: application/json"
     -d '{"text":"Hi, bot","userId":"+14155551234","platformJson":{"whateverJson":"any JSON specific to your platform can be stored here"}}'
     'https://tracker.dashbot.io/track?platform=sms&v=11.1.0-rest&type=incoming&apiKey=API_KEY'

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 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=sms&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.

The data to POST should pass the following data:

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

Sample cURL

curl -X POST -H "Content-Type: application/json"
     -d '{"text":"Hello, my human pet","userId":"+14155551234","platformJson":{"whateverJson":"any JSON specific to your platform can be stored here"}}'
     'https://tracker.dashbot.io/track?platform=sms&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.

Note
This is just an example — we accept all the fields listed at the top of the page.

Advanced Usage

SMS 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

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": "+14155551234",
  "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": "+14155551234",
  "platformJson": {
    "whateverJson": "any JSON specific to your platform can be stored here"
  },
  "intent": {
    "name": "WEATHER_QUERY",
    "inputs": [
      {
        "name": "city",
        "value": "San Francisco"
      }
    ]
  }
}

Post the complete message to Dashbot

https://tracker.dashbot.io/track?platform=sms&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":"+14155551234","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=sms&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": "+14155551234",
  "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": "+14155551234",
  "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=sms&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":"+14155551234","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=sms&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.

Tracking Events in a Conversation

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

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=sms&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=sms&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=sms&v=11.1.0-rest&type=event&apiKey=<strong>API_KEY_HERE</strong>

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=sms&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=sms&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=sms&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.

Post to the endpoint

https://tracker.dashbot.io/track?platform=sms&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=sms&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 Integration

Overview

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

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.

Creat a Webhook

Your webhook will recieve 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

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.

Edit this page on GitHub

SMS Documentation

SMS Documentation

SMS Integration with NPM

Create a bot API key

Install Dashbot via NPM

Include Dashbot

Whenever your bot sends, or receives data, log to Dashbot

Message Format

Log whenever your webhook is called

Whenever you send a message, log the response

Example

SMS Integration with REST API

Create a bot API key

Integrate the REST API

1. When bot posts to your webhook endpoint

The data to POST should pass the following data:

Sample cURL

2. When your bot sends a message

The data to POST should pass the following data:

Sample cURL

Advanced Usage

SMS Intent Tracking

Adding an Intent for an inbound message

Define Intent

Append the Intent JSON to the original message

Post the complete message to Dashbot

Sample cURL

Adding an Intent for an outbound message

Example: “The weather is 68 degrees and sunny.”

Define Intent

Append the Intent JSON to the original message

Post the complete message to Dashbot

Sample cURL

Tracking Events in a Conversation

Events

JSON Format

Tracking Custom Events

The data to POST should pass the following data:

Sample cURL

Tracking Revenue Events

The data to POST should pass the following data:

Sample cURL

Tracking Page Launch Events

The data to POST should pass the following data:

Sample cURL

Tracking Share Events

The data to POST should pass the following data:

Sample cURL

Live Person Takeover Integration

Overview

Bot Pause

Create a Pause Webhook

Example

Add the Webhook URL to your Account

Live Person Takeover

Creat a Webhook

Add the Webhook URL to your Account

Try it out

Webchat

Twitter

On this page