指南
在行動 app 上使用
可以。小工具只是一層薄薄的用戶端,底下是普通的 HTTP API,而那個 API 沒有任何地方假設有瀏覽器——沒有 cookie、沒有重定向,JSON 進、JSON 出。iOS 或 Android app 連的是同一個 agent,同一個方案、同一份額度。沒有另外要買的行動產品,也沒有 SDK 要裝。
會變的是 app 如何證明自己是誰——在發出一個別人能拆開的二進位檔之前,這件事值得做對。
兩種接入方式,以及你要哪一種
如果你的 app 已經有後端,就用它。你的伺服器保管 site secret,簽發短效已簽署權杖;app 向你的伺服器索取,再送給我們。secret 永遠不會打包進 app,權杖幾分鐘就過期,而由你決定你的哪些使用者能取得對話。如果有得選,走這條路。
如果你的 app 沒有後端,可以改帶公開的 site 金鑰——與網站小工具同一把。先明白這代表什麼:金鑰能在任何 app 二進位檔中被提取,而且不像網站,沒有網域可以對照。你必須刻意在控制台把它打開——在網站的 Setup tab 上、Also used from a mobile app 之下。在此之前,沒有瀏覽器 origin 的請求會被拒絕。
在這種情況下,也勾選它正下方的 Require each app install to register。你的 app 首次執行時呼叫一次 /v1/install,保留傳回的 id,之後每個請求都附上它。請求會依每個已註冊的安裝做速率限制,所以被提取的金鑰不會讓某個呼叫方取得通往機器人共用額度的不受限制的路徑。代價是每個安裝多一次呼叫。
請求順序
基礎 URL 是 https://kavilo.cloud。每個請求都把憑證放在標頭裡——Authorization: Bearer <token> 或 X-Kavilo-Key: kw_pub_…。
POST /v1/install——如果你勾選了上面的設定,就在首次執行時呼叫一次。保留它傳回的installId,之後以X-Kavilo-Install送出。POST /v1/session——開啟或接續。送出{"conversationId": "…"},第一次留空。你會拿到要保留的 id、開場白、一個游標,以及目前的歷史。POST /v1/message——送出一個回合。立即回應202;回覆會透過你正在讀取的那個通道到達。POST /v1/poll——兩種接收回覆的方式之一。送出你的游標,拿到任何新的內容。最多等 25 秒才回空,所以這樣輪迴就是長輪詢,不是忙等。GET /v1/stream——輪詢的替代方案:以 server-sent events 接收相同的幀。POST /v1/end——訪客結束了。送出逐字稿並關閉對話。
Poll 和 stream 透過同一個游標讀取同一個緩衝區,所以你可以在對話中途切換、什麼都不損失。在手機上,poll 通常是兩者中比較簡單的那個:網路切換不需要特別處理就能撐過去,而且用戶閱讀時它不會一直佔著一個 socket。
讀取回覆
每個幀有 seq、kind,通常還有 text。每收到一個 token 幀就附加上去。回合以 final 結束,它帶著完整答覆——以它為準、取代你累積的內容,這樣重連就不會讓你把同一則回覆顯示兩遍。回合也可能以 error 結束。這兩種是唯一的結束方式;沒有另一個「done」幀要等。
一則訊息不一定對應一則回覆。如果訪客在 agent 還在回答時送了第二則,它會被併進同一個回合。一個 app 如果阻塞到「每則訊息數到一則回覆」為止,遲早會掛住;改成讀到 final 為止。
退到背景
靜默十五分鐘的對話會被關閉,逐字稿也會送出——與 web 上相同的規則:在 web 上,訪客關閉分頁和起身去泡茶看起來一模一樣。手機一進入睡眠就很容易超過那條線。
所以回到前景時,用你儲存的 id 再呼叫一次 /v1/session。如果對話還開著,你接續下去;如果它被關閉了,你會拿到一個新的;兩種情況,回應都會給你歷史讓你重畫。把這個呼叫當作畫面載入的方式,而不是錯誤處理。
還沒有的東西
附件。聊天 API 沒有上傳端點,無論 app 還是 web 都沒有,所以訪客沒辦法傳一張壞掉零件的照片給你。如果你的 app 正是為此而做,告訴我們——真的有人需要時,它會往前排。
從這裡開始
向我們索取參考用戶端,我們會把整套流程用 Swift 和 Kotlin 寄給你——各自約一百行,短到可以直接讀、而不必只能相信。寫信到 hello@kavilo.cloud,並說明你在哪個平台。