> ## Documentation Index
> Fetch the complete documentation index at: https://docs.escrybe.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp

> Envie mensagens por modelo com carimbo de tempo, gerenciando remetentes e modelos.

A API de WhatsApp envia **mensagens por modelo** pela WhatsApp Cloud API. Cada
mensagem pode ter um carimbo de tempo certificado RFC 3161 como prova legal.

<Note>
  Todos os endpoints de WhatsApp usam **HTTP Basic Auth** —
  `usuário = e-mail da conta`, `senha = securityToken`. Veja
  [Autenticação](/pt/autenticacao).
</Note>

## Conceitos

* **Remetente (sender)** — um número do WhatsApp Business que você conecta (ou um
  número de sistema fornecido pela Escrybe). Gerenciado em *Remetentes*.
* **Modelo (template)** — uma estrutura de mensagem pré-aprovada (exige aprovação
  da Meta). Gerenciado em *Modelos*.
* **Mensagem** — um envio vinculado a um modelo e a um destinatário.

## Endpoints

| Método   | Caminho                                        | Descrição                           |
| -------- | ---------------------------------------------- | ----------------------------------- |
| `POST`   | `/api/whatsapp/v1/post`                        | Enviar uma mensagem                 |
| `GET`    | `/api/whatsapp/v1/get`                         | Listar / consultar mensagens        |
| `POST`   | `/api/whatsapp/v1/cancel`                      | Cancelar uma mensagem               |
| `POST`   | `/api/whatsapp/v1/process`                     | Reprocessar após adicionar créditos |
| `GET`    | `/api/whatsapp/v1/download_attestation_bundle` | Baixar pacote de atestação          |
| `GET`    | `/api/whatsapp/v1/senders/get`                 | Listar remetentes                   |
| `POST`   | `/api/whatsapp/v1/senders/post`                | Criar / atualizar remetente         |
| `POST`   | `/api/whatsapp/v1/senders/toggle`              | Alterar status do remetente         |
| `POST`   | `/api/whatsapp/v1/senders/sync_templates`      | Sincronizar modelos da Meta         |
| `GET`    | `/api/whatsapp/v1/templates/get`               | Listar modelos                      |
| `POST`   | `/api/whatsapp/v1/templates/post`              | Criar um modelo                     |
| `PUT`    | `/api/whatsapp/v1/templates/put`               | Atualizar um modelo                 |
| `DELETE` | `/api/whatsapp/v1/templates/delete`            | Remover um modelo                   |

Os schemas completos estão na aba **Referência da API**.

## Enviando uma mensagem

```bash theme={null}
curl -X POST "https://app.escrybe.com.br/api/whatsapp/v1/post" \
  -u "voce@exemplo.com:SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_name": "Acme Ltda",
    "sender_document": "12345678000190",
    "recipient_name": "Maria Silva",
    "recipient_phone": "+5511999998888",
    "recipient_document": "12345678901",
    "template_id": 50,
    "template_variables": {"1": "A1B2C3"},
    "paymentMethod": "escrybe_credits"
  }'
```

A resposta retorna um `message_id`, um `visual_id` público e um `status`
`processing` até o pagamento ser liquidado e a mensagem entrar na fila.

* O telefone do destinatário é verificado no WhatsApp — números que não estão
  no WhatsApp são rejeitados com `400`.
* Se o cabeçalho do modelo usa imagem ou documento, um entre `media_url`,
  `media_file` ou `media_base64` é obrigatório.
* Se uma mensagem parar com status 2 (créditos insuficientes), adicione
  créditos e faça `POST /api/whatsapp/v1/process` com o `message_id` para
  recolocá-la na fila.

## Carimbos de tempo certificados

Cada mensagem pode produzir arquivos de atestação para as fases **accepted**,
**sent**, **delivered** e **read**. Baixe todos em um ZIP:

```bash theme={null}
curl "https://app.escrybe.com.br/api/whatsapp/v1/download_attestation_bundle?code=VISUAL_ID" \
  -u "voce@exemplo.com:SEU_TOKEN" -o atestacoes.zip
```

## Modelos

Modelos precisam ser aprovados pela Meta antes do uso. Crie um e consulte o
status até ficar `approved`:

```bash theme={null}
curl -X POST "https://app.escrybe.com.br/api/whatsapp/v1/templates/post" \
  -u "voce@exemplo.com:SEU_TOKEN" \
  -F "sender_id=5" \
  -F "name=order_confirmation" \
  -F "category=UTILITY" \
  -F "body_text=Seu pedido {{1}} foi confirmado."
```

<Note>
  O nome final do modelo é normalizado e recebe o prefixo do seu id de usuário
  (ex.: `user42_order_confirmation`) — o campo `name` da resposta é o que você
  usa ao enviar; seu texto original fica em `display_name`. Um rodapé de
  identificação do remetente é adicionado automaticamente ao corpo, e modelos
  com cabeçalho de imagem/documento enviados sem mídia usam um arquivo de
  exemplo padrão da Escrybe para aprovação da Meta.
</Note>