Link Search Menu Expand Document Documentation Menu
Documentation

Create Or Update Message API

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.

Endpoints

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

Path parameters

The following table lists the available path parameters.

Parameter Data type Description
memory_id String The ID of the memory to which to add the message. Required for the POST method.
message_id String The ID of the message to be updated. Required for the PUT method.

Request body fields

The following table lists the available request fields.

Field Data type Required/Optional Updatable Description
input String Optional No The question (human input) in the message.
prompt_template String Optional No The prompt template that was used for the message. The template may contain instructions or examples that were sent to the large language model.
response String Optional No The answer (generative AI output) to the question.
origin String Optional No The name of the AI or other system that generated the response.
additional_info Object Optional Yes Any other information that was sent to the origin.

To create or update a message successfully, you must provide at least one of the preceding fields. The provided field(s) cannot be null or empty.

Response body fields

The following table lists the available response fields.

Field Data type Description
memory_id String The memory ID.
message_id String The message ID.
create_time String The time at which the message was created.
updated_time String The time at which the message was last updated.
input String The question in the message (human input).
prompt_template String The prompt template that was used for the message.
response String The answer to the question (generative AI output).
origin String The name of the AI or other system that generated the response.
additional_info Object Any other information that was sent to the origin.
parent_message_id String The ID of the parent message (for trace messages).
trace_number Integer The trace number (for trace messages).

Example request: Create a message

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

Example response

{
  "message_id": "WnA3cY0BfUsSoeNTI-_J"
}

Example request: Add a field to additional_info

PUT /_plugins/_ml/memory/message/WnA3cY0BfUsSoeNTI-_J
{
  "additional_info": {
    "feedback": "positive"
  }
}

Example response

{
  "_index": ".plugins-ml-memory-message",
  "_id": "WnA3cY0BfUsSoeNTI-_J",
  "_version": 2,
  "result": "updated",
  "forced_refresh": true,
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 45,
  "_primary_term": 1
}

The updated message contains an additional feedback field:

{
  "memory_id": "SXA2cY0BfUsSoeNTz-8m",
  "message_id": "WnA3cY0BfUsSoeNTI-_J",
  "create_time": "2024-02-03T23:04:15.554370024Z",
  "updated_time": "2024-02-03T23:05:20.123456789Z",
  "input": "How do I make an interaction?",
  "prompt_template": "Hello OpenAI, can you answer this question?",
  "response": "Hello, this is OpenAI. Here is the answer to your question.",
  "origin": "MyFirstOpenAIWrapper",
  "additional_info": {
    "feedback": "positive",
    "suggestion": "api.openai.com"
  }
}

Example request: Change a field in additional_info

PUT /_plugins/_ml/memory/message/WnA3cY0BfUsSoeNTI-_J
{
  "additional_info": {
    "feedback": "negative"
  }
}

Example response

{
  "_index": ".plugins-ml-memory-message",
  "_id": "WnA3cY0BfUsSoeNTI-_J",
  "_version": 3,
  "result": "updated",
  "forced_refresh": true,
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 46,
  "_primary_term": 1
}

The updated message contains the updated feedback field:

{
  "memory_id": "SXA2cY0BfUsSoeNTz-8m",
  "message_id": "WnA3cY0BfUsSoeNTI-_J",
  "create_time": "2024-02-03T23:04:15.554370024Z",
  "updated_time": "2024-02-03T23:06:45.987654321Z",
  "input": "How do I make an interaction?",
  "prompt_template": "Hello OpenAI, can you answer this question?",
  "response": "Hello, this is OpenAI. Here is the answer to your question.",
  "origin": "MyFirstOpenAIWrapper",
  "additional_info": {
    "feedback": "negative",
    "suggestion": "api.openai.com"
  }
}
350 characters left

Have a question? .

Want to contribute? or .