Aircall's WhatsApp Public API lets developers and external tools (HubSpot, Salesforce, and custom scripts) send WhatsApp messages programmatically on behalf of your company, without an agent sending manually from Aircall Workspace. This article explains who can use the API, how to register a line, and what each endpoint does.

Who can use the WhatsApp Public API

All four of the following conditions must be met before the API will work for your company:

  • Aircall Professional plan: Essentials accounts are not eligible and will return a 403 error.
  • WhatsApp add-on: at least one active WhatsApp add-on licence on the account.
  • Feature availability: it is enabled automatically for eligible customers and does not require action unless it has been disabled. If you suspect it has been disabled, contact Aircall Support.
  • Line registration: the WhatsApp line must be registered for Public API use via the configuration endpoint before any sends are possible.
Important: All conditions must be met. If any one is missing, the API will not function for that company.

The two send modes

When sending a WhatsApp message via the API, you choose between two modes.

  • Proxy send: the message is sent on the developer's behalf and does not appear in the agent inbox. Delivery updates and inbound replies are sent to the callbackUrl you registered.
  • Native send: the message is sent and appears in the agent's Workspace conversation. The agent can see and continue the conversation from Aircall.
Note: The two send modes are mutually exclusive. Proxy send requires the line to be registered for Public API use via the configuration endpoint. Native send requires that it is not registered.

The four API endpoints

Register a line for Public API use

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

Register a WhatsApp line and provide a callbackUrl: the URL where Aircall will send delivery updates and inbound replies. This step must be completed before any message sends are possible.

Important: If the API is not working, the first thing to check is whether the line has been registered via this endpoint. Without registration, all send attempts will return an error.

Check line health

GET /v1/numbers/{id}/whatsapp_status

Returns the current state of a WhatsApp line. Call this endpoint before sending to confirm the line is in a healthy state. The response includes:

  • Status: whether the line is ONLINE, OFFLINE, or NOT_REGISTERED
  • canSendMessage: whether the line can currently send (AVAILABLE, LIMITED, or BLOCKED)
  • qualityRating: Meta's signal of recipient engagement (GREEN, YELLOW, or RED)
  • messagingLimitTier: the maximum number of business-initiated conversations the line can start per 24 hours (TIER_250, TIER_1K, TIER_10K, or TIER_100K)

Send a message

POST /v1/messages/whatsapp/send

POST /v1/messages/send/whatsapp/native

Sends a WhatsApp message programmatically. Two message types are supported:

  • Approved templates: can be sent at any time, within or outside the 24-hour conversation window
  • Free-form text: can only be sent within an open 24-hour conversation window

See "The 24-hour conversation window" below for detail on when each type applies.

List available templates

GET /v1/numbers/{id}/templates

Returns all WhatsApp message templates for a line, including their approval status (APPROVED, PENDING, REJECTED, PAUSED, or DISABLED) and the variable structure for each template. Use this endpoint to confirm which templates are available before sending.

Setting up the WhatsApp Public API

Steps:

  1. Confirm your account is on the Pro plan and has at least one active WhatsApp add-on licence.
  2. Call POST /v1/numbers/{id}/messages/configuration with your WhatsApp line ID and your callbackUrl to register the line.
  3. Call GET /v1/numbers/{id}/whatsapp_status to confirm the line is ONLINE and canSendMessage shows AVAILABLE.
  4. Call GET /v1/numbers/{id}/templates to retrieve your approved templates.
  5. Send your first message using POST /v1/messages/whatsapp/send.
Tip: Always check line health before sending, especially in automated workflows. A line can change state based on quality rating and Meta's rules. Building a pre-send status check into your integration prevents failed sends.

The 24-hour conversation window

Meta's conversation window rule controls when free-form text messages can be sent:

  • When a customer messages your number, or replies to one of your messages, a 24-hour window opens.
  • Within that window, you can send free-form text messages.
  • Once the window closes (no customer reply within 24 hours), only approved templates can be sent to re-initiate contact.
Note: Sending free-form text outside an open window returns a 200 response, but your registered webhook will receive a callback containing a 63016 error. Use an approved template to re-open the conversation. Aircall cannot override or extend the window.

API reference

For the complete request and response schemas, authentication details, and code examples, visit Aircall's developer documentation.