Skip to content

Templates

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.

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.

Janela do terminal
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.
  • 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.

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. Without a valid handshake, the button falls back to Copy code.

Janela do terminal
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.
  • There is no 24-hour window: a template goes out at any time.

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.