POST - Send

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-sensitive notifications: Delivered order, delayed flight, canceled train, etc.

What changed with the CEP version of the API

The Transactional API now runs on Batch's Customer Engagement Platform (CEP). Same endpoint, same payload format: existing integrations keep working without any change on your side. What is no longer supported: message personalization (templating tags are not rendered and a URL containing one makes the notification skipped, see the note in Post Data), the advertising_ids recipients, the wp_template key (Windows), the landing object (mobile landings) for new integrations (existing landing themes keep working), and the Debug tool, which no longer lists transactional pushes. Analytics remain available through the Transactional Stats API and the Export API.

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"

There are two keys you will need to use when calling the API:

Key	Description
batch_rest_api_key	Your company REST API key. It identifies your account and 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.

You will find both keys in your dashboard settings:

Please note Batch manages each platform separately, so you will have to call the API twice with a different Dev/Live API key if you want to target iOS and Android. Supported platforms are iOS (APNS), Android (FCM) and Web push. Huawei, Windows Phone and Safari web push are not supported.

Insufficient privileges issue: You may see that error in the REST API key field. This happens because the REST API key is only visible to managers. Make sure the managers of the account share that key with you or ask them to grant you access through the team manager.

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.

Message personalization is not supported: templating tags (Jinja-style double curly braces) are not rendered. In text fields (title, body, custom_payload), the tags are removed from the final message. In URL fields (deeplink, media URLs), a URL containing a templating tag causes the notification to be skipped: it is not sent. Send the final values directly in your payload.

Let's see the parameters in detail.

Id	Description
group_id	String - Required Name of your campaign, useful for analytics purposes (see the Transactional Stats API) . 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"}
labels	Array of Strings - Optional - Max. 3 labels An array containing the label codes you want to attach to your notification. You can use labels to implement frequency capping: make sure that you create the labels before using them and that you fill the "CODE" field when setting them up. Labels are NOT supported for token recipients. E.g.{"labels":["label1","label2"]}
priority	String - Optional Defines the priority of your message on iOS (APNS) and Android (FCM) . 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_live	Integer - 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. There is no default value: ommitting this parameter will use default behaviours of the underlying services, which is often to store notifications for a while. The value must be greater than 0. Maximum: 28 days. E.g.{"time_to_live":3600}
gcm_collapse_key	Object - 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"}
push_type	String - Optional - Android/iOS. Default: 'alert' Defines whether notifications should show an alert or be silent to trigger a background action. Acceptable values are alert and background . Setting this to 'background' will disable the message and media keys: you will need to remove them from your call. iOS 13 will ignore silent notifications that don't define a background push_type, even though their custom payload defines a silent push. On iOS, {"aps":{"content-available":1}} will automatically be appended to the final payload to wake up the app in the background and the priority will be forced to `normal`. E.g.{"push_type":"alert"}
skip_media_check	Boolean - Optional Batch performs a HEAD request on your media URL to prevent you from sending invalid images, or ones too big. Checks include but are not limited to a valid Content-Type and Content-Length. If your server doesn't support this, you can disable these checks by setting this option to true. Acceptable values include: true or false. Default: false E.g.{"skip_media_check":"true"}
recipients	Object - 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. At least one of the three parameters must be included.
tokens	Array of strings - An array containing the push tokens to push. E.g.{"tokens":["USER_PUSH_TOKEN"]}
custom_ids	Array of strings - An array containing the custom user IDs to push. Custom user IDs are case and whitespace sensitive. Batch will select the 10 most recent installs with a token matching each custom user ID targeted in your call. E.g.{"custom_ids":["USER_CUSTOM_ID"]}
install_ids	Array 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"]}
message	Object - Required, conflicts with `messages`. Disallowed when push_type is `background` An object containing the message to be delivered. You can send the message in multiple languages by using the messages object described further below
title	String - Optional (except for web push) Title of the push notification. E.g.{"title":"Don't give up!"}
body	String - Required Body text of the push notification. E.g.{"body":"Just keep training, you'll get better"}
messages	Object - Required, conflicts with `message`. Disallowed when push_type is `background`. The `messages` object is a collection of messages in different languages. See more here .
media	Object - Optional - Disallowed when push_type is 'background' An object containing an icon, a picture, an audio or a video file's URL. Media URLs must not contain personalization tags: a notification whose media URL contains one is skipped and not sent. E.g.{"media":{"icon":"http://mydomain.com/icon.png","picture":"http://mydomain.com/pic.png"}}
deeplink	String - 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. The deeplink must not contain personalization tags: a notification whose deeplink contains one is skipped and not sent. E.g.{"deeplink":"recipe-app://recipes/desserts/peach-pie"}
sandbox	Boolean - Optional Flag specifying whether the APNS sandbox should be used. No effect for Android applications or Custom IDs. Default: false. E.g.{"sandbox":true}
custom_payload	String - 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. Some keys cannot be overriden and will be dropped. This includes com.batch on all platforms, but Android comes with additional forbidden keys due to FCM limitations . Format is {\"x\":\"y\"} .

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

{
	"group_id": "order_confirmed",
	"recipients": {
		"custom_ids": ["USER_ID"]
	},
	"message": {
		"title": "Your order is confirmed!",
		"body": "We will send you a shipping confirmation alert as soon as your order ships."
	}
}

Sending Localized Notifications

If you don't know your users' language, you can rely on Batch language detection and include localized versions of your message in your call to the Transactional API.

Batch will pick the appropriate version of the message for each user, based on the language detected by the SDK or the language your users selected in your app or on your website.

Here are the modifications you will need to make to add localized versions of your message:

Localizing the Notification

The messages object is a collection of messages in different languages. It conflicts with the message object and cannot be used with tokens recipients.

You will need to set a fallback version of your message. It will be sent to users whose language doesn't match any of the translated versions available. See here for more details about message localization rules.

Id	Description
messages	Object - Required, conflicts with message. Disallowed when push_type is background An array containing the messages to be delivered. One and only one message without language must be defined, which will be the fallback message. Messages are not supported for token recipients.
language	String - Optional Two letter language code as listed here . E.g.{"language":"en"}
title	String - Optional (except for web push) Title of the push notification. E.g.{"title":"Don't give up!"}
body	String - Required Body text of the push notification. E.g.{"body":"Just keep training, you'll get better"}

Here is a valid example. The first message will be sent to french speaking recipients, the second one to spanish speaking recipients. If none of the sent messages match the recipient's language, the last message will be used.

{
	"group_id": "order_confirmed",
	"recipients": {
		"custom_ids": ["USER_ID"]
	},
	"messages": [
		{
			"language": "fr",
			"title": "Votre commande est confirmée !",
			"body": "Nous vous enverrons une alerte dès qu'elle sera expédiée."
		},
		{
			"language": "es",
			"title": "¡Tu pedido está confirmado!",
			"body": "Te enviaremos una alerta cuando tu pedido sea enviado."
		},
		{
			"title": "Your order is confirmed!",
			"body": "We will send you a shipping confirmation alert as soon as your order ships."
		}
	]
}

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 identifies the transaction in your analytics and exports, 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 [e-mail] if you need further support.

• AUTHENTICATION_INVALID (Http status code: 401, Error code: 10)
• API_MISUSE (Http status code: 403, Error code: 12)
• 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)
• TOO_MANY_REQUESTS (Http status code: 429, Error code: 60) If you get a "too many requests" response, please wait for at least 5 seconds before trying again. Further requests might still return this error.

Analytics

Transactional push analytics are available through the Transactional Stats API (aggregated by group_id) and through the Export API (Transactional IDs and Transactional Events routes). The token returned by each successful call is included in the analytics data and lets you trace a given API call.

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, 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.
• 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.

If you are still having issues receiving notifications, please take a look at our troubleshooting sections.