Overview

WhatsApp in Aircall

WhatsApp is a messaging platform owned by Meta that enables businesses and customers to communicate through text messages, images, documents, voice notes, and interactive message formats. With billions of users worldwide, WhatsApp is widely used for customer support, notifications, sales conversations, and service interactions.

🚧
To use WhatsApp messaging, add WhatsApp in Aircall to your subscription and activate it on your Aircall numbers first. Please visit this page.

WhatsApp in Aircall extends the messaging API to support WhatsApp as a channel. Build outbound campaigns, transactional notifications, and CRM-triggered messages driven entirely from your stack — or hand inbound threads to human agents in the Aircall Workspace. 

Requirements

A few things need to be in place before you can send or receive messages through the API:

A verified Meta Business Portfolio — Meta's one-time business verification, completed in Meta Business Manager.
An activated WhatsApp Business Account (WABA) — linked to the Business Portfolio.
Approved WhatsApp templates — Meta requires a template for any send that initiates a conversation, i.e. outside the 24-hour customer service window.
A registered WhatsApp line on Aircall.

For full setup steps, pricing, and connected CRMs, see WhatsApp in Aircall overview in the Help Center.

Sending modes

Every WhatsApp integration on Aircall sits on top of a registered WhatsApp line. A line operates in one of two modes — Agent conversation or Skipping-inbox — and the mode determines how messages are sent and where inbound replies land.

Send (skipping-inbox mode)

POST /v1/messages/whatsapp/send
Your integration drives the conversation. Aircall forwards the message to WhatsApp, returns delivery status by webhook, and routes inbound replies to your registered callbackUrl. No Workspace conversation is created.

Best for
High-volume, programmatic, non-conversational flows where no human agent is in the loop.

Send (agent-conversation mode)

POST /v1/messages/send/whatsapp/native
The message is created as a Workspace conversation. Agents see the thread in the Aircall Workspace and continue it from there. Inbound replies surface in Workspace, not at a webhook.

Best for
Conversations a human will pick up — sales follow-ups, support handovers, anything agent-driven.

Common use cases

I want to…	Sending mode
🔔 Send CRM-triggered notifications	Skipping-inbox
📦 Send order confirmations & shipping updates	Skipping-inbox
📆 Appointment reminders	Skipping-inbox
💬 Support customers with my agents	Agent conversation

Supporting endpoints

Beyond sending, the API exposes endpoints for managing WhatsApp on Aircall. Full request and response schemas are in the API reference.

Capability	Description
Templates `GET /v1/numbers/:id/templates`	List the approved WhatsApp templates available on a given line. Use the returned template names and parameters when sending outside the 24-hour window. API reference →
Line health `GET /v1/numbers/:id/whatsapp_status`	Fetch the WhatsApp health status for a line. Surface this in your integration so admins can see whether the line is sending and receiving as expected. API reference →

Limitations

Meta limits when free-form text messages can be sent. The rule is set by Meta and applies to every WhatsApp Business Platform integration, not just Aircall.

A 24-hour window opens when a customer messages your number or replies to one of your messages.
Within that window, free-form text can be sent.
Once the window closes, only approved templates can be sent to re-open the conversation.

🚧
Sending free-form text outside an open window returns a 200 from the API, but your webhook will receive a callback with error 63016. The fix is always to send an approved template first — Aircall cannot override or extend the window. Check out the next guide to learn how to send templates via API.

Troubleshooting

The errors below cover what most integrations hit in production. Quality rating and messaging tiers are Meta-controlled concepts that shape a line's sending capability.

Common errors

	What it means	What to do
403	Account is on Essentials, has no active WhatsApp add-on, or the feature is not enabled.	Confirm plan and add-on status. Contact Aircall Support if needed.
400 — line not configured	The line has not been registered for Public API use.	Call POST `/v1/numbers/:id/messages/configuration` first.
400 — template not approved	The template is not in APPROVED status in Meta.	Check template status in Meta Business Manager. Aircall cannot resolve this.
400 — WABA not configured	The line does not have a WABA set up.	Contact Aircall Support — this is a line configuration issue.
400 — line OFFLINE or BLOCKED	The line is not in an active sending state.	Check the line health endpoint. If BLOCKED, contact Aircall Support.

For the full list of error references, visit our Help Center.