WebSocket APIs

Prerequisites

The intelligent interaction SDK can be integrated and the WebSocket APIs can be used to control virtual avatars only after the intelligent interaction permission is granted.

Obtaining an Endpoint

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.

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

**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.

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. nothing.

**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. 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 6 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.
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 AUDIO_DRIVE: audio 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	No	String	Text information. This parameter is mandatory when command is set to TEXT_DRIVE.
audio	No	String	Byte array of audio data, which is a Base64-encoded character string. This parameter is mandatory when command is set to AUDIO_DRIVE. Audio format: PCM Sampling bit width: 16 bits Maximum length: 40,960 bytes
sample_rate	No	Integer	Audio sampling rate. Supported rates: 8000, 12000, 16000 (default), 24000, and 48000, in Hz.
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 AUDIO_DRIVE_RSP: audio control response

Request Examples

The user requests for establishing a WebSocket connection for a dialog with a virtual avatar.
The following is a code example. For details about how to obtain {terminal access address}, see Obtaining an Endpoint.
```
wss://{terminal access address}/v1/70b76xxxxxx34253880af501cdxxxxxx/digital-human-chat/chat-command/e37a28485f684769aa537466e719629d
```

Wait until MetaStudio returns a message indicating that 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",
    }
}