Llamadas salientes (API)

Referencia del endpoint POST /api/v1/calls para lanzar llamadas salientes desde tu código, n8n u otra herramienta.

Llamadas salientes (API)

Esta es la API pública de Atendy para desarrolladores. Con una sola petición HTTP puedes pedirle a la plataforma que llame por teléfono a un número usando uno de tus agentes. Es ideal para conectar Atendy con tus propias aplicaciones o con herramientas de automatización como n8n: cuando ocurre algo en tu sistema (una nueva reserva, un pedido, un aviso), disparas una llamada automática.

Autenticación

Todas las peticiones se autentican con una clave de API que empieza por sk_live_. La creas en la sección Llamadas salientes del panel, en el apartado de claves de API. La clave se muestra completa una sola vez al crearla, así que guárdala en un lugar seguro. Se envía en cada petición mediante la cabecera x-api-key. Cada llamada lanzada con tu clave se factura a la cuenta dueña de esa clave, así que trátala como una contraseña y no la publiques en código del lado del cliente.

Método y URL

POST https://atendy.es/api/v1/calls

Cabeceras

Cuerpo de la petición

El cuerpo es un objeto JSON con los siguientes campos:

Ejemplo de petición (cURL)

curl -X POST https://atendy.es/api/v1/calls \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_tu_clave_aqui" \
  -d '{
    "agent_id": "1a2b3c4d-0000-0000-0000-000000000000",
    "to": "+34600000000",
    "from": "+34910000000",
    "vars": {
      "nombre": "Ana",
      "pedido": "12345"
    }
  }'

Respuesta correcta (200)

Si la llamada se acepta y empieza a marcarse, recibes un código 200 con un cuerpo JSON como este:

{
  "call_id": "call-out-4f3a9c2b1d7e",
  "room": "call-out-4f3a9c2b1d7e",
  "status": "dialing"
}

Evitar llamadas duplicadas (Idempotency-Key)

Cada petición aceptada llama por teléfono a una persona real y consume minutos de tu plan. Si tu sistema reintenta automáticamente cuando una petición tarda o da timeout, sin más precauciones esa persona recibiría dos llamadas. Para evitarlo, envía la cabecera Idempotency-Key con un identificador único de esa llamada: si repites la petición con la misma clave y los mismos datos, Atendy te devuelve la respuesta de la primera sin volver a marcar.

Usa un valor que identifique el hecho de negocio, no el intento: por ejemplo el identificador del pedido, del aviso o de la fila de tu base de datos. Debe tener entre 8 y 255 caracteres y admite letras, números, punto, guion, guion bajo y dos puntos. La clave se recuerda durante 24 horas.

curl -X POST https://atendy.es/api/v1/calls \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_tu_clave_aqui" \
  -H "Idempotency-Key: aviso-2026-08-06-12345" \
  -d '{
    "agent_id": "1a2b3c4d-0000-0000-0000-000000000000",
    "to": "+34600000000"
  }'

Cómo se usan las vars como {{variables}}

Cada clave que envíes dentro de vars queda disponible en el prompt y en el saludo del agente escribiéndola entre dobles llaves. Por ejemplo, si envías vars con nombre igual a Ana y pedido igual a 12345, en el prompt o el saludo puedes escribir {{nombre}} y {{pedido}} y el agente dirá los valores reales durante la llamada.

Saludo del agente:
Hola {{nombre}}, le llamo de la tienda por su pedido {{pedido}}.

Con vars = { "nombre": "Ana", "pedido": "12345" } el agente dice:
Hola Ana, le llamo de la tienda por su pedido 12345.

Errores

Cuando algo falla, la API devuelve un código de estado distinto de 200:

Límite de peticiones

Puedes lanzar hasta 30 peticiones por minuto con la misma cuenta. Al superarlo recibes un 429 con la cabecera Retry-After. Ten en cuenta que ese límite es de peticiones, no de conversaciones simultáneas: cada llamada ocupa recursos durante varios minutos, así que si vas a lanzar decenas de llamadas seguidas, repártelas en el tiempo o usa las campañas del panel, que tienen ritmo configurable. Si necesitas volumen alto y sostenido, háblalo con nosotros antes para dimensionar la capacidad.