Incoming Message Payloads

Learn about message payloads received by the bot

Messages from an author to a source channel are intercepted by Khoros Care and echoed to your brand's bot via the callback URL defined during bot registration. The incoming message includes a JSON payload that looks like this:

{  
  "coordinate":<coordinate-object>,
  "text":"<message-body-text>",
  "type":"message",
  "author":{  
    "id":"<network-author-id>",
    "fullName":"<author-name>"
  },
  "owner":{  
    "type":"<AGENT | BOT>",
    "appId":"<current-owner-app-id>"
  },
  "publishedTS":<message-published-timestamp>,
  "receivedTS":<message-received-by-bot-framework>,
  "properties":{  
    "customField":"customerSupplied1",
    "messageSpecificValues":"customValue"
  }
}

Incoming Message Payload Fields


coordinate	A Coordinate object. This is object contains details about the bot and the message in context. It is used by Khoros Care.
text	The text of the message
type	An incoming payload will have one of the following types: `message`: standard message to or from the author on the source network `update`: describing updates about conversations
actions	The Actions object represents structured actions that the user can take. This object is used with postbacks and replies.
form	The form response submitted by the user. Only supported for Khoros messaging. See Form Response object for details.
list	The list picker response submitted by the user. Only supported for Apple business chat.
media	A list of media objects sent by the user. See Media object for details.
author	The Author object representing the message author on the source network channel.
location	The Location object enables the designation of a specific location by its country code and/or exact coordinates.
owner	The owner of the message: AGENT or BOT. If the owner is BOT, the `owner` object also includes the bot's `appId` from the bot registration.
publishedTS	The publish timestamp in epoch milliseconds for the date/time the author published the message.
receivedTS	The received timestamp in epoch milliseconds for the date/time that Care received the message.
properties	An object consisting of key-values provided by the `beforeSend` hook inside the Khoros Messaging setDelegate API. Note that the fields are provided as a metadata field on the Messaging message; however, the fields come out of the Bot Service in the properties on the Message payload.
referral	The Referral object consists of information related to the source of the referral to the conversation. For example, a QR code containing a link to that opens a conversation.

Event Examples

Here's a quick breakdown of each of the incoming payloads for reference:

Message Event

{
    "coordinate":{
        "companyKey":"...",
        "networkKey":"whatsapp",
        "externalId":"5de...",
        "messageId":"5e2...",
        "botId":"bot-id",
        "scope":"PRIVATE",
        "normalizedAuthorId":"3a4..."
    },
    "text":"hello",
    "author":{
        "id":"3a4...",
        "fullName":"Jo",
        "properties":{
        }
    },
    "owner":{
        "type":"AGENT"
    },
    "publishedTS":1579793945986,
    "receivedTS":1579793946280,
    "properties":{
    },
    "type":"message"
}

Closed Conversation Event

{
    "coordinate":{
        "companyKey":"...",
        "networkKey":"apple",
        "externalId":"5bb...",
        "botId":"ABCBot",
        "scope":"PRIVATE",
        "normalizedAuthorId":"urn:mbid:AQ..."
    },
    "author":{
        "id":"urn:mbid:AQ...",
        "fullName":"Anonymous Stork 1afc-9b12"
    },
    "operation":"CLOSED",
    "conversation":{
        "displayId":5178076,
        "dispositionId":19,
        "encodedDispositionId": 320,
        "conversationUuid": "3de...."
    },
    "type":"update"
}

Created Conversation Event

{
    "coordinate":{
        "companyKey":"...",
        "networkKey":"whatsapp",
        "externalId":"5de...",
        "messageId":"5e2...",
        "botId":"5a3...",
        "scope":"PRIVATE",
        "normalizedAuthorId":"05..."
    },
    "author":{
        "id":"05...",
        "fullName":"name"
    },
    "operation":"CREATED",
    "conversation":{
        "displayId":123,
        "dispositionId":0,
        "encodedDispositionId": 0,
        "conversationUuid": "3de...."
    },
    "type":"update"
}

Agent Response Event

{
    "coordinate":{
        "companyKey":"...",
        "networkKey":"apple",
        "externalId":"5b...",
        "messageId":"15...",
        "botId":"ABCBot",
        "scope":"PRIVATE",
        "normalizedAuthorId":"urn:mbid:AQ..."
    },
    "author":{
        "id":"urn:mbid:AQ...",
        "fullName":"Anonymous Jackal 2860-5e3a"
    },
    "operation":"AGENT_RESPONSE",
    "conversation":{
        "displayId":123,
        "dispositionId":2,
        "encodedDispositionId": 0,
        "conversationUuid": "3de...."
    },
    "agentResponse":{
        "publishDate":1579793946000,
        "text":"test"
    },
    "type":"update"
}

Metadata

Each network sends its own unique metadata with each message. This metadata is contained within the properties object, and its fields are defined by the network from which the message originates.

Here is an example message payload from BrandMessenger:

{
   "coordinate":{
      "companyKey":"exampleinc",
      "networkKey":"smooch",
      "externalId":"5e59488cf3226500example",
      "messageId":"60e5fbb3a18ae800dexample",
      "botId":"examplebot",
      "scope":"PRIVATE",
      "normalizedAuthorId":"example-beb7-47f1-8fe9-192035664234"
   },
   "text":"batman",
   "author":{
      "id":"example-beb7-47f1-8fe9-192035664234",
      "fullName":"Anonymous Example 5f11-c602",
      "properties":{
      }
   },
   "owner":{
      "type":"BOT",
      "appId":"example123"
   },
   "publishedTS":1625684915486,
   "receivedTS":1625684916142,
   "properties":{
      "clients[0].title":"Khoros - Calendar - Wednesday, July 7, 2021, today",
      "clients[0].platform":"WEB",
      "widgetId":"8ed2dfb6-1f74-4dda-be26-004892b30d14",
      "clients[0].userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.114 Safari/537.36",
      "siteReferrer":"https://ogs.google.com/",
      "ruleId":"example-381c-47c4-9462-82af5315630d",
      "clients[0].url":"https://calendar.google.com/calendar/u/0/r"
   },
   "type":"message"
}

Additional information about the interaction is supplied through the metadata contained in the properties area of the payload. This information may be used to better customize your customer experience as they interact with the bot.

For example, the bot may respond with different directions for a customer interacting with it through one browser or platform over another. You can find more information about the types of metadata passed from each platform in our guide.