Crear llamada web

🚀 VPower: usa siempre el SDK de Anunzi (VoiceClient), que funciona con VPower y con el motor anterior (deprecado). Otros SDK de llamadas web dejan de funcionar cuando tu agente pasa a VPower. Ver la guía de migración.

POST /v3/create-web-call

Crea una llamada de voz que se realiza directamente desde el navegador, sin número de teléfono. La respuesta incluye el access_token y los datos de conexión que tu frontend le pasa al SDK de llamadas web para que el usuario se una a la llamada.

⚠️ /v2/create-web-call deja de funcionar el 30 de septiembre de 2026. Si tu integración todavía lo usa, sigue la guía de migración a llamadas web v3.

---

Parámetros del cuerpo

Requeridos

Campo	Tipo	Descripción
agent_id	string	ID del agente que conducirá la llamada. Ejemplo: agent_3f9c1a7b2e4d5c6f

Opcionales

Campo	Tipo	Descripción
agent_version	integer	Versión específica del agente. Por defecto, la versión publicada más reciente.
metadata	object	Objeto libre para guardar información propia (ID de sesión, de usuario, etc.). Se recupera luego con Obtener llamada.
dynamic_variables	object	Variables que se inyectan en el prompt del agente durante la llamada. Ejemplo: {"nombre_cliente": "Ana"} (También se acepta el nombre anterior del campo.)

El cuerpo es el mismo que en la versión anterior: solo cambian la ruta y la respuesta.

---

Respuesta — 201 Created

A diferencia de la versión anterior, la respuesta ya no trae el objeto completo de la llamada: trae solo lo necesario para conectarse. El detalle de la llamada (estado, transcripción, grabación, análisis) se consulta con Obtener llamada usando el call_id.

Campo	Tipo	Descripción
call_id	string	Identificador único de la llamada. Guárdalo para consultarla después.
access_token	string	Token para unirse a la llamada. Vence en pocos segundos si no se usa: créalo justo antes de conectar.
transport	string	Tipo de conexión que debe usar el SDK. Pásalo tal cual.
url	string	Dirección de conexión (según el transport). Pásala tal cual, si viene.
ice_servers	array	Servidores de conexión. Pásalos tal cual, si vienen.

💡 Pasa todos los datos de conexión al SDK (transport, url, ice_servers, además del token). Si solo pasas el token, el SDK puede elegir otro tipo de conexión y la llamada no conecta.

---

Ejemplo de solicitud

Desde tu servidor (nunca desde el navegador: tu API Key no debe quedar expuesta):

curl --request POST \
     --url https://calls.anunzi.net/v3/create-web-call \
     --header 'Authorization: Bearer anz_live_TU_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
  "agent_id": "agent_3f9c1a7b2e4d5c6f",
  "dynamic_variables": {
    "nombre_usuario": "Carlos",
    "plan_actual": "Básico"
  },
  "metadata": {
    "session_id": "web-9923"
  }
}'

Ejemplo de respuesta

{
  "call_id": "Kx2pYnWVmlR3eDsT1Qva59fHgJzLcAXb",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "transport": "gateway",
  "url": "wss://…",
  "ice_servers": [ { "urls": ["stun:…"] } ]
}

---

Unirse a la llamada desde el navegador

Usa el SDK de llamadas web de Anunzi. Es un módulo JavaScript que se importa directamente desde nuestro dominio (no requiere instalar nada):

<button id="llamar">Hablar con el agente</button>
<button id="colgar" disabled>Colgar</button>

<script type="module">
  import { VoiceClient } from 'https://panel.anunzi.net/voice/web-sdk.php';

  const client = new VoiceClient();

  client.on('call_started', () => console.log('Llamada iniciada'));
  client.on('call_ended',   () => console.log('Llamada terminada'));
  client.on('agent_start_talking', () => console.log('El agente habla'));
  client.on('agent_stop_talking',  () => console.log('El agente escucha'));
  client.on('error', (err) => { console.error(err); client.stopCall(); });

  document.getElementById('llamar').onclick = async () => {
    // 1) Tu backend crea la llamada con POST /v3/create-web-call y te devuelve la respuesta
    const r = await fetch('/mi-backend/crear-llamada-web', { method: 'POST' });
    const call = await r.json();

    // 2) Unirse pasando el token y TODOS los datos de conexión
    await client.startCall({
      accessToken: call.access_token,
      callId:      call.call_id,
      transport:   call.transport,
      url:         call.url,
      iceServers:  call.ice_servers,
    });
    document.getElementById('colgar').disabled = false;
  };

  document.getElementById('colgar').onclick = () => client.stopCall();
</script>

El navegador pide permiso de micrófono al iniciar la llamada. La página debe servirse por HTTPS.

Eventos disponibles

Evento	Cuándo ocurre
call_started	La conexión se estableció y la llamada comenzó.
call_ended	La llamada terminó (colgó el usuario, el agente o por error).
agent_start_talking	El agente empieza a hablar (útil para animar la interfaz).
agent_stop_talking	El agente deja de hablar.
update	Transcripción en vivo: { transcript: [{ role: "agent" | "user", content }] }, con la conversación hasta el momento.
error	Error de conexión o de audio. Recomendado: llamar a stopCall().

Para la transcripción, el resumen y la grabación, consulta la llamada al terminar con Obtener llamada.

---

Códigos de estado

Código	Descripción
201	Llamada web creada correctamente.
400	Formato de solicitud inválido. Verifica los parámetros.
401	API Key ausente o inválida.
402	Período de prueba vencido.
403	El agente no pertenece a tu cuenta.
422	El agente solicitado no existe bajo tu API Key.
429	Límite de solicitudes alcanzado.
500	Error interno del servidor.