Messages - Alibaba Cloud Model Studio - Alibaba Cloud Documentation Center

This topic describes the Message class in the Assistant API and explains how to create, list, retrieve, and modify messages.

Function name	Type
create	Creates a message.
retrieve	Retrieves a message.
modify	Modifies a message.
list	Lists messages.

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 containing the message to retrieve.	str	Yes
content	The details of the message.	str	Yes
role	The role of the message. Only user is supported.	str	No
metadata	Other related information.	object	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 output is a message object containing additional metadata and details.

id: The unique identifier of the message.
request_id: The request ID.

SDK

Sample code

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',
    # We recommend that you configure the environment variable first. If you have not configured the environment variable, replace the following line with your Model Studio API key: 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 {
        // create a message to thread
        Messages messages = new Messages();
        TextMessageParam param = TextMessageParam.builder()
                // We recommend that you configure the environment variable first. If you have not configured the environment variable, replace the following line with your Model Studio API key: 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	Default value	Description
thread_id	str	-	The ID of the thread containing the message.
content	str	-	The message content.
role	str	'user'	The role of the message. The default value is user.
metadata	object	None	The key-value information associated with the message.
workspace	str	None	The Workspace ID of Model Studio. This parameter is required only when api_key is a sub-workspace API key.
api_key	str	None	The API key of Model Studio. We recommend that you configure the API key as an environment variable.

Sample response

The result is a message object. The following code shows the content in JSON format:

{
    "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. A value of 200 indicates that the call is successful. Other values indicate that the call fails.
id	str	The unique identifier of the message.
content	List[dict]	The message content.
content.type	str	The content type, such as text.
content.text	dict	The content.
content.text.value	str	The text value of the content.
metadata	object	The key-value information associated with this message.
tool_calls	Dict	The information about the tool call.
plugin_call	Dict	The information about the plug-in call.
created_at	timestamp	The time when the assistant was created.
gmt_created	datetime	2024-03-22 17:12:31
gmt_modified	datetime	2024-03-22 17:12:31
code	str	Indicates that the request fails. This parameter indicates the error code. This parameter is ignored if the request is successful. Only returned for the Python SDK.
message	str	Indicates that the request fails. This parameter indicates the details of the failure. This parameter is ignored if the request is successful. Only returned for the Python SDK.

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 containing the message to retrieve.	str	Yes
limit	The number of messages to return.	int	No
order	The order in which messages are sorted by creation time, which can be ascending or descending.	str	No (The default value is "desc")
metadata	Additional metadata for the message	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

The output is a list of message objects, each containing additional metadata and details.

A list of multiple messages.

SDK

Sample code

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',
    # We recommend that you configure the environment variable first. If you have not configured the environment variable, replace the following line with your Model Studio API key: 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();
        // We recommend that you configure the environment variable first. If you have not configured the environment variable, replace the following line with your Model Studio API key: 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	Default value	Description
thread_id	str	-	The thread ID.
limit	int	None	The number of messages to retrieve.
order	str	None	The order in which messages are sorted by created_at.
workspace	str	None	The Workspace ID of Model Studio. This parameter is required only when api_key is a sub-workspace API key.
api_key	str	None	The API key of Model Studio. We recommend that you configure the API key as an environment variable.

Response parameters

Parameter	Type	Description
has_more	bool	Indicates whether there are more messages to retrieve.
last_id	str	The ID of the last message in the returned list.
first_id	str	The ID of the first message in the returned list.
data	list[Message]	A 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 ID of the thread containing 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 output is the retrieved message object, which contains the following fields:

id: The unique identifier of the message.
request_id: The request ID.

SDK

Sample code

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',
    # We recommend that you configure the environment variable first. If you have not configured the environment variable, replace the following line with your Model Studio API key: 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();
        // We recommend that you configure the environment variable first. If you have not configured the environment variable, replace the following line with your Model Studio API key: apiKey("sk-xxx")
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        ThreadMessage message = messages.retrieve("threadId", "messageId", apiKey);
    }
}

Request parameters

Parameter	Type	Default value	Description
message_id	str	-	The ID of the message to query.
thread_id	str	-	The ID of the thread containing the message to retrieve.
workspace	str	None	The Workspace ID of Model Studio. This parameter is required only when api_key is a sub-workspace API key.
api_key	str	None	The API key of Model Studio. We recommend that you configure the API key as an environment variable.

Response parameters

See the response parameters of create.

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 thread ID.	str	Yes
message_id	The ID of the message to modify.	str	Yes
metadata	The metadata.	object

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 output is the modified message object, which contains the following fields in addition to the input parameters:

id: The unique identifier of the message.
request_id: The request ID.

SDK

Sample code

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',
    # We recommend that you configure the environment variable first. If you have not configured the environment variable, replace the following line with your Model Studio API key: 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();
        // We recommend that you configure the environment variable first. If you have not configured the environment variable, replace the following line with your Model Studio API key: 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	Default value	Description
message_id	str	-	The ID of the message to update.
thread_id	str	-	The ID of the thread containing the message to retrieve.
metadata	object	None	The information associated with the thread.
workspace	str	None	The Workspace ID of Model Studio. This parameter is required only when api_key is a sub-workspace API key.
api_key	str	None	The API key of Model Studio. We recommend that you configure the API key as an environment variable.

Response parameters

See the response parameters of create.

Error codes

If a call fails and returns an error message, see Error messages for troubleshooting.