vamobotDocs

Modelos

Liste os modelos de mensagem da loja e envie um modelo aprovado para qualquer número, mesmo fora da janela de 24 horas.

Um modelo é uma mensagem aprovada pela Meta. É o único jeito de falar com um cliente que não escreveu nas últimas 24 horas: confirmação de pedido, aviso de entrega, lembrete de carrinho. Os modelos são criados e enviados para aprovação no Vamo, em Templates (veja Modelos de mensagem); a API lista e envia.

O modelo

{
  "id": "1f2e3d4c-5b6a-4978-8a6b-5c4d3e2f1a0b",
  "name": "pedido_enviado",
  "category": "utility",
  "language": "pt_BR",
  "header": "Pedido {{1}} a caminho",
  "headerFormat": "TEXT",
  "body": "Oi, {{2}}! Seu pedido saiu para entrega. Rastreie pelo código {{3}}.",
  "footer": "Loja Aurora",
  "buttons": [{ "type": "QUICK_REPLY", "text": "Falar com a loja" }],
  "waTemplateId": "1234567890123456",
  "reviewStatus": "approved",
  "rejectionReason": null,
  "replacesTemplateId": null,
  "createdAt": "2026-09-20T10:00:00.000Z"
}
CampoValores
categorymarketing, utility (utilidade) ou authentication
reviewStatuspending (em análise na Meta), approved, rejected, paused ou disabled (pausado ou desativado pela Meta)
rejectionReasonO motivo da Meta, quando rejeitado
replacesTemplateIdNuma nova versão de um modelo, o ID da versão anterior

GET /templates

Lista os modelos, do mais novo para o mais antigo. Acesso: chave secreta ou publicável (leitura).

ParâmetroDescrição
statuspending, approved, rejected, paused ou disabled
page, pageSizePadrão 50, máximo 100
curl "https://vamo.ai/api/v1/templates?status=approved" \
  -H "Authorization: Bearer pk_live_SUA_CHAVE_PUBLICAVEL"

Responde { "data": [ … ], "pagination": { "page": 1, "pageSize": 50, "total": 6 } }.

GET /templates/:id

Um modelo pelo ID. Acesso: chave secreta ou publicável (leitura). 404 (Template not found) se não existir na sua organização.

POST /templates/send

Envia um modelo aprovado para um número. Não precisa de janela de 24 horas aberta. Acesso: chave secreta com Leitura e escrita.

CampoTipoObrigatórioDescrição
tostringSimO número no formato internacional, com +: +5511987654321
templateIdstring (UUID)SimO modelo
variablesobjetoNãoO valor de cada variável do cabeçalho e do corpo, pela chave
curl -X POST https://vamo.ai/api/v1/templates/send \
  -H "Authorization: Bearer sk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5511987654321",
    "templateId": "1f2e3d4c-5b6a-4978-8a6b-5c4d3e2f1a0b",
    "variables": { "1": "#1042", "2": "Mariana", "3": "BR123456789" }
  }'

Resposta 201

{
  "data": {
    "id": "9b8c7d6e-5f4a-4b3c-8d2e-1f0a9b8c7d6e",
    "waMessageId": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABEYEjZB",
    "status": "sent",
    "to": "+5511987654321",
    "type": "template",
    "template": { "id": "1f2e3d4c-5b6a-4978-8a6b-5c4d3e2f1a0b", "name": "pedido_enviado", "language": "pt_BR" },
    "variables": { "1": "#1042", "2": "Mariana", "3": "BR123456789" },
    "timestamp": "2026-10-31T14:30:00.000Z"
  }
}

O id é o da mensagem: consulte o status depois com GET /messages/:id.

Variáveis

  • A chave de cada valor é o que está entre as chaves duplas no modelo: "1" para {{1}}, ou o nome, como "nome" para {{nome}}.
  • Envie um valor para cada variável do cabeçalho e do corpo. Uma variável sem valor vai vazia, e o WhatsApp recusa o envio.
  • Uma variável usada no cabeçalho aceita no máximo 60 caracteres (limite do WhatsApp). Acima disso: 400 template_header_variable_too_long, com key e limit no corpo.
  • O texto gravado na conversa é o modelo com as variáveis preenchidas.

Quem recebe

  • O Vamo procura um contato com exatamente esse phone. Se não achar, cria um contato com o número como nome e status lead (e dispara contact.created). Por isso grave sempre os telefones com + e código do país, como em to.
  • A conversa do contato é reaberta, ou criada (conversation.created). A mensagem aparece na caixa de entrada com origem api e dispara message.created.
  • Quando o cliente responder, a janela de 24 horas abre e você pode seguir com mensagens livres.

Modelos de marketing

Um modelo da categoria marketing tem regras a mais:

SituaçãoResposta
A conta está no período de teste409 trial_marketing_blocked. Utilidade e respostas funcionam normalmente
Há uma fatura do Vamo vencida402 billing_marketing_restricted até o pagamento
O cliente pediu para não receber marketing422 whatsapp_marketing_opt_out

Modelos que o Vamo ainda não envia

Modelos importados da sua conta do WhatsApp com imagem, vídeo, documento ou localização no cabeçalho, ou com um botão de link que muda por cliente (https://lojaaurora.com.br/pedido/{{1}}), respondem 400 template_not_sendable. Texto, cabeçalho de texto, botões de resposta rápida e links fixos funcionam.

Erros

Os erros vêm no formato de sempre: { "error": { "code": "…", "message": "…" } }.

StatusCódigoQuando
400validation_errorFalta to ou templateId, templateId não é UUID, ou uma variável não é texto (até 1.024 caracteres cada, até 100 variáveis)
400invalid_phoneto não está no formato + e 7 a 15 dígitos
400template_not_approvedO modelo não está approved
400template_not_sendableCabeçalho de mídia ou link variável (veja acima)
400template_header_variable_too_longVariável do cabeçalho com mais de 60 caracteres
400no_active_storeO WhatsApp da loja não está conectado
404not_foundO modelo não existe na sua organização
422whatsapp_template_errorO WhatsApp recusou o modelo (pausado, desativado, variáveis que não batem)
422whatsapp_recipient_unavailableO número não recebe WhatsApp

Os demais erros de envio (429, 409, 402, 502) são os mesmos de Mensagens e estão em Erros.

Aceita Idempotency-Key: repetir com a mesma chave não envia o modelo de novo (veja Idempotência).

Nesta página

O modeloGET /templatesGET /templates/:idPOST /templates/sendVariáveisQuem recebeModelos de marketingModelos que o Vamo ainda não enviaErros