MessagesBeta
Create messages within threads
Related guide: Assistants
Create messageBeta
Create a message.
Path parameters
The ID of the thread to create a message for.
Request body
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.
A list of files attached to the message, and the tools they should be added to.
Returns
A message object.
1
2
3
4
5
6
7
8
curl https://api.openai.com/v1/threads/thread_abc123/messages \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: assistants=v2" \
-d '{
"role": "user",
"content": "How does AI work? Explain it in simple terms."
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"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": {}
}
List messagesBeta
Returns a list of messages for a given thread.
Path parameters
The ID of the thread the messages belong to.
Query parameters
A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
Sort order by the created_at
timestamp of the objects. asc
for ascending order and desc
for descending order.
A cursor for use in pagination. after
is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
A cursor for use in pagination. before
is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.
Returns
A list of message objects.
1
2
3
4
curl https://api.openai.com/v1/threads/thread_abc123/messages \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: assistants=v2"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
"object": "list",
"data": [
{
"id": "msg_abc123",
"object": "thread.message",
"created_at": 1699016383,
"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": {}
},
{
"id": "msg_abc456",
"object": "thread.message",
"created_at": 1699016383,
"assistant_id": null,
"thread_id": "thread_abc123",
"run_id": null,
"role": "user",
"content": [
{
"type": "text",
"text": {
"value": "Hello, what is AI?",
"annotations": []
}
}
],
"attachments": [],
"metadata": {}
}
],
"first_id": "msg_abc123",
"last_id": "msg_abc456",
"has_more": false
}
Retrieve messageBeta
Retrieve a message.
Path parameters
The ID of the thread to which this message belongs.
Returns
The message object matching the specified ID.
1
2
3
4
curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: assistants=v2"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"id": "msg_abc123",
"object": "thread.message",
"created_at": 1699017614,
"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": {}
}
Modify messageBeta
Modifies a message.
Path parameters
Request body
Returns
The modified message object.
1
2
3
4
5
6
7
8
9
10
curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: assistants=v2" \
-d '{
"metadata": {
"modified": "true",
"user": "abc123"
}
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
"id": "msg_abc123",
"object": "thread.message",
"created_at": 1699017614,
"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": []
}
}
],
"file_ids": [],
"metadata": {
"modified": "true",
"user": "abc123"
}
}
Delete messageBeta
Deletes a message.
Path parameters
Returns
Deletion status
1
2
3
4
curl -X DELETE https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: assistants=v2"
1
2
3
4
5
{
"id": "msg_abc123",
"object": "thread.message.deleted",
"deleted": true
}
The message objectBeta
Represents a message within a thread.
The thread ID that this message belongs to.
On an incomplete message, details about why the message is incomplete.
The Unix timestamp (in seconds) for when the message was marked as incomplete.
If applicable, the ID of the assistant that authored this message.
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"id": "msg_abc123",
"object": "thread.message",
"created_at": 1698983503,
"thread_id": "thread_abc123",
"role": "assistant",
"content": [
{
"type": "text",
"text": {
"value": "Hi! How can I help you today?",
"annotations": []
}
}
],
"assistant_id": "asst_abc123",
"run_id": "run_abc123",
"attachments": [],
"metadata": {}
}