curl --request POST \
--url 'https://api.onesignal.com/notifications?c=push' \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"app_id": "YOUR_APP_ID",
"contents": {
"en": "Default message."
},
"include_aliases": {
"external_id": [
"<string>"
]
},
"target_channel": "push",
"include_subscription_ids": [
"<string>"
],
"included_segments": [
"<string>"
],
"excluded_segments": [
"<string>"
],
"filters": [
{
"key": "<string>",
"value": "<string>"
}
],
"headings": {
"en": "<string>"
},
"subtitle": {
"en": "<string>"
},
"name": "<string>",
"template_id": "<string>",
"custom_data": {},
"ios_attachments": {
"id": "<string>"
},
"big_picture": "<string>",
"huawei_big_picture": "<string>",
"adm_big_picture": "<string>",
"chrome_web_image": "<string>",
"small_icon": "<string>",
"huawei_small_icon": "<string>",
"adm_small_icon": "<string>",
"large_icon": "<string>",
"huawei_large_icon": "<string>",
"adm_large_icon": "<string>",
"chrome_web_icon": "<string>",
"firefox_icon": "<string>",
"chrome_web_badge": "<string>",
"android_channel_id": "<string>",
"existing_android_channel_id": "<string>",
"huawei_channel_id": "<string>",
"huawei_existing_channel_id": "<string>",
"huawei_category": "MARKETING",
"huawei_msg_type": "message",
"huawei_bi_tag": "<string>",
"huawei_badge_class": "<string>",
"huawei_badge_set_num": 49,
"huawei_badge_add_num": 50,
"priority": 10,
"ios_interruption_level": "active",
"ios_sound": "<string>",
"ios_badgeType": "None",
"ios_badgeCount": 123,
"android_accent_color": "<string>",
"huawei_accent_color": "<string>",
"url": "<string>",
"app_url": "<string>",
"web_url": "<string>",
"target_content_identifier": "<string>",
"buttons": [
{
"id": "<string>",
"text": "<string>",
"icon": "<string>"
}
],
"web_buttons": [
{
"id": "<string>",
"text": "<string>",
"url": "<string>"
}
],
"thread_id": "<string>",
"ios_relevance_score": 123,
"android_group": "<string>",
"adm_group": "<string>",
"ttl": 259200,
"collapse_id": "<string>",
"web_push_topic": "<string>",
"data": {},
"content_available": true,
"ios_category": "<string>",
"apns_push_type_override": "<string>",
"isIos": true,
"isAndroid": true,
"isHuawei": true,
"isAnyWeb": true,
"isChromeWeb": true,
"isFirefox": true,
"isSafari": true,
"isWP_WNS": true,
"isAdm": true,
"send_after": "<string>",
"delayed_option": "<string>",
"delivery_time_of_day": "<string>",
"throttle_rate_per_minute": 123,
"enable_frequency_cap": true,
"idempotency_key": "<string>"
}
'import Onesignal from '@onesignal/node-onesignal';
import { randomUUID } from 'node:crypto';
const configuration = Onesignal.createConfiguration({
restApiKey: 'YOUR_REST_API_KEY',
});
const apiInstance = new Onesignal.DefaultApi(configuration);
const notification = new Onesignal.Notification();
notification.app_id = 'YOUR_APP_ID';
notification.contents = { en: 'Hello from OneSignal!' };
notification.headings = { en: 'Push Notification' };
// Target by External ID: alias keys must match the API (external_id, not externalId).
notification.include_aliases = { external_id: ['YOUR_USER_EXTERNAL_ID'] };
notification.target_channel = 'push';
// Idempotency key: a client-generated UUID that lets you safely retry on network failure.
// If two requests arrive with the same key inside the 30-day window, only the first is sent
// and the second returns the original response. `randomUUID` is imported from `node:crypto`
// (available on Node 14.17+) — DO NOT reuse keys across logically distinct sends.
notification.idempotency_key = randomUUID();
try {
const response = await apiInstance.createNotification(notification);
// `response.id` discriminates the two HTTP 200 shapes. A falsy value (empty string,
// null, or undefined) means no notification was created (e.g. all targets were
// unreachable / not subscribed). `response.errors` is polymorphic: a `string[]` in the
// no-subscribers case, or an object keyed by recipient-identifier type
// (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, …) when the
// notification WAS created but some recipients were skipped.
if (!response.id) {
console.warn("Notification was not sent:", response.errors);
} else if (response.errors) {
console.log("Notification created:", response.id, "(partial failures:", response.errors, ")");
} else {
console.log("Notification created:", response.id);
}
} catch (e) {
if (e instanceof Onesignal.ApiException) {
// `e.errorMessages` flattens any error-envelope shape to a `string[]`;
// the raw parsed body remains on `e.body`.
console.error("createNotification failed: HTTP " + e.code, e.errorMessages);
} else {
throw e;
}
}import uuid
import onesignal
from onesignal.api import default_api
from onesignal.model.language_string_map import LanguageStringMap
from onesignal.model.notification import Notification
# See configuration.py for a list of all supported configuration parameters.
# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.
# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.
configuration = onesignal.Configuration(
rest_api_key = "YOUR_REST_API_KEY", # App REST API key required for most endpoints
organization_api_key = "YOUR_ORGANIZATION_API_KEY" # Organization key is only required for creating new apps and other top-level endpoints
)
with onesignal.ApiClient(configuration) as api_client:
api_instance = default_api.DefaultApi(api_client)
notification = Notification(
app_id='YOUR_APP_ID',
contents=LanguageStringMap(en='Hello from OneSignal!'),
headings=LanguageStringMap(en='Push Notification'),
include_aliases={'external_id': ['YOUR_USER_EXTERNAL_ID']},
target_channel='push',
# Idempotency key: a client-generated UUID that lets you safely retry on network
# failure. If two requests arrive with the same key inside the 30-day window, only
# the first is sent and the second returns the original response. Use uuid.uuid4()
# or a similar source of randomness — DO NOT reuse keys across logically distinct
# sends.
idempotency_key=str(uuid.uuid4()),
)
try:
api_response = api_instance.create_notification(notification)
# `api_response.id` discriminates the two HTTP 200 shapes. A falsy value means no
# notification was created (e.g. all targets were unreachable / not subscribed).
# `api_response.errors` is polymorphic: a `list[str]` in the no-subscribers case, or
# a dict keyed by recipient-identifier type (`invalid_player_ids`,
# `invalid_external_user_ids`, `invalid_aliases`, ...) when the notification WAS
# created but some recipients were skipped. Access via `.get('errors')` rather than
# attribute access — the legacy Python generator's `ModelNormal.__getattr__` raises
# `ApiAttributeError` for optional fields that the server omitted, so plain
# `api_response.errors` would crash on the pure-success path.
response_id = api_response.get('id')
response_errors = api_response.get('errors')
if not response_id:
print('Notification was not sent:', response_errors)
elif response_errors:
print('Notification created:', response_id, '(partial failures:', response_errors, ')')
else:
print('Notification created:', response_id)
except onesignal.ApiException as e:
print('Exception when calling DefaultApi->create_notification: %s\n' % e)
print('Status Code: %s' % e.status)
# `e.error_messages` flattens any error-envelope shape to a list[str];
# the raw body remains on `e.body`.
print('Error Messages: %s' % e.error_messages)
print('Response Body: %s' % e.body)<?php
require_once(__DIR__ . '/vendor/autoload.php');
// Configure Bearer authorization: rest_api_key
$config = onesignal\client\Configuration::getDefaultConfiguration()
->setRestApiKeyToken('YOUR_REST_API_KEY')
->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');
$apiInstance = new onesignal\client\Api\DefaultApi(
new GuzzleHttp\Client(),
$config
);
$notification = new onesignal\client\Model\Notification();
$notification->setAppId('YOUR_APP_ID');
$contents = new onesignal\client\Model\LanguageStringMap();
$contents->setEn('Hello from OneSignal!');
$notification->setContents($contents);
$headings = new onesignal\client\Model\LanguageStringMap();
$headings->setEn('Push Notification');
$notification->setHeadings($headings);
$notification->setIncludeAliases(['external_id' => ['YOUR_USER_EXTERNAL_ID']]);
$notification->setTargetChannel('push');
// Idempotency key: a client-generated UUID that lets you safely retry on network failure.
// If two requests arrive with the same key inside the 30-day window, only the first is sent
// and the second returns the original response. Use a strong source of randomness — DO NOT
// reuse keys across logically distinct sends. We use PHP 7+'s built-in random_bytes() here
// so the snippet works against this SDK's declared composer.json deps (Guzzle + PSR-7) with
// no extra install; projects that already pull in ramsey/uuid can swap in
// `\Ramsey\Uuid\Uuid::uuid4()->toString()` instead.
$idempotencyKeyBytes = random_bytes(16);
$idempotencyKeyBytes[6] = chr(ord($idempotencyKeyBytes[6]) & 0x0f | 0x40);
$idempotencyKeyBytes[8] = chr(ord($idempotencyKeyBytes[8]) & 0x3f | 0x80);
$idempotencyKey = vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($idempotencyKeyBytes), 4));
$notification->setIdempotencyKey($idempotencyKey);
try {
$result = $apiInstance->createNotification($notification);
// `$result->getId()` discriminates the two HTTP 200 shapes. A falsy value (empty
// string or null) means no notification was created (e.g. all targets were
// unreachable / not subscribed). `$result->getErrors()` is polymorphic: a `string[]`
// in the no-subscribers case, or an object keyed by recipient-identifier type
// (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...) when
// the notification WAS created but some recipients were skipped.
if (!$result->getId()) {
echo 'Notification was not sent: ', print_r($result->getErrors(), true), PHP_EOL;
} elseif ($result->getErrors()) {
echo 'Notification created: ', $result->getId(), ' (partial failures: ', print_r($result->getErrors(), true), ')', PHP_EOL;
} else {
echo 'Notification created: ', $result->getId(), PHP_EOL;
}
} catch (\onesignal\client\ApiException $e) {
echo 'Exception when calling DefaultApi->createNotification: ', $e->getMessage(), PHP_EOL;
echo 'Status Code: ', $e->getCode(), PHP_EOL;
echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;
} catch (\Exception $e) {
echo 'Exception when calling DefaultApi->createNotification: ', $e->getMessage(), PHP_EOL;
}package main
import (
"context"
"fmt"
"os"
"github.com/google/uuid"
"github.com/OneSignal/onesignal-go-api/v5"
)
func main() {
configuration := onesignal.NewConfiguration()
apiClient := onesignal.NewAPIClient(configuration)
restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, "YOUR_REST_API_KEY")
notification := onesignal.NewNotification("YOUR_APP_ID")
contents := onesignal.NewLanguageStringMap()
contents.SetEn("Hello from OneSignal!")
notification.SetContents(*contents)
headings := onesignal.NewLanguageStringMap()
headings.SetEn("Push Notification")
notification.SetHeadings(*headings)
notification.SetIncludeAliases(map[string][]string{"external_id": {"YOUR_USER_EXTERNAL_ID"}})
notification.SetTargetChannel("push")
// Idempotency key: a client-generated UUID that lets you safely retry on network failure.
// If two requests arrive with the same key inside the 30-day window, only the first is
// sent and the second returns the original response. The `github.com/google/uuid` module
// is not a declared dep of this SDK; run `go get github.com/google/uuid` (or `go mod tidy`
// after importing it) before building. DO NOT reuse keys across logically distinct sends.
notification.SetIdempotencyKey(uuid.NewString())
resp, r, err := apiClient.DefaultApi.CreateNotification(restAuth).Notification(*notification).Execute()
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `DefaultApi.CreateNotification``: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {
fmt.Fprintf(os.Stderr, "Response Body: %s\n", apiErr.Body())
}
return
}
// `resp.GetId()` discriminates the two HTTP 200 shapes. An empty string means no
// notification was created (e.g. all targets were unreachable / not subscribed).
// `resp.GetErrors()` is `interface{}` because the field is polymorphic: a `[]string` in
// the no-subscribers case, or a map keyed by recipient-identifier type
// (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...) when
// the notification WAS created but some recipients were skipped.
if resp.GetId() == "" {
fmt.Fprintf(os.Stderr, "Notification was not sent: %v\n", resp.GetErrors())
} else if errors := resp.GetErrors(); errors != nil {
fmt.Fprintf(os.Stdout, "Notification created: %s (partial failures: %v)\n", resp.GetId(), errors)
} else {
fmt.Fprintf(os.Stdout, "Notification created: %s\n", resp.GetId())
}
}require 'onesignal'
# setup authorization
OneSignal.configure do |config|
# Configure Bearer authorization: rest_api_key
config.rest_api_key = 'YOUR_REST_API_KEY'
end
api_instance = OneSignal::DefaultApi.new
require 'securerandom'
notification = OneSignal::Notification.new
notification.app_id = 'YOUR_APP_ID'
notification.contents = OneSignal::LanguageStringMap.new({ en: 'Hello from OneSignal!' })
notification.headings = OneSignal::LanguageStringMap.new({ en: 'Push Notification' })
notification.include_aliases = { 'external_id' => ['YOUR_USER_EXTERNAL_ID'] }
notification.target_channel = 'push'
# Idempotency key: a client-generated UUID that lets you safely retry on network failure.
# If two requests arrive with the same key inside the 30-day window, only the first is sent
# and the second returns the original response. Use SecureRandom.uuid — DO NOT reuse keys
# across logically distinct sends.
notification.idempotency_key = SecureRandom.uuid
begin
# Create notification
result = api_instance.create_notification(notification)
# `result.id` discriminates the two HTTP 200 shapes. An empty string means no
# notification was created (e.g. all targets were unreachable / not subscribed).
# `result.errors` is polymorphic: an `Array<String>` in the no-subscribers case, or
# a Hash keyed by recipient-identifier type (`invalid_player_ids`,
# `invalid_external_user_ids`, `invalid_aliases`, ...) when the notification WAS
# created but some recipients were skipped.
if result.id.to_s.empty?
puts "Notification was not sent: #{result.errors}"
elsif result.errors
puts "Notification created: #{result.id} (partial failures: #{result.errors})"
else
puts "Notification created: #{result.id}"
end
rescue OneSignal::ApiError => e
puts "Error when calling DefaultApi->create_notification: #{e}"
puts "Status Code: #{e.code}"
# `e.error_messages` flattens any error-envelope shape to an Array<String>;
# the raw body remains on `e.response_body`.
puts "Error Messages: #{e.error_messages}"
puts "Response Body: #{e.response_body}"
end// Import classes:
import java.util.Arrays;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.UUID;
import com.onesignal.client.ApiClient;
import com.onesignal.client.ApiException;
import com.onesignal.client.Configuration;
import com.onesignal.client.auth.*;
import com.onesignal.client.model.*;
import com.onesignal.client.api.DefaultApi;
public class Example {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://api.onesignal.com");
HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication("rest_api_key");
rest_api_key.setBearerToken("YOUR_REST_API_KEY");
DefaultApi apiInstance = new DefaultApi(defaultClient);
Notification notification = new Notification();
notification.setAppId("YOUR_APP_ID");
LanguageStringMap contents = new LanguageStringMap();
contents.setEn("Hello from OneSignal!");
notification.setContents(contents);
LanguageStringMap headings = new LanguageStringMap();
headings.setEn("Push Notification");
notification.setHeadings(headings);
Map<String, List<String>> aliases = new HashMap<>();
aliases.put("external_id", Arrays.asList("YOUR_USER_EXTERNAL_ID"));
notification.setIncludeAliases(aliases);
notification.setTargetChannel(Notification.TargetChannelEnum.PUSH);
// Idempotency key: a client-generated UUID that lets you safely retry on network failure.
// If two requests arrive with the same key inside the 30-day window, only the first is
// sent and the second returns the original response. Use UUID.randomUUID() — DO NOT
// reuse keys across logically distinct sends.
notification.setIdempotencyKey(UUID.randomUUID().toString());
try {
CreateNotificationSuccessResponse result = apiInstance.createNotification(notification);
// `result.getId()` discriminates the two HTTP 200 shapes. An empty string means no
// notification was created (e.g. all targets were unreachable / not subscribed).
// `result.getErrors()` is polymorphic (declared as `Object`): a `List<String>` in the
// no-subscribers case, or a Map keyed by recipient-identifier type
// (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...) when
// the notification WAS created but some recipients were skipped.
if (result.getId() == null || result.getId().isEmpty()) {
System.out.println("Notification was not sent: " + result.getErrors());
} else if (result.getErrors() != null) {
System.out.println("Notification created: " + result.getId() + " (partial failures: " + result.getErrors() + ")");
} else {
System.out.println("Notification created: " + result.getId());
}
} catch (ApiException e) {
System.err.println("Exception when calling DefaultApi#createNotification");
System.err.println("Status code: " + e.getCode());
System.err.println("Reason: " + e.getResponseBody());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}using System;
using System.Collections.Generic;
using System.Diagnostics;
using OneSignalApi.Api;
using OneSignalApi.Client;
using OneSignalApi.Model;
namespace Example
{
public class CreateNotificationExample
{
public static void Main()
{
Configuration config = new Configuration();
config.BasePath = "https://api.onesignal.com";
config.AccessToken = "YOUR_REST_API_KEY";
var apiInstance = new DefaultApi(config);
var notification = new Notification
{
AppId = "YOUR_APP_ID",
Contents = new LanguageStringMap(en: "Hello from OneSignal!"),
Headings = new LanguageStringMap(en: "Push Notification"),
IncludeAliases = new Dictionary<string, List<string>>
{
{ "external_id", new List<string> { "YOUR_USER_EXTERNAL_ID" } }
},
TargetChannel = Notification.TargetChannelEnum.Push,
// Idempotency key: a client-generated UUID that lets you safely retry on
// network failure. If two requests arrive with the same key inside the
// 30-day window, only the first is sent and the second returns the original
// response. Use Guid.NewGuid() — DO NOT reuse keys across logically distinct
// sends.
IdempotencyKey = Guid.NewGuid().ToString()
};
try
{
CreateNotificationSuccessResponse result = apiInstance.CreateNotification(notification);
// `result.Id` discriminates the two HTTP 200 shapes. An empty string means
// no notification was created (e.g. all targets were unreachable / not
// subscribed). `result.Errors` is polymorphic: a `List<string>` in the
// no-subscribers case, or an object keyed by recipient-identifier type
// (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...)
// when the notification WAS created but some recipients were skipped.
if (string.IsNullOrEmpty(result.Id))
{
Debug.WriteLine("Notification was not sent: " + result.Errors);
}
else if (result.Errors != null)
{
Debug.WriteLine("Notification created: " + result.Id + " (partial failures: " + result.Errors + ")");
}
else
{
Debug.WriteLine("Notification created: " + result.Id);
}
}
catch (ApiException e)
{
Debug.Print("Exception when calling DefaultApi.CreateNotification: " + e.Message);
Debug.Print("Status Code: " + e.ErrorCode);
Debug.Print("Response Body: " + e.ErrorContent);
Debug.Print(e.StackTrace);
}
}
}
}use onesignal_rust_api::apis::configuration::Configuration;
use onesignal_rust_api::apis::default_api;
use onesignal_rust_api::models::notification::TargetChannelType;
use onesignal_rust_api::models::{LanguageStringMap, Notification};
use uuid::Uuid;
#[tokio::main]
async fn main() {
let mut configuration = Configuration::new();
configuration.rest_api_key_token = Some("YOUR_REST_API_KEY".to_string());
let mut notification = Notification::new("YOUR_APP_ID".to_string());
notification.contents = Some(Box::new(LanguageStringMap {
en: Some("Hello from OneSignal!".to_string()),
..Default::default()
}));
notification.headings = Some(Box::new(LanguageStringMap {
en: Some("Push Notification".to_string()),
..Default::default()
}));
let mut aliases = std::collections::HashMap::new();
aliases.insert(
"external_id".to_string(),
vec!["YOUR_USER_EXTERNAL_ID".to_string()],
);
notification.include_aliases = Some(aliases);
notification.target_channel = Some(TargetChannelType::Push);
// Idempotency key: a client-generated UUID that lets you safely retry on network failure.
// If two requests arrive with the same key inside the 30-day window, only the first is
// sent and the second returns the original response. The `uuid` crate must be declared
// in your own Cargo.toml (Cargo doesn't expose transitive crates by name to downstream
// code) — add `uuid = { version = "1", features = ["v4"] }` to your `[dependencies]`.
// DO NOT reuse keys across logically distinct sends.
notification.idempotency_key = Some(Uuid::new_v4().to_string());
match default_api::create_notification(&configuration, notification).await {
Ok(resp) => {
// `resp.id` discriminates the two HTTP 200 shapes. An empty string or `None`
// means no notification was created (e.g. all targets were unreachable / not
// subscribed). `resp.errors` is polymorphic (typed as `Option<serde_json::Value>`):
// a `Vec<String>` in the no-subscribers case, or an object keyed by
// recipient-identifier type (`invalid_player_ids`, `invalid_external_user_ids`,
// `invalid_aliases`, ...) when the notification WAS created but some recipients
// were skipped.
match resp.id.as_deref() {
Some("") | None => eprintln!("Notification was not sent: {:?}", resp.errors),
Some(id) if resp.errors.is_some() => {
println!("Notification created: {} (partial failures: {:?})", id, resp.errors)
}
Some(id) => println!("Notification created: {}", id),
}
}
Err(onesignal_rust_api::apis::Error::ResponseError(content)) => {
eprintln!("create_notification failed: HTTP {}", content.status);
eprintln!("Response Body: {}", content.content);
}
Err(e) => eprintln!("create_notification failed: {:?}", e),
}
}{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"external_id": "<string>",
"errors": {
"invalid_aliases": {
"external_id": [
"[\"user_id_1\", \"user_id_1\", \"user_id_2\"]"
],
"onesignal_id": [
"[\"1589641e-bed1-4325-bce4-d2234e578884\", \"1589641e-bed1-4325-bce4-d2234e578884\", \"1589641e-bed1-4325-bce4-d2234e578884\"]"
]
},
"invalid_player_ids": [
"<string>"
]
},
"warnings": {
"invalid_external_user_ids": "<string>"
}
}{
"errors": [
{
"Message Notifications must have English language content": "<string>",
"Incorrect subscription_id format in include_subscription_ids (not a valid UUID):": "<string>",
"Platforms You may only send to one delivery channel at a time. Make sure you are only including one of push platforms, Email, or SMS.": "<string>"
}
]
}{
"errors": [
"This API is not available for applications on your plan."
]
}{
"errors": [
"API rate limit exceeded"
]
}{
"errors": [
"Service temporarily unavailable"
]
}Push notification
Send a message using the push notification channel.
curl --request POST \
--url 'https://api.onesignal.com/notifications?c=push' \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"app_id": "YOUR_APP_ID",
"contents": {
"en": "Default message."
},
"include_aliases": {
"external_id": [
"<string>"
]
},
"target_channel": "push",
"include_subscription_ids": [
"<string>"
],
"included_segments": [
"<string>"
],
"excluded_segments": [
"<string>"
],
"filters": [
{
"key": "<string>",
"value": "<string>"
}
],
"headings": {
"en": "<string>"
},
"subtitle": {
"en": "<string>"
},
"name": "<string>",
"template_id": "<string>",
"custom_data": {},
"ios_attachments": {
"id": "<string>"
},
"big_picture": "<string>",
"huawei_big_picture": "<string>",
"adm_big_picture": "<string>",
"chrome_web_image": "<string>",
"small_icon": "<string>",
"huawei_small_icon": "<string>",
"adm_small_icon": "<string>",
"large_icon": "<string>",
"huawei_large_icon": "<string>",
"adm_large_icon": "<string>",
"chrome_web_icon": "<string>",
"firefox_icon": "<string>",
"chrome_web_badge": "<string>",
"android_channel_id": "<string>",
"existing_android_channel_id": "<string>",
"huawei_channel_id": "<string>",
"huawei_existing_channel_id": "<string>",
"huawei_category": "MARKETING",
"huawei_msg_type": "message",
"huawei_bi_tag": "<string>",
"huawei_badge_class": "<string>",
"huawei_badge_set_num": 49,
"huawei_badge_add_num": 50,
"priority": 10,
"ios_interruption_level": "active",
"ios_sound": "<string>",
"ios_badgeType": "None",
"ios_badgeCount": 123,
"android_accent_color": "<string>",
"huawei_accent_color": "<string>",
"url": "<string>",
"app_url": "<string>",
"web_url": "<string>",
"target_content_identifier": "<string>",
"buttons": [
{
"id": "<string>",
"text": "<string>",
"icon": "<string>"
}
],
"web_buttons": [
{
"id": "<string>",
"text": "<string>",
"url": "<string>"
}
],
"thread_id": "<string>",
"ios_relevance_score": 123,
"android_group": "<string>",
"adm_group": "<string>",
"ttl": 259200,
"collapse_id": "<string>",
"web_push_topic": "<string>",
"data": {},
"content_available": true,
"ios_category": "<string>",
"apns_push_type_override": "<string>",
"isIos": true,
"isAndroid": true,
"isHuawei": true,
"isAnyWeb": true,
"isChromeWeb": true,
"isFirefox": true,
"isSafari": true,
"isWP_WNS": true,
"isAdm": true,
"send_after": "<string>",
"delayed_option": "<string>",
"delivery_time_of_day": "<string>",
"throttle_rate_per_minute": 123,
"enable_frequency_cap": true,
"idempotency_key": "<string>"
}
'import Onesignal from '@onesignal/node-onesignal';
import { randomUUID } from 'node:crypto';
const configuration = Onesignal.createConfiguration({
restApiKey: 'YOUR_REST_API_KEY',
});
const apiInstance = new Onesignal.DefaultApi(configuration);
const notification = new Onesignal.Notification();
notification.app_id = 'YOUR_APP_ID';
notification.contents = { en: 'Hello from OneSignal!' };
notification.headings = { en: 'Push Notification' };
// Target by External ID: alias keys must match the API (external_id, not externalId).
notification.include_aliases = { external_id: ['YOUR_USER_EXTERNAL_ID'] };
notification.target_channel = 'push';
// Idempotency key: a client-generated UUID that lets you safely retry on network failure.
// If two requests arrive with the same key inside the 30-day window, only the first is sent
// and the second returns the original response. `randomUUID` is imported from `node:crypto`
// (available on Node 14.17+) — DO NOT reuse keys across logically distinct sends.
notification.idempotency_key = randomUUID();
try {
const response = await apiInstance.createNotification(notification);
// `response.id` discriminates the two HTTP 200 shapes. A falsy value (empty string,
// null, or undefined) means no notification was created (e.g. all targets were
// unreachable / not subscribed). `response.errors` is polymorphic: a `string[]` in the
// no-subscribers case, or an object keyed by recipient-identifier type
// (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, …) when the
// notification WAS created but some recipients were skipped.
if (!response.id) {
console.warn("Notification was not sent:", response.errors);
} else if (response.errors) {
console.log("Notification created:", response.id, "(partial failures:", response.errors, ")");
} else {
console.log("Notification created:", response.id);
}
} catch (e) {
if (e instanceof Onesignal.ApiException) {
// `e.errorMessages` flattens any error-envelope shape to a `string[]`;
// the raw parsed body remains on `e.body`.
console.error("createNotification failed: HTTP " + e.code, e.errorMessages);
} else {
throw e;
}
}import uuid
import onesignal
from onesignal.api import default_api
from onesignal.model.language_string_map import LanguageStringMap
from onesignal.model.notification import Notification
# See configuration.py for a list of all supported configuration parameters.
# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.
# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.
configuration = onesignal.Configuration(
rest_api_key = "YOUR_REST_API_KEY", # App REST API key required for most endpoints
organization_api_key = "YOUR_ORGANIZATION_API_KEY" # Organization key is only required for creating new apps and other top-level endpoints
)
with onesignal.ApiClient(configuration) as api_client:
api_instance = default_api.DefaultApi(api_client)
notification = Notification(
app_id='YOUR_APP_ID',
contents=LanguageStringMap(en='Hello from OneSignal!'),
headings=LanguageStringMap(en='Push Notification'),
include_aliases={'external_id': ['YOUR_USER_EXTERNAL_ID']},
target_channel='push',
# Idempotency key: a client-generated UUID that lets you safely retry on network
# failure. If two requests arrive with the same key inside the 30-day window, only
# the first is sent and the second returns the original response. Use uuid.uuid4()
# or a similar source of randomness — DO NOT reuse keys across logically distinct
# sends.
idempotency_key=str(uuid.uuid4()),
)
try:
api_response = api_instance.create_notification(notification)
# `api_response.id` discriminates the two HTTP 200 shapes. A falsy value means no
# notification was created (e.g. all targets were unreachable / not subscribed).
# `api_response.errors` is polymorphic: a `list[str]` in the no-subscribers case, or
# a dict keyed by recipient-identifier type (`invalid_player_ids`,
# `invalid_external_user_ids`, `invalid_aliases`, ...) when the notification WAS
# created but some recipients were skipped. Access via `.get('errors')` rather than
# attribute access — the legacy Python generator's `ModelNormal.__getattr__` raises
# `ApiAttributeError` for optional fields that the server omitted, so plain
# `api_response.errors` would crash on the pure-success path.
response_id = api_response.get('id')
response_errors = api_response.get('errors')
if not response_id:
print('Notification was not sent:', response_errors)
elif response_errors:
print('Notification created:', response_id, '(partial failures:', response_errors, ')')
else:
print('Notification created:', response_id)
except onesignal.ApiException as e:
print('Exception when calling DefaultApi->create_notification: %s\n' % e)
print('Status Code: %s' % e.status)
# `e.error_messages` flattens any error-envelope shape to a list[str];
# the raw body remains on `e.body`.
print('Error Messages: %s' % e.error_messages)
print('Response Body: %s' % e.body)<?php
require_once(__DIR__ . '/vendor/autoload.php');
// Configure Bearer authorization: rest_api_key
$config = onesignal\client\Configuration::getDefaultConfiguration()
->setRestApiKeyToken('YOUR_REST_API_KEY')
->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');
$apiInstance = new onesignal\client\Api\DefaultApi(
new GuzzleHttp\Client(),
$config
);
$notification = new onesignal\client\Model\Notification();
$notification->setAppId('YOUR_APP_ID');
$contents = new onesignal\client\Model\LanguageStringMap();
$contents->setEn('Hello from OneSignal!');
$notification->setContents($contents);
$headings = new onesignal\client\Model\LanguageStringMap();
$headings->setEn('Push Notification');
$notification->setHeadings($headings);
$notification->setIncludeAliases(['external_id' => ['YOUR_USER_EXTERNAL_ID']]);
$notification->setTargetChannel('push');
// Idempotency key: a client-generated UUID that lets you safely retry on network failure.
// If two requests arrive with the same key inside the 30-day window, only the first is sent
// and the second returns the original response. Use a strong source of randomness — DO NOT
// reuse keys across logically distinct sends. We use PHP 7+'s built-in random_bytes() here
// so the snippet works against this SDK's declared composer.json deps (Guzzle + PSR-7) with
// no extra install; projects that already pull in ramsey/uuid can swap in
// `\Ramsey\Uuid\Uuid::uuid4()->toString()` instead.
$idempotencyKeyBytes = random_bytes(16);
$idempotencyKeyBytes[6] = chr(ord($idempotencyKeyBytes[6]) & 0x0f | 0x40);
$idempotencyKeyBytes[8] = chr(ord($idempotencyKeyBytes[8]) & 0x3f | 0x80);
$idempotencyKey = vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($idempotencyKeyBytes), 4));
$notification->setIdempotencyKey($idempotencyKey);
try {
$result = $apiInstance->createNotification($notification);
// `$result->getId()` discriminates the two HTTP 200 shapes. A falsy value (empty
// string or null) means no notification was created (e.g. all targets were
// unreachable / not subscribed). `$result->getErrors()` is polymorphic: a `string[]`
// in the no-subscribers case, or an object keyed by recipient-identifier type
// (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...) when
// the notification WAS created but some recipients were skipped.
if (!$result->getId()) {
echo 'Notification was not sent: ', print_r($result->getErrors(), true), PHP_EOL;
} elseif ($result->getErrors()) {
echo 'Notification created: ', $result->getId(), ' (partial failures: ', print_r($result->getErrors(), true), ')', PHP_EOL;
} else {
echo 'Notification created: ', $result->getId(), PHP_EOL;
}
} catch (\onesignal\client\ApiException $e) {
echo 'Exception when calling DefaultApi->createNotification: ', $e->getMessage(), PHP_EOL;
echo 'Status Code: ', $e->getCode(), PHP_EOL;
echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;
} catch (\Exception $e) {
echo 'Exception when calling DefaultApi->createNotification: ', $e->getMessage(), PHP_EOL;
}package main
import (
"context"
"fmt"
"os"
"github.com/google/uuid"
"github.com/OneSignal/onesignal-go-api/v5"
)
func main() {
configuration := onesignal.NewConfiguration()
apiClient := onesignal.NewAPIClient(configuration)
restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, "YOUR_REST_API_KEY")
notification := onesignal.NewNotification("YOUR_APP_ID")
contents := onesignal.NewLanguageStringMap()
contents.SetEn("Hello from OneSignal!")
notification.SetContents(*contents)
headings := onesignal.NewLanguageStringMap()
headings.SetEn("Push Notification")
notification.SetHeadings(*headings)
notification.SetIncludeAliases(map[string][]string{"external_id": {"YOUR_USER_EXTERNAL_ID"}})
notification.SetTargetChannel("push")
// Idempotency key: a client-generated UUID that lets you safely retry on network failure.
// If two requests arrive with the same key inside the 30-day window, only the first is
// sent and the second returns the original response. The `github.com/google/uuid` module
// is not a declared dep of this SDK; run `go get github.com/google/uuid` (or `go mod tidy`
// after importing it) before building. DO NOT reuse keys across logically distinct sends.
notification.SetIdempotencyKey(uuid.NewString())
resp, r, err := apiClient.DefaultApi.CreateNotification(restAuth).Notification(*notification).Execute()
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `DefaultApi.CreateNotification``: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {
fmt.Fprintf(os.Stderr, "Response Body: %s\n", apiErr.Body())
}
return
}
// `resp.GetId()` discriminates the two HTTP 200 shapes. An empty string means no
// notification was created (e.g. all targets were unreachable / not subscribed).
// `resp.GetErrors()` is `interface{}` because the field is polymorphic: a `[]string` in
// the no-subscribers case, or a map keyed by recipient-identifier type
// (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...) when
// the notification WAS created but some recipients were skipped.
if resp.GetId() == "" {
fmt.Fprintf(os.Stderr, "Notification was not sent: %v\n", resp.GetErrors())
} else if errors := resp.GetErrors(); errors != nil {
fmt.Fprintf(os.Stdout, "Notification created: %s (partial failures: %v)\n", resp.GetId(), errors)
} else {
fmt.Fprintf(os.Stdout, "Notification created: %s\n", resp.GetId())
}
}require 'onesignal'
# setup authorization
OneSignal.configure do |config|
# Configure Bearer authorization: rest_api_key
config.rest_api_key = 'YOUR_REST_API_KEY'
end
api_instance = OneSignal::DefaultApi.new
require 'securerandom'
notification = OneSignal::Notification.new
notification.app_id = 'YOUR_APP_ID'
notification.contents = OneSignal::LanguageStringMap.new({ en: 'Hello from OneSignal!' })
notification.headings = OneSignal::LanguageStringMap.new({ en: 'Push Notification' })
notification.include_aliases = { 'external_id' => ['YOUR_USER_EXTERNAL_ID'] }
notification.target_channel = 'push'
# Idempotency key: a client-generated UUID that lets you safely retry on network failure.
# If two requests arrive with the same key inside the 30-day window, only the first is sent
# and the second returns the original response. Use SecureRandom.uuid — DO NOT reuse keys
# across logically distinct sends.
notification.idempotency_key = SecureRandom.uuid
begin
# Create notification
result = api_instance.create_notification(notification)
# `result.id` discriminates the two HTTP 200 shapes. An empty string means no
# notification was created (e.g. all targets were unreachable / not subscribed).
# `result.errors` is polymorphic: an `Array<String>` in the no-subscribers case, or
# a Hash keyed by recipient-identifier type (`invalid_player_ids`,
# `invalid_external_user_ids`, `invalid_aliases`, ...) when the notification WAS
# created but some recipients were skipped.
if result.id.to_s.empty?
puts "Notification was not sent: #{result.errors}"
elsif result.errors
puts "Notification created: #{result.id} (partial failures: #{result.errors})"
else
puts "Notification created: #{result.id}"
end
rescue OneSignal::ApiError => e
puts "Error when calling DefaultApi->create_notification: #{e}"
puts "Status Code: #{e.code}"
# `e.error_messages` flattens any error-envelope shape to an Array<String>;
# the raw body remains on `e.response_body`.
puts "Error Messages: #{e.error_messages}"
puts "Response Body: #{e.response_body}"
end// Import classes:
import java.util.Arrays;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.UUID;
import com.onesignal.client.ApiClient;
import com.onesignal.client.ApiException;
import com.onesignal.client.Configuration;
import com.onesignal.client.auth.*;
import com.onesignal.client.model.*;
import com.onesignal.client.api.DefaultApi;
public class Example {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://api.onesignal.com");
HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication("rest_api_key");
rest_api_key.setBearerToken("YOUR_REST_API_KEY");
DefaultApi apiInstance = new DefaultApi(defaultClient);
Notification notification = new Notification();
notification.setAppId("YOUR_APP_ID");
LanguageStringMap contents = new LanguageStringMap();
contents.setEn("Hello from OneSignal!");
notification.setContents(contents);
LanguageStringMap headings = new LanguageStringMap();
headings.setEn("Push Notification");
notification.setHeadings(headings);
Map<String, List<String>> aliases = new HashMap<>();
aliases.put("external_id", Arrays.asList("YOUR_USER_EXTERNAL_ID"));
notification.setIncludeAliases(aliases);
notification.setTargetChannel(Notification.TargetChannelEnum.PUSH);
// Idempotency key: a client-generated UUID that lets you safely retry on network failure.
// If two requests arrive with the same key inside the 30-day window, only the first is
// sent and the second returns the original response. Use UUID.randomUUID() — DO NOT
// reuse keys across logically distinct sends.
notification.setIdempotencyKey(UUID.randomUUID().toString());
try {
CreateNotificationSuccessResponse result = apiInstance.createNotification(notification);
// `result.getId()` discriminates the two HTTP 200 shapes. An empty string means no
// notification was created (e.g. all targets were unreachable / not subscribed).
// `result.getErrors()` is polymorphic (declared as `Object`): a `List<String>` in the
// no-subscribers case, or a Map keyed by recipient-identifier type
// (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...) when
// the notification WAS created but some recipients were skipped.
if (result.getId() == null || result.getId().isEmpty()) {
System.out.println("Notification was not sent: " + result.getErrors());
} else if (result.getErrors() != null) {
System.out.println("Notification created: " + result.getId() + " (partial failures: " + result.getErrors() + ")");
} else {
System.out.println("Notification created: " + result.getId());
}
} catch (ApiException e) {
System.err.println("Exception when calling DefaultApi#createNotification");
System.err.println("Status code: " + e.getCode());
System.err.println("Reason: " + e.getResponseBody());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}using System;
using System.Collections.Generic;
using System.Diagnostics;
using OneSignalApi.Api;
using OneSignalApi.Client;
using OneSignalApi.Model;
namespace Example
{
public class CreateNotificationExample
{
public static void Main()
{
Configuration config = new Configuration();
config.BasePath = "https://api.onesignal.com";
config.AccessToken = "YOUR_REST_API_KEY";
var apiInstance = new DefaultApi(config);
var notification = new Notification
{
AppId = "YOUR_APP_ID",
Contents = new LanguageStringMap(en: "Hello from OneSignal!"),
Headings = new LanguageStringMap(en: "Push Notification"),
IncludeAliases = new Dictionary<string, List<string>>
{
{ "external_id", new List<string> { "YOUR_USER_EXTERNAL_ID" } }
},
TargetChannel = Notification.TargetChannelEnum.Push,
// Idempotency key: a client-generated UUID that lets you safely retry on
// network failure. If two requests arrive with the same key inside the
// 30-day window, only the first is sent and the second returns the original
// response. Use Guid.NewGuid() — DO NOT reuse keys across logically distinct
// sends.
IdempotencyKey = Guid.NewGuid().ToString()
};
try
{
CreateNotificationSuccessResponse result = apiInstance.CreateNotification(notification);
// `result.Id` discriminates the two HTTP 200 shapes. An empty string means
// no notification was created (e.g. all targets were unreachable / not
// subscribed). `result.Errors` is polymorphic: a `List<string>` in the
// no-subscribers case, or an object keyed by recipient-identifier type
// (`invalid_player_ids`, `invalid_external_user_ids`, `invalid_aliases`, ...)
// when the notification WAS created but some recipients were skipped.
if (string.IsNullOrEmpty(result.Id))
{
Debug.WriteLine("Notification was not sent: " + result.Errors);
}
else if (result.Errors != null)
{
Debug.WriteLine("Notification created: " + result.Id + " (partial failures: " + result.Errors + ")");
}
else
{
Debug.WriteLine("Notification created: " + result.Id);
}
}
catch (ApiException e)
{
Debug.Print("Exception when calling DefaultApi.CreateNotification: " + e.Message);
Debug.Print("Status Code: " + e.ErrorCode);
Debug.Print("Response Body: " + e.ErrorContent);
Debug.Print(e.StackTrace);
}
}
}
}use onesignal_rust_api::apis::configuration::Configuration;
use onesignal_rust_api::apis::default_api;
use onesignal_rust_api::models::notification::TargetChannelType;
use onesignal_rust_api::models::{LanguageStringMap, Notification};
use uuid::Uuid;
#[tokio::main]
async fn main() {
let mut configuration = Configuration::new();
configuration.rest_api_key_token = Some("YOUR_REST_API_KEY".to_string());
let mut notification = Notification::new("YOUR_APP_ID".to_string());
notification.contents = Some(Box::new(LanguageStringMap {
en: Some("Hello from OneSignal!".to_string()),
..Default::default()
}));
notification.headings = Some(Box::new(LanguageStringMap {
en: Some("Push Notification".to_string()),
..Default::default()
}));
let mut aliases = std::collections::HashMap::new();
aliases.insert(
"external_id".to_string(),
vec!["YOUR_USER_EXTERNAL_ID".to_string()],
);
notification.include_aliases = Some(aliases);
notification.target_channel = Some(TargetChannelType::Push);
// Idempotency key: a client-generated UUID that lets you safely retry on network failure.
// If two requests arrive with the same key inside the 30-day window, only the first is
// sent and the second returns the original response. The `uuid` crate must be declared
// in your own Cargo.toml (Cargo doesn't expose transitive crates by name to downstream
// code) — add `uuid = { version = "1", features = ["v4"] }` to your `[dependencies]`.
// DO NOT reuse keys across logically distinct sends.
notification.idempotency_key = Some(Uuid::new_v4().to_string());
match default_api::create_notification(&configuration, notification).await {
Ok(resp) => {
// `resp.id` discriminates the two HTTP 200 shapes. An empty string or `None`
// means no notification was created (e.g. all targets were unreachable / not
// subscribed). `resp.errors` is polymorphic (typed as `Option<serde_json::Value>`):
// a `Vec<String>` in the no-subscribers case, or an object keyed by
// recipient-identifier type (`invalid_player_ids`, `invalid_external_user_ids`,
// `invalid_aliases`, ...) when the notification WAS created but some recipients
// were skipped.
match resp.id.as_deref() {
Some("") | None => eprintln!("Notification was not sent: {:?}", resp.errors),
Some(id) if resp.errors.is_some() => {
println!("Notification created: {} (partial failures: {:?})", id, resp.errors)
}
Some(id) => println!("Notification created: {}", id),
}
}
Err(onesignal_rust_api::apis::Error::ResponseError(content)) => {
eprintln!("create_notification failed: HTTP {}", content.status);
eprintln!("Response Body: {}", content.content);
}
Err(e) => eprintln!("create_notification failed: {:?}", e),
}
}{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"external_id": "<string>",
"errors": {
"invalid_aliases": {
"external_id": [
"[\"user_id_1\", \"user_id_1\", \"user_id_2\"]"
],
"onesignal_id": [
"[\"1589641e-bed1-4325-bce4-d2234e578884\", \"1589641e-bed1-4325-bce4-d2234e578884\", \"1589641e-bed1-4325-bce4-d2234e578884\"]"
]
},
"invalid_player_ids": [
"<string>"
]
},
"warnings": {
"invalid_external_user_ids": "<string>"
}
}{
"errors": [
{
"Message Notifications must have English language content": "<string>",
"Incorrect subscription_id format in include_subscription_ids (not a valid UUID):": "<string>",
"Platforms You may only send to one delivery channel at a time. Make sure you are only including one of push platforms, Email, or SMS.": "<string>"
}
]
}{
"errors": [
"This API is not available for applications on your plan."
]
}{
"errors": [
"API rate limit exceeded"
]
}{
"errors": [
"Service temporarily unavailable"
]
}Overview
The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for push. See Email or SMS to send to those channels. Ensure your application is properly configured by following the Mobile SDK Setup and/or Web SDK Setup guides. You should see subscribed push Subscriptions in your OneSignal dashboard to send them messages.Headers
Your App API key with prefix Key. See Keys & IDs.
Body
Your OneSignal App ID in UUID v4 format. See Keys & IDs.
The main message body with language-specific values. Supports Message Personalization.
Show child attributes
Show child attributes
Target up to 20,000 users by their external_id, onesignal_id, or your own custom alias. Use with target_channel to control the delivery channel. Not compatible with any other targeting parameters like filters, include_subscription_ids, included_segments, or excluded_segments. See Sending messages with the OneSignal API.
Show child attributes
Show child attributes
The targeted delivery channel. Required when using include_aliases. Accepts push, email, or sms.
push, email, sms Target users' specific subscriptions by ID. Include up to 20,000 subscription_id per API call. Not compatible with any other targeting parameters like filters, include_aliases, included_segments, or excluded_segments. See Sending messages with the OneSignal API.
Target predefined Segments. Users that are in multiple segments will only be sent the message once. Can be combined with excluded_segments. Not compatible with any other targeting parameters like filters, include_aliases, or include_subscription_ids. See Sending messages with the OneSignal API.
Exclude users in predefined Segments. Overrides membership in any segment specified in the included_segments. Not compatible with any other targeting parameters like filters, include_aliases, or include_subscription_ids. See Sending messages with the OneSignal API.
Filters define the segment based on user properties like tags, activity, or location using flexible AND/OR logic. Limited to 200 total entries, including fields and OR operators. See Sending messages with the OneSignal API.
1 - 200 elementsRequired. The fitler object.
- Filter
- Operator
Show child attributes
Show child attributes
The message title with language-specific values. Required for Huawei and Web Push. If not set for Web Push, it defaults to your 'Site Name'. Not required if using template_id or content_available. Supports Message Personalization and must include the same languages as contents to ensure localization consistency.
Show child attributes
Show child attributes
iOS only. The subtitle with language-specific values. Supports Message Personalization and must include the same languages as contents to ensure localization consistency.
Show child attributes
Show child attributes
An internal name you set to help organize and track messages. Not shown to recipients. Maximum 128 characters.
Include user or context-specific data (e.g., cart items, OTPs, links) in a message. Use with template_id. See Message Personalization. Max size: 2KB (Push/SMS), 10KB (Email).
The local name or URL of the media attachment to include in your notification. Users can expand the notification to view images, videos, or other supported attachments. See Images & Rich Media.
Show child attributes
Show child attributes
The local name or URL of the image to include in your Google Android notification. Users can expand the notification to view the images. See Images & Rich Media.
The local name or URL of the image to include in your Huawei Android notification. Users can expand the notification to view the images. See Images & Rich Media.
The local name or URL of the image to include in your Amazon Android notification. Users can expand the notification to view the images. See Images & Rich Media.
The URL of the image to include in your Chrome notification. Users can expand the notification to view the images. Supported on Chrome for Windows and Android. macOS does not support this parameter and instead expands the chrome_web_icon. See Images & Rich Media.
The local name of the small icon to display in the Google Android notification. See Notification icons.
The local name of the small icon to display in the Huawei Android notification. See Notification icons.
The local name of the small icon to display in the Amazon Android notification. See Notification icons.
The local name or URL of the large icon to display in the Google Android notification. See Notification icons.
The local name or URL of the large icon to display in the Huawei Android notification. See Notification icons.
The local name or URL of the large icon to display in the Amazon Android notification. See Notification icons.
The URL of the icon to display in the Chrome web notification. Defaults to the resource set in the OneSignal dashboard. See Notification icons.
The URL of the icon to display in the Firefox web notification. Defaults to the resource set in the OneSignal dashboard. See Notification icons.
The URL of the monochrome status-bar icon for Chrome web notifications on Android. Defaults to the Chrome icon. See Notification icons.
The UUID of the Android notification channel category created within your OneSignal app.
The UUID of the Android notification channel category created within your Android app.
The UUID of the Android notification channel category created within your OneSignal app.
The UUID of the Android notification channel category created within your Huawei app.
The category you set for notifications sent to Huawei devices. The category chosen must align with an approved self-classification application. Subject to daily send limitations ranging from 2 to 5, depending on the specific third-level classifications the message falls under.
MARKETING, IM, VOIP, SUBSCRIPTION, TRAVEL, HEALTH, WORK, ACCOUNT, EXPRESS, FINANCE, DEVICE_REMINDER, MAIL Controls how OneSignal delivers the push to Huawei (HMS) devices. Both options can display a visible notification. Options: message - (default) HMS Core renders the notification server-side. Supports title and body only (no images, buttons, or other rich features). Displays even if the app is force quit, and if the device is offline it displays when the device reconnects within the ttl timeframe (usually 3 days). Does not support Confirmed delivery. Huawei reports receipts only in their own dashboard. data - HMS Core delivers the payload to the device and the OneSignal SDK renders the notification client-side. This enables the full OneSignal feature set (large images, action buttons, etc.) and supports Confirmed delivery. Because the SDK must run to render it, the notification is not shown if the app has been force quit (HMS Core will not start the app). This is also the type to use for silent data & background notifications on Huawei. Note: data here refers to the HMS transport type, not a silent notification. A data-type push with visible content still shows a full notification.
message, data Define a tag for associating messages in a batch delivery, facilitating precise monitoring and analysis of delivery stats. This tag is returned to your server when Huawei's Push Kit sends a message receipt. You can set this parameter to track your push campaigns' performance and optimize your messaging strategy.
Sets the badge count to this exact number on Huawei devices. Range: 0-99. Set to 0 to clear the badge. If both huawei_badge_set_num and huawei_badge_add_num are provided, huawei_badge_set_num takes priority. Requires EMUI 10.0.0+ and Push SDK 10.1.0+. See Badges.
0 <= x <= 99Set the priority based on the urgency of the message. 10 - High priority. 5 - Normal priority. Recommended and default value is 10. APNs and FCM use this parameter to determine how quickly a notification is delivered and processed, particularly in power-saving modes. If sending data/background notifications, 5 (Normal priority) is recommended. For details, see APNs apns-priority and FCM priority.
10, 5 The priority and delivery timing of iOS notifications based on their importance and the urgency with which they should interrupt the user. See iOS Focus modes and interruption levels.
active, passive, time_sensitive, critical The name of a sound file in your app bundle, including its extension (for example, explode_sound.wav), to play when this message is delivered. Omit this field to deliver it silently. See Notification sounds.
The ARGB Hex formatted color of the Android small icon background. For Android 8+ use Android notification channel category and android_channel_id.
The ARGB Hex formatted color of the Huawei small icon background. For Android 8+ use Android notification channel category and huawei_channel_id.
The httpsURL that opens in the browser when a user interacts with the notification. See URLs, Links and Deep Links. Supports Message Personalization.
Similar to the url parameter but exclusively targets mobile platforms like iOS, Android. Accepts values other than https but must use your-app-scheme:// protocol.
Use with app_url if your app and website need different URLs. Accepts URLs with protocol https://
Direct the notification to a specific user experience within your app, such as an App Clip, or target a particular window in applications that use multiple scenes. See Apple's documentation.
Add a maximum of 3 Action Buttons to Android and iOS push notifications. See Action Buttons.
3Show child attributes
Show child attributes
Add a maximum of 2 Action Buttons to Chrome web push notifications. See Action Buttons.
2Show child attributes
Show child attributes
An ID to group notifications on Apple devices. Notifications with the same identifier are organized together in the notification center.
A value between 0 and 1, to sort the notifications from your app. The highest score gets featured in the notification summary. See iOS Relevance Score
An ID to group notifications on Google Android devices. Notifications with the same identifier are organized together in the notification center.
An ID to group notifications on Amazon Android devices. Notifications with the same identifier are organized together in the notification center.
The duration in seconds for which a notification remains valid if the device is offline. Any number between 0 and 2419200 (28 days). Defaults to 3 days. See Push: Time to Live.
An ID that replaces older notifications with newer ones that have the same identifier. For mobile push only. See Push: Collapse ID.
An ID that prevents replacement of older notifications with newer ones that have different identifiers. For web push only. See Push: Web Push Topic.
Bundle a custom data map within your notification, which is then passed to your app. See Push: Additional Data.
Allows for sending data/background notifications to the Android and iOS apps. Set to true and omit contents. Apple interprets this as content-available=1. See Data & background notifications.
Enable users to respond directly to a notification without launching the app. The Category will activate the corresponding Notification Content Extension in your app when the push is interacted with.
Use only for VoIP notifications. Corresponds to the apns-push-type. OneSignal automatically sets this value to alert or background based on the notification content. Pass voip to initiate VoIP calls or alert the user to incoming VoIP calls.
Specifies if the notification should target iOS mobile apps only. Defaults to true. If set to true, all other platforms are disabled unless explicitly enabled.
Specifies if the notification should target Google Android mobile apps only. Defaults to true. If set to true, all other platforms are disabled unless explicitly enabled.
Specifies if the notification should target Huawei mobile apps only. Defaults to true. If set to true, all other platforms are disabled unless explicitly enabled.
Specifies if the notification should target web push only. Defaults to true. If set to true, all other platforms are disabled unless explicitly enabled.
Specifies if the notification should target Chrome only. Defaults to true. If set to true, all other platforms are disabled unless explicitly enabled.
Specifies if the notification should target Firefox only. Defaults to true. If set to true, all other platforms are disabled unless explicitly enabled.
Specifies if the notification should target Safari only. Defaults to true. If set to true, all other platforms are disabled unless explicitly enabled
Specifies if the notification should target Windows apps only. Defaults to true. If set to true, all other platforms are disabled unless explicitly enabled
Specifies if the notification should target Amazon devices only. Defaults to true. If set to true, all other platforms are disabled unless explicitly enabled
Schedule delivery for a future date/time (in UTC). The format must be valid per the ISO 8601 standard and compatible with JavaScript's Date() parser. Example: 2025-09-24T14:00:00-07:00
Controls how messages are delivered on a per-user basis. timezone sends at the same local time across time zones. last-active delivers based on each user's most recent session. Not compatible with Push Throttling. If you set delayed_option, set throttle_rate_per_minute to 0.
Use with delayed_option: 'timezone' to set a consistent local delivery time. Accepted formats: '9:00AM' (12-hour), '21:45' (24-hour), '09:45:30' (HH:mm:ss).
Overrides the throttle limit set in the OneSignal dashboard settings. Must be enabled through the dashboard. Only available with push notifications. See Push Throttling. If throttle_rate_per_minute is set to 0, then the message will be sent immediately without any rate limiting.
Overrides the frequency cap set in the OneSignal dashboard settings. Must be enabled through the dashboard first. Only available with push notifications. See Frequency Capping. Set to false to disable frequency capping.
A unique identifier used to prevent duplicate messages from repeat API calls. See Idempotent notification requests. Any RFC 9562 UUID supported. Valid for 30 days. Previously called external_id.
Response
200
- Message Sent
- Message Not Sent
Two variants are possible with HTTP 200, distinguished by the id field: a UUID indicates the message was accepted and dispatched (Message Sent); an empty string indicates the request was valid but no subscribers matched (Message Not Sent). Inspect errors when id is empty.
Notification ID in UUID v4 format. If id is an empty string, then the message was not sent.
The idempotency_key parameter from the request, echoed back. Null when no idempotency_key was provided. Use this to detect duplicate-send attempts. See Idempotent message requests.
Per-channel listings of invalid identifiers in the request. Only emitted when at least one identifier in the request failed validation. Each listed key is optional; the keys present depend on the channel and request.
Show child attributes
Show child attributes
Non-fatal warnings emitted alongside a successful send.
Show child attributes
Show child attributes
Was this page helpful?