Trying to send structured messages via POST /api/v2/conversations/messaging/externalcontacts/{id}/messages from our Kotlin backend. The JSON payload includes a quickReply action type, but the API returns 400 Bad Request with error code invalid_payload. I’ve checked the Open Messaging spec and the syntax looks valid. Here’s the snippet:
"content": { "type": "text", "text": "Pick an option", "actions": [{ "type": "quickReply", "value": "opt1" }] }
Any idea what’s missing?
The 400 error usually isn’t the quickReply type itself. It’s the payload structure inside the action. Genesys Cloud expects a specific schema for the quickReply action, and if the actions array is malformed or missing required fields, the API rejects the whole message.
Check your JSON structure carefully. The content object needs to wrap the quickReply action correctly. Here is the exact format that works in our Kotlin backend using the Genesys Cloud SDK:
{
"content": {
"type": "quickReply",
"text": "Pick an option",
"quickReply": {
"title": "Select Option",
"actions": [
{
"type": "postBack",
"text": "Option 1",
"payload": "OPT_1"
},
{
"type": "postBack",
"text": "Option 2",
"payload": "OPT_2"
}
]
}
},
"to": {
"id": "external_contact_id",
"type": "external_contact"
}
}
Notice the quickReply object sits inside the content block, not as a sibling to type. Also, ensure the actions array contains objects with type, text, and payload. If you omit payload or use a different action type like call without proper formatting, it fails.
We hit this same issue last month. The docs are slightly vague on the nesting level. The type field at the root of content must be quickReply, and the actual data goes into the quickReply property. Double-check your Kotlin data class annotations. If you’re using Jackson or Gson, make sure the field names match exactly. Case sensitivity matters.
Also, verify the external contact ID is valid and the channel supports quick replies. SMS channels often drop structured data. We use WhatsApp and Facebook Messenger for this. If you’re testing on a plain SMS endpoint, it might reject the payload silently or with a generic 400.
Try sending a plain text message first to confirm the endpoint is reachable. Then add the quick reply structure. Step by step. It’s easier to debug.