Open Messaging API returning 400 for quick reply cards

Getting a 400 Bad Request when trying to send a structured message via the Open Messaging API. The payload looks right based on the docs but the response body just says “Invalid message structure”.

Here is the JSON I’m sending to /api/v2/conversations/messages:

{
“toId”: “some-guest-id”,
“type”: “guest”,
“media”: {
“contentType”: “application/vnd.genesys.message.card+json”,
“content”: {
“type”: “card”,
“title”: “Support Options”,
“actions”: [
{
“type”: “quickReply”,
“label”: “Chat with agent”,
“value”: “chat_request”
}
]
}
}
}

The conversation is active and I can send plain text messages fine. The issue seems to be with the card structure. I’ve tried changing the action type to button but that fails too. The docs mention contentType needs to be exact. Is there a specific format for the quickReply value field that I’m missing? Or maybe the actions array needs a different wrapper? The error doesn’t give much detail so it’s hard to tell what’s wrong.

The issue is almost certainly in how you’re structuring the actions array inside the card. The Open Messaging API is pretty strict about the type field for actions. You can’t just throw a generic object in there. It needs to be explicitly postBack or webUrl.

If you’re trying to trigger a flow or update an attribute, use postBack. If you’re just linking out, use webUrl. I’ve seen the 400 error pop up when the label is missing or when the payload for a postBack is empty.

Here is a working example of a quick reply card that actually goes through. Note the postBack type and the specific payload structure:

{
 "toId": "some-guest-id",
 "type": "guest",
 "media": {
 "contentType": "application/vnd.genesys.message.card+json",
 "content": {
 "type": "card",
 "title": "Support Options",
 "actions": [
 {
 "type": "postBack",
 "label": "Talk to Agent",
 "payload": "talk_to_agent"
 },
 {
 "type": "postBack",
 "label": "FAQ",
 "payload": "view_faq"
 }
 ]
 }
 }
}

Make sure your Architect flow is listening for those specific payloads. If you send a webUrl action, the guest gets redirected immediately and no message payload hits your flow unless you’ve set up a specific webhook callback, which is rare for standard quick replies.

Also, double-check that the guest’s channel supports rich media. If they’re on a plain SMS channel, this will fail or get stripped down to plain text depending on your routing configuration. Don’t assume all messaging channels support cards equally. WhatsApp handles them differently than Web Chat.

You’ll also want to ensure the toId is actually an active guest ID and not a user ID or something else. The API throws a 400 for that too, though usually with a different error message.

Check the payload string. It has to match exactly what you’re looking for in the Data Action or Trigger. Case sensitive. If you send “Talk_to_Agent” and look for “talk_to_agent”, it won’t match, and you might think the message failed when it actually just wasn’t handled.

Let me know if switching to postBack fixes the 400.