Como montar modelos de mensagem do WhatsApp (componentes, formatos, variáveis e autenticação), editar, acompanhar a saúde e dar ações aos botões de resposta rápida.
Um modelo de mensagem (na API, template) é uma mensagem do WhatsApp oficial aprovada pela Meta antes do uso. É o único jeito de começar uma conversa ou de falar com um contato fora da janela de 24 horas. O modelo pertence a uma conta do WhatsApp Business (WABA) e é criado a partir de um número dessa conta.
Além do conteúdo que vai para a Meta, a Vozko guarda ações de botão: o que acontece quando o lead toca num botão de resposta rápida (sair das mensagens, passar para a equipe, iniciar um fluxo e outras). Essas ações nunca vão para a revisão da Meta.
As rotas estão nos grupos WhatsApp: modelos e WhatsApp: campanhas da Referência da API. Os tipos de ação de botão, com os parâmetros e as permissões de cada um, estão em Ações de botão.
Conceitos
| Conceito | O que é |
|---|---|
| Categoria | MARKETING, UTILITY ou AUTHENTICATION. Outro valor é recusado com template_invalid_category. |
| Status | O estado na Meta: PENDING, APPROVED, REJECTED, PAUSED ou DISABLED. |
| Nome e idioma | O nome tem letras minúsculas, números e _, começa com letra e tem até 512 caracteres. O idioma padrão é pt_BR. Nome e idioma identificam o modelo na conta. |
| Componentes | As partes da mensagem: cabeçalho, corpo, rodapé e botões. |
usabilityStatus | Se o modelo pode ser enviado agora: ready, not_approved (o status não é APPROVED) ou missing_header_media (o cabeçalho é de mídia e falta a mídia de envio). |
Componentes
Cada item de components tem um type. O corpo é obrigatório.
type | Para que serve | Regras |
|---|---|---|
HEADER | Cabeçalho | format obrigatório. Em TEXT, até 60 caracteres e no máximo uma variável. |
BODY | Corpo | Até 1.024 caracteres. Não pode começar nem terminar com uma variável nem ter duas variáveis seguidas. |
FOOTER | Rodapé | Até 60 caracteres, sem variáveis. |
BUTTONS | Botões | Até 10 botões. Os de resposta rápida ficam juntos, sem outros tipos entre eles. |
CALL_PERMISSION_REQUEST | Pedido de permissão para ligar | No máximo um, e nunca junto com BUTTONS: o WhatsApp desenha os botões sozinho. |
Formatos do cabeçalho
format | O que exige |
|---|---|
TEXT | text. Com uma variável, um exemplo em example.header_text ou example.header_text_named_params. |
IMAGE, VIDEO, DOCUMENT | Um exemplo em example.header_handle: um identificador de mídia da Meta ou o endereço de um arquivo da biblioteca de mídia do workspace, que a plataforma envia à Meta. Endereço fora da biblioteca: template_header_media_outside_storage. |
GIF | Um exemplo em example.header_handle. |
LOCATION | Nada além do formato. |
Num cabeçalho de imagem, vídeo ou documento, informe também headerMediaUrl (um arquivo da biblioteca de mídia): é a mídia usada nos envios. Sem ela, o modelo fica com usabilityStatus missing_header_media até você enviar a mídia por PATCH /whatsapp/templates/{id}/header-media.
Tipos de botão
type | Campos | Regras |
|---|---|---|
QUICK_REPLY | text | Resposta rápida. É o único tipo que aceita ação de botão. |
URL | text, url, example | Até uma variável, no fim da URL, com um exemplo em example. |
PHONE_NUMBER | text, phone_number | Abre a ligação para o número. |
COPY_CODE | example | Copia um código. text é opcional. |
OTP | otp_type | Só em modelos AUTHENTICATION. Veja a seção Modelos de autenticação. |
FLOW | text, flowId, flowAction, navigateScreen | Abre um formulário. No máximo um por modelo. Veja a seção Botão de formulário. |
O texto de um botão tem até 25 caracteres e é obrigatório, menos em COPY_CODE e OTP.
Variáveis
Uma variável é um marcador entre chaves duplas no texto do cabeçalho ou do corpo. Há dois estilos, e um modelo usa só um deles (template_mixed_parameter_styles):
| Estilo | Marcador | Exemplos exigidos |
|---|---|---|
| Posicional | {{1}}, {{2}} | example.body_text: uma lista com uma linha de valores, na ordem dos números. No cabeçalho, example.header_text. |
| Nomeada | {{primeiro_nome}} | example.body_text_named_params: uma lista de param_name e example. No cabeçalho, example.header_text_named_params. |
O nome de uma variável nomeada tem só letras minúsculas sem acento, números e _, e começa com letra; senão, 400 template_variable_name_invalid com o nome em expected.variable. Para conferir nomes antes de montar o modelo, use POST /whatsapp/templates/variable-names/check.
O estilo do modelo é deduzido das variáveis do texto: só números é posicional, qualquer nome é nomeado, e sem variáveis é posicional. As leituras trazem o estilo em parameterFormat (positional ou named). O campo parameterFormat do corpo de criação não muda essa dedução.
Um corpo com variáveis nomeadas:
{
"type": "BODY",
"text": "Olá {{primeiro_nome}}, o pedido {{pedido}} saiu para entrega.",
"example": {
"body_text_named_params": [
{ "param_name": "primeiro_nome", "example": "Maria" },
{ "param_name": "pedido", "example": "4521" }
]
}
}Criar um modelo
- Escolha o número da conta em que o modelo vai existir (
businessPhoneId). O número precisa ser do workspace; senão,403. - Monte os componentes e, se quiser, as ações dos botões de resposta rápida (
buttonActions) e a confirmação de saída (exitConfirmation). - Envie
POST /whatsapp/templates. A plataforma confere o modelo antes de mandá-lo à Meta; um erro de formato volta com400e um códigotemplate_*. Uma recusa da Meta volta com422 template_provider_rejectede a Meta indisponível, com502 template_provider_unavailable. - Acompanhe o status com
GET /whatsapp/templates/{id}ouPOST /whatsapp/templates/{id}/sync. O modelo só pode ser enviado com statusAPPROVED.
{
"businessPhoneId": "8f14e45f-ceea-4e7a-9c1d-2b3a4c5d6e7f",
"name": "promo_outubro",
"language": "pt_BR",
"category": "MARKETING",
"components": [
{ "type": "HEADER", "format": "IMAGE", "example": { "header_handle": ["https://cdn.exemplo.com/oferta.jpg"] } },
{ "type": "BODY", "text": "Olá {{1}}, a sua oferta de {{2}} chegou.", "example": { "body_text": [["Maria", "outubro"]] } },
{ "type": "FOOTER", "text": "Responda /sair para não receber mais" },
{ "type": "BUTTONS", "buttons": [
{ "type": "QUICK_REPLY", "text": "Quero saber mais" },
{ "type": "QUICK_REPLY", "text": "Sair" },
{ "type": "URL", "text": "Ver oferta", "url": "https://exemplo.com.br/oferta" }
] }
],
"headerMediaUrl": "https://cdn.exemplo.com/oferta.jpg",
"buttonActions": [
{ "buttonIndex": 0, "buttonText": "Quero saber mais", "kind": "hand_off", "params": { "departmentId": "5b0c1d2e-3f4a-4b5c-8d6e-7f8091a2b3c4" } },
{ "buttonIndex": 1, "buttonText": "Sair", "kind": "opt_out", "params": {} }
],
"exitConfirmation": "Pronto, você não receberá mais mensagens."
}As ações e a confirmação de saída só são gravadas depois que a Meta aceita o modelo, e substituem as que já existiam para o mesmo nome e idioma. Sem nenhuma das duas no corpo, as que já existiam ficam como estão.
Os nomes dos campos seguem o que a Meta usa: phone_number, otp_type, add_security_recommendation, code_expiration_minutes e os campos de example vão em snake_case; flowId, flowAction e navigateScreen, em camelCase. As leituras devolvem todos os campos em camelCase.
Modelos de autenticação
Um modelo AUTHENTICATION envia um código de uso único. O texto é escrito pelo WhatsApp, então o modelo leva só as opções:
| Componente | O que aceita |
|---|---|
BODY | Sem text (template_authentication_body_not_editable). add_security_recommendation: true acrescenta o aviso para não compartilhar o código. |
FOOTER | Sem text. code_expiration_minutes, de 1 a 90, mostra a validade do código. |
BUTTONS | Um botão OTP obrigatório, com otp_type COPY_CODE. ONE_TAP e ZERO_TAP são recusados com template_otp_type_unsupported. |
HEADER | Não aceita (template_authentication_no_header). |
{
"businessPhoneId": "8f14e45f-ceea-4e7a-9c1d-2b3a4c5d6e7f",
"name": "codigo_acesso",
"language": "pt_BR",
"category": "AUTHENTICATION",
"components": [
{ "type": "BODY", "add_security_recommendation": true },
{ "type": "FOOTER", "code_expiration_minutes": 10 },
{ "type": "BUTTONS", "buttons": [ { "type": "OTP", "otp_type": "COPY_CODE", "text": "Copiar código" } ] }
]
}Um botão OTP em outra categoria é recusado com template_otp_button_not_authentication. No envio, o primeiro parâmetro é o código, com até 15 caracteres. Modelos de autenticação não são editados pela rota de edição.
Botão de formulário
Um botão FLOW abre um formulário do WhatsApp. O formulário precisa estar publicado por este workspace na conta do modelo (template_flow_not_published). GET /whatsapp/forms/sendable devolve, para um número, os valores do botão: metaFlowId vai em flowId e firstScreen em navigateScreen.
{ "type": "FLOW", "text": "Responder", "flowId": "1234567890", "flowAction": "navigate", "navigateScreen": "SCREEN_A" }flowAction é navigate (padrão, exige navigateScreen) ou data_exchange.
Botões de link rastreados
trackedUrlButtons lista os índices (entre todos os botões) dos botões URL com cliques rastreados. A plataforma cria um link curto para o destino e troca a URL do botão pelo link curto com uma variável de sufixo; em cada envio a variável recebe um token do envio e o toque abre o destino real. As leituras trazem trackedUrlButtons (lista vazia quando nenhum botão é rastreado). Uma recusa do rastreio traz o índice do botão em expected.buttonIndex.
Editar um modelo
PUT /whatsapp/templates/{id}/content envia à Meta uma nova versão, que volta para a revisão. O corpo traz todos os componentes que o modelo deve ter: o que não vier é removido.
| Regra | Recusa |
|---|---|
Só modelos APPROVED, REJECTED ou PAUSED. | 409 template_not_editable |
A categoria só muda em REJECTED ou PAUSED. | 409 template_edit_category_locked |
Um modelo APPROVED aceita uma edição por dia e dez a cada 30 dias. | 429 template_edit_window, com a próxima data em expected.nextEditAt |
| Só um workspace com número na conta do modelo pode editá-lo. | 403 template_edit_not_owner |
| Nunca enquanto uma campanha em andamento ou agendada usa o modelo. | 409 template_in_use |
| Botões que a plataforma não edita (de formulário ou de código) impedem trocar os botões. | 409 template_edit_unsupported |
Nome e idioma não mudam. Um cabeçalho de mídia é reenviado a partir de headerMediaUrl, da mídia guardada ou da cópia da Meta. O corpo pode trazer buttonActions e exitConfirmation, gravados só depois que a Meta aceita a edição.
Saúde do modelo
GET /whatsapp/templates/{id}/health mostra a qualidade que a Meta deu ao modelo (GREEN, YELLOW, RED ou UNKNOWN enquanto não houve avaliação), se ele está sinalizado (flagged) e as mudanças recentes de qualidade, status e categoria em changes, cada uma com signal, previous, current e occurredAt.
Ações dos botões
Cada botão de resposta rápida pode ter uma ação, que roda quando o lead toca no botão. As ações são da plataforma: salvá-las nunca reenvia o modelo para a Meta.
Como uma ação é endereçada
buttonIndexé a posição do botão dentro do componenteBUTTONS, contando todos os botões a partir de0. No exemplo de criação acima, "Quero saber mais" é0, "Sair" é1e o botão de URL, que não aceita ação, é2.buttonTexté o texto do botão que a pessoa viu ao salvar. Se o texto mudou na Meta, a ação fica desatualizada (stale: true) e não roda; reenviada sem nenhuma mudança e com o texto que guarda, ela continua gravada e desatualizada. Qualquer outro texto é recusado com422 button_action_stale.- Um botão tem no máximo uma ação (
400 button_action_duplicate_button). Um índice que não é de resposta rápida é recusado com400 button_action_not_quick_reply. confirmation, opcional e com até 1.000 caracteres, é enviada ao lead depois que a ação muda algo, se a janela de 24 horas estiver aberta.
Saída do lead
opt_out e consent_grant são as ações de saída. Um modelo também mostra uma saída quando o texto do cabeçalho, do corpo, do rodapé ou de um botão de resposta rápida traz um comando /palavra, como o rodapé "Responda /sair para não receber mais". O lead usa a saída enviando a palavra com a barra (/sair, sem diferenciar maiúsculas e acentos). A palavra tem de 1 a 30 caracteres, sem espaços.
- Um modelo
MARKETINGprecisa mostrar uma saída: sem ela, a criação e a edição são recusadas com422 marketing_template_needs_exit, antes de chegar à Meta.UTILITYeAUTHENTICATIONnão precisam. exitConfirmation(até 1.000 caracteres) é a mensagem enviada quando o lead usa uma palavra de saída. Sem ela, nenhuma confirmação é enviada.GET /whatsapp/templates/{id}/exit-verdictdiz se o modelo mostra uma saída (stateokounone) e lista as palavras emexitWords.POST /whatsapp/templates/exit-verdictcalcula o mesmo sobre um rascunho, sem gravar nada.
Salvar as ações de um modelo
Leia GET /whatsapp/templates/{id}/button-actions e envie a version lida no cabeçalho If-Match de PUT /whatsapp/templates/{id}/button-actions. O corpo substitui todas as ações e a confirmação de saída.
curl -X PUT "https://api.vozkoia.com/whatsapp/templates/TEMPLATE_ID/button-actions" \
-H "Authorization: Bearer SEU_TOKEN" \
-H "X-Workspace-ID: SEU_WORKSPACE" \
-H "If-Match: 2" \
-H "Content-Type: application/json" \
-d '{
"actions": [
{ "buttonIndex": 0, "buttonText": "Quero saber mais", "kind": "hand_off", "params": { "departmentId": "5b0c1d2e-3f4a-4b5c-8d6e-7f8091a2b3c4" }, "confirmation": "Um atendente vai falar com você." },
{ "buttonIndex": 1, "buttonText": "Sair", "kind": "opt_out", "params": {} }
],
"exitConfirmation": "Pronto, você não receberá mais mensagens."
}'Sem If-Match, 428 version_required; com uma versão antiga, 409 version_conflict com o estado atual em current. Os ids em params precisam ser deste workspace (422 button_action_params_not_found).
GET /whatsapp/button-action-kinds devolve em allowedKinds os tipos que quem pede pode configurar, pelas mesmas permissões do salvamento. A resposta de GET .../button-actions traz a mesma lista.
Desvios numa campanha
Uma campanha pode mudar o destino dos botões que não são de saída, sem mexer no modelo: PUT /whatsapp/campaigns/{id}/button-routes, com o mesmo formato de ação em routes e a version em If-Match. opt_out, consent_grant ou um botão cuja ação no modelo é de saída são recusados com 422 button_action_exit_locked.
Quando o lead toca num botão, vale a primeira destas que existir e estiver atualizada: a ação de saída do modelo, o desvio da campanha, a ação do modelo.
{
"routes": [
{ "buttonIndex": 0, "buttonText": "Quero saber mais", "kind": "start_workflow", "params": { "workflowId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d" } }
]
}Erros das ações
| Status e código | Quando |
|---|---|
400 button_action_kind_unknown | kind não é um tipo conhecido. |
400 button_action_not_quick_reply | buttonIndex não é um botão de resposta rápida. |
400 button_action_params_invalid | params não tem o formato do tipo. |
400 button_action_confirmation_too_long | confirmation passa de 1.000 caracteres. |
400 button_action_duplicate_button | Duas ações para o mesmo botão. |
400 exit_confirmation_too_long | exitConfirmation passa de 1.000 caracteres. |
403 button_action_forbidden | Falta a permissão do tipo criado, mudado ou removido. |
404 button_action_template_not_found | O modelo não existe ou não é acessível. |
422 button_action_params_not_found | Um id de params não é deste workspace. |
422 button_action_stale | buttonText não é o texto atual do botão. |
422 button_action_exit_locked | Desvio de campanha com tipo de saída ou num botão de saída. |
422 marketing_template_needs_exit | Modelo de marketing sem saída. |
Rotas
| Rota | O que faz |
|---|---|
GET /whatsapp/templates | Lista os modelos acessíveis, com filtros de status, categoria, idioma e número. |
POST /whatsapp/templates | Cria um modelo. |
GET /whatsapp/templates/{id} | Consulta um modelo. |
PUT /whatsapp/templates/{id}/content | Edita o conteúdo. |
DELETE /whatsapp/templates/{id} | Remove o modelo. |
POST /whatsapp/templates/sync | Sincroniza os modelos com a Meta. |
POST /whatsapp/templates/{id}/sync | Sincroniza um modelo. |
PATCH /whatsapp/templates/{id}/header-media | Define a mídia de envio do cabeçalho. |
POST /whatsapp/templates/variable-names/check | Confere nomes de variáveis. |
GET /whatsapp/templates/{id}/health | Saúde do modelo. |
GET e PUT /whatsapp/templates/{id}/button-actions | Lê e salva as ações e a confirmação de saída. |
GET /whatsapp/templates/{id}/exit-verdict | Veredito de saída de um modelo. |
POST /whatsapp/templates/exit-verdict | Veredito de saída de um rascunho. |
GET /whatsapp/button-action-kinds | Tipos de ação que quem pede pode configurar. |
GET e PUT /whatsapp/campaigns/{id}/button-routes | Lê e salva os desvios de uma campanha. |