# Server-Sent Events Structure

Clients subscribe to the Server-Sent Events endpoint to receive server-side events.

These events encompass diverse message entries and provide supplementary information related to the conversation entry.

For a comprehensive understanding of the various supported message types and formats, please refer to the “Message Types & Format Types” section.

:::important
New event types can be introduced at any time as the Messaging API evolves. To ensure that your integration remains stable when new events are added, your implementation must ignore unrecognized event types, rather than throwing errors or failing.
:::

## CONVERSATION_CLIENT_ACTION

The CONVERSATION_CLIENT_ACTION event carries a client action entry for the conversation.

The `entryType` value for this event is `ClientAction`.

## CONVERSATION_CLIENT_MENU

The CONVERSATION_CLIENT_MENU event carries a client menu entry for the conversation.

The `entryType` value for this event is `ClientMenu`.

:::note
This event is deprecated. Don't build new integrations that depend on it.
:::

## CONVERSATION_CLOSE_CONVERSATION

The CONVERSATION_CLOSE_CONVERSATION event handles when the client receives an indicator or a confirmation that the conversation is closed.

This event only triggers when the end user closes the conversation, not when an agent ends a session. To handle when sessions end regardless of who initiated it, see the [CONVERSATION_SESSION_STATUS_CHANGED](#conversation_session_status_changed) event.

Add the following payload to the [Server-Sent Events](/docs/service/messaging-api/references/about/server-sent-events.md) endpoint.

```sfdocs-code {"lang":"json", "title": "Sample Payload" }
"{\"entryType\":\"CloseConversation\",\"id\":\"28abcd89-5b99-4162-966f-70fee8588b17\",\"conversationIdentifier\":\"9d1357a8-9a31-4ae2-a13b-6781a6b15045\"}",
```

## CONVERSATION_CONSULT_CONVERSATION_INFO

The CONVERSATION_CONSULT_CONVERSATION_INFO event provides consult-conversation information for multiparty conversations, such as when a rep consults another rep or a supervisor while continuing to handle the original conversation.

The `entryType` value for this event is `ConsultConversationInfo`.

:::note
This event applies to multiparty-conversation capabilities.
:::

## CONVERSATION_CONVERSATION_UPDATED

The CONVERSATION_CONVERSATION_UPDATED event notifies when conversation-level data changes. Currently, this event covers modality updates, such as when a conversation's channel or modality changes.

The `entryType` value for this event is `ConversationUpdated`.

## CONVERSATION_DELIVERY_ACKNOWLEDGEMENT

The CONVERSATION_DELIVERY_ACKNOWLEDGEMENT event handles when an end user receives an acknowledgment for their message when it is ‘Delivered’.

Add the following payload to the [Server-Sent Events](/docs/service/messaging-api/references/about/server-sent-events.md) endpoint.

```sfdocs-code {"lang":"json", "title": "Sample Payload" }
"{\"entryType\":\"DeliveryAcknowledgement\",\"id\":\"2f4548b2-42d7-4535-82dd-d2b0fb38ab95\",\"recipient\":{\"role\":\"Agent\",\"appType\":\"agent\",\"subject\":\"005SB000000AEkr\",\"clientIdentifier\":null},\"acknowledgedConversationEntryIdentifier\":\"7f7700aa-7ae4-4cf6-b23d-8f5ae11cbf72\",\"acknowledgementTimestamp\":1713391682342}",
```

## CONVERSATION_END_USER_CONSENT_UPDATED

The CONVERSATION_END_USER_CONSENT_UPDATED event notifies when an end user's consent status changes, such as when a user grants or revokes consent for data collection or communication.

The `entryType` value for this event is `EndUserConsentUpdated`.

## CONVERSATION_FILE_TRANSFER_CANCELLED

The CONVERSATION_FILE_TRANSFER_CANCELLED event handles when a file-upload request is cancelled or completed.

The `entryType` value for this event is `FileTransferCancelled`.

## CONVERSATION_FILE_TRANSFER_REQUEST

The CONVERSATION_FILE_TRANSFER_REQUEST event handles when an end user requests to upload a file. The event includes an upload JSON Web Token (JWT) and its expiration.

The `entryType` value for this event is `FileTransferRequest`.

## CONVERSATION_FLAG_LOWER

The CONVERSATION_FLAG_LOWER event handles when a previously raised flag on a conversation is lowered. See [CONVERSATION_FLAG_RAISE](#conversation_flag_raise) for details on raising a flag.

The `entryType` value for this event is `FlagLower`.

## CONVERSATION_FLAG_RAISE

The CONVERSATION_FLAG_RAISE event handles when a flag is raised on a conversation, such as to call attention to the conversation for review or escalation.

The `entryType` value for this event is `FlagRaise`.

## CONVERSATION_HOLD_TOGGLE

The CONVERSATION_HOLD_TOGGLE event handles when a conference call is placed on or removed from hold.

The `entryType` value for this event is `HoldToggle`.

:::note
This event applies to voice conference capabilities.
:::

## CONVERSATION_INTELLIGENCE_SIGNAL_VOICE_PILOT

The CONVERSATION_INTELLIGENCE_SIGNAL_VOICE_PILOT event carries a voice-pilot intelligence signal, such as a real-time insight generated during a voice conversation.

The `entryType` value for this event is `IntelligenceSignalVoicePilot`.

:::note
This event applies to voice capabilities.
:::

## CONVERSATION_MESSAGE

The CONVERSATION_MESSAGE event handles when a conversation message comes through the event source (SSE).

Add the following payload to the [Server-Sent Events](/docs/service/messaging-api/references/about/server-sent-events.md) endpoint.

```sfdocs-code {"lang":"json", "title": "Sample Payload" }
"{\"entryType\":\"Message\",\"id\":\"98ff46c3-358e-43e1-b70a-981d403374e9\",\"abstractMessage\":{\"messageType\":\"StaticContentMessage\",\"inReplyToMessageId\":null,\"id\":\"98ff46c3-358e-43e1-b70a-981d403374e9\",\"references\":[],\"staticContent\":{\"formatType\":\"Text\",\"text\":\"hi\"}},\"messageReason\":null}",
```

## CONVERSATION_MESSAGE_DELIVERY_FAILED

The CONVERSATION_MESSAGE_DELIVERY_FAILED event handles when a message can't be delivered.

The `entryType` value for this event is `MessageDeliveryFailed`.

## CONVERSATION_MESSAGE_UPDATED

The CONVERSATION_MESSAGE_UPDATED event handles when an existing message is updated after it's sent.

The `entryType` value for this event is `MessageUpdated`.

## CONVERSATION_MODALITY_CONNECTION

The CONVERSATION_MODALITY_CONNECTION event carries modality connection details, currently for voice conversations that use LiveKit.

The `entryType` value for this event is `ModalityConnection`.

:::note
This event applies to voice capabilities.
:::

## CONVERSATION_MUTE_TOGGLE

The CONVERSATION_MUTE_TOGGLE event handles when a conference participant is muted or unmuted.

The `entryType` value for this event is `MuteToggle`.

:::note
This event applies to voice conference capabilities.
:::

## CONVERSATION_NOTE

The CONVERSATION_NOTE event handles a private whisper-message entry, such as an internal note that's visible only to reps and not to the end user.

The `entryType` value for this event is `Note`.

## CONVERSATION_PARTICIPANT_CHANGED

The CONVERSATION_PARTICIPANT_CHANGED event handles when a new participant joins a conversation or an existing participant leaves. This event applies to a participant other than the end user using the Enhanced Chat client.

Add the following payload to the [Server-Sent Events](/docs/service/messaging-api/references/about/server-sent-events.md) endpoint.

```sfdocs-code {"lang":"json", "title": "Sample Payload" }
"{\"entryType\":\"ParticipantChanged\",\"id\":\"889fb316-6627-4158-9a91-4f641870899c\",\"entries\":[{\"operation\":\"add\",\"menuMetadata\":null,\"participant\":{\"role\":\"Agent\",\"appType\":\"agent\",\"subject\":\"005SB000000AEkr\",\"clientIdentifier\":\"\"},\"displayName\":\"Jessica T\"}]}",

"{\"entryType\":\"ParticipantChanged\",\"id\":\"ff2dcd62-d8b1-43b0-9165-f7b21d0f1bb4\",\"entries\":[{\"operation\":\"remove\",\"menuMetadata\":null,\"participant\":{\"role\":\"Agent\",\"appType\":\"agent\",\"subject\":\"005SG0000018413\",\"clientIdentifier\":\"\"},\"displayName\":\"Admin U\"}]}"
```

## CONVERSATION_PARTICIPANT_PRESENCE

The CONVERSATION_PARTICIPANT_PRESENCE event handles when a participant's state changes to `Present`, `Missing`, or `Gone`.

The `entryType` value for this event is `ParticipantPresence`.

## CONVERSATION_PARTICIPANTS_CONFERENCED

The CONVERSATION_PARTICIPANTS_CONFERENCED event handles when a multiparticipant conference is created.

The `entryType` value for this event is `ParticipantsConferenced`.

:::note
This event applies to voice conference capabilities.
:::

## CONVERSATION_PROGRESS_INDICATOR

The CONVERSATION_PROGRESS_INDICATOR event allows you to display a progress indicator when an AI agent is responding to a conversation. Progress indicators are useful to provide more information and context to users when an AI Agent is executing complex actions.

Add the following payload to the [Server-Sent Events](/docs/service/messaging-api/references/about/server-sent-events.md) endpoint.

```sfdocs-code {"lang":"json", "title": "Sample Payload" }
"{\"entryType\":\"ProgressIndicator\",\"id\":\"a7ba79d6-6ee5-402c-936c-d2716682c4ed\",\"progressIndicator\":{\"indicatorType\":\"ProgressUpdateIndicator\",\"progressMessage\":{\"formatType\":\"Text\",\"text\":\"Calling agent action: SvcCopilotTmpl__GetAllCasesForContact\"}}}",
```

## CONVERSATION_QUEUE_POSITION

The CONVERSATION_QUEUE_POSITION event handles when the queue position of a chat in the service queue is updated.

Add the following payload to the [Server-Sent Events](/docs/service/messaging-api/references/about/server-sent-events.md) endpoint.

```sfdocs-code {"lang":"json", "title": "Sample Payload" }
"{\"entryType\":\"QueuePosition\",\"pendingServiceRoutingId\":\"0JRSG0000039WoX\",\"workItemId\":\"0MwSG00000DQVQU\",\"position\":1}"
```

## CONVERSATION_READ_ACKNOWLEDGEMENT

The CONVERSATION_READ_ACKNOWLEDGEMENT event handles when an end user receives an acknowledgment for their message when it is ‘Read’.

Add the following payload to the [Server-Sent Events](/docs/service/messaging-api/references/about/server-sent-events.md) endpoint.

```sfdocs-code {"lang":"json", "title": "Sample Payload" }
"{\"entryType\":\"ReadAcknowledgement\",\"id\":\"52824f00-2365-4ab8-9e27-827d08d5b4d4\",\"recipient\":{\"role\":\"Agent\",\"appType\":\"agent\",\"subject\":\"005SB000000AEkr\",\"clientIdentifier\":null},\"acknowledgedConversationEntryIdentifier\":\"7f7700aa-7ae4-4cf6-b23d-8f5ae11cbf72\",\"acknowledgementTimestamp\":1713391759278}",
```

## CONVERSATION_RECOMMENDATIONS

The CONVERSATION_RECOMMENDATIONS event carries recommendations for the conversation.

The `entryType` value for this event is `Recommendations`.

## CONVERSATION_RECORDING_TOGGLE

The CONVERSATION_RECORDING_TOGGLE event handles when conference recording is paused or resumed.

The `entryType` value for this event is `RecordingToggle`.

:::note
This event applies to voice conference capabilities.
:::

## CONVERSATION_ROUTING_RESULT

The CONVERSATION_ROUTING_RESULT event handles routing to a rep or chatbot, such as when a conversation is initially created or when a conversation is transferred from a chatbot to a rep.

Add the following payload to the [Server-Sent Events](/docs/service/messaging-api/references/about/server-sent-events.md) endpoint.

```sfdocs-code {"lang":"json", "title": "Sample Payload" }
"{\"entryType\":\"RoutingResult\",\"id\":\"3dd5edf6-49f1-464b-8d59-f53d8ff18528\",\"recordId\":\"0MwSB000007tiXR\",\"errorMessages\":[],\"pendingServiceRoutingId\":\"0JRSB0000029uEk\",\"routingType\":\"Initial\",\"estimatedWaitTime\":{\"estimatedWaitTimeInSeconds\":-1,\"isEWTRequested\":true},\"failureReason\":\"\",\"failureType\":\"None\",\"routingConfigurationDetails\":{\"routingConfigurationType\":\"QueueRoutingType\",\"queueId\":\"00GSB0000002RNV\"}}",
```

## CONVERSATION_ROUTING_WORK_RESULT

The CONVERSATION_ROUTING_WORK_RESULT event handles the result of routing work, including assignment, acceptance, closure, transfer, and failure information.

The `entryType` value for this event is `RoutingWorkResult`.

## CONVERSATION_SESSION_CONTEXT

The CONVERSATION_SESSION_CONTEXT event handles a session context entry, which carries contextual information associated with a messaging session.

The `entryType` value for this event is `SessionContext`.

## CONVERSATION_SESSION_OWNER_CHANGED

The CONVERSATION_SESSION_OWNER_CHANGED event handles when the owner of a session changes.

The `entryType` value for this event is `SessionOwnerChanged`.

## CONVERSATION_SESSION_STATUS_CHANGED

The CONVERSATION_SESSION_STATUS_CHANGED event notifies when a messaging session's status changes. For example, this event is triggered when a messaging session status changes to `NEW`, `ACTIVE`, `INACTIVE`, or `ENDED`. This event allows you to track whether a session was created, accepted, or ended. This event is especially useful because the [CONVERSATION_CLOSE_CONVERSATION](#conversation_close_conversation) event only triggers when the end user closes the conversation, not when an agent ends a session. The session status change event fills that gap by letting you detect when sessions end regardless of who initiated it.

Add the following payload to the [Server-Sent Events](/docs/service/messaging-api/references/about/server-sent-events.md) endpoint.

```sfdocs-code {"lang":"json", "title": "Sample Payload" }
"{\"entryType\":\"SessionStatusChanged\",\"id\":\"fe7991bd-d863-4d8f-8ca9-ae52dd4b3d93\",\"conversationIdentifier\":\"f804aa54-e77e-4958-8840-79e0233ae4b0\",\"channelAddressIdentifier\":\"0aeba2ad-ff17-416f-8c70-7b0326220008\",\"sessionStatusPrev\":\"Waiting\",\"sessionEndedByRole\":null,\"sessionEndTime\":null,\"sessionStatus\":\"Active\",\"sessionStartTime\":1767740596000,\"sessionId\":\"0MwSB00000WMkZk\"}",
```

## CONVERSATION_STREAMING_TOKEN

The CONVERSATION_STREAMING_TOKEN event allows you to feed partial responses in real time as they become available, engaging users immediately and allowing them to consume content sooner.

Add the following payload to the [Server-Sent Events](/docs/service/messaging-api/references/about/server-sent-events.md) endpoint.

```sfdocs-code {"lang":"json", "title": "Sample Payload" }
"{\"entryType\":\"StreamingToken\",\"id\":\"5f1085c6-e933-49d3-bf87-f7d52fac149a\",\"streamingToken\":{\"tokenType\":\"MessageStreamingToken\",\"sequenceNumber\":1,\"timestamp\":1741299980669,\"targetMessageIdentifier\":\"1741299974320-REQ-1\",\"token\":{\"formatType\":\"Text\",\"text\":\"Agentforce is a powerful tool that helps companies build AI agents to drive customer\"}}}",
```

The token type `StreamingTokenValidation` notifies you when there's an issue like hallucination in the tokens streamed.

```sfdocs-code {"lang":"json", "title": "Sample Validation Payload" }
"{\"entryType\":\"StreamingToken\",\"id\":\"8b764460-fde7-4ad4-a9f9-b9ed85528542\",\"streamingToken\":{\"tokenType\":\"StreamingTokenValidation\",\"sequenceNumber\":1,\"timestamp\":1741302561902,\"result\":{\"valid\":false,\"reason\":\"UNGROUNDED\"},\"targetMessageIdentifier\":\"1741302557255-REQ-1\"}}",
```

## CONVERSATION_TRANSCRIPTS_HISTORY_IMPORTED

The CONVERSATION_TRANSCRIPTS_HISTORY_IMPORTED event handles when a conversation's transcript history is imported.

The `entryType` value for this event is `TranscriptsHistoryImported`.

## CONVERSATION_TRANSFER_PROGRESS

The CONVERSATION_TRANSFER_PROGRESS event handles when the status of a warm or cold transfer changes.

The `entryType` value for this event is `TransferProgress`.

## CONVERSATION_TYPING_INDICATOR

The CONVERSATION_TYPING_INDICATOR event handles the original typing indicator for a conversation.

The `entryType` value for this event is `TypingIndicator`.

:::note
This event is deprecated. Use [CONVERSATION_TYPING_STARTED_INDICATOR](#conversation_typing_started_indicator) and [CONVERSATION_TYPING_STOPPED_INDICATOR](#conversation_typing_stopped_indicator) instead.
:::

## CONVERSATION_TYPING_STARTED_INDICATOR

The CONVERSATION_TYPING_STARTED_INDICATOR event handles when the client receives a “typing started” indicator when the other participant, such as a rep or chatbot, starts typing a message.

Add the following payload to the [Server-Sent Events](/docs/service/messaging-api/references/about/server-sent-events.md) endpoint.

```sfdocs-code {"lang":"json", "title": "Sample Payload" }
"{\"entryType\":\"TypingStartedIndicator\",\"id\":\"0df87b90-d916-49a1-8739-fc59e6090668\",\"timestamp\":1713391872258}",
```

## CONVERSATION_TYPING_STOPPED_INDICATOR

The CONVERSATION_TYPING_STOPPED_INDICATOR event handles when the client receives a “typing stopped” indicator when the other participant, such as a rep or chatbot, stops typing a message.

Add the following payload to the [Server-Sent Events](/docs/service/messaging-api/references/about/server-sent-events.md) endpoint.

```sfdocs-code {"lang":"json", "title": "Sample Payload" }
"{\"entryType\":\"TypingStoppedIndicator\",\"id\":\"60582fd0-d697-43b4-9b39-e014d6d62760\",\"timestamp\":1713391878151}",
```

## Conversation Action Events Reference

The Conversation Action Framework (CAF) emits events when a participant performs an action on an existing conversation entry, such as reacting to a message or submitting feedback. These events arrive on the `conversationAction` key rather than `conversationEntry` — see [Server-Sent Events](/docs/service/messaging-api/references/about/server-sent-events.md) for the top-level envelope. Every conversation action event shares the same envelope fields, and the decoded `actionPayload` field varies by `actionType`.

### Envelope Field Reference

| Field                       | Type   | Description                                                                                              | Required |
| --------------------------- | ------ | -------------------------------------------------------------------------------------------------------- | -------- |
| conversationEntryIdentifier | string | The UUID of the conversation entry that this action applies to.                                          | Yes      |
| actionId                    | string | Unique identifier (UUID) for this action.                                                                | Yes      |
| actionType                  | string | The type of conversation action. See [Supported Action Types](#supported-action-types).                  | Yes      |
| actionInitiatedAt           | number | Unix epoch timestamp (in milliseconds, UTC) when the action was initiated.                               | Yes      |
| serverReceivedTimestamp     | number | Unix epoch timestamp (in milliseconds, UTC) when the Salesforce server received the action.              | Yes      |
| actionPayload               | string | A JSON-encoded string whose structure depends on `actionType`. See the sections below.                   | Yes      |
| performedBy                 | object | The participant who performed the action. Contains `role`, `appType`, `subject`, and `clientIdentifier`. | Yes      |

### Supported Action Types

| Action Type  | `actionType` Value | Status                |
| ------------ | ------------------ | --------------------- |
| Reaction     | `Reaction`         | Enabled               |
| Translation  | `Translation`      | Enabled               |
| Feedback     | `Feedback`         | Enabled               |
| Delivery ACK | `DeliveryAck`      | Not currently enabled |
| Read ACK     | `ReadAck`          | Not currently enabled |
| SDR          | `Sdr`              | Not currently enabled |

:::note
`DeliveryAck`, `ReadAck`, and `Sdr` are defined in the action type schema but aren't currently emitted on the SSE stream. Your unknown-`actionType` fallback handling covers them automatically if they start arriving before this reference is updated with their payload shapes.
:::

:::tip
**Handle unknown `actionType` values gracefully**, the same way you handle unknown `entryType` values — log them and continue processing rather than throwing an error. See the note above about ignoring unrecognized event types.
:::

## CONVERSATION_ACTION_REACTION

The CONVERSATION_ACTION_REACTION event is sent when a participant reacts to a conversation entry (for example, with an emoji).

The decoded `actionPayload` for this event contains the following fields, in addition to the [envelope fields](#envelope-field-reference).

### Field Reference

| Field       | Type   | Description                                                                           | Required |
| ----------- | ------ | ------------------------------------------------------------------------------------- | -------- |
| id          | string | Unique identifier (UUID) for this action payload. Matches `actionId` on the envelope. | Yes      |
| actionType  | string | Always `Reaction`.                                                                    | Yes      |
| uniCodeChar | string | The Unicode character of the reaction (for example, an emoji).                        | Yes      |

:::tip
**UI Handling**: Use `conversationEntryIdentifier` from the [envelope](#envelope-field-reference) to find the message this reaction applies to, then display `uniCodeChar` alongside it (for example, as a small badge under the message bubble).
:::

Add the following payload to the [Server-Sent Events](/docs/service/messaging-api/references/about/server-sent-events.md) endpoint.

```sfdocs-code {"lang":"json", "title": "Sample Payload" }
"{\"id\":\"f7904eb6-5352-4c5e-adf6-5f100572cf5d\",\"actionType\":\"Reaction\",\"uniCodeChar\":\"\\uD83D\\uDC4D\"}",
```

## CONVERSATION_ACTION_TRANSLATION

The CONVERSATION_ACTION_TRANSLATION event is sent when a conversation entry is translated, recording the source and target locales and the translated content.

The decoded `actionPayload` for this event contains the following fields, in addition to the [envelope fields](#envelope-field-reference).

### Field Reference

| Field                  | Type    | Description                                                                                                                                                                  | Required |
| ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| id                     | string  | Unique identifier (UUID) for this action payload. Matches `actionId` on the envelope.                                                                                        | Yes      |
| actionType             | string  | Always `Translation`.                                                                                                                                                        | Yes      |
| sourceLocale           | string  | Locale of the source text (BCP 47, for example `es` or `fr-CA`).                                                                                                             | Yes      |
| targetLocale           | string  | Locale the text was translated to.                                                                                                                                           | Yes      |
| translationDirection   | string  | Direction of translation relative to the conversation entry. Valid values are `OUTBOUND` and `INBOUND`.                                                                      | Yes      |
| provider               | string  | The translation engine used (for example, `AWS`).                                                                                                                            | Yes      |
| terminologyFileApplied | boolean | Whether a terminology file was configured at translation time.                                                                                                               | No       |
| terminologyFileName    | string  | The name of the terminology resource. Omitted when no terminology file was configured.                                                                                       | No       |
| content                | string  | The translated or original text being recorded. For `OUTBOUND` translations, this is the agent's original text. For `INBOUND` translations, this is the text the agent sees. | No       |
| structuredContent      | object  | Translated structured content. `null` for simple text.                                                                                                                       | No       |

:::tip
**Direction Matters**: Check `translationDirection` before deciding how to display `content` — for `OUTBOUND` translations the recorded text is the agent's original (pre-translation) message, while for `INBOUND` translations it's the translated text the agent saw.
:::

Add the following payload to the [Server-Sent Events](/docs/service/messaging-api/references/about/server-sent-events.md) endpoint.

```sfdocs-code {"lang":"json", "title": "Sample Payload" }
"{\"id\":\"f7904eb6-5352-4c5e-adf6-5f100572cf5d\",\"actionType\":\"Translation\",\"sourceLocale\":\"es\",\"targetLocale\":\"en-US\",\"translationDirection\":\"INBOUND\",\"provider\":\"AWS\",\"terminologyFileApplied\":false,\"content\":\"Hello, I need help with my order.\",\"structuredContent\":null}",
```

## CONVERSATION_ACTION_FEEDBACK

The CONVERSATION_ACTION_FEEDBACK event is sent when a participant submits feedback on a conversation entry, such as a thumbs-up or thumbs-down rating on an Agentforce response.

The decoded `actionPayload` for this event contains the following fields, in addition to the [envelope fields](#envelope-field-reference).

### Field Reference

| Field      | Type   | Description                                                                                                          | Required |
| ---------- | ------ | -------------------------------------------------------------------------------------------------------------------- | -------- |
| id         | string | Unique identifier (UUID) for this action payload. Matches `actionId` on the envelope.                                | Yes      |
| actionType | string | Always `Feedback`.                                                                                                   | Yes      |
| feedback   | string | The feedback rating. Valid values are `GOOD` and `BAD`.                                                              | Yes      |
| text       | string | Free-text feedback. Maximum length is 2000 characters.                                                               | No       |
| details    | object | Additional details as key-value pairs. Maximum of 25 properties. For example, `{"tags":["incorrect","incomplete"]}`. | No       |

:::tip
**UI Handling**: Use `feedback` to drive a thumbs-up/thumbs-down indicator on the conversation entry identified by `conversationEntryIdentifier`. If your UI collects follow-up detail (such as a reason for a `BAD` rating), surface `text` and `details` alongside the rating.
:::

Add the following payload to the [Server-Sent Events](/docs/service/messaging-api/references/about/server-sent-events.md) endpoint.

```sfdocs-code {"lang":"json", "title": "Sample Payload" }
"{\"id\":\"f7904eb6-5352-4c5e-adf6-5f100572cf5d\",\"actionType\":\"Feedback\",\"feedback\":\"BAD\",\"text\":\"The response didn't answer my question.\",\"details\":{\"tags\":[\"incorrect\",\"incomplete\"]}}",
```
