Skip to content

Ledger entryNo. 686570

WhatsApp Platform IDs

Also called: WhatsApp API IDs · WhatsApp Cloud API identifiers · WhatsApp IDs

Definition
The identifiers the WhatsApp Business Platform uses (portfolio, app, WABA, phone number, wa_id, BSUID, wamid) and how they nest inside each other.

Platform & accounts

Mode · json explorer

Work it out

Find every ID in one map

10 / 10
{
  "business_portfolio": {
    "id": "2290017654321098",
    "whatsapp_business_accounts": [
      {
        "id": "104996543210987",
        "phone_numbers": [
          {
            "id": "113456789012345",
            "display_phone_number": "+91 98765 43210"
          }
        ],
        "message_templates": [
          {
            "id": "1873456789012345",
            "name": "order_shipped"
          }
        ]
      }
    ]
  },
  "app": {
    "id": "987654321098765"
  },
  "webhook_event": {
    "entry": [
      {
        "id": "104996543210987",
        "changes": [
          {
            "field": "messages",
            "value": {
              "metadata": {
                "display_phone_number": "919876543210",
                "phone_number_id": "113456789012345"
              },
              "contacts": [
                {
                  "wa_id": "919812345678",
                  "user_id": "IN.7Hq2Lk9ZpW4xRt3V"
                }
              ],
              "messages": [
                {
                  "id": "wamid.HBgMOTE5ODEyMzQ1Njc4FQIAEhgUM0E5QjRDN0Y",
                  "from": "919812345678",
                  "from_user_id": "IN.7Hq2Lk9ZpW4xRt3V",
                  "type": "image",
                  "image": {
                    "id": "1345678901234567",
                    "mime_type": "image/jpeg"
                  }
                }
              ]
            }
          }
        ]
      }
    ]
  }
}
An illustrative map: the business IDs nested from portfolio down to template, the app ID beside them, and an inbound webhook carrying the account, number, customer, message and media IDs. Step through each annotated field.

Field 10: webhook_event.entry.0.changes.0.value.messages.0.image.id — Media ID: valid for 7 days when received in a webhook.

What is WhatsApp platform IDs?

WhatsApp platform IDs are the identifiers the WhatsApp Business Platform uses to name its objects. On the business side there are four that nest: the business portfolio ID (the company in Meta Business Suite), the Meta app ID (the developer app whose token calls the API), the WhatsApp Business Account ID or WABA ID (the account that holds numbers, templates and billing) and the phone number ID (one registered business number, the node you send from). Template IDs, media IDs and Flow IDs name objects inside an account.

On the customer and message side there are three. The wa_id is the customer's WhatsApp ID, their phone number in digits without a plus sign. The business-scoped user ID (BSUID), in webhooks as user_id and from_user_id since early April 2026, is a country code, a dot and up to 128 letters and digits; it is scoped to a business portfolio and arrives even when a user with a username has hidden their number. The wamid is the ID of one message, returned by every send and repeated on its status webhooks.

This page is the map; each ID has its own glossary page with the details. The commonest bugs come from mixing them: sending to a WABA ID instead of a phone number ID, storing the display number instead of the phone number ID, or using wa_id as the only customer key now that usernames can hide it. Under Meta's new account model the WABA ID also identifies the Messaging account, and a separate WhatsApp account (WAAC) ID is due with a new Graph API version in the first half of 2027.

Key takeaways

  • WhatsApp platform IDs name different things: a company, an app, an account, a business number, a customer, a message or a file.
  • Business identifiers nest: portfolio ID, then WABA ID, then phone number ID; messages are sent from the phone number ID.
  • Customers have a phone-based wa_id and, since early April 2026, a business-scoped user ID (BSUID) in user_id.
  • Each message has a wamid, the key for statuses, replies and deduplication.
  • All Graph IDs are opaque strings: store them as text, never as numbers, and never derive one from another.

The figures

WhatsApp platform IDs: key facts and limits

Send from
Phone number ID (not WABA ID, not the display number)
wa_id format
Digits with country code, no plus sign
BSUID format
Country code, a dot, up to 128 alphanumerics
BSUID scope
One business portfolio; regenerated on number change
wamid prefix
wamid.
Media ID lifetime
30 days uploaded, 7 days from webhooks
WAAC ID
Due with a new Graph API version, H1 2027

In code

WhatsApp platform IDs in code

export function idsFrom(body) {
  const out = [];
  for (const entry of body.entry ?? []) {
    for (const change of entry.changes ?? []) {
      const v = change.value ?? {};
      for (const msg of v.messages ?? []) {
        const contact = (v.contacts ?? [])[0] ?? {};
        out.push({
          wabaId: entry.id,                          // WhatsApp Business Account
          phoneNumberId: v.metadata?.phone_number_id, // your number that received it
          waId: contact.wa_id ?? msg.from ?? null,    // may be absent for username users
          bsuid: contact.user_id ?? msg.from_user_id, // business-scoped user ID
          wamid: msg.id,                              // this message
        });
      }
    }
  }
  return out;
}

Every ID stays a string; wa_id is optional by design.

How does WhatsApp platform IDs work?

  1. Store the business IDs in config

    Keep the portfolio ID, app ID, WABA ID and each phone number ID together per environment. The phone number ID is the one in the send URL: POST /{PHONE_NUMBER_ID}/messages.

  2. Route inbound events by account and number

    In a webhook, entry[].id is the WABA ID and metadata.phone_number_id says which of your numbers received the message, which matters when several numbers share an endpoint.

  3. Key customers on two IDs

    Save wa_id (when present) and the BSUID from contacts[].user_id. Look a customer up by either, because a username user may arrive without a wa_id.

  4. Save the wamid at send time

    Write the messages[0].id from the send response to the record that triggered it. Status webhooks quote it, and replies quote it in context.id.

  5. Treat short-lived IDs as short-lived

    Media IDs from uploads expire after 30 days and those received in webhooks after 7 days; download what you need to keep.

Costly mistakes

Common mistakes with WhatsApp platform IDs

  • Sending to the WABA ID

    The messages edge exists only on phone numbers. A send to /{WABA_ID}/messages fails; use the phone number ID from /{WABA_ID}/phone_numbers.

  • Storing IDs as numbers

    Graph IDs exceed the safe integer range of JavaScript and some databases, so they get rounded. Store them as strings.

  • Using wa_id as the only customer key

    Users with usernames can arrive without a wa_id. Keep the BSUID as a second key and listen for user_id_update when it changes.

  • Treating a BSUID as global

    A BSUID is scoped to one business portfolio. The same person has a different BSUID with another portfolio, so do not share it across companies as an identifier.

Why does WhatsApp platform IDs matter?

Every WhatsApp integration is a set of joins between these IDs: an inbound webhook arrives keyed by WABA ID and phone number ID, carries a customer identified by wa_id and BSUID, and a message by wamid, which must be matched to an order, a ticket or a consent record. Getting the map right once, in the database schema and the config, prevents misrouted replies in multi-number setups, duplicate customers when usernames arrive, and lost delivery statuses when a wamid is not stored at send time.

Example: Two cities, one webhook

A Mumbai and Delhi furniture brand runs one WABA with two numbers and one webhook endpoint. Early on, its developer routed every reply to the Mumbai team because the code ignored metadata.phone_number_id. After the fix, events are routed by phone number ID, the customer is matched on wa_id or BSUID, and each reply is threaded to its order through the wamid the brand saved when it sent the delivery update. When a regular customer later adopts a username and her number disappears from the webhook, the stored BSUID keeps her history in one place.

Best practices for WhatsApp platform IDs

  • Name config variables after the ID type (WA_PHONE_NUMBER_ID), never just WA_ID.
  • Log the WABA ID and phone number ID with every webhook so multi-number bugs are easy to trace.
  • Index your messages table on wamid; it is the lookup for every status update.

WhatsApp Platform IDs FAQs

What is the difference between the WABA ID and the phone number ID?
The WABA ID names the account; the phone number ID names one business number inside it. Templates and webhook subscriptions are managed on the WABA ID, while messages are sent from the phone number ID.
Is the wa_id the same as the customer's phone number?
Usually it is the number in digits with the country code and no plus sign, but it can differ from what you sent, so store the wa_id WhatsApp returns. It can be missing for users who adopted a username.
What is a BSUID on WhatsApp?
A business-scoped user ID: an identifier for a WhatsApp user that is unique within your business portfolio. It appears in webhooks as user_id and lets you recognise customers whose phone number is hidden.
Where do I find my business portfolio ID?
In Meta Business Suite under business settings, in the business info section; it is also in the URL as business_id. The API lists its WABAs at /{BUSINESS_ID}/owned_whatsapp_business_accounts.

See InfiQ pricing

Put WhatsApp Platform IDs to work

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