AI 通話摘要 API：逐字稿不漏頁、不混版
TL;DR — AI 通話摘要 API 與逐字稿是 2 份獨立結果。Brightalk 讓你分開輪詢、沿用
next_cursor讀完同一修訂版，再用revision更新下游（官方結果指南 2026）。
這篇從通話結果可查之後開始。若你還在處理發話、批次或自動化啟動，先看 AI 電話 API 串接指南。這裡只解決一件事：如何把目前的摘要與完整逐字稿，可靠寫回客服、QA 或 BI 系統。
最常見的錯誤，是摘要一出現就假設逐字稿也完成。另一個錯誤，是逐字稿某頁少於要求筆數，就提早結束。兩者都會留下看似成功、其實缺資料的紀錄。
AI 通話摘要 API 與逐字稿要分開判定
Brightalk 把摘要與逐字稿視為各自就緒的結果；其中一個狀態不能推論另一個（官方結果指南 2026）。因此，消費端需要兩條讀取路徑，不是一個「通話後處理完成」旗標。
摘要： 使用 calls:read 獨立查看結果狀態，適合客服摘要、搜尋與快速瀏覽。
逐字稿： 使用 transcripts:read 獨立查看結果狀態與分頁，適合 QA、稽核與分析。
只有讀摘要，就只授予 calls:read。需要逐字稿時才加 transcripts:read；兩種結果都要，才同時授予兩個 scope（官方結果指南 2026）。既有金鑰也不會自動取得逐字稿權限（官方結果指南 2026）。
痛點： 客服畫面已顯示摘要，資料工作卻把逐字稿欄位留空，並把整筆工作標成完成。後續 QA 只會看到不完整樣本。
AI 解法： 為同一通電話分別保存摘要與逐字稿狀態。兩條路徑各自輪詢、各自停止，任何一邊完成都不替另一邊作答。
預期效益： 下游能明確區分「摘要可用」與「完整逐字稿可用」。結果不再靠猜。若要把狀態接進自動任務，可搭配 Brightalk 工作流功能。
💡 權限驗收： 用只有
calls:read的測試金鑰讀摘要，再確認它不能越權讀逐字稿。需要兩種結果時，再建立具兩個 scope 的專用金鑰。
介面也要能表達兩條狀態。以下不是通話流程，而是結果消費端該保留的判斷：
| 摘要狀態 | 逐字稿狀態 | 下游處理 |
|---|---|---|
| 處理中 | 處理中 | 兩邊各自等候，不發布完整結果 |
| 已就緒 | 處理中 | 摘要可先顯示，逐字稿仍標示等候 |
| 無法提供 | 已就緒 | 保存摘要 reason，逐字稿照常讀完 |
| 已就緒 | 無法提供 | 保留摘要，逐字稿保存 reason |
這張表的重點不是預測哪邊先完成，而是不要互相封鎖。結果是否就緒彼此獨立（官方結果指南 2026）。如果客服只需要摘要，就不必等逐字稿；QA 需要完整對話，則不能因摘要完成而提早收工。
processing 是正常回應，三種結果才停止摘要輪詢
摘要尚未完成時，Brightalk API 正常回傳 HTTP 200、status: processing 與 poll_after_seconds: 5。依這個間隔再查；狀態進入 ready、unavailable 或 failed 後停止輪詢（官方結果指南 2026）。
| 摘要狀態 | 消費端動作 | 不該做的事 |
|---|---|---|
processing |
依 poll_after_seconds 稍後再查 |
當成伺服器故障 |
ready |
保存摘要與 revision |
繼續無限輪詢 |
unavailable |
保存穩定的 reason，結束輪詢 |
猜測稍後必定會有內容 |
failed |
記錄處理耗盡，結束輪詢 | 當成 HTTP 傳輸錯誤重送 |
unavailable 表示這通電話無法產生該項結果。failed 搭配 processing_failed 則表示安全處理已耗盡；這兩者是結果內容，不是 HTTP 錯誤（官方結果指南 2026）。因此，下游要保存狀態與 reason，不能只看 HTTP 200 就寫成成功。
逐字稿也要獨立輪詢。即使摘要已 ready，逐字稿仍可能尚未就緒；反過來也不能推論（官方結果指南 2026）。把兩條狀態呈現在全通路互動時間軸時，請保留這項差異。
⚠️ 別用固定秒數狂刷。 逐字稿有專用配額，組織預設為每分鐘 60 次請求（官方速率限制 2026）。收到
429後，讀取最新Retry-After，至少等待該時間並加上小幅隨機延遲（官方速率限制 2026）。
輪詢排程應以「哪一通電話、哪一個端點」為單位。摘要仍在處理，不該拖住已就緒的逐字稿；逐字稿遇到 429，也不該把它誤記成通話結果失敗。前者是內容狀態，後者是請求節流，處理方式不同。
多個輪詢工作共用配額時，等待策略也要一致。收到 429 的工作應服從最新 Retry-After，不要各自用固定間隔再次湧入。公開契約要求以回應標頭為準，不能假設所有組織或金鑰都有相同上限（官方速率限制 2026）。
逐字稿分頁要沿用 next_cursor，不能自己重組
Brightalk 的逐字稿單頁預設最多 100 輪，上限 250 輪；若先碰到回應大小預算，頁面可能提早截斷（官方逐字稿 API 2026）。所以，回傳筆數小於 limit 不代表讀完。
「單頁輪次可能少於
limit；只有next_cursor為 null 才表示分頁完成。」——官方結果指南 2026
讀取流程很短，但每一步都不能省：
- 第一個請求不帶
cursor，保存這頁的revision。 next_cursor非 null，就在下一個請求原樣送回。- 每頁持續累積對話輪次，不自行解析或修改游標。
- 只有
next_cursor為 null，才把這個修訂版標成完整（官方結果指南 2026）。
若讀取在中途暫停，請保存最後收到的 next_cursor，下次仍原樣送回。不要把游標拆成頁碼，也不要自行增加或縮短。API 把它定義為前一頁傳回的不透明游標；由伺服器決定下一頁位置（官方逐字稿 API 2026）。
完整性還需要一個發布界線。當 next_cursor 尚未變成 null，下游只能把內容視為「讀取中」。等整條游標鏈完成，再把該修訂版標成可供 QA 或 BI 使用。如此即使中途重啟，也不會把半份逐字稿當成完整資料。
游標的價值不只是翻頁。它會固定一個不可變的逐字稿修訂版；只有不帶原游標重新開始分頁，才會看到較高的 revision（官方逐字稿 API 2026）。這可避免第一頁來自舊版、後幾頁卻混入新版。
想評估雙聲道、說話者辨識或遮罩等產出品質，請另看 AI 電話轉錄稿 RFP 指南。本文不判斷逐字稿好不好，只處理如何把一個版本完整讀完。
最新版結果完成後，若要把抽樣、評分與主管回饋接起來，可再看通話品質教練閉環 SOP。
用 revision 更新下游，不要把新版混進舊分頁
讀完一個修訂版後，請保存 call_id、端點名稱與 revision。較高的 revision 表示該端點清理後的內容已更新；相同內容的重投影不會增加 revision（官方結果指南 2026）。
下游更新鍵可寫成這樣：
| 保存欄位 | 用途 | 更新判斷 |
|---|---|---|
call_id |
辨識哪一通電話 | 相同 ID 才比較結果 |
| 端點名稱 | 區分摘要與逐字稿 | 兩種資源不互相覆蓋 |
revision |
辨識內容版本 | 只在數值變高時更新 |
摘要出現較高修訂時，只更新摘要。逐字稿出現較高修訂時，則不帶舊游標，從第一頁重新開始，讀到 next_cursor 為 null，再以完整新版取代舊版。這項做法直接沿用「端點與 revision」的更新契約，以及游標固定修訂版的規則（官方結果指南 2026）。
較高修訂出現時，也不要把新頁面追加到舊逐字稿後面。先建立一份新的完整讀取，沿著新游標讀到終點，再替換下游目前版本。舊版可繼續服務查詢，直到新版完整；這是避免混版的最後一道門。
限制也要明說。API 不保證摘要與逐字稿同時完成，也不保證單頁填滿 limit。若消費端只保存一個共同狀態，或用頁面筆數猜終點，資料仍會缺漏。
把五個條件寫進 AI 通話結果 API 驗收表
正式串接前，請用測試通話逐項驗收：
| 驗收項目 | 合格條件 |
|---|---|
| 獨立就緒 | 摘要與逐字稿各自顯示狀態 |
| 最小權限 | calls:read 與 transcripts:read 按需求分開 |
| 輪詢終點 | processing 續查，三種結果狀態停止 |
| 完整分頁 | 原樣沿用游標，直到 next_cursor 為 null |
| 修訂更新 | 以 call_id、端點與 revision 判斷更新 |
速率限制也要進測試。逐字稿輪詢使用專用配額，不占一般讀取配額（官方速率限制 2026）。不要寫死一個全域上限；組織與個別金鑰可能套用不同限制，應以回應標頭為準（官方速率限制 2026）。
建議再做一輪故障驗收。先讓摘要保持 processing，確認系統依 poll_after_seconds 排程，而不是回報紅色故障。再讓逐字稿第一頁完成、第二頁中斷，確認恢復後仍沿用原 next_cursor。最後模擬較高 revision，驗證新版要重新讀完才對外可見。這些測試分別對應輪詢、游標固定與修訂更新契約（官方結果指南 2026）。
監控欄位也應服務營運判斷。至少讓值班人員看得見目前端點、結果狀態、最後 revision、是否仍有 next_cursor，以及 429 要等到何時。這些值都來自公開結果與速率契約；不必曝光金鑰，也不必把內部處理細節搬上畫面。
✅ 通過標準： 同一通測試電話能分別完成摘要與逐字稿；逐字稿不漏頁、不混版；新版結果只在
revision增加後更新。三件事缺一不可。
常見問題
摘要 ready 代表逐字稿也 ready 嗎？
不代表。兩種資源各自判定是否就緒，不能用摘要狀態推論逐字稿，或反過來推論（官方結果指南 2026）。
逐字稿一頁最多可以拿幾輪對話？
預設最多 100 輪，上限 250 輪；碰到回應大小預算時可能提早截頁，因此仍要以 next_cursor 判斷是否讀完（官方逐字稿 API 2026）。
next_cursor 可以自己解析或修改嗎？
不可以。next_cursor 非 null 時，下一個請求必須原樣送回；只有它變成 null，才表示該修訂版分頁完成（官方結果指南 2026）。
revision 變大時要怎麼更新 CRM 或 BI？
先以 call_id、端點名稱與 revision 辨認新版。摘要可獨立更新；逐字稿應不帶舊游標，從第一頁重新讀完新版（官方結果指南 2026）。
unavailable 與 failed 是 HTTP 錯誤嗎？
不是。unavailable 代表無法產生該結果；failed 搭配 processing_failed 代表安全處理已耗盡。請保存狀態與 reason（官方結果指南 2026）。
只有讀摘要也需要 transcripts:read 嗎？
不需要。摘要使用 calls:read，逐字稿使用 transcripts:read。只有整合同時需要兩種資源時，才授予兩個 scope（官方結果指南 2026）。
要把結果讀取接進日常流程，可查看 Brightalk 工作流功能與方案費率。
若你正規劃完整 AI 電話導入，回到台灣 AI 電話行銷完整指南；發話端整合則看 AI 電話 API 串接指南。