Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Suggested
Overview Models Agents Tools Voice & Audio Production API reference
API Dashboard
Try ChatGPT
API Reference
Beta
Threads
Messages

Create message

beta.threads.messages.create(strthread_id, MessageCreateParams**kwargs) -> Message
POST/threads/{thread_id}/messages

Create a message.

ParametersExpand Collapse
thread_id: str
content: Union[str, Iterable[MessageContentPartParam]]

The text contents of the message.

role: Literal["user", "assistant"]

The role of the entity that is creating the message. Allowed values include:

  • user: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages.
  • assistant: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation.
attachments: Optional[Iterable[Attachment]]

A list of files attached to the message, and the tools they should be added to.

metadata: Optional[Metadata]

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.

Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

ReturnsExpand Collapse
class Message: …

Represents a message within a thread.

id: str

The identifier, which can be referenced in API endpoints.

assistant_id: Optional[str]

If applicable, the ID of the assistant that authored this message.

attachments: Optional[List[Attachment]]

A list of files attached to the message, and the tools they were added to.

completed_at: Optional[int]

The Unix timestamp (in seconds) for when the message was completed.

formatunixtime
content: List[MessageContent]

The content of the message in array of text and/or images.

created_at: int

The Unix timestamp (in seconds) for when the message was created.

formatunixtime
incomplete_at: Optional[int]

The Unix timestamp (in seconds) for when the message was marked as incomplete.

formatunixtime
incomplete_details: Optional[IncompleteDetails]

On an incomplete message, details about why the message is incomplete.

metadata: Optional[Metadata]

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.

Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

object: Literal["thread.message"]

The object type, which is always thread.message.

role: Literal["user", "assistant"]

The entity that produced the message. One of user or assistant.

run_id: Optional[str]

The ID of the run associated with the creation of this message. Value is null when messages are created manually using the create message or create thread endpoints.

status: Literal["in_progress", "incomplete", "completed"]

The status of the message, which can be either in_progress, incomplete, or completed.

thread_id: str

The thread ID that this message belongs to.

Create message

from openai import OpenAI
client = OpenAI()

thread_message = client.beta.threads.messages.create(
  "thread_abc123",
  role="user",
  content="How does AI work? Explain it in simple terms.",
)
print(thread_message)

{
  "id": "msg_abc123",
  "object": "thread.message",
  "created_at": 1713226573,
  "assistant_id": null,
  "thread_id": "thread_abc123",
  "run_id": null,
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": {
        "value": "How does AI work? Explain it in simple terms.",
        "annotations": []
      }
    }
  ],
  "attachments": [],
  "metadata": {}
}
Returns Examples
{
  "id": "msg_abc123",
  "object": "thread.message",
  "created_at": 1713226573,
  "assistant_id": null,
  "thread_id": "thread_abc123",
  "run_id": null,
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": {
        "value": "How does AI work? Explain it in simple terms.",
        "annotations": []
      }
    }
  ],
  "attachments": [],
  "metadata": {}
}