Overview

The Create Notification API allows you to send push notifications, emails, and SMS to your users. This guide is specific for SMS. See Push notification or Email to send to those channels.

This API can send SMS and MMS messages to your phone number Subscriptions. If a user does not have an existing Subscription, create one using the Create Subscription API.

How to use this API

To start with this API, ensure your application is properly configured by following the SMS Setup guide.

Craft your SMS or MMS message

1. Draft the message and embed it in the contents parameter.
2. (Optional) Provide the phone number to send the SMS from in the sms_from parameter.
3. 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.

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