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 apiwpp | Template da Cloud API | |
|---|---|---|
| Aprovação | Não precisa: vale assim que é criado | Aprovado pela Meta antes do uso |
| Alterar o texto | A qualquer momento, com PUT | Nova submissão para aprovação |
| Obrigatório para iniciar conversa | Não | Sim, fora da janela de atendimento |
| Onde fica | Na 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:
| Chamada | O que faz |
|---|---|
POST /connections/{id}/templates | Cria um template |
GET /connections/{id}/templates | Lista 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.
Outros recursos
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.
Mensagens interativas
Em breveBotõ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 breveEnviar 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.