CreateChat - STAROps - Alibaba Cloud Documentation Center

Creates a conversation.

Operation description

Initiates a conversation.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

starops:CreateChat

none

*DigitalEmployee

acs:starops:{#regionId}:{#accountId}:digitalemployee/{#name}

None

Request syntax

POST /chat HTTP/1.1

Request parameters

Parameter	Type	Required	Description	Example
body	object	No	The request struct.
digitalEmployeeName	string	No	The name of the digital employee.	test
threadId	string	No	The conversation thread ID.	thread_id01
action	string	No	The action type. Valid values: create: creates a conversation. reconnect: reconnects to an existing conversation. stop: stops the conversation. Default value: create.	create
variables	object	No	The list of variables.	{ "workspace": "test", "region": "cn-beijing", "project": "test", "language": "zh", "timeZone": "Asia/Shanghai", "timeStamp": "1768893948", "startTime": 1768887171, "endTime": 1768890771, "skill": "trace" }
messages	array<object>	No	The list of messages.
	array<object>	No	The message.
messageId	string	No	The unique identifier of the current message.	message_id02
role	string	No	The role of the message.	system
contents	array<object>	No	The text or multimodal array.
	object	No	The text or multimodal content.
type	string	No	The content type.	text
value	string	No	The value of the content.	test
tools	array<object>	No	The list of tool invocations.
	object	No	The tool invocation.	{ "arguments": { "confidence": "high", "intent": "analyser", "is_new_turn": true, "language": "en", "title": "Root Cause of Alert" }, "id": "IntentRecognition", }

Response elements

Element	Type	Description	Example
	object	Schema of Response
messages	array<object>	The list of messages in the session.
	array<object>	The message detail structure.
version	string	The version number of the message.	v0.1.0
parentCallId	string	The execution ID of the parent level.	sess_abc123
callId	string	The current execution ID.	call_search_001
role	string	The role that initiated the message.	tool
seq	integer	The sequence number of the message.	1
timestamp	string	The timestamp in nanoseconds.	1765000005
type	string	The specific type of the message.	done
detail	string	The message details.	test
contents	array<object>	The content information.
	object	The content detail structure.	{ "append": false, "lastChunk": false, "type": "text", "value": "result output chunk" }
tools	array<object>	The list of tools used.
	object	The tool detail structure.	{ "arguments": { "confidence": "high", "intent": "analyser", "is_new_turn": true, "language": "en", "title": "Root Cause of Alert" }, "id": "IntentRecognition", "name": "IntentRecognition", "status": "start", "toolCallId": "019bc1cb-adad" }
agents	array<object>	The list of invoked agents.
	object	The details of the invoked agent.	{ "callId": "019bc1cb-adad", "id": "analyser", "inputs": [ { "append": false, "lastChunk": false, "type": "text", "value": "Analyze this trace: TraceID=xxx" } ], "name": "analyser", "status": "start" }
events	array<object>	The list of events.
	object	The event details.	{ "payload": { "error": { "code": "TASK_FAILED", "message": "Invalid task parameter", "suggestion": "" }, "statistics": { "duration": 300000 }, "success": false }, "type": "task_finished" }
artifacts	array<object>	The artifact output information.
	object	The artifact detail structure.	{ "artifactId": "019bc1cb-9600-703axxx", "name": "sql output", "description": "sql generation task result", "extensions": ["sql_generation_tool", "sql_diagnosis"], "metadata": { "model": "qwen3-coder-plus" }, "parts": [ { "text": "select * from table", "kind": "text" } ] }
traceId	string	The ID data of the current message request. The first trace ID in the root data.	21504600000008405622576e3b48
requestId	string	The ID data of the current message request. The first request ID in the root data.	0CEC5375-XXXX-XXXX-XXXX-9A629907C1F0

Examples

Success response

JSON format

{
  "messages": [
    {
      "version": "v0.1.0",
      "parentCallId": "sess_abc123",
      "callId": "call_search_001",
      "role": "tool",
      "seq": 1,
      "timestamp": "1765000005",
      "type": "done",
      "detail": "test",
      "contents": [
        {
          "append": false,
          "lastChunk": false,
          "type": "text",
          "value": "result output chunk"
        }
      ],
      "tools": [
        {
          "arguments": {
            "confidence": "high",
            "intent": "analyser",
            "is_new_turn": true,
            "language": "en",
            "title": "Root Cause of Alert"
          },
          "id": "IntentRecognition",
          "name": "IntentRecognition",
          "status": "start",
          "toolCallId": "019bc1cb-adad"
        }
      ],
      "agents": [
        {
          "callId": "019bc1cb-adad",
          "id": "analyser",
          "inputs": [
            {
              "append": false,
              "lastChunk": false,
              "type": "text",
              "value": "Analyze this trace: TraceID=xxx"
            }
          ],
          "name": "analyser",
          "status": "start"
        }
      ],
      "events": [
        {
          "payload": {
            "error": {
              "code": "TASK_FAILED",
              "message": "Invalid task parameter",
              "suggestion": ""
            },
            "statistics": {
              "duration": 300000
            },
            "success": false
          },
          "type": "task_finished"
        }
      ],
      "artifacts": [
        {
          "artifactId": "019bc1cb-9600-703axxx",
          "name": "sql output",
          "description": "sql generation task result",
          "extensions": [
            "sql_generation_tool",
            "sql_diagnosis"
          ],
          "metadata": {
            "model": "qwen3-coder-plus"
          },
          "parts": [
            {
              "text": "select * from table",
              "kind": "text"
            }
          ]
        }
      ]
    }
  ],
  "traceId": "21504600000008405622576e3b48",
  "requestId": "0CEC5375-XXXX-XXXX-XXXX-9A629907C1F0"
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.