Bot Integration

This feature is available only with paid Kochava accounts. Contact us to learn more.

Feature Summary: This document describes the process to integrate with the Kochava platform to track bot engagements including Facebook chatbots. Make sure you have created a unique app in the Kochava system, specific to the chatbot you want to track. This allows behavior segmentation to occur naturally, all while utilizing the Kochava IdentityLink to correlate user identities cross-app, if you choose.


Tracking Clicks & Impressions

To understand how users come to interact with, or allow a bot to start a conversation with them, you can ping Kochava upon initial bot communication. We classify this information as:

 

Impressions:

When you push a message to a bot to display an initial greeting to a user but they have not yet clicked, ping Kochava using an impression tracking URL. If you have in scope the fb_user_id at this point, you should send through with this ping. Message delivery info here: https://developers.facebook.com/docs/messenger-platform/webhook-reference#message_delivery

 

Clicks:

Once a user clicks through from the initial greeting into the bot experience, send Kochava a click-tracking notification. If you have in scope the fb_user_id at this point, you should send through with this ping. Tracking clicks into and within the bot experience utilize Kochava SmartLink. You can review message receive info here: https://developers.facebook.com/docs/messenger-platform/webhook-reference#received_message

Below is a sample of a message pushed to bot with PLACE_SMARTLINK_URL_HERE representing your click or impression tracking URLs. Click tracking, specifically, has the option to handle the entire redirect process from one bot interaction to the next, all configured within the Kochava UI. Utilizing SmartLink for bot interaction also allows you to handle different device models, versions, OSs, and other device attributes uniquely in both redirect location and landing experience.

Sample from (https://developers.facebook.com/docs/messenger-platform/send-api-reference)

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient":{
    "id":"USER_ID"
  },
  "message":{
    "attachment":{
      "type":"template",
      "payload":{
        "template_type":"button",
        "text":"What do you want to do next?",
        "buttons":[
          {
            "type":"web_url",
            "url":"PLACE_SMARTLINK_URL_HERE",
            "title":"Show Website"
          },
          {
            "type":"postback",
            "title":"Start Chatting",
            "payload":"USER_DEFINED_PAYLOAD"
          }
        ]
      }
    }
  }
}' "https://graph.facebook.com/v2.6/me/messages?access_token=<PAGE_ACCESS_TOKEN>”

Tracking Bot Engagements

All bot engagements should be sent to the Kochava using our engagement tracking endpoint. As there are not always advertising identifiers available during bot communication, we recommend utilizing the fb_user_id as the joining element between your bot interactions, as well as utilizing Kochava IdentityLink to link your users cross-app.

To send usage events from your bot, call the following endpoint with a POST payload containing the desired JSON elements. You can either send bot interactions directly via the Messenger web hooks, messenger native, or via a server-to-server feed when your server detects user interaction.

You can review the Facebook documentation on postbacks out of Messenger here:
https://developers.facebook.com/docs/messenger-platform/webhook-reference#postback
http://control.kochava.com/track/json

 

JSON Property Example Value Description Required?
kochava_app_id kogamerdna114e9bb3481258 This is the unique application ID used to represent the App. Yes
device_ids  123456789 This is a unique identifier for the user, like fb_user_id Yes
action “event” Action associated to the API event. Yes
data event_name: event string
event_data: value string
Each event is a JSON object – see examples.

event_name -> A string representation of an event that has happened.

event_data -> A corresponding value associated to the event_name. event_data is not required, but useful for monetary tracking for correlated events (i.e. event_name -> “DLC Purchased” and event_value -> “20”.

Yes

 

Sample Event Call:

{
    "data": {
        "device_ids": {
            "fb_user_id": "123456789"
        },
        "event_name": "Purchase",
        "event_data": {
            "id": "123",
            "name": "Shoes",
            "currency": "USD",
            "sum": 100
        }
    },
    "action": "event",
    "kochava_app_id": "koconversionsdemo174ea19bc63928c"
}

 

If you have the capability to collect fb_user_id within your mobile app, you can use IdentityLink to correlate this value with a device identifier. Using Identitylink allows you to understand bot interaction both separate (within each Kochava app), or together by correlating users across apps. If you include an identifier, such as a fb_user_id, with all bot and native app interactions, Kochava will persist this identifier as a first class property of the user/device model.

 
 

Last Modified: Oct 18, 2023 at 8:58 am