--- updatedAt: 2026-05-13T09:04:12.000Z --- # 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](https://developer.khoros.com/khoroscaredevdocs/reference/registration-payload) defined during [bot registration](https://developer.khoros.com/khoroscaredevdocs/docs/bot-registration-1). The incoming message includes a JSON payload that looks like this: ```json Incoming message payload format { "coordinate":, "text":"", "type":"message", "author":{ "id":"", "fullName":"" }, "owner":{ "type":"", "appId":"" }, "publishedTS":, "receivedTS":, "properties":{ "customField":"customerSupplied1", "messageSpecificValues":"customValue" } } ``` ```text ``` # 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](https://developer.khoros.com/khoroscaredevdocs/reference/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](https://developer.khoros.com/khoroscaredevdocs/reference/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](https://developer.khoros.com/khoroscaredevdocs/reference/media-object) for details. | | author | The [Author object](https://developer.khoros.com/khoroscaredevdocs/reference/author-object) representing the message author on the source network channel. | | location | The [Location object](https://developer.khoros.com/khoroscaredevdocs/reference/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](https://developer.khoros.com/khoroscaredevdocs/reference/registration-payload). | | 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](https://github.com/smooch/smooch-web#setdelegatedelegate) 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](https://developer.khoros.com/khoroscaredevdocs/reference/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 ```json { "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 ```json { "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 ```json { "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 ```json { "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: ```json { "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](https://community.khoros.com/t5/Tagging-and-routing-in-Response/Using-Metadata-Tag-Rules/ta-p/556700).