WhatsApp OTP codes
Send verification codes over WhatsApp from your backend with an authentication template. You generate and check the code; Meteor delivers it.
Use it for sign-up, login or confirming a payment on your platform: your user types their number, gets a code on WhatsApp and types it back on your screen.
Who does what
This comes first, because it shapes everything else:
| Step | Done by |
|---|---|
| Generate the code (for example, 6 random digits) | Your backend |
| Store it with its expiry and attempts | Your backend |
| Deliver it over WhatsApp with the authentication template | Meteor |
| Compare what the person typed with what you stored | Your backend |
Meteor does not generate or check the code, and does not store it: the contact's chat only shows the note "Verification code sent over WhatsApp", never the code. The code lives in one place: yours.
What you need
- An API key with the
channels:read,channels:sendandcontacts:writescopes (see Authentication). - A WhatsApp channel connected to your workspace.
- An
AUTHENTICATION-category template approved by Meta, in the same WhatsApp account (WABA) as the sending line. A template from another category is rejected, even if its text says "your code is…".
OTP sending is available for every account. Meteor can turn it off for a specific account; if that happens, the response is authentication_send_not_enabled and you need to contact support.
1. Create the authentication template (once)
Meta fixes the shape of these templates: Meta writes the text in the template's language ("*123456* is your verification code"). You only choose whether it shows the security notice and how many minutes the code lasts.
const channels = await met.channels.list();
const whatsapp = channels.find((c) => c.type === 'whatsapp')!;
await met.channels.createTemplate(whatsapp.id, {
name: 'codigo_verificacion',
language: 'es',
category: 'AUTHENTICATION',
components: [
// No `text`: Meta rejects a BODY with text in this category.
{ type: 'BODY', add_security_recommendation: true },
{ type: 'FOOTER', code_expiration_minutes: 10 },
// Copy-code button. No `text`: Meta adds "Copy code".
{ type: 'BUTTONS', buttons: [{ type: 'OTP', otp_type: 'COPY_CODE' }] },
],
});
The template starts under review (PENDING). Before using it, check that it is APPROVED and which account it belongs to:
const { data } = await met.channels.templates(whatsapp.id, { name: 'codigo_verificacion' });
const otp = data.find((t) => t.name === 'codigo_verificacion' && t.language === 'es');
// otp.status === 'APPROVED' && otp.category === 'AUTHENTICATION'
If the channel has several WhatsApp accounts, the template must be approved in the account of the sending line (see WhatsApp templates through the API).
2. The contact must exist
The code goes to a contact in your workspace, not to a loose number. If the person is new, create them first with their number:
const contact = await met.contacts.create({ name: 'Ana Pérez', phone: '+573001234567' });
A contact blocked in Meteor does not receive codes.
3. Generate the code and send it
import { randomInt } from 'node:crypto';
const code = String(randomInt(0, 1_000_000)).padStart(6, '0');
await saveCode(user.id, code, { expiresIn: '10m', attempts: 0 }); // your database
await met.channels.whatsapp.sendTemplate(whatsapp.id, {
contact_id: contact.id,
template_name: 'codigo_verificacion',
language: 'es',
purpose: 'authentication',
components: [
{ type: 'body', parameters: [{ type: 'text', text: code }] },
// The copy button carries the SAME code.
{ type: 'button', sub_type: 'url', index: '0', parameters: [{ type: 'text', text: code }] },
],
});
With purpose: 'authentication', Meteor checks before sending anything that the template is an authentication template, that it is approved in the line's account and that the contact belongs to your workspace. If something does not match, no message is sent.
This send does not touch the chat's attention: it does not turn the Met back on or change who the conversation is assigned to.
Test without sending:
dry_run: truevalidates the template, the line and the contact and returns the recipient, without calling Meta. The response never includes the code.
4. Check the code
When the person types the code on your screen, you compare it with what you stored. Some rules worth following:
- Short expiry: 5 to 10 minutes, the same you set in the template.
- Few attempts: 3 to 5; after that, a new code.
- Single use: delete it once it is checked.
- Compare in constant time (
crypto.timingSafeEqual) so response time does not leak hints. - Limit resends per number and per hour: each send is an authentication conversation that Meta charges for.
Errors
| Code | HTTP | What happened | What to do |
|---|---|---|---|
authentication_send_not_enabled | 403 | OTP sending is off for your account | Contact support |
authentication_template_required | 403 | The template does not exist with that name and language, is not approved, or is not AUTHENTICATION in the line's account | Check channels.templates |
authentication_template_unverifiable | 503 | The template or account could not be confirmed with Meta | Retry in a few seconds |
authentication_contact_unverifiable | 503 | The contact could not be verified | Retry |
| — | 404 | The contact is not in your workspace | Create the contact (step 2) |
authentication_provider_rejected | 400 | WhatsApp did not accept the send; includes provider_code | Check Meta's code (for example 131026: the number has no WhatsApp) |
To retry without duplicating the send, use an idempotency key (see Errors and idempotency), and check your plan's caps in Limits.