Skip to content

Voice Call Button

A button in a WhatsApp message or template that starts a WhatsApp voice call to the business in one tap, instead of dialling a phone line.

Also called: WhatsApp call button · voice_call button · Call on WhatsApp button

Reviewed

Interactive lab

Hands on: use the controls to explore. Anything that plays on its own pauses while you are working inside it.

Follow one tap from button to answered call

9 / 9
  • Business serverCloud API client
  • WhatsApp Cloud API
  • CustomerWhatsApp app
  • KYC deskagent softphone

Step 9 of 9Event

WhatsApp Cloud APIBusiness server

calls webhook · terminate

COMPLETED with the duration in seconds, and the same cta_payload for reporting.

  • Request — solid arrow — a call that expects an answer
  • Response — dashed arrow — the answer coming back
  • Event — dotted arrow — something happened and is pushed out
  • Async — double head — fire-and-forget, nobody waits
Step through a voice call button's journey: sent as an interactive message, tapped by the customer, delivered to the business as a calls webhook carrying its payload, routed to the right desk and answered.

Step 9 of 9: WhatsApp Cloud API to Business server — calls webhook · terminate. COMPLETED with the duration in seconds, and the same cta_payload for reporting.

01What is a voice call button?

A voice call button is a button in a WhatsApp business message that, when tapped, places a WhatsApp voice call to the business. It is one of the entry points for user-initiated calls on the WhatsApp Business Calling API, alongside the call icon in the chat header and wa.me/call/ deep links. The call travels over WhatsApp to the business's Cloud API number, where it is answered through the Calling API or by a contact centre connected over SIP.

There are two ways to send one. Inside an open 24-hour customer service window, an interactive message with type and action.name both set to voice_call carries a body and three parameters: display_text (up to 20 characters, "Call Now" by default), ttl_minutes (how long the button stays active, from 1 to 43,200 minutes, with a default of 10,080, seven days) and an optional payload of up to 512 characters. Outside the window, a message template can include a button of type voice_call, created with a TTL of one to 30 days and adjustable when you send it.

It is easy to confuse with the call-to-action (CTA) phone-number button, which hands a number to the phone's dialler and starts an ordinary call over the mobile network. A voice call button never leaves WhatsApp: the business needs calling enabled on its number, the customer needs the WhatsApp app on Android or iOS, and the call, a user-initiated call that carries no Meta call charge, arrives with the button's payload attached.

Key takeaways

  • A voice call button starts a WhatsApp voice call to the business in one tap; the call stays inside WhatsApp instead of dialling a phone number.
  • Send it free-form as an interactive message of type voice_call, or outside the window as a template button of type voice_call.
  • display_text takes up to 20 characters, and ttl_minutes sets how long the button works: 1 to 43,200 minutes, 7 days by default.
  • An optional payload of up to 512 characters comes back as cta_payload in the call webhooks, so you know which message produced the call.
  • A phone-number CTA button dials a regular line over the mobile network; a voice call button rings your Calling API number.

02A voice call button in code

curl -X POST "https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/messages" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "919812345678",
    "type": "interactive",
    "interactive": {
      "type": "voice_call",
      "body": { "text": "Stuck on the address proof? Call us on WhatsApp and we will walk you through it." },
      "action": {
        "name": "voice_call",
        "parameters": {
          "display_text": "Call for help",
          "ttl_minutes": 2880,
          "payload": "kyc_LN4471"
        }
      }
    }
  }'

Free-form, so it needs an open customer service window.

03 · How it works, step by step

How does a voice call button work?

  1. Step 1

    Enable calling on the number

    The button rings a Cloud API number with calling enabled in its settings and a messaging limit of at least 2,000. Set call hours before you start sending buttons.

  2. Step 2

    Choose free-form or template

    Inside an open window, send an interactive voice_call message. Outside it, create a template with a voice_call button, get it approved and send it like any template.

  3. Step 3

    Set the label, expiry and payload

    display_text up to 20 characters; ttl_minutes from 1 to 43,200 at send time (1,440 to 43,200 when creating a template); payload up to 512 characters for tracking.

  4. Step 4

    The customer taps

    WhatsApp places a voice call to your number. Your calls webhook receives a connect event with the SDP offer and the button's cta_payload.

  5. Step 5

    Answer and attribute

    Route on the payload, answer through the Calling API, and read cta_payload again in the terminate webhook to count calls and minutes per message or campaign.

04A voice call button: key facts and limits

Interactive type
interactive.type and action.name: voice_call
Label
display_text, up to 20 characters (default Call Now)
Expiry at send
ttl_minutes 1–43,200; default 10,080 (7 days)
Expiry at template creation
1,440–43,200 minutes (1–30 days)
Payload
Up to 512 characters, returned as cta_payload
Meta call charge
None: the customer places the call
Link alternative
wa.me/call/<number>?biz_payload=…

05Example: A stuck KYC upload at a Pune two-wheeler lender

A Pune two-wheeler finance company sees loan applications stall at the document step. It sends an approved utility template, "Your application LN4471 is waiting for your address proof", with a voice call button labelled "Call for help", a two-day TTL and the payload kyc_LN4471. Applicants who tap it reach the KYC desk directly, because the router reads the payload and opens the application on the agent's screen before the call is answered. After two days the button expires, so nobody rings a desk about a case that has already closed.

06 · Common mistakes, and the fix

Common mistakes with a voice call button

  • Sending buttons before calling is staffed

    A button that rings an unattended number frustrates customers more than no button. Enable calling, set call hours and put agents on the queue before the first send.

  • Confusing it with the phone-number button

    The CTA phone-number button dials a regular line through the mobile network and gives you no payload. Choose the voice call button when you want the call inside WhatsApp, routed by your Calling API setup.

  • An expiry that doesn't match the offer

    The default is seven days. A button for a same-day delivery issue should expire within hours; one for a month-long service plan can last up to 30 days.

  • No payload

    Without one, every call looks the same and you cannot tell which campaign or case produced it. Put a campaign or case ID in payload on every send.

  • Labels over 20 characters

    "Call our loan expert now" is 24 characters and will be rejected. Keep labels short and specific: "Call for help", "Call on WhatsApp".

07 · Tips from the bench

Best practices for a voice call button

  • Use an action label such as "Call on WhatsApp" (16 characters).
  • Encode campaign and case IDs in the payload, for example diwali26:order4521.
  • Match call hours to the times you send buttons, so taps reach a person.
  • Offer a typed alternative in the same body for customers who prefer to chat.

08Why does a voice call button matter?

A button turns "call us" from a number to copy into a single tap at the moment it matters: a failed payment, a delivery that needs directions, a loan application stuck on a document. The call arrives with context, because the payload says which order or campaign it came from, and it rings agents who can see the chat. Marketing and support can measure exactly which messages produce calls, and customers who would rather talk do not have to wait for an outbound callback.

09Voice Call Button FAQs

How do I add a WhatsApp call button to a message?+
Send an interactive message with `type: voice_call` and an action named `voice_call`, inside an open service window. Outside the window, create a template with a `voice_call` button, get it approved and send it with optional `ttl_minutes` and `payload` parameters.
What is the difference between a voice call button and a phone number button?+
A voice call button starts a WhatsApp call to your Calling API number; a phone number button opens the dialler to call a regular phone line. The WhatsApp call needs calling enabled on your number and carries a payload, while the phone call goes over the mobile network to the number you configured.
How long does a WhatsApp voice call button stay active?+
Seven days by default. At send time `ttl_minutes` can be set from 1 to 43,200 minutes (30 days); a template button's value set at creation must be between one and 30 days.
Are calls from a WhatsApp voice call button charged?+
Not by Meta. A call the customer places by tapping the button is a user-initiated call, which carries no call charge. The message containing the button is billed like any other message: by template category, or as a service message inside the window.
Does the WhatsApp call button work on WhatsApp Web?+
No. Customers can place WhatsApp business calls only from the Android and iOS apps, and Meta notes that call deep links are not supported on desktop clients either.

See InfiQ pricing

From definition to your first message

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms