CreateChat - STAROps - Alibaba Cloud Documentation Center

New conversation

Operation description

Starts a session.

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 body.
digitalEmployeeName	string	No	The name of the digital employee.	test
threadId	string	No	The session thread ID.	thread_id01
action	string	No	The operation type. Valid values: `create` (default), `reconnect`, and `stop`.	create
variables	object	No	The set 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 message list.
	array<object>	No	A message.
messageId	string	No	A unique identifier for the message.	message_id02
role	string	No	The role of the message.	system
contents	array<object>	No	The multimodal content of the message.
	object	No	A block of multimodal content.
type	string	No	The content type.	text
value	string	No	The value of the content.	test
tools	array<object>	No	The tool call list.
	object	No	A tool call.	{ "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	Response schema.
messages	array<object>	A list of message objects in the session.
	array<object>	The detailed structure of a message object.
version	string	The message version.	v0.1.0
parentCallId	string	The ID of the parent call.	sess_abc123
callId	string	The ID of the current call.	call_search_001
role	string	The role of the message sender.	tool
seq	integer	The message sequence number.	1
timestamp	string	The timestamp, in nanoseconds.	1765000005
type	string	The message type.	done
detail	string	Message details.	test
contents	array<object>	A list of content objects.
	object	The detailed structure of a content object.	{ "append": false, "lastChunk": false, "type": "text", "value": "result output chunk" }
tools	array<object>	A list of tool calls.
	object	The detailed structure of a tool call.	{ "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>	A list of invoked agents.
	object	The detailed structure of an 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>	A list of events.
	object	The detailed structure of an event.	{ "payload": { "error": { "code": "TASK_FAILED", "message": "Invalid task parameter", "suggestion": "" }, "statistics": { "duration": 300000 }, "success": false }, "type": "task_finished" }
artifacts	array<object>	A list of generated artifacts.
	object	The detailed structure of an artifact.	{ "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	Uniquely identifies the request chain for tracing.	21504600000008405622576e3b48
requestId	string	A unique identifier for the API request, useful for troubleshooting.	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.