Help Center/ MetaStudio/ API Reference/ Intelligent Interaction/ Intelligent Interaction Control/ WebSocket APIs

Updated on 2025-12-08 GMT+08:00

View PDF

WebSocket APIs

Obtaining an Endpoint

Obtain the endpoint of the WebSocket API for intelligent interaction by referring to Table 1.

The endpoint address is dynamically obtained each time when a virtual avatar intelligent interaction task is started. You use a fixed address for access and cannot enter a fixed domain name.

**Table 1** Obtaining an endpoint
Scenario	How to Obtain
Web SDK is not used	The endpoint address is obtained from the response parameter chat_access_address of the API for starting a virtual avatar intelligent interaction task.
Web SDK is used	The endpoint address is obtained from the parameter websocketAddr in the notification jobInfoChange of the intelligent interaction SDK.

Functions

This API is used to create a WebSocket connection for a dialog between a user and a virtual avatar.

Calling Methods

You can use either of the following methods to call this API:

IAM token authentication. For details, see Calling APIs.
One-off token authentication. For details, see Creating a One-Off Authentication Code.

URI

/v1/{project_id}/digital-human-chat/chat-command/{job_id}

Table 2, Table 3, and Table 4 are parameters for establishing a WebSocket connection.

**Table 2** URI parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. See Obtaining a Project ID.
job_id	Yes	String	Task ID. In the input parameter eventListeners of the API create of the Web SDK, listen to the jobInfoChange event notification to obtain the task ID.

**Table 3** Query parameters
Parameter	Mandatory	Type	Description
token	No	String	One-off token. To obtain the token, see Creating a One-off Authentication Code. NOTICE: JavaScript-based development requires a one-off authentication code.

**Table 4** Header parameters in a request
Parameter	Mandatory	Type	Description
X-Auth-Token	No	String	User token. The token can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token.

Request Parameters

The request parameters in Table 5, Table 6, and Table 7 are used for a dialog between a user and a virtual avatar after a WebSocket connection is established.

**Table 5** Message parameters in a request
Parameter	Mandatory	Type	Description
request_id	No	String	Request ID.
payload	Yes	RequestPayloadInfo object	Request load information.

**Table 6** RequestPayloadInfo
Parameter	Mandatory	Type	Description
job_id	Yes	String	Task ID. See Obtaining the Task ID.
robot_id	No	String	Application ID. Obtain the value from the URL of the virtual avatar interaction page. For details about how to obtain the URL, see "Creating an Interactive Virtual Avatar" in the User Guide.
chat_id	Yes	String	Dialog ID.
command	Yes	String	Operation command. Options: TEXT_DRIVE: text control INTERRUPT_CHAT: interrupting a dialog STOP_CHAT: stopping a dialog
data	Yes	ChatReqDataInfo object	Dialog request data.

**Table 7** ChatReqDataInfo
Parameter	Mandatory	Type	Description
text	Yes	String	Text information.
seq	No	Integer	Sequence number of a data packet.
is_last	No	Boolean	Whether the text is the last one.

Response Parameters

Status code: 101

**Table 8** Header parameters in a response
Parameter	Type	Description
X-Request-Id	String	Request ID.

**Table 9** Message parameters in a response
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error description.
request_id	String	Request ID.
payload	ResponsePayloadInfo object	Response load information.

**Table 10** ResponsePayloadInfo
Parameter	Type	Description
job_id	String	Task ID.
chat_id	String	Dialog ID.
command	String	Operation command. Options: START_CHAT: starting a dialog TEXT_DRIVE_RSP: response to text control START_SPEAKING: starting speaking STOP_SPEAKING: stopping speaking INTERRUPT_CHAT_RSP: response to the request for interrupting a dialog STOP_CHAT_RSP: response to the request for stopping a dialog JOB_FINISHED: ending a task PING: heartbeat request PONG: heartbeat response

Request Examples

The user requests for establishing a WebSocket connection for a dialog with a virtual avatar.

Code example:

wss://metastudio-api.cn-north-4.myhuaweicloud.com/v1/70b76xxxxxx34253880af501cdxxxxxx/digital-human-chat/chat-command/e37a28485f684769aa537466e719629d

Wait until MetaStudio returns a message indicating that the the dialog can be started, as shown in 2. The user sends a message for text control.

Code example:

{
    "request_id": "d7aa08da33dd4a662ad5be508c5b77cf",
    "payload": {
        "job_id": "e37a28485f684769aa537466e719629d",
        "robot_id": "2c9d60818b365847018b365f40320000",
        "chat_id": "ac71c539395b4446865074589ffa2c6c",
        "command": "TEXT_DRIVE",
        "data": {
            "text": "Hello, I'm your virtual avatar",
            "seq": 1,
            "is_last": true
        }
    }
}

Response Examples

Status code: 101

After receiving the request for establishing a WebSocket connection, MetaStudio returns a response, as shown in 1.
Code example:
```
{
    "error_code": "MSS.00000000",
    "error_msg": "success",
    "request_id": "d7aa08da33dd4a662ad5be508c5b77cf"
}
```

MetaStudio sends a message for starting a dialog.

Code example:

{
    "request_id": "d7aa08da33dd4a662ad5be508c5b77cf",
    "payload": {
        "command": "START_CHAT",
        "job_id": "e37a28485f684769aa537466e719629d",
        "chat_id": "ac71c539395b4446865074589ffa2c6c",
    }
}

MetaStudio receives a message sent by the user for text control, as shown in 2. MetaStudio returns a response to text control.

Code example:

{
    "error_code": "MSS.00000000",
    "error_msg": "success",
    "request_id": "d7aa08da33dd4a662ad5be508c5b77cf",
    "payload": {
        "command": "TEXT_DRIVE_RSP",
        "job_id": "e37a28485f684769aa537466e719629d",
        "chat_id": "ac71c539395b4446865074589ffa2c6c",
    }
}

Status Codes

Status Code	Description
101	Connected.

Error Codes

See Error Codes.

Parent Topic: Intelligent Interaction Control

Previous topic: Process

Next topic: Third-Party LLM Callback for Intelligent Interaction

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot