Gemini Live en una llamada real con la API de Wixzel Voice

¿Qué necesitas antes de empezar?

• Una clave de API de Wixzel Voice con crédito. La recarga mínima es de $5.
• Una troncal SIP en tu operador y un número en ella que el operador te permita mostrar como identificador de llamada.
• curl, jq y uuidgen.

¿Cómo construyes esto en Wixzel Voice, paso a paso?

1. 01Conecta tu troncal SIP

   Define tu clave y la base de la API una vez, y luego crea la troncal. tee guarda la respuesta completa, porque además del id necesitas dos valores de ella:

   shellCopiar

   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

   Omite username y password si tu operador autoriza por IP. En cualquier caso, añade platform_ip a la lista de IP permitidas del operador para que acepte llamadas desde la plataforma; origination_uri es adonde el operador debe enviar las llamadas entrantes, algo que esta guía no necesita.

2. 02Registra el número desde el que vas a llamar

   Usa tu propio número, en formato E.164:

   shellCopiar

   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. 03Crea el agente Gemini Live

   La voz es un solo modelo en tiempo real en lugar de tres etapas:

   shellCopiar

   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 entrega todo el turno (escuchar, razonar y hablar) a Gemini Live, así que no hay bloque stt, llm ni tts; la API rechaza una voz que nombre ambas formas. Charon es una de las voces predefinidas de Gemini, y GET /v1/engines/gemini_live/voices las lista todas con las descripciones de una palabra de Google.

   outbound_phone_number_id le da al agente un identificador de llamada, y eso es lo que permite que la siguiente petición omita from_number_id.

4. 04Haz la llamada

   Sustituye el número to por el teléfono al que quieres llamar:

   shellCopiar

   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)

   La API responde 201 con status: "queued" al instante, y el teléfono suena un momento después. Idempotency-Key es obligatorio aquí: si la red agota el tiempo de espera, no sabes si la llamada se hizo, y un reintento con la misma clave devuelve la llamada original en lugar de marcar dos veces, así que conserva la clave si programas reintentos. Una llamada que no puede cubrir sus primeros 15 segundos se rechaza con 402 antes de marcar.

5. 05Consulta qué pasó

   La quinta petición consulta la llamada:

   shellCopiar

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

   Example response, shortenedCopiar

   {
     "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 pasa de queued por ringing e in-progress a completed, o termina como failed, busy o no-answer. cost_micros se escribe cuando la llamada se liquida (1 000 000 equivale a $1.00) y queda en null en una llamada que nunca se conectó, porque esa llamada no se cobra. Cuando una llamada falla, failure_code es la causa Q.850 del operador (17 ocupado, 19 sin respuesta, 21 rechazada por el operador) y failure_reason dice qué hacer al respecto. GET /v1/usage/events?session_id=… detalla cada cargo.

¿Cuánto cuesta esto en Wixzel Voice?

¿Qué límites de Wixzel Voice se aplican a esto?

• Las llamadas telefónicas necesitan tu propia troncal SIP. Wixzel Voice no vende, porta ni aloja números. Puede comprarte uno en una cuenta de Twilio, Telnyx, Plivo, Vobiz o Vonage que conectes desde la consola, facturado por tu operador.
• Una llamada de prueba con POST /v1/agents/{id}/test-call dice su frase mediante el pipeline de voz classic, porque Gemini Live no tiene un modo de frase única. Para oír la propia voz de Gemini, haz una llamada normal.
• Por defecto, cada cuenta puede tener cinco llamadas en curso a la vez; el límite se amplía a petición.
• No se publica ninguna cifra de latencia: un motor en tiempo real responde tan rápido como el propio modelo. Los cambios de comportamiento de Wixzel Voice se publican detrás de un encabezado Wixzel-Version con fecha.