iframe

使用 iframe 將 Audio Agent 嵌入您的企業網站。當使用者造訪目標網頁時，即可載入 Agent 對話視窗，提供線上客戶支援、售前諮詢及潛在客戶資料收集等服務。

如何整合至網站

1. 前往 Agent-Integration-iframe，複製「整合程式碼」。
   
2. 將程式碼貼到網站 HTML 頁面欲嵌入的位置。
3. 發佈網站，即完成 AI Agent 嵌入並可立即開始對話。
4. 若需自訂 UI 與 LOGO、控制使用者訊息頻率或顯示主動訊息以提升互動率，可進行進階設定。

自訂 UI

此功能支援自訂小工具氣泡的大小、位置、顏色、圖示、LOGO 及名稱。

• 小工具暱稱：可自訂名稱。
• 小工具說明：可自訂描述資訊。
• 主題設定：可自訂主題色、氣泡圖示與 Agent 外觀。
• 氣泡自訂：可依據業務需求設定氣泡的顯示位置與大小。
• 對話視窗自訂：可依據業務需求設定聊天視窗的寬度與高度（為確保小螢幕相容性，建議勿設過大）。
• Agent LOGO：
  • 平台 LOGO：顯示 GPTBots 標誌。
  • 組織 LOGO：顯示企業於這裡上傳的 LOGO，組織下所有 Agent 共用。
  • 自訂 LOGO：顯示上傳的自訂 LOGO。每個 Agent 可使用不同 LOGO，需聯絡業務開通進階權限。
  • 無 LOGO：聊天視窗不顯示任何 LOGO。

安全性與速率限制

• 網域白名單：定義「小工具氣泡整合程式碼」可嵌入的網域範圍。若未啟用則無限制。
  

• 點數消耗上限：定義「小工具氣泡」的總點數消耗上限。若未啟用則無限制。
  

  • 最多可設定 3 組規則
  • 支援「每日／每週／每月」總點數消耗上限

• 使用者消耗上限：定義每位使用者的點數消耗上限。若未啟用則無限制。
  

  • 最多可設定 3 組規則
  • 支援「每日／每週／每月」每位使用者的點數消耗上限

• 使用者速率限制：定義每位使用者的訊息發送頻率上限。若未啟用則無限制。
  

  • 最多可設定 3 組規則
  • 支援依「訊息數量／時間區間」設定每位使用者的訊息發送上限
  • 超出限制時，Agent 將不再回應，並自動回覆預設訊息。

事件回呼

如何將小工具氣泡的使用者行為事件傳送至 GA4 或第三方系統

1. 建立 GA4 回呼事件，於 GA4 專案取得 Measurement Protocol API Secret 與 Measurement ID，並填入設定欄位。

2. 建立 Webhook 回呼事件，依頁面指示選擇所需事件，填寫 URL 與驗證資訊。
   

3. 在事件回呼列表中啟用回呼，並於 GA4 或 Webhook 端檢查資料是否正常。資料成功存入後，即可進行使用者數據分析。

進階用法

設定使用者 ID

1. 方式一：嵌入 iframe 時網址規則為：iframe_url+?user_id=your_user_id

   說明：此功能支援 Agent 開發者設定使用者 ID

2. 方式二：可用 JavaScript 動態設定使用者 ID

                      
                      Array.from(document.getElementsByTagName('iframe')).filter(iframe => iframe.src.includes('gptbots')).forEach(iframe => iframe.contentWindow.postMessage('{"type":"UserId","data":"your_user_id"}', '*'))

                    

設定使用者電子郵件

嵌入 iframe 時網址規則為：iframe_url+?email=somebody@mail.com
// 說明：此功能支援 Agent 開發者設定使用者電子郵件，使用者呼叫人工服務時即可免去填寫電子郵件的步驟；若未設定，則使用者發起人工服務請求時必須填寫電子郵件地址方可呼叫人工服務

設定自訂變數

支援開發者設定自訂變數的臨時變數值，於本次對話中生效，以實現 Agent 的動態邏輯與回應。
嵌入 iframe 時網址規則為：iframe_url?var_key1=value1&var_key2=value2

iframe 參數控制介面

• show_messages：控制是否顯示對話記錄
  iframe_url+?show_messages=true
• show_auto_call：是否自動開始通話
  iframe_url+?show_auto_call=true

iframe 事件監聽方法

支援透過監聽 iframe 的 postMessage 事件來取得使用者行為資料，開發者可依業務需求進行資料分析與處理。

                      
                      window.addEventListener('message', (e) => {
  let msg;
  try {
    msg = JSON.parse(e.data);
  } catch {
    return;
  }
  switch (msg.type) {
    case 'audio_conversation_id':
      console.log('audio_conversation_id', msg.data);
      // msg.data 為本次通話的 conversation id
      break;
    case 'audio_call_started':
      console.log('audio_call_started', msg.data);
      // msg.data === 'manual'（使用者主動開始）| 'auto'（自動開始）開始通話事件, 
      break;
    case 'audio_call_ended':
      console.log('audio_call_ended', msg.data);
      // msg.data === 'manual'（使用者掛斷）| 'auto'（自動結束，如逾時／斷線）結束通話事件
      break;
  }
});