message - Zapster API

`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.

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 pra detalhes de cada tipo.

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

{
  "ok": true,
  "data": {
    "kind": "immediate",
    "message_id": "3EB0C68ECE69F2DF660423",
    "message_trace_id": "x7jCGxw83jXOjaXR60qJQ24Zkrs4MacA"
  }
}

Saída — envio imediato (oficial / WABA)

{
  "ok": true,
  "data": {
    "kind": "immediate",
    "message_id": "wamid.HBgMNTU4NzgxMTcwMjYxFQIAERgSNDQyQzhBOTY1OEI5Mzk2MzI3AA=="
  }
}

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

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

Exemplos

Texto simples:

zapsterapi message send --recipient 5511999999999 --text "olá"

Texto + mídia + caption:

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:

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:

zapsterapi message send --recipient 5511999999999 \
  --template-name welcome --template-language pt_BR

Mensagem em grupo com mention everyone:

zapsterapi message send --recipient group:120363021234567890 \
  --text "Reunião em 10min @everyone" --mention-everyone

Reply + view-once:

zapsterapi message send --recipient 5511999999999 \
  --text "Aqui está a senha temporária" \
  --reply-to msg_4rajud08wyl9pmi6bhnwr \
  --view-once

Agendamento:

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.

zapsterapi message cancel msg_4rajud08wyl9pmi6bhnwr [--profile <nome>] [--json]

Saída

{
  "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.

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

{
  "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 e o guia de botões.

​zapsterapi message send

​Flags principais

​Mídia (--media-*)

​Templates WABA (--template-*)

​Botões interativos (--button, --buttons-mode)

​Mentions (--mention, --mention-everyone)

​Outros

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

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

​Saída — agendamento (--send-at definido)

​Exemplos

​zapsterapi message cancel <message-id>

​Saída

​Códigos de erro específicos

​zapsterapi message list

​Saída

​Códigos de erro específicos

​Códigos de erro comuns

`zapsterapi message send`

Flags principais

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

Templates WABA (`--template-*`)

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

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

Outros

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

Saída — envio imediato (oficial / WABA)

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

Exemplos

`zapsterapi message cancel <message-id>`

Saída

Códigos de erro específicos

`zapsterapi message list`

Saída

Códigos de erro específicos

Códigos de erro comuns