# Templates de autenticação

> Códigos de verificação (OTP) pelo WhatsApp: os 3 tipos de botão, o handshake no app Android e o envio com type otp, sem o código ficar gravado.

Um template de autenticação leva um **código de uso único** (login, confirmação de cadastro, troca de senha). A Meta fixa o texto; você escolhe o botão, a validade e o idioma. O código é **seu**: o Messajo não gera nem confere códigos, só entrega, e não grava o código em lugar nenhum.

## Os 3 tipos de botão

| `otp_type` | O que o contato vê | Requisito |
|---|---|---|
| `COPY_CODE` | botão **Copiar código** | nenhum |
| `ONE_TAP` | botão que preenche o código no seu app Android | handshake no app; `supported_apps` |
| `ZERO_TAP` | o código entra no app sozinho, sem toque | handshake no app; `supported_apps`; aceitar os termos da Meta (`zero_tap_terms_accepted: true`) |

Quando o app não fez o handshake (ou o contato está no iPhone), `ONE_TAP` e `ZERO_TAP` viram **Copiar código**.

## Criar

```bash
curl https://api.messajo.com/v1/templates/authentication \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "conn_...",
    "name": "codigo_login",
    "languages": ["pt_BR", "en_US", "es"],
    "add_security_recommendation": true,
    "code_expiration_minutes": 10,
    "message_send_ttl_seconds": 300,
    "button": {
      "otp_type": "ONE_TAP",
      "text": "Copiar código",
      "autofill_text": "Preencher",
      "supported_apps": [{ "package_name": "com.suaempresa.app", "signature_hash": "K8a/AINcGX7" }]
    }
  }'
```

- Volta um template por idioma (até 20), em revisão na Meta, como os outros [templates](/start/concepts/).
- `add_security_recommendation` acrescenta "Para sua segurança, não compartilhe este código".
- `code_expiration_minutes` (1 a 90) acrescenta o rodapé com a validade.
- `message_send_ttl_seconds` (30 a 900): depois desse tempo sem entregar, a Meta desiste (o código já teria vencido).
- `supported_apps`: de 1 a 5 apps, cada um com o `package_name` e o `signature_hash` de 11 caracteres.

`POST /v1/templates/authentication/preview` com os mesmos campos mostra o texto que a Meta vai gerar, sem criar nada. No painel, **Templates → Novo template → Autenticação**.

## Handshake no app Android

`ONE_TAP` e `ZERO_TAP` só funcionam se o seu app avisar o WhatsApp **antes** de você mandar o código:

1. Gere o `signature_hash` do certificado que assina o app (o mesmo hash de 11 caracteres da SMS Retriever API do Google).
2. No app, logo antes de pedir o código ao seu backend, mande o intent de handshake para o WhatsApp (`com.whatsapp` e `com.whatsapp.w4b`) com um `PendingIntent` do seu app.
3. Para `ONE_TAP`, receba o código na Activity que trata `com.whatsapp.otp.OTP_RETRIEVED`; para `ZERO_TAP`, num `BroadcastReceiver` com o mesmo action.

O passo a passo com código Kotlin está na [documentação da Meta](https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates). Sem handshake válido, o botão cai para **Copiar código**.

## Mandar o código

```bash
curl https://api.messajo.com/v1/messages \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7b0c…" \
  -d '{
    "connection_id": "conn_...",
    "to": "5511999990001",
    "type": "otp",
    "otp": { "template": { "name": "codigo_login", "language": "pt_BR" }, "code": "482913" }
  }'
```

- Use `template_id` (`tpl_…`) **ou** `template` (nome e idioma), um dos dois.
- `code`: de 4 a 15 letras ou números.
- O template precisa ser `AUTHENTICATION` e estar aprovado; senão `422` [`otp_template_invalid`](/errors#otp_template_invalid).
- Não há janela de 24 h: template sai a qualquer hora.

## O código não fica gravado

O código só existe na chamada à Meta. A mensagem guardada, os eventos (`message.sent`, `message.status`), os logs e a resposta guardada para a `Idempotency-Key` levam `code: "••••"` e `otp: true`. Você confere o código digitado contra o que o **seu** sistema gerou, nunca contra o Messajo.

Boas práticas: código curto e com validade curta, limite de tentativas no seu backend e um código novo a cada pedido.
