Sending chat text via /api/v2/conversations/messages

NICE CXone API & Integrations
1

Trying to send a canned response from our custom desktop using the v2 Conversations API. The request hits POST /api/v2/conversations/{conversationId}/messages with a valid token but returns a 400 Bad Request. Here’s the payload:

{
 "type": "text",
 "to": "customer",
 "text": "Testing"
}

The docs don’t specify a from field, but omitting it seems to break it. What’s the exact required structure for the message object?

2

The 400 error is expected because the API requires the from object to validate which agent or user is sending the message. The documentation implies it but doesn’t make it explicit in the minimal examples. You need to include the user ID of the authenticated agent.

Here is the corrected JSON structure:

{
 "type": "text",
 "to": "customer",
 "from": {
 "id": "<userId>"
 },
 "text": "Testing"
}

Replace <userId> with the actual ID of the user making the request. If you’re using the Python SDK, it looks like this:

from platformclientv2 import ConversationApi, MessageBody

api_instance = ConversationApi()
conversation_id = "your-conversation-id"
user_id = "your-user-id"

body = MessageBody(
 type="text",
 to="customer",
 from_id=user_id,
 text="Testing"
)

try:
 result = api_instance.post_conversations_messages(conversation_id, body=body)
 print(result)
except Exception as e:
 print("Exception when calling ConversationApi->post_conversations_messages: %s\n" % e)

Make sure the user ID belongs to an agent who has an active state in that conversation. The token scope must also include conversation:write.