La API pública de WhatsApp de Aircall permite a los desarrolladores y a las herramientas externas (HubSpot, Salesforce y scripts personalizados) enviar mensajes de WhatsApp de forma programática en nombre de tu empresa, sin que un agente los envíe manualmente desde Aircall Workspace. Este artículo explica quién puede usar la API, cómo registrar una línea y qué hace cada endpoint.

Quién puede usar la API pública de WhatsApp

Las cuatro condiciones siguientes deben cumplirse antes de que la API funcione para tu empresa:

  • Plan Professional de Aircall: las cuentas Essentials no son aptas y devolverán un error 403.
  • Complemento de WhatsApp: al menos una licencia activa del complemento de WhatsApp en la cuenta.
  • Disponibilidad de la función: se activa automáticamente para los clientes aptos y no requiere ninguna acción a menos que se haya desactivado. Si sospechas que se ha desactivado, contacta con el soporte de Aircall.
  • Registro de la línea: la línea de WhatsApp debe registrarse para su uso con la API pública mediante el endpoint de configuración antes de que sea posible realizar cualquier envío.
Importante: Deben cumplirse todas las condiciones. Si falta хотя бы una, la API no funcionará para esa empresa.

Los dos modos de envío

Al enviar un mensaje de WhatsApp mediante la API, puedes elegir entre dos modos.

  • Envío proxy: el mensaje se envía en nombre del desarrollador y no aparece en la bandeja de entrada del agente. Las actualizaciones de entrega y las respuestas entrantes se envían a la callbackUrl que registraste.
  • Envío nativo: el mensaje se envía y aparece en la conversación de Workspace del agente. El agente puede ver y continuar la conversación desde Aircall.
Nota: Los dos modos de envío son mutuamente excluyentes. El envío proxy requiere que la línea esté registrada para su uso con la API pública mediante el endpoint de configuración. El envío nativo requiere que no esté registrada.

Los cuatro endpoints de la API

Registrar una línea para usarla con la API pública

POST /v1/numbers/{id}/messages/configuration

Registra una línea de WhatsApp y proporciona una callbackUrl: la URL a la que Aircall enviará actualizaciones de entrega y respuestas entrantes. Este paso debe completarse antes de que sea posible enviar cualquier mensaje.

Importante: Si la API no funciona, lo primero que hay que comprobar es si la línea se ha registrado mediante este endpoint. Sin registro, todos los intentos de envío devolverán un error.

Comprobar el estado de la línea

GET /v1/numbers/{id}/whatsapp_status

Devuelve el estado actual de una línea de WhatsApp. Llama a este endpoint antes de enviar para confirmar que la línea está en buen estado. La respuesta incluye:

  • Estado: si la línea está ONLINE, OFFLINE o NOT_REGISTERED
  • canSendMessage: si la línea puede enviar actualmente (AVAILABLE, LIMITED o BLOCKED)
  • qualityRating: la señal de Meta sobre la interacción del destinatario (GREEN, YELLOW o RED)
  • messagingLimitTier: el número máximo de conversaciones iniciadas por la empresa que la línea puede comenzar por cada 24 horas (TIER_250, TIER_1K, TIER_10K o TIER_100K)

Enviar un mensaje

POST /v1/messages/whatsapp/send

POST /v1/messages/send/whatsapp/native

Envía un mensaje de WhatsApp de forma programática. Se admiten dos tipos de mensajes:

  • Plantillas aprobadas: pueden enviarse en cualquier momento, dentro o fuera del periodo de conversación de 24 horas
  • Texto libre: solo puede enviarse dentro de un periodo de conversación abierto de 24 horas

Consulta "El periodo de conversación de 24 horas" a continuación para obtener más información sobre cuándo se aplica cada tipo.

Enumerar las plantillas disponibles

GET /v1/numbers/{id}/templates

Devuelve todas las plantillas de mensajes de WhatsApp de una línea, incluido su estado de aprobación (APPROVED, PENDING, REJECTED, PAUSED o DISABLED) y la estructura de variables de cada plantilla. Usa este endpoint para confirmar qué plantillas están disponibles antes de enviar.

Configurar la API pública de WhatsApp

Pasos:

  1. Confirma que tu cuenta está en el plan Pro y que tiene al menos una licencia activa del complemento de WhatsApp.
  2. Llama a POST /v1/numbers/{id}/messages/configuration con el ID de tu línea de WhatsApp y tu callbackUrl para registrar la línea.
  3. Llama a GET /v1/numbers/{id}/whatsapp_status para confirmar que la línea está ONLINE y que canSendMessage muestra AVAILABLE.
  4. Llama a GET /v1/numbers/{id}/templates para recuperar tus plantillas aprobadas.
  5. Envía tu primer mensaje usando POST /v1/messages/whatsapp/send.
Consejo: Comprueba siempre el estado de la línea antes de enviar, especialmente en flujos de trabajo automatizados. El estado de una línea puede cambiar en función de la calificación de calidad y de las reglas de Meta. Incorporar una comprobación de estado antes del envío en tu integración evita envíos fallidos.

El periodo de conversación de 24 horas

La regla del periodo de conversación de Meta controla cuándo pueden enviarse mensajes de texto libre:

  • Cuando un cliente envía un mensaje a tu número, o responde a uno de tus mensajes, se abre un periodo de 24 horas.
  • Dentro de ese periodo, puedes enviar mensajes de texto libre.
  • Una vez que se cierra el periodo (sin respuesta del cliente en un plazo de 24 horas), solo pueden enviarse plantillas aprobadas para volver a iniciar el contacto.
Nota: Enviar texto libre fuera de un periodo abierto devuelve una respuesta 200, pero tu Webhook registrado recibirá una devolución de llamada que contiene un error 63016. Usa una plantilla aprobada para volver a abrir la conversación. Aircall no puede anular ni ampliar el periodo.

Referencia de la API

Para consultar los esquemas completos de solicitud y respuesta, los detalles de autenticación y ejemplos de código, visita la documentación para desarrolladores de Aircall.