Wixzel VoiceでWebサイトに話すAIマスコットを追加する

始める前に何が必要ですか？

• クレジットのあるWixzel Voiceのアカウント。ウィジェット経由の通話は無料のテスト時間ではなく、実際のクレジットから支払われます。最低チャージ額は$5です。
• agents:writeとcalls:writeのスコープを持つAPIキー。サーバーに保管します。以下の操作はすべて、コンソールのエージェントの「マスコット」タブでも行えます。
• scriptタグを追加できる、HTTPSで配信されているWebサイト。ブラウザはHTTPSのページにしかマイクの使用を許可しません。

Wixzel Voiceでこれを構築する手順は？

1. 01Webサイトからエージェントを作る

   サイトと役割を指定します。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"で返されます。バックグラウンドでページを読み込み、プロンプトと冒頭のあいさつを書き、読み取った内容からナレッジベースを作り、ブランドカラーでマスコットを描きます。mascot.statusがreadyになるまでGET /v1/agents/{id}をポーリングしてください。通常は1分以内です。SDKではwaitForAgentがポーリングを行います。作成に失敗しても、エージェントは元の見た目のまま動きます。

   エージェントは最初Gemini Liveで動きます。エンジン、音声、プロンプトは、他のエージェントと同様にPATCH /v1/agents/{id}で変更できます。マスコットはそのまま変わりません。

2. 02ウィジェットを有効にし、通話できる相手を選ぶ

   共有は有効にするまでオフです。サイトを配信しているオリジンを列挙してください。ウィジェットはそれ以外の場所では通話を開始しません。

   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に含まれるオリジンにだけ返されます。

   4つの上限で、公開通話を予算内に収めます。1回の通話の最長時間、全員合計の1日あたりの公開通話時間（UTCの午前0時まで）、1人の訪問者が1日にかけられる通話数、同時通話数です。上の値はデフォルトです。"link": trueを追加すると、voice.wixzel.com/m?id=…の共有ページも作られます。

   レスポンスにはm_4fT9qLx2Bv8Kのようなmascot.public_idが含まれます。これがscriptタグに入れるIDです。

3. 03scriptタグを1つ貼り付ける

   マスコットを表示するすべてのページで、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（ブラウザ、OS、デバイス）、発信元のpage_url、相手が提供した情報、call_countが記録されます。1人の通話は、ブラウザが保持するランダムなIDでまとめられます。フィンガープリンティングは行わず、ウィジェットは発信者に、何があなたに共有されるかを伝えます。

   ブロックした発信者は、ウィジェット、共有リンク、アプリ、電話のいずれからも、そのエージェントに再び通話できません。各通話は文字起こしと料金とともにGET /v1/callsにも記録され、caller_idで絞り込めます。

Wixzel Voiceでこの構築にかかる費用は？

この構築に関係するWixzel Voiceの制限は？

• 音声は電話並みの音質で、双方向ともG.711 µ-law、8 kHzです。
• ウィジェットが通話を開始するのは、embed_originsに含まれるオリジン（最大20個）からだけです。
• 公開通話は、エージェントに設定した上限の範囲内に収まります。daily_minutesを超えると、UTCの午前0時まで通話は拒否されます。
• ウィジェットからの通話は、電話やアプリのセッションと合わせて、アカウントの同時通話数の上限（デフォルトは5件）に数えられます。max_concurrent_callsを設定すると、混雑したページが上限をすべて使い切るのを防げます。
• ウィジェットからの通話は実際のクレジットを使います。無料のテスト時間は、コンソールから自分のエージェントと話すためのものです。
• Web通話から人間の担当者に転送することはできません。転送には電話回線が必要です。