> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Realiza llamadas salientes (API)
> Activa una llamada saliente impulsada por IA desde tu propio código: flujos de encuestas, seguimiento o confirmación.
Las llamadas salientes te permiten proporcionar un número de destino y una
configuración de agente a ThunderPhone para que la IA realice la llamada en tu
nombre. Casos de uso habituales:
* Confirmaciones de citas
* Llamadas de seguimiento de encuestas
* Seguimientos de "segundo intento" después de una llamada perdida
* Notificaciones de tipo despacho
¿Llamas a una lista completa? La función
[**Campañas**](/es/guides/outbound-campaigns) del dashboard
(`/dashboard/campaigns`) recibe un CSV de contactos y gestiona por
ti las ventanas de llamadas según las zonas horarias, la concurrencia y
la política de reintentos. Esta guía cubre llamadas programáticas individuales.
## Requisitos previos
Las llamadas salientes requieren que tengas el `from_number` mediante una
[conexión de VoIP](/api-reference/voip-connections). Los números de demostración
son solo para llamadas entrantes. Consulta
[Usa tus propios números](/es/guides/bring-your-own-numbers).
Un prompt orientado a llamadas salientes suele comenzar con el agente
identificándose y explicando su propósito: "Hola, le habla Acme para
confirmar su cita de mañana a las 3 p. m.…" Configura
`outbound_speak_order` como `agent_first` (el valor predeterminado).
Las llamadas salientes devuelven `402 Payment Required` si el saldo es ≤
`$0.00`. Recarga saldo mediante
[`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)
o activa la [recarga automática](/api-reference/billing#update-auto-reload).
## Realiza una llamada con un agente guardado
La forma más sencilla: referencia un agente por ID:
```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/call \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from_number": "+15551234567",
"to_number": "+14155550199",
"agent_id": 12
}'
```
Respuesta:
```json theme={null}
{ "call_id": 987654321, "status": "initiated" }
```
`status: "initiated"` solo significa que se aceptó la solicitud: la llamada
**aún no está conectada**. Consulta
[`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
para ver el estado en tiempo real (`in_progress` → `completed` / `failed`).
## Realiza una llamada con configuración en línea
Si quieres un prompt único que no vale la pena guardar como agente,
pasa `config` en su lugar. La estructura coincide con el esquema de respuesta del
[webhook `call.incoming`](/es/webhooks/call-incoming):
```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/call \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from_number": "+15551234567",
"to_number": "+14155550199",
"config": {
"prompt": "You are confirming Jane Doe appointment for 3pm tomorrow…",
"voice": "john",
"product": "spark"
}
}'
```
## Sigue la llamada
En paralelo, suscríbete al
[webhook `telephony.complete`](/es/webhooks/events):
es la forma más rápida de saber que una llamada terminó. Si no puedes aceptar
webhooks entrantes, consulta `GET /v1/calls/{call_id}` cada pocos segundos; el
registro incluye `end_reason`, `duration_seconds` y la URL de la grabación
una vez que termina la llamada.
## Errores que vale la pena controlar
| Error | Solución |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `402 Payment Required` | Recarga el saldo o activa la recarga automática |
| `403` llamadas salientes bloqueadas (número de demostración) | Usa un número de VoIP en su lugar |
| `403` llamadas salientes bloqueadas (VoIP no verificado) | Ejecuta [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| `404 from_number is not registered to this organization` | Confirma que el `from_number` coincida con un número de teléfono que tengas |
| `502 Bad Gateway` | Error transitorio de SIP / LiveKit; puedes reintentar con seguridad |
## Control del tiempo en espera
Las llamadas salientes que se prolongan porque la persona que recibe la llamada tarda en responder
(árboles IVR, colas) se pueden limitar con `max_hold_seconds`:
```json theme={null}
{
"from_number": "+15551234567",
"to_number": "+14155550199",
"agent_id": 12,
"max_hold_seconds": 120
}
```
El agente cuelga si no ha recibido audio humano en los últimos
N segundos. El valor predeterminado es 900 (15 minutos).
***
## Próximos pasos
Cada campo de solicitud y código de error.
Transmite llamadas salientes finalizadas a tu sistema.
Recarga automática para que las llamadas salientes nunca fallen por saldo.
Ejecuta una prueba de tu agente saliente antes de producción.