Offering WhatsApp support to callers using the Ring to via API widget

Long hold times are one of the fastest ways to frustrate a caller. Instead of leaving customers waiting in a queue, or turning them away when every agent is busy, you can use your IVR to offer them support over WhatsApp instead. When a caller chooses this option, Aircall sends an approved WhatsApp template to their number. The caller replies at their own pace, and the conversation lands in your agents' Aircall inbox, where it's handled like any other WhatsApp conversation.

This is useful in two common situations:

• Proactive choice: offer WhatsApp up front so callers who prefer messaging never have to wait on hold.
• Overflow, all agents busy: when no agent is available, offer WhatsApp as a way to still get help instead of only waiting in the queue or dropping off.

Note: This setup involves building an API request inside Smartflows, including a JSON body and Basic authentication. You don't need to be a developer, but you should be comfortable following technical, step-by-step instructions.

How it works

1. A customer calls your Aircall number and enters your Smartflows IVR.
2. The caller reaches a point where WhatsApp is offered, either as a menu option ("Press 1 to get help on WhatsApp instead of waiting") or as an overflow branch that triggers when no agent is available.
3. On that branch, the Ring to via API widget sends a request to Aircall's WhatsApp messaging endpoint, specifying which line to send from, which template to use, and which number to send to (the caller's own number).
4. The caller receives the WhatsApp message and can reply. Their reply opens a conversation in the Aircall inbox, visible to your agents.
5. The call ends with a short spoken confirmation.

Important: The Ring to via API widget sends the request but cannot branch the call based on the API response. Everything after the widget (a confirmation message, ending the call, or an alternative route) has to happen regardless of whether the message actually sent.

Before you begin

Make sure the following are already true before starting:

• You're on a Professional or Custom Aircall plan. The Ring to via API widget isn't available on other plans.
• You have Admin access to the Aircall Dashboard and Smartflows.
• You have a WhatsApp-capable number in your account, with WhatsApp messaging enabled.
• You have (or can create) a WhatsApp template already approved by WhatsApp/Meta.

Note: Business-initiated WhatsApp messages always require an approved template. Free-form messages are only possible inside an open 24-hour window, after the customer has messaged you first. If you're offering this to every caller, also review WhatsApp's opt-in and opt-out requirements: only message customers who can reasonably expect to hear from you.

The specific IDs and credentials you'll need (line ID, template ID, API key) are retrieved in Steps 1 and 2 below, you don't need to gather those in advance. For general background on how Aircall's API works, see Aircall for Developers: API references.

Step 1: Prepare your WhatsApp template

Steps

1. Open or create the template you want to send when a caller opts in (for example, a greeting that tells them a sales manager will reach out shortly).
2. Check the template body for variables:
   • No variables (fully static text): you only need the template ID.
   • Positional variables ({{1}}, {{2}}): your request keys will be {{1}}, {{2}}, and so on.
   • Named variables ({{name}}, {{order_id}}): your request keys must match those exact names, including capitalisation.

Important: A template is either positional or named, never both. The key you send in the request must match what the template declares, or the variable won't be filled in.

Step 2: Gather your line ID, template ID, and API credentials

You need three things for the request, all retrieved from the Public API.

API ID and API token 

Go to Aircall Dashboard, go to Company Settings > API Keys > Add a new API key. Copy the token immediately, it isn't shown again. These are the credentials the widget uses to authenticate.

Line ID 

The ID of the WhatsApp-capable number the template is sent from. Retrieve it with the List all Numbers endpoint; each number in the response has an id, which is your lineId.

Template ID 

Retrieve the templates associated with your WhatsApp-capable number using the List WhatsApp Templates endpoint, and copy the id of the template from Step 1.

Step 3: Build the flow in Smartflows

1. Go to Aircall Dashboard > Numbers > Numbers
2. Select the number and click on the Edit green button to open Smartflows
3. Decide where WhatsApp is offered:

   • As a menu option:

     Add an IVR menu widget, for example, "To continue on WhatsApp instead of waiting, press 1. To stay on the line, press 2."

     

   • As an overflow: 

     Place the Ring to via API widget on the branch reached when no agent is available.

     

Step 4: Configure the Ring to via API widget

Add the Ring to via API widget on the WhatsApp branch and configure the request as follows. This request uses the Send WhatsApp Message in Agent Conversation endpoint.

Authentication

The endpoint uses HTTP Basic authentication. In the widget's authentication settings, choose Basic and enter:

• Username: your API ID

• Password: your API token

  

  The widget builds the authorization for you, no manual encoding needed.

Request configuration

• Method: POST
• URL: https://api.aircall.io/v1/messages/send/whatsapp/native
• Request body, template with variables:

{
  "lineId": 1018591,
  "externalNumber": "{{callerNumber}}",
  "templateParams": {
    "id": "13779",
    "body": [
      { "key": "{{1}}", "value": "Jordan" },
      { "key": "{{2}}", "value": "2026-06-15" }
    ]
  }
}

• Request body, template with no variables:

{
  "lineId": 1018591,
  "externalNumber": "{{callerNumber}}",
  "templateParams": {
    "id": "12029"
  }
}

• Field reference:
  • lineId: the ID of your WhatsApp-capable number (the sender), from Step 2.
  • externalNumber: the number the template is sent to. Use {{callerNumber}} so Smartflows inserts the caller's own number at runtime.
  • templateParams.id: the ID of your approved template, from Step 2.
  • templateParams.body: include this only when the template has variables. Omit it entirely for a static template.
  • key: must match the template's placeholder exactly ({{1}} for positional, or the exact name for named templates).
  • value: a static value, or a Smartflows variable.

Important: {{callerNumber}} sends the template to the number the caller is dialling from. If that number isn't registered on WhatsApp, delivery will fail. Keep this in mind when deciding whether to offer the WhatsApp option to every caller.

Response configuration

The widget's UI expects a response it can route on, even though this flow doesn't use one (the call is closed in the next step regardless of the result). Fill these with placeholder values just so the configuration saves:

• Response type: Aircall Number (internal)
• Path: null

Note: The Aircall Public API is limited to 120 requests per minute per company. This shouldn't affect a typical call flow, but is worth knowing if you're testing at volume.

Step 5: Close the call flow

Because the widget can't react to the API response, finish the branch cleanly regardless of outcome.

Steps:

1. After the widget, click on + and add an Audio Message such as: "We've just sent you a WhatsApp message. You can reply there whenever you're ready. Goodbye."

   

2. End the call, or route to voicemail or another team as a fallback.

Step 6: Test the flow

Steps

1. Click on the Publish button in the top-right corner
2. Call the number from a phone whose number is registered on WhatsApp.
3. Reach the WhatsApp branch (select the option, or trigger the overflow condition).
4. Confirm: you receive the template, any variables are filled in correctly, and replying opens a conversation in the Aircall inbox.

If the message doesn't arrive, see the troubleshooting table below.

Troubleshooting

FAQs

Will my agents see the WhatsApp conversation if the caller replies?

Yes. This request uses the Send WhatsApp Message in Agent Conversation endpoint, so both the outgoing message and the customer's reply are visible to agents in their Aircall inbox.

Can I use a template with both positional and named variables?

No. A template is either positional or named, never both. The keys in your request must match exactly what the template declares.

What happens if the caller's number isn't registered on WhatsApp?

Delivery fails. Since the message goes to whatever number the caller dialled in from, this is worth weighing before offering the WhatsApp option to every caller rather than a specific segment.