Configure Student Question Customer Callback URL
API Description
Save or update the customer address (Webhook URL) for asynchronous POST notifications from the server after a "Student Question" event, based on the account dimension. When a student sends
S_QUESTIONvia WebSocket in the chat room and the server completes storage and broadcasting, a JSON (with signature) will be pushed to this URL; the customer can then call capabilities such as the instructor's HTTP reply upon receipt. The API supports the HTTPS protocol.
API URL
https://api.polyv.net/live/v5/chat/redirect/channel/student-question-webhook/post
Request Method
POST
API Constraints
- The API supports both HTTP and HTTPS; HTTPS is recommended.
callbackUrlmust be a valid http / https full URL (validation rules are consistent with theurltype within the platform), and must be accessible by the network where the chat service resides; after successful saving, the Redis cache under the same account will be invalidated, and the next read will fetch from the database and write back to the cache.- Only one configuration is retained per account; repeated calls to this API will overwrite and update.
Request Parameter Description
| Parameter | Required | Type | Description |
|---|---|---|---|
| appId | true | String | Account appId [See details in Get Secret Key] |
| timestamp | true | Long | Current 13-digit millisecond timestamp, valid within 3 minutes |
| sign | true | String | Signature, a 32-character uppercase MD5 value. The appSecret key used to generate the signature is critical for communication data security. It must not be stored or used directly on the client side. All APIs must be called through the customer's own server to relay requests to the POLYV server for responses. [See details in Signature Generation Rules] |
| roomId | true | String | Channel ID, used to verify whether the channel belongs to the current account |
| callbackUrl | true | String | The complete URL (http or https) for the customer to receive student question notifications |
Example
Request Body JSON:
{
"roomId": "412738",
"callbackUrl": "https://your-server.example.com/api/polyv/student-question"
}
Response Body JSON (Success):
{
"code": 200,
"status": "success",
"message": "保存成功",
"data": ""
}
Response Parameter Description
| Parameter | Type | Description |
|---|---|---|
| code | Integer | 200 Success; 400 Parameter validation failed; 500 Business or service exception |
| status | String | success / fail / error |
| message | String | e.g., "Saved successfully" or error description |
| data | String | Usually an empty string on success |
After Configuration Takes Effect: Server POST Description to Customer (Not this API, for integration testing)
When a student S_QUESTION successfully, the server will initiate a POST to the saved callbackUrl, Content-Type: application/json, with main fields including:
| Field | Description |
|---|---|
| accountId | Account ID to which the channel belongs |
| roomId | Channel ID |
| questionId | Question record ID |
| sessionId | Session ID |
| viewerUserId | Viewer userId who asked the question |
| content | Question content (consistent with platform encoding rules) |
| msgType | Message type, text can be an empty string, etc. |
| askUser | Object containing display fields such as userId, nick, pic |
| timestamp | Millisecond timestamp, participates in signature |
| sign | Signature: Rules are consistent with the platform's polyvChatSign (key concatenated at both ends, middle is key+value sorted by key dictionary order, object JSON.stringify), key is polyvlog, algorithm MD5 uppercase (consistent with createApiSign('polyvlog', data)) |
The customer interface must return code: 200 (number) in the response JSON; otherwise, the server will log the notification as failed and record an error log, without retrying.
Error Examples
Parameter validation failed (e.g., callbackUrl invalid):
{
"code": 400,
"status": "fail",
"message": "…（与 checkDataType 返回一致）"
}
roomId does not match the account:
{
"code": 400,
"status": "fail",
"message": "roomId非法"
}
x-auth-user-id not provided:
{
"code": 400,
"status": "fail",
"message": "accountId is required"
}
Server exception:
{
"code": 500,
"status": "error",
"message": "unknown error"
}
(The specific message depends on the actual situation.)
