WebSocket is connection-oriented and full-duplex channel. Before establishing connection, you must first get Token from the server. Use this token to create a WebSocket connection with the server. The token is only valid during link establishment and will be discarded upon success.
Access Process Diagram:
1. Retrieve the Token for Establishing a Websocket Connection
1.1 Calling Method
Obtain the Token by calling the GetWsToken API through the Tencent Cloud SDK. See the GetWsToken document.
Note:
The obtained Token can be used only once for session connection and will expire. Please establish a persistent connection promptly after obtaining the Token. If another connection is required, you must get the Token again.
Tag-related values no longer use this API for transmission. Refer to section 3.1 data structure for custom_variables to input knowledge library search scope related parameters.
1.2 How to Obtain an AppKey
In the Application Management interface, find your running application (it must be published first), click Call, and the "Call Information" window will pop up.
In the Call Information window, you can see the AppKey. Click Copy.
After establishing a connection and receiving the server response, send the Token for authentication. The Token format is as follows:
40{"token":"xx-xx-xx-xx-xx"}
2.3 Heartbeat Processing
The server sends the heartbeat packet as follows ("2" is the content of the heartbeat packet):
2
At this point, the client must respond ("3" is the response content):
3
Note:
Socket io V4 has a heartbeat packet, must process it, otherwise the server will disconnect.
If you implement the Client yourself, pay attention to heartbeat packet processing. This document provides a Demo that has already handled heartbeat packets automatically.
3. WebSocket Support Event
Socket.IO event format is as follows. Pay attention to its structure when implementing. It is advisable to use the standard Client provided by Socket.IO.
42["Type",{"payload":{event body}}]
3.1 Sending Event
Event name: send
Event direction: frontend > backend
Note:
Before sending a send event, you must publish the application.
When a user sends a message (send event), the server returns the message without modification (reply event, where is_from_self = true) so that the message is acknowledged by the server and the message ID and timestamp are updated accordingly.
If you need to carry knowledge tag information, include it when obtaining the token.
Data structure:
Name
Type
Required or Not
Description
request_id
string(255)
Yes
Request ID, used to identify a request (concatenate messages, recommend using a different request_id per request).
session_id
string(64)
Yes
Session ID, used to identify a session (provided by the external system, recommend importing different session_id for different user clients, otherwise messages from different users within the same application may get mixed up).
Parameter length: 2-64 characters
Verification rule: ^[a-zA-Z0-9_-]{2,64}$. You can use uuid to generate this value.
Message content. If sending a picture, transmit the image link in markdown format, such as . The image link must be public read.
file_infos
Object array
No
File information. If you fill this field, the content field can be left blank. For data structure, refer to file_infos, dependent on real-time document parsing.
Note:
If there is no file information, this field can be left blank or set to an empty array.
custom_variables
map[string]string
No
Workflow scenario:
Custom parameters can be used to pass parameters to the API parameter field of the workflow start node. These parameters can be recognized and used by the workflow. For details, refer to the operation instructions of the start node.
The value of custom API parameters. Multiple key:value pairs can be configured, where key is the parameter name and value is the runtime value of the corresponding parameter.
Note:
The key and value types of the map are string, such as {"UserID":"10220022"}. Invalid parameters include {"UserID": 10220022}. The value can also be a json string, such as {"Data": "{\\"UserID\\":\\"10220022\\",\\"Score\\":{\\"Chinese\\":89,\\"Math\\":98}}"}
Set knowledge base search scope scenario:
Custom parameters are used to set the knowledge base search scope. If needed, input multiple parameter values separated by English vertical bars (|), for example: "user1|user2".
Note:
If you need to specify a knowledge base for retrieval in a question, you can input relevant tag values through this field. For details, refer to Set Knowledge Base Search Scope.
system_role
string(2000)
No
Role directive (Note): Use the application configuration default setting when empty, or take the current value when filled.
Maximum value limit: Different models have differences in maximum value. Refer to the ListModel API RoleLenLimit.
incremental
bool
No
Control whether the content in reply and thinking events is incrementally output. Default false.
Note:
Set this field to true to take effect only for reply and thinking events.
Reply event effect:
Thinking event effect:
search_network
string
No
Whether online search is enabled. Value ranges from...to...
empty string: follow application configuration
enable: Turn on online search
disable: Turn off online search
Note:
The value field is meaningless when online search is not enabled in application configuration.
model_name
string
No
Support importing specified models during the dialogue process. Using different model names under the same session_id maintains context correlation.
The following custom models are currently supported:
lke-deepseek-r1:DeepSeek-R1
lke-deepseek-v3:DeepSeek-V3
lke-deepseek-r1-0528:DeepSeek-R1-0528
Note:
Ensure the selected model has sufficient tokens or postpaid mode is enabled to avoid errors during the process.
stream
string
No
Whether streaming is enabled. Value ranges from...to...
empty string: follow application configuration
enable: streaming
disable: Non-streaming transmission
workflow_status
string
No
Whether workflow is enabled. Value ranges from...to...
empty string: follow application configuration (the page has no portal to configure workflow and is selected by default)
enable: Enable workflow
disable: Disable workflow
file_infos
Data structure of file information
Name
Type
Required or Not
Description
file_name
string
Yes
File Name.
file_size
string
Yes
Real-time document parsing API response file size.
file_url
string
Yes
Real-time document parsing API response file URL.
file_type
string
Yes
File type.
doc_id
string
Yes
Real-time document parsing API response doc_id.
3.2 Replying to Event
Event name: reply
Event direction: backend > frontend
Note:
If is_evil == true in the received message, it means the message hit sensitive content and failed to send.
Request ID, used to identify a request (concatenate messages, recommend using a different request_id per request).
content
string
Reply message content
file_infos
Object array
File Information
record_id
string(64)
Unique message ID
related_record_id
string(64)
Unique ID of associated messages
session_id
string(64)
Session ID, used to identify a session (provided by the external system, recommend importing different session_id for different user clients, otherwise messages from different users within the same application may get mixed up).
is_from_self
bool
Whether the message is sent by the client
can_rating
bool
Whether the message record can be evaluated
timestamp
int64
message timestamp (in seconds)
is_final
bool
Whether the message output is complete
In streaming mode, messages are returned multiple times, each time overwriting the previous answer
When is_final == true, the stop generation button hides and the like/dislike buttons appear
is_evil
bool
Whether it hits sensitive content
Note: After message uplink, sensitive content detection is first performed, and a [reply] event is returned to inform the detection result. Normal business logic processing begins only after sensitivity detection is passed.
is_llm_generated
bool
Whether the model generates content
reply_method
uint8
Response method:
1: large model reply
2: unknown question reply
3: refused question reply
4: sensitive reply
5: accepted Q&A pair precedence reply
6: welcome message reply
7: number of concurrencies exceeded reply
8: global intervention knowledge
9: task flow reply
10: task flow answer
11: search engine reply
12: polished knowledge reply
13: image understanding reply
14: real-time document reply
15: clarification confirmation reply
16: workflow reply
17: workflow operation completed
18: Intelligent Agent reply
19: multi-intent reply
knowledge
Object array
Hit knowledge
custom_params
string array
User-customized business parameters for passing through QA business parameters
Description: This field may be empty. If empty, the field does not return.
task_flow
Object
Task flow debugging information
Description: This field may be empty. If empty, the field does not return.
work_flow
Object
Workflow debugging info
Description: This field may be empty. If empty, the field does not return.
quote_infos
Object array
Quoted information.
knowledge hit data structure:
Name
Type
Description
id
string
Hit knowledge ID
type
uint32
Hit knowledge type:
1: QA
2: Document fragment
seg_id
string
Segment ID, view segment details via the DescribeSegments API
When the client sends a rating event, the client will also receive this event so that it can acknowledge the message was sent successfully.
Data structure:
Name
Type
Required or Not
Description
record_id
string(64)
Yes
Message ID (message ID of the rated reply event)
score
uint8
Yes
Score
Like
Create and bind policy Query instance Reset instance access password
reasons
string array
No
Reasons (user feedback, can have multiple)
3.5 Stop Generation Event
Event name: stop_generation
Event direction: frontend > backend
Data structure:
Name
Type
Required or Not
Description
record_id
string(64)
Yes
Message ID (message ID of the reply event message that needs to be stopped)
3.6 Reference Source Event
Event name: reference
Event direction: backend > frontend
Data structure:
Name
Type
Description
record_id
string(64)
Unique message ID
references
Object array
Reference source
Data structure of references
Name
Type
Description
id
uint64
The ID usage method is divided into two parts. See the following two examples:
1. When the reference source type is 1, 2, or 3, you can call the detail list acquisition source API to view reference source details. If needed, you can obtain corresponding parameters through the above API and concatenate them for redirection: https://lke.tencentcloud.com/preview?id=${docid}&botBizId=${appid}&page=${page number of the redirected document}&name=${name of the redirected sheet}&test=1
Note:
The id field corresponds to the ReferBizIds field in DescribeRefer
2. When the reference source type is 4, the id means multiple reference serial numbers.
type
uint32
Reference source type
1: Q&A
2: Document fragment
4: Online retrieved content
Note:
When type = 2, the granularity of the reference return is document slice dimensional data, which needs to be used with the id field. A document [doc_id] may contain multiple slices. Determine whether to show duplicates.
url
string
When type = 2, this url is the custom redirect link address set for opening the external reference link of the document.
When type = 4, this url is the source address retrieved from online search.
name
string
Reference source name
doc_id
uint64
Reference source document ID
doc_biz_id
uint64
Reference source document business ID. You can call the Document Detail API to check the basic information of the corresponding document.
doc_name
string
Reference source document name
qa_biz_id
string
Reference source QA business ID
Example:
Reference source type:
1: Q&A
2: Document fragment
Call the Tencent Cloud SDK's detail list acquisition source API to view reference source details. At this point, the id field corresponds to the ReferBizIds field in DescribeRefer. The id field corresponds to the ReferBizIds field in DescribeRefer.
Event name: reference
[
"reference",
{
"type": "reference",
"payload": {
"record_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"references": [
{
"doc_biz_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"doc_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"doc_name": "100 idioms and their historical stories.docx"
"id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"name": "100 idioms and their historical stories + (1)"
"qa_biz_id": "0",
"type": 2,
"url": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
],
"trace_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"message_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
]
3.7 Error Event
Event name: error
Event direction: backend > frontend
Data structure:
Name
Type
Description
request_id
string(255)
Request ID, used to identify a request (concatenate messages, recommend using a different request_id per request).
error
Object
Error
error data structure:
Name
Type
Description
code
uint32
Error Code
message
string
Error Message
3.8 Thinking Event
Event name: thought
Event direction: backend > frontend
Note:
This event currently only returns when using the DeepSeek-R1 model.
Data structure:
Name
Type
Description
elapsed
int
Call duration, ms
is_workflow
bool
Whether it is a workflow
procedures
Object array
Invocation process list
record_id
string(64)
Message record id for sending corresponding event
request_id
string(255)
Request id for sending corresponding event
session_id
string(64)
Session id
trace_id
string
Link id
workflow_name
string
workflow name
Data structure of procedures
Name
Type
Description
debugging
Object array
Debug process information
index
uint32
Process index
name
string
English name, one-to-one with the title field
title
string
Invocation process description, corresponding to the name field, with Chinese meanings as follows: call the knowledge base, large model reply, thinking
plugin type 0: custom plugin; 1: official plugin; 2: workflow
elapsed
uint32
Request execution time. Unit: ms.
Data structure for debugging
Name
Type
Description
content
string
Debug output
effect
Example:
[
"thought",
{
"type": "thought",
"payload": {
"elapsed": 0,
"is_workflow": false,
"procedures": [
{
"debugging": {
The user is asking about the features of DeepSeek-R1 for the third time. The previous two responses already detailed its high efficiency, long-context processing, versatility across multiple fields, security compliance, multilingual support, flexible deployment, and cost-effectiveness. Possible reasons for repeating the question include: - The user may not fully understand the previous answers and needs a more concise summary. - They might want to confirm the accuracy of the information. - They could be checking for updates. - They may be testing response consistency. - They might need the information for a specific purpose, such as a report or comparing different models. Next steps: - Verify if previous responses were comprehensive, covering aspects like training data, supported frameworks, and performance metrics. - Check if technical details (model structure, training methods, or practical applications) might be of interest.
Message does not exist or insufficient permissions
460007
Session creation failed
460008
fail to render
460009
Visitor does not exist
460010
The session does not exist or insufficient permissions
460011
Exceeding the concurrency limit
460020
Model request timeout
460021
Knowledge base not released
460022
Failed to create visitor
460023
Message like/dislike failed
460024
Invalid tag
460025
Image Analysis failed
460031
Current application connections exceed the request limit. Try again later.
460032
Insufficient balance for the current application model
460033
Application does not exist or insufficient permissions
460034
Content too long
460035
Compute content too long, stopped
460036
Process node preview parameter exception
460037
Search for resource used up, call failed
460038
The AppID request shows abnormal behavior, call failed
5. Quick Deploy
ADP-chat-client includes a complete process for establishing connections and sending/receiving messages. For detailed instructions, please refer to Integration Solution Based on the Official Open-Source Project ADP-chat-client to integrate your agent application into your own system, enabling you to embed conversational capabilities into your business workflows.
