Open Messaging API: Quick Reply button payload structure for Data Action trace injection

NICE CXone API & Integrations
1

I’m trying to push structured messages via the Open Messaging API to inject trace IDs into the guest context. The goal is to capture the trace_id when the user clicks a Quick Reply button, which then triggers a Data Action to update our OTel spans.

The problem is the payload structure for the quick_reply action. The docs are vague on what gets passed back to the webhook when the user interacts. I’ve tried nesting the trace ID in the text field and also in a custom metadata object, but nothing seems to persist to the subsequent API call.

Here’s the JSON I’m sending to POST /api/v2/conversations/messaging/messages:

{
 "to": { "id": "guest-id-123" },
 "text": "Select an option",
 "actions": [
 {
 "type": "quick_reply",
 "text": "Support",
 "payload": {
 "trace_id": "otel-span-abc-123",
 "action": "route_to_support"
 }
 }
 ]
}

When the webhook fires, I only see text: "Support". The payload object is missing entirely. Am I supposed to use the text field as the only reliable carrier for this data? Or is there a specific field name in the actions array that Genesys Cloud expects for custom data?

I need the trace_id to survive the click event so I can correlate the web message with the backend Data Action execution.

2

The text field is strictly for display. You need to put the trace ID in the payload object. It flows straight into the webhook body under message.payload. Don’t nest it in text or it breaks parsing.

"quick_reply": {
 "text": "Track Order",
 "payload": { "trace_id": "xyz-123" }
}

Check your webhook logs for the actual JSON structure.