> 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-anunzi/api-calls.md).

# API de llamadas de voz

Crea y controla llamadas de voz en tiempo real y configura tus agentes de voz VPower por API.

Con la API de llamadas de voz haces que tus agentes **llamen y atiendan en tiempo real** desde tu sistema: inicias llamadas telefónicas y web, las consultas o detienes, y configuras a fondo tus agentes de voz (prompt, modelo, funciones, voz y números). Funciona con **VPower**, el motor de voz de Anunzi.

Es parte de la [API de Anunzi](/anunzi-ia-documentation/api-de-anunzi/api.md): usa la **misma API Key** que la API de plataforma.

***

## URL base y autenticación

```
https://calls.anunzi.net
```

```
Authorization: Bearer anz_live_TU_API_KEY
```

Genera tu API Key desde el menú de tu usuario → **API Keys** (ver [API Keys de cuenta](/anunzi-ia-documentation/api-de-anunzi/api/api-keys.md)). Cada operación queda **limitada a los agentes de tu cuenta** (y a los de tus clientes, si eres partner).

***

## Llamadas

| Método   | Ruta                        | Descripción                                                                                                                 |
| -------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `POST`   | `/v2/create-phone-call`     | [Inicia una llamada telefónica](/anunzi-ia-documentation/api-de-anunzi/api-calls/crear-llamada-telefonica.md)               |
| `POST`   | `/v3/create-web-call`       | [Crea una llamada web](/anunzi-ia-documentation/api-de-anunzi/api-calls/crear-llamada-web.md) (desde el navegador o tu app) |
| `GET`    | `/v2/get-call/{call_id}`    | [Obtiene el detalle de una llamada](/anunzi-ia-documentation/api-de-anunzi/api-calls/obtener-llamada.md)                    |
| `POST`   | `/v3/list-calls`            | [Lista llamadas](/anunzi-ia-documentation/api-de-anunzi/api-calls/listar-llamadas.md) con filtros y paginación              |
| `PATCH`  | `/v2/update-call/{call_id}` | [Actualiza los metadatos](/anunzi-ia-documentation/api-de-anunzi/api-calls/actualizar-llamada.md) de una llamada            |
| `POST`   | `/v2/stop-call/{call_id}`   | [Detiene una llamada](/anunzi-ia-documentation/api-de-anunzi/api-calls/detener-llamada.md) en curso                         |
| `DELETE` | `/v2/delete-call/{call_id}` | [Elimina el registro](/anunzi-ia-documentation/api-de-anunzi/api-calls/eliminar-llamada.md) de una llamada                  |

## Agentes de voz

| Método  | Ruta                             | Descripción                                                                                                                                               |
| ------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET`   | `/list-agents`                   | [Lista tus agentes de voz](/anunzi-ia-documentation/api-de-anunzi/api-calls/gestionar-agentes.md#listar-agentes)                                          |
| `GET`   | `/get-agent/{agent_id}`          | [Obtiene la configuración completa](/anunzi-ia-documentation/api-de-anunzi/api-calls/gestionar-agentes/obtener-agente.md) de un agente                    |
| `PATCH` | `/update-agent/{agent_id}`       | [Cambia voz, idioma, comportamiento, extractores…](/anunzi-ia-documentation/api-de-anunzi/api-calls/gestionar-agentes.md#actualizar-agente)               |
| `POST`  | `/publish-agent/{agent_id}`      | [Pone en uso los cambios](/anunzi-ia-documentation/api-de-anunzi/api-calls/gestionar-agentes.md#publicar-agente)                                          |
| `GET`   | `/get-agent-versions/{agent_id}` | [Historial de versiones](/anunzi-ia-documentation/api-de-anunzi/api-calls/gestionar-agentes.md#versiones-del-agente)                                      |
| `GET`   | `/get-agent-llm/{llm_id}`        | [Prompt, mensaje inicial, modelo y funciones](/anunzi-ia-documentation/api-de-anunzi/api-calls/gestionar-agentes/prompt-y-funciones.md)                   |
| `PATCH` | `/update-agent-llm/{llm_id}`     | [Cambia prompt, mensaje inicial, modelo y funciones](/anunzi-ia-documentation/api-de-anunzi/api-calls/gestionar-agentes/prompt-y-funciones.md#actualizar) |
| `GET`   | `/list-voices`                   | [Voces disponibles](/anunzi-ia-documentation/api-de-anunzi/api-calls/gestionar-agentes/voces-y-numeros.md#listar-voces)                                   |
| `GET`   | `/get-voice/{voice_id}`          | [Una voz](/anunzi-ia-documentation/api-de-anunzi/api-calls/gestionar-agentes/voces-y-numeros.md#obtener-una-voz)                                          |
| `GET`   | `/list-phone-numbers`            | [Números de tu cuenta](/anunzi-ia-documentation/api-de-anunzi/api-calls/gestionar-agentes/voces-y-numeros.md#listar-numeros)                              |

Los cambios de configuración van a un **borrador**: el agente sigue atendiendo con la versión publicada hasta que llamas a `publish-agent`.

Para contactos, campañas, mensajes, créditos y webhooks, usa la [API de plataforma](/anunzi-ia-documentation/api-de-anunzi/v1.md).

***

## Motor de voz anterior (deprecado)

Todos los agentes nuevos se crean en VPower y los existentes se van pasando **sin cambiar su `agent_id`, sus números ni estas rutas**.

* Mientras un agente siga en el motor anterior, las llamadas funcionan igual, pero las rutas de **agentes de voz** responden `409` con `"code": "agent_not_migrated"`.
* Si tu integración usa **llamadas web**, revisa la [guía de migración a VPower](/anunzi-ia-documentation/api-de-anunzi/api-calls/migrar-a-vpower.md): con el SDK de Anunzi no tienes que cambiar nada.

***

## Códigos de error

| Código        | Descripción                                                                                    |
| ------------- | ---------------------------------------------------------------------------------------------- |
| `400`         | Solicitud inválida (la respuesta indica qué campo).                                            |
| `401`         | API Key ausente o inválida.                                                                    |
| `402`         | Sin créditos o período de prueba vencido.                                                      |
| `403`         | El agente o la llamada no pertenecen a tu cuenta.                                              |
| `404` / `422` | El recurso no existe bajo tu API Key.                                                          |
| `409`         | Agente todavía en el motor anterior (`agent_not_migrated`) o sin cambios para publicar.        |
| `429`         | Límite de solicitudes, o todas las líneas simultáneas de tu plan en uso (`concurrency_limit`). |
| `500`         | Error interno.                                                                                 |

> 💡 Para hacer muchas llamadas en paralelo, revisa las líneas simultáneas de tu plan en [Suscripción](/anunzi-ia-documentation/suscripcion/suscripcion.md). Para llamar a una lista de contactos, una [campaña](/anunzi-ia-documentation/api-de-anunzi/v1/campaigns.md) gestiona los reintentos y el ritmo por ti.