Documentación
API de Llamadas (voz).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 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

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:

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

{
  "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.
Esc