> For the complete documentation index, see [llms.txt](https://anunzi-ai.gitbook.io/anunzi-docs/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-docs/api-calls/crear-llamada-telefonica.md).

# Crear llamada telefónica

**POST** `/v2/create-phone-call`

Inicia una llamada de voz saliente a través de un agente de Anunzi. El agente llama al número de destino y conduce la conversación según su configuración.

***

## Parámetros del cuerpo

### Requeridos

| Campo         | Tipo   | Descripción                                                                                              |
| ------------- | ------ | -------------------------------------------------------------------------------------------------------- |
| `from_number` | string | Número de origen en formato E.164. Debe estar registrado en tu cuenta de Anunzi. Ejemplo: `+14157774444` |
| `to_number`   | string | Número de destino en formato E.164. Ejemplo: `+12137774445`                                              |

### Opcionales

| Campo                          | Tipo    | Descripción                                                                                                                                                                |
| ------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `override_agent_id`            | string  | Sobreescribe el agente para esta llamada únicamente, sin modificar la configuración del número.                                                                            |
| `override_agent_version`       | integer | Sobreescribe la versión del agente para esta llamada únicamente.                                                                                                           |
| `agent_override`               | object  | Sobreescribe parámetros específicos del agente para esta llamada. Contiene los sub-objetos `agent`, `retell_llm` y `conversation_flow`.                                    |
| `metadata`                     | object  | Objeto libre para almacenar información adicional. No es procesado por el sistema. Recuperable luego desde el objeto de llamada.                                           |
| `retell_llm_dynamic_variables` | object  | Pares clave-valor inyectados dinámicamente en el prompt del agente durante la llamada. Solo aplica para agentes con Response Engine. Ejemplo: `{"nombre_cliente": "Juan"}` |
| `custom_sip_headers`           | object  | Encabezados SIP personalizados para agregar a la llamada. Ejemplo: `{"X-Custom-Header": "valor"}`                                                                          |
| `ignore_e164_validation`       | boolean | Si es `true`, omite la validación E.164 del número de origen. Solo aplica con telefonía personalizada. Por defecto: `false`                                                |

***

## Respuesta — 201 Created

Devuelve el objeto de la llamada creada.

### Campos del objeto de llamada

| Campo                  | Tipo    | Descripción                                                                                                     |
| ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| `call_id`              | string  | Identificador único de la llamada. Ejemplo: `Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6`                                  |
| `call_type`            | string  | Siempre `phone_call` para llamadas telefónicas.                                                                 |
| `agent_id`             | string  | ID del agente utilizado.                                                                                        |
| `agent_version`        | integer | Versión del agente utilizado.                                                                                   |
| `call_status`          | string  | Estado actual: `registered` \| `not_connected` \| `ongoing` \| `ended` \| `error`                               |
| `direction`            | string  | `inbound` o `outbound`                                                                                          |
| `from_number`          | string  | Número de origen.                                                                                               |
| `to_number`            | string  | Número de destino.                                                                                              |
| `start_timestamp`      | integer | Marca de tiempo de inicio en milisegundos (epoch).                                                              |
| `end_timestamp`        | integer | Marca de tiempo de fin en milisegundos (epoch).                                                                 |
| `duration_ms`          | integer | Duración total en milisegundos.                                                                                 |
| `transcript`           | string  | Transcripción completa (disponible tras el fin de la llamada).                                                  |
| `recording_url`        | string  | URL del audio de la llamada en formato WAV.                                                                     |
| `disconnection_reason` | string  | Razón de desconexión (ver tabla abajo).                                                                         |
| `call_analysis`        | object  | Análisis post-llamada: `call_summary`, `call_successful`, `user_sentiment`, `custom_analysis_data`.             |
| `metadata`             | object  | Metadatos enviados al crear la llamada.                                                                         |
| `latency`              | object  | Métricas de latencia: `e2e`, `asr`, `llm`, `tts` (cada una con `p50`, `p90`, `p95`, `p99`, `max`, `min` en ms). |

### Razones de desconexión (`disconnection_reason`)

| Valor                     | Descripción                   |
| ------------------------- | ----------------------------- |
| `user_hangup`             | El usuario colgó              |
| `agent_hangup`            | El agente finalizó la llamada |
| `call_transfer`           | La llamada fue transferida    |
| `voicemail_reached`       | Se detectó buzón de voz       |
| `inactivity`              | Inactividad prolongada        |
| `max_duration_reached`    | Duración máxima alcanzada     |
| `dial_busy`               | Número ocupado                |
| `dial_no_answer`          | Sin respuesta                 |
| `dial_failed`             | Fallo al marcar               |
| `error_no_audio_received` | No se recibió audio           |
| `manual_stopped`          | Detenida manualmente vía API  |

***

## Ejemplo de solicitud

```bash
curl --request POST \
     --url https://calls.anunzi.net/v2/create-phone-call \
     --header 'Authorization: Bearer TU_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
  "from_number": "+14157774444",
  "to_number": "+12137774445"
}'
```

Con variables dinámicas y metadatos:

```bash
curl --request POST \
     --url https://calls.anunzi.net/v2/create-phone-call \
     --header 'Authorization: Bearer TU_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
  "from_number": "+14157774444",
  "to_number": "+12137774445",
  "override_agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "retell_llm_dynamic_variables": {
    "nombre_cliente": "María López",
    "producto": "Plan Premium"
  },
  "metadata": {
    "crm_id": "LEAD-9821",
    "campaña": "reactivacion-mayo"
  }
}'
```

***

## Ejemplo de respuesta

```json
{
  "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
  "call_type": "phone_call",
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "agent_version": 1,
  "call_status": "registered",
  "direction": "outbound",
  "from_number": "+14157774444",
  "to_number": "+12137774445"
}
```

***

## Códigos de estado

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