Dashbot
SMS Documentation
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.
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).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
- input – object
- images – array – (optional)
- image – object
- url – string
- image – object
- buttons – array – (optional)
- button – object
- id – string
- label – string
- value – string
- button – object
- postback – object (optional)
- buttonClick – object
- buttonId – string
- buttonClick – object
- 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
- input – object
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.
Tracking Share 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": "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