Skip to content

Playbook · 5 steps

Postman Collection

Also called: WhatsApp Cloud API Postman collection · Meta Postman workspace

5steps

Level
Foundation
Reading time
About 5 min

Reviewed

Definition
Meta's ready-made set of WhatsApp Cloud API and management requests for Postman, driven by environment variables for the token, phone number ID and WABA ID.

01 · How it works, in 5 steps

How does the WhatsApp Postman collection work?

  1. 1

    Fork the collection

    Open Meta's WhatsApp Business Platform workspace on postman.com, and fork the Cloud API collection and its environment into your own workspace so your changes stay yours.

  2. 2

    Fill the environment

    Set the variables: the current Graph API version, phone number ID, WABA ID, access token and a recipient number. Most values are in WhatsApp Manager or the App Dashboard's API Setup panel. Variable names can change between collection versions, so check the environment tab.

  3. 3

    Select the environment

    Choose it in the environment picker. If none is selected, the variables resolve to nothing and requests go to broken URLs such as https://graph.facebook.com//messages. This is the most common first-day failure.

  4. 4

    Send the first template

    Run the send-template request with hello_world. A 200 response containing a wamid means the token, number and recipient are all correct.

  5. 5

    Save and share

    Save the requests you change and add tests that check the response. Share the collection with your team, but never an environment that contains a live token.

02Try it

Hands-on: use the controls to work through it yourself.

Press Send on the collection's first request

2 / 2
POSThttps://graph.facebook.com/v26.0/106540352242922/messages

POST 200 in 820 ms

Request

3 headers · body
POST /v26.0/106540352242922/messages HTTP/1.1
Host: graph.facebook.com
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json
{
"messaging_product": "whatsapp",
"to": "919812345678",
"type": "template",
"template": {
"name": "hello_world",
"language": {
"code": "en_US"
}
}
}

Response

200 OK
HTTP/1.1 200 OK
Content-Type: application/json
{
"messaging_product": "whatsapp",
"contacts": [
{
"input": "919812345678",
"wa_id": "919812345678"
}
],
"messages": [
{
"id": "wamid.HBgMOTE5ODEyMzQ1Njc4FQIAERgSQzVGNjc4OUFCQ0RFRjAxMjM0AA=="
}
]
}
Try another response
The hello_world template request after Postman resolves {{Version}}, {{Phone-Number-ID}} and the token from your environment. Toggle the two errors new users hit most: an expired token and a recipient the test number cannot message.

Response: 200 OK after 820 ms.

03 · Why it matters

Why does the WhatsApp Postman collection matter?

The collection is the fastest way to see the WhatsApp Cloud API work end to end before you write any code. One request sends the hello_world template, another lists your numbers, another uploads media. It is also the clearest way to reproduce a bug. A saved request with the exact body and headers that fails can be run by a teammate, your provider's support team or Meta, without your application getting in the way.

04What is the WhatsApp Postman collection?

A Postman collection is a saved, shareable set of HTTP requests for the Postman API client. Meta publishes collections for the WhatsApp Business Platform in its public Postman workspace. They cover the Cloud API (sending each message type, uploading media, registering numbers) and management calls such as templates, phone numbers and business profiles. Each request already has the right method, path, headers and an example body.

The requests use variables instead of hard-coded values: the Graph API version, your phone number ID, your WABA ID, your access token and a test recipient. A matching Postman environment holds the actual values, so the same collection works for any account. Postman substitutes the variables just before sending. You can switch environments to point the same requests at a test app or a production app.

It differs from Graph API Explorer, Meta's browser tool that runs one query at a time with a token tied to the logged-in user. A collection lives in your workspace. It can be forked and version-controlled, and run as a sequence or in CI with Postman's command-line runner, using a long-lived system user token. Neither replaces your application code: both are for exploring, debugging and reproducing calls.

Key takeaways

  • Meta's WhatsApp Postman collection packages ready-made Cloud API and management requests that run without writing code.
  • Requests use variables such as {{Version}}, {{Phone-Number-ID}} and {{WABA-ID}}, filled in from a Postman environment.
  • Select the matching environment before sending. Otherwise every variable resolves to nothing and the requests fail.
  • The temporary token from API Setup expires after about 24 hours. Use a system user token for anything longer-lived.
  • Unlike Graph API Explorer, a collection is saved, shareable and runs with any token you give it.

05 · In code

The WhatsApp Postman collection in code

POST https://graph.facebook.com/{{Version}}/{{Phone-Number-ID}}/messages
Authorization: Bearer {{User-Access-Token}}
Content-Type: application/json
 
{
  "messaging_product": "whatsapp",
  "to": "{{Recipient-Phone-Number}}",
  "type": "template",
  "template": { "name": "hello_world", "language": { "code": "en_US" } }
}

Double-brace variables are resolved from the selected environment just before sending.

06Example: Debugging a failed send in Indore

An Indore D2C brand's developer sees sends failing from their backend with an unclear error. They open the forked collection, select the production environment and run the same template request. Postman shows error 131030: the recipient is not on the allowed list. The backend was still using the test phone number's ID, which can only message up to five pre-approved recipients. Changing the phone number ID variable to the production number makes the request succeed, and the same fix reaches the backend config within the hour.

07 · Mistakes to avoid

Common mistakes with the WhatsApp Postman collection

  • No environment selected

    Variables resolve to empty strings, and the URL becomes https://graph.facebook.com//messages. Pick the environment before sending, and check the resolved URL in the Postman console.

  • Expired temporary token

    The token copied from API Setup lasts about a day, after which calls fail with error 190. Generate a system user token for anything you will reuse.

  • Sharing a live token

    Exporting or sharing an environment includes its values. Mark tokens as secret, keep them out of shared values, and share collections rather than environments.

  • Test number, real customer

    The test phone number can only message its few pre-approved recipients, and anyone else returns error 131030. Switch the phone number ID variable to a registered production number.

  • Assuming the collection is your app

    A request that works in Postman proves the account is set up correctly. It does not prove your code builds the same body. Copy Postman's generated code snippet and diff it against what your app sends.

08 · Key facts

The WhatsApp Postman collection: key facts and limits

Publisher
Meta, public WhatsApp Business Platform workspace on postman.com
Covers
Cloud API sends, media, registration, templates, numbers, profiles
Key variables
Version, Phone-Number-ID, WABA-ID, access token, recipient
Temporary token lifetime
About 24 hours (API Setup panel)
Test number recipients
Up to 5 pre-approved numbers
Headless runs
Postman CLI or newman

09 · Pro tips

Best practices for the WhatsApp Postman collection

  • Keep one environment per app and number, for example staging and production.
  • Add a test script that saves the returned wamid to a variable for follow-up requests.
  • Use Postman's code generator to turn a working request into cURL, Node.js or Python.
  • Pull Meta's updates into your fork when new message types or Graph API versions arrive.

10Postman Collection FAQs

Where do I find the official WhatsApp Postman collection?+
It is in Meta's public WhatsApp Business Platform workspace on postman.com. Fork the Cloud API collection and its environment into your own workspace before editing them.
Why does my Postman request return error 131030?+
Your recipient is not on the test number's allowed list. A test phone number can only message a few pre-approved recipients, so add the recipient in API Setup or send from a registered production number.
Should I use Postman or Graph API Explorer?+
Use Postman for repeatable, shareable requests and sequences, and Graph API Explorer for a quick one-off query with your own user token. Many developers use both.
Which access token should I put in the Postman environment?+
For a quick test, the temporary token from API Setup works for about 24 hours. For anything ongoing, use a system user access token with the WhatsApp permissions, stored as a secret value.

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