Documentación

Llamadas salientes

Documentación

Las llamadas salientes son la forma en que tu agente llama a la gente en lugar de esperar a que le llamen. Dos disparadores cubren casi cualquier necesidad real:

  • Por API — POST /v1/calls desde tu código, una llamada cada vez. La vía más común para integraciones en producción.
  • Por lote CSV — sube una lista de contactos vía la API y la plataforma dosifica las marcaciones por ti. Pensado para campañas y tandas de recordatorios.

Ambos acaban ejecutando el mismo scenario en el mismo motor. Para probar un scenario de forma interactiva, usa el Test call en el navegador desde el Overview del proyecto — ejercita el mismo agente sin marcar a nadie.

Disparar por API

POST /v1/calls
Authorization: Bearer <project-api-key>
Idempotency-Key: <your unique id>
Content-Type: application/json

{
  "scenarioId": "0d7e0f5a-…",
  "phone": "+34123456789",
  "parameters": {
    "customer_name": "Maria",
    "appointment_at": "2026-05-15T18:00:00Z"
  }
}

Campos:

  • scenarioId — el id de un scenario saliente de tu proyecto. Obligatorio.
  • phone — destino en E.164. Obligatorio.
  • parameters — mapa opcional de clave-valor que tu scenario puede leer durante la llamada. Úsalo para pasar contexto por llamada (nombre del cliente, hora de la cita, número de pedido).
  • callerIdNumber — opcional; cuál de tus caller ID verificados presentar.
  • Idempotency-Key — recomendado: tu identificador único para esta llamada. Repetir la misma clave dentro de 24 horas devuelve la respuesta original sin marcar dos veces — importante cuando reintentas una petición de API fallida. Reutilizar una clave con un cuerpo distinto devuelve 409.

La llamada se encola y se marca de inmediato; el envío programado a una hora futura está en la hoja de ruta (por ahora, programa en tu lado). La respuesta lleva el id de sesión — consulta GET /v1/sessions/{id} para el estado y los resultados.

Las claves de API se emiten en la pestaña API keys del proyecto. Las claves tienen scopes — da a una clave solo los permisos que necesita (outbound:trigger, sessions:read). Rota emitiendo una clave nueva y revocando la antigua.

Disparar por lote CSV

POST /v1/calls/bulk
Authorization: Bearer <project-api-key>
Content-Type: multipart/form-data

scenarioId=<uuid>
callerIdNumber=+1…        (optional)
csv=@contacts.csv

El CSV necesita al menos una columna phone; cada otra columna se convierte en un parámetro por fila que tu scenario puede leer.

phone,customer_name,appointment_at
+34123456789,Maria,2026-05-15T18:00:00Z
+34987654321,Carlos,2026-05-15T19:00:00Z

Hasta 100.000 filas / 10 MB por lote. La plataforma dosifica las marcaciones (5 llamadas por minuto por defecto — se amplía por proyecto bajo petición) para que no inundes tu propio troncal ni al operador de destino.

Sigue el progreso a través de la API:

  • GET /v1/calls/batches — lista tus lotes
  • GET /v1/calls/batches/{id} — contadores en vivo: pendientes / en curso / completadas / fallidas / abandonadas
  • POST /v1/calls/batches/{id}/cancel — detiene las filas restantes

Resultados y motivos de fallo

Cada llamada saliente completada se resuelve en un resultado (success / conversación real / spam) exactamente igual que una entrante. Las llamadas que nunca llegaron a ser conversación llevan en cambio un motivo de fallo tipado:

  • no_answer — sonó hasta el final, ningún humano contestó.
  • busy — la línea estaba ocupada.
  • voicemail_detected — se detectó un contestador; el agente cuelga por defecto en lugar de hablar con una máquina (dejar mensajes en el buzón está en la hoja de ruta).
  • invalid_number — el número de destino no está en servicio.
  • caller_id_unauthorized — el operador del destino rechazó nuestro caller ID.
  • provider_error — error del proveedor de telefonía (raro).
  • internal_error — error de la plataforma (raro; se investiga).

Todos ellos afloran en los registros de sesión, los contadores del lote y tus eventos de webhook.

Cumplimiento normativo — tu responsabilidad

Las llamadas salientes están reguladas. Las reglas exactas dependen del país de destino, la hora del día y a qué ha consentido la persona a la que llamas. La plataforma te da grabaciones y registros de sesión completos para tu pista de auditoría; el cumplimiento de la TCPA (EE. UU.), el RGPD (UE) o la normativa local es tu responsabilidad.

Orientación práctica:

  • Consigue consentimiento antes de llamar — guarda la prueba. No llames a personas que no pidieron que se les llamara.
  • Filtra contra tu lista de exclusión antes de disparar — la plataforma no mantiene hoy una lista DNC por ti, así que filtra tus listas de contactos antes de que lleguen a POST /v1/calls.
  • Revela que es una IA donde se exija — pon la revelación en el saludo de tu scenario. Cada año más jurisdicciones lo exigen.
  • Respeta las franjas horarias — dispara en horas locales apropiadas; la plataforma no impone horarios de silencio por país.
  • Vigila tus tasas de conexión — si disparas muchas llamadas que fallan o cuelgan de inmediato, la reputación de tu caller ID se degrada ante los operadores. Reduce el ritmo.

Límites de tasa

  • 100 peticiones de mutación por minuto por clave de API (cubre POST /v1/calls)
  • 5 marcaciones por minuto de dosificación de lotes por proyecto (ampliable bajo petición)
  • Hay límites superiores disponibles — contacta con sales@aitelier.org.