# Como enviar mensagens, botões, imagens e listas pela API do WhatsApp

> Aprenda a enviar pela API do WhatsApp: texto, imagem, documento, áudio, localização, botões interativos (resposta rápida e call to action) e mensagens de lista. Com exemplos de código em cURL e Node.js.

**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

```bash
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:

```bash
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:

| Mídia | Endpoint |
| --- | --- |
| Imagem | `/{key}/message/image` |
| Vídeo | `/{key}/message/video` |
| Áudio | `/{key}/message/audio` |
| Documento | `/{key}/message/document` |
| Localização | `/{key}/message/location` |
| Contato | `/{key}/message/contact` |

> 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:

```bash
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**:

```bash
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:

```bash
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`:

```ts
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](/docs);
- Aprenda a [conectar e enviar a primeira mensagem](/blog/como-criar-api-whatsapp);
- Confira as [boas práticas para evitar bloqueio](/blog/api-nao-oficial-whatsapp) 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.