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. 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로 인증하므로 여기에는 사용자 이름이나 비밀번호가 없습니다. IP 설정은 다음 단계에서 합니다. 대신 Twilio Credential List를 쓰려면 그 username과 password를 넘깁니다. 비밀번호는 암호화되어 저장되며 API가 다시 반환하지 않습니다.

3. 03Twilio가 양방향으로 Wixzel Voice를 가리키게 하기

   Twilio는 발신과 수신을 따로 설정하며, 어느 쪽이든 빠져 있으면 아무 표시 없이 실패합니다.

   Termination의 Authentication에서 위에서 출력된 platform_ip를 IP Access Control List에 추가합니다. 이 설정이 없으면 Twilio가 약 1초 만에 hangup cause 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로 구성되며, 영어에서 가장 저렴하면서 안정적인 조합으로 분당 $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 웹훅도 발생하므로, 이를 이용해 예약을 실시간으로 자체 캘린더에 복사할 수 있습니다.

Wixzel Voice에서 이 빌드의 비용은 얼마인가요?

이 빌드에는 Wixzel Voice의 어떤 한도가 적용되나요?

• 접수원은 영업시간을 프롬프트로 압니다. v1 API에는 예약 가능 시간 엔드포인트가 없어 실제 캘린더를 볼 수 없습니다. API로 이미 예약된 시간은 거부되지만, 다른 곳에서 관리하는 예약은 알지 못합니다.
• 예약은 계정 시간대로 읽히며, 변경하지 않았다면 UTC이고 v1 API에서는 아직 바꿀 수 없습니다. 처음 들어온 예약의 date_time을 확인한 뒤에 사용하시고, 사업장이 UTC 기준이 아니라면 aqeel@wixzel.com로 연락해 주십시오.
• 계정당 기본적으로 동시에 5건의 통화를 진행할 수 있습니다. 그 이상의 통화는 하나가 끝날 때까지 거부되며, 요청하면 한도를 늘려 드립니다.
• 번호는 Twilio에 그대로 남습니다. Wixzel Voice는 번호를 판매, 이전하거나 보유하지 않습니다.
• Wixzel Voice의 동작 변경은 날짜 기반 Wixzel-Version 헤더로 구분되어 배포됩니다.