{"id":802,"date":"2026-10-29T13:31:21","date_gmt":"2026-10-29T13:31:21","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/whatsapp-api-postman\/"},"modified":"2026-10-29T13:31:31","modified_gmt":"2026-10-29T13:31:31","slug":"whatsapp-api-postman","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/en\/whatsapp-api-postman\/","title":{"rendered":"How to test the WhatsApp API in Postman (with a ready-made collection)"},"content":{"rendered":"\n

Updated on October 29, 2026<\/em><\/p>\n\n\n\n

To test the WhatsApp API in Postman you need three values (the Phone Number ID, an access token and a recipient number), an environment<\/em> holding them as variables, and POST<\/code> requests to https:\/\/graph.facebook.com\/v26.0\/{{phone_number_id}}\/messages<\/code>. 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.<\/p>\n\n\n\n

Meta’s official collection or your own?<\/h2>\n\n\n\n

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

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.<\/p>\n\n\n\n

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<\/a>.<\/p>\n\n\n\n

What you need before opening Postman<\/h2>\n\n\n\n
    \n
  1. A Meta app with the WhatsApp use case<\/strong> and either a test number or your production number. Meta’s get started guide walks you through access.<\/li>\n\n\n
  2. The Phone Number ID<\/strong> of the sending number. It is shown in the app’s API Setup<\/strong> panel, according to Meta’s get started guide<\/a>.<\/li>\n\n\n
  3. An access token<\/strong>. The Generate access token<\/em> 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<\/a>.<\/li>\n\n\n
  4. A recipient number<\/strong> you control, in international format without +<\/code> (e.g. 5511999999999<\/code> for a Brazilian mobile, or 14155550123<\/code> for a US one). With Meta’s test number, the recipient must be added in API Setup itself.<\/li>\n\n<\/ol>\n\n\n\n

    For the big picture, see the complete guide to the official WhatsApp API<\/a>.<\/p>\n\n\n\n

    Step 1: create the environment<\/h2>\n\n\n\n

    In Postman, an environment<\/em> 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}}<\/code>, and when the same name exists in more than one scope, the narrowest scope wins (Postman variables<\/a>).<\/p>\n\n\n\n

    Save the JSON below as whatsapp-test.postman_environment.json<\/code> and import it with the Import<\/strong> button. This is the format Postman uses when it exports an environment:<\/p>\n\n\n\n

    {\n  \"name\": \"WhatsApp - test\",\n  \"values\": [\n    { \"key\": \"graph_url\", \"value\": \"https:\/\/graph.facebook.com\", \"type\": \"default\", \"enabled\": true },\n    { \"key\": \"version\", \"value\": \"v26.0\", \"type\": \"default\", \"enabled\": true },\n    { \"key\": \"phone_number_id\", \"value\": \"\", \"type\": \"default\", \"enabled\": true },\n    { \"key\": \"meta_token\", \"value\": \"\", \"type\": \"secret\", \"enabled\": true },\n    { \"key\": \"vectalk_url\", \"value\": \"https:\/\/apis.vectalk.com.br\/api\", \"type\": \"default\", \"enabled\": true },\n    { \"key\": \"vectalk_token\", \"value\": \"\", \"type\": \"secret\", \"enabled\": true },\n    { \"key\": \"to\", \"value\": \"5511999999999\", \"type\": \"default\", \"enabled\": true }\n  ],\n  \"_postman_variable_scope\": \"environment\"\n}<\/code><\/pre>\n\n\n\n
    After importing, fill in phone_number_id<\/code>, meta_token<\/code> and to<\/code> inside Postman, not in the file. According to the environments documentation<\/a>, 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<\/em> so they are masked on screen.<\/p>\n\n\n\n
    Step 2: import the minimal collection<\/h2>\n\n\n\n
    The collection below follows the Postman Collection v2.1<\/strong> format (the info.schema<\/code> field points to the official schema<\/a>). It has two folders, one for Meta’s Cloud API and one for the Vectalk API, each with its own Bearer<\/em> auth. A collection-level test script checks for HTTP 200 and stores the wamid<\/code> of the last sent message in the last_wamid<\/code> variable.<\/p>\n\n\n\n
    {\n  \"info\": {\n    \"name\": \"WhatsApp API - tests\",\n    \"schema\": \"https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json\"\n  },\n  \"event\": [{\n    \"listen\": \"test\",\n    \"script\": {\n      \"type\": \"text\/javascript\",\n      \"exec\": [\n        \"pm.test('HTTP 200', () => pm.response.to.have.status(200));\",\n        \"const body = pm.response.json();\",\n        \"if (body.messages && body.messages[0]) {\",\n        \"  pm.environment.set('last_wamid', body.messages[0].id);\",\n        \"}\"\n      ]\n    }\n  }],\n  \"item\": [\n    {\n      \"name\": \"Meta (Cloud API)\",\n      \"auth\": { \"type\": \"bearer\", \"bearer\": [{ \"key\": \"token\", \"value\": \"{{meta_token}}\", \"type\": \"string\" }] },\n      \"item\": [\n        {\n          \"name\": \"Send text\",\n          \"request\": {\n            \"method\": \"POST\",\n            \"header\": [{ \"key\": \"Content-Type\", \"value\": \"application\/json\" }],\n            \"url\": \"{{graph_url}}\/{{version}}\/{{phone_number_id}}\/messages\",\n            \"body\": { \"mode\": \"raw\", \"raw\": \"{\\\"messaging_product\\\": \\\"whatsapp\\\", \\\"to\\\": \\\"{{to}}\\\", \\\"type\\\": \\\"text\\\", \\\"text\\\": {\\\"body\\\": \\\"Test from Postman\\\"}}\" }\n          }\n        },\n        {\n          \"name\": \"Send hello_world template\",\n          \"request\": {\n            \"method\": \"POST\",\n            \"header\": [{ \"key\": \"Content-Type\", \"value\": \"application\/json\" }],\n            \"url\": \"{{graph_url}}\/{{version}}\/{{phone_number_id}}\/messages\",\n            \"body\": { \"mode\": \"raw\", \"raw\": \"{\\\"messaging_product\\\": \\\"whatsapp\\\", \\\"to\\\": \\\"{{to}}\\\", \\\"type\\\": \\\"template\\\", \\\"template\\\": {\\\"name\\\": \\\"hello_world\\\", \\\"language\\\": {\\\"code\\\": \\\"en_US\\\"}}}\" }\n          }\n        },\n        {\n          \"name\": \"Send image by link\",\n          \"request\": {\n            \"method\": \"POST\",\n            \"header\": [{ \"key\": \"Content-Type\", \"value\": \"application\/json\" }],\n            \"url\": \"{{graph_url}}\/{{version}}\/{{phone_number_id}}\/messages\",\n            \"body\": { \"mode\": \"raw\", \"raw\": \"{\\\"messaging_product\\\": \\\"whatsapp\\\", \\\"to\\\": \\\"{{to}}\\\", \\\"type\\\": \\\"image\\\", \\\"image\\\": {\\\"link\\\": \\\"https:\/\/example.com\/test.jpg\\\", \\\"caption\\\": \\\"Test image\\\"}}\" }\n          }\n        }\n      ]\n    },\n    {\n      \"name\": \"Vectalk\",\n      \"auth\": { \"type\": \"bearer\", \"bearer\": [{ \"key\": \"token\", \"value\": \"{{vectalk_token}}\", \"type\": \"string\" }] },\n      \"item\": [\n        {\n          \"name\": \"Send text\",\n          \"request\": {\n            \"method\": \"POST\",\n            \"header\": [{ \"key\": \"Content-Type\", \"value\": \"application\/json\" }],\n            \"url\": \"{{vectalk_url}}\/messages\",\n            \"body\": { \"mode\": \"raw\", \"raw\": \"{\\\"messaging_product\\\": \\\"whatsapp\\\", \\\"to\\\": \\\"{{to}}\\\", \\\"type\\\": \\\"text\\\", \\\"text\\\": {\\\"body\\\": \\\"Test from Postman\\\"}}\" }\n          }\n        },\n        { \"name\": \"List templates\", \"request\": { \"method\": \"GET\", \"url\": \"{{vectalk_url}}\/templates\" } },\n        { \"name\": \"Phone number details\", \"request\": { \"method\": \"GET\", \"url\": \"{{vectalk_url}}\/phone-numbers\" } }\n      ]\n    }\n  ]\n}<\/code><\/pre>\n\n\n\n
    Save it as whatsapp-api.postman_collection.json<\/code>, import it, select the “WhatsApp – test” environment and run the requests in the order below.<\/p>\n\n\n\n
    Step 3: send your first message (a template)<\/h2>\n\n\n\n
    Start with the hello_world<\/code> template<\/strong>. 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:<\/p>\n\n\n\n
    {\n  \"messaging_product\": \"whatsapp\",\n  \"to\": \"5511999999999\",\n  \"type\": \"template\",\n  \"template\": {\n    \"name\": \"hello_world\",\n    \"language\": { \"code\": \"en_US\" }\n  }\n}<\/code><\/pre>\n\n\n\n
    If the send is accepted, the response follows the format in the send messages reference<\/a>:<\/p>\n\n\n\n
    {\n  \"messaging_product\": \"whatsapp\",\n  \"contacts\": [{ \"input\": \"5511999999999\", \"wa_id\": \"5511999999999\" }],\n  \"messages\": [{ \"id\": \"wamid.HBgLNTUxMTk5OTk5OTk5...\", \"message_status\": \"accepted\" }]\n}<\/code><\/pre>\n\n\n\n
    The message_status<\/code> field only appears when the template you send is being paced (values accepted<\/code> or held_for_quality_assessment<\/code>). Keep in mind that a 200 means the API accepted<\/strong> the request, not that the message was delivered. Delivery is reported later through the status webhook (sent<\/code>, delivered<\/code>, read<\/code> or failed<\/code>); see message status via webhook<\/a>. For templates with variables, header media and buttons, the next step is the guide on how to send a template through the WhatsApp API<\/a>.<\/p>\n\n\n\n
    Step 4: text and media<\/h2>\n\n\n\n
    Once you reply to the test message from your phone, the customer service window opens and the Send text<\/strong> and Send image by link<\/strong> requests start working. The text body is the simplest one in the API: type: \"text\"<\/code> with the content in text.body<\/code>.<\/p>\n\n\n\n
    For the image, replace https:\/\/example.com\/test.jpg<\/code> 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<\/code>). Formats, size limits and sending by uploaded media id<\/code> are covered in how to send images, PDFs, audio and video<\/a>.<\/p>\n\n\n\n
    Step 5: read the errors<\/h2>\n\n\n\n
    When something fails, the Cloud API returns an error<\/code> object. According to Meta’s error codes page<\/a>, it looks like this:<\/p>\n\n\n\n
    {\n  \"error\": {\n    \"message\": \"(#130429) Rate limit hit\",\n    \"type\": \"OAuthException\",\n    \"code\": 130429,\n    \"error_data\": {\n      \"messaging_product\": \"whatsapp\",\n      \"details\": \"Cloud API message throughput has been reached.\"\n    },\n    \"fbtrace_id\": \"Az8or2yhqkZfEZ-_4Qn_Bam\"\n  }\n}<\/code><\/pre>\n\n\n\n
    The errors you will see most often while testing in Postman:<\/p>\n\n\n\n
    Code<\/th>Meaning<\/th>What to do<\/th><\/tr><\/thead>
    190<\/code><\/td>Access token expired<\/td>Generate a new token or use a system user token<\/td><\/tr>
    10<\/code><\/td>Permission not granted or removed<\/td>Review the token’s permissions<\/td><\/tr>
    100<\/code><\/td>Unsupported or misspelled parameter<\/td>Check the JSON and the Phone Number ID in the URL<\/td><\/tr>
    131047<\/code><\/td>More than 24 hours since the customer last replied<\/td>Send a template<\/td><\/tr>
    132000<\/code><\/td>Parameter count does not match the template<\/td>Fix the parameters<\/code><\/td><\/tr>
    132001<\/code><\/td>Template does not exist in that language or is not approved<\/td>Check name<\/code> and language.code<\/code><\/td><\/tr>
    133010<\/code><\/td>Phone number not registered on the platform<\/td>Register the number first<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    Always keep the fbtrace_id<\/code>: it is what Meta support asks for when investigating a case. The full list, with causes and fixes, is in WhatsApp API error codes<\/a>, and template parameter errors have their own article, errors 132000 and 132012<\/a>.<\/p>\n\n\n\n
    Tips to keep the collection tidy<\/h2>\n\n\n\n