跳至主要内容

REFERENCE

開發者參考

認證、API、SDK、Flow Agent 處理節點與參數取值的完整參考。

asgard.message.delta

asgard.message.delta 事件用於串流式傳送訊息內容，每個事件包含一小段文字，透過 idx 欄位來確保正確的順序。

  1. 事件特性​

    • 觸發時機：AI 生成內容時，分批傳送文字片段
    • 作用：實現即時打字機效果，提升使用者體驗
    • 頻率：一個訊息可能有多個 delta 事件

  2. 關鍵欄位​

    欄位說明
    messageDelta.message.text增量文字，包含新增的文字片段（可能是單字、詞組或句子）
    messageDelta.message.idx順序索引，從 0 開始遞增
    messageDelta.message.template通常為 null，在 complete 事件中才有值

  3. 完整範例​

    以下範例展示了一個完整訊息的打字機效果過程。假設 AI 要回應「目前台北xxx」，會分成多個 delta 事件傳送（可能是單字、詞組或句子）：

    Delta 1 (idx: 0) - 第一個片段​

    {
        "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            // ← 通常為 null
                }
            },
            "messageComplete": null
        }
    }

    Delta 2 (idx: 1) - 第二個片段​

    {
        "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
        }
    }

    Delta 3 (idx: 2) - 第三個片段​

    {
        "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
        }
    }

  4. 範例說明​

    累積效果​

    隨著 delta 事件陸續到達，前端應該這樣累積文字：

    • Delta 1 後："目前" (可能是詞組)
    • Delta 2 後："目前台" (繼續累積)
    • Delta 3 後："目前台北" (繼續累積)

    關鍵觀察點​

    1. messageId 相同：所有 delta 事件都屬於同一個訊息
    2. idx 遞增：確保正確的順序處理
    3. text 增量：每次包含新增的文字片段（可能是單字、詞組或句子）

  5. 注意事項​

    • 順序重要：必須按照 idx 順序處理
    • 累積文字：需要將所有 delta 的 text 累積、呈現像是打字機效果
    • 效能考量：頻繁更新 UI，注意效能的最佳化

準備好開始了嗎？

想知道 Asgard 怎麼用在你的團隊？跟我們聊聊。

聯絡我們