How to test the WhatsApp API in Postman (with a ready-made collection)

Updated on October 29, 2026

To test the WhatsApp API in Postman you need three values (the Phone Number ID, an access token and a recipient number), an environment holding them as variables, and POST requests to https://graph.facebook.com/v26.0/{{phone_number_id}}/messages. Meta maintains a public Postman workspace with WhatsApp Business Platform collections, but a minimal collection of your own, with 5 or 6 requests, is usually easier to understand and to keep in version control. This guide covers both paths and includes JSON you can import right away.

Meta’s official collection or your own?

Meta publishes collections in the WhatsApp Business Platform workspace, under Meta’s Postman profile: postman.com/meta/workspace/whatsapp-business-platform. The link appears in a Meta for Developers blog post describing a collection that pre-fills environment variables and walks you through your first requests, and the Flows API documentation points to the Flows collection in the same workspace.

One caveat: the old “Postman Collection for WhatsApp Business APIs” page in Meta’s docs belonged to the On-Premises API, which has been sunset (its last version expired on October 23, 2025). Tutorials that tell you to import files from GitHub with a “WABiz” environment are about that old API.

The practical recommendation: use the official collection as a reference to discover endpoints, and build your own with the calls your team actually makes. Before you start, have your Phone Number ID handy; if you are not sure where it is, see where to find the Phone Number ID, WABA ID and App ID.

What you need before opening Postman

1. A Meta app with the WhatsApp use case and either a test number or your production number. Meta’s get started guide walks you through access.
2. The Phone Number ID of the sending number. It is shown in the app’s API Setup panel, according to Meta’s get started guide.
3. An access token. The Generate access token button in API Setup creates a temporary token, fine for a first test. For ongoing use, create a system user token as explained in WhatsApp API permanent access token.
4. A recipient number you control, in international format without + (e.g. 5511999999999 for a Brazilian mobile, or 14155550123 for a US one). With Meta’s test number, the recipient must be added in API Setup itself.

For the big picture, see the complete guide to the official WhatsApp API.

Want to try it while you read? Create a Vectalk account and send your first message through the official API. Create free account →

Step 1: create the environment

In Postman, an environment is a set of variables you pick in the top-right selector; only one is active at a time. You reference a variable by wrapping its name in double curly braces, like {{phone_number_id}}, and when the same name exists in more than one scope, the narrowest scope wins (Postman variables).

Save the JSON below as whatsapp-test.postman_environment.json and import it with the Import button. This is the format Postman uses when it exports an environment:

{
  "name": "WhatsApp - test",
  "values": [
    { "key": "graph_url", "value": "https://graph.facebook.com", "type": "default", "enabled": true },
    { "key": "version", "value": "v26.0", "type": "default", "enabled": true },
    { "key": "phone_number_id", "value": "", "type": "default", "enabled": true },
    { "key": "meta_token", "value": "", "type": "secret", "enabled": true },
    { "key": "vectalk_url", "value": "https://apis.vectalk.com.br/api", "type": "default", "enabled": true },
    { "key": "vectalk_token", "value": "", "type": "secret", "enabled": true },
    { "key": "to", "value": "5511999999999", "type": "default", "enabled": true }
  ],
  "_postman_variable_scope": "environment"
}

After importing, fill in phone_number_id, meta_token and to inside Postman, not in the file. According to the environments documentation, a variable’s local value is never synced to the Postman cloud or shared with your team unless you choose to share it. Mark the tokens as Secure so they are masked on screen.

Step 2: import the minimal collection

The collection below follows the Postman Collection v2.1 format (the info.schema field points to the official schema). It has two folders, one for Meta’s Cloud API and one for the Vectalk API, each with its own Bearer auth. A collection-level test script checks for HTTP 200 and stores the wamid of the last sent message in the last_wamid variable.

{
  "info": {
    "name": "WhatsApp API - tests",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "event": [{
    "listen": "test",
    "script": {
      "type": "text/javascript",
      "exec": [
        "pm.test('HTTP 200', () => pm.response.to.have.status(200));",
        "const body = pm.response.json();",
        "if (body.messages && body.messages[0]) {",
        "  pm.environment.set('last_wamid', body.messages[0].id);",
        "}"
      ]
    }
  }],
  "item": [
    {
      "name": "Meta (Cloud API)",
      "auth": { "type": "bearer", "bearer": [{ "key": "token", "value": "{{meta_token}}", "type": "string" }] },
      "item": [
        {
          "name": "Send text",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": "{{graph_url}}/{{version}}/{{phone_number_id}}/messages",
            "body": { "mode": "raw", "raw": "{\"messaging_product\": \"whatsapp\", \"to\": \"{{to}}\", \"type\": \"text\", \"text\": {\"body\": \"Test from Postman\"}}" }
          }
        },
        {
          "name": "Send hello_world template",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": "{{graph_url}}/{{version}}/{{phone_number_id}}/messages",
            "body": { "mode": "raw", "raw": "{\"messaging_product\": \"whatsapp\", \"to\": \"{{to}}\", \"type\": \"template\", \"template\": {\"name\": \"hello_world\", \"language\": {\"code\": \"en_US\"}}}" }
          }
        },
        {
          "name": "Send image by link",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": "{{graph_url}}/{{version}}/{{phone_number_id}}/messages",
            "body": { "mode": "raw", "raw": "{\"messaging_product\": \"whatsapp\", \"to\": \"{{to}}\", \"type\": \"image\", \"image\": {\"link\": \"https://example.com/test.jpg\", \"caption\": \"Test image\"}}" }
          }
        }
      ]
    },
    {
      "name": "Vectalk",
      "auth": { "type": "bearer", "bearer": [{ "key": "token", "value": "{{vectalk_token}}", "type": "string" }] },
      "item": [
        {
          "name": "Send text",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": "{{vectalk_url}}/messages",
            "body": { "mode": "raw", "raw": "{\"messaging_product\": \"whatsapp\", \"to\": \"{{to}}\", \"type\": \"text\", \"text\": {\"body\": \"Test from Postman\"}}" }
          }
        },
        { "name": "List templates", "request": { "method": "GET", "url": "{{vectalk_url}}/templates" } },
        { "name": "Phone number details", "request": { "method": "GET", "url": "{{vectalk_url}}/phone-numbers" } }
      ]
    }
  ]
}

Save it as whatsapp-api.postman_collection.json, import it, select the “WhatsApp – test” environment and run the requests in the order below.

Step 3: send your first message (a template)

Start with the hello_world template. It’s the template Meta’s getting-started guide uses for the test send and, because it is a template, it can go to someone who has never messaged your number: outside the 24-hour customer service window, only templates get through. This is the request body:

{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "hello_world",
    "language": { "code": "en_US" }
  }
}

If the send is accepted, the response follows the format in the send messages reference:

{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "5511999999999", "wa_id": "5511999999999" }],
  "messages": [{ "id": "wamid.HBgLNTUxMTk5OTk5OTk5...", "message_status": "accepted" }]
}

The message_status field only appears when the template you send is being paced (values accepted or held_for_quality_assessment). Keep in mind that a 200 means the API accepted the request, not that the message was delivered. Delivery is reported later through the status webhook (sent, delivered, read or failed); see message status via webhook. For templates with variables, header media and buttons, the next step is the guide on how to send a template through the WhatsApp API.

Step 4: text and media

Once you reply to the test message from your phone, the customer service window opens and the Send text and Send image by link requests start working. The text body is the simplest one in the API: type: "text" with the content in text.body.

For the image, replace https://example.com/test.jpg with a public HTTPS URL. Meta says the Cloud API caches assets sent by link for 10 minutes; if you change the image on your server and resend the same URL within that window, you may get the old version. To force a fresh download, append a random query string to the URL (e.g. ?v=2). Formats, size limits and sending by uploaded media id are covered in how to send images, PDFs, audio and video.

Step 5: read the errors

When something fails, the Cloud API returns an error object. According to Meta’s error codes page, it looks like this:

{
  "error": {
    "message": "(#130429) Rate limit hit",
    "type": "OAuthException",
    "code": 130429,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "Cloud API message throughput has been reached."
    },
    "fbtrace_id": "Az8or2yhqkZfEZ-_4Qn_Bam"
  }
}

The errors you will see most often while testing in Postman:

Code	Meaning	What to do
190	Access token expired	Generate a new token or use a system user token
10	Permission not granted or removed	Review the token’s permissions
100	Unsupported or misspelled parameter	Check the JSON and the Phone Number ID in the URL
131047	More than 24 hours since the customer last replied	Send a template
132000	Parameter count does not match the template	Fix the parameters
132001	Template does not exist in that language or is not approved	Check name and language.code
133010	Phone number not registered on the platform	Register the number first

Always keep the fbtrace_id: it is what Meta support asks for when investigating a case. The full list, with causes and fixes, is in WhatsApp API error codes, and template parameter errors have their own article, errors 132000 and 132012.

Tips to keep the collection tidy

• One environment per number or stage. “WhatsApp – test” and “WhatsApp – production” with the same keys keep you from firing a test from the real number.
• Never export the environment with the token filled in. If you commit it to Git, keep meta_token and vectalk_token empty in the file.
• Test the webhook in parallel. Postman shows the synchronous response; everything else (statuses and customer replies) arrives at your webhook. To receive events on your machine, see how to test the WhatsApp webhook locally with ngrok.

How to test the Vectalk API in Postman

Vectalk is a proxy for the WhatsApp Cloud API: message bodies are the same as Meta’s, only the base URL and the token change. The Vectalk folder in the collection already uses the routes from the Vectalk documentation:

• POST {{vectalk_url}}/messages sends any message type, with the same JSON as the Cloud API.
• GET {{vectalk_url}}/templates lists the account’s templates (accepts ?name= to filter).
• GET {{vectalk_url}}/phone-numbers returns the number’s details, such as verified name and quality_rating.

You create the token in the dashboard under Settings → API Tokens, and it is shown only once. Use an instance token: with it the phone_number_id is resolved automatically, and templates and media require this token type. With an organization token, you must send phone_number_id in the message body. Per the authentication page, 401 Unauthorized means a missing or invalid token, and 403 Forbidden means a valid token without permission for that resource, such as an organization token calling /templates.

On Vectalk, each delivered message is deducted from the platform’s prepaid balance, so tests on a real number also use balance. To create an account, go to apps.vectalk.com.br/register.

Frequently asked questions

Does Meta have an official WhatsApp collection in Postman?

Yes. Meta maintains the public “WhatsApp Business Platform” workspace in Postman, linked from the Meta for Developers blog and from the Flows API documentation. Fork it into your account and fill the environment with your own IDs and token.

Why do I get error 190 in Postman?

Your token expired. The token generated in API Setup is temporary; for frequent testing, create a system user token and update the meta_token variable.

Does a 200 in Postman mean the message was delivered?

No. A 200 means the API accepted the request. Delivery and read receipts arrive later through the status webhook.

---

Official sources checked on October 29, 2026: Get started (Meta), Send messages (Meta), Error codes (Meta), Flows API (Meta), On-Premises API sunset (Meta), Meta for Developers blog post on Postman, WhatsApp Business Platform workspace in Postman, Variables (Postman), Environment variables (Postman), Collection v2.1 schema (Postman), Quickstart (Vectalk), Authentication (Vectalk).