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`

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`

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`

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`

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"
  ]
}