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.