開始之前
伺服器端 API 金鑰以calls:read 取得摘要,以 transcripts:read
取得逐字稿。只有在整合需要兩種資源時才授予兩個 scope。既有金鑰不會
自動取得逐字稿權限。
完整通話歷史與結構化結果
GET /call-history 涵蓋組織留存的後台撥號、進線、人工通話、批次、自動化與公開 API 通話,包含已封存資料。使用 calls:read,並沿用 next_cursor 取得所有頁面。號碼檢測與沒有開始或建立時間的資料不會列入。
source 可選 ai 或 human,表示資料來源;human 也可能包含 AI 進線,不能據此判斷由誰接聽。created_after 包含時間邊界,created_before 不包含,兩者依通話開始時間篩選,缺少時使用建立時間。
每筆歷史有獨立的 id,可用 GET /call-history/{history_id} 查詢。call_id 只有對應到公開 API 執行資源時才有值;歷史 ID 不能用於取消電話。舊的 GET /calls 繼續提供可執行操作的 API 通話。
每筆歷史內的 result,以及 GET /calls/{call_id}/result,都提供相同的結構化結果:
只有
classification_status: processing 時依 poll_after_seconds 輪詢。unavailable 表示目前沒有分類,後續分析仍可能更新;缺少的歷史偵測與留言回報維持未知。人工修正會保留修正後的 outcome,並讓原 AI 分類回傳 null,原因為 manually_corrected。
MCP 對應工具為 brightalk_list_call_history、brightalk_get_call_history、brightalk_get_call_result,權限與 REST 相同。
輪詢摘要
呼叫GET /calls/{call_id}/summary。尚未完成是正常狀態:HTTP 200、
status: "processing"、poll_after_seconds: 5。狀態成為 ready、
unavailable 或 failed 後停止輪詢。
輪詢逐字稿
呼叫GET /calls/{call_id}/transcript?limit=100。摘要與逐字稿各自判定
是否就緒,不能用其中一個推論另一個。
沿用游標
next_cursor 非 null 時,下一個請求必須原樣送回。游標會固定逐字稿
修訂版本;較晚完成的對帳可以發布新修訂版本,不會改變正在讀取的舊頁面。
為了遵守回應大小上限,單頁輪次可能少於 limit;只有
next_cursor 為 null 才表示分頁完成。
偵測內容更新
儲存call_id、端點名稱與 revision。較高的 revision 表示清理後的
端點內容已更新;相同內容的重投影不會增加 revision。
處理終止狀態
unavailable 表示這通電話無法產生該結果,可查看穩定的 reason。
failed 與 processing_failed 表示安全處理已耗盡。兩者都不是 HTTP
錯誤。