Llamadas

Llamadas salientes

Automatiza campañas de llamadas telefónicas desde tu backend usando la API REST de VoiceAgent.

¿Qué son las llamadas salientes?

Las llamadas salientes te permiten iniciar llamadas telefónicas programáticamente hacia cualquier número de teléfono. El agente de IA realiza la llamada, espera a que la persona conteste y conduce la conversación según las instrucciones configuradas.

A diferencia de las llamadas entrantes (donde el cliente llama a tu número), en las salientes eres tú quien inicia el contacto. Esto abre un abanico de casos de uso de alto valor para cualquier negocio.

Endpoint: `POST /api/calls/outbound`

Para iniciar una llamada saliente, realiza una petición POST al endpoint con los datos del destinatario y el agente que debe realizar la llamada.

Request

curl -X POST https://usvoiceagent.com/api/calls/outbound \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_xxxxxxxxxxxx",
    "to": "+34600123456",
    "from": "+12125551234",
    "metadata": {
      "customerId": "cust_789",
      "appointmentDate": "2025-06-15",
      "patientName": "María García"
    },
    "overrides": {
      "greeting": "Hola María, te llamamos de la Clínica Salud para recordarte tu cita del 15 de junio. ¿Confirmas tu asistencia?",
      "maxDurationSeconds": 120
    }
  }'

Parámetros del body

Campo	Tipo	Requerido	Descripción
`agentId`	string	Sí	ID del agente que realizará la llamada
`to`	string	Sí	Número de destino en formato E.164 (+34...)
`from`	string	Sí	Número de Twilio desde el que se llama
`metadata`	object	No	Datos adicionales accesibles por el agente durante la llamada
`overrides.greeting`	string	No	Saludo personalizado para esta llamada específica
`overrides.systemPrompt`	string	No	Instrucciones adicionales para esta llamada
`overrides.maxDurationSeconds`	number	No	Duración máxima en segundos (default: 300)
`scheduledAt`	string (ISO 8601)	No	Fecha/hora futura para programar la llamada

Response

// HTTP 202 Accepted
{
  "callId": "call_abc123def456",
  "status": "queued",
  "agentId": "agent_xxxxxxxxxxxx",
  "to": "+34600123456",
  "from": "+12125551234",
  "scheduledAt": null,
  "estimatedStartTime": "2025-05-21T10:30:05Z",
  "createdAt": "2025-05-21T10:30:00Z"
}

Estado inicial: queued

Las llamadas salientes pasan por los estados: queued → initiated → ringing → in-progress → completed (o no-answer, busy, failed). Puedes recibir estos cambios de estado mediante webhooks.

Llamadas programadas

Usa el campo scheduledAt para programar llamadas en el futuro. VoiceAgent encola la llamada y la ejecuta automáticamente en el momento indicado:

{
  "agentId": "agent_xxxxxxxxxxxx",
  "to": "+34600123456",
  "from": "+12125551234",
  "scheduledAt": "2025-06-15T09:00:00Z",
  "overrides": {
    "greeting": "Buenos días, te llamamos para confirmar tu cita de mañana."
  }
}

Zona horaria

El campo scheduledAt debe estar en formato ISO 8601 con zona horaria UTC. VoiceAgent no asume ninguna zona horaria local. Convierte tus fechas a UTC antes de enviarlas.

Límites de tasa y cuotas

VoiceAgent aplica límites de tasa para garantizar la estabilidad del servicio y el cumplimiento de las políticas de Twilio y operadores telefónicos.

Límite	Starter	Business	Enterprise
Llamadas simultáneas	5	25	Ilimitado
Llamadas por minuto	10	60	Personalizado
Llamadas por día	100	1.000	Sin límite
Llamadas programadas pendientes	50	500	Sin límite
Duración máxima por llamada	5 min	15 min	60 min

Si superas el límite de llamadas por minuto, la API responderá con HTTP 429 Too Many Requests e incluirá la cabecera Retry-After con los segundos de espera recomendados.

Casos de uso

Recordatorios de citas

Salud / Servicios

Llama automáticamente a los pacientes o clientes 24h antes de su cita para confirmar o reprogramar. Reduce las ausencias hasta un 60%.

Seguimiento post-venta

E-commerce

Llama a clientes 3 días después de una compra para confirmar la satisfacción, resolver dudas y solicitar una reseña.

Encuestas de satisfacción

Customer Success

Realiza encuestas NPS o CSAT mediante llamadas. Las respuestas se guardan automáticamente y se analizan con IA.

Cobranza amigable

Finanzas

Notifica a clientes sobre facturas pendientes, ofrece opciones de pago y registra compromisos de pago de forma estructurada.

Bienvenida a nuevos usuarios

SaaS / Onboarding

Llama a nuevos registros para presentarles el servicio, resolver dudas iniciales y aumentar la activación.

Alertas críticas

IT / DevOps

Notifica a técnicos o responsables cuando un sistema falla. El agente llama hasta que alguien confirme la recepción del aviso.

Buenas prácticas

Respeta los horarios. En España, evita llamar antes de las 9:00h y después de las 21:00h. En México, el horario recomendado es 9:00–20:00h. Usa el campo scheduledAt para programar llamadas en horarios apropiados.
Identifícate claramente. Las instrucciones del agente deben incluir el nombre de la empresa y el motivo de la llamada desde el primer momento. Las normativas de muchos países exigen esto explícitamente.
Ofrece una opción de opt-out. Incluye siempre la opción de no recibir más llamadas. El agente puede manejar esto con la herramientaunsubscribe_contact.
Implementa reintentos con backoff. Si una llamada resulta en no-answer o busy, espera al menos 30 minutos antes de reintentar y no superes 3 intentos por contacto por día.
Valida los números antes de llamar. Usa la API de Twilio Lookup o la herramienta integrada en VoiceAgent para verificar que los números son válidos y son móviles (no fijos) antes de iniciar campañas masivas.

Anterior: Llamadas entrantes Siguiente: Triangulación