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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.anunzi.net/api-calls/crear-llamada-telefonica.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.