# Guia da API do WhatsApp: endpoints essenciais e como usar

> Referência prática dos principais endpoints da API do WhatsApp: instância e conexão, envio de mensagens (texto, mídia, botões, listas), grupos, contatos e webhooks. Com a base URL e o padrão de autenticação.

**A API do WhatsApp da api-wa.me usa a base URL `https://us.api-wa.me` e o padrão `/{key}/...`, onde `{key}` é a chave da sua instância — que já serve de autenticação, sem precisar de header.** A partir daí, os endpoints se organizam em grupos: instância/conexão, mensagens, grupos, contatos e webhooks. Este guia resume os principais para você ter uma visão geral; a referência completa fica em [/docs](/docs).

## Conceitos básicos

- **Base URL:** `https://us.api-wa.me`
- **Autenticação:** a `key` da instância vai na URL — `https://us.api-wa.me/SUA_KEY/...`. Sem header.
- **Formato:** requisições JSON; números no formato internacional (só dígitos).

## Instância e conexão

| Método | Endpoint | O que faz |
| --- | --- | --- |
| `GET` | `/{key}/instance` | Status da conexão e QR Code |
| `POST` | `/{key}/instance` | Conectar (gera QR Code) |
| `POST` | `/{key}/instance/pairing-code` | Conectar por código de pareamento |
| `PUT` | `/{key}/instance` | Configurar webhooks |
| `PATCH` | `/{key}/instance` | Ajustes (auto-leitura, salvar mídia, etc.) |
| `DELETE` | `/{key}/instance` | Desconectar (logout) |

## Envio de mensagens

| Método | Endpoint | Tipo |
| --- | --- | --- |
| `POST` | `/{key}/message/text` | Texto |
| `POST` | `/{key}/message/image` | Imagem |
| `POST` | `/{key}/message/video` | Vídeo |
| `POST` | `/{key}/message/audio` | Áudio |
| `POST` | `/{key}/message/document` | Documento |
| `POST` | `/{key}/message/location` | Localização |
| `POST` | `/{key}/message/contact` | Contato |
| `POST` | `/{key}/message/button_reply` | Botões de resposta rápida |
| `POST` | `/{key}/message/button_action` | Botões de ação (URL/ligar/copiar) |
| `POST` | `/{key}/message/list` | Lista (menu) |
| `POST` | `/{key}/message/pix` | Pix |

Exemplo mínimo de envio 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á!" }'
```

Para os detalhes de cada tipo, veja [Como enviar mensagens, botões e mídia](/blog/como-enviar-mensagem-whatsapp-api).

## Grupos e contatos

| Método | Endpoint | O que faz |
| --- | --- | --- |
| `GET` | `/{key}/groups` | Listar grupos |
| `POST` | `/{key}/groups` | Criar grupo |
| `POST` | `/{key}/groups/{id}/participants` | Adicionar participantes |
| `GET` | `/{key}/contacts` | Listar contatos |
| `GET` | `/{key}/contacts/{number}` | Perfil do contato |
| `GET` | `/{key}/actions/registered` | Checar se o número tem WhatsApp |

## Webhooks (receber eventos)

Para receber mensagens e eventos em tempo real, configure os webhooks com `PUT /{key}/instance`:

```bash
curl -X PUT "https://us.api-wa.me/SUA_KEY/instance" \
  -H "Content-Type: application/json" \
  -d '{
    "allowWebhook": true,
    "allowNumber": "all",
    "webhookMessage": "https://seu-site.com/webhook",
    "webhookConnection": "https://seu-site.com/webhook"
  }'
```

Você pode definir URLs separadas por tipo de evento (mensagem, grupo, conexão, QR Code, mensagens enviadas por você, histórico) e filtrar por número com `allowNumber`.

## Acelere com contexto para IA

A api-wa.me oferece um arquivo `llms.txt` com toda a referência em formato otimizado para assistentes de IA. Cole no **Claude, ChatGPT ou Cursor** e peça ajuda para montar a integração — a IA já entende todos os endpoints.

## Próximos passos

- [Como criar e integrar uma API de WhatsApp](/blog/como-criar-api-whatsapp) — do zero ao primeiro envio;
- [Documentação completa](/docs) — todos os endpoints e parâmetros;
- [API não oficial do WhatsApp: é segura?](/blog/api-nao-oficial-whatsapp) — boas práticas.

## Perguntas frequentes

### Qual é a base URL da API do WhatsApp da api-wa.me?

A base URL é https://us.api-wa.me. Todos os endpoints seguem o padrão https://us.api-wa.me/{key}/... , onde {key} é a chave da sua instância.

### Como funciona a autenticação da API?

A autenticação é feita pela chave da instância (key) diretamente na URL, no formato /{key}/.... Não é necessário enviar header de autenticação.

### Quais são os principais endpoints da API do WhatsApp?

Os grupos principais são: instância e conexão (/{key}/instance), envio de mensagens (/{key}/message/text, /image, /button_action, /list, etc.), grupos (/{key}/groups), contatos (/{key}/contacts) e configuração de webhooks (PUT /{key}/instance).

### Onde encontro a documentação completa da API?

A documentação completa, com todos os endpoints e parâmetros, está em /docs. Há também um arquivo de contexto para IA (llms.txt) que você pode colar no Claude ou ChatGPT para acelerar a integração.