Asgard API Reference
Server-Sent Events
伺服器傳送事件 (Server-Sent Events) 的端點 (Endpoint) 是客戶端 (Client Side) 與伺服器傳送事件建立連結的介面,用於接收從伺服器 (Server) 發出的訊息 (Messages) 和事件 (Events)。
這些訊息包含各種內容,例如 Agent 或 Bot 發送的訊息、系統事件、終端用戶訊息等。一旦呼叫了端點,瀏覽器就會保持連線開啟並接收來自伺服器的事件。
URI
{{base_url}}/generic/ns/{{namespace}}/bot-provider/{{bot_provider_name}}/message/sse
HTTP Method
POST
Headers
X-Asgard-Webhook-Token
Request Parameters
名稱 | 類型 | 描述 | 範例值 |
---|---|---|---|
customChannelId | string | 聊天頻道 ID,可自訂。同一頻道 ID 才會記憶對話內容。 | channelid123 |
customMessageId | string | 訊息 ID,可自訂或留空,便於追蹤與除錯。 | msgid123 |
text | string | 輸入的訊息內容。 | 有什麼商品可以推薦嗎? |
action | string | 命令方法,常用值為 RESET_CHANNEL (初始化)與 NONE (一般訊息)。 | RESET_CHANNEL |
Sample Payload
{
"customChannelId": "channelid134707djfls",
"customMessageId": "",
"text": "",
"action": "RESET_CHANNEL"
}
實際應用範例
想了解如何在實務上傳送對話指令?
請參考下方的請求操作教學,內含完整 JSON 範例與應用說明:
Response
事件類型依據前後順序,主要分成五種,彙整如下:
Event Types
名稱 | 描述 |
---|---|
asgard.run.init | SSE 服務初始化事件 |
asgard.message.start | 對話的起始(可能包含初始文字) |
asgard.message.delta | 對話的內容更新(打字機效果,逐字傳送) |
asgard.message.complete | 對話的結束(完整文字 + Template 格式) |
asgard.run.done | SSE 服務事件完成 |
事件開始必須先初始化,才會開始訊息的傳送,訊息分成開始、持續以及完成等階段,其中訊息持續的階段,可能會有多個 delta 直至訊息完成為止,可利用 idx 來觀察訊息的次序。訊息完成後才會接續著一個事件的完成。
事件流程圖
Fact Fields
參考Fact 表格整理事件內的欄位如下:
名稱 | 描述 |
---|---|
runInit | init 回傳內容 |
runDone | done 回傳內容 |
runError | error 回傳內容 |
messageStart | 訊息的開始,message 物件支援欄位有: messageId, replyToCustomMessageId, text, payload, isDebug, idx, template |
messageDelta | 訊息的疊加,message 物件支援欄位有: messageId, replyToCustomMessageId, text, payload, isDebug, idx, template(省略為 null) idx 為識別該段訊息的次序,參考底下 Delta 範例。 |
messageComplete | 訊息的完成,message 物件支援欄位有: messageId, replyToCustomMessageId, text, payload, isDebug, idx, template |
延伸資源
Message Template
message 物件的 template
欄位提供了前端公版的渲染資料物件,詳細可參考:
- Message Template 完整說明 - 了解如何處理模板資料