Dimension Labs API & Integrations

Tracking Intents and Events

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
    • confidence – float (optional) – the confidence value for your intent from 0.0 (completely uncertain) to 1.0 (completely certain)

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

Post the complete message to Dimension

https://tracker.dimensionlabs.io/track?platform=universal&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":"USERIDHERE123123","conversationId":"GROUPCHATID234","platformJson":{"whateverJson":"any JSON specific to your platform can be stored here"},"intent":{"name":"WEATHER_QUERY","inputs":[{"name":"city","value":"San Francisco"}]}}'
'https://tracker.dimensionlabs.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.

Adding an Intent for an outbound message

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

{
  "text": "The weather is 68 and sunny.",
  "userId": "USERIDHERE123123",
  "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": "USERIDHERE123123",
  "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 Dimension

https://tracker.dimensionlabs.io/track?platform=universal&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":"USERIDHERE123123","conversationId":"GROUPCHATID234","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.dimensionlabs.io/track?platform=universal&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.

Universal NotHandled Intent

It is very important to understand when a user says something to your bot that it does not understand.

By passing Dimension the NotHandled Intent, you can take advantage of the Not Handled report.

For incoming messages that your bot does not handle, set the intent name to “NotHandled” to take advantage of this special report.

Add the NotHandled Intent to the JSON

Prior to sending the message to Dimension, add an intent with the name NotHandled

const messageForDimension = {
  "text": "Hi, this is a confusing message for the bot.",
  "userId": "USERIDHERE123123"
}

Becomes:

const messageForDimension = {
  "text": "Hi, this is a confusing message for the bot.",
  "userId": "USERIDHERE123123",
  "intent": {
     "name": "NotHandled"
  }
}

Tracking 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
    • referralEvent

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.dimensionlabs.io/track?platform=universal&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.dimensionlabs.io/track?platform=universal&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.dimensionlabs.io/track?platform=generic&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.dimensionlabs.io/track?platform=generic&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.dimensionlabs.io/track?platform=generic&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.dimensionlabs.io/"
  }
}

Sample cURL

curl -X POST -H "Content-Type: application/json"
     -d '{"name":"Launched Detail Page","type":"pageLaunchEvent","userId":"967295313370594","extraInfo":{"url":"https://www.dimensionlabs.io/"}}'
     'https://tracker.dimensionlabs.io/track?platform=generic&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.dimensionlabs.io/track?platform=generic&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.dimensionlabs.io/track?platform=generic&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.