Messages

Messages facilitate communication with agents, including user prompts and assistant responses. They provide a structured way to manage conversations and agent interactions.

Message Group object

A structured representation of a communication event, containing user prompts, assistant responses, or associated runs and metadata.

Attributes

String

A unique identifier for the message.

status

Enum

Current processing or lifecycle state of the message.

type

Enum

Specifies whether the message represents user input or assistant output.

created_at

Date

The timestamp when the message was created, formatted in ISO 8601.

thread_id

String

A unique identifier linking the message to a thread.

parent_message_group_id

String

The identifier of the message group that precedes this message in the sequence.

metadata

Object

Additional metadata associated with the message, in a key-value format.

messages

Array of Objects

A collection of message items in this message group.

attached_items

Array of Objects

A list of additional items attached to this message, such as files or metadata.

run

ObjectOptional

Information about a run triggered by this message. This field is optional.

{
  "id": "msg_Rm4Mnheq2bfEPhBhP7SY",
  "status": "completed",
  "type": "assistant_message",
  "created_at": "2025-01-01T00:00:00.000Z",
  "thread_id": "thread_Rm4Mnheq2bfEPhBhP7SY",
  "parent_message_group_id": "mgrp_Rm4Mnheq2bfEPhBhP7SY",
  "metadata": {
    "key": "value"
  },
  "messages": [
    {
      "id": "msg_Rm4Mnheq2bfEPhBhP7SY",
      "status": "active",
      "type": "content",
      "message_group_id": "mgrp_Rm4Mnheq2bfEPhBhP7SY",
      "thread_id": "thread_Rm4Mnheq2bfEPhBhP7SY",
      "actor": {
        "id": "act_Rm4Mnheq2bfEPhBhP7SY",
        "name": "John Doe",
        "type": "user",
        "metadata": {
          "email": "[email protected]",
          "other": "Additional metadata can be included here."
        },
        "created_at": "2025-01-01T00:00:00.000Z",
        "updated_at": "2025-01-01T00:00:00.000Z"
      },
      "content": {
        "id": "cnt_Rm4Mnheq2bfEPhBhP7SY",
        "message_item_id": "msg_Rm4Mnheq2bfEPhBhP7SY",
        "attachments": [
          {
            "id": "att_Rm4Mnheq2bfEPhBhP7SY",
            "type": "file",
            "file_id": "file_Rm4Mnheq2bfEPhBhP7SY",
            "url": "https://example.com/file_Rm4Mnheq2bfEPhBhP7SY",
            "caption": "Example file"
          }
        ],
        "parts": [
          {
            "id": "part_Rm4Mnheq2bfEPhBhP7SY",
            "type": "text",
            "text": "Example text"
          }
        ]
      },
      "error": null,
      "created_at": "2025-01-01T00:00:00.000Z"
    },
    {
      "id": "msg_Rm4Mnheq2bfEPhBhP7SY",
      "status": "active",
      "type": "content",
      "message_group_id": "mgrp_Rm4Mnheq2bfEPhBhP7SY",
      "thread_id": "thread_Rm4Mnheq2bfEPhBhP7SY",
      "actor": {
        "id": "act_Rm4Mnheq2bfEPhBhP7SY",
        "name": "John Doe",
        "type": "user",
        "metadata": {
          "email": "[email protected]",
          "other": "Additional metadata can be included here."
        },
        "created_at": "2025-01-01T00:00:00.000Z",
        "updated_at": "2025-01-01T00:00:00.000Z"
      },
      "content": {
        "id": "cnt_Rm4Mnheq2bfEPhBhP7SY",
        "message_item_id": "msg_Rm4Mnheq2bfEPhBhP7SY",
        "attachments": [
          {
            "id": "att_Rm4Mnheq2bfEPhBhP7SY",
            "type": "file",
            "file_id": "file_Rm4Mnheq2bfEPhBhP7SY",
            "url": "https://example.com/file_Rm4Mnheq2bfEPhBhP7SY",
            "caption": "Example file"
          }
        ],
        "parts": [
          {
            "id": "part_Rm4Mnheq2bfEPhBhP7SY",
            "type": "text",
            "text": "Example text"
          }
        ]
      },
      "error": null,
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  ],
  "attached_items": [
    {
      "id": "itm_Rm4Mnheq2bfEPhBhP7SY",
      "actor": {
        "id": "act_Rm4Mnheq2bfEPhBhP7SY",
        "name": "John Doe",
        "type": "user",
        "metadata": {
          "email": "[email protected]",
          "other": "Additional metadata can be included here."
        },
        "created_at": "2025-01-01T00:00:00.000Z",
        "updated_at": "2025-01-01T00:00:00.000Z"
      },
      "key": "example_key",
      "value": {
        "example": "value"
      },
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  ],
  "run": {
    "id": "run_Rm4Mnheq2bfEPhBhP7SY",
    "agent_id": "act_Rm4Mnheq2bfEPhBhP7SY",
    "status": "success",
    "metadata": {
      "key": "value"
    },
    "started_at": "2025-01-01T00:00:00.000Z",
    "created_at": "2025-01-01T00:00:00.000Z",
    "completed_at": "2025-01-01T00:00:00.000Z"
  }
}

cURL

List Messages

Retrieve a list of messages with optional filters for more precise results.

Query Parameters

ObjectOptional

Filter messages by their unique IDs.

created_at

ObjectOptional

Filter messages by their creation date.

status

ObjectOptional

Filter messages by their current status.

type

ObjectOptional

Filter messages by their type.

GEThttps://api.metorial.com/messages

cURL

curl -X GET https://api.metorial.com/v1/messages \
  -H "Authorization: Bearer metorial_sk_..."

Get Message

Retrieve details of a single message by its unique identifier.

URL Parameters

messageId

String

A unique identifier for a message, typically used for message tracking, retrieval, and reference in various contexts.

GEThttps://api.metorial.com/messages/:messageId

cURL

curl -X GET https://api.metorial.com/v1/messages/msg_Rm4Mnheq2bfEPhBhP7SY \
  -H "Authorization: Bearer metorial_sk_..."

Create Message

Create and post a new message to a specified thread.

Request Body

actor_id

StringOptional

The unique identifier for the actor creating the message. Optional when using an authenticated secret key.

thread_id

String

The unique identifier of the thread to which the message belongs.

content

Object

The structured content of the message.

POSThttps://api.metorial.com/messages

cURL

curl -X POST https://api.metorial.com/v1/messages \
  -H "Authorization: Bearer metorial_sk_..." \
  -d '{
    "actor_id": "act_Rm4Mnheq2bfEPhBhP7SY",
    "thread_id": "thread_Rm4Mnheq2bfEPhBhP7SY",
    "content": {
      "parts": [
        {
          "mime_type": "markdown",
          "content": "This is a sample message in **Markdown** format."
        }
      ],
      "attachments": [
        {
          "file_id": "file_Rm4Mnheq2bfEPhBhP7SY",
          "caption": "An example file attachment."
        }
      ]
    }
  }'