{"id":801,"date":"2026-10-29T13:31:19","date_gmt":"2026-10-29T13:31:19","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/api-whatsapp-postman\/"},"modified":"2026-10-29T13:31:27","modified_gmt":"2026-10-29T13:31:27","slug":"api-whatsapp-postman","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/api-whatsapp-postman\/","title":{"rendered":"Como testar a API do WhatsApp no Postman (com cole\u00e7\u00e3o pronta)"},"content":{"rendered":"\n

Atualizado em 29\/10\/2026<\/em><\/p>\n\n\n\n

Para testar a API do WhatsApp no Postman, voc\u00ea precisa de tr\u00eas dados (o Phone Number ID, um token de acesso e o n\u00famero de destino), um environment<\/em> com essas vari\u00e1veis e requisi\u00e7\u00f5es POST<\/code> para https:\/\/graph.facebook.com\/v26.0\/{{phone_number_id}}\/messages<\/code>. A Meta mant\u00e9m um workspace p\u00fablico no Postman com cole\u00e7\u00f5es da WhatsApp Business Platform, mas uma cole\u00e7\u00e3o m\u00ednima pr\u00f3pria, com 5 ou 6 requisi\u00e7\u00f5es, costuma ser mais f\u00e1cil de entender e de versionar. Este guia mostra os dois caminhos e traz o JSON pronto para importar.<\/p>\n\n\n\n

Cole\u00e7\u00e3o oficial da Meta ou cole\u00e7\u00e3o pr\u00f3pria?<\/h2>\n\n\n\n

A Meta publica cole\u00e7\u00f5es no workspace WhatsApp Business Platform<\/strong>, dentro do perfil da Meta no Postman: postman.com\/meta\/workspace\/whatsapp-business-platform<\/a>. O link aparece no an\u00fancio do blog de desenvolvedores da Meta<\/a>, que descreve uma cole\u00e7\u00e3o que pr\u00e9-preenche vari\u00e1veis de ambiente e guia as primeiras requisi\u00e7\u00f5es, e a documenta\u00e7\u00e3o da Flows API<\/a> aponta para a cole\u00e7\u00e3o de Flows no mesmo workspace.<\/p>\n\n\n\n

Um cuidado: a antiga p\u00e1gina “Postman Collection for WhatsApp Business APIs” da documenta\u00e7\u00e3o era da API On-Premises, que foi descontinuada (a \u00faltima vers\u00e3o expirou em 23\/10\/2025). Tutoriais que pedem para importar arquivos do GitHub com um environment “WABiz” s\u00e3o dessa API antiga.<\/p>\n\n\n\n

A recomenda\u00e7\u00e3o pr\u00e1tica: use a cole\u00e7\u00e3o oficial como refer\u00eancia para descobrir endpoints e monte a sua com o que o seu time realmente chama. Antes de come\u00e7ar, tenha em m\u00e3os o Phone Number ID; se n\u00e3o sabe onde ele fica, veja onde encontrar o Phone Number ID, o WABA ID e o App ID<\/a>.<\/p>\n\n\n\n

O que voc\u00ea precisa antes de abrir o Postman<\/h2>\n\n\n\n
    \n
  1. Um app na Meta com o caso de uso do WhatsApp<\/strong> e um n\u00famero de teste ou o seu n\u00famero de produ\u00e7\u00e3o. O passo a passo de acesso est\u00e1 no guia de primeiros passos da Meta.<\/li>\n\n\n
  2. O Phone Number ID<\/strong> do n\u00famero que vai enviar. Ele aparece no painel API Setup<\/strong> do app, segundo o guia de primeiros passos da Meta<\/a>.<\/li>\n\n\n
  3. Um token de acesso<\/strong>. O bot\u00e3o Generate access token<\/em> do API Setup gera um token tempor\u00e1rio, bom para o primeiro teste. Para uso cont\u00ednuo, gere um token de usu\u00e1rio do sistema, como explicado em token permanente da API do WhatsApp<\/a>.<\/li>\n\n\n
  4. Um n\u00famero de destino<\/strong> que voc\u00ea controla, no formato internacional sem +<\/code> (ex.: 5511999999999<\/code>). Com o n\u00famero de teste da Meta, o destinat\u00e1rio precisa ser cadastrado no pr\u00f3prio API Setup.<\/li>\n\n<\/ol>\n\n\n\n

    Para o contexto geral, veja o guia completo da API oficial do WhatsApp<\/a>.<\/p>\n\n\n\n

    Passo 1: crie o environment<\/h2>\n\n\n\n

    No Postman, um environment<\/em> \u00e9 um conjunto de vari\u00e1veis que voc\u00ea seleciona no canto superior direito; s\u00f3 um fica ativo por vez. Voc\u00ea referencia uma vari\u00e1vel escrevendo o nome entre chaves duplas, como {{phone_number_id}}<\/code>, e, se o mesmo nome existir em mais de um escopo, vale o de escopo mais estreito (vari\u00e1veis no Postman<\/a>).<\/p>\n\n\n\n

    Salve o JSON abaixo como whatsapp-teste.postman_environment.json<\/code> e importe pelo bot\u00e3o Import<\/strong>. \u00c9 o formato que o Postman usa ao exportar um environment:<\/p>\n\n\n\n

    {\n  \"name\": \"WhatsApp - teste\",\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
    Depois de importar, preencha phone_number_id<\/code>, meta_token<\/code> e to<\/code> direto no Postman, n\u00e3o no arquivo. Pela documenta\u00e7\u00e3o de environments<\/a>, o valor local de uma vari\u00e1vel n\u00e3o \u00e9 sincronizado com a nuvem do Postman nem compartilhado com o time, a menos que voc\u00ea escolha compartilhar. Marque os tokens como seguros (op\u00e7\u00e3o Secure<\/em>) para que n\u00e3o apare\u00e7am na tela.<\/p>\n\n\n\n
    Passo 2: importe a cole\u00e7\u00e3o m\u00ednima<\/h2>\n\n\n\n
    A cole\u00e7\u00e3o abaixo segue o formato Postman Collection v2.1<\/strong> (o campo info.schema<\/code> aponta para o schema oficial<\/a>). Ela tem duas pastas: uma para a Cloud API da Meta e outra para a API da Vectalk, cada uma com autentica\u00e7\u00e3o Bearer<\/em> pr\u00f3pria. Um script de teste na raiz confere o status 200 e guarda o wamid<\/code> da \u00faltima mensagem enviada na vari\u00e1vel last_wamid<\/code>.<\/p>\n\n\n\n
    {\n  \"info\": {\n    \"name\": \"WhatsApp API - testes\",\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\": \"Enviar texto\",\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\\\": \\\"Teste pelo Postman\\\"}}\" }\n          }\n        },\n        {\n          \"name\": \"Enviar template hello_world\",\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\": \"Enviar imagem por 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:\/\/exemplo.com.br\/teste.jpg\\\", \\\"caption\\\": \\\"Imagem de teste\\\"}}\" }\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\": \"Enviar texto\",\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\\\": \\\"Teste pelo Postman\\\"}}\" }\n          }\n        },\n        { \"name\": \"Listar templates\", \"request\": { \"method\": \"GET\", \"url\": \"{{vectalk_url}}\/templates\" } },\n        { \"name\": \"Dados do n\u00famero\", \"request\": { \"method\": \"GET\", \"url\": \"{{vectalk_url}}\/phone-numbers\" } }\n      ]\n    }\n  ]\n}<\/code><\/pre>\n\n\n\n
    Salve como whatsapp-api.postman_collection.json<\/code>, importe, selecione o environment “WhatsApp – teste” e rode as requisi\u00e7\u00f5es na ordem abaixo.<\/p>\n\n\n\n
    Passo 3: envie a primeira mensagem (template)<\/h2>\n\n\n\n
    Comece pelo template hello_world<\/code><\/strong>. \u00c9 o template que o guia de primeiros passos da Meta usa no envio de teste e, por ser template, pode ser enviado para quem ainda n\u00e3o falou com o n\u00famero: fora da janela de 24 horas de atendimento, s\u00f3 templates passam. O corpo enviado \u00e9 este:<\/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
    Se o envio for aceito, a resposta tem o formato descrito na refer\u00eancia de envio de mensagens<\/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
    O campo message_status<\/code> s\u00f3 aparece quando o template enviado est\u00e1 sob pacing (valores accepted<\/code> ou held_for_quality_assessment<\/code>). Aten\u00e7\u00e3o: o 200 significa que a API aceitou<\/strong> a requisi\u00e7\u00e3o, n\u00e3o que a mensagem foi entregue. A entrega chega depois, pelo webhook de status (sent<\/code>, delivered<\/code>, read<\/code> ou failed<\/code>); veja status de mensagem via webhook<\/a>. Para templates com vari\u00e1veis, m\u00eddia no cabe\u00e7alho e bot\u00f5es, o passo seguinte \u00e9 o guia de como enviar template pela API do WhatsApp<\/a>.<\/p>\n\n\n\n
    Passo 4: texto e m\u00eddia<\/h2>\n\n\n\n
    Depois que voc\u00ea responder a mensagem de teste no celular, a janela de atendimento abre e as requisi\u00e7\u00f5es Enviar texto<\/strong> e Enviar imagem por link<\/strong> passam a funcionar. O corpo de texto \u00e9 o mais simples da API: type: \"text\"<\/code> e o conte\u00fado em text.body<\/code>.<\/p>\n\n\n\n
    Na imagem, troque https:\/\/exemplo.com.br\/teste.jpg<\/code> por uma URL p\u00fablica HTTPS. A Meta informa que a Cloud API guarda em cache por 10 minutos o arquivo enviado por link; se voc\u00ea trocar a imagem no servidor e reenviar com a mesma URL dentro desse prazo, pode receber a vers\u00e3o antiga. Para for\u00e7ar o download, acrescente um par\u00e2metro aleat\u00f3rio na URL (ex.: ?v=2<\/code>). Formatos, limites de tamanho e envio por id<\/code> de upload est\u00e3o no guia de como enviar imagem, PDF, \u00e1udio e v\u00eddeo<\/a>.<\/p>\n\n\n\n
    Passo 5: leia os erros<\/h2>\n\n\n\n
    Quando algo falha, a Cloud API devolve um objeto error<\/code>. O formato, segundo a p\u00e1gina de c\u00f3digos de erro da Meta<\/a>, \u00e9 este:<\/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
    Os erros que mais aparecem em testes no Postman:<\/p>\n\n\n\n
    C\u00f3digo<\/th>O que significa<\/th>O que fazer<\/th><\/tr><\/thead>
    190<\/code><\/td>Token expirado<\/td>Gere um token novo ou use token de usu\u00e1rio do sistema<\/td><\/tr>
    10<\/code><\/td>Permiss\u00e3o n\u00e3o concedida ou removida<\/td>Revise as permiss\u00f5es do token<\/td><\/tr>
    100<\/code><\/td>Par\u00e2metro inexistente ou com erro de digita\u00e7\u00e3o<\/td>Confira o JSON e o Phone Number ID na URL<\/td><\/tr>
    131047<\/code><\/td>Passou de 24 horas desde a \u00faltima resposta do cliente<\/td>Envie um template<\/td><\/tr>
    132000<\/code><\/td>N\u00famero de vari\u00e1veis n\u00e3o bate com o template<\/td>Ajuste os parameters<\/code><\/td><\/tr>
    132001<\/code><\/td>Template n\u00e3o existe nesse idioma ou n\u00e3o foi aprovado<\/td>Confira name<\/code> e language.code<\/code><\/td><\/tr>
    133010<\/code><\/td>N\u00famero n\u00e3o registrado na plataforma<\/td>Registre o n\u00famero antes<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    Guarde sempre o fbtrace_id<\/code>: \u00e9 o que o suporte da Meta pede para investigar um caso. A lista completa, com causas e corre\u00e7\u00f5es, est\u00e1 em erros da API do WhatsApp<\/a>, e os erros de par\u00e2metro de template t\u00eam um artigo pr\u00f3prio, erros 132000 e 132012<\/a>.<\/p>\n\n\n\n
    Dicas para a cole\u00e7\u00e3o n\u00e3o virar bagun\u00e7a<\/h2>\n\n\n\n