Modelos de Autenticação (OTP): Regras, Criação e Envio

Os modelos de mensagem da categoria Autenticação (também conhecidos como OTP - One Time Password) são utilizados exclusivamente para enviar códigos de verificação, senhas temporárias ou tokens de login para os usuários do WhatsApp.

Devido à natureza sensível e de segurança desse tipo de mensagem, a Meta e a nossa plataforma possuem regras de funcionamento diferentes dos modelos de Marketing e Utilidade.

⚠️ Regras Fundamentais (Leia Antes de Começar)

Para garantir a segurança e o funcionamento correto dos códigos de verificação, existem duas restrições técnicas importantes na nossa plataforma:

Criação Exclusiva na Plataforma: Diferente de outros modelos, os templates de Autenticação DEVEM ser criados diretamente no nosso sistema.
- Não é possível criar o modelo no painel da Meta (Facebook) e depois sincronizá-lo/importá-lo para cá. O vínculo técnico precisa nascer na plataforma.
Disparo Exclusivo via API: Modelos de autenticação não aparecem para os atendentes na tela de atendimento e não podem ser usados em campanhas de marketing ou sequências.
- Eles foram desenhados para serem disparados automaticamente pelo seu sistema (site/app) através da nossa API de Integração.

1. Diretrizes da Meta para Autenticação

A Meta impõe um formato rígido para esses modelos. Você não tem liberdade criativa para escrever textos longos. O modelo segue um padrão fixo para garantir que o usuário reconheça imediatamente que se trata de um código de segurança.

Estrutura Padrão:

Texto fixo: "Seu código de verificação é {{codigo}}" (ou variações muito similares).
Botão Obrigatório: Um botão de "Copiar código" (ou "Toque para preencher") é inserido automaticamente.
Rodapé de Segurança (Opcional): Você pode optar por exibir um aviso de segurança ("Não compartilhe este código").
Validade: O código também pode ter um tempo de expiração visível.

Atenção

Nota: Imagens, vídeos e cabeçalhos personalizados não são permitidos nesta categoria.

2. Como Criar um Modelo de Autenticação

Siga o passo a passo abaixo para cadastrar seu modelo corretamente:

Acesse o menu Ajustes > Modelos de Mensagem.
Clique no botão + Novo no canto superior direito.
No modal de seleção de tipo, escolha a opção Autenticação (ícone de chave)

Preencha os dados básicos:

Nome: Identificador interno (sem espaços ou caracteres especiais).
Canal: Selecione o canal oficial que enviará os códigos.

Configuração de Segurança:

O corpo da mensagem já virá pré-preenchido conforme o padrão da Meta.
Adicionar recomendação de segurança: Marque esta caixa se desejar incluir o aviso "Por segurança, não compartilhe este código".

Clique em Salvar.

O modelo será enviado para análise da Meta. Assim que o status mudar para ATIVO, ele estará pronto para uso via API.

3. Como Disparar via API (Integração)

Uma vez aprovado, o disparo deve ser feito integrando o seu sistema ao nosso endpoint dedicado de OTP: Modelos de Mensagem > Enviar OTP

Endpoint de Envio: POST https://api.trilhawhats.com.br/chat/v1/template/otp/send

Parâmetros Principais:

from: Número do canal remetente.
to: Telefone do destinatário.
templateId: O ID do modelo de autenticação criado.
code (Opcional): O código numérico ou alfanumérico que será enviado.
- Dica: Se você não enviar este campo, nossa plataforma pode gerar um código aleatório de 5 dígitos automaticamente para você.

Exemplo de Requisição (cURL):

curl --request POST \
  --url [https://api.trilhawhats.com.br/chat/v1/template/otp/send](https://api.trilhawhats.com.br/chat/v1/template/otp/send) \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "to": "5511999999999",
    "templateId": "auth_login_01",
    "code": "85294"
  }'

Consultando o Status e Validação

Após o envio, você pode consultar se a mensagem foi entregue ou verificar o status do código através do endpoint de consulta: Modelos de Mensagem > Consultar OTP.

Endpoint de Envio: GET https://api.trilhawhats.com.br/chat/v1/template/otp/{messageId}/status