Skip to main content

Create a new Message for a Conversation

POST 
/v1/conversations/:conversationId/messages

A Message is typically a piece of plain text contributed to the conversation by the user or the agent. However, it can also be a control message that changes the state of the conversation. (See below.)

You will often use that endpoint to post a user message and ask for a reponse by the agent. You do this by passing some content and specifying the role: 'user' with and action: 'generate-reply'.

If you want to force a response by the agent, for example at the beginning of a conversation, you can use role: 'control' and action: 'generate-reply'. You can also use role:control to hidden messages in the conversation that will only be visible to the agent, or to change the state of the conversation.

Use stateAfter to change the state of the conversation. You can use it to set the playbook, phase, systemMessage, or context. Any field you do not specify will be left unchanged. For more details on these concepts, see the Create a Conversation endpoint.

Finally, you can use role: 'agent' to artificially add a message from the agent into the conversation. This can be useful to add a message that was generated outside of the API.

When you specify action: 'generate-reply' the agent will start processing the current conversation. The agent's reply will be provided in the response to your API call, so your call may block for a while as the response is being generated.

If a response is currently being generated in this Conversation, any call to this endpoint will return a 409 error.

Note that Messages can not be modified or deleted once they have been created. If you want to remove them you must delete the entire Conversation.

Request​

Responses​

Message created successfully