SMS setup
Complete setup guide for SMS and MMS messaging with OneSignal, including provider configuration, subscriber management, compliance, and message design.
Overview
SMS is a scalable channel for reaching users in real-time, even outside your app or website. It boasts some of the highest open and engagement rates of all messaging channels.
SMS channel setup overview
Before sending SMS or MMS messages, make sure you:
- Follow SMS Regulatory Compliance
- Meet SMS Registration Requirements including user consent
- Properly configure your SMS provider credentials
SMS setup
In your OneSignal dashboard, navigate to Settings > SMS > Set up SMS.
Activating SMS platform in OneSignal settings
Select provider
You can send SMS using either OneSignal-managed infrastructure or your own Twilio account.
SMS provider selection options
OneSignal leverages Twilio under the hood. Choose this if:
- You send more than 5,000 SMS per month
- You are on a paid OneSignal plan (see pricing)
Click Book Demo with SMS Expert to get assistance from our team.
While waiting for verification, you can begin Designing SMS & MMS templates and ensuring you meet the SMS registration requirements.
OneSignal leverages Twilio under the hood. Choose this if:
- You send more than 5,000 SMS per month
- You are on a paid OneSignal plan (see pricing)
Click Book Demo with SMS Expert to get assistance from our team.
While waiting for verification, you can begin Designing SMS & MMS templates and ensuring you meet the SMS registration requirements.
Use this option if:
- You send fewer than 5,000 SMS per month
- You want full control of your Twilio account
This is ideal for testing or small-scale sending. Ensure your Twilio phone number supports SMS (and MMS if needed).
Need help from a teammate? Use Manage Team Members to invite them and share this guide.
Configure Twilio
Add your Twilio Account SID and Auth Token from your Twilio dashboard.
SMS Configuration Screen - Twilio Details
Click Next: Add Phone Numbers.
Set default “From” number
Once verified, OneSignal will retrieve all Twilio phone numbers linked to your account.
Select a default number to use when sending. You can override this later during message creation.
Setting a default phone number
Send a test SMS
Enter your phone number and click Send Test SMS.
If the message doesn’t arrive:
- Confirm the default number supports SMS
- Check Twilio logs for errors
Twilio trial accounts require recipient numbers to be pre-registered.
Click Next: Add Subscribers.
Understanding users and subscriptions
Each unique phone number is treated as a separate SMS subscription in OneSignal.
Subscriptions can be created by:
- Uploading phone numbers via CSV
- Using the API
- Capturing numbers with a web prompt
- Using the SDK’s
addSms
method
Refer to SMS Opt-in and Collection for implementation details.
Important:
- Use E.164 format for phone numbers
- Phone numbers are considered anonymous until you assign them an External ID.
Users
Manage users, assign External IDs, and track activity.
Subscriptions
Learn how subscriptions work across devices.
Segments
Target users based on behavior and traits.
Upload CSV
Bulk upload phone numbers to create subscribers.
Create User/Subscription APIs
Use APIs to manage SMS users.
Web Prompt
Prompt users to input their phone number.
SMS SDK Methods
Programmatically add or remove SMS subscribers.
Design SMS & MMS
Great SMS/MMS messages are concise, personalized, and cost-effective. Each message is charged per segment.
Pricing is based on message segments, which depend on character count and encoding type. If your message exceeds segment limits, it may be split and billed as multiple messages.
Use OneSignal’s built-in character estimation to preview segment count and manage cost.
SMS overview
Learn how SMS/MMS design, content, and delivery works.
Templates
Save time with reusable message templates.
Message personalization and localization
Make your messages more relevant by customizing based on user data and language preferences.
Personalization increases character count and can cause messages to split into multiple segments. Always test before sending to large audiences.
Message Personalization
Use dynamic variables like name or location.
Multi-Language Messaging
Automatically send messages in users’ preferred language.
Dynamic Content
Tailor messages in real-time based on user data.
Compliance and registration requirements
SMS Regulatory Compliance
Understand and follow applicable laws.
SMS Registration Requirements
Ensure your opt-in process meets standards.
Senders
Manage your From phone numbers under Settings > SMS > Senders. Here, you can:
- Update your default sender
- Choose whether the number can receive replies
Consent management, keywords, & auto-responder
Use built-in and custom keywords for managing user consent:
- Double opt-in confirmation
- Opt-out requests (e.g.,
"STOP"
) - Re-subscription (e.g.,
"START"
) - Help inquiries
Auto-responders allow you to send automated replies based on keywords.
SMS consent keyword management
Configure default consent keywords.
SMS keywords
Set up custom auto-response keywords.
Analytics and troubleshooting
Monitor performance and troubleshoot delivery:
SMS message reports
View delivery and engagement metrics.
Analytics overview
Explore multi-channel engagement analytics.
SMS FAQ
Common troubleshooting steps.