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:
|
| 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.