跳至主要内容

與 Asgard API Service 整合開發

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 Parameter​

名稱類型描述範例值
customChannelId頻道的識別 IDid123
customMessageId訊息的識別 IDid123
textstring訊息內容文字有什麼商品可以推薦嗎？
action用於重置頻道RESET_CHANNEL

Sample Payload​

{
    "customChannelId": "channelid134707djfls",
    "customMessageId": "",
    "text": "",
    "action": "RESET_CHANNEL"
}

Response​

事件類型依據前後順序，主要分成五種，彙整如下：

Event Type​

名稱描述
asgard.run.init初始化事件
asgard.message.start訊息開始
asgard.message.delta訊息持續
asgard.message.complete訊息完成
asgard.run.done事件完成

事件開始必須先初始化，才會開始訊息的傳送，訊息分成開始、持續以及完成等階段，其中訊息持續的階段，可能會有多個 delta 直至訊息完成為止，可利用 idx 來觀察訊息的次序。訊息完成後才會接續著一個事件的完成。參考 Fact 表格整理事件內的欄位如下：

Fact​

名稱描述
runInitinit回傳內容
runDonedone回傳內容
runErrorerror回傳內容
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

messageStart 範例

{
    "eventType": "asgard.message.start",
    "requestId": "6939c5a6c590d90c401e3850a1ff44f3",
    "namespace": "qa-7e301310-a594-4a7b-aa2a-xxxxxxxxxxxx",
    "botProviderName": "bpapi-d97c512f-f8dc-46f6-82f0-xxxxxxxxxxxx",
    "customChannelId": "ch-6xxxxxxxxxxxx",
    "fact": {
        "runInit": null,
        "runDone": null,
        "runError": null,
        "messageStart": {
            "message": {
                "messageId": "1834828082242916352",
                "replyToCustomMessageId": "",
                "text": "",
                "payload": {}
                "isDebug": false,
                "idx": null,
                "template": {
                    "type": "TEXT",
                    "text": ""
                }
            }
        },
        "messageDelta": null,
        "messageComplete": null
    }
}

messageDelta 範例：delta idx0

{
    "eventType": "asgard.message.delta",
    "requestId": "6939c5a6c590d90c401e3850a1ff44f3",
    "namespace": "qa-7e301310-a594-4a7b-aa2a-xxxxxxxxxxxx",
    "botProviderName": "bpapi-d97c512f-f8dc-46f6-82f0-xxxxxxxxxxxx",
    "customChannelId": "ch-6xxxxxxxxxxxx",
    "fact": {
        "runInit": null,
        "runDone": null,
        "runError": null,
        "messageStart": null,
        "messageDelta": {
            "message": {
                "messageId": "1834828082242916352",
                "replyToCustomMessageId": "",
                "text": "目前",
                "payload": null,
                "isDebug": false,
                "idx": 0,
                "template": null
            }
        },
        "messageComplete": null
    }
}

messageDelta 範例：delta idx1

{
"eventType": "asgard.message.delta",
    "requestId": "6939c5a6c590d90c401e3850a1ff44f3",
    "namespace": "qa-7e301310-a594-4a7b-aa2a-xxxxxxxxxxxx",
    "botProviderName": "bpapi-d97c512f-f8dc-46f6-82f0-xxxxxxxxxxxx",
    "customChannelId": "ch-6xxxxxxxxxxxx",
    "fact": {
        "runInit": null,
        "runDone": null,
        "runError": null,
        "messageStart": null,
        "messageDelta": {
            "message": {
                "messageId": "1834828082242916352",
                "replyToCustomMessageId": "",
                "text": "台",
                "payload": null,
                "isDebug": false,
                "idx": 1,
                "template": null
            }
        },
        "messageComplete": null
    }
}

messageDelta 範例：delta idx2

{
    "eventType": "asgard.message.delta",
    "requestId": "6939c5a6c590d90c401e3850a1ff44f3",
    "namespace": "qa-7e301310-a594-4a7b-aa2a-xxxxxxxxxxxx",
    "botProviderName": "bpapi-d97c512f-f8dc-46f6-82f0-xxxxxxxxxxxx",
    "customChannelId": "ch-6xxxxxxxxxxxx",
    "fact": {
        "runInit": null,
        "runDone": null,
        "runError": null,
        "messageStart": null,
        "messageDelta": {
            "message": {
                "messageId": "1834828082242916352",
                "replyToCustomMessageId": "",
                "text": "北",
                "payload": null,
                "isDebug": false,
                "idx": 2,
                "template": null
            }
        },
        "messageComplete": null
    }
}

messageComplete 範例

{
    "eventType": "asgard.message.complete",
    "requestId": "6939c5a6c590d90c401e3850a1ff44f3",
    "namespace": "qa-7e301310-a594-4a7b-aa2a-xxxxxxxxxxxx",
    "botProviderName": "bpapi-d97c512f-f8dc-46f6-82f0-xxxxxxxxxxxx",
    "customChannelId": "ch-6xxxxxxxxxxxx",
    "fact": {
        "runInit": null,
        "runDone": null,
        "runError": null,
        "messageStart": null,
        "messageDelta": null,
        "messageComplete": {
            "message": {
                "messageId": "1834828082242916352",
                "replyToCustomMessageId": "",
                "text": "目前台北xxx",
                "payload": {
                },
                "isDebug": false,
                "idx": null,
                "template": {
                    "type": "TEXT",
                    "text": "目前台北xxx"
                }
            }
        }
    }
}