Wixzel Voice API로 실제 전화 통화에 Gemini Live 연결하기

시작하기 전에 무엇이 필요한가요?

• 크레딧이 있는 Wixzel Voice API 키. 최소 충전 금액은 $5입니다.
• 통신사의 SIP 트렁크와, 통신사가 발신자 번호로 표시하도록 허용한 번호.
• curl, jq, uuidgen.

Wixzel Voice에서 단계별로 어떻게 만드나요?

1. 01SIP 트렁크 연결하기

   키와 API 기본 주소를 한 번 설정한 뒤 트렁크를 만듭니다. ID 외에도 두 값이 필요하므로 tee로 전체 응답을 저장합니다.

   shell복사

   export WIXZEL_API_KEY="wv_live_..."
   API=https://api.voice.wixzel.com/v1
   
   TRUNK_ID=$(curl -s $API/sip-trunks \
     -H "Authorization: Bearer $WIXZEL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "My carrier",
       "host": "sip.your-carrier.example",
       "username": "your-sip-username",
       "password": "your-sip-password"
     }' | tee trunk.json | jq -r .id)
   
   jq -r '.platform_ip, .origination_uri' trunk.json

   통신사가 IP로 인증한다면 username과 password는 빼십시오. 어느 경우든 통신사에서 platform_ip를 허용 목록에 추가해 플랫폼에서 오는 통화를 받게 해야 합니다. origination_uri는 통신사가 수신 통화를 보낼 주소이며, 이 가이드에서는 필요하지 않습니다.

2. 02발신에 쓸 번호 등록하기

   직접 보유한 번호를 E.164 형식으로 사용합니다.

   shell복사

   NUMBER_ID=$(jq -n --arg trunk "$TRUNK_ID" \
     '{phone_number: "+14155550100", sip_trunk_id: $trunk}' |
     curl -s $API/phone-numbers \
       -H "Authorization: Bearer $WIXZEL_API_KEY" \
       -H "Content-Type: application/json" \
       -d @- | jq -r .id)

3. 03Gemini Live 에이전트 만들기

   음성은 세 단계가 아니라 실시간 모델 하나입니다.

   shell복사

   AGENT_ID=$(jq -n --arg number "$NUMBER_ID" '{
       name: "Gemini Live",
       system_prompt: "You are a friendly assistant on a phone call. Keep answers to one or two sentences.",
       opening_message: "Hi, this is an automated assistant. Do you have a minute?",
       outbound_phone_number_id: $number,
       voice: { realtime: { model: "google/gemini-live", voice: "Charon" } }
     }' |
     curl -s $API/agents \
       -H "Authorization: Bearer $WIXZEL_API_KEY" \
       -H "Content-Type: application/json" \
       -d @- | jq -r .id)

   voice.realtime은 듣기, 추론, 말하기로 이루어진 대화 턴 전체를 Gemini Live에 맡기므로 stt, llm, tts 블록이 없습니다. 두 구성을 모두 지정한 음성은 API가 거부합니다. Charon은 Gemini의 기본 제공 음성 중 하나이며, GET /v1/engines/gemini_live/voices가 Google의 한 단어 설명과 함께 전체 목록을 보여 줍니다.

   outbound_phone_number_id는 에이전트에 발신자 번호를 지정하며, 덕분에 다음 요청에서 from_number_id를 생략할 수 있습니다.

4. 04전화 걸기

   to 번호를 전화를 걸 번호로 바꿉니다.

   shell복사

   CALL_ID=$(jq -n --arg agent "$AGENT_ID" '{to: "+14155551234", agent_id: $agent}' |
     curl -s $API/calls \
       -H "Authorization: Bearer $WIXZEL_API_KEY" \
       -H "Idempotency-Key: $(uuidgen)" \
       -H "Content-Type: application/json" \
       -d @- | jq -r .id)

   API는 즉시 status: "queued"와 함께 201로 응답하고, 잠시 후 전화가 울립니다. 여기서는 Idempotency-Key가 필수입니다. 네트워크 타임아웃만으로는 통화가 걸렸는지 알 수 없고, 같은 키로 재시도하면 두 번 거는 대신 원래 통화를 반환하므로, 스크립트에서 재시도한다면 키를 보관하십시오. 처음 15초를 충당할 수 없는 통화는 발신 전에 402로 거부됩니다.

5. 05결과 확인하기

   다섯 번째 요청으로 통화를 읽어 옵니다.

   shell복사

   curl -s $API/calls/$CALL_ID \
     -H "Authorization: Bearer $WIXZEL_API_KEY" | jq

   Example response, shortened복사

   {
     "id": "6a96a3ead6e886d42462dd3e",
     "object": "call",
     "session_id": "sip-5b0c7c0e-9d1f-4c52-8a9e-2f0d3a4b6c7d",
     "status": "completed",
     "direction": "outbound",
     "channel": "phone",
     "engine": "gemini_live",
     "to": "+14155551234",
     "duration_seconds": 94,
     "cost_micros": 76923,
     "failure_code": null,
     "failure_reason": null,
     "transcript": [
       { "role": "assistant", "content": "Hi, this is an automated assistant. Do you have a minute?" },
       { "role": "user", "content": "Sure, go ahead." }
     ]
   }

   status는 queued에서 ringing, in-progress를 거쳐 completed가 되거나, failed, busy, no-answer로 끝납니다. cost_micros는 통화가 정산될 때 기록되며(1,000,000이 $1.00), 연결되지 않은 통화는 요금이 없으므로 null로 남습니다. 통화가 실패하면 failure_code는 통신사의 Q.850 원인 코드(17 통화 중, 19 응답 없음, 21 통신사 거부)이고 failure_reason은 해결 방법을 알려 줍니다. GET /v1/usage/events?session_id=…는 모든 요금을 항목별로 보여 줍니다.

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

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

• 전화 통화에는 직접 보유한 SIP 트렁크가 필요합니다. Wixzel Voice는 번호를 판매, 이전하거나 보유하지 않습니다. 콘솔에서 연결한 Twilio, Telnyx, Plivo, Vobiz, Vonage 계정에서는 번호를 대신 구매할 수 있으며, 요금은 통신사가 청구합니다.
• POST /v1/agents/{id}/test-call의 테스트 통화는 한 문장을 classic 음성 파이프라인으로 말합니다. Gemini Live에는 한 문장만 말하는 모드가 없기 때문입니다. Gemini 음성 자체를 들어 보려면 일반 통화를 거십시오.
• 계정당 기본적으로 동시에 5건의 통화를 진행할 수 있으며, 요청하면 한도를 늘려 드립니다.
• 지연 시간 수치는 공개하지 않습니다. 실시간 엔진은 모델 자체가 응답하는 속도로 답합니다. Wixzel Voice의 동작 변경은 날짜 기반 Wixzel-Version 헤더로 구분되어 배포됩니다.