On this page
Guides / WhatsApp OTP codes

WhatsApp OTP codes

Send verification codes over WhatsApp from your backend with an authentication template. You generate and check the code; Meteor delivers it.

Updated View .md
StackNode · TypeScript SDK
Endpointschannels.createTemplate · channels.templates · contacts.create · channels.whatsapp.sendTemplate with purpose: 'authentication'

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:

StepDone by
Generate the code (for example, 6 random digits)Your backend
Store it with its expiry and attemptsYour backend
Deliver it over WhatsApp with the authentication templateMeteor
Compare what the person typed with what you storedYour 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

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: true validates 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:

Errors

CodeHTTPWhat happenedWhat to do
authentication_send_not_enabled403OTP sending is off for your accountContact support
authentication_template_required403The template does not exist with that name and language, is not approved, or is not AUTHENTICATION in the line's accountCheck channels.templates
authentication_template_unverifiable503The template or account could not be confirmed with MetaRetry in a few seconds
authentication_contact_unverifiable503The contact could not be verifiedRetry
—404The contact is not in your workspaceCreate the contact (step 2)
authentication_provider_rejected400WhatsApp did not accept the send; includes provider_codeCheck 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.