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.
The 3 button types
Section titled “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
Section titled “Create”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_recommendationadds “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 itspackage_nameand 11-charactersignature_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
Section titled “Android app handshake”ONE_TAP and ZERO_TAP only work if your app tells WhatsApp before you send the code:
- Generate the
signature_hashof the certificate that signs the app (the same 11-character hash as Google’s SMS Retriever API). - In the app, right before asking your backend for the code, send the handshake intent to WhatsApp (
com.whatsappandcom.whatsapp.w4b) with aPendingIntentfrom your app. - For
ONE_TAP, receive the code in the Activity that handlescom.whatsapp.otp.OTP_RETRIEVED; forZERO_TAP, in aBroadcastReceiverwith 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.
Sending the code
Section titled “Sending the code”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_…) ortemplate(name and language), one of the two. code: 4 to 15 letters or digits.- The template must be
AUTHENTICATIONand approved; otherwise422otp_template_invalid. - There is no 24-hour window: a template goes out at any time.
The code is not stored
Section titled “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.