Pular para o conteúdo
apiwpp
Recurso

Templates de mensagem com variáveis

Salve mensagens com variáveis na apiwpp e envie pelo nome, a partir de qualquer sistema. Sem aprovação da Meta: crie, edite e use na hora pela API.

Atualizado em

Quase toda integração com o WhatsApp repete as mesmas mensagens: a confirmação do pedido, o aviso de que ele saiu para entrega, o lembrete da consulta de amanhã. Muda o nome do cliente, o número do pedido e o horário; o resto do texto é igual. Com os templates de mensagem da apiwpp, você guarda esse texto uma vez, com variáveis no lugar do que muda, e cada sistema envia só o nome do template e os valores.

O texto deixa de ficar espalhado pelo código de cada sistema. Para ajustar uma palavra da confirmação de pedido, você altera o template e todos os envios seguintes já saem com a versão nova, sem publicar código.

Como funciona um template

Um template é uma mensagem salva numa conexão (um número de WhatsApp), com um nome e um corpo. As variáveis vão entre chaves duplas, como {{nome}} e {{pedido}}, e podem usar letras, números e sublinhado, começando por uma letra ou sublinhado. O nome do template aceita letras, números, hífen e sublinhado, e é guardado em minúsculas; ele é único dentro da conexão.

Crie o template com POST /connections/{id}/templates, usando uma chave de API com o escopo templates:write:

curl -s -X POST "https://api.apiwpp.com/connections/$CONNECTION_ID/templates" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name": "pedido_confirmado", "body": "Olá {{nome}}, recebemos o seu pedido {{pedido}}. Avisaremos quando ele sair para entrega."}'

A resposta é 201 com o template criado. Se já existe um template com esse nome na conexão, a resposta é 409.

Um template também pode levar uma mídia: uma imagem, um vídeo, um áudio ou um documento a partir de uma URL https pública, com legenda e nome do arquivo, como num envio de mídia comum. Assim, um cardápio em PDF ou a imagem de uma promoção para clientes que pediram para recebê-la ficam salvos junto com o texto.

Enviar pelo nome, com as variáveis

Para usar o template, chame o mesmo POST /connections/{id}/send de qualquer envio, trocando o texto pelo campo template e passando os valores em variables:

{
  "to": "5511988887777",
  "template": "pedido_confirmado",
  "variables": { "nome": "Maria", "pedido": "#1234" },
  "clientRef": "pedido-1234-confirmado"
}

A resposta é a de qualquer envio: 202 com jobId, scheduledAt e position, porque a mensagem entra na fila do número e sai no ritmo que protege o número. Se faltar alguma variável, a API responde 400 na hora com a lista em missingVariables, e nada é enfileirado. Assim, um cliente nunca recebe um Olá {{nome}} pela metade.

O clientRef funciona igual ao de um envio de texto: com o id do pedido dentro dele, repetir a chamada depois de um timeout não manda a confirmação duas vezes. Veja idempotência com clientRef.

Diferença para os templates da API oficial

Na API oficial do WhatsApp (a Cloud API da Meta), "template" é outra coisa: um modelo de mensagem que a Meta precisa aprovar antes do uso, com categoria definida, e que é a única forma de iniciar uma conversa com quem não escreveu nas últimas horas.

A apiwpp conecta o número pelo protocolo do WhatsApp Web, como um aparelho conectado, e não é a API oficial. Por isso os templates daqui são só mensagens salvas com variáveis, uma conveniência para o seu sistema:

Template da apiwppTemplate da Cloud API
AprovaçãoNão precisa: vale assim que é criadoAprovado pela Meta antes do uso
Alterar o textoA qualquer momento, com PUTNova submissão para aprovação
Obrigatório para iniciar conversaNãoSim, fora da janela de atendimento
Onde ficaNa conexão (no número)Na conta do WhatsApp Business

Não existe aprovação, mas as regras do WhatsApp continuam valendo: mensagem é para quem espera recebê-la. Um template não muda o ritmo da fila nem o limite de destinatários novos por dia. Para entender os dois modelos, leia o comparativo apiwpp ou API oficial.

Exemplos de uso

Confirmação de pedido numa loja virtual, disparada quando o pagamento é aprovado:

{ "name": "pagamento_aprovado", "body": "Oi {{nome}}! O pagamento do pedido {{pedido}} foi aprovado. Previsão de entrega: {{prazo}}." }

Lembrete de agendamento numa clínica ou barbearia, enviado na véspera:

{ "name": "lembrete_consulta", "body": "Olá {{nome}}, lembrando do seu horário amanhã às {{hora}} com {{profissional}}. Responda esta mensagem se precisar remarcar." }

A resposta do cliente chega ao seu sistema pelo webhook message.incoming, e você atualiza a agenda. Os casos de uso de notificações de pedido e de lembretes de agendamento mostram esses fluxos do começo ao fim.

Mantenha o texto curto e com cara de conversa. Variar a mensagem entre clientes, com o nome e os dados de cada um, também é mais natural do que o mesmo texto idêntico para todos.

Gerenciar pela API

Todos os templates de uma conexão são gerenciados pela API:

ChamadaO que faz
POST /connections/{id}/templatesCria um template
GET /connections/{id}/templatesLista os templates da conexão
GET /connections/{id}/templates/{name}Mostra um template e as variáveis que o corpo usa
PUT /connections/{id}/templates/{name}Altera o corpo ou a mídia
DELETE /connections/{id}/templates/{name}Apaga o template

Ler e listar pedem o escopo connections:read; criar, alterar e apagar pedem templates:write. Dessa forma, o sistema que só envia não precisa poder mudar os textos. Os templates ficam guardados até você apagá-los; apagar a conexão apaga também os templates dela. A referência completa, com todos os campos, está na documentação da API.

Os templates fazem parte dos planos LITE e PRO, sem custo por template nem por mensagem: o preço é por número conectado. Veja os preços.

Perguntas frequentes

Preciso de aprovação da Meta para criar um template?

Não. A apiwpp não é a API oficial do WhatsApp, e os templates daqui são mensagens salvas com variáveis. O template pode ser usado assim que é criado e alterado a qualquer momento com PUT.

O que acontece se eu esquecer uma variável no envio?

A API responde 400 na hora, com as variáveis que faltaram em missingVariables, e a mensagem não entra na fila. Corrija os valores e envie de novo.

Um template criado num número vale para os outros?

Não. Cada template pertence a uma conexão, e o nome é único dentro dela. Se vários números enviam a mesma mensagem, crie o template em cada conexão; um script com POST /connections/{id}/templates resolve isso em poucas linhas.

Templates estão disponíveis no plano LITE?

Sim. Templates, envio de texto e de mídia, webhooks e a fila anti-bloqueio fazem parte dos dois planos. O PRO acrescenta editar e apagar mensagens, marcar como lida, presença e o IP dedicado.

Todos: Recursos →

POST /connections/{id}/send coloca a mensagem na fila do número e responde 202 com jobId, scheduledAt e position. A API resolve o endereço do destinatário, mostra o "digitando…" e avisa o resultado pelo webhook message.delivery.

Botões e listas pelo protocolo do WhatsApp Web não têm suporte estável, e a apiwpp ainda avalia se vai oferecê-los. Enquanto isso, menus numerados, templates e reações resolvem confirmações e atendimento nos planos LITE e PRO.

Enquetes

Em breve

Enviar enquetes pela API e receber cada voto no seu webhook é um recurso em desenvolvimento, previsto para o plano PRO. Enquanto isso, respostas em texto e reações já confirmam agendamentos e coletam opiniões.

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.