# Verification codes (OTP) over WhatsApp

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:send` and `contacts:write`
  scopes (see [Authentication](authentication.html)).
- 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.

```ts
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:

```ts
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](whatsapp-templates.html)).

## 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:

```ts
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

```ts
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:

- **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](errors-and-idempotency.html)), and check your plan's
caps in [Limits](limits.html).
