Push API

Push API

This is a REST API that sends messages (pushes) in the form of a notification to devices that have your app installed. You choose the users whose devices receive the notification and the content of the notification for each user. The Kahuna servers calculate the best time of day to send the notification, based on a starting time and time window you specify, as well as data the servers already have about the habits of your users.

You can send push notifications to the following types of devices:

  • Android—uses Google Cloud Messaging (GCM) or Firebase Cloud Messaging (FCM) to send the notification. GCM/FCM works only if the user installed your app from the Google Play store.
  • iOS—uses Apple Push Notification Service (APNS). The user has to install your app from iTunes or the App Store to enable APNS for the device.

The Push API does not currently support web browser push.

Note: Kahuna recommends a limit on the number of API requests you make per day; up to 25% of the total number of users you have in Kahuna. For example, if you have 1000 users, you can make 250 requests per day with one unique user per request, or 250 batched requests per day with four users per request, or 100 batched requests per day with ten users per request.

API Request

Request URI and Header



To target the production environment:

To target the sandbox environment:


Request Header


Content-Type: application/json

Authorization: The API uses Basic Authentication (BasicAuth), which requires credentials in the form of a username (Secret Key) and password (API Key).

The Secret Key and API Key for the namespace are:

Secret Key: Available in Settings
API Key: Available in Settings


Request Body

The request body is a single JSON object that contains an array of push requests, as well as optional defaults that the server applies to any push request you submit. The JSON is also known as a request object. The fields and possible values of the request object are described below.


The param field values are used as defaults for all the push objects. A param key-value pair specifies extra data that is sent to the device but does not appear in the push message. Using a default param value enables you to send the same extra data to all the users you specify in your push request. Individual push objects can override the defaults.


The config field values are used as defaults for all push objects. A config key-value pair controls how the server issues the push notification. The following describes the fields for default_config and config. The value of a config field for an individual push request overrides the same value in default_config. The format is:


The desired start time for the push, specified in seconds from the POSIX Epoch in UTC time.

If the value is not specified or is in the past, the push is sent immediately. The maximum value is current_time + 604,800 seconds (seven days). current_time is the time of the request, measured in seconds since the POSIX epoch (1970-01-01 00:00:00 UTC).


The desired time range in which to choose the optimal time for sending the notification. For example, if you add the field optimal_hours : 4, Kahuna determines the optimal time within the next four hours to send the notification. The optimal time is based on a prediction of when the user is most likely to use your app.

If specified, the value must be greater than or equal to 1 and less than or equal to 24. If not specified, the value defaults to 0 and the notification is sent immediately (or at the start_time, if specified).


Indicates if this push request you make through the API rate-limits other campaign pushes. For example, if you set influence_rate_limiting : true and another campaign is scheduled to launch immediately afterwards, for any user who is a target of this push request, the other campaign push is rate-limited and not sent, because this push request counts towards the push cooldown for your account.

The default is true; this push request counts towards the push cooldown.


Indicates if this push is rate-limited. For example, if your account has a push cooldown of eight hours and you set observe_rate_limiting : true, if one of your campaigns sends a push message seven hours before you send the push request, your push request is rate-limited, so it is not sent.

The default is true; this push request might be rate-limited because of the push cooldown period.


Specifies a name for the campaign associated with this push request (a campaign label).

  • If the label does not already exist, the system creates a campaign, associates the label with the campaign, and adds the push requests to the new campaign.
    Important: The All Campaigns page in the Kahuna application lists this campaign created by the API, which looks unusual as it does not contain filters or segments. Do not disable this campaign from the All Campaigns page. If disabled, the Push API can no longer send push notifications, but still returns a 200 response code. In addition, you cannot reenable the campaign from the All Campaigns page.
  • If the label exists, the push requests are added to the campaign with that label.
  • This field is valid only within the default_config object. If you specify the field for an individual config, it is ignored.
  • If you do not specify a value, the value defaults to Web Service Push.

Specifies the number of seconds that the message delivery should be attempted, if the recipient is not immediately available to receive the message. The value of this parameter must be a duration from 0 to 2,419,200 seconds.

  • A ttl setting of 0 indicates that the message should be delivered immediately, or not at all.
  • A ttl setting of 3600 indicates that if the user is unavailable for more than 60 minutes after Kahuna delivers the message, the user will not receive the message.
  • Messages are considered delivered once the message is delivered to Apple or Google, whether or not the message is actually delivered to the recipient. The implementation and observance of the ttl option is delegated to Apple and Google.
  • iOS messages that do not specify a ttl option default to 7 days. (1 day for push messages sent via a campaign)
  • Android GCM and FCM messages that do not specify a ttl option default to 28 days.

An array of push objects, each of which identifies a user and the notification to send to that user. Each push object must contain a user specification and a notification message. The array size is limited to 100 objects; you can only submit 100 push objects per request. The format of a push object is:

target Required. The dictionary of user credentials in the following format:
"credential_type" : "credential_value"

The first user who matches a credential receives the notification. Custom credentials are not supported; if you specify a custom credential, the request fails.


Required. The contents of the notification sent to the target user. A notification sent to an iOS device can contain a badge setting. The contents of the notification field are:


If neither badge_set or badge_increment is specified, this field is required; otherwise, it is optional.

alert can be a string or a dictionary.

The string is the text message you want to display as a notification on a user's device. For example:

"alert" : "this is my notification text"

The dictionary contains the subfields title and body, where title is the title of the notification and body is the text message you want to display as a notification on a user's device. For example:

"alert" : {
    "body" : "this is my notification text",
    "title" : "this is the title of my notification"

The title subfield is supported for iOS 8.2 and Android.

  • If you specify alert, the value cannot be empty (length 0).
  • If you specify badge_set or badge_increment, and you do not want to show a notification, omit the alert field.
  • The length of the text payload of a push object is limited. The sum of the length of alert plus the lengths of each of the values in the params object must not exceed 500 bytes for iOS or 2048 bytes for Android.


For Android, this is a string that identifies the URL of the image you want to include in the push notification.

For iOS 10, this is a string that identifies the URL of the image, gif, or video you want to include in the push notification. The URL is passed to your app with the @"media_attachment" key.


Optional. This field lets you specify action buttons in your push notifications. The action field has two subfields:

action_identifier – For iOS 8 and above, this is a required string that contains the category identifier obtained when you register your iOS app's supported user interaction types so that you can use actionable buttons in your push notification. For Android, this is a string that contains any identifier you want to use to classify the Android action button grouping.

actions – Optional. A list of dictionaries, where each dictionary in the list is a single action button. The order in which you add the dictionaries is the order of the action buttons from left to right in the notification.

- button_title (required) is the title of the button displayed in the notification.

- button_identifier (required) identifies the action that the button takes when pressed.

- button_action (optional) is the URL or deep link URL. If you do not specify a button_action, your app opens when the user presses the button. If you implement your own custom push receiver, the Kahuna SDK does not perform any actions on the button_action URLs, and instead, forwards the intent to your push receiver. If there is no custom push receiver, the Kahuna SDK opens the URL provided in the button_action.


Optional. A number displayed as part of your app icon. In comparison, badge_increment increments the existing value.

  • badge_set must be greater than or equal to 0.
  • A value of 0 clears an existing badge.
  • badge_set only has an effect on iOS devices. Android devices still receive the push, display the notification in alert, and receive the params object, but the app icon is unaffected.

Optional. Increments the number currently displayed as part of your app icon. In comparison, badge_set sets a particular value for the number.

  • badge_increment cannot be 0. A value greater than 0 increments the badge value. A value less than 0 decrements the badge value.
  • badge_increment only has an effect on iOS devices. Android devices still receive the push, display the notification in alert, and receive the params object, but the app icon is unaffected.

Optional. A dictionary of key-value pairs that contain extra values to send to the user's device. The values are not displayed with the notification, but they are available to the mobile app associated with the namespace that originates the push request. The total length of the values is limited. See the restrictions listed for the notification field.


Optional. A dictionary of key-value pairs that control the push process. The allowed keys are listed in default_config, above.

   "default_params" : {
        "item_codes_on_sale" : [
        "sale_landing_page" : "sales_page_2015_09"
    "default_config" : {
        "start_time" : 1441231830,
        "optimal_hours" : 4,
        "influence_rate_limiting" : false,
        "observe_rate_limiting" : false,
        "campaign_name" : "New user campaign"
    "push_array" : [
            "target" : {
                "username" : "app_user_tester"
            "notification" : {
                "alert" : {
                    "body" : "Check this rich notification out!",
                    "title" : "New Message"
                "action" : {
                    "actions" : [
                            "button_title" : "Yes",
                            "button_action" : "",
                            "button_identifier" : "yes_button"
                            "button_title" : "No",
                            "button_identifier" : "no_button"
                    "action_identifier" : "yes_no_group_identifier"
                "media_attachment" : ""
            "params" : {
                "sale_landing_page" : "special_customer_sales_page"
            "config" : {
                "optimal_hours" : 2

API Response

The response to a Push API request consists of an HTTP response code and a response body.

HTTP Response Codes

The request was parsed and validated.

Note: This does not indicate that the individual push requests succeeded. For example, if you submit 100 push objects in a request and all 100 objects fail because their specified user is not found, you still receive a response code of 200. You must look at the success flag in each response object to determine the result of an individual push request.


Authentication failure. You did not specify authentication, you specified your credentials incorrectly, or authentication is denied.

409 Your credentials are not authorized to use the Push API.
500 Internal server error.
Response Body

The response body is an array of response objects that indicate the result of the push request contained in each push object. The only field that is present in all response objects is success. Depending on the value of the success field, the response object might contain other fields.

Response objects do not contain information that link them to push request objects. Instead, a response object has the same array index in the response body as the push request object has in the request body. The Logs API for Push provides detailed logs for push notifications, including both the notifications you generate with the Push API and the notifications the system generates automatically. The response object format is described below.


Indicates the result of the push request contained in the corresponding push object. A value of true indicates that the request is a success. A value of false indicates that an error occurred. Other fields in the object indicate the nature of the error.


A short description of an error that occurred while processing an individual push object. For example, Unknown User Credential indicates that the credential specified in the push object does not match any users. This field might be present if success is false. The field is never present if success is true.


A numeric error code for an error that occurred during push object processing. The field might be present if success is false. The field is never present if success is true. The possible error codes are:

  • 404: User not found—the credentials provided in the push object fail to match any users.
  • 409: User not enabled for Push—although the specified credentials match a user, the user or the user device is disabled for push notifications.

A message that provides additional information about the error described in the error field.


The following JSON snippets show an invalid push request object and its corresponding response object.

In this request object, the value of alert is empty, which is a violation of the restrictions for alert.

   "target": {
        "username": "bob"
   "notification": {

The invalid request object generates the following response object.

  "success": false,
  "error": "The request could not be parsed",
  >"error_code": 400,
  "error_detail": "push_array[1]: Alert is empty, {\"notification\": {\"alert\": \"\"}, \"target\": {\"username\": \"bob\" }}"
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request