> For the complete documentation index, see [llms.txt](https://anunzi-ai.gitbook.io/anunzi-ia-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://anunzi-ai.gitbook.io/anunzi-ia-documentation/api-de-llamadas-voz/crear-llamada-web.md).

# Crear llamada web

> 🚀 **VPower:** usa siempre el SDK de Anunzi (`VoiceClient`), que funciona con el motor anterior y con VPower. Otros SDK de llamadas web dejan de funcionar cuando tu agente pasa a VPower. Ver la [guía de migración](/anunzi-ia-documentation/api-de-llamadas-voz/migrar-a-vpower.md).

**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](/anunzi-ia-documentation/api-de-llamadas-voz/migrar-llamadas-web-v3.md).

***

## 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](/anunzi-ia-documentation/api-de-llamadas-voz/obtener-llamada.md). |
| `retell_llm_dynamic_variables` | object  | Variables que se inyectan en el prompt del agente durante la llamada. Ejemplo: `{"nombre_cliente": "Ana"}`                                                                               |

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](/anunzi-ia-documentation/api-de-llamadas-voz/obtener-llamada.md) 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):

```bash
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",
  "retell_llm_dynamic_variables": {
    "nombre_usuario": "Carlos",
    "plan_actual": "Básico"
  },
  "metadata": {
    "session_id": "web-9923"
  }
}'
```

## Ejemplo de respuesta

```json
{
  "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):

```html
<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](/anunzi-ia-documentation/api-de-llamadas-voz/obtener-llamada.md).

***

## 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.                             |