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 places to compose a message in OneSignal: Templates and Messages (the Dashboard). Both use the same editor. The difference is that Templates let you save reusable messages you can reference in campaigns, Journeys, or API calls, while Messages is where you compose and send a one-time message directly. When composing from Messages, the workflow is:
  1. Select an audience.
  2. Select the sender for your use case.
  3. Compose your message.
In Templates, you compose the message without selecting an audience or sender — those are chosen at send time, when the template is referenced in a campaign, Journey, or API call. The editor you see depends on the sender you selected. If your sender uses SMS/MMS sender resources, you get the SMS editor. If your sender includes an RCS sender resource, you get the RCS editor. In Templates, if any sender on your account has an RCS sender resource, the editor opens in RCS view by default — the template isn’t locked to RCS, and the actual format is decided by the sender you pick when you send.

​
SMS and MMS

The SMS editor lets you write plain text and optionally attach media.
  • SMS: Text-only. Character limits depend on encoding (see below).
  • MMS: Triggered when you attach an image, GIF, video, or audio file. Key limits:
    • Up to 1,600 characters of text
    • Up to 10 media attachments per message (5MB total across all attachments)
    • Supported formats: JPEG, PNG, GIF, video, and audio
    • Available only in the US, Canada, and Australia
    • Billed at a flat per-message MMS rate (not by segment)

​
Encoding and character limits

SMS messages use one of two encodings, determined automatically by the characters in your message:
EncodingCharacters per segmentUsed for
GSM-7160 (153 for multi-segment)Standard Latin characters and common symbols
UCS-270 (67 for multi-segment)Emojis, accented characters, and non-Latin scripts
When a message exceeds the per-segment limit, it splits into multiple segments, each billed separately. Multi-segment messages reserve a small header per segment for reassembly, which is why the limit is slightly lower for longer messages. The editor shows a live character count and segment estimate as you type. A single emoji can push a one-segment message to three segments, so check the counter before sending.
OneSignal SMS composer showing a GSM-7 encoded message with segment count
OneSignal SMS composer showing a UCS-2 encoded message with segment count
You can add trackable links to your messages to measure click-through rates and attribute conversions back to a specific campaign. When you insert a URL, OneSignal can automatically shorten and wrap it in a tracking link. Clicks are reported in your message analytics.
Use a branded custom domain for any short links in SMS. Do not use free or public shortener domains like bit.ly, tinyurl.com, or goo.gl in production SMS — major US carriers actively filter or block messages containing these domains.

Create links in the Dashboard

Generate carrier-safe, trackable shortened URLs from the dashboard.

Create links via the API

Shorten and track URLs programmatically using the OneSignal API.
OneSignal supports one trackable link per SMS message and does not support personalization in tracked links. If you need to track more than one link or a personalized link, use one of these options: Option 1: UTM parameters Append UTM parameters to your URLs to track each link individually in Google Analytics (GA4). Since the URL is plain text in the message body, Liquid tags work directly inside it. You can personalize the URL with subscriber-specific values like {{ subscription_id }} and OneSignal renders the actual value per recipient at send time. 
https://example.com/sale?utm_source=onesignal&utm_medium=sms&utm_campaign=spring_sale&utm_content=cta
UTM-tagged URLs can be long (150+ characters), which may push your message into additional SMS segments and increase messaging costs. Option 2: Third-party link management tools Third-party tools (Rebrandly, Short.io, Branch.io, AppsFlyer) can track clicks, shorten URLs, and brand the link. For personalized links (unique URL per recipient), look for tools that support parameter passthrough, forwarding query parameters through to the destination URL. With parameter passthrough, you can use Liquid tags directly in the short link (e.g., https://go.yourbrand.com/offer?sub_id={{ subscription_id }}). Option 3: Website-side click tracking Track SMS link clicks by instrumenting your website to send data back to OneSignal when a subscriber lands on your page from an SMS link.
  1. Include a URL in your SMS that identifies the subscriber using Liquid tags (e.g., https://yourbrand.com/offer?uid={{ onesignal_id }}).
  2. When the subscriber clicks the link and lands on your website, fire a call to the OneSignal API to record the engagement:
    • Custom event: Send a custom event (e.g., sms_click) tied to the subscriber. Use as a trigger in Journeys or as a segmentation filter.
    • User tag: Update the subscriber’s profile with a tag (e.g., last_sms_click = <unix_timestamp>). Use to segment by recency of engagement.

​
RCS content

If your sender includes an RCS sender resource, the editor unlocks rich content capabilities:
  • Cards: A standalone rich card with an image, title, description, and up to three actions.
  • Carousels: A horizontally scrollable set of cards. Each card can have its own image, text, and buttons. Useful for showcasing multiple products, locations, or options in a single message.
  • Actions: Tappable buttons attached to cards. Three types are supported:
    • Link buttons: Open any http or https URL. You can set whether it opens in the messaging app or a new tab. This includes iOS Universal Links and Android App Links, which open directly in your app when it is installed.
    • Keyword replies: When a subscriber taps a keyword reply action, it sends that text back as their response without requiring them to type. Simplifies two-way interactions.
    • Phone number: Initiates a phone call directly from the message.

​
RCS image aspect ratios

When adding an image to a rich card, the recommended aspect ratios depend on the card layout:
  • Media on top (vertical card): 2:1, 16:9, or 7:3
  • Media on the left (horizontal card): 3:4
Keep text, logos, and key visual elements away from the edges and centered within the frame. Each device and screen size may crop and center-zoom your image slightly differently.

​
SMS fallback

You can set an SMS fallback message for when RCS fails to deliver — for example, when the recipient’s device or carrier does not support RCS. OneSignal automatically sends the fallback. Note that text-only RCS messages always use the text set by the RCS message and do not use the SMS fallback text.

​
Personalization

Promotional and transactional messages are most effective when they include individualized information, such as discount codes, a user’s name, an appointment time, or an order number.

Message personalization

Use Liquid tags to insert subscriber-specific data into SMS and RCS messages.

​
How content affects billing

The type of content you send directly affects your messaging costs.

​
SMS segments

SMS messages are billed by the number of segments sent, not per message. The per-segment character limit depends on encoding — see Encoding and character limits above for the GSM-7 and UCS-2 math. Example billing:
  • 200-character GSM-7 message = 2 segments
  • 500-character GSM-7 message = 4 segments
  • 100-character message with an emoji = 2 segments (encoding switches to UCS-2)

​
MMS

MMS is billed at a flat per-message rate regardless of text length. See SMS and MMS above for media limits and supported regions.

​
RCS

RCS messages are grouped into four billing categories based on content and length:
Billing categoryAudienceDescription
RichUSText-only messages, or a title with body text. Cannot include actions or media. Messages longer than 160 characters are broken into segments and charged per segment.
Rich MediaUSMessages that include any actions (quick replies, dials, or links), a title with actions, a title with media, standalone media, or carousel content.
BasicInternationalText messages up to 160 UTF-8 characters. Does not include any actions, media, or carousels.
SingleInternationalText messages greater than 160 UTF-8 characters, up to the max message length of 3,072 characters. Can also include actions, media, or carousels.
The billing table uses carrier-invoice vocabulary: quick replies are keyword reply actions, dials are phone number actions, and links are link buttons in the OneSignal editor.

​
FAQ

​
Why did my message become 2 segments when I added an emoji?

Emojis require UCS-2 encoding, which reduces the per-segment character limit from 160 to 70 characters (67 for multi-segment messages). A message that fits in one segment as plain text can easily become 2–3 segments with an emoji added. Monitor the segment count in the editor before sending.

​
Can I use a public URL shortener like bit.ly?

No. Major US carriers actively filter or block messages containing public shortener domains. Use OneSignal’s built-in link shortener, a branded custom domain, or leave the full URL in the message body.

​
Does MMS support all media types?

MMS supports images (JPEG, PNG, GIF), video, and audio. Total media size must be under 5MB across up to 10 media URLs. For a full list of accepted MIME types, see Twilio’s documentation. Note that MMS is only supported in the US, Canada, and Australia.

​
What is the maximum message length for RCS?

RCS supports up to 3,072 characters. Messages over 160 UTF-8 characters fall into the “Single” billing category for international recipients.

​
How do I know if my sender uses the SMS or RCS editor?

The editor is determined by the sender you select when composing a message. If your sender includes an RCS sender resource, you get the RCS editor. If your sender uses SMS/MMS sender resources only, you get the SMS editor. In Templates, RCS is the default format if you have any RCS senders.