notifications_create
Create and send a web push notification to specific users, segments, or all subscribers. Target by user IDs, tags, or boolean expressions, and customize with title, body, images, actions, and scheduling.
Instructions
To send a web push notification,
send a POST request to /projects/PROJECT_ID/notifications.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ttl | No | The number of seconds after which the notification should be dropped if the device of the user is offline. | |
| body | Yes | The main text of the push notification. | |
| tags | No | The segments that should receive this push notification (i.e. the browsers that have at least one of these tags associated will receive the notification). If both uids and tags are present, only the browsers that match both the conditions will receive the notification (i.e. a browser must be associated to a user ID listed in uids and have at least one of those tags). Instead of simple tags, you can pass boolean expressions that use the operators !, &&, || (from highest to lowest precedence) and can include parentheses. If you pass an array of tags and boolean expressions they are interpreted as ||: the example above is equivalent to "tag0 || tag1 || tagA && !tagB". When the field is omitted or null, it is ignored and the push notification is sent to everyone or to the people specified by uids. When the field is an empty array, the notification will not be sent to anyone. | |
| uids | No | The users that should receive this push notification. When the field is omitted or null, it is ignored and the push notification is sent to everyone or to the people specified by tags. When the field is an empty array, the notification will not be sent to anyone. | |
| title | No | The title of the push notification. | |
| silent | No | Set to true if you want to disable the notification sound and vibration. | |
| urgent | No | Set to true for time-sensitive alerts (e.g. incoming phone call) that must wake up devices that are sleeping. | |
| actions | No | Add some action buttons to the notification. | |
| send_at | No | A time when the notification will be sent. | |
| starred | No | Bookmark the notification to make it easier to find it from the Pushpad dashboard. You can use this feature to highlight some notifications, for example those that have been sent manually. | |
| icon_url | No | The url of an image that will be used as the notification icon. Suggested size: 192x192px. | |
| badge_url | No | The url of a small image (that represents the app or the notification category) that will be displayed when there is not enough space to display the full notification (e.g. Android status bar). Suggested size: 96x96px. | |
| image_url | No | The url of an image that will be displayed in the notification content. Suggested size: 800px for the longer side. | |
| target_url | No | The url the user is redirected to when clicks the push notification. | |
| custom_data | No | An arbitrary string that represents some metadata that you want to attach to the notification. This string is passed as an argument to the JavaScript functions binded to the action buttons. | |
| custom_metrics | No | Aggregate the stats for this notification into the specified buckets (you can add up to 3 buckets for a single notification). Custom metrics are a way to aggregate the stats for all the notifications that belong to a given category. You need to explicitly create the categories from the project settings before using this feature. You can learn more in the Monitoring section of the documentation. | |
| project_id__path | Yes | The ID of a project. (Path parameter) | |
| require_interaction | No | Set to true in order to prevent browser from automatically closing the notification after a few seconds. Currently this applies only to Chrome on desktop. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | The notification id. | |
| uids | No | This field is included in the response only if you specify some user IDs (uids) in the request, and it indicates which of those users are subscribed to notifications. This field is not available for scheduled notifications. | |
| send_at | No | The time when the notification will be sent. Available only for scheduled notifications. | |
| scheduled | No | The number of devices the notification will be delivered to. Note that this value may differ from the number of user IDs (uids) in the request, for example when some users are not subscribed or are subscribed with multiple devices. This field is not available for scheduled notifications. |