Skip to main content

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.

Collecting valid consent is the foundation of a compliant SMS program. The method and disclosure language you need depend on the type of program you are running: promotional, transactional, or OTP.

​
Promotional opt-ins

Promotional messages require the highest standard of consent. The subscriber must take an affirmative action to opt in.

​
Opt-in collection methods

​
Web sign-up form

A form on your website, landing page, or pop-up where subscribers enter their phone number. Requirements:
  • The SMS opt-in checkbox must be unchecked by default.
  • Disclosure language must appear on the same form, above the submit button, not linked away or buried.
  • SMS consent must be collected separately from email consent.

​
Text-to-subscribe keyword

Subscribers text a keyword to your sender number to opt in (for example, “Text DISCOUNT to 58120”). You define the keyword and the confirmation message sent back.
With iOS 26, messages from numbers not saved as contacts are filtered into a separate “Unknown Senders” folder. Because text-to-subscribe has the subscriber send the first message, your number appears in their message history before you respond, making it a known sender. This is one of the best collection methods for iOS inbox visibility.

​
QR code

A QR code that opens the subscriber’s SMS app with your sender number and keyword pre-populated. Ideal for in-store signage, product packaging, receipts, and events. To create one, use an SMS QR code generator that supports the sms: URL format (for example, QR Code Dynamic or QRKIT). The underlying URL format is sms:+[phone_number]?body=KEYWORD. For an RCS agent, use sms:+[phone_number]?service_id=[your_agent_id]%40rbm.goog&body=MESSAGE. You can find your phone number and agent ID in Settings > Senders. Wherever you share the QR code, include disclosure language on the same surface: program description, message frequency, “Msg & data rates may apply,” and opt-out instructions.
Like text-to-subscribe, QR codes establish your number as a known sender before you reply, giving them the same iOS 26 inbox visibility advantage.

​
Checkout and point-of-sale

Collect opt-ins at the moment of purchase. The opt-in must be a separate, unchecked checkbox and cannot be framed as required for order confirmations or delivery updates.

​
Physical sign-up form

Collect phone numbers on a printed form at retail locations, events, or service counters. Include the same disclosure language required for digital opt-ins. Import these subscribers via CSV or API. See Importing subscribers.

​
Email

An opt-in prompt in an existing email campaign asking subscribers to also join your SMS list. Having an email address does not imply SMS consent. The subscriber must actively opt in through a separate action. For code examples, see the OneSignal signup form examples and email and SMS collection sample on GitHub.

​
Required disclosure language

Every promotional opt-in disclosure must cover:
  • Your brand name
  • That the subscriber will receive recurring automated marketing messages
  • Message frequency (approximate)
  • “Msg & data rates may apply”
  • How to opt out (STOP)
  • Links to your Terms of Service and Privacy Policy
  • A statement that consent is not a condition of purchase
The program description must explicitly state the messages are for marketing. Vague language like “updates” or “information” is not sufficient. Pre-checked checkboxes are non-compliant everywhere.

​
Transactional opt-ins

Transactional messages have a lower consent bar than promotional messages. A user entering their phone number in a form that includes disclosure language is sufficient opt-in. No separate checkbox is required. The disclosure must appear directly on or near the phone number field. It cannot be on a separate page or buried in terms of service.

​
Common collection points by use case

Use caseWhere to collect
Order confirmations and shipping updatesCheckout, near the phone number field
Account notifications (security alerts, billing)Account creation or sign-up form
Appointment remindersBooking or scheduling form
Onboarding sequencesAccount creation or profile setup
Notification preferencesIn-app or web preferences page

​
Required disclosure language

Every transactional opt-in disclosure must include:
  • Your brand name
  • The specific types of messages the user will receive (for example, “order confirmation and shipping update text messages,” rather than just “messages” or “updates”)
  • “Msg & data rates may apply”
  • How to opt out (for example, “Reply STOP to opt out”)
A phone number alone is not consent. If your form collects a phone number but has no disclosure text, you don’t have consent to send text messages.Consent is scoped to the stated purpose. If a user consented to receive shipping updates at checkout, that does not cover sending them appointment reminders from a different part of your business.

​
OTP opt-ins

Consent for one-time password messages follows the same standard as transactional messages. A user entering their phone number in a form that includes disclosure language is sufficient. Every OTP opt-in disclosure must include:
  • Your brand name
  • The specific types of messages the user will receive (for example, “verification codes and security alerts”)
  • “Msg & data rates may apply”
  • How to opt out (for example, “Reply STOP to opt out”)

​
Audience validation

A clean subscriber list improves deliverability, reduces costs, and keeps your program compliant.

​
Validate phone numbers with Lookup

Before adding a number to your subscriber list, use OneSignal’s Lookup to verify it. Lookup checks whether a phone number is valid, active, and mobile, filtering out landlines, VoIP numbers, disconnected lines, and mistyped numbers before they ever receive a message. Run Lookup at the point of collection (for example, on form submission) or as a batch operation on your existing subscribers.

​
Only collect numbers for regions you can send to

Make sure you’re only collecting phone numbers in geographies where you have a sender with an approved sender resource for that geography. If you don’t have a sender with an approved sender resource for a given country, messages to numbers in that country will fail.

​
Verify ownership with a one-time password

Lookup confirms a number is valid, but it doesn’t confirm the person signing up actually owns that number. To close that gap, send a one-time password immediately after the subscriber enters their phone number. See One-time passwords for how to set up OTPs with OneSignal Verify or your own backend.

​
Collect numbers in E.164 format

Phone numbers should be stored in E.164 format: a country code followed by the subscriber number with no spaces, dashes, or parentheses (for example, +14155551234). This is the format carriers and messaging platforms expect. If your sign-up form accepts free-text phone input, validate and normalize the number to E.164 before saving it. OneSignal’s API and CSV import both expect E.164 format.

​
Branding your sender with a contact card

A contact card (vCard) lets subscribers save your business as a contact on their phone. Once saved, your brand name and logo appear in place of an unknown phone number. This improves visibility, reduces the chance messages are ignored, and helps you avoid the iOS “Unknown Senders” inbox. You deliver a contact card by sending a .vcf file as an MMS message.

​
Create your vCard file

Create a .vcf file with your business contact information. You can use an online vCard generator or write it in a text editor. The format is plain text: 
BEGIN:VCARD
VERSION:3.0
FN:Your Business Name
ORG:Your Business Name
TEL;TYPE=CELL:+15551234567
END:VCARD
Use the same phone number as your SMS sender identity. You can optionally include a PHOTO property with your brand logo to have it appear alongside the contact name.

​
Host the file at a public URL

The .vcf file must be accessible via a direct, publicly reachable URL, not a download page or preview. Host it on your CDN, web server, or cloud storage (AWS S3, Google Cloud Storage) with public read access enabled.

​
Send the contact card

1

Create a new SMS message

In the OneSignal dashboard, create a new SMS message.
2

Attach the vCard URL

In the Media URL field, paste the public URL to your hosted .vcf file.
3

Add the message body

Encourage the subscriber to save your contact, for example: “Save our contact so you always know it’s us! Tap the attachment to add us to your contacts.”
4

Send it as part of your welcome flow

Send it when a new subscriber opts in, so your number is recognized before any future messages arrive.
Sending a contact card uses the media URL field, which means the message is sent as MMS and billed at MMS rates.

​
FAQ

Promotional messages require express written consent, an affirmative action like checking an unchecked box or texting a keyword. Transactional messages have a lower bar: a user entering their phone number in a form where disclosure language is visible is sufficient. The disclosure must be present and specific about what types of messages they’ll receive.

​
Do I need double opt-in for all promotional programs?

Double opt-in is required for cart abandonment programs in the US. For other promotional programs it is optional, but strongly recommended — it reduces spam complaints, improves list quality, and provides stronger consent documentation. You can use the same form, but you must collect consent for each channel separately. Bundling SMS consent with email consent (for example, a single checkbox for both) is non-compliant for SMS.

​
Can I import subscribers from another provider?

Yes, if they have already provided valid consent that meets the requirements for the program type you are running. See Importing subscribers for how to transfer existing subscribers via CSV or API.

​
What is E.164 format?

E.164 is the international standard phone number format: a plus sign, country code, and subscriber number with no spaces or punctuation (for example, +14155551234 for a US number). OneSignal’s API and CSV import require numbers in this format.

​
Why should I use Lookup before adding subscribers?

Sending to invalid, landline, or disconnected numbers wastes spend and can hurt your sender reputation with carriers. Lookup filters these out before they reach your list, which improves deliverability and reduces costs.

Consent keyword management

Manage STOP, HELP, START, and custom opt-out keywords after subscribers opt in.

Regulatory compliance

Carrier rules, quiet hours, prohibited content, and the broader regulatory framework.

One-time passwords

Set up OTPs with OneSignal Verify or your own backend to verify number ownership.

Promotional messaging

Promotional-specific patterns: double opt-in setup, preference centers, and sending guidance.