A one-time password (OTP) message is a text containing a short, temporary code to verify a user’s identity. The user enters the code into your app or website to prove they have access to the phone number they provided. OTP messages provide:Documentation Index
Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
Use this file to discover all available pages before exploring further.
- Account protection: preventing unauthorized access reduces support costs, fraud losses, and reputational damage
- Phone number validation: an OTP that gets delivered and entered correctly confirms the number is real, active, and in the hands of the person who submitted it
- Fraud prevention at the front door: OTPs at account creation deter fake signups, bot accounts, and abuse
- Regulatory and compliance baseline: for certain industries (finance, healthcare), multi-factor authentication is required. SMS OTP is the most accessible method because it works on every phone with no app install required
- Account creation: confirming a new user’s phone number during signup
- Login / two-factor authentication: adding a second layer of verification beyond a password
- Password reset: confirming identity before allowing a credential change
- Transaction confirmation: verifying a high-value action like a money transfer or address change
Consent requirements
Consent for OTP messages follows the same standard as transactional messages. A user entering their phone number in a form that includes disclosure language is sufficient opt-in. The disclosure must appear directly on or near the phone number field, not on a separate page or buried in terms of service.Required disclosure language
Disclosure language requirements and the full OTP opt-in compliance rules.
How to send OTP messages
There are two ways to send OTP messages with OneSignal:| Method | Best for | What you manage |
|---|---|---|
| OneSignal Verify (Recommended) | Teams that want a managed solution: code generation, delivery, and validation handled for you | Configuration only |
| Build your own | Teams that need custom verification logic or already have a code generation system | Code generation, storage, expiration, rate limiting, and validation |
OneSignal Verify
Verify is only available to OneSignal SMS customers (not the Twilio integration).
Create a verification service
Set a friendly name (your brand name), code length, and how often a code regenerates.
Send a verification code
Provide the user’s phone number and the channel (
sms). Optionally specify a custom code or override the code length.By default, the message sent to the end user says: “Your [brand name] verification code is: XXXXXX.”Additional considerations
- Expiration: Codes expire after 10 minutes by default. Contact support to customize.
- Retries: Handle failed verification attempts and implement retry logic in your app.
- Security: Follow best practices for handling sensitive data like phone numbers and verification codes.
Build your own code authentication
You can also manage verification logic yourself: generating codes, tracking expiration, and validating attempts in your own backend. In this approach, you send OTP messages through the OneSignal Create Message API as a standard API-triggered SMS.Send it via the OneSignal API
Call the Create Message endpoint with the recipient’s phone number, your OTP sender, and a message body containing the code (for example, “Your [brand name] verification code is 847291. It expires in 10 minutes.”).
Your responsibilities
- Generating and storing codes securely
- Enforcing expiration: codes should not be valid indefinitely
- Rate limiting: cap how many codes a single phone number can request in a given window to prevent SMS pumping fraud
- Attempt limits: lock out after a set number of failed entries (for example, 3–5 attempts) to prevent brute-force attacks
- Retry logic: handling cases where the SMS fails to deliver
Dedicated sender best practice
While you can send OTP messages from any sender, it is best practice to use a dedicated sender approved for the authentication use case. If your OTP messages share a sender with promotional or transactional messages, a single STOP opt-out means the user can no longer receive verification codes, effectively locking them out of their own account. A dedicated OTP sender keeps opt-outs scoped so a marketing unsubscribe never blocks a security code.Audience validation
A clean subscriber list is essential for OTP deliverability. Invalid or disconnected numbers mean verification codes don’t reach the user, which can block account creation, lock users out of password resets, and erode trust in your authentication flow. Validate phone numbers with Lookup at the point of collection, only collect numbers for regions you have an approved sender resource in, and store all numbers in E.164 format (for example,+14155551234).
Audience validation
Full details on Lookup, region restrictions, ownership verification, and E.164 formatting.
FAQ
What’s the difference between OneSignal Verify and building my own OTP?
OneSignal Verify handles code generation, delivery, and validation for you. You only manage configuration. Building your own gives you more control over verification logic, but you are responsible for code generation, storage, expiration, rate limiting, and retry handling. OneSignal Verify is only available to OneSignal SMS customers (not the Twilio integration).How long do verification codes last with OneSignal Verify?
Codes expire after 10 minutes by default. Contact OneSignal support to customize the expiration window.Why do I need a dedicated sender for OTPs?
If a user texts STOP to a sender that handles both OTPs and other message types, they are opted out of all messages from that sender, including verification codes. This can lock them out of their account. A dedicated OTP sender keeps opt-outs cleanly scoped.What happens if an OTP fails to deliver?
With OneSignal Verify, contact support if you see widespread delivery failures. If you are building your own, implement retry logic in your backend and monitor for error codes in Audience Activity. See SMS message reports for error code troubleshooting.Can I use OTP messages for account creation verification?
Yes. This is one of the most common use cases: sending a code during signup to confirm the user owns the phone number they provided. Lookup can also help at this stage to validate the number before sending.Related pages
SMS opt-in and collection
Collection methods, required disclosure language, and audience validation for all program types.
Transactional messaging
Transactional use cases and collection points alongside OTP programs.
SMS message reports
Delivery metrics and SMS error codes for troubleshooting OTP failures.
Create Message API
API reference for triggering OTP and transactional sends from your backend.