Dimension Labs API & Integrations

SMS 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)
  • adid – _string an ID to identify the ad (optional)
  • refereruri – _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.

https://youtu.be/9WUcY78AqrU

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