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.

There are two ways to set up texting with OneSignal: a direct integration with Twilio, or OneSignal SMS (which manages the carrier infrastructure on your behalf). Twilio integration is best for customers who can self-serve their sender resource application and sender setup. OneSignal SMS is best for customers who want our compliance team to handle carrier applications, registration, and ongoing support. Setting up texting involves three core concepts: brands, senders, and sender resources. Getting this structure right from the start directly impacts which regions you can send to, how quickly your messages go out, and what type of content you can send.

​
Core concepts

​
Brand

A brand is the shared identity information (company name, website, tax ID, and logo) that identifies the organization behind your messaging during sender resource approval. In OneSignal, a brand maps to a single OneSignal app.

​
Sender

A sender is a sender resource or group of sender resources. Each texting program (promotional, transactional, or OTP) requires a dedicated sender. The most important reason to use a dedicated sender per program is consent management. When each sender maps to a single program, opt-outs stay cleanly scoped. If a recipient unsubscribes from your promotional sender, they stop receiving marketing messages, but they continue to receive order confirmations, shipping updates, or security codes from your other senders. Grouping multiple sender resources into a single sender is useful for:
  • Geo-sending: Route messages through the best sender resource for each recipient’s geography without segmenting your audience by location. For example, a sender with both a US short code and a UK short code automatically delivers from the US number to US recipients and the UK number to UK recipients.
  • Scaling throughput: Combine multiple sender resources to multiply your effective send rate. For example, 10 sender IDs each with 1 message per second (MPS) gives you 10 MPS. Throughput scaling is not permitted in the US and may have restrictions in other regions.
  • Managing fallbacks: Pair RCS and SMS sender resources so that if RCS fails to deliver, SMS is automatically used as a fallback.
Grouping sender resources into a sender does not disrupt the end user’s experience. A user who first receives from one resource in the group continues to receive future messages from that same resource.
You can share a sender across multiple texting programs and use custom keywords to manage opt-outs, but we don’t recommend this. STOP is a protected keyword that automatically opts the user out of the entire sender. If a shared sender is used for both a marketing program and a transactional program, a user texting STOP to a marketing message will no longer receive important account notifications either.

​
Sender resources

A sender resource is the underlying provisioned number or agent required to send messages across a carrier network. Sender resources are confined to a single geography and should be dedicated to a single sender. Each sender resource has a maximum throughput, the number of messages it can send per second. All sender resource types require approval for each combination of geography and use case. For example, a US 10DLC approved for promotional messages and a UK RCS agent approved for transactional messages are two separate sender resources, each requiring its own approval with brand information and sample messages.

​
Sender resource types

TypeBest forApproval timelineThroughputPrice
Alphanumeric sender IDBranded sender name with medium throughput; requires managing consent (opt-out) separatelyFast (only available in certain geos)Moderate (10 MPS default)Included
Toll-freeAll types of messagesDaysLow (3 MPS default, up to 25+)Included
Long codesAll types of messagesWeeksModerate–High (3–225 MPS)Included
Short codeHigh-volume messagesWeeks–MonthsHigh (100+ MPS)Premium
RCSBranded, rich app-like messages, or high-volume messages8–16 weeksHigh (100 MPS)Premium

Sender resource applications

Country-specific availability, approval timelines, reviewers, and additional notes for every sender resource type.

​
Choose your setup path

Navigate to Settings > SMS > Set up SMS in your OneSignal dashboard.
OneSignal manages the carrier infrastructure on your behalf, with a dedicated compliance team that draws on experience from hundreds of sender resource applications. 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. Your account manager can also set up time with our compliance team to begin sender resource applications.
While waiting for verification, you can begin designing SMS & MMS templates and ensuring you meet the sender resource application requirements.

​
Migrating from an existing provider

If you want to move existing texting programs to OneSignal SMS from another provider, you will need to migrate your sender resources and existing SMS automations.
  • From Twilio: No downtime. OneSignal transfers your numbers to the new account. Depending on the number type and registration process, this typically takes around 3 weeks.
  • From another provider: There is some risk of downtime. Depending on number types and account complexity, this typically takes around 4 weeks or more.
Contact your account manager to set up time with our implementation team to begin your migration.

​
FAQ

​
What’s the difference between OneSignal SMS and the Twilio integration?

With the Twilio integration, you manage your own Twilio account, sender resources, and carrier relationships. With OneSignal SMS, OneSignal manages the carrier infrastructure on your behalf, including sender resource applications, compliance guidance, and support. OneSignal SMS is recommended for customers sending more than 5,000 messages per month.

​
Can I use multiple sender resources for the same sender?

Yes. You can group multiple sender resources into a single sender for geo-sending, throughput scaling, or RCS/SMS fallback. A user receiving from one sender resource in a sender continues to receive from that same sender resource in the future.

​
What is throughput and why does it matter?

Throughput is the number of messages a sender resource (or sender) can send per second. If you need to send to a large audience quickly, you may need a sender resource type with higher throughput (for example, a short code) or group multiple sender resources into one sender. Throughput scaling across multiple sender resources is not permitted in the US.

​
How long does sender resource approval take?

Timelines vary by country and sender resource type. Alphanumeric sender IDs in most countries take 1–5 business days. 10DLC in the US takes 1–3 weeks. Short codes and RCS typically take 8–16 weeks. See Sender resource applications for per-country specifics.

Sender resource applications

Per-country approval processes, sender resource types, and governing laws.

SMS opt-in and collection

Collection methods, required disclosure language, and audience validation.

Regulatory compliance

Consent standards, quiet hours, prohibited content, and fraud prevention.

Composing messages

Character limits, MMS, trackable links, and RCS rich content.