asgard.message.delta

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

事件特性

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

關鍵欄位

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

完整範例

以下範例展示了一個完整訊息的打字機效果過程。假設 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
    }
}

範例說明

累積效果

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

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

關鍵觀察點

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

注意事項

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