Skip to content

WhatsApp ID(wa_id)

Also called: WhatsApp user ID · WA ID

Definition
The wa_id field that identifies a WhatsApp user in send responses and webhooks, normally their phone number as digits without the plus sign.

Exhibit A

Follow one customer's wa_id across three payloads

7 / 7
{
  "send_response": {
    "messaging_product": "whatsapp",
    "contacts": [
      {
        "input": "+91 98123 45678",
        "wa_id": "919812345678"
      }
    ],
    "messages": [
      {
        "id": "wamid.HBgMOTE5ODEyMzQ1Njc4FQIAERgSQjE3RTQ5NUY0NjhBMzdBQzQA",
        "message_status": "accepted"
      }
    ]
  },
  "status_webhook_value": {
    "statuses": [
      {
        "id": "wamid.HBgMOTE5ODEyMzQ1Njc4FQIAERgSQjE3RTQ5NUY0NjhBMzdBQzQA",
        "status": "delivered",
        "timestamp": "1792390460",
        "recipient_id": "919812345678"
      }
    ]
  },
  "inbound_webhook_value": {
    "contacts": [
      {
        "profile": {
          "name": "Meera"
        },
        "wa_id": "919812345678",
        "user_id": "IN.40731866125599102847"
      }
    ],
    "messages": [
      {
        "from": "919812345678",
        "from_user_id": "IN.40731866125599102847",
        "id": "wamid.HBgMOTE5ODEyMzQ1Njc4FQIAEhggMkRBNzA1QkI",
        "timestamp": "1792390800",
        "type": "text",
        "text": {
          "body": "Has my order shipped?"
        }
      }
    ]
  }
}
Trimmed versions of a send response, a status webhook value and an inbound webhook value for the same customer, side by side. Step through each place the wa_id appears and the IDs that sit next to it.

Field 7: inbound_webhook_value.messages.0.from — Equals the sender's wa_id. Match it to the contacts entry.

What is the WhatsApp ID (wa_id)?

The WhatsApp ID, written wa_id in API payloads, is the identifier the WhatsApp Cloud API uses for a WhatsApp user. In practice it is the user's phone number in international form as digits only — country code first, with no plus sign, spaces or leading zero — so an Indian user on +91 98123 45678 normally has the wa_id 919812345678. You never create a wa_id: WhatsApp returns it when you send to a number and when the user messages you.

It shows up in four places. The messages endpoint's response to POST /{PHONE_NUMBER_ID}/messages echoes what you put in to as contacts[].input and returns the matching contacts[].wa_id. Inbound webhooks carry it as contacts[].wa_id in the webhook contacts object and as messages[].from. Status webhooks name the recipient in statuses[].recipient_id. The input and the wa_id can differ — formatting aside, Meta notes that the wa_id may not match the number you hold for some users — so the safe rule is to store both and treat the wa_id as WhatsApp's canonical ID for that person.

WhatsApp usernames add a second identifier. Since early April 2026 webhooks also carry a business-scoped user ID (BSUID) as user_id, and when a user has adopted a username, the phone-based wa_id and from can be omitted unless either side messaged or called within 30 days or the user is in your contact book. Do not confuse the wa_id with the phone number ID, which identifies your business number, or with the WhatsApp message ID (wamid), which identifies one message rather than a person.

Key takeaways

  • The WhatsApp ID (wa_id) is how the Cloud API names a WhatsApp user: normally the phone number as digits, country code first, no plus sign.
  • It appears in send responses beside the input you sent, in webhook contacts and messages[].from, and as recipient_id in status webhooks.
  • The wa_id can differ from the number you sent, so store both and key customer records on what WhatsApp returns.
  • For users with a username the wa_id can be omitted from webhooks, while the business-scoped user_id (BSUID) is always present.
  • A wa_id identifies a person and a wamid identifies one message; never use one where the other belongs.

The WhatsApp ID (wa_id) in code

{
  "messaging_product": "whatsapp",
  "contacts": [
    { "input": "+91 98123 45678", "wa_id": "919812345678" }
  ],
  "messages": [
    {
      "id": "wamid.HBgMOTE5ODEyMzQ1Njc4FQIAERgSQjE3RTQ5NUY0NjhBMzdBQzQA",
      "message_status": "accepted"
    }
  ]
}

input is what you sent; wa_id is WhatsApp's ID for the user who will receive it.

How does the WhatsApp ID (wa_id) work?

  1. Normalise before sending

    Convert the number to E.164 (+919812345678) and send it in to. Meta recommends including the plus sign and the country code.

  2. Read the wa_id from the response

    The 200 response pairs contacts[0].input with contacts[0].wa_id. Store the wa_id on the contact, and keep the input too if they differ.

  3. Match inbound messages

    On a messages webhook, find the contact whose wa_id equals messages[].from, or whose user_id equals from_user_id when the phone number is hidden.

  4. Map statuses to recipients

    Status webhooks carry recipient_id. Pair it with the wamid you stored at send time to update the right message for the right person.

  5. Store the BSUID too

    Save user_id next to the wa_id whenever it arrives, and look customers up by either identifier.

Common mistakes with the WhatsApp ID (wa_id)

  • Assuming wa_id equals the number on file

    Formatting and, for some users, the number itself can differ. Store what WhatsApp returns rather than recomputing it from your own records.

  • Keying customers on raw input

    Leading zeros, spaces and missing country codes create duplicate contacts. Normalise to E.164 before sending and merge records on the returned wa_id.

  • Treating wa_id as always present

    Username users can arrive without one. Make the column optional and fall back to the BSUID in user_id.

  • Mixing up wa_id, phone number ID and wamid

    wa_id is the customer, the phone number ID is your sending number and the wamid is one message. Name columns explicitly so they can never be swapped.

  • Using sends to check who is on WhatsApp

    The Cloud API has no lookup endpoint. A send to a number without WhatsApp still returns a wamid and then fails in the status webhook, typically with error 131026.

Example: One customer, three formats, in Surat

A Surat saree retailer imports contacts from its billing software, where one customer appears as 09812345678, +91 98123 45678 and 98123-45678. Messages go out fine because each is normalised to E.164 before sending, but the inbox shows three threads. The fix is to key contacts on the wa_id from the send response — 919812345678 for all three — and merge records that share it. Two months later the customer, who has since adopted a username, writes in without a wa_id in the webhook; the BSUID stored from her earlier messages keeps her in the same thread.

Why does the WhatsApp ID (wa_id) matter?

The wa_id is the join key between WhatsApp and every customer record: CRM contacts, consent records, support tickets and order histories. Get it wrong and the same customer appears twice, replies land in the wrong thread, or an opt-out is missed because the number on file had a space or a leading zero. Normalising numbers once, storing the wa_id WhatsApp returns, and saving the BSUID beside it keeps one customer as one record while usernames roll out.

wa_id FAQs

Is wa_id the same as the customer's phone number?+
Usually it is the phone number as digits without the plus sign. Meta notes it may not match the number you hold for some users, so store the wa_id WhatsApp returns as its own field.
Why is the wa_id different from the number I sent?+
The input is whatever you passed in `to`, formatting included; the wa_id is WhatsApp's canonical form of the account it will deliver to. Keep both and key your records on the wa_id.
What is the difference between wa_id and wamid?+
wa_id identifies a WhatsApp user; wamid identifies one message. A customer keeps the same wa_id across thousands of messages, and each of those messages has its own wamid.
What do I use when a user's wa_id is missing?+
Use the business-scoped user ID (BSUID) sent as `user_id`. It is always present in webhooks, while the wa_id can be left out for username users you have not been in touch with recently.

Best practices for the WhatsApp ID (wa_id)

  • Index contacts on both wa_id and BSUID so either lookup is fast.
  • Mask wa_id in logs and analytics exports; it is a phone number and personal data under the DPDP Act.
  • Keep the last known wa_id after a BSUID arrives; phone-based sends and consent records still depend on it.
  • Give support a one-page map of the WhatsApp platform IDs (wa_id, BSUID, phone number ID, WABA ID, wamid) so tickets quote the right one.

See InfiQ pricing

Try it on the official WhatsApp Business API

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