Receiving Callback
With this callback, you can listen to events that occur during user conversations with the agent, including ASR results, LLM results, exception events, agent interruption events, user speaking actions, agent speaking actions, and user speaking audio data.
To receive different types of callback results, configure the corresponding CallbackConfig parameter to 1 when creating an agent instance:
- ASR results:
CallbackConfig.ASRResult - LLM results:
CallbackConfig.LLMResult - Agent interruption events:
CallbackConfig.Interrupted - User speaking actions:
CallbackConfig.UserSpeakAction - Agent speaking actions:
CallbackConfig.AgentSpeakAction - User speaking audio data:
CallbackConfig.UserAudioData
Callback Description
- Request method: POST.
NoteThe callback data format is JSON. You need to perform UrlDecode decoding on it.
- Request URL: Please contact ZEGOCLOUD Technical Support for configuration.
- Transmission protocol: HTTPS/HTTP, it is recommended to use HTTPS.
Callback Parameters
| Parameter | Type | Description |
|---|---|---|
| AppId | Number | The unique identifier for the developer's APP provided by ZEGOCLOUD. |
| Event | String | Notification type of event.
|
| Nonce | String | A random number used for signature calculation. |
| Timestamp | Number | Unix timestamp (in milliseconds) when the callback was sent, used for signature calculation. |
| Signature | String | Verification string to confirm the identity of the sender of the callback. |
| AgentInstanceId | String | The unique identifier for the AI agent instance. |
| AgentUserId | String | The user ID of the AI agent. |
| RoomId | String | The room ID. |
| Sequence | Number | The sequence number of the callback, ensuring orderliness but not necessarily continuity. |
| Data | Object | Detailed information about the event. For details, see Data. |
Data
Depending on the different values of Event, the parameters included in Data are different.
Callback Examples
Below are callback examples for each Event type.
Signature Verification
To enhance data security, developers should perform local signature calculations when receiving callbacks from the ZEGOCLOUD server, and compare them with the provided signature to determine if the request is legitimate.
The verification process is as follows:
Sort the three parameters callbacksecret, timestamp, and nonce in dictionary order
Concatenate the sorted callbacksecret, timestamp, and nonce into a string and calculate SHA1
Compare the calculated hash string with signature, if they match, the request is from ZEGOCLOUD
The parameters are described as follows:
| Parameter | Description |
|---|---|
| callbacksecret | Server verification key. Generated when registering a project in the ZEGOCLOUD Console. You can view it in "Console > Project Configuration > Project Information > Configuration Information". |
| timestamp | Unix timestamp. |
| nonce | Random number. |
Return Response
After you receive the callback, please return an HTTP status code of 2XX (e.g., 200) to indicate successful receipt. Any other response will be considered a failure.
Callback Retry Policy
If the ZEGOCLOUD server does not receive a response, or if the received HTTP status code is not 2XX (e.g., 200), it will attempt to retry, with a maximum of 5 retries. The interval between each retry request and the previous request will be 2s, 4s, 8s, 16s, and 32s respectively. If the 5th retry still fails, no further retries will be attempted, and the callback will be lost.