Skip to main content
A one-time code is the short number you ask a person to type to prove they control a phone: a login, a sign-up, a booking confirmation. Boom sends the code over WhatsApp and remembers it; your backend then asks Boom whether what the person typed is right. Boom handles the code itself (generating it, resending it, expiring it, limiting wrong guesses). What a valid code unlocks stays in your app. Today codes go out over WhatsApp only.

​
Before you start

  • One-time codes are available to every workspace. You need a connected WhatsApp number and an approved authentication template.
  • Go to One-time codes in the dashboard and choose the WhatsApp number the codes are sent from, then an approved authentication template (or create one there; it must be approved by WhatsApp first). Turn codes on.
  • The template sets the message and the expiry. WhatsApp writes the text of an authentication message, and the minutes a code stays valid are the ones set on the template. A request can’t change either. If the template shows no expiry, Boom treats the code as valid for 10 minutes.
  • Use an API key from your backend.
Any of your organization’s API keys can send and verify codes. Keys are not scoped to endpoints today, so create a dedicated key for the backend that sends codes, and never put it in a browser or mobile app.
The examples use these two variables. Note that the base here is the host, not the /api/v1/cdp base other pages use:

​
Send a code

Pass exactly one of: reference (optional, up to 255 characters) is your label for what the code is for, such as an appointment id. It is echoed back and can be used to verify. Keep the otpId: it is the simplest way to verify.

​
Verify a code

Identify the code with exactly one of otpId, phone or personExternalId (the last two together with the same reference you sent with, if any). code is the 6 to 10 digits the person entered. A wrong code is not an HTTP error: you get 200 with valid: false. attemptsRemaining counts the wrong guesses left before the code locks. The limit is set on the dashboard (5 by default). Boom also stops guessing across codes: after 20 wrong codes for the same phone within 24 hours, further attempts are refused (valid: false, the code stays PENDING, attemptsRemaining doesn’t move) until older failures age out. 404 otp_not_found means no code matches. 422 otp_unverifiable means Boom can no longer check that code; send a new one.

​
Resending

Calling send again for the same person while their code is still valid sends the same code again and returns the same otpId with resent: true. The expiry does not move. Once the code has expired, the next send creates a new one. Two limits apply, both set on the dashboard (defaults shown):
  • Cooldown (30 seconds): a send to a phone too soon after the last send to it is refused.
  • Hourly cap (5 sends per phone per hour).
Both count per phone, across every person and reference on it. If the code is about to expire when you call send, Boom issues a new code with a new otpId (resent: false) instead of resending one the person can barely use. Both answer 429, and the error body tells you how long to wait:
code is resend_cooldown or too_many_sends. Read retryAfterSeconds from the body: these 429s don’t set a Retry-After header. Two requests for the same phone at the same moment are treated as one, and the second gets resend_cooldown.

​
People who share a phone

A family, a clinic front desk or a shared work phone can mean several people on one number. By default a phone has one live code. To give each person their own, pass personExternalId or reference on both send and verify:
A code sent for one reference (or person) never verifies another’s. A verify by bare phone only matches codes that were sent without either. The cooldown and the hourly cap count per phone, not per person: one patient’s send also starts the cooldown for the others on that number.

​
Errors

Errors use the standard shape.
Boom does not apply a limit across your whole organization: only the per-phone cooldown, hourly cap and wrong-guess limits above. Protecting your endpoint from abuse (for example someone requesting codes for numbers that aren’t theirs) is up to your app.

​
Billing and the inbox

Each code that WhatsApp delivers is billed as an authentication template message, and so is each delivered resend. The Send a test code button on the dashboard sends and bills a real code too. Codes appear in the person’s conversation like any outbound message, but the code itself is shown as dots (••••••) in the inbox and in the stored message. Boom keeps the code encrypted only while it can still be resent and clears it once the code is verified, expired or locked. Code records, with the phone number they were sent to, are deleted after 90 days. Sending a code doesn’t reopen a closed conversation or assign it to anyone.