Skip to content

A glossary story9 chapters · 6 min read

User-Initiated Call

A WhatsApp voice call a customer starts from the call icon or a call button in a business chat, answered through the Calling API and not charged.

Also called: Inbound WhatsApp call · Customer-initiated call · Incoming business call

Reviewed

Follow along

Three agents, five callers: who picks up?

5 / 5

Only agents with the required skill are eligible; the least busy of them wins.

Incoming · 0 left

  1. All 5 conversations have been routed.

Conversation 5 of 5 · Skills-based

Imran · new installation(needs hindi)goes toWaiting queue

Every agent is at capacity, so “Imran · new installation” waits in the queue.

  • Meera (Hindi)

    1 of 1 open

    Full
    • hindi
    1. Rahul · repair bookingneeds hindi

  • Arjun (Hindi, English)

    1 of 1 open

    Full
    • hindi
    • english
    1. Sana · warranty questionneeds english

  • Kavya (English)

    1 of 1 open

    Full
    • english
    1. Neha · invoice copyneeds english

Waiting · 2

  1. Vikram · repair_RP8841 payloadneeds hindi
  2. Imran · new installationneeds hindi
Same 5 conversations, each strategy
StrategyRoutedWaitingSkill mismatches
Skills-based320
Round-robin321
Each chip is a connect webhook from a caller waiting to be answered. Step through skills-based routing to match callers to free agents by language, compare round-robin, and see who is left waiting: those calls need a quick reject and a follow-up message.

Conversation 5 of 5, Imran · new installation: Every agent is at capacity, so “Imran · new installation” waits in the queue.

Chapter 1 · The scenario

Example: Evening rush at a Lucknow appliance service centre

At 6 pm five customers call a Lucknow appliance-repair service from its WhatsApp chat within two minutes. Two want Hindi, two want English and one, a returning customer, taps the "Call about my repair" button from yesterday's visit summary, so his call carries the repair ID as cta_payload. The router reads each connect webhook, matches language to the three agents on shift and pre-accepts each call as soon as an agent is free. Two callers cannot be placed: their calls are rejected after 20 seconds instead of ringing out, and each gets a message in the window the call opened: "Sorry we missed you. Reply with a good time and we'll call you back."

— Evening rush at a Lucknow appliance service centre

Chapter 2 · What is a user-initiated call?

A user-initiated call is a voice call that a WhatsApp user places to a business. The customer taps the call icon in the chat header, a voice call button the business sent, or a wa.me/call/ link, and the call rings the business's number on the Cloud API. It is the receiving side of the WhatsApp Business Calling API and the mirror image of a business-initiated call, where the business dials the customer and needs their permission first.

Technically the call arrives as a webhook on the calls field: event is connect, direction is USER_INITIATED, and a session carries the caller's SDP offer, alongside the call ID (wacid…), the caller's wa_id and any cta_payload or deeplink_payload that says which button or link they used. The business answers on POST /{PHONE_NUMBER_ID}/calls with pre_accept (recommended, so media is ready early) and then accept, both carrying an SDP answer, or declines with reject. When the call ends, a terminate webhook reports COMPLETED or FAILED and, if it was picked up, the duration. A number connected to a contact centre over SIP receives the same call as a SIP INVITE instead.

Meta does not charge for user-initiated calls. A customer's call also opens or refreshes the 24-hour customer service window whether or not the business answers, so a free-form follow-up after a missed call is allowed, and it is billed as a service message. Only WhatsApp on iPhone and Android can place these calls; desktop clients cannot.

Key takeaways

  • A user-initiated call is a WhatsApp voice call a customer places to a business number from the chat's call icon, a call button or a call link.
  • It arrives as a calls webhook with event: connect and an SDP offer; you answer with pre_accept and accept on POST /{PHONE_NUMBER_ID}/calls.
  • Meta does not charge for user-initiated calls, and the call opens or refreshes the 24-hour customer service window even if nobody answers.
  • If you do not respond within roughly 30 to 60 seconds, the caller sees "Not Answered" and you receive a terminate webhook.
  • Call hours, call icon visibility and a callback-permission prompt are set in the number's calling settings.

Chapter 3 · How it unfolds

How does a user-initiated call work?

  1. Enable calling and set hours

    On a Cloud API number with a messaging limit of at least 2,000, set calling.status to ENABLED, choose call_icon_visibility, and add call_hours with a time zone, up to two slots per day and up to 20 holiday overrides.

  2. The customer taps call

    From the chat header icon, a voice call button or a wa.me/call/ deep link. Buttons and links can carry a payload saying where the call came from.

  3. Receive the connect webhook

    The calls webhook brings the call ID, the caller, the SDP offer and any cta_payload or deeplink_payload. Use them to pick an agent by language, skill or case.

  4. Pre-accept, then accept

    Send pre_accept with your SDP answer as soon as an agent is chosen, then accept with the same answer. Start media only after accept returns 200, and respond within roughly 30 to 60 seconds.

  5. End and follow up

    The terminate webhook gives the status and duration. For a missed or rejected call, follow up with a message in the window the call opened, or ask to call back.

Chapter 4 · In code

A user-initiated call in code

{
  "field": "calls",
  "value": {
    "messaging_product": "whatsapp",
    "metadata": { "display_phone_number": "919876543210", "phone_number_id": "106540352242922" },
    "contacts": [{ "profile": { "name": "Priya" }, "wa_id": "919812345678" }],
    "calls": [
      {
        "id": "wacid.HBgMOTE5ODEyMzQ1Njc4FQIAEhggQkQ2RjQ5",
        "from": "919812345678",
        "to": "919876543210",
        "event": "connect",
        "direction": "USER_INITIATED",
        "timestamp": "1760865600",
        "cta_payload": "repair_RP8841",
        "session": { "sdp_type": "offer", "sdp": "v=0\r\no=- 7669997803033704573 2 IN IP4 127.0.0.1\r\n..." }
      }
    ]
  }
}

One change inside entry[].changes[]. The SDP offer is abbreviated.

Chapter 5 · The facts

A user-initiated call: key facts and limits

Meta call chargeNone for user-initiated calls
Webhookcalls field, event connect, direction USER_INITIATED
Answer actionspre_accept, accept, reject, terminate
Time to respondRoughly 30–60 seconds, then "Not Answered"
Service windowOpened or refreshed by the call, answered or not
Who can callWhatsApp on iPhone and Android, not desktop
Call hoursUp to 2 slots per day, up to 20 holiday overrides
PrerequisiteCloud API number, messaging limit of 2,000 or more

Chapter 6 · Where it goes wrong

Common mistakes with a user-initiated call

  • Sending audio at the wrong moment

    Media that flows before accept returns clips the caller's first words; media that starts late leaves them hearing silence. Pre-accept early and start audio right after the 200.

  • Letting calls ring out

    With no free agent, the caller waits up to a minute and sees "Not Answered". Reject quickly and follow up by message, which the call's open window allows.

  • No call hours

    Without call_hours, the call icon invites calls at 2 am and on holidays. Set opening slots in your time zone and keep the holiday schedule current.

  • Ignoring the payload

    cta_payload and deeplink_payload say which button or link started the call. Routing on them sends a caller straight to the right desk instead of a generic queue.

  • Forgetting the messages around the call

    The call is free, but the follow-up messages are not: in India a free-form reply in the window is billed at the service rate, ₹0.145.

Chapter 7 · Why it matters

Why does a user-initiated call matter?

For many Indian customers a call is still the fastest way to sort out a delivery, a payment or a booking, and a call from inside the chat skips the helpline number, the IVR menu and re-explaining who they are, because the agent sees the chat history and the number the call came from. For the business, inbound WhatsApp calls carry no Meta call charge, and they land on the same identity and thread as the messages, so voice and chat can be routed, reported and staffed as one queue.

Chapter 8 · What good teams do

Best practices for a user-initiated call

  • Pre-accept as soon as an agent is chosen, so media is ready the moment they pick up.
  • Put an order or case ID in call button payloads so calls route themselves.
  • Turn on the callback-permission prompt so a caller you missed can be called back.
  • Report answer rate and time to answer next to chat first response time.

Chapter 9 · User-Initiated Call FAQs

User-Initiated Call FAQs

Are incoming WhatsApp calls to a business free?+
Yes. Meta does not charge for user-initiated calls. Messages you send afterwards are billed as usual; in India a free-form follow-up inside the service window is a service message at ₹0.145.
How does a business answer a WhatsApp call through the API?+
By responding to the connect webhook. Your server sends `pre_accept` and then `accept` to `POST /{PHONE_NUMBER_ID}/calls` with an SDP answer from your WebRTC stack, or `reject` to decline. Over SIP the call arrives as an INVITE to your SIP server instead.
What happens if no one answers a WhatsApp business call?+
After roughly 30 to 60 seconds without a response the caller sees "Not Answered" and you receive a terminate webhook with no duration. The call has opened the 24-hour service window, so you can follow up with a free-form message.
Can customers call a WhatsApp Business API number from WhatsApp Web?+
No. User-initiated calls can be placed only from WhatsApp on iPhone and Android, and call deep links are not supported on WhatsApp desktop clients.
Can I limit when customers can call my WhatsApp number?+
Yes. Calling settings let you set `call_hours` with a time zone, weekly opening slots and up to 20 holiday overrides, restrict the call icon to certain countries, or hide it with `DISABLE_ALL`.

See InfiQ pricing

* Per-message rates for India, ex-GST: marketing, utility and authentication effective 1 July 2026; service messages ₹0.145 since 1 October 2026 (they were ₹0 until 30 September 2026). Volume commitments earn discounts — final rate is confirmed on your account; applicable GST extra. Rates for other countries differ (see the international rate table on /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