Create, List & Modify Assistant API Messages - Alibaba Cloud Model Studio

Operations

Operation	Description
Create a message	Add a new message to a thread
List messages	Get all messages in a thread
Retrieve a message	Get a specific message by ID
Modify a message	Update the metadata of a message

Message object

Message object structure:

Parameter	Type	Description
id	string	Unique identifier for the message. Example: `message_f1933671-19e1-4162-ad25-7326165123e1`
object	string	Object type. Always `thread.message`.
created_at	integer	Unix timestamp (in milliseconds) when the message was created.
thread_id	string	Thread ID for this message.
role	string	The entity that produced the message: `user` or `assistant`.
content	array	Message content as an array of content objects. Each object has a `type` field (such as `text`) and a corresponding data field.
content[].type	string	Content type. Currently supports `text`.
content[].text.value	string	The text content of the message.
content[].text.annotations	array	Annotations associated with the text content.
assistant_id	string	ID of the assistant that authored this message, if applicable.
run_id	string	ID of the run associated with creating this message, if applicable.
metadata	object	Key-value pairs for storing additional structured information.
tool_calls	array	Tool call information, if any.
plugin_call	object	Plugin call information, if any.
request_id	string	Unique request identifier for the API call.
status_code	integer	HTTP status code (`200` = success). SDK responses only.

Create a message

Adds a user message to a thread.

HTTP

POST https://dashscope-intl.aliyuncs.com/api/v1/threads/{thread_id}/messages

Sample request

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	Type	Required	Description
thread_id	string	Yes	Thread ID (path parameter).
content	string	Yes	The text content of the message.
role	string	No	Message sender role. Only `user` supported (default).
metadata	object	No	Key-value pairs for additional structured information.

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"
}

The response is a message object.

SDK

SDK examples use the international endpoint.

Python

Java

Python

from dashscope import Messages
import dashscope
import os

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
msg = Messages.create(
    'the_thread_id',
    # Set the API key through the DASHSCOPE_API_KEY environment variable (recommended)
    # or replace with: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    content='The message content.',
    role='user',
    metadata={'key': 'value'}
)

Java

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 {
        Messages messages = new Messages();
        TextMessageParam param = TextMessageParam.builder()
                // Set the API key through the DASHSCOPE_API_KEY environment variable (recommended)
                // or replace with: .apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .role("user")
                .content("How to make delicious beef and potato stew?")
                .build();
        ThreadMessage message = messages.create("threadId", param);
    }
}

Request parameters

Parameter	Type	Required	Default	Description
thread_id	string	Yes	-	Thread ID for the message.
content	string	Yes	-	The text content of the message.
role	string	No	`user`	Message sender role (default: `user`).
metadata	object	No	None	Key-value pairs for additional structured information.
workspace	string	No	None	Model Studio Workspace ID. Required when `api_key` is a sub-workspace key.
api_key	string	No	None	Model Studio API key. Set as environment variable instead of hardcoding.

Sample response

Response (message object in JSON):

{
    "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": []
}

SDK-specific response parameters

SDK responses include these additional fields:

Parameter	Type	Description
status_code	integer	HTTP status code (`200` = success).
gmt_created	datetime	Formatted creation time (e.g., `2024-03-22 17:12:31`).
gmt_modified	datetime	Formatted last modification time (e.g., `2024-03-22 17:12:31`).
code	string	Error code (on failure). Python SDK only.
message	string	Error details (on failure). Python SDK only.

List messages

Get all messages in a thread (supports pagination and sorting).

HTTP

GET https://dashscope-intl.aliyuncs.com/api/v1/threads/{thread_id}/messages

Sample request

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	Type	Required	Description
thread_id	string	Yes	Thread ID (path parameter).
limit	integer	No	Max messages to return.
order	string	No	Sort order: `asc` (oldest first) or `desc` (newest first, default).
metadata	string	No	Filter messages by metadata.

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

Parameter	Type	Description
object	string	Always `list`.
data	array	Array of message objects.
first_id	string	First message ID in the list.
last_id	string	Last message ID in the list.
has_more	boolean	`true` if more messages exist beyond current page.
request_id	string	Unique request ID.

SDK

Python

Java

Python

from dashscope import Messages
import dashscope
import os

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

messages = Messages.list(
    'thread_id',
    # Set the API key through the DASHSCOPE_API_KEY environment variable (recommended)
    # or replace with: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    limit=1,
    order='desc'
)

Java

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 {
        Messages messages = new Messages();
        // Set the API key through the DASHSCOPE_API_KEY environment variable (recommended)
        // or replace with: .apiKey("sk-xxx")
        GeneralListParam listThreadMessages = GeneralListParam.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .build();
        ListResult<ThreadMessage> message = messages.list("threadId", listThreadMessages);
    }
}

Request parameters

Parameter	Type	Required	Default	Description
thread_id	string	Yes	-	Thread ID to list messages from.
limit	integer	No	None	Max messages to return.
order	string	No	None	Sort order: `asc` or `desc`.
workspace	string	No	None	Model Studio Workspace ID. Required when `api_key` is a sub-workspace key.
api_key	string	No	None	Model Studio API key. Set as environment variable instead of hardcoding.

Response parameters

Parameter	Type	Description
has_more	boolean	`true` if more messages exist beyond current page.
first_id	string	First message ID in the list.
last_id	string	Last message ID in the list.
data	list[Message]	Array of message objects.

Retrieve a message

Get a message by ID.

HTTP

GET https://dashscope-intl.aliyuncs.com/api/v1/threads/{thread_id}/messages/{message_id}

Sample request

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	Type	Required	Description
thread_id	string	Yes	Thread ID (path parameter).
message_id	string	Yes	Message ID (path parameter).

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"
}

The response is a message object.

SDK

Python

Java

Python

from dashscope import Messages
import dashscope
import os

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

message = Messages.retrieve(
    'message_id',
    # Set the API key through the DASHSCOPE_API_KEY environment variable (recommended)
    # or replace with: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    thread_id='thread_id'
)

Java

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 {
        Messages messages = new Messages();
        // Set the API key through the DASHSCOPE_API_KEY environment variable (recommended)
        // or replace with: .apiKey("sk-xxx")
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        ThreadMessage message = messages.retrieve("threadId", "messageId", apiKey);
    }
}

Request parameters

Parameter	Type	Required	Default	Description
message_id	string	Yes	-	Message ID to retrieve.
thread_id	string	Yes	-	Thread ID containing the message.
workspace	string	No	None	Model Studio Workspace ID. Required when `api_key` is a sub-workspace key.
api_key	string	No	None	Model Studio API key. Set as environment variable instead of hardcoding.

Response parameters

Same as the Create a message response.

Modify a message

Update message metadata (only metadata field is modifiable).

HTTP

POST https://dashscope-intl.aliyuncs.com/api/v1/threads/{thread_id}/messages/{message_id}

Sample request

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	Type	Required	Description
thread_id	string	Yes	Thread ID (path parameter).
message_id	string	Yes	Message ID (path parameter).
metadata	object	No	Key-value pairs (replace existing metadata).

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: updated message object with new metadata.

SDK

Python

Java

Python

from dashscope import Messages
import dashscope
import os

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

thread = Messages.update(
    'message_id',
    # Set the API key through the DASHSCOPE_API_KEY environment variable (recommended)
    # or replace with: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    thread_id='the_message_thread_id',
    metadata={'key': 'value'}
)

Java

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();
        // Set the API key through the DASHSCOPE_API_KEY environment variable (recommended)
        // or replace with: .apiKey("sk-xxx")
        UpdateMetadataParam updateMetadataParam = UpdateMetadataParam.builder()
                .metadata(Collections.singletonMap("key", "value"))
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .build();
        messages.update("thread_id", "message_Id", updateMetadataParam);
    }
}

Request parameters

Parameter	Type	Required	Default	Description
message_id	string	Yes	-	Message ID to update.
thread_id	string	Yes	-	Thread ID containing the message.
metadata	object	No	None	Key-value pairs (replace existing metadata).
workspace	string	No	None	Model Studio Workspace ID. Required when `api_key` is a sub-workspace key.
api_key	string	No	None	Model Studio API key. Set as environment variable instead of hardcoding.

Response parameters

Same as Create a message response.

Error codes

For failed calls, see Error messages.