Create or update a message

Introduced 2.12

Use this API to create or update a message within a conversational memory for conversational search. A memory stores conversation history for the current conversation. A message represents one question/answer pair within a conversation.

Once a message is created, you’ll provide its message_id to other APIs.

The POST method creates a new message. The PUT method updates an existing message.

You can only update the additional_info field of a message.

When the Security plugin is enabled, all memories exist in a private security mode. Only the user who created a memory can interact with that memory and its messages.

Path and HTTP methods

  1. POST /_plugins/_ml/memory/<memory_id>/messages
  2. PUT /_plugins/_ml/memory/message/<message_id>

Path parameters

The following table lists the available path parameters.

ParameterData typeDescription
memory_idStringThe ID of the memory to which to add the message. Required for the POST method.
message_idStringThe ID of the message to be updated. Required for the PUT method.

Request body fields

The following table lists the available request fields.

FieldData typeRequired/OptionalUpdatableDescription 
 inputStringOptionalNoThe question (human input) in the message.
 prompt_templateStringOptionalNoThe prompt template that was used for the message. The template may contain instructions or examples that were sent to the large language model.
 responseStringOptionalNoThe answer (generative AI output) to the question.
 originStringOptionalNoThe name of the AI or other system that generated the response.
 additional_infoObjectOptionalYesAny other information that was sent to the origin.

Example request: Create a message

  1. POST /_plugins/_ml/memory/SXA2cY0BfUsSoeNTz-8m/messages
  2. {
  3.     "input": "How do I make an interaction?",
  4.     "prompt_template": "Hello OpenAI, can you answer this question?",
  5.     "response": "Hello, this is OpenAI. Here is the answer to your question.",
  6.     "origin": "MyFirstOpenAIWrapper",
  7.     "additional_info": {
  8.       "suggestion": "api.openai.com"
  9.     }
  10. }

copy

Example response

  1. {
  2.   "memory_id": "WnA3cY0BfUsSoeNTI-_J"
  3. }

Example request: Add a field to additional_info

  1. PUT /_plugins/_ml/memory/message/WnA3cY0BfUsSoeNTI-_J
  2. {
  3.   "additional_info": {
  4.     "feedback": "positive"
  5.   }
  6. }

copy

Example response

  1. {
  2.   "_index": ".plugins-ml-memory-message",
  3.   "_id": "WnA3cY0BfUsSoeNTI-_J",
  4.   "_version": 2,
  5.   "result": "updated",
  6.   "forced_refresh": true,
  7.   "_shards": {
  8.     "total": 1,
  9.     "successful": 1,
  10.     "failed": 0
  11.   },
  12.   "_seq_no": 45,
  13.   "_primary_term": 1
  14. }

The updated message contains an additional feedback field:

  1. {
  2.   "memory_id": "SXA2cY0BfUsSoeNTz-8m",
  3.   "message_id": "WnA3cY0BfUsSoeNTI-_J",
  4.   "create_time": "2024-02-03T23:04:15.554370024Z",
  5.   "input": "How do I make an interaction?",
  6.   "prompt_template": "Hello OpenAI, can you answer this question?",
  7.   "response": "Hello, this is OpenAI. Here is the answer to your question.",
  8.   "origin": "MyFirstOpenAIWrapper",
  9.   "additional_info": {
  10.     "feedback": "positive",
  11.     "suggestion": "api.openai.com"
  12.   }
  13. }

Example request: Change a field in additional_info

  1. PUT /_plugins/_ml/memory/message/WnA3cY0BfUsSoeNTI-_J
  2. {
  3.   "additional_info": {
  4.     "feedback": "negative"
  5.   }
  6. }

copy

Example response

  1. {
  2.   "_index": ".plugins-ml-memory-message",
  3.   "_id": "WnA3cY0BfUsSoeNTI-_J",
  4.   "_version": 3,
  5.   "result": "updated",
  6.   "forced_refresh": true,
  7.   "_shards": {
  8.     "total": 1,
  9.     "successful": 1,
  10.     "failed": 0
  11.   },
  12.   "_seq_no": 46,
  13.   "_primary_term": 1
  14. }

The updated message contains the updated feedback field:

  1. {
  2.   "memory_id": "SXA2cY0BfUsSoeNTz-8m",
  3.   "message_id": "WnA3cY0BfUsSoeNTI-_J",
  4.   "create_time": "2024-02-03T23:04:15.554370024Z",
  5.   "input": "How do I make an interaction?",
  6.   "prompt_template": "Hello OpenAI, can you answer this question?",
  7.   "response": "Hello, this is OpenAI. Here is the answer to your question.",
  8.   "origin": "MyFirstOpenAIWrapper",
  9.   "additional_info": {
  10.     "feedback": "negative",
  11.     "suggestion": "api.openai.com"
  12.   }
  13. }