Wixzel VoiceとNode.jsでTwilioのAI受付を作る

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

• Elastic SIP Trunkingが使えるTwilioアカウントと、Twilioの電話番号。
• Wixzel VoiceのAPIキー（wv_live_…）と、アカウントのクレジット。最低チャージ額は$5です。
• Node.js 20以降。

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

1. 01TwilioでElastic SIPトランクを作成する

   Twilioのコンソールで「Elastic SIP Trunking」を開き、トランクを作成します。「Termination」で、your-clinic.pstn.twilio.comのような「Termination SIP URI」を決めます。このホスト名が、次の手順で接続するトランクのhostになります。

   Twilioのコンソールは開いたままにしておいてください。APIから入力用の2つのアドレスを受け取ったら、また戻ってきます。

2. 02SDKをインストールしてトランクを接続する

   SDKをインストールし、APIキーを環境変数に設定します。

   shellコピー

   npm install wixzel-voice
   export WIXZEL_API_KEY="wv_live_..."

   trunk.mjsコピー

   import { WixzelVoice } from 'wixzel-voice';
   
   const client = new WixzelVoice({ apiKey: process.env.WIXZEL_API_KEY });
   
   const trunk = await client.sipTrunks.create({
     name: 'Twilio',
     host: 'your-clinic.pstn.twilio.com', // your Termination SIP URI
     port: 5060,
     transport: 'udp',
   });
   
   console.log('TRUNK_ID', trunk.id);
   console.log('Allowlist at Twilio:', trunk.platform_ip);
   console.log('Origination URI:', trunk.origination_uri);

   ここでユーザー名とパスワードを指定しないのは、Twilioが送信元IPで認証するためです（次の手順で設定します）。代わりにTwilioの「Credential List」を使う場合は、そのusernameとpasswordを渡してください。パスワードは暗号化して保存され、APIから再び返されることはありません。

3. 03TwilioをWixzel Voiceに向ける（発信と着信の両方）

   Twilioでは発信と着信を別々に設定します。どちらかが欠けていても、エラーは表示されずに失敗します。

   「Termination」の「Authentication」で、上で出力されたplatform_ipを「IP Access Control List」に追加します。これがないと、Twilioは約1秒で通話を拒否し、切断原因21を返します。

   「Origination」で、上で出力されたorigination_uriを「Origination SIP URI」として追加します。これがないと、番号への着信はエージェントに届かず、通話がTwilioの外に出ないため、どちらのログにも何も記録されません。

   最後に、「Numbers」でTwilioの番号をこのトランクに割り当てます。

4. 04受付エージェントを作成する

   エージェントは、プロンプト、冒頭のあいさつ、音声エンジンで構成されます。appointment_booking_enabledを有効にすると、通話中に予約の一覧、登録、キャンセルができるようになります。提示してよい曜日、時間帯、枠の長さはプロンプトで指示します。

   agent.mjsコピー

   import { WixzelVoice } from 'wixzel-voice';
   
   const client = new WixzelVoice({ apiKey: process.env.WIXZEL_API_KEY });
   
   const agent = await client.agents.create({
     name: 'Reception',
     system_prompt: [
       'You are the receptionist for Riverside Dental, answering the phone.',
       'Keep every reply to one or two short sentences, and never read out lists.',
       'You can book, move and cancel check-ups and cleanings.',
       'Offer appointments Monday to Friday, 09:00 to 17:00, 30 minutes each.',
       'Before booking, ask for the full name of the caller and repeat the day and time back.',
       'For a dental emergency, tell the caller to hang up and ring the emergency number.',
       'If you cannot help, take a message and promise a callback.',
     ].join('\n'),
     opening_message: 'Riverside Dental, this is the automated assistant. How can I help?',
     appointment_booking_enabled: true,
     voice: {
       stt: { model: 'deepgram/nova-3', language: 'en-US' },
       llm: { model: 'openrouter/gpt-4o-mini' },
       tts: { model: 'elevenlabs/eleven_flash_v2_5' },
     },
   });
   
   console.log('AGENT_ID', agent.id);

   これはclassicエンジンです。Deepgram Nova-3、GPT-4o-mini、ElevenLabs Flash v2.5の組み合わせで、英語向けの信頼できる構成の中では最も安く、1分あたり$0.0867です。話者を選ぶにはttsブロックにvoiceを追加します。使える音声はclient.engines.voices('classic')で一覧できます。

   冒頭のあいさつでは、相手が自動アシスタントと話していることを伝えています。法律でその告知や通話録音の告知が求められる場合は、冒頭のあいさつに入れるのが適切です。

5. 05番号を受付エージェントにつなぐ

   トランクに番号を登録し、応答するエージェントを指定します。

   number.mjsコピー

   import { WixzelVoice } from 'wixzel-voice';
   
   const client = new WixzelVoice({ apiKey: process.env.WIXZEL_API_KEY });
   
   const number = await client.phoneNumbers.create({
     phone_number: '+14155550100', // your Twilio number, in E.164
     sip_trunk_id: process.env.TRUNK_ID,
     inbound_agent_id: process.env.AGENT_ID,
   });
   
   console.log('NUMBER_ID', number.id);

   inbound_agent_idがない番号への着信は拒否されます。同じエージェントにリマインダーやテスト通話の発信もさせるには、client.agents.update(agentId, { outbound_phone_number_id: number.id })でその番号を発信者番号に設定します。

6. 06電話をかけて、通話と予約を確認する

   携帯電話からTwilioの番号に電話をかけ、枠を予約します。電話を切ると、通話と予約の両方がAPIに記録されています。

   results.mjsコピー

   import { WixzelVoice } from 'wixzel-voice';
   
   const client = new WixzelVoice({ apiKey: process.env.WIXZEL_API_KEY });
   
   // Lists are newest first.
   const calls = await client.calls.list({ direction: 'inbound', limit: 1 });
   const latest = calls.data[0];
   if (latest) {
     const call = await client.calls.retrieve(latest.id);
     console.log(call.status, call.duration_seconds + 's', (call.cost_micros ?? 0) / 1e6, 'USD');
     for (const line of call.transcript) console.log(line.role + ': ' + line.content);
   }
   
   const appointments = await client.appointments.list({ limit: 5 });
   for (const a of appointments.data) {
     console.log(a.date_time, a.client_name, a.phone_number, a.status);
   }

   date_timeは常にUTCです。予約ごとにappointmentBooked Webhookも送信されるので、これを使えば予約が入った時点で自社のカレンダーにコピーできます。

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

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

• 受付エージェントは営業時間をプロンプトから知ります。v1 APIには空き状況のエンドポイントがないため、実際のカレンダーは参照できません。APIですでに予約された時間は拒否されますが、他の場所で管理している予約はエージェントからは見えません。
• 予約はアカウントのタイムゾーンで読み取られます。変更していない限りUTCで、v1 APIではまだ変更できません。最初の数件の予約のdate_timeを確認してから運用し、事業がUTCで動いていない場合はaqeel@wixzel.comまでご連絡ください。
• デフォルトでは、1アカウントあたり同時に5件まで通話できます。それ以上の通話は1件終わるまで拒否されます。上限は申請により引き上げられます。
• 番号はTwilioに残ります。Wixzel Voiceは電話番号の販売、ポーティング、保有を行いません。
• Wixzel Voiceの動作の変更は、日付付きのWixzel-Versionヘッダーで切り替える形でリリースされます。