Skip to main content

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.

POST
 https://api.pushengage.com/apiv1/notifications

Request Parameters

Parameter NameTypeRequiredDescription
notification_titleStringYesTitle of the push notification, should not exceed 85 characters.
notification_messageStringYesThe message to be displayed in the push notification, should not exceed 135 characters.
notification_urlStringYesURL to be opened upon clicking the received push notification. It should adhere to the W3C format.
image_urlStringNoImage to be displayed in the Push Notification.
notification_typeStringNoDefines 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_utcStringNoIndicates 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_idArray of StringNoA 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_segmentsArray of StringNoAccepts an array of segment_id values. Notifications will only be sent to subscribers who are part of these segments.
exclude_segmentsArray of StringNoThe 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_countriesArray of StringNoinclude_countries accepts value as array of country. Notifications will be sent to only those subscribers, which are subscribed from these countries.
exclude_countriesArray of StringNoexclude_countries accepts value as array of country. Notifications will be not sent to those subscribers, which are subscribed from these countries.
include_statesArray of StringNoinclude_states accepts value as array of state. Notifications will be sent to only those subscribers, which are subscribed from these states.
include_citiesArray of StringNoinclude_cities accepts value as array of city. Notifications will be sent to only those subscribers, which are subscribed from these cities.
include_device_typesArray of StringNoinclude_device_types accepts value as array of device. Notifications will be sent to only those subscribers, which are subscribed from these devices.
include_browsersArray of StringNoinclude_browsers accepts value as array of browser. Notifications will be sent to only those subscribers, which are subscribed from these browsers.
from_dateStringNoDefines 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_dateStringNoDefines 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_interactionNumberNoThis defines the maximum duration for the notification to remain on browsers without user interaction.
notification_expiryNumberNoThis 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_hashArray of StringNoA 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_urlStringNoThe URL of an image to be displayed as part of the notification.
AttributesJSON Encoded ArrayNoAttributes are key-value pairs used to store additional information about subscribers. They can be used for segmenting subscribers and sending personalized notifications.
multi_element_title1StringNoFirst button title.
multi_element_url1StringNoFirst button URL to be opened, should be in W3C format.
multi_element_image1StringNoFirst button image URL, should be in W3C format.
multi_element_title2StringNoSecond button title.
multi_element_url2StringNoSecond button URL to be opened, should be in W3C format.
multi_element_image2StringNoSecond button image URL, should be in W3C format.

Response Object

Property NameTypeRequiredDescription
successBooleanYesIndicates whether the push request was successful. Accepts values true or false.
Notification_idNumberYesRepresents the unique ID of the notification.
messageStringNoProvided in case of failure, indicating the reason for the failure.
info

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 -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&notification_message=this is message of notification&notification_url=http://www.example.com' "https://api.pushengage.com/apiv1/notifications"

Response

{
"success": true,
"notification_id": 12345
}

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 -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&notification_message=this is message of notification&notification_url=http://www.example.com&notification_type=now&attributes=[[{"key": "age", "op": "gt", "value": 20}]]' "https://api.pushengage.com/apiv1/notifications"

Response

{
"success": true,
"notification_id": 12345
}

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 -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&notification_message=this is message of notification&notification_url=http://www.example.com&notification_type=later&valid_from_utc=<your_schedule_time>' "https://api.pushengage.com/apiv1/notifications"

Response

{
"success": true,
"notification_id": 12345
}

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 -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&notification_message=this is message of notification&notification_url=http://www.example.com&notification_type=draft' "https://api.pushengage.com/apiv1/notifications"

Response

{
"success": true,
"notification_id": 12345
}

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.

info

This API is restricted reach out to care@pushengage.com for approval.