跳至主要内容

REFERENCE

SDK 範例

@asgard-js/core 與 @asgard-js/react 的用法與可以直接操作的範例。

預載訊息（initMessages）

initMessages 讓你在 chatbot 初始化時帶入一組預設的對話歷史，使用者開啟 chatbot 時便已有對話內容。常見用途：

  • 展示範例對話
  • 從後端載入歷史訊息
  • 引導式開場白
搭配 autoResetChannel={false}，且僅對「尚不存在」的 channel 有效

要讓 initMessages 保留下來，請搭配 autoResetChannel={false}：

<Chatbot
  initMessages={messages}
  autoResetChannel={false}
  ...
/>

0.3.x 起 mount 會先查 channel metadata：若後端已存在該 customChannelId，會一律還原並重播 server 歷史，initMessages 會被覆蓋（不受 autoResetChannel 影響）。因此 initMessages 最適合搭配一個後端尚未建立的 customChannelId（純客戶端預載）。詳見 自動重置 Channel。

  1. 說明​

  2. 型別​

    initMessages 接受 ConversationMessage[]，每則訊息為下列聯合型別之一：

    import type { ConversationMessage } from "@asgard-js/core";
    // ConversationMessage = ConversationUserMessage | ConversationBotMessage | ...

    使用者訊息​

    import type { ConversationUserMessage } from "@asgard-js/core";
     
    const userMsg: ConversationUserMessage = {
      type: "user",
      messageId: "msg-1",       // 每則訊息的唯一 ID
      text: "你好！",
      blobIds: [],
      time: new Date("2026-01-01T10:00:00"),
    };

    Bot 訊息​

    Bot 訊息需要提供完整的 message 物件（對應 SSE 回傳的訊息結構）：

    import { EventType, MessageTemplateType } from "@asgard-js/core";
    import type { ConversationBotMessage } from "@asgard-js/core";
     
    const botMsg: ConversationBotMessage = {
      type: "bot",
      messageId: "msg-2",
      eventType: EventType.MESSAGE_COMPLETE,   // 標記為已完成的訊息
      isTyping: false,
      typingText: null,
      message: {
        messageId: "msg-2",
        replyToCustomMessageId: "",
        text: "你好！有什麼可以幫你的嗎？",
        payload: null,
        isDebug: false,
        idx: 0,
        template: {
          type: MessageTemplateType.TEXT,
          text: "你好！有什麼可以幫你的嗎？",
          quickReplies: [],
        },
      },
      time: new Date("2026-01-01T10:00:05"),
      raw: "",
    };

  3. 完整範例（Next.js App Router）​

    "use client";
     
    import dynamic from "next/dynamic";
    import "@asgard-js/react/style";
    import { useMemo } from "react";
    import { EventType, MessageTemplateType } from "@asgard-js/core";
    import type { ConversationMessage } from "@asgard-js/core";
     
    const Chatbot = dynamic(
      () => import("@asgard-js/react").then((m) => m.Chatbot),
      { ssr: false },
    );
     
    function makeBotMessage(
      id: string,
      text: string,
      time: Date,
    ): ConversationMessage {
      return {
        type: "bot",
        messageId: id,
        eventType: EventType.MESSAGE_COMPLETE,
        isTyping: false,
        typingText: null,
        message: {
          messageId: id,
          replyToCustomMessageId: "",
          text,
          payload: null,
          isDebug: false,
          idx: 0,
          template: {
            type: MessageTemplateType.TEXT,
            text,
            quickReplies: [],
          },
        },
        time,
        raw: "",
      };
    }
     
    export default function ChatPage() {
      const initMessages = useMemo<ConversationMessage[]>(
        () => [
          {
            type: "user",
            messageId: "pre-1",
            text: "你好！",
            blobIds: [],
            time: new Date("2026-01-01T10:00:00"),
          },
          makeBotMessage(
            "pre-2",
            "你好！有什麼可以幫你的嗎？",
            new Date("2026-01-01T10:00:05"),
          ),
        ],
        [],
      );
     
      return (
        <div style={{ height: "100vh" }}>
          <Chatbot
            title="My Chatbot"
            customChannelId="user-123"
            config={{
              botProviderEndpoint:
                "https://api.asgard-ai.com/ns/{namespace}/bot-provider/{botProviderId}",
            }}
            initMessages={initMessages}
            autoResetChannel={false}
          />
        </div>
      );
    }
    備註

    useMemo 確保 initMessages 陣列在重新渲染時保持穩定參考，避免不必要的 channel 重置。

  4. 延伸閱讀​

準備好開始了嗎？

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

聯絡我們