Guia de modelos e botões

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

ConceitoO que é
CategoriaMARKETING, UTILITY ou AUTHENTICATION. Outro valor é recusado com template_invalid_category.
StatusO estado na Meta: PENDING, APPROVED, REJECTED, PAUSED ou DISABLED.
Nome e idiomaO 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.
ComponentesAs partes da mensagem: cabeçalho, corpo, rodapé e botões.
usabilityStatusSe 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.

typePara que serveRegras
HEADERCabeçalhoformat obrigatório. Em TEXT, até 60 caracteres e no máximo uma variável.
BODYCorpoAté 1.024 caracteres. Não pode começar nem terminar com uma variável nem ter duas variáveis seguidas.
FOOTERRodapéAté 60 caracteres, sem variáveis.
BUTTONSBotõesAté 10 botões. Os de resposta rápida ficam juntos, sem outros tipos entre eles.
CALL_PERMISSION_REQUESTPedido de permissão para ligarNo máximo um, e nunca junto com BUTTONS: o WhatsApp desenha os botões sozinho.

Formatos do cabeçalho

formatO que exige
TEXTtext. Com uma variável, um exemplo em example.header_text ou example.header_text_named_params.
IMAGE, VIDEO, DOCUMENTUm 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.
GIFUm exemplo em example.header_handle.
LOCATIONNada 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

typeCamposRegras
QUICK_REPLYtextResposta rápida. É o único tipo que aceita ação de botão.
URLtext, url, exampleAté uma variável, no fim da URL, com um exemplo em example.
PHONE_NUMBERtext, phone_numberAbre a ligação para o número.
COPY_CODEexampleCopia um código. text é opcional.
OTPotp_typeSó em modelos AUTHENTICATION. Veja a seção Modelos de autenticação.
FLOWtext, flowId, flowAction, navigateScreenAbre 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):

EstiloMarcadorExemplos 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

  1. Escolha o número da conta em que o modelo vai existir (businessPhoneId). O número precisa ser do workspace; senão, 403.
  2. 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).
  3. Envie POST /whatsapp/templates. A plataforma confere o modelo antes de mandá-lo à Meta; um erro de formato volta com 400 e um código template_*. Uma recusa da Meta volta com 422 template_provider_rejected e a Meta indisponível, com 502 template_provider_unavailable.
  4. Acompanhe o status com GET /whatsapp/templates/{id} ou POST /whatsapp/templates/{id}/sync. O modelo só pode ser enviado com status APPROVED.
{
  "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:

ComponenteO que aceita
BODYSem text (template_authentication_body_not_editable). add_security_recommendation: true acrescenta o aviso para não compartilhar o código.
FOOTERSem text. code_expiration_minutes, de 1 a 90, mostra a validade do código.
BUTTONSUm botão OTP obrigatório, com otp_type COPY_CODE. ONE_TAP e ZERO_TAP são recusados com template_otp_type_unsupported.
HEADERNã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.

RegraRecusa
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 componente BUTTONS, contando todos os botões a partir de 0. No exemplo de criação acima, "Quero saber mais" é 0, "Sair" é 1 e 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 com 422 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 com 400 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 MARKETING precisa mostrar uma saída: sem ela, a criação e a edição são recusadas com 422 marketing_template_needs_exit, antes de chegar à Meta. UTILITY e AUTHENTICATION nã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-verdict diz se o modelo mostra uma saída (state ok ou none) e lista as palavras em exitWords. POST /whatsapp/templates/exit-verdict calcula 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ódigoQuando
400 button_action_kind_unknownkind não é um tipo conhecido.
400 button_action_not_quick_replybuttonIndex não é um botão de resposta rápida.
400 button_action_params_invalidparams não tem o formato do tipo.
400 button_action_confirmation_too_longconfirmation passa de 1.000 caracteres.
400 button_action_duplicate_buttonDuas ações para o mesmo botão.
400 exit_confirmation_too_longexitConfirmation passa de 1.000 caracteres.
403 button_action_forbiddenFalta a permissão do tipo criado, mudado ou removido.
404 button_action_template_not_foundO modelo não existe ou não é acessível.
422 button_action_params_not_foundUm id de params não é deste workspace.
422 button_action_stalebuttonText não é o texto atual do botão.
422 button_action_exit_lockedDesvio de campanha com tipo de saída ou num botão de saída.
422 marketing_template_needs_exitModelo de marketing sem saída.

Rotas

RotaO que faz
GET /whatsapp/templatesLista os modelos acessíveis, com filtros de status, categoria, idioma e número.
POST /whatsapp/templatesCria um modelo.
GET /whatsapp/templates/{id}Consulta um modelo.
PUT /whatsapp/templates/{id}/contentEdita o conteúdo.
DELETE /whatsapp/templates/{id}Remove o modelo.
POST /whatsapp/templates/syncSincroniza os modelos com a Meta.
POST /whatsapp/templates/{id}/syncSincroniza um modelo.
PATCH /whatsapp/templates/{id}/header-mediaDefine a mídia de envio do cabeçalho.
POST /whatsapp/templates/variable-names/checkConfere nomes de variáveis.
GET /whatsapp/templates/{id}/healthSaúde do modelo.
GET e PUT /whatsapp/templates/{id}/button-actionsLê e salva as ações e a confirmação de saída.
GET /whatsapp/templates/{id}/exit-verdictVeredito de saída de um modelo.
POST /whatsapp/templates/exit-verdictVeredito de saída de um rascunho.
GET /whatsapp/button-action-kindsTipos de ação que quem pede pode configurar.
GET e PUT /whatsapp/campaigns/{id}/button-routesLê e salva os desvios de uma campanha.