API do WhatsApp no Postman: coleção pronta

Atualizado em 29/10/2026

Para testar a API do WhatsApp no Postman, você precisa de três dados (o Phone Number ID, um token de acesso e o número de destino), um environment com essas variáveis e requisições POST para https://graph.facebook.com/v26.0/{{phone_number_id}}/messages. A Meta mantém um workspace público no Postman com coleções da WhatsApp Business Platform, mas uma coleção mínima própria, com 5 ou 6 requisições, costuma ser mais fácil de entender e de versionar. Este guia mostra os dois caminhos e traz o JSON pronto para importar.

Coleção oficial da Meta ou coleção própria?

A Meta publica coleções no workspace WhatsApp Business Platform, dentro do perfil da Meta no Postman: postman.com/meta/workspace/whatsapp-business-platform. O link aparece no anúncio do blog de desenvolvedores da Meta, que descreve uma coleção que pré-preenche variáveis de ambiente e guia as primeiras requisições, e a documentação da Flows API aponta para a coleção de Flows no mesmo workspace.

Um cuidado: a antiga página “Postman Collection for WhatsApp Business APIs” da documentação era da API On-Premises, que foi descontinuada (a última versão expirou em 23/10/2025). Tutoriais que pedem para importar arquivos do GitHub com um environment “WABiz” são dessa API antiga.

A recomendação prática: use a coleção oficial como referência para descobrir endpoints e monte a sua com o que o seu time realmente chama. Antes de começar, tenha em mãos o Phone Number ID; se não sabe onde ele fica, veja onde encontrar o Phone Number ID, o WABA ID e o App ID.

O que você precisa antes de abrir o Postman

Um app na Meta com o caso de uso do WhatsApp e um número de teste ou o seu número de produção. O passo a passo de acesso está no guia de primeiros passos da Meta.
O Phone Number ID do número que vai enviar. Ele aparece no painel API Setup do app, segundo o guia de primeiros passos da Meta.
Um token de acesso. O botão Generate access token do API Setup gera um token temporário, bom para o primeiro teste. Para uso contínuo, gere um token de usuário do sistema, como explicado em token permanente da API do WhatsApp.
Um número de destino que você controla, no formato internacional sem + (ex.: 5511999999999). Com o número de teste da Meta, o destinatário precisa ser cadastrado no próprio API Setup.

Para o contexto geral, veja o guia completo da API oficial do WhatsApp.

Quer testar enquanto lê? Crie sua conta na Vectalk e envie a primeira mensagem pela API oficial. Criar conta grátis →

Passo 1: crie o environment

No Postman, um environment é um conjunto de variáveis que você seleciona no canto superior direito; só um fica ativo por vez. Você referencia uma variável escrevendo o nome entre chaves duplas, como {{phone_number_id}}, e, se o mesmo nome existir em mais de um escopo, vale o de escopo mais estreito (variáveis no Postman).

Salve o JSON abaixo como whatsapp-teste.postman_environment.json e importe pelo botão Import. É o formato que o Postman usa ao exportar um environment:

{
  "name": "WhatsApp - teste",
  "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"
}

Depois de importar, preencha phone_number_id, meta_token e to direto no Postman, não no arquivo. Pela documentação de environments, o valor local de uma variável não é sincronizado com a nuvem do Postman nem compartilhado com o time, a menos que você escolha compartilhar. Marque os tokens como seguros (opção Secure) para que não apareçam na tela.

Passo 2: importe a coleção mínima

A coleção abaixo segue o formato Postman Collection v2.1 (o campo info.schema aponta para o schema oficial). Ela tem duas pastas: uma para a Cloud API da Meta e outra para a API da Vectalk, cada uma com autenticação Bearer própria. Um script de teste na raiz confere o status 200 e guarda o wamid da última mensagem enviada na variável last_wamid.

{
  "info": {
    "name": "WhatsApp API - testes",
    "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": "Enviar texto",
          "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\": \"Teste pelo Postman\"}}" }
          }
        },
        {
          "name": "Enviar template hello_world",
          "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": "Enviar imagem por 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://exemplo.com.br/teste.jpg\", \"caption\": \"Imagem de teste\"}}" }
          }
        }
      ]
    },
    {
      "name": "Vectalk",
      "auth": { "type": "bearer", "bearer": [{ "key": "token", "value": "{{vectalk_token}}", "type": "string" }] },
      "item": [
        {
          "name": "Enviar texto",
          "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\": \"Teste pelo Postman\"}}" }
          }
        },
        { "name": "Listar templates", "request": { "method": "GET", "url": "{{vectalk_url}}/templates" } },
        { "name": "Dados do número", "request": { "method": "GET", "url": "{{vectalk_url}}/phone-numbers" } }
      ]
    }
  ]
}

Salve como whatsapp-api.postman_collection.json, importe, selecione o environment “WhatsApp – teste” e rode as requisições na ordem abaixo.

Passo 3: envie a primeira mensagem (template)

Comece pelo template hello_world. É 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ão falou com o número: fora da janela de 24 horas de atendimento, só templates passam. O corpo enviado é este:

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

Se o envio for aceito, a resposta tem o formato descrito na referência de envio de mensagens:

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

O campo message_status só aparece quando o template enviado está sob pacing (valores accepted ou held_for_quality_assessment). Atenção: o 200 significa que a API aceitou a requisição, não que a mensagem foi entregue. A entrega chega depois, pelo webhook de status (sent, delivered, read ou failed); veja status de mensagem via webhook. Para templates com variáveis, mídia no cabeçalho e botões, o passo seguinte é o guia de como enviar template pela API do WhatsApp.

Passo 4: texto e mídia

Depois que você responder a mensagem de teste no celular, a janela de atendimento abre e as requisições Enviar texto e Enviar imagem por link passam a funcionar. O corpo de texto é o mais simples da API: type: "text" e o conteúdo em text.body.

Na imagem, troque https://exemplo.com.br/teste.jpg por uma URL pública HTTPS. A Meta informa que a Cloud API guarda em cache por 10 minutos o arquivo enviado por link; se você trocar a imagem no servidor e reenviar com a mesma URL dentro desse prazo, pode receber a versão antiga. Para forçar o download, acrescente um parâmetro aleatório na URL (ex.: ?v=2). Formatos, limites de tamanho e envio por id de upload estão no guia de como enviar imagem, PDF, áudio e vídeo.

Passo 5: leia os erros

Quando algo falha, a Cloud API devolve um objeto error. O formato, segundo a página de códigos de erro da Meta, é este:

{
  "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"
  }
}

Os erros que mais aparecem em testes no Postman:

Código	O que significa	O que fazer
`190`	Token expirado	Gere um token novo ou use token de usuário do sistema
`10`	Permissão não concedida ou removida	Revise as permissões do token
`100`	Parâmetro inexistente ou com erro de digitação	Confira o JSON e o Phone Number ID na URL
`131047`	Passou de 24 horas desde a última resposta do cliente	Envie um template
`132000`	Número de variáveis não bate com o template	Ajuste os `parameters`
`132001`	Template não existe nesse idioma ou não foi aprovado	Confira `name` e `language.code`
`133010`	Número não registrado na plataforma	Registre o número antes

Guarde sempre o fbtrace_id: é o que o suporte da Meta pede para investigar um caso. A lista completa, com causas e correções, está em erros da API do WhatsApp, e os erros de parâmetro de template têm um artigo próprio, erros 132000 e 132012.

Dicas para a coleção não virar bagunça

Um environment por número ou ambiente. “WhatsApp – teste” e “WhatsApp – produção” com as mesmas chaves evitam disparar um teste pelo número real.
Nunca exporte o environment com o token preenchido. Se for versionar no Git, mantenha meta_token e vectalk_token vazios no arquivo.
Teste o webhook em paralelo. O Postman mostra a resposta síncrona; o resto (status e respostas do cliente) chega no webhook. Para receber os eventos na sua máquina, veja como testar o webhook localmente com ngrok.

Como testar a API da Vectalk no Postman

A Vectalk é um proxy da WhatsApp Cloud API: o corpo das mensagens é o mesmo da Meta, só mudam a URL base e o token. A pasta Vectalk da coleção já usa as rotas da documentação da Vectalk:

POST {{vectalk_url}}/messages envia qualquer tipo de mensagem, com o mesmo JSON da Cloud API.
GET {{vectalk_url}}/templates lista os templates da conta (aceita ?name= para filtrar).
GET {{vectalk_url}}/phone-numbers traz os dados do número, como nome verificado e quality_rating.

O token é criado no painel em Configurações → API Tokens e só aparece uma vez. Use um token de instância: com ele o phone_number_id é resolvido automaticamente, e templates e mídia exigem esse tipo de token. Com um token de organização, você precisa mandar phone_number_id no corpo do envio. Pela página de autenticação, 401 Unauthorized indica token ausente ou inválido e 403 Forbidden indica token válido sem permissão para o recurso, como um token de organização chamando /templates.

Na Vectalk, cada mensagem entregue desconta do saldo pré-pago da plataforma, então os testes no número real também consomem saldo. Para criar a conta, acesse apps.vectalk.com.br/register.

Perguntas frequentes

A Meta tem uma coleção oficial do WhatsApp no Postman?

Sim. A Meta mantém o workspace público “WhatsApp Business Platform” no Postman, linkado no blog de desenvolvedores da Meta e na documentação da Flows API. Faça um fork para a sua conta e preencha o environment com os seus IDs e token.

Por que recebo erro 190 no Postman?

O token expirou. O token gerado no API Setup é temporário; para testes frequentes, crie um token de usuário do sistema e atualize a variável meta_token.

O 200 no Postman garante que a mensagem foi entregue?

Não. O 200 indica que a API aceitou a requisição. A entrega e a leitura são informadas depois pelo webhook de status.

Fontes oficiais consultadas em 29/10/2026: Get started (Meta), Send messages (Meta), Error codes (Meta), Flows API (Meta), On-Premises API sunset (Meta), Blog de desenvolvedores da Meta sobre o Postman, Workspace WhatsApp Business Platform no Postman, Variáveis (Postman), Environment variables (Postman), Schema Collection v2.1 (Postman), Guia rápido (Vectalk), Autenticação (Vectalk).

Coloque o WhatsApp oficial da sua empresa para funcionar

Crie sua conta, conecte seu número à API oficial (dá para manter o app com coexistência) e comece a atender e enviar mensagens.

Criar conta grátis

Ler a documentação

Como testar a API do WhatsApp no Postman (com coleção pronta)