• iOS
  • Android
  • Windows
  • Cordova
  • Web
  • Unity
  • Adobe Air
  • Dashboard
  • API
  • Guides
  • FAQ
  • Documentation > API

    Transactional API

    The Transactional API is made for 1-to-1 interactions. It allows you to push a specific user ID or to a group of IDs (device token, install ID or custom user ID).

    Use it to send action-oriented or time-sensitive push notifications.

    • Action-oriented notifications: New message, friend request, reached credit limit, user's turn in a game, etc.
    • Time-sentitive notifications: Delivered order, delayed flight, canceled train, etc.

    Request structure

    Route

    The Transactional API exposes a POST send endpoint: https://api.batch.com/1.1/BATCH_API_KEY/transactional/send.

    Here is a valid cURL example:

    curl -H "Content-Type: application/json" -H "X-Authorization: batch_rest_api_key" -X POST -d "@payload.json" "https://api.batch.com/1.1/batch_api_key/transactional/send"
    
    Key Description
    batch_rest_api_key Your company REST API key. It gives you access to our APIs. You can find it in ⚙ Settings → General.
    batch_api_key Your app's API key. It allows you to choose the app you want to push. Each app has a different API key. You can find it in ⚙ Settings → General.

    Headers

    In order to authenticate with the API, you need to provide your company REST API Key as the value of the X-Authorization header.

    Post data

    The body of the request must contain a valid JSON payload with all the parameters you chose to add: Targeting, recurrence and more.

    Let's see the parameters in detail.

    IdDescription
    group_idString - Required
    Name of your campaign, useful for analytics purposes (see Analytics → Notifications → Transactional). The group_id shouldn't be unique, it's a key to group your transactional push analytics.
    You can use the letters a-z, A-Z, the numbers 0-9, underscores and hyphens.
    E.g.{"group_id":"Welcome_campaign"}
    labelsArray of Strings - Optional
    An array containing the label codes you want to attach to your campaign. You can use labels to filter the list of campaigns that appears on Batch's dashboard and manage global capping: make sure that you fill the "code" field when setting them up. Labels are NOT supported for token recipients.
    E.g.{"labels":["label1","label2"]}
    priorityString - Optional
    Defines the priority of your message on iOS (APNS) and Android (GCM).
    Acceptable values include: normal or high.
    Default value on iOS is high. Default value on Android is normal.
    On Android, use the high priority if you have a messaging/voip app and if you notice delivery issues due to native (Doze) or constructor related (Samsung Smart Manager, etc) energy saving features. High priority Android notifications can drain your user's battery faster since they 'wake up' the device and open a network connection.
    E.g.{"priority":"high"}
    time_to_liveInteger - Optional - iOS / Android only
    Time, in seconds, after which the notification will be considered as invalid and should not be delivered after attempting to send it at least once, in any case.
    By default, all notifications are sent with a TTL of 14 days.
    A time_to_live of zero results in attempting to deliver the notification once, and will discard it if the device was offline. Negative values are invalid.
    E.g.{"time_to_live":3600}
    gcm_collapse_keyObject - Optional - Android only
    Defines how notifications are managed when an offline device goes online (enabled by default).
    If enabled, the device will only show the most recent notification. If disabled, it will show all the notifications received when the device was offline. You should disable the collapse key if all your notifications matter (E.g. messages, etc). You can use up to 3 different collapse keys if you want users to get only one notification of each kind when coming online (E.g. marketing messages, alert, etc).
    E.g.{"enabled":true,"key":"default"}
    recipientsObject - Required
    An object containing who you want to push, by tokens or Custom IDs.
    Supports up to 10,000 push tokens/custom IDs/Install IDs.
    One of the three parameters must be included.
    tokensArray of strings - An array containing the push tokens to push.
    E.g.{"tokens":["USER_PUSH_TOKEN"]}
    custom_idsArray of strings - An array containing the custom user IDs to push. Custom IDs are case and whitespace sensitive.
    E.g.{"custom_ids":["USER_CUSTOM_ID"]}
    install_idsArray of strings - An array containing the installation IDs to push. It should be the unmodified installation ID given by the SDK's user module.
    E.g.{"install_ids":["USER_INSTALL_ID"]}
    advertising_idsArray of strings - An array containing the advertising IDs to push, IDFA on iOS and GAID on Android. It should be the unmodified advertising ID collected from the device.
    E.g.{"advertising_ids":["USER_ADVERTISING_ID"]}
    messageObject - Required
    An object containing the message to be delivered.
    titleString - Optional (except for web push). Title of the push notification. On iOS, the title will only appear on the Apple Watch or in the notification center (since iOS 8).
    E.g.{"title":"Don't give up!"}
    bodyString - Required. Body text of the push notification.
    E.g.{"body":"Just keep training, you'll get better"}
    mediaObject - Optional
    An object containing an icon, a picture, an audio or a video file's URL.
    E.g.{"media":{"icon":"http://mydomain.com/icon.png","picture":"http://mydomain.com/pic.png"}}
    iconString - Android / Windows 10 - URL of the icon file. The file must be a PNG or JPG image, with a minimum width of 192px and must be hosted on an HTTPS server that responds to HEAD requests. It must not be larger than 5MB.
    pictureString - iOS 10+ / Android / Windows 10 - URL of the picture file. The file must be a PNG or JPG image with a minimum width and height of 300px. It must be hosted on an HTTPS server that correctly responds to HEAD requests and must not be larger than 5MB.
    Note: On iOS, make sure your server complies to App Transport Security or that you’ve added the appropriate exceptions in your app and app extension. Here is how a push with an image attachement looks: Example.
    audioString - iOS 10+ - URL of the audio file. The file must be a MP3 file hosted on an HTTPS server that responds to HEAD requests. It must not be larger than 10MB. Here is how a push with an audio attachement looks: Example.
    videoString - iOS 10+ - URL of the video file. The file must be a MPEG-4 file hosted on an HTTPS server that responds to HEAD requests. It must not be larger than 30MB. Here is how a push with a video attachement looks: Example.
    deeplinkString - Optional
    A URL that points to a specific part of your app (i.e. The news you mention in your notification, etc). The deeplink URL is usually a link based on a URL scheme that you specify within your app, but can be a relative one if you decide to read it manually.
    E.g.{"deeplink":"recipe-app://recipes/desserts/peach-pie"}
    sandboxBoolean - Optional
    Flag specifying whether the APNS sandbox should be used. No effect for Android applications or Custom IDs. Default: false.
    E.g.{"sandbox":true}
    wp_templateString - Optional
    Flag specifying what Windows Toast template should be used. Use "legacy" if you push Windows 8.1 or Windows Phone 8.1, "generic" for UWP (Windows 10). Default: "legacy".
    E.g.{"wp_template":"generic"}
    custom_payloadString - Optional (only available on paid plans)
    A JSON string that can contain additional parameters that your application can handle when receiving push notifications if configured to do so. The only forbidden key is com.batch.
    Format is {"x":"y"}.
    landingObject - Optional
    An object describing the landing message. This will display a landing view allowing you to have complex interactions following a push notification. The landing message object will be described further below

    Here is how a minimal and valid JSON payload looks like:

    {
        "group_id": "welcome",
        "recipients": {
            "tokens": ["USER_PUSH_TOKEN"]
        },
        "message": {
            "title": "Hello!",
            "body": "How's it going?"
        },
        "custom_payload": "{\"tag\":\"wake up push\", \"landing_screen\":\"greeting\"}"
    }
    

    The landing message object

    A landing message must have the following format.

    IdDescription
    themeString - Required
    The code of the theme to use for your landing view
    E.g.{"theme":"dark_base_theme"}
    imageString - Optional
    The url of the image to use if the theme contains one
    E.g.{"image":"https://d1v3v59tzaau1a.cloudfront.net/medias/img/landing-samples/fly.15569dd6.jpg"}
    image_descriptionString - Optional
    The description of the image used for accessibility purposes
    E.g.{"image_description":"Boeing 747"}
    tracking_idString - Optional
    A tracking ID that you will receive in your application if set
    E.g.{"tracking_id":"OPEA20161005"}
    headerString - Optional
    The text of the header
    E.g.{"header":"News"}
    titleString - Optional
    The text of the title
    E.g.{"title":"Update to the latest version!"}
    bodyString - Optional
    The text of the body
    E.g.{"body":"Lots of bug and security fixes"}
    actionsArray of objects - Required
    A list of actions available in the landing message. The action object will be described further below

    Note
    If your theme contains the close button, the actions array is not strictly required.

    The action object

    Each action in the landing message must be defined as follows.

    IdDescription
    actionString - Required
    The action name. Must match with the actions you register in your mobile application. Not strictly required, if null the close action will be used
    E.g.{"action":"show_article"}
    labelString - Required
    The label of the call to action
    E.g.{"label":"Show"}
    argsObject - Optional
    An object containing arbitrary data that will be passed to your action as is
    E.g.{"args":{"id":4,"category":"sports"}}

    Responses

    Success

    If the POST to the API endpoint is successful you will receive an HTTP 201 confirmation and a unique token representing the transaction.

    {"token":"110e8400-e29b-11d4-b543-446655440000"}
    

    Please keep this token: It will be useful to see the list of push tokens you targeted in the debug tool and it will also help in getting faster support.

    If you don't receive the notification after a successful POST, make sure your app is not opened in the foreground (iOS) and check again your integration.

    Failure

    If the POST data does not meet the API requirements you will receive an actionable error message. Contact us at support@batch.com if you need further support.

    • AUTHENTICATION_INVALID (Http status code: 401, Error code: 10)
    • ROUTE_NOT_FOUND (Http status code: 404, Error code: 20)
    • MISSING_PARAMETER (Http status code: 400, Error code: 30)
    • MALFORMED_PARAMETER (Http status code: 400, Error code: 31)
    • MALFORMED_JSON_BODY (Http status code: 400, Error code: 32)
    • SERVER_ERROR (Http status code: 500, Error code: 1)
    • MAINTENANCE_ERROR (Http status code: 503, Error code: 2)

    Debug

    Batch provides a simple debug tool that lets the list of all the targeted push tokens for any given API call. Go to ⚙️ Settings → Debug and input the token generated by the API on each successful call:

    Transactional Debug

    Troubleshooting

    Can I do a single API request for both iOS and Android?

    Batch manages iOS and Android notifications separately to take advantage of the features that each OS has (e.g. silent push notifications, GCM collapse key, etc). This is why you will need to call the Transactional API once per OS.

    Our APIs are asynchronous and respond very fast. Batch will send a push notification, provided that a valid device token is tied to the custom user ID you are targeting. However, if the custom user ID does not exist for the app you targeted, the call will fail silently.

    My device doesn't seem to receive any notifications

    Here are some suggestions in case your device doesn't receive any notifications:

    • Invalid token: Make sure the device token you are targeting is still valid using the Debug tool (iOS / Android).
    • Wrong environment: On iOS, try adding {"sandbox":true} to your json payload.
    • Invalid custom user ID: Make sure the custom user ID (iOS / Android) was registered by Batch for the OS you are targeting using the Debug tool (iOS / Android).

    If you are still having issues receiving notifications, please take a look at our troubleshooting sections (iOS / Android).