Raphael Serafim· Publicado em 07 de agosto de 2026· 9 min de leitura

API não oficial do WhatsApp: recursos que a oficial não tem (com exemplos)

Recursos da API não oficial do WhatsApp (QR Code): botões, listas, enquete, figurinha, reação, grupos, status e Pix — com exemplos em cURL e Node.js.

Ver como Markdown

A API não oficial do WhatsApp conecta seu número por QR Code (como o WhatsApp Web) e, justamente por isso, libera recursos ricos que a API oficial da Meta não expõe da mesma forma: botões, listas, enquete, figurinha, reação, grupos, status e até mensagem de Pix. Neste guia você vê cada um desses recursos com exemplos prontos em cURL e Node.js, usando a base https://us.api-wa.me/{key}/.

Já publicamos um material conceitual sobre a API não oficial e um comparativo entre oficial e não oficial. Aqui o foco é diferente: recursos e código.

O que é a API não oficial (e por que ela tem mais recursos)

A API não oficial não passa pela WhatsApp Cloud API. Em vez disso, ela abre uma sessão do tipo WhatsApp Web através de uma conexão por QR Code ou código de pareamento. Como a sessão enxerga o WhatsApp como um aparelho conectado, ela consegue enviar tipos de mensagem que o app suporta nativamente — botões interativos, enquetes, figurinhas, reações — que a camada oficial trata de forma mais restrita.

Duas diferenças importantes na api-wa.me:

Sem criar app na Meta. Não há cadastro de número dedicado, templates pré-aprovados nem verificação de conta.
Sem self-host. Diferente de rodar Baileys ou Evolution API no seu servidor, aqui a infraestrutura é hospedada e gerenciada — 99,9% de uptime e suporte 24/7 em português. A plataforma existe desde 2017 e já passa de 50 mil instâncias.

A camada não oficial é independente e não é afiliada, endossada ou suportada pelo WhatsApp Inc. O uso vai contra os Termos de Serviço e é de responsabilidade de quem envia.

Conectar em minutos

A instância é identificada por uma key na própria URL — ela já serve de autenticação, sem header. Para gerar o QR Code:

# Gera o QR Code para conectar (escaneie em Aparelhos conectados)
curl -X POST "https://us.api-wa.me/SUA_KEY/instance"

Prefere não escanear? Use o código de pareamento, informando o número que vai conectar:

curl -X POST "https://us.api-wa.me/SUA_KEY/instance/pairing-code" \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "5511999999999" }'

No Node.js, o SDK oficial encapsula tudo:

import { Wame, TypeMessage } from '@raphaelvserafim/client-api-whatsapp';

const wa = new Wame({
  server: "https://us.api-wa.me",
  key: "SUA_KEY"
});

// Envio simples de texto com método de conveniência
await wa.message.sendText("5511999999999", "Olá! Conectado pela API.");

Repare que a key já autentica a chamada e que o número vai sempre no formato internacional, só com dígitos (código do país + DDD + número). Esse mesmo padrão vale para todos os recursos que veremos a seguir, o que torna a integração muito consistente: se você aprendeu a enviar um texto, já sabe a estrutura de qualquer outro tipo de mensagem.

Recursos ricos, com exemplos

Todos os endpoints abaixo são POST para https://us.api-wa.me/{key}/... com o header Content-Type: application/json. A ideia é mostrar, na prática, o que a conexão por QR Code libera além do texto simples — recursos interativos que aumentam a taxa de resposta e encurtam o caminho até a conversão.

Botões de resposta rápida

Ótimos para menus curtos e fluxos de atendimento — o cliente toca em vez de digitar.

curl -X POST "https://us.api-wa.me/SUA_KEY/message/button_reply" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "header": { "title": "Menu" },
    "text": "Escolha:",
    "buttons": [
      { "type": "quick_reply", "id": "1", "text": "Sim" },
      { "type": "quick_reply", "id": "2", "text": "Não" }
    ]
  }'

Botões de ação (CTA)

Para direcionar a uma ação externa, como abrir um site.

curl -X POST "https://us.api-wa.me/SUA_KEY/message/button_action" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "header": { "title": "Oferta" },
    "text": "Confira",
    "buttons": [
      { "type": "cta_url", "url": "https://api-wa.me", "text": "Acessar site" }
    ]
  }'

Mensagem de lista (menu)

Ideal para vários itens organizados em seções — catálogos, categorias, opções de suporte.

curl -X POST "https://us.api-wa.me/SUA_KEY/message/list" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "buttonText": "Ver opções",
    "text": "Selecione:",
    "sections": [
      {
        "title": "Serviços",
        "rows": [ { "title": "Suporte", "rowId": "support" } ]
      }
    ]
  }'

Enquete

Pesquisas rápidas direto no chat. Há duas formas — survey e poll:

# survey: enquete simples com opções
curl -X POST "https://us.api-wa.me/SUA_KEY/message/survey" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "name": "Você gosta de PHP?",
    "options": ["Sim", "Não"]
  }'

# poll: permite controlar quantas opções podem ser selecionadas
curl -X POST "https://us.api-wa.me/SUA_KEY/message/poll" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "name": "Cor favorita?",
    "values": ["Vermelho", "Azul"],
    "selectableCount": 1
  }'

Figurinha (sticker)

Envie uma figurinha a partir de uma imagem por URL.

curl -X POST "https://us.api-wa.me/SUA_KEY/message/sticker" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "url": "https://exemplo.com/img.png"
  }'

Reação

Reaja a uma mensagem existente com um emoji, usando o msgId recebido.

curl -X POST "https://us.api-wa.me/SUA_KEY/message/reaction" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "text": "👍",
    "msgId": "wamid.XXX"
  }'

Grupos

A camada não oficial expõe endpoints de grupos — criar grupo, listar e gerenciar participantes — algo que a Cloud API oficial não oferece. No SDK Node há o serviço wa.group para essas operações:

# Listar grupos da instância
curl -X GET "https://us.api-wa.me/SUA_KEY/groups"

# Criar um grupo
curl -X POST "https://us.api-wa.me/SUA_KEY/groups" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Equipe de Vendas", "participants": ["5511999999999"] }'

Status / Stories

Publique status (stories) de texto, imagem ou vídeo pelo seu número. No SDK Node, use o serviço wa.status para publicar programaticamente — útil para avisos e campanhas para quem já segue seu contato.

Pix

Um dos recursos mais poderosos para vendas: enviar uma mensagem de pagamento Pix direto no chat, com valor e chave.

curl -X POST "https://us.api-wa.me/SUA_KEY/message/pix" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "title": "Pizza",
    "text": "Pagamento",
    "referenceId": "apiwame",
    "key": "23711695000115",
    "merchantName": "MINHA EMPRESA",
    "keyType": "CNPJ",
    "subtotal": 90,
    "totalAmount": 100
  }'

No Node.js, além dos métodos de conveniência como wa.message.sendText(to, text) e wa.message.sendImage(...), os demais tipos seguem o mesmo padrão de payload dos exemplos em cURL acima — a estrutura enviada é a mesma.

Independência: uma camada não oficial

Vale reforçar: esses recursos existem porque a conexão é do tipo WhatsApp Web. Essa camada é independente e não é afiliada, endossada ou suportada pelo WhatsApp Inc. Como ela contraria os Termos de Serviço, o principal cuidado é de uso — evite disparo em massa para quem não pediu, respeite opt-in/opt-out e trate a API como extensão do seu atendimento, não como máquina de spam. Assim o número se mantém estável.

Quando a não oficial faz sentido (e quando não)

A não oficial brilha quando você quer recursos ricos e velocidade: menus com botões e listas, enquetes, figurinhas, reações, grupos e cobrança por Pix — sem burocracia da Meta e sem hospedar nada. É ideal para atendimento, vendas, notificações para quem já é cliente e MVPs que precisam validar rápido. Na prática, é a diferença entre o cliente digitar "quero a opção 2" e simplesmente tocar em um botão, ou entre pedir para ele fazer uma transferência e receber a cobrança Pix pronta dentro da própria conversa.

Se o seu caso exige garantia formal da Meta, altíssimo volume ou setores regulados, a API oficial é o caminho — e ela também está disponível na mesma plataforma. Para decidir com calma, veja o comparativo entre oficial e não oficial. Se ainda tem dúvidas conceituais, comece pelo guia da API não oficial.

Comece agora

A api-wa.me oferece oficial e não oficial na mesma plataforma, hospedada e gerenciada, a partir de R$28,99/mês, com suporte 24/7 em português. Crie sua conta no portal, conecte por QR Code e explore todos os endpoints na documentação da API. Do QR Code ao primeiro Pix enviado, leva minutos.

Pronto para automatizar seu WhatsApp?

Crie sua conta gratuita e comece a enviar mensagens pela API em minutos.

Começar grátis

Perguntas frequentes

O que é a API não oficial do WhatsApp?+

É uma interface que conecta seu número ao WhatsApp da mesma forma que o WhatsApp Web — por QR Code ou código de pareamento — e permite enviar e receber mensagens por código. Não exige criar um app na Meta nem aprovação de conta. Na api-wa.me ela é hospedada e gerenciada, sem precisar de self-host como Baileys ou Evolution.

Quais recursos a API não oficial tem que a oficial não tem?+

Por conectar como o WhatsApp Web, a camada não oficial libera recursos ricos que a Cloud API oficial não expõe da mesma forma: botões, mensagem de lista, enquete (poll/survey), figurinha (sticker), reação com emoji, criação e gestão de grupos, status/stories e mensagem de pagamento Pix.

Como conecto meu número por QR Code na API?+

Faça um POST em /{key}/instance para gerar o QR Code e escaneie em Aparelhos conectados no app do WhatsApp. Se preferir não usar QR, faça POST em /{key}/instance/pairing-code enviando o phoneNumber para receber um código de pareamento no próprio celular.

Preciso hospedar a API não oficial no meu servidor?+

Não. Diferente de rodar Baileys ou Evolution API por conta própria, na api-wa.me a infraestrutura é hospedada e gerenciada, com 99,9% de uptime e suporte 24/7 em português. Você só faz as chamadas HTTP para a base https://us.api-wa.me/{key}/.

A API não oficial é afiliada ao WhatsApp?+

Não. A camada não oficial é independente e não é afiliada, endossada ou suportada pelo WhatsApp Inc. Ela conecta como o WhatsApp Web e vai contra os Termos de Serviço, então o uso é de responsabilidade de quem envia. Para casos com garantia formal da Meta, use a API oficial.