Introducción a la API

Guía para desarrolladores: qué permite la API pública de Atendy, cómo se estructura y qué necesitas para empezar a lanzar llamadas desde tu sistema.

Introducción a la API

Atendy incluye una API pública pensada para desarrolladores. Con ella puedes lanzar llamadas salientes desde tu propio sistema, tu CRM o una herramienta de automatización como n8n, sin necesidad de entrar en el panel. Tú decides a quién se llama y con qué agente, y Atendy se encarga de hacer la llamada.

Es la misma tecnología que usas dentro de la plataforma, pero controlada desde tu código. Ideal para integrar las llamadas de voz en flujos que ya tienes montados: recordatorios, confirmaciones, encuestas, avisos o cualquier proceso que quieras automatizar.

Qué puedes hacer con la API

Lanzar llamadas salientes

Envías una petición con el agente, el número de destino y, si quieres, unas variables. Atendy inicia la llamada al instante.

Personalizar cada llamada

Puedes pasar variables (por ejemplo el nombre del cliente) que se inyectan como {{variables}} en el prompt y el saludo del agente.

Integrar con n8n u otras plataformas

Al ser una API estándar por HTTP, encaja en n8n, Make, Zapier o cualquier backend que sepa hacer una petición web.

Automatizar desde tus procesos

Dispara llamadas cuando ocurra algo en tu sistema: un nuevo pedido, una cita creada, un pago pendiente, lo que necesites.

URL base y formato

Todas las peticiones van contra el mismo dominio y se comunican en JSON. La URL base es:

https://atendy.es

Las peticiones envían y reciben datos en formato JSON. Debes incluir la cabecera Content-Type: application/json en las llamadas que llevan cuerpo, y autenticarte con tu clave de API en la cabecera x-api-key.

La API pública requiere el plan Escala. Si tu cuenta está en un plan inferior, las peticiones se rechazan con un error 403. Puedes cambiar de plan desde el panel cuando lo necesites.

Autenticación en dos palabras

Cada petición se identifica con una clave secreta que empieza por sk_live_ y que creas en la sección de Llamadas salientes. La clave viaja en la cabecera x-api-key. La llamada se factura siempre al dueño de la clave, así que trátala como una contraseña y no la publiques nunca en código del lado del cliente.

x-api-key: sk_live_tu_clave_secreta

Tu primera llamada

Para lanzar una llamada saliente haces una petición POST al endpoint de llamadas, indicando el agente que debe atender, el número de destino y, opcionalmente, un número de origen y unas variables. Ejemplo con cURL:

curl -X POST https://atendy.es/api/v1/calls \
  -H "x-api-key: sk_live_tu_clave_secreta" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "uuid-de-tu-agente",
    "to": "+34600000000",
    "vars": { "nombre": "Ana" }
  }'

Si todo va bien, la respuesta es un 200 con los datos de la llamada iniciada:

{
  "call_id": "...",
  "room": "...",
  "status": "dialing"
}

Las variables que envías en vars (como nombre) se inyectan como {{nombre}} en el prompt y el saludo del agente. Así cada llamada suena personalizada sin tener que crear un agente distinto por cliente.

Errores más habituales

Código	Significado	Qué revisar
401	Clave inválida	Comprueba que la cabecera x-api-key es correcta y que la clave no se ha revocado.
403	Plan insuficiente	La API requiere el plan Escala. Actualiza tu plan desde el panel.
429	Límite de ritmo	Estás enviando peticiones demasiado rápido. Espacia las llamadas y reintenta.

Siguientes pasos

Para poner en marcha tu integración, sigue estos apartados en orden: primero Autenticación, para crear tu clave sk_live_ y aprender a enviarla en cada petición; después Llamadas salientes, con la referencia completa del endpoint para lanzar llamadas, sus parámetros y todas las respuestas; y por último Estado de una llamada, para consultar cómo acabó cada una. Si prefieres que Atendy te avise en lugar de preguntar tú, monta el webhook de fin de llamada.