Send a message using the SMS channel.
Overview
The Create Notification API allows you to send SMS and MMS messages to your subscribers. If a user does not have an existing SMS subscription, create one using the Create Subscription API.
How to Use this API
To get started with this API, ensure your application is properly configured by following the SMS Setup guide.
Craft your text message
- Draft the message and embed it in the
contents
parameter. - (Optional) Provide the phone number to send the SMS from in the
sms_from
parameter. - Refer to SMS channel parameters for additional parameters.
Choose a targeting strategy
Choose only one strategy for targeting users with this message:
- Segments
- Filters
- Aliases
Schedule delivery
You can specify rate limits and delivery timing as well. See Delivery Notification Parameters to learn more.
Examples
Send to segments
curl --include \
--request POST \
--header "Content-Type: application/json; charset=utf-8" \
--header "Authorization: Basic <YOUR_REST_API_KEY>" \
--data-binary '{
"app_id": "YOUR_APP_ID",
"name": "Identifier for SMS Message",
"sms_from": "YOUR_REGISTERED_PHONE_NUMBER",
"contents": { "en": "Welcome to Cat Facts!", "es": "Bienvenidos a Factos del Gato" },
"sms_media_urls": ["https://cat.com/cat.jpg"],
"included_segments": ["Subscribed Users"]
}' \
https://api.onesignal.com/notifications
Send to dynamically filtered segment
curl --include \
--request POST \
--header "Content-Type: application/json; charset=utf-8" \
--header "Authorization: Basic <YOUR_REST_API_KEY>" \
--data-binary '{
"app_id": "YOUR_APP_ID",
"name": "Identifier for SMS Message",
"sms_from": "YOUR_REGISTERED_PHONE_NUMBER",
"contents": { "en": "Welcome to Cat Facts!", "es": "Bienvenidos a Factos del Gato" },
"sms_media_urls": ["https://cat.com/cat.jpg"],
"filters": [
{"field": "tag", "key": "level", "relation": ">", "value": "10"},
{"operator": "OR"},
{"field": "amount_spent", "relation": ">", "value": "0"}
]
}' \
https://api.onesignal.com/notifications
Send to specific users via External ID
curl --include \
--request POST \
--header "Content-Type: application/json; charset=utf-8" \
--header "Authorization: Basic <YOUR_REST_API_KEY>" \
--data-binary '{
"app_id": "YOUR_APP_ID",
"name": "Identifier for SMS Message",
"sms_from": "YOUR_REGISTERED_PHONE_NUMBER",
"contents": { "en": "Welcome to Cat Facts!", "es": "Bienvenidos a Factos del Gato" },
"sms_media_urls": ["https://cat.com/cat.jpg"],
"include_aliased": {
"external_user_id": ["CUSTOM-EXTERNAL_ID-ASSIGNED-BY-YOU-1", "CUSTOM-EXTERNAL_ID-ASSIGNED-BY-YOU-2", "CUSTOM-EXTERNAL_ID-ASSIGNED-BY-YOU-3"]
},
"target_channel": "sms"
}' \
https://api.onesignal.com/notifications
Send to specific phone numbers
curl --include \
--request POST \
--header "Content-Type: application/json; charset=utf-8" \
--header "Authorization: Basic <YOUR_REST_API_KEY>" \
--data-binary '{
"app_id": "YOUR_APP_ID",
"name": "Identifier for SMS Message",
"sms_from": "YOUR_REGISTERED_PHONE_NUMBER",
"contents": { "en": "Welcome to Cat Facts!", "es": "Bienvenidos a Factos del Gato" },
"sms_media_urls": ["https://cat.com/cat.jpg"],
"include_phone_numbers": ["+1999999999"]
}' \
https://api.onesignal.com/notifications
Body Parameters
sms_from
sms_from
Type string
Description
The phone number used to send the SMS or MMS message. Defaults to the number selected in SMS Setup.
Guidance
The phone number must be specified using the E.164 format.
Example
{
"sms_from": "+15558675309"
}
contents
contents
Type string
Description
The text message's content.
Guidance
Limit each localized message's content to
- 160 characters for GSM-7 Character Encoding
- 70 characters for UCS-2 Character Encoding
Example
{
"contents": {
"en": "Welcome to Cat Facts!",
"es": "Bienvenidos a Factos del Gato"
}
}
sms_media_urls
sms_media_urls
Type string[]
Description
URLs for the media files to be attached to the text message. Your from_number
must support sending MMS messages.
Guidance
You may include 10 media URLs totaling up to 5 Megabytes in size.
Example
{
"sms_media_urls": ["https://cat.com/cat.png", "https://cat.com/cat.gif"]
}
include_phone_numbers
include_phone_numbers
Type string[]
Description
Allows targeting users based on their phone number in E.164 format. The phone number must exist within the OneSignal App before it can be sent an SMS. See Import Phone Numbers for details.
Guidance
You may include up to 2,000 phone numbers in E.164 format per API call.
Example
{
"include_phone_numbers": [
"+19999999999"
]
}