HiLink 文件

概述

這篇文章將提供關於從 VCaaS 會議中推送的所有 Webhooks 和數據的概述。它包括兩個部分：會議結束後的會議數據推送和實時數據推送。

會議結束後的會議數據推送

說明

會議結束後，會產生相應的會議時長、與會者考勤、會議錄像（會議過程中開啟錄像）以及會議過程中的 POLL、QUIZ 記錄等數據。 VCaaS 平台提供主動推送和查詢會議數據介面兩種方式獲取會議數據。VCaaS 平台提供的會議時長和與會者考勤數據是基於客戶端連接事件產生，可能出現事件延時。

創建會議時，可以通過請求參數中的 callbackUrl 字段指定接收會議數據的回調地址。若未設置該參數，則 VCaaS 平台不會主動推送會議數據，用戶可以通過查詢會議數據介面獲取會議數據。
會議結束時，VCaaS 平台會立即進行一次會議數據的推送。若未正常接收到回調介面響應碼為200的正確響應，在間隔5分鐘、10分鐘、15分鐘、30分鐘後，VCaaS 平台會再次推送會議數據，累計推送4次後，將結束會議數據的主動推送。
接收會議數據的回調介面必須為 POST 方法，用戶需要自行實現回調介面的幂等性。
接收會議數據的回調介面示例：

/**
 * 接收會議數據的回調介面示例
 *
 * @param meetingData VCaaS 平台推送的會議數據
 */
@PostMapping(path = "/accept-meeting-data-demo")
public void acceptMeetingDataDemo(@RequestBody MeetingCompleteDataDto meetingData) {
    log.info("accept meeting data:{}", Jsons.toString(meetingData, ""));
}

示例中 MeetingCompleteDataDto 的數據結構和會議數據數據結構說明一致。

會議數據響應

{
  // 會議時長數據
  "meetingData": {
    // 會議ID
    "meetingUid": "",
    // 外部會議ID
    "meetingExternalId": "",
    // 原計劃會議開始時間
    "scheduledStartTime": "",
    // 原計劃會議結束時間
    "scheduledEndTime": "",
    // 會議實際開始時間
    "startTime": "",
    // 會議實際結束時間
    "endTime": "",
    // 會議持續時長，單位：秒
    "duration": ""
  },
  // 會議與會者考勤數據
  "attendeeDatas": [
    {
      // 會

議ID  
      "meetingUid": "",
      // 外部會議ID
      "meetingExternalId": "",
      // 與會者ID
      "attendeeUid": "",
      // 外部與會者ID
      "externalId": "",
      // 與會者首次進入會議時間
      "timeIn": "",
      // 與會者最後一次離開會議時間
      "timeOut": "",
      // 參會總時長，單位：秒
      "totalTime": "",
      // 設備
      "device": "",
      // 與會者考勤明細數據
      "details": [
        {
          // 考勤類型，AttendeeJoined：進入會議；AttendeeLeft：離開會議；AttendeeDropped：與會者掉線；
          "type": "",
          // 時間戳，單位：毫秒
          "timestamp": 0
        }
      ]
    }
  ],
  // 會議錄像數據
  "meetingVideoData": {
    // 會議ID 
    "meetingUid": "",
    // 外部會議ID 
    "meetingExternalId": "",
    // 會議錄像下載地址
    "videoUrls": [
        ""
    ]
  },
  // 會議互動數據
  "meetingInteractiveData": {
    // 會議ID 
    "meetingUid": "",
    // 外部會議ID 
    "meetingExternalId": "",
    // 答題數據
    "quizData": {
      // 使用答題器總次數   
      "totalCount": 0,
      // 答題器明細數據
      "detailDatas": [
        {
          // 題目ID  
          "id": "",
          // 題目內容和選項
          "content": {
            // 選項
            "options": [
              {
                "value": "",
                "label": ""
              }
            ],
            // 題目內容
            "content": ""
          },
          // 答題正確率
          "averageAccuracy": "",
          // 正確答案
          "correctAnswer": ""
        }
      ]
    },
    // 投票數據
    "pollData": {
      // 使用投票總次數
      "totalCount": 0,
      // 投票明細數據
      "detailDatas": [
        {
          // 投票ID
          "id": "",
          // 投票內容與選項
          "content": {
            // 選項
            "options": [
              {
                "value": "",
                "label": ""
              }
            ],
            // 內容
            "content": ""
          }
        }
      ]
    }
  },
  // 會議與會者互動數據
  "attendeeInteractiveDatas": [
    {
      // 會議ID 
      "meetingUid": "",
      // 外部會議ID 
      "meetingExternalId": "",
      // 與會者ID 
      "attendeeUid": "",
      // 外部與會者ID 
      "externalId": "",
      // 與會者答題數據
      "attendeeQuizData": {
        // 參與答題次數
        "count": 0,
        // 答題結果
        "answers": [
          {
            // 題目ID
            "id": "",
            – 與會者用戶名
            "username": "",
            – 題型
            "questionType": "",
            – 與會者選項
            "selection": ""
          }
        ]
      },
      – 與會者投票數據
      "attendeePollData": {
        – 參與投票次數
        "count": 0,
        – 投票結果
        "answers": [
          {


            – 投票ID
            "id": "",
            – 與會者用戶名
            "username": "",
            – 投票類型
            "pollType": "",
            – 投票選項
            "pollOption": {
              "value": "",
              "label": ""
            }
          }
        ]
      }
    }
  ]
}

實時數據推送

說明

客戶可以選擇接收捕獲會議中發生事件的實時回調。

在創建會議時，可以在“創建會議”請求體中設置 realTimeCallbackUrl 及其相關字段。如果未設置這些參數，VCaaS 平台將不會主動推送事件數據。
實時回調發生在以下情況下：1) 有人加入或離開會議（userJoinLeaveUrl） 2) 會議開始或結束（meetingStartEndUrl）。3) 會議開始錄製或停止錄製（recordingStartEndUrl）。每個操作都有其自己的數據格式（請參見下面的示例）。
如果 VCaaS 在操作發生時未收到正確的響應（200 狀態碼和 success 響應），它將嘗試在 15、30、180 和 1800 秒後再次共享數據。嘗試 5 次後，將停止共享數據。
回調介面必須使用 POST 方法。用戶必須確保介面能夠處理重複的數據。

可配置的參數

參數	類型	必需	備註
userJoinLeaveUrl	String	否	用戶加入和離開會議事件的回調 URL
meetingStartEndUrl	String	否	會議開始和結束事件的回調 URL
recordingStartEndUrl	String	否	會議開始錄製和停止錄製事件的回調 URL
endClassForAllUrl	String	否	老師點選 End class for all 事件的回調 URL

實時回調URL示例實現

{
    "meetingExternalId": "500000",
    "meetingTitle": "Tech meeting",
    "startTime": 1673062042,
    "endTime": 1673753242,
    // 實時回調URL
    "realTimeCallbackUrl": { 
        "userJoinLeaveUrl": "https://app.hilink.co/", 
        "meetingStartEndUrl": "https://app.hilink.co/" 
        "recordingStartEndUrl": "https://app.hilink.co/",
        "endClassForAllUrl": "https://app.hilink.co/"
    },
    "config": {
    },
    "docIds": [
    ]
}

處理實時回調 API 示例

@PostMapping(path = "/mock-callback")
public String mockCallback(@RequestBody Map<String, Object> data) {
    log.info("receive callback data: {}", data);
    // TODO: Add any additional processing logic here
    return "success";
}

實時回調數據結構

用戶進入/離開會議事件

{
    // 由 HiLink 分配的內部會議ID
    "meetingUid": "12345",
    // 客戶端分配的外部ID
    "meetingExternalId": "meeting-500000",
    // 用戶角色，0=教師，1=IT支持，2=學生
    "userRole": "0",
    // 客戶端定義的用戶ID
    "externalId": "user-1234",
    // 客戶端定義的用戶名稱
    "externalName": "",
    // 用戶活動狀態 0=用戶加入，1=用戶離開，2=用戶進入等待室
    "userStatus": "1",
    // 用戶活動的時間戳
    "timestamp": "123456"
}

會議開始/結束事件

{
    // 由 HiLink 分配的內部會議ID
    "meetingUid": "12345",
    // 客戶端分配的外部ID
    "meetingExternalId": "meeting-500000",
    // 用戶活動的時間戳
    "timestamp": "123456",
    // 0: 會議開始，1: 會議結束
    "meetingStatus": 1,
    // 0: 普通會議結束，1: 非正常會議結束（網絡錯誤）
    "meetingEndType": 0
}

會議開始/停止錄製事件

{
    // HiLink 分配的內部會議ID
    "meetingUid": "12345",
    // 客戶端分配的外部ID
    "meetingExternalId": "meeting-500000",
    // 用戶角色，0=老師，1=IT支援，2=系統關閉
    "userRole": "0",
    // 客戶端定義的用戶ID
    "externalId": "user-1234",
    // 客戶端定義的用戶名稱
    "externalName": "",
    // 錄製狀態，0=開始錄製, 1=停止錄製
    "recordingStatus": "0",
    // 用戶活動的時間戳
    "timestamp": "123456"
}

老師點選 End class for all 事件

{
    // HiLink 分配的內部會議ID
    "meetingUid": "12345",
    // 客戶端分配的外部ID
    "meetingExternalId": "meeting-500000",
    // 用戶角色，0=老師，1=IT支援
    "userRole": "0",
    // 客戶端定義的用戶ID
    "externalId": "user-1234",
    // 客戶端定義的用戶名稱
    "externalName": "",
    // 用戶活動的時間戳
    "timestamp": "123456"
}

# 概述

# 會議結束後的會議數據推送

# 說明

# 會議數據響應

# 實時數據推送

# 說明

# 可配置的參數

# 實時回調URL示例實現

# 處理實時回調 API 示例

# 實時回調數據結構

# 用戶進入/離開會議事件

# 會議開始/結束事件

# 會議開始/停止錄製事件

# 老師點選 End class for all 事件

概述