Campañas de llamadas salientes

Ciclo de vida

1. Crear

   POST/v1/campaigns con un name, un agentId y un phoneId. Se crea inactiva, salvo que envíes isActive: true.

2. Añadir contactos

   POST/v1/campaigns/{campaignId}/contacts crea o actualiza cada contacto por número de teléfono y pone en cola una llamada por contacto.

3. Iniciar

   Haz un PATCH de la campaña con isActive: true. Las llamadas en cola se marcan respetando el límite de llamadas por segundo del trunk, y los contactos añadidos más tarde se llaman a medida que llegan.

4. Supervisar

   Consulta los totales con GET/v1/campaigns/{campaignId} y las llamadas con GET /v1/calls?campaignId=.

5. Reintentar

   POST/v1/campaigns/{campaignId}/retry crea una campaña nueva, inactiva, con los contactos con los que no lograste hablar y que nunca devolvieron la llamada.

Añadir contactos

{
  "contacts": [
    {
      "salutation": "ms",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "phoneNumber": "+33612345678",
      "email": "ada@example.com",
      "metadata": { "plan": "pro", "renewal": "2026-11-15" }
    }
  ]
}

• phoneNumber es obligatorio, en E.164: normaliza los números antes de enviarlos.
• Un email presente pero vacío o mal formado hace fallar toda la petición con un 400: omite el campo si no estás seguro de su valor. error.issues[].path señala el contacto que tiene el error, como ["contacts", 0, "email"].
• metadata acepta cualquier objeto JSON y llega al prompt del agente (consulta Variables).

Iniciar, detener y horarios de llamada

isActive inicia y detiene la campaña. Una campaña no tiene franja horaria propia: para respetar los horarios legales de llamada, programa la activación y la desactivación desde tu sistema, al principio y al final de cada franja.

Parada automática por llamadas rechazadas

Una campaña se detiene sola cuando demasiadas de sus llamadas recientes se rechazan nada más realizarse, lo que suele indicar que el operador está bloqueando el número. Las llamadas recientes son las 40 últimas que han terminado en los últimos 10 minutos, y el cálculo empieza cuando ya han terminado 30. declinedStopRatio fija el umbral, de 0,35 (14 llamadas de 40) a 0,7 (28 de 40), con 0,5 por defecto. Es un ajuste avanzado: una cuenta que no lo tiene activado recibe un 403; pídeselo a tu gestor de cuenta.

Eliminar las llamadas en cola

DELETE/v1/campaigns/{campaignId}/calls con ?status=READY elimina las llamadas que aún esperan a ser marcadas: todas, o las de los phoneNumbers que envíes. Las llamadas ya realizadas nunca se tocan. Los totales de la campaña se calculan a partir de las llamadas que quedan.

Bajas (opt-out)

Cuando un contacto pide que no se le vuelva a llamar, POST/v1/contact-opted-out marca su número. Sus llamadas en cola y futuras terminan con contact-opted-out, sin llegar a marcarse. Una entrada boolean como Pidió darse de baja en la información que debe recopilar el agente permite que tu webhook lo haga automáticamente.