HTTP SSE is a one-way communication channel. After the client initiates an HTTP request, the server continuously pushes streaming data to the client. At this point, bidirectional interaction is not supported.
Before triggering the dialogue API, you need to have a published application.
1.1 Parameter Description
Place it in the HTTP Body and send it in the form of JSON, as follows:
Name
Type
Required
Description
request_id
string(255)
No
Request ID, used to identify a request (connect messages, recommend using a different request ID per request).
For easy troubleshooting, it is required.
content
string
Yes
Message content, if sending picture, herein transmit image link in markdown format, such as , among them image link must be public read [image needs to be ingested into tcadp cos].
Maximum value limit: Different models have differences in maximum value. Refer to ListModel API InputLenLimit.
file_infos
Object array
No
File information. If you fill in this field, the content field can be empty. 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.
session_id
string(64)
Yes
Session ID, used to identify a session (provided by external system, recommend different client sessions import different session_id, otherwise messages from different users within the same application will get mixed up).
Parameter Length: 2 to 64 characters
Verification rule: ^[a-zA-Z0-9_-]{2,64}$, normally you can use uuid to generate this value
visitor ID (external input, recommend unique, indicate current integration session the user)
streaming_throttle
int32
No
Streaming reply frequency control: Controls the response packet frequency of the application. This value means how many characters the application accumulates before sending a reply packet to the caller once. A smaller value results in more frequent reply packets (smoother experience but larger traffic overhead). When no value is passed or it is 0, the system settings will be used.
Default value: 5
Recommended maximum value: 100
Note: This setting item does not accelerate the model output time, it merely changes the frequency of returning packets to the caller. Therefore, if set too high, the symptom of no packet return for a long time may occur.
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 identified and used by the workflow. For details, refer to the start node operation instructions.
Custom API parameter values. Multiple key:value pairs can be configured, where key is the name of the custom parameter and value is the corresponding runtime value of the custom parameter.
Note:
Both the key and value in the map are of string type, for example {"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}}"}
Knowledge Base Retrieval Scope Settings Scenario:
Custom parameters are used to set the search scope in the knowledge library. 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
No
Role directive (prompt content). Use the default setting in the application configuration when empty. Fill in the current value when provided.
Maximum value limit: Different models have differences in maximum value. Refer to ListModel API RoleLenLimit.
Note:
This parameter only takes effect in standard mode.
incremental
bool
No
Control whether the content in reply events and thinking events is incrementally output, default false
Note:
This field set to true only takes effect for reply and thinking events.
Reply event effect:
Thinking event effect:
model_name
string
No
Support importing specified models during the dialogue process. Using different model names under the same session_id can maintain context correlation with each other.
The following custom models are currently supported:
If is_evil == true in the received message, it means the message hit sensitive content and failed to send.
Due to concurrency overrun causing queue timeout, the "concurrency limit exceeded" error will be triggered.
Data structure:
Name
Type
Description
request_id
string(255)
Request ID, used to identify a request (connect messages, recommend using a different request ID per request).
content
string
Message content
file_infos
Object array
File information
record_id
string(64)
Unique message ID
related_record_id
string(64)
Associated unique message ID
session_id
string(64)
Session ID, used to identify a session (provided by external system, recommend different client sessions import different session_id, otherwise messages from different users within the same application will get mixed up).
is_from_self
bool
Whether the message is sent by itself
(If it is sent by itself, display on the right side of the chat box, otherwise on the left.)
can_rating
bool
Can this message record be evaluated
timestamp
int64
message timestamp (in seconds)
is_final
bool
Whether the reply event message has been output
In streaming mode, messages return multiple times, each time overwriting the previous answer.
When is_final == true, the stop generation button is hidden and the like and dislike buttons are displayed.
The reference event and reply event have no sequential relationship. Using this field as identification for message completion is not recommended.
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 sensitive content detection result. Normal business logic processing is entered only after sensitive content 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: rejected question reply
4: sensitive reply
5: accepted Q&A pair reply with precedence
6: Welcome Words reply
7: number of concurrencies exceeded reply
8: global intervention knowledge
9: Task Flow reply
10: Task Flow answer
11: Search Engine reply
12: Knowledge polished reply
13: Image understanding reply
14: Real-time document reply
15: Clarify confirm reply
16: Workflow reply
17: Workflow operation completed
18: Intelligent Agent reply
19: Multi-intent reply
knowledge
Object array
Hit knowledge
option_cards
string array
Tab, task flow proprietary
Note: This field may be empty. If empty, the field does not return.
custom_params
string array
User-customized business parameter for transparently transmitting business parameters in QA
Note: This field may be empty. If empty, the field does not return.
task_flow
Object
Task Flow Debug Information
Note: This field may be empty. If empty, the field does not return.
work_flow
Object
Workflow Debug Information
Description: This field may be empty. If empty, the field does not return.
quote_infos
Object array
Quoted information.
Data structure of knowledge in cache hit
Name
Type
Description
id
string
Hit knowledge ID
type
uint32
Hit knowledge Type:
1: Q&A
2: Document fragment
seg_id
string
Segment ID. You can view the segment description via the DescribeSegments API.
Final output of the node. json string (including ordinary string).
TaskOutput
string
Task output. (Original output)
FailMessage
string
Exception information
CostMilliSeconds
string
Total time consumed by the node. If the node has multiple calls, the duration is the sum of all calls.
Reply
string
Reply content of the current node. Current parameter extraction, message node, and end reply node may not be empty.
BelongNodeID
string
ID of the referenced node when the associated workflow is referenced. The workflow to which the task belongs is not empty when referenced.
StatisticInfo
Object
LLM statistical information
StatisticInfo LLM statistical information:
Name
Type
Description
ModelName
string
Model Name
FirstTokenCost
uint32
First token duration
TotalCost
uint32
reasoning total time
InputTokens
uint32
Input token count
OutputTokens
uint32
Output token count
TotalTokens
uint32
Input + output total tokens
quote_infos reference info data structure:
Name
Type
Description
index
int
Reference index, the subscript icon should be designed and implemented by the accessing party
position
int
position in the reply content (Chinese character, English character, and other symbol each count as one character)
Effect:
quote_infos example (here shows partial structure, abbreviated):
[
"reply",
{
"type": "reply",
"payload": {
"can_feedback": true,
"can_rating": false,
"content": "Tencent stock performance on February 13, 2025 is as follows: ### Tencent Holding (00700.HK) Hong Kong Stock Market Performance - **Stock Fluctuation**: Tencent Holding stock experienced distinct fluctuation on February 13, 2025, with an intraday amplitude of 4.35%. This reflects the short-term impact of market emotion and capital competition, as well as the long-term logic of the sector environment and company fundamentals. - **Stock Range**: Tencent stock reached a high of HKD 464.6 and a low of HKD 437 on the day. ### Tencent Holding (TCTZF.us) US Stock Market Performance - **Stock Increase**: In the US market, Tencent Holding (TCTZF.us) stock rose by 5.05% during the session on February 13, 2025, with the latest price at USD 58.10 per share. - **Market Feedback**: This unusual change drew extensive market attention, with investors starting to mine the causes for and impact behind it. Please note, the above information is for reference only. Investment is at risk, please be cautious when entering the market."
"quote_infos": [
{
"index": 1,
"position": 323
}
],
},
"message_id": "xxxxxxxxxxxxxxxxxxxxxxx"
}
]
2.2 Token Statistics Event
Event name: token_stat
Event direction: backend > frontend
Data structure:
Name
Type
Description
session_id
string(64)
Session id
request_id
string(255)
Request id for sending event
record_id
string(64)
Message record id for sending event
status_summary
string
This round conversation status. Processing: processing. Successful: success. Failed: failed.
status_summary_title
string
This round conversation status description
elapsed
int
This round call duration, ms
token_count
int
Token consumption in this round's request (when containing multiple processes, calculations will be aggregated)
procedures
Object array
Invocation process list
Data structure of the procedures calling procedure list:
Name
Type
Description
name
string
English name, one-to-one with the title field below.
The id method of use is divided into two parts. See the following two examples:
1. When the source type is 1, 2, or 3, you can call the list of details acquisition source API to view the reference details. If needed, you can obtain the corresponding parameters through the above API and navigate to: https://lke.cloud.tencent.com/preview?id=${docid}&botBizId=${appid}&page=${page number of the redirected doc document}&name=${name of the redirected sheet}&test=1
Note:
The id field corresponds to the ReferBizIds field in DescribeRefer
2. When the source type is 4, the id means the serial number of multiple reference sources.
type
uint32
reference
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, the url is a custom redirect link set for externally referenced document opening.
When type = 4, the url is the host address found in online search results.
name
string
reference source name
doc_id
uint64
reference document ID
doc_biz_id
uint64
Reference document business ID. You can call the Document Detail API to check corresponding document basic information.
doc_name
string
reference document name
qa_biz_id
string
reference QA business ID
Example 1:
reference source type is:
1: Q&A
2: Document fragment
You can call the acquisition source detail list API to view reference details. At this point, 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 Figures Stories (1).docx"
"id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"name": "100 Idioms and Their Historical Figures Stories+ (1)"
"qa_biz_id": "0",
"type": 2,
"url": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
],
"trace_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"message_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
]
Example 2:
reference source type is:
4: Online retrieved content
At this point, the [3] [4] in the content field of the received thought event or reply event represent the index of the online retrieved source in references.
"content": "As of 14:59 on February 13, 2025, the total box office of \\"Nezha 2\\" (\\"Nezha: The Devil's Birth\\") (including pre-sale)
It has exceeded **9.8 billion CNY**, just one step away from the 10 billion milestone[3][4][7][8]. This box office result has surpassed "Black Panther".
Became the only non-Hollywood movie in the top 18 of the global box office history[3][4][8]. According to Beacon Pro Edition projection, "Ne Zha 2" may finally reach **15.338 billion CNY**, while Maoyan forecast provides a higher **16.032 billion CNY**[4].
In addition, the overseas box office of the video has exceeded 6.27 million RMB.
},
"message_id": "**************************"
}
]
Event name: reference
[
"reference",
{
"type": "reference",
"payload": {
"record_id": "**************************",
"references": [
{
"doc_biz_id": "0",
"doc_id": "0",
"doc_name": "",
"id": "1",
"name": "Over 8.2 billion CNY, enters the top 31 worldwide box office rankings! Nezha 2 overseas premiere moves audience to tears, merchandise sells out in 3 days"
Request ID, used to identify a request (concatenate messages, recommend using a different request ID per request).
error
Object
Error
error: erroneous data structure
Name
Type
Description
code
uint32
Error Code
message
string
Error Message
Example:
event:reply
data:{"type":"reply","payload":{"can_rating":false,"content":"Who are you","from_avatar":"","from_name":"","is_evil":false,"is_final":true,"is_from_self":true,"is_llm_generated":false,"knowledge":null,"record_id":"83ecd23c-6283-48d0-ac5e-7d8ab604770d","related_record_id":"","reply_method":0,"request_id":"","session_id":"sse_session8","timestamp":1701330804,"trace_id":"5daf1726c254241810bb160b4c8efbed"},"message_id":"808727d6-260a-4b7f-8a70-99330feaef3f"}
event:reply
data:{"type":"reply","payload":{"can_rating":true,"content":"I am the Intelligent Agent development platform, can answer various questions and provide information.","from_avatar":"https://qbot-1251316161.cos.ap-nanjing.myqcloud.com/avatar.png","from_name":"bot","is_evil":false,"is_final":true,"is_from_self":false,"is_llm_generated":true,"knowledge":[{"id":33386,"type":1},{"id":452,"type":1},{"id":33388,"type":1}],"record_id":"7cfaf2dc-8e95-475b-9aa5-d6a5d4358f71","related_record_id":"83ecd23c-6283-48d0-ac5e-7d8ab604770d","reply_method":1,"request_id":"","session_id":"sse_session8","timestamp":1701330805,"trace_id":"5daf1726c254241810bb160b4c8efbed"},"message_id":"21b3eb5b-b0eb-4a2c-907b-2a287ad26a34"}
event:error
data:{"type":"error","error":{"code":460004,"message":"application does not exist"}}
Note:
When using the API, judge whether the value is 200. If yes, it will return normally.
2.5 Thinking About Events
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
This round call duration, ms
is_workflow
bool
Whether 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 the procedures:
Name
Type
Description
debugging
Object
Debug Process Information
index
uint32
Procedure Index
name
string
English name, one-to-one with the title field below: knowledge, task_flow, search_engine, image, large_language_model, pot_math, file, thought
title
string
Invocation process description, corresponding to the name field, with Chinese meanings as follows: call knowledge base, call task flow, call search engine, call image understanding, large model reply, call calculator, read file, thinking
Plugin type 0: custom plugin; 1: official plug-in; 2: workflow
elapsed
uint32
Current request execution time (ms)
Data structure for debugging:
Name
Type
Description
content
string
Content output during debugging
Effect:
Example:
[
"thought",
{
"type": "thought",
"payload": {
"elapsed": 0,
"is_workflow": false,
"procedures": [
{
"debugging": {
"content": "\\nThe user asked about the features of DeepSeek-R1 for the third time. In the previous two responses, I already listed its high efficiency, long-context processing, versatility across multiple fields, security compliance, multilingual support, flexible deployment, and cost-effectiveness. The user may be confirming information or hoping for a more concise or different perspective.\\n\\nI need to consider why the user repeated the question. Possible situations include: the user did not fully understand the previous response and needs a simpler summary; they want to confirm the accuracy of the information; or they are checking for updates. Additionally, the user might be testing response consistency or needs the information for specific scenarios, such as reports or comparing different models.\\n\\nNext, I should check if the previous responses were comprehensive and if any important features were missed. For example, did they mention the model's training data, supported frameworks, or specific performance metrics? The user might also be interested in technical details like model structure, training methods, or practical applications."
Message does not exist or insufficient permissions.
460007
Session creation failed
460008
Fail to render Prompt
460009
The visitor does not exist.
460010
The session does not exist or insufficient permissions.
460011
Exceed the concurrency limit
460020
Model request timeout
460021
Knowledge base not released
460022
Failed to create visitor.
460023
Failed to like or dislike the message.
460024
Invalid tag
460025
Image Analysis failed.
460031
The number of connections in this application has exceeded the request limit. Try again later.
460032
Insufficient balance in the current application model
460033
Application does not exist or insufficient permissions
460034
Content too long
460035
Content too long, already stopped
460036
Preview parameter anomaly in process node
460037
Search for resource exhausted, call failed
460038
The AppID request shows anomalous behavior, call failed
4505004
APPKEY is invalid, please verify the source of APPKEY
4. Quick Deployment
The adp-chat-client code includes a complete process for connection establishment and message sending and receiving. Refer to the integration solution based on the official open-source project ADP-chat-client for details to proceed with rapid client deployment and seamless integration of your Intelligent Agent application, embedding the dialogue feature of your Intelligent Agent application into your business system.
5. Front-End Rendering Component
If a complete client is unnecessary and only the front-end rendering component for large model reply of messages is required, you may skip downloading the frontend demo code and directly npm download:
