用 Wixzel Voice 在您的網站加入會說話的 AI 吉祥物

開始之前需要準備什麼？

• 一個有點數的 Wixzel Voice 帳號。透過小工具的通話使用真實點數，而不是免費測試分鐘數；最低儲值金額為 $5。
• 一把具有 agents:write 和 calls:write 權限範圍的 API 金鑰，保存在您的伺服器上。以下所有步驟也都能在主控台中該代理的「吉祥物」分頁完成。
• 一個以 HTTPS 提供、可加入 script 標籤的網站。瀏覽器只會在 HTTPS 下讓網頁使用麥克風。

如何在 Wixzel Voice 上逐步打造？

1. 01用您的網站建立代理

   提供您的網站和角色。role 可以是 receptionist、support、sales、guide，或您自己的描述：

   shell複製

   curl https://api.voice.wixzel.com/v1/agents/generate \
     -H "Authorization: Bearer $WIXZEL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "website_url": "https://smiledental.example", "role": "receptionist" }'

   make-agent.mjs (TypeScript SDK)複製

   import { WixzelVoice, waitForAgent } from 'wixzel-voice';
   
   const client = new WixzelVoice({ apiKey: process.env.WIXZEL_API_KEY });
   
   let agent = await client.agents.generate({
     website_url: 'https://smiledental.example',
     role: 'receptionist',
   });
   agent = await waitForAgent(client.agents, agent); // until the mascot is ready or failed
   console.log(agent.id, agent.name, agent.mascot.status, agent.knowledge_base_id);

   它會立即回應一個已經能對話的代理，並帶有 mascot.status: "building"。它會在背景讀取您的網頁、撰寫提示詞和開場白、用讀到的內容建立知識庫，並以您的品牌色彩繪製吉祥物。輪詢 GET /v1/agents/{id} 直到 mascot.status 變為 ready，通常不到一分鐘；在 SDK 中由 waitForAgent 負責輪詢。建置失敗時，代理仍可正常運作，並保持原本的外觀。

   代理一開始使用 Gemini Live。和其他代理一樣，可用 PATCH /v1/agents/{id} 更改其引擎、語音或提示詞；吉祥物則維持不變。

2. 02開啟小工具，並選擇誰可以撥打

   分享預設為關閉，需要您自行開啟。列出您網站使用的來源（origin）；小工具在其他任何地方都不會發起通話：

   shell複製

   curl -X PATCH https://api.voice.wixzel.com/v1/agents/AGENT_ID/mascot \
     -H "Authorization: Bearer $WIXZEL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "welcome_message": "Hi! I am Molly from Smile Dental. Tap Call to talk to me.",
       "sharing": {
         "embed": true,
         "embed_origins": ["https://smiledental.example", "https://www.smiledental.example"],
         "caller_info": "contact",
         "max_call_seconds": 300,
         "daily_minutes": 60,
         "calls_per_visitor_daily": 3,
         "max_concurrent_calls": 2
       }
     }'

   caller_info 是訪客通話前需提供的資料：none（預設）不需要任何資料，contact 要求姓名以及電話號碼或電子郵件，google 要求以 Google 登入。Google 登入能讓您知道對方是誰，但絕不會為對方建立 Wixzel 帳號；在您的網站上，它會在 voice.wixzel.com 的小視窗中開啟，並只將結果交回 embed_origins 中的來源。

   四項上限讓公開通話維持在預算內：單通最長時間、所有人合計的每日公開分鐘數（至 UTC 午夜為止）、每位訪客每日可撥打的次數，以及同時通話數。上方的值就是預設值。加入 "link": true 還能取得位於 voice.wixzel.com/m?id=… 的分享頁面。

   回應中帶有 mascot.public_id，例如 m_4fT9qLx2Bv8K。它就是 script 標籤中的 id。

3. 03貼上一個 script 標籤

   將以下內容加到每個要顯示吉祥物的頁面，放在 body 結束標籤之前：

   index.html複製

   <script src="https://voice.wixzel.com/embed.js" data-mascot="m_4fT9qLx2Bv8K" async></script>

   吉祥物會帶著歡迎訊息在右下角等待。訪客點一下「Call」按鈕、允許使用麥克風並開始說話；吉祥物會聆聽、思考，並隨代理的語音動嘴。小工具在 shadow root 中執行，因此您的 CSS 和它的 CSS 互不影響。

4. 04自行指定位置，並讓代理在您的頁面上執行動作

   若要顯示在您自己的元素中而不是角落，請在標籤中省略 data-mascot，並在指令碼載入後呼叫 WixzelMascot.mount。

   用戶端工具會在代理要求時於您的頁面上執行，例如開啟預約頁面。先在主控台或用 POST /v1/tools 為代理建立該工具，再註冊它要做的事，在指令碼載入前後皆可：

   index.html複製

   <div id="talk"></div>
   <script>
     window.WixzelMascot = Object.assign(window.WixzelMascot || {}, {
       tools: {
         open_page: ({ path }) => {
           location.href = path;
           return { opened: path };
         },
       },
     });
   </script>
   <script
     src="https://voice.wixzel.com/embed.js"
     async
     onload="WixzelMascot.mount(document.getElementById('talk'), { mascot: 'm_4fT9qLx2Bv8K' })"
   ></script>

   處理函式回傳的任何內容都會交回給代理，由代理告訴來電者。呼叫您伺服器的 webhook 工具，在小工具上也能使用。

5. 05查看誰撥打過，並封鎖某人

   每通小工具通話都會記錄來電者。列出某個代理的來電者：

   shell複製

   curl "https://api.voice.wixzel.com/v1/callers?agent_id=AGENT_ID&limit=20" \
     -H "Authorization: Bearer $WIXZEL_API_KEY"
   
   curl -X PATCH https://api.voice.wixzel.com/v1/callers/CALLER_ID \
     -H "Authorization: Bearer $WIXZEL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "blocked": true }'

   每位來電者都有大致的 location（城市、地區和國家，由 IP 位址推算，IP 只以雜湊值保存）、platform（瀏覽器、作業系統和裝置）、撥打時所在的 page_url、對方提供給您的資料，以及 call_count。瀏覽器保存的一個隨機 id 會將同一人的通話歸為一組；不使用指紋辨識，且小工具會告知來電者哪些資料會分享給您。

   被封鎖的來電者無法再透過小工具、分享連結、應用程式或電話撥打該代理。每通電話也會出現在 GET /v1/calls 中，附逐字稿和費用，並可依 caller_id 篩選。

在 Wixzel Voice 上打造這個要花多少錢？

這個實作適用哪些 Wixzel Voice 限制？

• 音質為電話等級，雙向皆為 8 kHz 的 G.711 µ-law。
• 小工具只會從 embed_origins 中的來源發起通話，最多 20 個。
• 公開通話受代理上設定的上限約束。超過 daily_minutes 後，通話會被拒絕，直到 UTC 午夜。
• 小工具通話與電話通話、應用程式工作階段一起計入帳號的同時通話上限，預設五通。max_concurrent_calls 可避免單一熱門頁面佔用全部名額。
• 小工具通話使用真實點數。免費測試分鐘數是用於從主控台與您自己的代理對話。
• 網頁通話無法轉接給真人；轉接需要電話線路。