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

# message

> Envio, agendamento, cancelamento e listagem de mensagens WhatsApp via CLI.

## `zapsterapi message send`

Envia uma mensagem para um destinatário no WhatsApp. Suporta texto, mídia, templates WABA, botões interativos, mentions, agendamento, reply, view-once e mais.

```bash theme={null}
zapsterapi message send \
  --recipient <numero> \
  [--text <texto>] \
  [--instance-id <id>] \
  [--send-at <iso8601>] \
  [--media-url <url> | --media-base64 <b64>] \
  [--media-caption <texto>] [--media-filename <nome>] \
  [--ptt | --ptv | --sticker] \
  [--template-name <nome> --template-language <code> [--template-components <json>]] \
  [--button '<json>' ...]  [--buttons-mode <auto|interactive>] \
  [--mention <pn> ... | --mention-everyone] \
  [--reply-to <message-id>] \
  [--view-once] [--no-link-preview] [--auto-mention] \
  [--profile <nome>] [--json]
```

### Flags principais

| Flag                   | Obrigatório | Descrição                                                                                                                                    |
| ---------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `--recipient <numero>` | Sim         | Telefone E.164 sem `+` (ex: `5511999999999`) ou ID de grupo (`group:<id>`).                                                                  |
| `--text <texto>`       | Condicional | Conteúdo da mensagem. Pelo menos um de `--text`, `--media-*` ou `--template-*` é necessário.                                                 |
| `--instance-id <id>`   | Não         | Instância específica de envio. Se omitido e você só tiver **uma instância conectada**, a CLI usa ela; com mais de uma, a flag é obrigatória. |
| `--send-at <iso8601>`  | Não         | Agenda a mensagem (ISO 8601, ex: `2026-05-15T10:00:00Z`). Mínimo 1 minuto no futuro.                                                         |

### Mídia (`--media-*`)

Use `--media-url` sempre que possível — `--media-base64` carrega o arquivo no payload e fica reservado pra quando a URL não estiver acessível.

| Flag                      | Descrição                                             |
| ------------------------- | ----------------------------------------------------- |
| `--media-url <url>`       | URL pública/assinada do arquivo. **Preferida.**       |
| `--media-base64 <b64>`    | Conteúdo em base64. Use só quando URL não for viável. |
| `--media-caption <texto>` | Legenda (imagem/vídeo) ou texto sob o documento.      |
| `--media-filename <nome>` | Nome de arquivo (ex: `relatorio.pdf`).                |
| `--ptt`                   | Marca o áudio como push-to-talk (mensagem de voz).    |
| `--ptv`                   | Marca o vídeo como push-to-view (efêmero).            |
| `--sticker`               | Envia a mídia como figurinha.                         |

Exatamente um de `--media-url` ou `--media-base64` é necessário quando enviar mídia.

### Templates WABA (`--template-*`)

Templates são exclusivos de instâncias WABA (Meta oficial). **Mutuamente exclusivos com `--text` e `--media-*`.**

| Flag                           | Descrição                                                            |
| ------------------------------ | -------------------------------------------------------------------- |
| `--template-name <nome>`       | Nome do template aprovado na Meta.                                   |
| `--template-language <code>`   | Código de idioma (ex: `en_US`, `pt_BR`).                             |
| `--template-components <json>` | Array JSON de components com `header`/`body`/`buttons` e parâmetros. |

### Botões interativos (`--button`, `--buttons-mode`)

Repita `--button` até **3 vezes**. Cada valor é JSON com `type` + campos do tipo. Veja o [guia de botões](/pt-BR/v1/guides/messages-with-buttons) pra detalhes de cada tipo.

```bash theme={null}
--button '{"type":"reply","label":"Sim"}' \
--button '{"type":"call","label":"Ligar","phone_number":"+5511999999999"}' \
--button '{"type":"url","label":"Abrir","url":"https://exemplo.com"}'
```

| Tipo       | Campos obrigatórios                     |
| ---------- | --------------------------------------- |
| `reply`    | `label`                                 |
| `call`     | `label`, `phone_number` (E.164 com `+`) |
| `url`      | `label`, `url`                          |
| `copyable` | `label`, `copy_code`                    |

`--buttons-mode <auto\|interactive>` é opcional (default `auto`). Use `interactive` pra forçar visual rico mesmo só com `reply`.

### Mentions (`--mention`, `--mention-everyone`)

| Flag                 | Descrição                                    |
| -------------------- | -------------------------------------------- |
| `--mention <pn>`     | Telefone/JID a ser mencionado. Pode repetir. |
| `--mention-everyone` | Menciona @todos no grupo.                    |

`--mention` e `--mention-everyone` são **mutuamente exclusivos**.

### Outros

| Flag                      | Descrição                                             |
| ------------------------- | ----------------------------------------------------- |
| `--reply-to <message-id>` | Responde a uma mensagem existente (limite de 7 dias). |
| `--view-once`             | Marca como mensagem efêmera (some após visualizar).   |
| `--no-link-preview`       | Desativa o preview de URLs (default: ativo).          |
| `--auto-mention`          | Habilita auto-mention.                                |

### Saída — envio imediato (não-oficial / Baileys)

```json theme={null}
{
  "ok": true,
  "data": {
    "kind": "immediate",
    "message_id": "3EB0C68ECE69F2DF660423",
    "message_trace_id": "x7jCGxw83jXOjaXR60qJQ24Zkrs4MacA"
  }
}
```

### Saída — envio imediato (oficial / WABA)

```json theme={null}
{
  "ok": true,
  "data": {
    "kind": "immediate",
    "message_id": "wamid.HBgMNTU4NzgxMTcwMjYxFQIAERgSNDQyQzhBOTY1OEI5Mzk2MzI3AA=="
  }
}
```

### Saída — agendamento (`--send-at` definido)

```json theme={null}
{
  "ok": true,
  "data": {
    "kind": "scheduled",
    "message_id": "msg_4rajud08wyl9pmi6bhnwr",
    "send_at": "2026-05-15T10:00:00.000Z",
    "status": "scheduled"
  }
}
```

### Exemplos

**Texto simples:**

```bash theme={null}
zapsterapi message send --recipient 5511999999999 --text "olá"
```

**Texto + mídia + caption:**

```bash theme={null}
zapsterapi message send --recipient 5511999999999 \
  --text "veja o relatório anexo" \
  --media-url https://exemplo.com/relatorio.pdf \
  --media-filename relatorio.pdf
```

**Botões interativos:**

```bash theme={null}
zapsterapi message send --recipient 5511999999999 \
  --text "Como podemos te ajudar?" \
  --button '{"type":"reply","label":"Suporte"}' \
  --button '{"type":"reply","label":"Vendas"}' \
  --buttons-mode interactive
```

**Template WABA:**

```bash theme={null}
zapsterapi message send --recipient 5511999999999 \
  --template-name welcome --template-language pt_BR
```

**Mensagem em grupo com mention everyone:**

```bash theme={null}
zapsterapi message send --recipient group:120363021234567890 \
  --text "Reunião em 10min @everyone" --mention-everyone
```

**Reply + view-once:**

```bash theme={null}
zapsterapi message send --recipient 5511999999999 \
  --text "Aqui está a senha temporária" \
  --reply-to msg_4rajud08wyl9pmi6bhnwr \
  --view-once
```

**Agendamento:**

```bash theme={null}
zapsterapi message send --recipient 5511999999999 \
  --text "Bom dia!" --send-at 2026-05-16T08:00:00-03:00
```

***

## `zapsterapi message cancel <message-id>`

Cancela uma mensagem **agendada** (`scheduled`) ou **pendente** (`pending`). Mensagens já enviadas não podem ser canceladas.

```bash theme={null}
zapsterapi message cancel msg_4rajud08wyl9pmi6bhnwr [--profile <nome>] [--json]
```

### Saída

```json theme={null}
{
  "ok": true,
  "data": {
    "id": "msg_4rajud08wyl9pmi6bhnwr",
    "status": "canceled"
  }
}
```

### Códigos de erro específicos

| `error.code`            | Causa                                             |
| ----------------------- | ------------------------------------------------- |
| `message_not_found`     | ID não existe ou não pertence à conta.            |
| `message_cannot_cancel` | Mensagem já saiu do estado `scheduled`/`pending`. |

***

## `zapsterapi message list`

Lista mensagens dentro de uma janela de tempo. Útil pra auditoria, dashboards e agentes que precisam reconciliar status.

```bash theme={null}
zapsterapi message list \
  --from <iso8601> \
  --to <iso8601> \
  [--status <pending|scheduled|sent|failed|canceled>] \
  [--instance-id <id>] \
  [--recipient <numero>] \
  [--message-id <id>] \
  [--connection-type <waba|unofficial>] \
  [--limit <n>] \
  [--after <cursor>] \
  [--profile <nome>] \
  [--json]
```

| Flag                       | Obrigatório | Descrição                                                    |
| -------------------------- | ----------- | ------------------------------------------------------------ |
| `--from <iso8601>`         | Sim         | Início da janela. ISO 8601.                                  |
| `--to <iso8601>`           | Sim         | Fim da janela. ISO 8601. **Janela máxima de 90 dias.**       |
| `--status <status>`        | Não         | Filtra por status.                                           |
| `--instance-id <id>`       | Não         | Filtra por instância.                                        |
| `--recipient <pn>`         | Não         | Filtra por destinatário.                                     |
| `--message-id <id>`        | Não         | Filtra por ID de mensagem (wamid ou `msg_...`).              |
| `--connection-type <type>` | Não         | `waba` ou `unofficial`.                                      |
| `--limit <n>`              | Não         | 1–100, default 20.                                           |
| `--after <cursor>`         | Não         | Cursor de paginação (`meta.next_cursor` da página anterior). |

### Saída

```json theme={null}
{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "msg_01HABC...",
        "message_id": "wamid.HBg...",
        "recipient": "5511999999999",
        "status": "sent",
        "connection_type": "waba",
        "instance_id": "i_xyz1234abc",
        "send_at": null,
        "sent_at": "2026-05-08T10:00:00Z",
        "canceled_at": null,
        "errors": null
      }
    ],
    "meta": {
      "next_cursor": null,
      "has_more": false,
      "limit": 20
    }
  }
}
```

### Códigos de erro específicos

| `error.code`       | Causa                                     |
| ------------------ | ----------------------------------------- |
| `from_after_to`    | `--from` igual ou maior que `--to`.       |
| `window_too_large` | Janela excede 90 dias.                    |
| `invalid_argument` | `--from` ou `--to` não é ISO 8601 válido. |

***

## Códigos de erro comuns

| `error.code`            | Causa                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------ |
| `missing_recipient`     | Flag `--recipient` ausente ou vazia.                                                 |
| `missing_text`          | Nenhum de `--text`, `--media-*` ou `--template-*` foi informado.                     |
| `incompatible_content`  | `--template-*` combinado com `--text` ou `--media-*` (são mutuamente exclusivos).    |
| `invalid_media`         | `--media-url` e `--media-base64` ambos presentes, ou nenhum dos dois.                |
| `invalid_button`        | JSON inválido em `--button`, mais de 3 botões, ou campo obrigatório do tipo ausente. |
| `invalid_template`      | `--template-name` ou `--template-language` ausente.                                  |
| `invalid_mentions`      | `--mention` e `--mention-everyone` foram passados juntos.                            |
| `invalid_send_at`       | `--send-at` não é ISO 8601 válido.                                                   |
| `invalid_token`         | Token inválido ou expirado.                                                          |
| `invalid_recipient`     | Número não é WhatsApp válido.                                                        |
| `instance_not_found`    | `--instance-id` não pertence à conta.                                                |
| `no_connected_instance` | `--instance-id` omitido e nenhuma instância está conectada.                          |
| `instance_id_required`  | `--instance-id` omitido e há múltiplas instâncias conectadas.                        |

Para a referência completa do payload (todos os campos, validações cross-field, edge cases), veja a [REST API](/pt-BR/v1/api-reference/messages/sending) e o [guia de botões](/pt-BR/v1/guides/messages-with-buttons).