Modelos do WhatsApp Business pela CLI

Estes comandos encapsulam a API /v1/whatsapp/*. O escopo é propositalmente restrito: ciclo de vida dos modelos mais o envio de mensagens de modelo. A conexão da WABA é feita apenas pelo navegador (OAuth) e continua no painel.

Todos os comandos aceitam, na posição <account-id>, o UUID interno da conta social (obtido em accounts:list) ou o ID de provedor da WABA da Meta. O controller v1 resolve os UUIDs para IDs de provedor no servidor.

whatsapp:templates

Lista todos os modelos registrados em uma conta do WhatsApp Business, incluindo status (APPROVED, PENDING, REJECTED), categoria, idioma e estrutura de componentes.

so-me whatsapp:templates <account-id>

Argumento	Descrição
`<account-id>`	UUID da conta social do WhatsApp (obtido em `accounts:list`) ou ID de provedor da WABA da Meta (obrigatório)

Exemplos

# Lista completa
so-me whatsapp:templates e6be46a2-430a-41df-b180-b51527e954e3

# Somente modelos aprovados
so-me whatsapp:templates e6be46a2-... | jq '.data[] | select(.status == "APPROVED")'

# Somente nomes + status em um formato próximo de tabela
so-me whatsapp:templates e6be46a2-... | jq -r '.data[] | "\(.status)\t\(.name)\t\(.language)"'

# Passar o ID de provedor em vez do UUID
so-me whatsapp:templates 1050417321480811

whatsapp:create-template

Envia um novo modelo à Meta para aprovação. A aprovação dos modelos pode levar de minutos a horas; consulte whatsapp:templates repetidamente para ver o status passar de PENDING para APPROVED.

so-me whatsapp:create-template --account <id> (--file <path> | --data <json>)

Opção	Descrição
`--account <id>`	UUID da conta do WhatsApp ou ID de provedor (obrigatório)
`-f, --file <path>`	Arquivo JSON com a definição completa do modelo
`-d, --data <json>`	String JSON com a definição completa do modelo

Informe a definição do modelo com --file ou --data (se as duas forem passadas, --file prevalece; se nenhuma for passada, o comando gera erro). O payload segue o esquema da WhatsApp Cloud API da Meta. Campos mínimos:

name: minúsculas, com sublinhados
language: por exemplo, en_US
category: MARKETING, UTILITY ou AUTHENTICATION
components[]: HEADER, BODY, FOOTER, BUTTONS

A CLI mescla accountId (de --account) ao payload antes de enviar, portanto você não precisa incluí-lo no JSON.

{
  "name": "order_shipped",
  "language": "en_US",
  "category": "UTILITY",
  "components": [
    { "type": "HEADER", "format": "TEXT", "text": "Order update" },
    { "type": "BODY", "text": "Hi {{1}}, your order #{{2}} has shipped." },
    { "type": "FOOTER", "text": "Thanks for shopping with us!" }
  ]
}

Exemplos

# A partir de um arquivo
so-me whatsapp:create-template --account e6be46a2-... --file ./order_shipped.json

# Inline
so-me whatsapp:create-template --account e6be46a2-... --data '{
  "name": "welcome_v1",
  "language": "en_US",
  "category": "MARKETING",
  "components": [{ "type": "BODY", "text": "Welcome, {{1}}!" }]
}'

Os nomes dos modelos devem ser alfanuméricos em minúsculas com sublinhados (^[a-z0-9_]+$). A Meta valida isso; nomes fora do padrão são rejeitados imediatamente com 400.

whatsapp:delete-template

Exclui um modelo permanentemente. Depois de excluído, ele não pode ser restaurado; você precisa reenviá-lo com um novo nome.

so-me whatsapp:delete-template <account-id> <template-name> [-y]

Argumento	Descrição
`<account-id>`	UUID da conta social do WhatsApp ou ID de provedor (obrigatório)
`<template-name>`	Nome do modelo (`lowercase_underscored`) (obrigatório)

Opção	Descrição
`-y, --yes`	Ignora a confirmação

Sem -y, o comando pergunta Delete template "<name>" on account <id>? (y/N) e é cancelado, a menos que você responda y.

Exemplos

# Com confirmação
so-me whatsapp:delete-template e6be46a2-... old_template

# Ignorar a confirmação
so-me whatsapp:delete-template e6be46a2-... old_template -y

# Excluir todos os modelos REJECTED (com cuidado)
so-me whatsapp:templates e6be46a2-... \
  | jq -r '.data[] | select(.status == "REJECTED") | .name' \
  | xargs -I {} so-me whatsapp:delete-template e6be46a2-... {} -y

whatsapp:send

Envia uma mensagem de modelo aprovado para um destinatário. Esta é a principal forma de iniciar uma conversa no WhatsApp fora da janela de atendimento ao cliente de 24 horas.

so-me whatsapp:send <account-id> --to <phone> --template <name> --language <code> [--components <json>]

Argumento	Descrição
`<account-id>`	UUID da conta social do WhatsApp ou ID de provedor (obrigatório)

Opção	Descrição
`--to <phone>`	Destinatário no formato E.164 (por exemplo, `+15551234567`) (obrigatório)
`--template <name>`	Nome de um modelo APPROVED (obrigatório)
`--language <code>`	Código de idioma (por exemplo, `en_US`, `es`, `pt_BR`) (obrigatório)
`--components <json>`	Parâmetros do modelo como uma string JSON inline
`--file <path>`	Parâmetros do modelo a partir de um arquivo JSON

--components e --file são opcionais (um modelo sem variáveis não precisa de nenhuma das duas). Se as duas forem informadas, --file tem precedência. Os parâmetros dos componentes preenchem as variáveis ({{1}}, {{2}} etc.) do modelo aprovado. O formato segue a Cloud API da Meta:

[
  {
    "type": "body",
    "parameters": [
      { "type": "text", "text": "Alice" },
      { "type": "text", "text": "1234" }
    ]
  }
]

Exemplos

# Modelo sem variáveis
so-me whatsapp:send e6be46a2-... \
  --to +15551234567 --template welcome_v1 --language en_US

# Modelo com variáveis no corpo
so-me whatsapp:send e6be46a2-... \
  --to +15551234567 --template order_shipped --language en_US \
  --components '[{"type":"body","parameters":[{"type":"text","text":"Alice"},{"type":"text","text":"ORD-1234"}]}]'

# Parâmetros a partir de um arquivo (mais fácil para componentes complexos)
so-me whatsapp:send e6be46a2-... \
  --to +15551234567 --template order_shipped --language en_US \
  --file ./order_components.json

# Loop de envio em massa (atenção aos limites de taxa de mensagens da Meta)
while read -r phone name; do
  so-me whatsapp:send e6be46a2-... \
    --to "$phone" --template welcome_v1 --language en_US \
    --components "[{\"type\":\"body\",\"parameters\":[{\"type\":\"text\",\"text\":\"$name\"}]}]"
done < recipients.tsv

O envio de modelos é cobrado conforme a tabela de preços do WhatsApp Business da Meta. Sempre teste primeiro com um único destinatário. Modelos não aprovados ou rejeitados falham com 400.

whatsapp:upload-media

Envia mídia de cabeçalho (imagem/vídeo/documento) para uso no componente HEADER de um modelo. Retorna um identificador de mídia que você pode referenciar ao criar ou enviar modelos.

so-me whatsapp:upload-media --account <id> --type <fileType> (--url <url> | --base64 <content>)

Opção	Descrição
`--account <id>`	UUID da conta do WhatsApp ou ID de provedor (obrigatório)
`--type <fileType>`	Tipo de arquivo: `image`, `video` ou `document` (obrigatório)
`--url <url>`	URL pública da mídia a enviar
`--base64 <content>`	Conteúdo do arquivo codificado em Base64 (alternativa a `--url`)

Informe exatamente uma entre --url e --base64; o comando gera erro se você não informar nenhuma ou informar as duas.

Exemplos

# A partir de uma URL pública
so-me whatsapp:upload-media \
  --account e6be46a2-... --type image \
  --url https://cdn.example.com/hero.jpg

# A partir de um arquivo local (codificado em Base64)
so-me whatsapp:upload-media \
  --account e6be46a2-... --type image \
  --base64 "$(base64 -w0 ./hero.jpg)"

Visão geral

As mensagens de sessão (respostas em até 24 horas após uma mensagem recebida) passam por inbox:reply, sem necessidade de modelo.
As mensagens de modelo (primeiro contato ou fora da janela de 24 horas) usam whatsapp:send e exigem um modelo aprovado pela Meta.
Conectar uma conta do WhatsApp Business continua sendo feito apenas pelo navegador: conclua o OAuth no painel primeiro; depois, seus scripts da CLI poderão referenciar a conta conectada.

Primeiros passos

Publicação

AI Studio

Caixa de entrada e engajamento

Análises

Biolink

Equipe e colaboração

Configurações e cobrança

Webhooks

Suporte

Modelos do WhatsApp Business pela CLI

whatsapp:templates

whatsapp:create-template

whatsapp:delete-template

whatsapp:send

whatsapp:upload-media

Visão geral

​whatsapp:templates

​whatsapp:create-template

​whatsapp:delete-template

​whatsapp:send

​whatsapp:upload-media

​Visão geral

whatsapp:templates

whatsapp:create-template

whatsapp:delete-template

whatsapp:send

whatsapp:upload-media

Visão geral