Templates de WhatsApp

O canal de WhatsApp do Portal usa a conta Meta da própria organização (BYO) e só envia mensagens iniciadas pela empresa (fora da janela de 24 horas) por template aprovado na Meta — não há texto livre. Este guia lista os templates sugeridos (genéricos, espelhando os textos de e-mail/SMS) para o responsável pela conta Meta criar e aprovar. Depois de aprovados, o administrador do tenant seleciona cada template e mapeia as variáveis nas telas do Portal.

Convenção

Use nomes começando com portal_ e crie ao menos em pt_BR (e en/es, com o mesmo nome, se o portal atender nesses idiomas). As variáveis da Meta são posicionais ({{1}}, {{2}}…); no Portal, cada posição é mapeada para um placeholder (ex.: {{ticketId}}), substituído no envio.

Placeholders disponíveis

• Notificações: {{name}}, {{ticketId}}, {{taskId}}, {{ticketLink}}, {{taskLink}}, {{serviceName}}, {{taskTitle}}, {{portalName}}, {{portalBaseUrl}}.
• 2FA: {{code}}, {{minutes}}, {{portalName}}, {{name}}.

{{ticketLink}} e {{taskLink}} já vêm com a URL completa do deep-link do chamado/tarefa ({{portalBaseUrl}}/tickets/<id> e /tasks/<id>) — prontos para usar no corpo (não servem no botão; veja abaixo).

Botão de URL — como a Meta trata

A Meta não aceita uma URL completa como valor de variável de botão. O botão de URL tem a base fixa no template (definida na criação, obrigatoriamente https://); a variável {{1}}, quando existe, só completa o final (um caminho ou argumento). Há três formas válidas de deep-link (o Portal tem as rotas /tickets/:id e /tasks/:id):

1. No corpo, URL completa numa variável (recomendado): o corpo tem só Acesse: {{N}} e você mapeia {{N}} = {{ticketLink}} (ou {{taskLink}}) — a URL inteira vira o parâmetro e o WhatsApp deixa clicável. É o mais flexível (domínio e caminho totalmente livres).
2. No corpo, base fixa + id na variável: Acesse: https://SEU-PORTAL/tickets/{{N}}, mapeando {{N}} = {{ticketId}}. Domínio fixo no texto, só o id na variável.
3. Botão de URL com sufixo: base fixa https://SEU-PORTAL/tickets/ + variável {{1}} completando só o id ({{ticketId}}/{{taskId}}). O botão não aceita a URL inteira na variável — só o sufixo, e https:// obrigatório.

O botão é opcional nas notificações (dá para usar só o link no corpo). A exceção é o 2FA, cujo botão "Copiar código" é padrão do tipo AUTHENTICATION e recebe o código como parâmetro.

Templates sugeridos

portal_2fa_code — código de acesso (2FA)

Categoria AUTHENTICATION (obrigatória para código de uso único — a Meta não aceita UTILITY sem botão nesse caso). Mapeie em /settings/auth. Vem com o botão "Copiar código", que também exige o código como parâmetro — mapeie as duas posições (variável 1 do corpo e o botão) para {{code}}, senão a Meta rejeita com (#100) Invalid parameter. O corpo é gerado pela Meta ({{1}} = código).

Posição	Mapear para
Variável 1 (corpo)	{{code}}
Botão "Copiar código"	{{code}}

portal_task_assigned — nova tarefa aguardando o cliente

• Categoria: UTILITY
• Corpo: Olá {{1}}, há uma tarefa aguardando você no chamado #{{2}} ({{3}}). Acesse: {{4}}. Obrigado por usar nossos serviços.

Posição	Mapear para
Variável 1	{{name}}
Variável 2	{{ticketId}}
Variável 3	{{serviceName}}
Variável 4 (link)	{{ticketLink}}

portal_task_received — tarefa recebida no portal

• Categoria: UTILITY
• Corpo: Olá {{1}}, você recebeu uma tarefa no portal: {{2}} ({{3}}). Acesse: {{4}}. Obrigado por usar nossos serviços.

Posição	Mapear para
Variável 1	{{name}}
Variável 2	{{taskTitle}}
Variável 3	{{serviceName}}
Variável 4 (link)	{{taskLink}}

portal_ticket_completed — chamado concluído

• Categoria: UTILITY
• Corpo: Olá {{1}}, seu chamado #{{2}} ({{3}}) foi concluído. Acompanhe: {{4}}. Obrigado por usar nossos serviços.

Posição	Mapear para
Variável 1	{{name}}
Variável 2	{{ticketId}}
Variável 3	{{serviceName}}
Variável 4 (link)	{{ticketLink}}

dica

Mantenha a ordem das variáveis igual à do corpo. Exemplos de valor para a revisão da Meta: {{1}}=Maria, {{2}}=1042, {{3}}=Suporte, {{4}}=https://SEU-PORTAL/tickets/1042.

O corpo não pode terminar em variável

A Meta rejeita templates cujo corpo termina com uma variável. Por isso os três modelos acima encerram com a frase fixa "Obrigado por usar nossos serviços." após o link. Ao ajustar o texto, garanta que a última parte do corpo seja texto fixo, não um {{n}}.

Criando na Meta

No WhatsApp Manager → Modelos de mensagem, crie os quatro modelos com os nomes exatos (portal_2fa_code, portal_task_assigned, portal_task_received, portal_ticket_completed), as categorias acima (AUTHENTICATION no 2FA, UTILITY nos demais), idioma pt_BR e os corpos exatos. Botão de URL sempre https:// e com a base fixa (o domínio do portal do cliente).

Depois de aprovados, no Portal: em /settings/whatsapp use "Listar templates"; em /settings/notifications (WhatsApp) e /settings/auth (2FA), selecione e mapeie as variáveis conforme as tabelas. Botão de URL estática não precisa de mapeamento; só o botão OTP do 2FA precisa ({{code}}).

Padrão recomendado (produção)

Cada cliente usa a própria conta Meta (BYO) e cria os templates na sua conta. Recomenda-se:

1. Mesmos nomes e mesma ordem de variáveis dos modelos acima — o mapeamento no Portal fica idêntico entre clientes.
2. Categoria certa: AUTHENTICATION no 2FA, UTILITY nas notificações (nunca MARKETING).
3. Botão = URL estática https:// do próprio portal (base fixa no template).
4. Pode ajustar o texto e a marca, desde que preserve a quantidade e a ordem das variáveis.
5. O cliente final precisa aceitar receber WhatsApp (em Preferências) e ter telefone no cadastro.

observação

Sem template configurado para um uso, o Portal não envia por aquele canal/evento — os demais (e-mail, SMS, push) seguem normalmente.