A API do WhatsApp permite enviar muito além de texto: imagens, documentos, áudio, vídeo, localização, contatos, botões interativos e menus de lista — tudo por requisições HTTP para endpoints específicos. Todos seguem o mesmo padrão: um POST para https://us.api-wa.me/{key}/message/<tipo> com um corpo JSON. O destinatário (to) é sempre o número em formato internacional, só dígitos.

Este guia mostra os tipos mais usados, com exemplos prontos.

Mensagem de texto

curl -X POST "https://us.api-wa.me/SUA_KEY/message/text" \
  -H "Content-Type: application/json" \
  -d '{ "to": "5566996852025", "text": "Olá! Como posso ajudar?" }'

Imagem (e outras mídias)

Envie uma imagem a partir de uma URL pública, com legenda opcional:

curl -X POST "https://us.api-wa.me/SUA_KEY/message/image" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5566996852025",
    "url": "https://exemplo.com/foto.jpg",
    "caption": "Confira nosso novo produto"
  }'

Os mesmos campos valem para outros tipos de mídia, trocando apenas o endpoint:

Precisa enviar um arquivo local em vez de URL? Use as versões em base64: /{key}/message/base64/image, /base64/audio e /base64/document.

Botões de resposta rápida (quick reply)

Botões de resposta rápida mostram opções clicáveis que o cliente toca para responder:

curl -X POST "https://us.api-wa.me/SUA_KEY/message/button_reply" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5566996852025",
    "header": { "title": "Confirmação" },
    "text": "Deseja confirmar seu pedido?",
    "footer": "Escolha uma opção",
    "buttons": [
      { "type": "quick_reply", "id": "sim", "text": "Sim" },
      { "type": "quick_reply", "id": "nao", "text": "Não" }
    ]
  }'

Botões de ação (call to action)

Botões de ação levam o cliente a abrir um site, ligar ou copiar um código:

curl -X POST "https://us.api-wa.me/SUA_KEY/message/button_action" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5566996852025",
    "header": { "title": "Seu pedido" },
    "text": "Acompanhe ou fale com a gente",
    "footer": "Estamos à disposição",
    "buttons": [
      { "type": "cta_url", "url": "https://api-wa.me", "text": "Acessar site" },
      { "type": "cta_call", "phone_number": "+5566996852025", "text": "Ligar" },
      { "type": "cta_copy", "copy_code": "PED12345", "text": "Copiar código" }
    ]
  }'

Mensagem de lista (menu)

Listas são ótimas para menus de atendimento com várias opções:

curl -X POST "https://us.api-wa.me/SUA_KEY/message/list" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5566996852025",
    "title": "Atendimento",
    "description": "Selecione o que você precisa",
    "buttonText": "Ver opções",
    "footer": "api-wa.me",
    "sections": [
      {
        "title": "Suporte",
        "rows": [
          { "id": "2via", "title": "2ª via de boleto" },
          { "id": "status", "title": "Status do pedido" }
        ]
      }
    ]
  }'

Enviando com o SDK Node.js

Todos os tipos passam pelo mesmo método wa.message.send, mudando o type:

import { WhatsApp, TypeMessage } from "@raphaelvserafim/client-api-whatsapp";

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

// Texto
await wa.message.send(
  { type: TypeMessage.TEXT, body: { to: "5566996852025", text: "Olá!" } },
  false
);

// Imagem
await wa.message.send(
  {
    type: TypeMessage.IMAGE,
    body: { to: "5566996852025", url: "https://exemplo.com/foto.jpg", caption: "Novidade" },
  },
  false
);

// Botões de ação
await wa.message.send(
  {
    type: TypeMessage.BUTTON_ACTION,
    body: {
      to: "5566996852025",
      text: "Acompanhe seu pedido",
      buttons: [{ type: "quick_reply", id: "ok", text: "Ok" }],
    },
  },
  false
);

Próximos passos

• Veja todos os endpoints e parâmetros na documentação da API;
• Aprenda a conectar e enviar a primeira mensagem;
• Confira as boas práticas para evitar bloqueio antes de escalar os envios.

Perguntas frequentes

Como enviar uma mensagem de texto pela API do WhatsApp?+

Faça um POST para /{key}/message/text com o corpo JSON contendo 'to' (número em formato internacional) e 'text'. Exemplo: { "to": "5566996852025", "text": "Olá!" }.

Como enviar botões no WhatsApp pela API?+

Use o endpoint /{key}/message/button_action para botões de ação (abrir URL, ligar, copiar código) ou /{key}/message/button_reply para botões de resposta rápida (quick_reply). Cada botão tem um tipo, um texto e os campos específicos do tipo.

Como enviar imagem ou documento pela API do WhatsApp?+

Para imagem, use /{key}/message/image com 'to', 'url' (link público da imagem) e 'caption' opcional. Para documento, áudio e vídeo existem endpoints equivalentes (/message/document, /message/audio, /message/video). Também há versões em base64.

É possível enviar menus de lista pela API do WhatsApp?+

Sim. O endpoint /{key}/message/list envia uma mensagem de lista com título, descrição, texto do botão e seções com opções — ideal para menus de atendimento.

Continue lendo

Como enviar mensagens em massa no WhatsApp pela API sem ser bloqueado

Guia para disparar mensagens em massa no WhatsApp pela API com segurança: como evitar bloqueio do número, boas práticas de opt-in, aquecimento, personalização e intervalo entre envios. Com exemplo de código.

API de Instagram e Messenger na mesma API do WhatsApp: uma instância, um padrão

API de Instagram Direct e Messenger oficiais na mesma API do WhatsApp: uma instância, um padrão Meta, o campo provider escolhe o canal. Sem criar app na Meta.

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.