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.

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.

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.

Let's see the parameters in detail.

Id	Description
group_id	String - 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"}
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"]}
	advertising_ids	Array 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. Batch will select the 10 most recent installs with a token matching each advertising ID targeted in your call. E.g.{"advertising_ids":["USER_ADVERTISING_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) - Supports message personalization Title of the push notification. E.g.{"title":"Don't give up!"}
	body	String - Required - Supports message personalization 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. E.g.{"media":{"icon":"http://mydomain.com/icon.png","picture":"http://mydomain.com/pic.png"}}
	icon	String - Supports message personalization Android / Windows 10 - URL of the icon file. The file must be a PNG or JPG square image, at least 192px side and must be hosted on an HTTPS server that responds to HEAD requests. It must not be larger than 5MB.
	picture	String - Supports message personalization 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 200px. 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 attachment looks: Example .
	audio	String - Supports message personalization 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 attachment looks: Example .
	video	String - Supports message personalization 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 attachment looks: Example .
deeplink	String - Optional, conflicts with 'landing' - Supports message personalization 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"}
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}
wp_template	String - 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_payload	String - Optional (only available on paid plans) - Supports message personalization 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\"} .
landing	Object - Optional An object describing the landing message. This will display a landing view allowing you to have complex interactions following a push notification. You will find more information here .

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."
	}
}

The Landing Message Object

A landing message must have the following format:

Id	Description
theme	String - Required The code of the theme to use for your landing view E.g.{"theme":"dark_base_theme"}
webview_url	String - Optional The URL to load in the Webview. Does nothing on non webview themes. E.g.{"webview_url":"https://batch.com"}
image	String - Optional - Supports message personalization 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_description	String - Optional The description of the image used for accessibility purposes E.g.{"image_description":"Boeing 747"}
tracking_id	String - Optional A tracking ID that you will receive in your application if set E.g.{"tracking_id":"OPEA20161005"}
header	String - Optional - Supports message personalization The text of the header E.g.{"header":"News"}
title	String - Optional - Supports message personalization The text of the title E.g.{"title":"Update to the latest version!"}
body	String - Optional - Supports message personalization The text of the body E.g.{"body":"Lots of bug and security fixes"}
actions	Array 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.

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

Id	Description
action	String - 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"}
label	String - Required The label of the call to action E.g.{"label":"Show"}
args	Object - Optional An object containing arbitrary data that will be passed to your action as is E.g.{"args":{"id":4,"category":"sports"}}

Important note: You will find here a list of all the built-in actions you can use in your Mobile Landing to dismiss the In-App message, use a deeplink, and more : iOS / Android.

Here is how a valid JSON payload looks like with a Mobile Landing:

{
	"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."
	},
	"landing": {
		"theme": "MODAL-WITH-IMAGE",
		"image": "https://batch-store.com/img/sunglasses.jpg",
		"tracking_id": "order confirmation",
		"image_description": "Item preview",
		"header": "Thank you!",
		"title": "Your order has been confirmed!",
		"body": "Check the status of your order now or keep shopping.",
		"actions": [
      {
				"action": "batch.deeplink",
				"label": "Check Status",
				"args": {
					"l": "https://batch-store.com/order-status"
				}
			},
			{
				"action": "batch.dismiss",
				"label": "Later"
			}
		]
	}
}

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 (see more here).

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) - Supports message personalization Title of the push notification. E.g.{"title":"Don't give up!"}
	body	String - Required - Supports message personalization 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."
		}
	]
}

Localizing the Mobile Landing

You can also localize the content of the Mobile Landing attached to your push notification.

contents is an array of objects. Use it in the landing object. You will also need to set a fallback version of your message that 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.

Here is a valid example:

{
	"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."
		}
	],
	"landing": {
		"theme": "MODAL-WITH-IMAGE",
		"image": "https://batch-store.com/img/sunglasses.jpg",
		"tracking_id": "order confirmation",
		"contents": [{
				"language": "fr",
				"header": "Merci !",
				"title": "Votre commande est confirmée",
				"body": "Vérifiez le statut de votre commande ou continuez vos achats.",
				"image_description": "Aperçu article",
				"actions": [{
						"action": "batch.deeplink",
						"label": "Vérifier le statut",
						"args": {
							"l": "https://batch-store.com/order-status"
						}
					},
					{
						"action": "batch.dismiss",
						"label": "Plus tard"
					}
				]
			},
			{
				"language": "es",
				"header": "¡Gracias!",
				"title": "Tu pedido está confirmado",
				"body": "Revisa el estado de tu pedido o sigue comprando.",
				"image_description": "Vista previa del artículo",
				"actions": [{
						"action": "batch.deeplink",
						"label": "Revisar el estado",
						"args": {
							"l": "https://batch-store.com/order-status"
						}
					},
					{
						"action": "batch.dismiss",
						"label": "Más tarde"
					}
				]
			},
			{
				"header": "Thank you!",
				"title": "Your order has been confirmed!",
				"body": "Check the status of your order now or keep shopping.",
				"image_description": "Item preview",
				"actions": [{
						"action": "batch.deeplink",
						"label": "Check Status",
						"args": {
							"l": "https://batch-store.com/order-status"
						}
					},
					{
						"action": "batch.dismiss",
						"label": "Later"
					}
				]
			}
		]
	}
}

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

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:

The advanced analytics view gives you detailed information for a specific transactional push:

• SENT: The total amount of sent push notifications.
• NOT FOUND: Number of Custom User ID or installation ID are not linked to any push token.
• UNDELIVERABLE: Number of push tokens that were flagged as invalid by Apple/Google. Your app may have been uninstalled.
• ERRORS: Number of APNS/FCM/WNS errors.

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 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).