Documentation

  1. Home
  2. Documentation
Need Help?

Visit the support center for answers to common questions and for ways to get in touch.

Got Feedback?

We'd love to hear what you have to say about our documentation. Let us know how we can improve it.

Send Notifications API

Instantly send push notifications to your users with this powerful API.

  • API Reference
  • Code Samples
  • Test it out 
  • POST https://api.pushy.me/push?api_key=SECRET_API_KEY

    Note: Make sure to replace SECRET_API_KEY with your app's Secret API Key, available in the Pushy Dashboard (Click your app -> API Authentication tab). This is a backend API endpoint. Never expose your application's Secret API Key in your client code.

    API Request

    Sample Request Body

    {
    "to": "a6345d0278adc55d3474f5",
    "data": {
        "message": "Hello World!"
    },
    "notification": {
        "title": "Test Notification",
        "body": "Hello World \u270c",
        "badge": 1,
        "sound": "ping.aiff"
    }
}

    Note: Please make sure to send the Content-type: application/json header with your request.

    Request Schema
    Field Description Example
    to*
    String[] / String     		A device token, an array of device tokens, a topic, or an array of topics (prefix topic names with /topics/, max 100 topics).

    The max number of tokens specified cannot exceed 100,000 per request.     		["a6345d0278adc55d3474f5"]
    data*
    Object     		The payload data you want to push to devices, limited to 4kb and accessible in your notification listener.

    Get in touch if you need to send larger payloads.     		{"message": "Hello World!"}
    time_to_live
    Integer     		Specifies how long (in seconds) the push notification should be kept if the device is offline.
    If unspecified, notifications will be kept for 30 days. The maximum value is 365 days.     		3600
    content_available
    Boolean (iOS)     		When set to true, your app's notification handler will be invoked even if the app is running in the background, making it possible to fetch updated content from the server or execute other custom logic without necessarily alerting the user.

    Requires the Background Modes -> Remote Notifications capability to be enabled.

    Note: Apple restricts the number of silent notifications you can send to an iOS device in a given day. Sending too many to the same device in a single day, or sending them in quick succession, will lead to those notifications being throttled (and dropped) by APNs (more info).     		true
    mutable_content
    Boolean (iOS)     		When set to true, your app's Notification Service Extension will be invoked even if the app is running in the background, making it possible to download and display rich media attachments within your notification.

    Requires the Background Modes -> Remote Notifications capability to be enabled.    		 true
    notification
    Object (iOS)     		iOS notification options, such as the alert message, sound, or badge number.
    - title
    String     		A short string describing the purpose of the notification, visible on iOS 8.2+ and Apple Watch. "Alert"
    - body
    String     		The main alert message, visible on the lock screen and in other areas on iOS. Supports Apple Emojis via their unicode representation. "Hello World \u270c"
    - badge
    Integer     		The number to display as the badge of the app icon. 1
    - sound
    String / Object     		The filename of a sound in the app bundle or in the Library/Sounds folder of your app's data container, or a sound dictionary object for critical alerts (iOS 12, more info) . "ping.aiff"
    - category
    String (iOS 10+)     		Your app's Notification Content Extension with the matching category will be invoked in order to display custom notification UI. "photo_notification"
    - thread_id
    String (iOS 12+)     		Group multiple notifications together by specifying a common thread_id.

    Requires implementation of a Notification Content Extension.    		 "chat-129381983414"
    - interruption_level
    String (iOS 15+)     		Indicate the importance and delivery timing of a notification on iOS 15+, with possible values of passive, active, time-sensitive, or critical.

    Defaults to active. Anything above active requires capabilities to be enabled in your Xcode project. Refer to the APNs documentation for more information.    		 "time-sensitive"
    - loc_key
    String     		The localization key of a string present in your app's Localizable.strings file.

    Use this parameter to localize the notification body. Refer to the APNs documentation for more information.    		 "NOTIFICATION_TEXT"
    - loc_args
    String[]     		The replacement strings to substitute in place of the %@ placeholders of the localization string matching the specified loc_key.

    Use this parameter to localize the notification body. Refer to the APNs documentation for more information.    		 ["John", "1"]
    - title_loc_key
    String     		The localization key of a string present in your app's Localizable.strings file.

    Use this parameter to localize the notification title. Refer to the APNs documentation for more information.    		 "NOTIFICATION_TITLE"
    - title_loc_args
    String[]     		The replacement strings to substitute in place of the %@ placeholders of the localization string matching the specified title_loc_key.

    Use this parameter to localize the notification title. Refer to the APNs documentation for more information.    		 ["John", "1"]
    schedule
    Integer     		Schedule the notification for later by specifying a futuristic Unix timestamp (in seconds).

    Your scheduled time cannot exceed 1 year.     		1652344429
    collapse_key
    String     		When specified, any undelivered notifications pending for device(s) with the same collapse_key are discarded. Only the last message gets delivered when connectivity can be re-established with the device.

    Collapse keys should not exceed 32 characters.     		news_updates
    API Response

    Sample Response Body

    {
    "success": true,
    "id": "5ea9b214b47cad768a35f13a",
    "info": {
        "devices": 1
    }
}
    Response Schema
    Field Description Example
    id
    String     		The push notification unique ID. Use it to check delivery status using the Notification Status API. "5ea9b214b47cad768a35f13a"
    success
    Boolean     		Returned if the API request was successful. true
    info
    Object     		Contains additional information about the notification, for debugging purposes. {"devices": 1, "failed": ["abc"]}
    - devices
    Integer     		The number of devices that will potentially receive the notification. 1
    - failed
    String[]     		An array of invalid device tokens passed in which could not be found in our database registered under the app with the Secret API Key used to authenticate this request. ["9d1096fe0c58670dad2116"]
    API Error Reference

    Sample Error Response

    {
    "code": "NO_RECIPIENTS", 
    "error": "No devices matched the specified condition."
}
    Error Codes

    A list of endpoint-specific error codes, in addition to the global API errors.

    Error code Description HTTP status code
    NO_RECIPIENTS The to parameter did not resolve to any recipients, either due to invalid device tokens, or Pub/Sub topic(s) with zero subscribers. 400 Bad Request
    NO_APNS_AUTH Your app needs to be configured with an APNs Auth Key to send notifications to iOS devices. 400 Bad Request
    PAYLOAD_LIMIT_EXCEEDED Your data payload has exceeded 4kb in stringified JSON character length. 400 Bad Request

  • We provide code samples to help you implement this API request: 

  • POST https://api.pushy.me/push?api_key=SECRET_API_KEY
    URL Param Value
    SECRET_API_KEY
    JSON Params
    JSON Param Value
    to*
    String[] / String
    data*
    Object

    Show optional params


    API Response

    500 CLIENT ERROR

    N/A