Dashbot

Slack Documentation

Slack Documentation

Welcome to the Slack documentation for Dashbot! Integrating Dashbot into your Slack bot is quick and easy.

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

Slack 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).slack;

When you first connect, tell dashbot and save the bot and team locally

request('https://slack.com/api/rtm.start?token=' + process.env.SLACK_BOT_TOKEN, (error, response) => {
const parsedData = JSON.parse(response.body);
// Tell Dashbot when you connect.
dashbot.logConnect(parsedData);
const bot = parsedData.self;
const team = parsedData.team;
...
})

When you receive a message on the websocket, tell Dashbot — passing bot, team, and message

connection.on('message', (message) => {
const parsedMessage = JSON.parse(message.utf8Data);
// Tell Dashbot when a message arrives
dashbot.logIncoming(bot, team, parsedMessage);
})

When you send a reply on the websocket, tell Dashbot — passing bot, team, and reply

const reply = {
type: 'message',
text: 'You are right when you say: ' + parsedMessage.text,
channel: parsedMessage.channel
};
// Tell Dashbot about your response
dashbot.logOutgoing(bot, team, reply);
connection.sendUTF(JSON.stringify(reply));

Example

See a complete example.



Slack Integration with Botkit and 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).slack;

After you create your Botkit controller, simply add send and receive middleware

const controller = Botkit.slackbot();
controller.configureSlackApp(...);
// Add the dashbot middleware
controller.middleware.receive.use(dashbot.receive);
controller.middleware.send.use(dashbot.send);

Slack Buttons

Starting with this slack button example, here is how you add Slack Button reporting to your bot.

Since Botkit does not send button interactions through its middleware, we need to log the button presses and interactive replies when they are made.

When you receive and send an interactive message, log it (you also must set the channel on the reply):

controller.on('interactive_message_callback', (bot, message) => {
dashbot.logIncoming(bot.identity, bot.team_info, message);
...
replyMessage.channel = message.channel;
dashbot.logOutgoing(bot.identity, bot.team_info, replyMessage);
bot.replyInteractive(message, replyMessage)

If you set the interactive_replies: true option in botkit, the incoming message is received by the middleware, but you still must send dashbot the outgoing message with the channel set:

controller.on('direct_message', (bot, message) => {
...
replyMessage.channel = message.channel;
dashbot.logOutgoing(bot.identity, bot.team_info, replyMessage);
bot.replyInteractive(message, replyMessage)

Example

View sample code for a complete Slack bot example.



Slack 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 three integration points as outlined below.

1. When you first connect Slack via rtm.start

When you first connect Slack via rtm.start, POST the data that Slack returns to the following endpoint.

https://tracker.dashbot.io/track?platform=slack&v=11.1.0-rest&type=connect&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:

{
"self": {
"...": "..."
},
"team": {
"...": "..."
},
"channels": {
"...": "..."
},
"users": {
"...": "..."
}
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
-d '{"self":{"...":"..."},"team":{"...":"..."},"channels":{"...":"..."},"users":{"...":"..."}}'
'https://tracker.dashbot.io/track?platform=slack&v=11.1.0-rest&type=connect&apiKey=API_KEY_HERE'

Notice, you must replace the placeholder API_KEY_HERE above with your api key.

2. When you receive a message on the Slack websocket

When you receive a message on the Slack websocket, POST to Dashbot passing token, botId, teamId, teamName, and message.

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

{
"token": "...",
"team": {
"id": "T0RKXFPTP",
"name": "jessetest"
},
"bot": {
"id": "U16R8L1JA"
},
"message": {
"type": "message",
"channel": "D16RSST6W",
"user": "U0RKX8RDM",
"text": "hi, bot",
"ts": "1483257600.000000",
"team": "T0RKXFPTP"
}
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
-d '{"token":"...","team":{"id":"T0RKXFPTP","name":"jessetest"},"bot":{"id":"U16R8L1JA"},"message":{"type":"message","channel":"D16RSST6W","user":"U0RKX8RDM","text":"hi, bot","ts":"1483257600.000000","team":"T0RKXFPTP"}}'
'https://tracker.dashbot.io/track?platform=slack&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 any rich media that Slack accepts.

3. When you send a message to Slack via the websocket or the chat.postMessage endpoint

When you send a message to Slack via the websocket or the chat.postMessage endpoint POST it to Dashbot passing token, botId, teamId, teamName, and message.

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

{
"token": "...",
"team": {
"id": "T0RKXFPTP",
"name": "jessetest"
},
"bot": {
"id": "U16R8L1JA"
},
"message": {
"type": "message",
"text": "Hello, my human pet",
"channel": "D16RSST6W"
}
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
-d '{"token":"...","team":{"id":"T0RKXFPTP","name":"jessetest"},"bot":{"id":"U16R8L1JA"},"message":{"type":"message","text":"Hello, my human pet","channel":"D16RSST6W"}}'
'https://tracker.dashbot.io/track?platform=slack&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 any rich media that Slack accepts.

Example

View a complete example.

Extra integrations when using Slack buttons

When you receive a button click message on Slack webhook

When you receive a message on Slack webhook, send the payload to Dashbot. Make sure to parse the payload as JSON and do not send a raw string.

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

{
"token": "...",
"team": {
"id": "T0RKXFPTP",
"name": "jessetest"
},
"bot": {
"id": "U16R8L1JA"
},
"message": {
"actions": [
{
"name": "name",
"value": "value"
}
],
"callback_id": "foo_1474051104627",
"team": {
"id": "T0RKXFPTP",
"domain": "jessetestteam"
},
"channel": {
"id": "D0S2AS2F4",
"name": "directmessage"
},
"user": {
"id": "U0RKX8RDM",
"name": "jhull"
},
"action_ts": "1483344000000.000000",
"message_ts": "1483344000000.000000",
"attachment_id": "1",
"token": "...",
"original_message": {
"...": "..."
}
},
"response_url": "..."
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
-d '{"token":"...","team":{"id":"T0RKXFPTP","name":"jessetest"},"bot":{"id":"U16R8L1JA"},"message":{"actions":[{"name":"name","value":"value"}],"callback_id":"foo_1474051104627","team":{"id":"T0RKXFPTP","domain":"jessetestteam"},"channel":{"id":"D0S2AS2F4","name":"directmessage"},"user":{"id":"U0RKX8RDM","name":"jhull"},"action_ts":"1483344000000.000000","message_ts":"1483344000000.000000","attachment_id":"1","token":"...","original_message":{"...":"..."}},"response_url":"..."}'
'https://tracker.dashbot.io/track?platform=slack&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 any rich media that Slack accepts.

When you send a message in response to a button click

When you send a message in response to a button click, send the message to Dashbot. Be sure to set the channel.

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

{
"token": "...",
"team": {
"id": "T0RKXFPTP",
"name": "jessetest"
},
"bot": {
"id": "U16R8L1JA"
},
"message": {
"text": "replace button with this",
"channel": "D0S2AS2F4"
}
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
-d '{"token":"...","team":{"id":"T0RKXFPTP","name":"jessetest"},"bot":{"id":"U16R8L1JA"},"message":{"text":"replace button with this","channel":"D0S2AS2F4"}}'
'https://tracker.dashbot.io/track?platform=slack&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.

Example

View a complete example.



Advanced Usage

Slack 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?”

{
"token": "...",
"team": {
"id": "T0RKXFPTP",
"name": "jessetest"
},
"bot": {
"id": "U16R8L1JA"
},
"message": {
"type": "message",
"channel": "D16RSST6W",
"user": "U0RKX8RDM",
"text": "What is the weather in San Francisco?",
"ts": "1517990867.000000",
"team": "T0RKXFPTP"
}
}

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

{
"token": "...",
"team": {
"id": "T0RKXFPTP",
"name": "jessetest"
},
"bot": {
"id": "U16R8L1JA"
},
"message": {
"type": "message",
"channel": "D16RSST6W",
"user": "U0RKX8RDM",
"text": "What is the weather in San Francisco?",
"ts": "1517990867.000000",
"team": "T0RKXFPTP"
},
"intent": {
"name": "WEATHER_QUERY",
"inputs": [
{
"name": "city",
"value": "San Francisco"
}
]
}
}

Post the complete message to Dashbot

https://tracker.dashbot.io/track?platform=slack&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 '{"token":"...","team":{"id":"T0RKXFPTP","name":"jessetest"},"bot":{"id":"U16R8L1JA"},"message":{"type":"message","channel":"D16RSST6W","user":"U0RKX8RDM","text":"What is the weather in San Francisco?","ts":"1517990867.000000","team":"T0RKXFPTP"},"intent":{"name":"WEATHER_QUERY","inputs":[{"name":"city","value":"San Francisco"}]}}'
'https://tracker.dashbot.io/track?platform=slack&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
Notice that the Intent object is for each message in the array of messages (which is inside the entries array).

Adding an Intent for an outbound message

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

{
"token": "...",
"team": {
"id": "T0RKXFPTP",
"name": "jessetest"
},
"bot": {
"id": "U16R8L1JA"
},
"message": {
"type": "message",
"text": "The weather is 68 and sunny.",
"channel": "D16RSST6W"
}
}

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

{
"token": "...",
"team": {
"id": "T0RKXFPTP",
"name": "jessetest"
},
"bot": {
"id": "U16R8L1JA"
},
"message": {
"type": "message",
"text": "The weather is 68 and sunny.",
"channel": "D16RSST6W"
},
"intent": {
"name": "WEATHER_RESPONSE",
"inputs": [
{
"name": "forecast",
"value": "68 and sunny"
}
]
}
}

Post the complete message to Dashbot

https://tracker.dashbot.io/track?platform=slack&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 '{"token":"...","team":{"id":"T0RKXFPTP","name":"jessetest"},"bot":{"id":"U16R8L1JA"},"message":{"type":"message","text":"The weather is 68 and sunny.","channel":"D16RSST6W"},"intent":{"name":"WEATHER_RESPONSE","inputs":[{"name":"forecast","value":"68 and sunny"}]}}'
'https://tracker.dashbot.io/track?platform=slack&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
Notice that the Intent object is for each message in the array of messages (which is inside the entries array).



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

Create a Webhook

The first step is to create a webhook for your bot that handles pausing the bot.

Slack Pause Webhook

Your webhook will receive three fields in the body:

  • channelId
    • the Slack channel id to pause
  • teamId
    • the Slack team id of the session to pause
  • 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 channel and team sessions are paused. Whenever a new message is received, check if the session is paused for that channel and team, and if so, stop the bot from responding.

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

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