配置學員提問客戶回調地址

更新時間：2026-05-12 09:49:50

介面描述

按帳號維度儲存或更新「學員提問」成功後，服務端非同步 POST 通知的客戶地址（Webhook URL）。學員在聊天室透過 WebSocket 發送 S_QUESTION 且服務端完成入庫與廣播後，會向該 URL 推送一條 JSON（含簽名）；客戶可在收到後自行呼叫講師 HTTP 回覆等能力。介面支援 HTTPS 協定。

介面URL

https://api.polyv.net/live/v5/chat/redirect/channel/student-question-webhook/post

請求方式

POST

介面約束

1、介面同時支援 HTTP、HTTPS，建議使用 HTTPS。
3、**callbackUrl** 須為合法 http / https 完整地址（校驗規則與站內 url 類型一致），且需能被聊天服務所在網路存取；儲存成功後，同帳號下會失效 Redis 快取，下一次讀取走資料庫再回寫快取。
4、同一帳號僅保留一條配置；重複呼叫本介面為覆蓋更新。

請求參數描述

參數名	必選	類型	說明
appId	true	String	帳號appId【詳見取得金鑰】
timestamp	true	Long	當前13位毫秒級時間戳，3分鐘內有效
sign	true	String	簽名，為32位大寫的MD5值,`產生簽名的appSecret金鑰作為通訊資料安全的關鍵資訊，嚴禁儲存在用戶端直接使用，所有API都必須透過客戶自己伺服器中轉呼叫POLYV伺服器取得回應資料`【詳見簽名產生規則】
roomId	true	String	頻道號，用於校驗該頻道是否屬於當前帳號
callbackUrl	true	String	客戶接收學員提問通知的完整 URL（http 或 https）

範例

請求體 JSON：

{
  "roomId": "412738",
  "callbackUrl": "https://your-server.example.com/api/polyv/student-question"
}

回應體 JSON（成功）：

{
  "code": 200,
  "status": "success",
  "message": "保存成功",
  "data": ""
}

回應參數描述

參數名	類型	說明
code	Integer	200 成功；400 參數校驗失敗；500 業務或服務異常
status	String	`success` / `fail` / `error`
message	String	如「儲存成功」或錯誤說明
data	String	成功時多為空字串

配置生效後：服務端對客戶的 POST 說明（非本介面，供聯調）

當學員 S_QUESTION 成功後，服務端會向已儲存的 callbackUrl 發起 POST，**Content-Type: application/json**，主要欄位包括：

欄位名	說明
accountId	頻道所屬帳號 ID
roomId	頻道號
questionId	提問記錄 ID
sessionId	場次 ID
viewerUserId	提問觀眾 userId
content	提問正文（與站內編碼規則一致）
msgType	訊息類型，文字可為空字串等
askUser	物件，含 `userId`、`nick`、`pic` 等展示欄位
timestamp	毫秒時間戳，參與簽名
sign	簽名：規則與站內 polyvChatSign 一致（首尾拼接金鑰，中間為按 key 字典序的 `key+value`，物件 `JSON.stringify`），金鑰為 `polyvlog`，演算法 MD5 大寫（與 `createApiSign('polyvlog', data)` 一致）

客戶介面須在回應 JSON 中返回 **code: 200**（number），否則服務端記為通知失敗並打錯誤日誌，不重試。

異常範例

參數校驗失敗（如 callbackUrl 非法）：

{
  "code": 400,
  "status": "fail",
  "message": "…（与 checkDataType 返回一致）"
}

roomId 與帳號不匹配：

{
  "code": 400,
  "status": "fail",
  "message": "roomId非法"
}

未傳 x-auth-user-id：

{
  "code": 400,
  "status": "fail",
  "message": "accountId is required"
}

服務端異常：

{
  "code": 500,
  "status": "error",
  "message": "unknown error"
}

（具體 message 以實際為準。）