Push Broadcast
A push notification is a message sent to a subscriber. A user visiting a website or application and coming across a request, asking them if they'd like to receive updates or notifications from that site. If the user agrees and gives permission, they become a subscriber. This means they've provided the necessary consent to receive push campaigns from that source. Therefore, whenever the website or application wants to convey information, updates, or any other messages, it can easily send a push campaign to its subscribers, ensuring their message is delivered.
Create Push Broadcast
This endpoint allows you to create new notifications. You can target specific subscribers using segments, subscriber hash/id, or profile id, among many other options. This call accepts form-encoded request bodies and returns responses in JSON format.
Create a push Broadcast via the PushEngage Dashboard.
https://api.pushengage.com/apiv1/notifications
Request Parameters
Parameter Name | Type | Required | Description |
---|---|---|---|
notification_title | String | Yes | Title of the push notification, should not exceed 85 characters. |
notification_message | String | Yes | The message to be displayed in the push notification, should not exceed 135 characters. |
notification_url | String | Yes | URL to be opened upon clicking the received push notification. It should adhere to the W3C format. |
image_url | String | No | Image to be displayed in the Push Notification. |
notification_type | String | No | Defines the status of the notification, which can be now , later , or draft . Use now to send the notification immediately, later to schedule the notification, and draft to save the notification as a draft. If this parameter is not provided, the notification will be sent immediately. |
valid_from_utc | String | No | Indicates the send time for scheduled notifications, based on the timezone of the configured site. This parameter is required only if the notification_type is set to later . The format should be YYYY-MM-DD HH:mm:ss . |
profile_id | Array of String | No | A unique profile ID for each subscriber, provided by the site owner. Notifications will only be sent to subscribers associated with this profile ID. The maximum number of entries in the profile_id array is 100, and this is available only in paid plans. |
include_segments | Array of String | No | Accepts an array of segment_id values. Notifications will only be sent to subscribers who are part of these segments. |
exclude_segments | Array of String | No | The exclude_segments parameter accepts an array of segment_id values. Notifications will not be sent to subscribers who are part of the segments specified by these segment ids. |
include_countries | Array of String | No | include_countries accepts value as array of country. Notifications will be sent to only those subscribers, which are subscribed from these countries. |
exclude_countries | Array of String | No | exclude_countries accepts value as array of country. Notifications will be not sent to those subscribers, which are subscribed from these countries. |
include_states | Array of String | No | include_states accepts value as array of state. Notifications will be sent to only those subscribers, which are subscribed from these states. |
include_cities | Array of String | No | include_cities accepts value as array of city. Notifications will be sent to only those subscribers, which are subscribed from these cities. |
include_device_types | Array of String | No | include_device_types accepts value as array of device. Notifications will be sent to only those subscribers, which are subscribed from these devices. |
include_browsers | Array of String | No | include_browsers accepts value as array of browser. Notifications will be sent to only those subscribers, which are subscribed from these browsers. |
from_date | String | No | Defines the start date and time (in ISO 8601 format) of the subscriber's range. Notifications will only be sent to subscribers who joined after the specified date & time. (e.g., 2020-05-01 OR 2020-05-01T10:28:35Z) |
to_date | String | No | Defines the end date and time (in ISO 8601 format) of the subscriber's range. Notifications will only be sent to subscribers who joined before the specified date & time. (e.g., 2020-05-26 OR 2020-05-26T10:28:35Z) |
require_interaction | Number | No | This defines the maximum duration for the notification to remain on browsers without user interaction. |
notification_expiry | Number | No | This is the expiry time for a notification, after which it will not be sent to subscribers. The maximum time allowed is 28 days, in minutes. |
subscriber_hash | Array of String | No | A subscriber hash is unique for a subscriber provided by PushEngage. Notifications will be sent to the device having this subscriber hash. Maximum entries in subscriber_hash array is 100. |
big_image_url | String | No | The URL of an image to be displayed as part of the notification. |
Attributes | JSON Encoded Array | No | Attributes are key-value pairs used to store additional information about subscribers. They can be used for segmenting subscribers and sending personalized notifications. |
multi_element_title1 | String | No | First button title. |
multi_element_url1 | String | No | First button URL to be opened, should be in W3C format. |
multi_element_image1 | String | No | First button image URL, should be in W3C format. |
multi_element_title2 | String | No | Second button title. |
multi_element_url2 | String | No | Second button URL to be opened, should be in W3C format. |
multi_element_image2 | String | No | Second button image URL, should be in W3C format. |
Response Object
Property Name | Type | Required | Description |
---|---|---|---|
success | Boolean | Yes | Indicates whether the push request was successful. Accepts values true or false . |
Notification_id | Number | Yes | Represents the unique ID of the notification. |
message | String | No | Provided in case of failure, indicating the reason for the failure. |
valid_from_utc: Input should be in local date and time with the format "YYYY-MM-DD hh:mm:ss" (e.g., 1997-07-16 19:20:30) using a 24-hour clock.
- YYYY: Four-digit year
- MM: Two-digit month (01=January, etc.)
- DD: Two-digit day (01-31)
- HH: Two-digit hour (00-23) (no AM/PM)
- mm: Two-digit minute (00-59)
- ss: Two-digit second (00-59)
Example
Request
- cURL
- PHP
curl -X POST -H 'api_key: <your_pushengage_api_key>' -H 'Content-Type: application/x-www-form-urlencoded' -d 'notification_title=this is title of notification¬ification_message=this is message of notification¬ification_url=http://www.example.com' "https://api.pushengage.com/apiv1/notifications"
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.pushengage.com/apiv1/notifications",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "notification_title=this is title of notification¬ification_message=this is message of notification¬ification_url=http://www.example.com",
CURLOPT_HTTPHEADER => array(
"api_key: <your_pushengage_api_key>",
"content-type: application/x-www-form-urlencoded"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
?>
Response
- 200 OK
- 401 Unauthorized
- 400 Bad Request
- 500 Internal Server Error
{
"success": true,
"notification_id": 12345
}
{
"success": false,
"message": "API KEY Invalid"
}
{
"success": false,
"message": "The Title field is required."
}
{
"success": false,
"message": "The Message field is required."
}
{
"success": false,
"message": "The URL field is required."
}
{
"success": false,
"message": "Something went wrong."
}
Create Push Broadcast Based on Attributes
Create notification based on subscriber attributes such as age, unique ID, gender, location, and many more.
Example
Request
- cURL
- PHP
curl -X POST -H "api_key: <your_pushengage_api_key>" -H "Content-Type: application/x-www-form-urlencoded" -d 'notification_title=this is title of notification¬ification_message=this is message of notification¬ification_url=http://www.example.com¬ification_type=now&attributes=[[{"key": "age", "op": "gt", "value": 20}]]' "https://api.pushengage.com/apiv1/notifications"
<?php
$attribute_filter_rule = [
[
{
"key": "age",
"op": "gt",
"value": 20
}
]
];
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.pushengage.com/apiv1/notifications",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "notification_title=this is title of notification¬ification_message=this is message of notification¬ification_url=http://www.example.com¬ification_type=now&attributes="+json_encode($attribute_filter_rule),
CURLOPT_HTTPHEADER => array(
"api_key: <your_pushengage_api_key>",
"content-type: application/x-www-form-urlencoded"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
?>
Response
- 200 OK
- 401 Unauthorized
- 400 Bad Request
- 500 Internal Server Error
{
"success": true,
"notification_id": 12345
}
{
"success": false,
"message": "API KEY Invalid"
}
{
"success": false,
"message": "Error Message."
}
{
"success": false,
"message": "Something went wrong."
}
Create Schedule Push Broadcast
Create new notifications that can be scheduled for future delivery. To create a scheduled notification, you need to specify notification_type
as later
and valid_from_utc
.
Example
Request
- cURL
- PHP
curl -X POST -H "api_key: <your_pushengage_api_key>" -H "Content-Type: application/x-www-form-urlencoded" -d 'notification_title=this is title of notification¬ification_message=this is message of notification¬ification_url=http://www.example.com¬ification_type=later&valid_from_utc=<your_schedule_time>' "https://api.pushengage.com/apiv1/notifications"
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.pushengage.com/apiv1/notifications",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "notification_title=this is title of notification¬ification_message=this is message of notification¬ification_url=http://www.example.com¬ification_type=later&valid_from_utc=<your_schedule_time>",
CURLOPT_HTTPHEADER => array(
"api_key: <your_pushengage_api_key>",
"content-type: application/x-www-form-urlencoded"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
?>
Response
- 200 OK
- 401 Unauthorized
- 400 Bad Request
- 500 Internal Server Error
{
"success": true,
"notification_id": 12345
}
{
"success": false,
"message": "API KEY Invalid"
}
{
"success": false,
"message": "The Title field is required."
}
{
"success": false,
"message": "The Message field is required."
}
{
"success": false,
"message": "The URL field is required."
}
{
"success": false,
"message": "Something went wrong."
}
Create Draft Push Broadcast
Create new notifications that can be saved as drafts. To create a draft notification, specify notification_type
as draft
.
Example
Request
- cURL
- PHP
curl -X POST -H "api_key: <your_pushengage_api_key>" -H "Content-Type: application/x-www-form-urlencoded" -d 'notification_title=this is title of notification¬ification_message=this is message of notification¬ification_url=http://www.example.com¬ification_type=draft' "https://api.pushengage.com/apiv1/notifications"
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.pushengage.com/apiv1/notifications",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "notification_title=this is title of notification¬ification_message=this is message of notification¬ification_url=http://www.example.com¬ification_type=draft",
CURLOPT_HTTPHEADER => array(
"api_key: <your_pushengage_api_key>",
"content-type: application/x-www-form-urlencoded"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
?>
Response
- 200 OK
- 401 Unauthorized
- 400 Bad Request
- 500 Internal Server Error
{
"success": true,
"notification_id": 12345
}
{
"success": false,
"message": "API KEY Invalid"
}
{
"success": false,
"message": "The Title field is required."
}
{
"success": false,
"message": "The Message field is required."
}
{
"success": false,
"message": "The URL field is required."
}
{
"success": false,
"message": "Something went wrong."
}
Impression Count Callback URL Example
A notification with an Impression Count Callback URL will trigger a call to a third-party URL when the notification is viewed by the subscriber.
This API is restricted reach out to care@pushengage.com for approval.