This topic describes the functions of the message component of Assistant API, including how to create, retrieve, modify, and list messages.
For more information on the functions and usage of Assistant API, see Feature overview.
Function | Description |
create | Creates a message class. |
retrieve | Retrieves a message class. |
modify | Modifies a message class. |
list | Lists a message class. |
Create a message
HTTP
Sample code
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/threads/thread_e99a9fe7-0433-426f-98ad-a5139c36579c/messages' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
"role": "user",
"content": "Who are you",
"metadata": {}
}'Request parameters
Parameter | Description | Type | Required |
thread_id | The ID of the thread that the message belongs to. | str | Yes |
content | The content of the message. | str | Yes |
role | The role of the input message. Valid value: user. | str | No |
metadata | Other related information. | str | No |
Sample response
{
"id": "message_f1933671-19e1-4162-ad25-7326165123e1",
"object": "thread.message",
"created_at": 1711508433283,
"thread_id": "thread_e99a9fe7-0433-426f-98ad-a5139c36579c",
"assistant_id": "",
"run_id": "",
"role": "user",
"content": [
{
"type": "text",
"text": {
"value": "Who are you",
"annotations": []
}
}
],
"metadata": {},
"from": "",
"name": "",
"plugin_call": {},
"tool_calls": [],
"status": {},
"request_id": "b3ad40b9-f052-9665-a064-dab11c34625f"
}Response parameters
The created message class, including the following parameters:
id: The message ID.
request_id: The request ID.
SDK
Sample code
from dashscope import Messages
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
msg = Messages.create('the_thread_id',
content='The message content.',
role='user',
metadata={'key': 'value'})
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.InvalidateParameter;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.threads.messages.Messages;
import com.alibaba.dashscope.threads.messages.TextMessageParam;
import com.alibaba.dashscope.threads.messages.ThreadMessage;
import com.alibaba.dashscope.utils.Constants;
public class Main {
static {
Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
}
public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
// create a message to thread
Messages messages = new Messages();
ThreadMessage message = messages.create("threadId", TextMessageParam.builder().role("user").content("How to make a hamburger").build());
}
}
Request parameters
Parameter | Type | Description |
thread_id | str | The thread ID. |
content | str | The content of the message. |
role | str | The role of the message. Default value: user. |
metadata | Dict | The key-value information related to the message. |
workspace | str | The workspace ID. |
api_key | str | The API key. You can set it as an environment variable. |
Sample response
The response is a JSON-formatted message object:
{
"assistant_id": "",
"content": [
{
"text": {
"value": "sdhafjdasf"
},
"type": "text"
}
],
"created_at": 1711345341301,
"display": true,
"from": "",
"gmt_crete": "2024-03-25 13:42:21",
"gmt_update": "2024-03-25 13:42:21",
"id": "message_05494921-a646-484e-85fc-76329acba842",
"metadata": {
"key": "value"
},
"name": "",
"object": "thread.message",
"plugin_call": {},
"request_id": "631de0b3-7e50-9c9e-8444-0924d1b7e7a5",
"role": "user",
"run_id": "",
"status": {},
"status_code": 200,
"thread_id": "thread_f1e7737e-b045-479f-99d1-510db49d535b",
"tool_calls": []
}Response parameters
Parameter | Type | Description |
status_code | int | The HTTP status code. 200 indicates that the request has succeeded. Otherwise, the request failed. |
id | str | The message ID, formatted as a UUID string. |
content | List[dict] | The content of the message. |
content.type | str | The type of the content, such as text. |
content.text | dict | The textual content. |
content.text.value | str | The text value of the content. |
metadata | Dict | The key-value pairs associated with the message. |
tool_calls | Dict | The details of the called tool. |
plugin_call | Dict | The details of the called plug-in. |
created_at | timestamp | The timestamp when the message was created. |
gmt_created | datetime | The time when the message was created. |
gmt_modified | datetime | The time when the message was modified. |
code | str | The error code returned in case of a failed request. This parameter is returned only when you use the SDK for Python. |
message | str | The error message returned in case of a failed request. This parameter is returned only when you use the SDK for Python. |
List messages
HTTP
Sample code
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/threads/thread_e99a9fe7-0433-426f-98ad-a5139c36579c/messages?limit=2&order=desc' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"Request parameters
Parameter | Description | Type | Required |
thread_id | The ID of the thread to query. | str | Yes |
limit | The maximum number of messages that can be returned. | int | No |
order | The ascending or descending order in which the messages are sorted based on the creation time. Default value: desc. | str | No |
Sample response
{
"object": "list",
"data": [
{
"id": "message_f1933671-19e1-4162-ad25-7326165123e1",
"object": "thread.message",
"created_at": 1711508433283,
"thread_id": "thread_e99a9fe7-0433-426f-98ad-a5139c36579c",
"assistant_id": "",
"run_id": "",
"role": "user",
"content": [
{
"type": "text",
"text": {
"value": "Who are you",
"annotations": []
}
}
],
"metadata": {},
"from": "",
"name": "",
"plugin_call": {},
"tool_calls": [],
"status": {}
}
],
"first_id": "message_f1933671-19e1-4162-ad25-7326165123e1",
"last_id": "message_f1933671-19e1-4162-ad25-7326165123e1",
"has_more": false,
"request_id": "78f7d607-4a9a-90c6-8040-d3f81c84d60a"
}Response parameters
A List Message class, including the following parameters:
A collection of messages.
SDK
Sample code
from dashscope import Messages
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
messages = Messages.list('thread_id',
limit=1,
order='desc',
after='',
before='')
import com.alibaba.dashscope.common.GeneralListParam;
import com.alibaba.dashscope.common.ListResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.InvalidateParameter;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.threads.messages.Messages;
import com.alibaba.dashscope.threads.messages.ThreadMessage;
import com.alibaba.dashscope.utils.Constants;
public class Main {
static {
Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
}
public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
// create a message to thread
Messages messages = new Messages();
GeneralListParam listThreadMessages = GeneralListParam.builder().build();
ListResult<ThreadMessage> message = messages.list("threadId", listThreadMessages);
}
}
Request parameters
Parameter | Type | Description |
thread_id | str | The ID of the thread to query. |
limit | str | |
order | ||
after | ||
before | ||
workspace | str | The workspace ID. |
api_key | str | The API key. You can set it as an environment variable. |
Response parameters
Parameter | Type | Description |
has_more | bool | |
last_id | str | |
first_id | str | |
data | list[Message] | The list of message objects. |
Retrieve a message
HTTP
Sample code
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/threads/thread_e99a9fe7-0433-426f-98ad-a5139c36579c/messages/message_ea26d29d-4509-490e-98e9-9f6238bd821b' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"Request parameters
Parameter | Description | Type | Required |
thread_id | The thread ID of the message to retrieve. | str | Yes |
message_id | The ID of the message to retrieve. | str | Yes |
Sample response
{
"id": "message_ea26d29d-4509-490e-98e9-9f6238bd821b",
"object": "thread.message",
"created_at": 1711508622598,
"thread_id": "thread_e99a9fe7-0433-426f-98ad-a5139c36579c",
"assistant_id": "",
"run_id": "",
"role": "user",
"content": [
{
"type": "text",
"text": {
"value": "Hello",
"annotations": []
}
}
],
"metadata": {},
"from": "",
"name": "",
"plugin_call": {},
"tool_calls": [],
"status": {},
"request_id": "4d5ce962-91c3-9edb-87f7-00bbf985135e"
}Response parameters
The retrieved message class, including the following parameters:
id: The message ID.
request_id: The request ID.
SDK
Sample code
from dashscope import Messages
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
message = Messages.retrieve('message_id',
thread_id='thread_id')
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.InvalidateParameter;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.threads.messages.Messages;
import com.alibaba.dashscope.threads.messages.ThreadMessage;
import com.alibaba.dashscope.utils.Constants;
public class Main {
static {
Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
}
public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
// create a message to thread
Messages messages = new Messages();
ThreadMessage message = messages.retrieve("threadId", "messageId");
}
}
Request parameters
Parameter | Type | Description |
message_id | str | The ID of the message to retrieve. |
thread_id | str | The ID of the thread that the message belongs to. |
workspace | str | The workspace ID. |
api_key | str | The API key. You can set it as an environment variable. |
Response parameters
See the response parameters of the Create a message section.
Modify a message
HTTP
Sample code
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/threads/thread_e99a9fe7-0433-426f-98ad-a5139c36579c/messages/message_ea26d29d-4509-490e-98e9-9f6238bd821b' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
"metadata": {
"modified": "true",
"user": "abc123"
}
}'
Request parameters
Parameter | Description | Type | Required |
thread_id | The ID of the thread that the message to modify belongs to. | str | Yes |
message_id | The ID of the message to modify. | str | Yes |
metadata | The key-value information related to the thread. | dict |
Sample response
{
"id": "message_ea26d29d-4509-490e-98e9-9f6238bd821b",
"object": "thread.message",
"created_at": 1711508622598,
"thread_id": "thread_e99a9fe7-0433-426f-98ad-a5139c36579c",
"assistant_id": "",
"run_id": "",
"role": "user",
"content": [
{
"type": "text",
"text": {
"value": "Hello",
"annotations": []
}
}
],
"metadata": {
"modified": "true",
"user": "abc123"
},
"from": "",
"name": "",
"plugin_call": {},
"tool_calls": [],
"status": {},
"request_id": "7877b011-cb94-9df1-9add-dc42b7d611f6"
}Response parameters
The modified message class, including the following parameters:
id: The message ID.
request_id: The request ID.
SDK
Sample code
from dashscope import Messages
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
thread = Messages.update('message_id',
thread_id='the_message_thread_id',
metadata={'key': 'value'})
import java.util.Collections;
import com.alibaba.dashscope.common.UpdateMetadataParam;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.InvalidateParameter;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.threads.messages.Messages;
import com.alibaba.dashscope.utils.Constants;
public class Main {
static {
Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
}
public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
Messages messages = new Messages();
UpdateMetadataParam updateMetadataParam = UpdateMetadataParam.builder().metadata(Collections.singletonMap("key", "value")).build();
messages.update("thread_id", "message_Id", updateMetadataParam);
}
}
Request parameters
Parameter | Type | Description |
message_id | str | The ID of the message to modify. |
thread_id | str | The ID of the thread that the message to modify belongs to. |
metadata | Dict | The key-value information related to the thread. |
workspace | str | The workspace ID. |
api_key | str | The API key. You can set it as an environment variable. |
Response parameters
See the response parameters of the Create a message section.