# 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 motor conversacional configurado. 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. |