# Authentication templates

> Verification codes (OTP) over WhatsApp: the 3 button types, the Android app handshake and sending with type otp, without the code being stored.

An authentication template carries a **one-time code** (login, sign-up confirmation, password reset). Meta fixes the text; you choose the button, the expiry and the language. The code is **yours**: Messajo neither generates nor checks codes, it only delivers them, and never stores the code anywhere.

## The 3 button types

| `otp_type` | What the contact sees | Requirement |
|---|---|---|
| `COPY_CODE` | a **Copy code** button | none |
| `ONE_TAP` | a button that fills the code in your Android app | handshake in the app; `supported_apps` |
| `ZERO_TAP` | the code goes into the app by itself, no tap | handshake in the app; `supported_apps`; accept Meta's terms (`zero_tap_terms_accepted: true`) |

When the app has not done the handshake (or the contact is on an iPhone), `ONE_TAP` and `ZERO_TAP` fall back to **Copy code**.

## Create

```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": "login_code",
    "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": "Copy code",
      "autofill_text": "Autofill",
      "supported_apps": [{ "package_name": "com.yourcompany.app", "signature_hash": "K8a/AINcGX7" }]
    }
  }'
```

- It returns one template per language (up to 20), under Meta review, like other [templates](/en/start/concepts/).
- `add_security_recommendation` adds "For your security, do not share this code".
- `code_expiration_minutes` (1 to 90) adds the footer with the expiry.
- `message_send_ttl_seconds` (30 to 900): after this time without delivery, Meta gives up (the code would have expired anyway).
- `supported_apps`: 1 to 5 apps, each with its `package_name` and 11-character `signature_hash`.

`POST /v1/templates/authentication/preview` with the same fields shows the text Meta will generate, without creating anything. In the panel, **Templates → New template → Authentication**.

## Android app handshake

`ONE_TAP` and `ZERO_TAP` only work if your app tells WhatsApp **before** you send the code:

1. Generate the `signature_hash` of the certificate that signs the app (the same 11-character hash as Google's SMS Retriever API).
2. In the app, right before asking your backend for the code, send the handshake intent to WhatsApp (`com.whatsapp` and `com.whatsapp.w4b`) with a `PendingIntent` from your app.
3. For `ONE_TAP`, receive the code in the Activity that handles `com.whatsapp.otp.OTP_RETRIEVED`; for `ZERO_TAP`, in a `BroadcastReceiver` with the same action.

The step-by-step with Kotlin code is in [Meta's documentation](https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates). Without a valid handshake, the button falls back to **Copy code**.

## Sending the code

```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": "login_code", "language": "en_US" }, "code": "482913" }
  }'
```

- Use `template_id` (`tpl_…`) **or** `template` (name and language), one of the two.
- `code`: 4 to 15 letters or digits.
- The template must be `AUTHENTICATION` and approved; otherwise `422` [`otp_template_invalid`](/en/errors#otp_template_invalid).
- There is no 24-hour window: a template goes out at any time.

## The code is not stored

The code only exists in the call to Meta. The stored message, the events (`message.sent`, `message.status`), the logs and the response kept for the `Idempotency-Key` carry `code: "••••"` and `otp: true`. You check the typed code against what **your** system generated, never against Messajo.

Good practice: short codes with a short expiry, an attempt limit in your backend and a new code for each request.
