1 of 100

API & SDK Documentation

Developer Portal

Welcome to Batch's developer portal!

Here, you’ll find everything you need to integrate with Batch—whether you’re working on the client side using our SDKs, or on the server side with our APIs.

Our resources include high-level usage guides, sample code, and detailed API references to help you get started quickly.

Customer Engagement Platform APIs

Batch’s Customer Engagement Platform APIs give you server-side access to our new, profile-oriented data model—making it easy to manage and act on user data at scale.

SDKs

Batch's SDKs bring our features to your app in a developer-friendly API.

What is an SDK?

"SDK" stands for Software Development Kit.

An SDK is a set of tools developers can use to create apps for a specific platform or to add features to their apps without having to redevelop them from scratch. Apps usually integrate a wide variety of third-party analytics and marketing SDKs.

Here is a non-exhaustive list of the purposes the SDK serves:

Analytics: registers new installs, sends app usage data and feedback on push and In-App interactions (e.g. push displayed, opened, In-App message dismissed, etc).
Data collection: collects and sends Profile data (attributes, events) to Batch servers to improve your segmentation and personalization.
Push notifications: collects and sends the push token to Batch servers, required to deliver a push to your users' devices. On Android, the receiver included in the SDK is in charge of receiving and displaying the notifications.
In-App messaging: pulls the list of In-app campaigns matching your users' install from Batch servers and displays the In-app messages.

Available SDKs and Plugins

SDK Downloads

Most SDKs and Plugins are not to be downloaded directly but integrated by using a package manager: the ones Batch support and how to use the SDK with them is detailed in the "SDK Integration" pages.

You can also find us on where you will find our SDKs & Plugins source code and sample apps you can use to test our features with.

Mobile Engagement Platform APIs

API

API - Customer Engagement Platform

Projects and Profiles

Before we begin, we would like to talk about two paradigms:

Projects group Android/iOS apps, Websites and all channels leveraged together in a single entity. Projects have their own identifier for use with our new project-level APIs (called the Project key).

Data used to be siloed between different apps: projects remove that limitation by introducting profiles.

Profiles centralize data and events from multiple sources (Apps, Websites, APIs) in a single place based on the Custom user ID. They can also store a profile's email, phone number, etc. and email, SMS, etc. subscriptions. This allows Batch to support more complex and cross-channel lifecycles: it is now possible to message a user on a channel even though its profile data is fed from another one.

For example, this use case is now supported:

A user creates an account from your Android app. You use the Android SDK to set a and add .
You collect their email and use the Profile API to tell Batch about it.
This user then logs in on your website, which sets the Custom User ID.
The user performs some action on your website, which you send to Batch using the

You will now be able to create an email, SMS etc. automation or campaign, which automatically uses the data from the app, website and profile API and reacts to both events the user did on your website and tracked by your backend thanks to the Custom User ID.

Using Project APIs

Prerequisites

Before sending your first call to our API, make sure you have:

Your REST API key.
Your Project Key.

You will find these IDs in your project settings, on Batch dashboard (⚙️ Settings → General). Please note you need to be the manager of the account to see the REST API key.

Please make sure that you keep your REST API key secret: it is sensitive and should not be shared in any form. You should never use it in client apps to call APIs from there as it would easily be extractable. Our support team will never ask for your REST API key.

Request headers and authentication

Three headers are required to use the API:

Content-Type must be set to application/json.
The REST API key should be in the Authorization header, prefixed by Bearer . Example: Authorization: Bearer EC3DBFXPZ67RTCDEF. If you are logging your requests, you should exclude this header from the logs.

Example:

Note: You will find cURL examples for the API endpoints in the documentation pages, by clicking on "Test it"

Rate Limiting

To ensure fair usage and platform stability, all CEP API endpoints are subject to rate limiting.

Unless specified otherwise, APIs are subject to a rate limit of 1 request per second per project key.

Some APIs like Profile update and Edit catalog items have custom rate limits. In those cases, the limits are documented both on the root page of this API's documentation and on their specific endpoints.

If either threshold is exceeded, the API will respond with an HTTP 429 Too Many Requests error. You are expected to handle those responses appropriately. When that happens, slow down your requests or reduce the batch size (when applicable) to comply with the limit.

Differences with v1 APIs

APIs on the 2.0 and higher endpoints work differently than the previous APIs:

The REST API key does not use X-Authorization anymore, but the standard Authorization header
The Project key is in a HTTP header rather than in the route
The 2.x APIs are not RESTful by design: endpoints are structured differently and will use GET/POST methods only

OpenAPI Spec

The OpenAPI Spec .

Profiles

Profiles centralize data and events from multiple sources (apps, websites, APIs) in a single place based on the Custom ID.

The Profiles API allows you to update profiles and create exports requests for Profile data.

Profile updates: choosing the right API endpoint

Two endpoints are available for profiles update, each optimized for distinct use cases.

Mass update profile

Profiles centralize data and events from multiple sources (Apps, Websites, APIs) in a single place based on the Custom ID.

Use /profiles/mass-update for large-scale periodic imports. Learn more about selecting the right endpoint here: .

API Description

Audiences

Audiences APIs allow brands to Create, Update, Replace, Remove, List and View Audiences.

Audiences are lists of Custom User IDs, Emails, or Install IDs that can be used for targeting with Batch Platform, when performing Campaigns and Automations.

Audiences can also be associated with attributes that can be used for personalization purposes (more information here).

Create Update Replace Remove List

Update

See create to see an introduction about Audience API.

API Description

Request structure

Route

The Audience API exposes a POST endpoint that allows to add or delete users from an audience:

/audiences/update

Headers and authentication

See .

Post data

The body of the request must contain a valid JSON payload describing the operations to be executed on the audience.

Here is a how a complete JSON payload looks like:

NOTE: If multiple actions are given for the same ID, only the last one will be taken into account.

Responses

Success

If the PATCH to the API endpoint is successful you will receive an HTTP 202 confirmation and a token.

Once you get your token, you can use it to of this update with the API.

Failure

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

Processing time

While the indexation of IDs is usually done in real time, we offer no guarantees. If you send a campaign right after the audience creation, you might end up with a campaign targeting nobody. A call to the view action with the indexing token replies with an APPLIED indexing state if the processing is finished (and IN_PROCESS if it is still ongoing).

Replace

See to see an introduction about Audience API.

API Description

Request structure

Remove

See to see an introduction about Audience API.

API Description

Request structure

View

See create to see an introduction about Audience API.

API Description

Request structure

Route

The Audience API exposes a GET endpoint that allows to get information about a audience :

/audiences/view

Headers and authentication

See .

Query parameters

See the API Description.

Responses

Success

If the GET to the API endpoint is successful you will receive an HTTP 200 confirmation and information about your audience.

The indexing state is the indexing state of the update that returned the given indexing token. If there is no indexing token provided, the state of the last update will be used. 3 values are possible for indexing state

IN_PROGRESS : update processing is in progress
APPLIED : update processing is finished
REPLACED : the audience content has been replaced since the issue of the indexing token.

Failure

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

See the list of potential failures in the API Description.

Campaigns

Campaigns API is designed for broad audience interactions, allowing you to send messages to large groups of users. You can target either your entire user base or specific segments using Batch's segmentation features.

This API supports the creation, updating, and deletion of campaigns, giving you full control over your messaging strategies.

Delete campaign

It allows the deletion of a campaign.

API Description

Request structure

Catalogs

Catalogs API allow brands to Create, Update, Remove, List, View and Edit catalog items, making it easy to maintain up-to-date content—like products, events, or offers—that can be dynamically injected into your campaigns or automations.

Rate Limiting

To ensure fair usage and platform stability, all Catalog API endpoints are subject to rate limiting.

General Catalog API rate limit

All Catalog API endpoints (including Create,

Create catalog

Use /catalogs/create to create a new catalog. You are allowed to create up to 5 catalogs per project.

Request structure

Route

The Catalog API exposes a POST endpoint that allows to create an audience:

/catalogs/create

You will be allowed to create up to 5 catalogs for a project. A catalog can have up to 25 fields.

Headers and authentication

See .

Post data

The body of the request must contain a valid JSON payload describing the operations to be executed on the catalog.

Here is a how a complete JSON payload looks like:

Responses

Success

If the call to the API endpoint is successful you will receive an HTTP 201 confirmation.

Failure

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

Update catalog

Use /catalogs/update to update an existing catalog.

Request structure

Route

The Catalog API exposes a POST endpoint that allows to update an existing catalog:

/catalogs/update

A catalog can have up to 25 fields.

Headers and authentication

See .

Post data

The body of the request must contain a valid JSON payload describing the operations to be executed on the catalog.

Here is a how a complete JSON payload looks like:

Responses

Success

If the call to the API endpoint is successful you will receive an HTTP 202 confirmation.

Failure

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

Remove catalog

Use /catalogs/remove to remove an existing catalog.

Request structure

Route

The Catalog API exposes a POST endpoint that allows to remove an existing catalog:

/catalogs/remove

Headers and authentication

See .

Post data

The body of the request must contain a valid JSON payload describing the operations to be executed on the catalog.

Here is a how a complete JSON payload looks like:

Responses

Success

If the call to the API endpoint is successful you will receive an HTTP 202 confirmation.

Failure

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

View catalog

Use /catalogs/view to view an existing catalog.

Request structure

Route

List catalogs

Use /catalogs/list to list existing catalogs.

Request structure

Route

The Catalog API exposes a GET endpoint that allows to list catalogs :

/catalogs/list

Headers and authentication

See .

Query parameters

See API Description.

Responses

Success

If the GET to the API endpoint is successful you will receive an HTTP 200 confirmation and information about your catalogs.

Pagination infos:

next_from can be used for the next call to list to retrieve the next page
count is only returned for the first page

Failure

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

See the list of potential failures in the API Description.

Exports

If you want to export your entire profile based or segments, the export request has to be done via the Profiles API, see this section to know more: .

The Exports API allows you to list exports requested, view them and finally retrieve export files.

Download export file

The export API allows you to download files extracted by your export request.

API Description

Route

The Project Export API exposes a GET endpoint that allows to download result files:

Orchestrations

Orchestrations is the word we use to encompass Campaigns and Automations. This API allows the retrieval of:

the listing of all orchestrations you manage with Batch, using a GET list request,
the performance metrics of all orchestrations you manage with Batch, using a GET stats request.

Transactional

Campaigns

POST - Delete campaign

The delete endpoint allows you to remove a campaign using its token number.

Request structure

Route

The campaigns API exposes a POST endpoint at: https://api.batch.com/1.1/BATCH_API_KEY/campaigns/delete/CAMPAIGN_TOKEN

In-app Campaigns

POST - Delete In-App campaign

The delete endpoint allows you to remove an In-App campaign using its token number.

Request structure

Route

The In-App campaigns API exposes a POST endpoint at: https://api.batch.com/1.1/BATCH_API_KEY/in-app-campaigns/delete/CAMPAIGN_TOKEN

Custom Audience

v1.0

DELETE - Remove

The Custom Audience API 1.0 only accepts custom user IDs and avertising IDs. For audiences with install IDs, the version 1.1 should be used.

The Custom Audience API enables you to create, update, delete and list custom audiences. A custom audience can contain a list of custom user IDs or advertising IDs (GAID or IDFA).

This is useful to target segments with push notifications or In-App messages, either they are coming from your userbase or created by third-party tools.

Custom audiences created using the API can be targeted from Batch’s dashboard or the Campaigns API.

Request structure

Route

The Custom Audience API exposes a DELETE endpoint that allows to delete a custom audience :

https://api.batch.com/1.0/BATCH_API_KEY/custom-audience/AUDIENCE_NAME

Here is a valid cURL example:

The AUDIENCE_NAME value is the name of the existing audience you want this operation to be applied to.

NOTE: If the deleted custom audience is already used as a campaign targeting, Batch will consider it as an empty custom audience.

The BATCH_API_KEY value is either your Live, Dev or SDK Batch API key from the settings page of your app within the dashboard (⚙ 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. You can find it in ⚙ Settings → General.

Responses

Success

If the call to the API endpoint is successful you will receive an HTTP 200 confirmation.

Failure

If the POST data does not meet the API requirements you will receive an actionable error message. Contact us at 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)

GET - View

The Custom Audience API 1.0 only accepts custom user IDs and avertising IDs. For audiences with install IDs, the version 1.1 should be used.

The Custom Audience API enables you to create, update, delete and list custom audiences. A custom audience can contain a list of custom user IDs, advertising IDs (GAID or IDFA) or install IDs.

This is useful to target segments with push notifications or In-App messages, either they are coming from your userbase or created by third-party tools.

Custom audiences created using the API can be targeted from Batch’s dashboard or the .

Request structure

v1.1 (install ids only)

DELETE - Remove

The Custom Audience API 1.1 only accepts install IDs for the moment. For audiences with custom user IDs or advertising IDs, the version 1.0 should be used.

The Custom Audience API enables you to create, update, delete and list custom audiences. A custom audience can contain a list of custom user IDs, advertising IDs (GAID or IDFA) or install IDs.

This is useful to target segments with push notifications or In-App messages, either they are coming from your userbase or created by third-party tools.

Custom audiences created using the API can be targeted from Batch’s dashboard or the .

NOTE: Custom Audiences with install IDs are only supported from the 1.1 version of the Custom Audience API. Also note that this version doesn't support custom user IDs and advertising IDs for the moment.

GET - View

The Custom Audience API 1.1 only accepts install IDs for the moment. For audiences with custom user IDs or advertising IDs, the version 1.0 should be used.

The Custom Audience API enables you to create, update, delete and list custom audiences. A custom audience can contain a list of custom user IDs, advertising IDs (GAID or IDFA) or install IDs.

This is useful to target segments with push notifications or In-App messages, either they are coming from your userbase or created by third-party tools.

Custom audiences created using the API can be targeted from Batch’s dashboard or the Campaigns API.

Custom Data

App Data

DELETE - Remove

The App Data API enables you to create, update, delete and list data you associated to your application. App Data lets you create tables of key/value pairs. It is for application centric data as opposed to user centric data. You can use the data in your targeting queries and/or in a message template.

Request structure

Route

The App Data API exposes a DELETE endpoint that allows to delete a table:

https://api.batch.com/1.0/BATCH_API_KEY/app-data/TABLE_NAME

Here is a valid cURL example:

The TABLE_NAME value must be a string that only contains letters, numbers or the following characters: _, -.

NOTE: Make sure before deletion that this App Data table is not used by any campaign.

The BATCH_API_KEY value is either your Live, Dev or SDK Batch API key from the settings page of your app within the dashboard (⚙ 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. You can find it in ⚙ Settings → General.

Responses

Success

If the call to the API endpoint is successful you will receive an HTTP 200 confirmation and an empty json payload.

Failure

If the POST data does not meet the API requirements you will receive an actionable error message. Contact us at 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)

PATCH - Update

Request structure

GDPR

Export

GET - Get request info

The Export API allows you to create export requests and get their status. This page documents the request endpoint.

Request structure

Route

GET - Get all requests

The Export API allows you to create export requests and get their status. This page documents the requests endpoint.

Request structure

Route

The Export API exposes a GET endpoint to get last requests created and their status:

https://api.batch.com/1.0/BATCH_API_KEY/export/requests

Here is a valid cURL example:

The BATCH_API_KEY value is either your Live, Dev or SDK Batch API key from the settings page of your app within the dashboard (⚙ 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.

Responses

Success

If the GET to the API endpoint is successful you will receive an HTTP 200 confirmation and information about last Export requests.

This information is an array of all requests we currently know of for your application. The output contains requests created in the last 4 months (sorted desc and limited to ~1000) Each object in the array contains exactly the same information as you would get if you made a with the request id.

Failure

Same as GET request

Trigger Events

sdk

iOS

Prerequisites

Creating an app

Let's get going!

The very first step is to go to and create a new iOS app.

SDK Integration

Profile Data

Inbox

Inbox is an optional feature. If you are interested, please contact us.

The Inbox API allows you to fetch and process notifications that this user has previously received, even if their device was offline. You can then do anything you want with the data, such as making a "notification center", where the user can catch up with previous notifications in a list.

The API gives you access to the entire notification, including its raw payload. It also lets you know if the notification has already been read, and allows you to mark one or all notifications as such. Once received/stored in the inbox, your push notifications will remain for a 3 months period.

This screenshot is an example of what you can achieve with the Inbox API. Please note Batch does not include any UI.

Picking the Right Fetcher

Installation Mode

This mode will fetch notifications from the current app installation, and nothing else. If the user clears the app's data, this inbox will be cleared. This is great for applications where your users don't have to log in.

In this mode, you can simply get the Inbox Fetcher with a context:

Note: This may cause privacy issues if your app has an identification system. Users sharing the same device and using different accounts in your app would be able to see the push history of previous users.

Custom User ID Mode

This mode will fetch notifications for the specified , even if they just installed the application and already got notifications on another device logged in with the same user identifier. If your application has a login system, this is the mode you should use.

Since notifications can have sensitive content, you cannot get a user's notifications simply with their user identifier: Batch requires you to authenticate your request.

Getting Your Authentication Key

First, you will need your inbox secret key. You will find that in your dashboard, below your API Keys. It is unique for every app.

The authentication key is generated by computing a sha256 hmac hash of the API Key concatenated with the user identifier, using the secret as the key. Then, you have to encode the hash in a hexadecimal string.

For the API Key "abcdef", user identifier "paul" and secret of "foobar", the string to hash is abcdefpaul and the expected authentication key would be 796f1ab5d119d1b2eab8201e60335b56d1befff40c0f80263d64a169a8fd2e45.

PHP example code:

Note: This hash HAS to be computed on your server. If you bundle the inbox secret in your application to compute the hash, attackers will be able to extract it, and read the notifications of any of your users

Getting the Fetcher Instance

Once you've got the authentication key from the server, you only have to give Batch the right user identifier and auth key tuple to get the Inbox Fetcher:

Fetching Notifications

Now that you've got your fetcher instance, it's time to fetch notifications, and display them!

The inbox fetcher has several important methods and properties:

allFetchedNotifications This returns a copy of all the notifications that have been fetched. Useful for a list adapter. Warning: Calling this always makes a copy of the objects, so you should cache that method's result.
fetchNewNotifications() Allows you to fetch notifications that might have been received after the initial fetch. This is useful for implementing a refresh feature. This will erase the notification history returned by allFetchedNotifications to ensure consistency: you should clear the other notification pages you've already from your cache.

Note: BatchInboxFetcher and its methods are well documented in BatchInbox.h. You can also use the of BatchInboxFetcher to get detailed explanations about what every method does.

BatchInboxFetcher will not fetch any notification by default, so before trying to display anything, you will need to call fetchNewNotifications() or fetchNextPage()

Both fetch methods take a block, which the SDK will call you back on either on failure, or success. Success callbacks include information about the operation to operate on the data, but you can very well do with the global methods. The block callbacks are always called on the main thread.

Reading Notification Content

Once you've fetched notifications, you will end up with a list of BatchInboxNotificationContent objects.

These objects have everything you need to display these notifications:

Title
Body
Send timestamp (UTC)
Read state

Note: Just like when you get it using iOS' standard callbacks, the raw payload (accessible from the payload property) should be used carefully on keys you do not control:

"aps" is considered private by Apple, and can change at any time. This has happened in the past, where the "alert" object got additional keys for new iOS features.
"com.batch" is Batch's internal payload: You should not make any assumption about its content, nor depend on it. We reserve the right to change it at anytime, without warning.
Standard parsing good practices apply: Make sure to check every cast and handle errors gracefully, and never assume anything about the payload's content.

You can then use the same methods that you can use on push payloads to extract information. Example: BatchPush.deeplink(fromUserInfo: notificationContent.payload), where "notificationContent" is a BatchInboxNotificationContent instance.

Marking Notifications as Read

Notifications can be marked as read in two ways:

By marking only one notification as read Use markNotification(asRead: notification) with the notification you want to mark as read.
By marking all notifications as read Simply call markAllNotificationsAsRead()

In both cases, the notifications will be marked as read locally, but refreshing them might mark them as unread again, as the server might not have processed the request. These methods return quickly, and are thus safe to call on your UI thread.

Note that notifications that have been opened when received are automatically marked as read.

Displaying Mobile Landing

Batch allows you to display a mobile landing attached to a notification. To do so, you can simply trigger the landing message from the BatchInboxNotificationContent object as following:

Marking Notifications as Deleted

Notifications can be deleted using the markNotification(asDeleted: notification) method with the notification you want to mark as deleted. A deleted notification will NOT appear in the notification list the SDK provides, and you will be expected to update your UI accordingly.

The notifications will be marked as deleted locally, but refreshing them might make them appear again, as the server might not have processed the request. These methods return quickly, and are thus safe to call on your UI thread.

Tweaking the Fetcher

For more advanced usages, you can also change various aspects of the Inbox Fetcher, such as:

The maximum number of notifications fetched per page (maxPageSize)
The maximum number of notifications that can be fetched using this object (limit) A default limit is set to avoid going over memory by accident.
1.19.0 Disabling the filtering of silent notifications (filterSilentNotifications). A silent notification is a push that doesn't show any visible message to the user.

Testing Your Integration

In order to test your integration, you will need to create a push campaign on the dashboard. Please see our fore more info.

Webhooks

Webhooks feature allows you to get a real-time stream of events sent to your HTTPS endpoint. Webhooks alert you about events that have just occurred - for instance, a user displayed an In-App campaign, or subscribed to push notifications.

Combined with our Export API, they are often used to:

Orchestrate multi-channel communications
Keep your user profile data in sync with Batch related events

Webhooks is a paid option and will be setup with the help of your Solutions Engineer. Please contact us if you are interested.

Overview

HTTPS requests sent to the endpoint by Batch:

will use the POST method/verb.
will contain a JSON data payload (Content-Type: application/json).
will be identified with User agent (User-Agent: Batch.com/1.0).

Requirements

Endpoint must use HTTPS (valid SSL certificate issued by a recognized authority).
Response time should be under 100 milliseconds (ms) and endpoint must be localized in the EU area.
Response body won't be handled by Batch. We are only expecting an HTTP 200 or 201 status code.
Endpoint should be able to deduplicate events based on their ID if uniqueness is required.

Authentication

Secret key

In order to authenticate with your endpoint, Batch will provide your Webhook Secret as the value of the X-Authorization header.

OAuth2

Alternatively, if your endpoint supports an OAuth2 authentication, the header will pass the OAuth2 Access Token under the standard Authorization header:

You'll have to provide Batch with the full URL of your authorization endpoint, and a set of grant_type, client_id and client_secret credentials.

Retries

If your endpoint fails to return a 200 or 201 status code Batch will retry periodically using an exponential backoff.

Your endpoint might be disabled if we receive too many errors over a long period: if that happens a manual intervention is required to enable the endpoint.

Batching

Batch supports delivering more than one event in a single HTTP request. This is useful to increase the delivery throughput and reduce the load on your endpoints.

Batching can be configured with the following properties:

max size which is the maximum number of events that should be in a batch. A batch is guaranteed to never have more than this number of events however it can have less events.
max wait time which is the maximum amount of time to wait before the batch is sent regardless of its size.

For example if batching is enabled with a max size of 10 and a max wait time of 5s the following will happen:

the batch is sent as soon as 10 events are generated
the batch is sent after 5s even if less than 10 events are generated

Batching is disabled by default. If you decide to enable it you can choose values in the following ranges:

max size must be between 10 and 1000.
max wait time must be between 1s and 30s.

If you don't choose values Batch will use default values:

max size of 100.
max wait time of 5s.

Data payload

The body of the request will contain a valid JSON payload describing a message and a single event (or a batch of events).

Here is how a complete JSON payload for a single event looks like:

A batch of events is composed of a number of single events in an array. The format of each event is the same as the example above.

Here is how a complete JSON payload for a batch of events looks like:

Test events

When configuring your Webhook endpoint Batch can send test events which can help you test and validate your code.

The payload will have the same format as a normal event, other than its event_type which will always be prefixed with test_.

All data in a test event will be randomly generated so take care not to save it.

Event types

push_campaign_sent

Event generated for every Push notification sent in a campaign.

push_campaign_open

Event generated for every Push notification opened in a campaign.

push_campaign_undelivered

Event generated for every Push notification not delivered in a campaign.

Reasons:

uninstalled : installation's push token has been unregistered
error : an error has been returned by the push API (see error code)
capping_limit : installation has reached a capping rule

push_transactional_sent

Event generated for every Push notification sent in a Transactional API request.

push_transactional_open

Event generated for every Push notification opened in a Transactional API request.

push_transactional_undelivered

Event generated for every Push notification not delivered in a Transactional API request.

Reasons:

not_found : no installation could be found for the supplied ID
unreachable : no push token could be found for the supplied ID
uninstalled : installation's push token has been unregistered

in_app_campaign_displayed

Event generated for every In-app message displayed in a campaign.

in_app_campaign_clicked

Event generated for every In-app message clicked in a campaign.

in_app_campaign_closed

Event generated for every In-app message closed in a campaign.

push_reachability_change

Event generated whenever an installation's reachability status change (eg: opt-in, opt-out, uninstall the app etc.).

Properties:

is_reachable : installation has a push token
is_optin : installation enabled Push notifications for the app
has_custom_id : installation is linked to a user profile

Mobile landings

Mobile Landings allow you to easily introduce continuity between your app, and your pushes: A user opening a push will be greeted by a rich message related to what they opened, rather than just ending up on your app's main menu.

They're included in the Startup, Business and Enterprise plans.

Displaying the message

Automatic mode

There's no code required to make mobile landings work in automatic mode: just attach a landing to your push campaign, and Batch will display it.

You might want to go further into this documentation, and setup your delegate, or head to the documentation to add custom behaviour to buttons.

Manual mode

You may want to be in control of if, when and how landings will be loaded and displayed. Batch allows you to disable automatic displaying, and handle loading and displaying the view controller itself.

First, you'll need to implement UNUserNotificationCenterDelegate in a class (for more information, please see the part):

Then, you have to disable the automatic mode and set your class as your default UNUserNotificationCenter delegate:

Finally, you need to ask Batch to load the right view controller for the push payload (if applicable), and display it:

Controlling the display using "Do Not Disturb mode"

"Do Not Disturb" (DnD) feature: It allows you to tell Batch to hold on a mobile landing for you, rather than display it without using the fully manual mode. For example, if launching your app results in a splash screen or a fullscreen ad, you might find it undesirable to have Batch display something on top of it.

Turning on "Do Not Disturb" mode will make Batch enqueue the latest mobile landing, rather than display it.

Toggling DnD

Now, when you don't want Batch to automatically display, turn on Do Not Disturb:

Once you want to start showing landings automatically, call the method with false to turn it off.

Note: Disabling Do Not Disturb mode does NOT make Batch show the enqueued message

Displaying pending mobile landings

After coming back from DnD mode, you might want to show the enqueued message, as Batch will not do that automatically. Batch exposes two properties/methods for managing the queue:

BatchMessaging.hasPendingMessage , allowing you to peek into the queue.
BatchMessaging.popPendingMessage() , allowing you to fetch the pending message (if any). Since calling this makes Batch delete its reference to it to save memory, further calls might return nil.
BatchMessaging.showPendingMessage() , allowing you to try to show the pending message, if any.

Here is a quick example of how they can be used:

Note: Only the latest message is queued: if a mobile landing arrives while one is still pending, it will overwrite the previous one.

Listening to lifecycle events and reacting to button actions

Setting up a delegate

Batch's messaging module supports setting up a delegate, which can be used for analytics:

It can be any object that implements the BatchMessagingDelegate protocol.

While your application delegate can safely implement this protocol, we split it out in a separate class in our examples for simplicity.

Like most delegates on iOS, Batch only stores a weak reference to it. Make sure you keep a reference to your object instance so it isn't released

Analytics delegate

Batch can notify your delegate of lifecycle events of the in-app messages:

The messageIdentifier variable is the message tracking identifier you've configured in the dashboard. It can be nil if you didn't specify one.

Custom button actions

In order to be able to use the "Custom" button action kind, you need to implement them using the Batch Actions module. More info here:

Customizing the landing

Setting a custom font

If you'd like to use a custom font instead of the system's, Batch allows you to override the fonts it will use:

The size will be overriden later, so you can use anything you want. Make sure you provide both a normal and a bold font, even if they are the same.

This assumes you've already got custom UIFonts working. If you don't, you can find a great tutorial .

Troubleshooting

Nothing happens when I press an actionable button

Take a look at your application logs in Xcode, the SDK might try to warn you about an issue. Here are some the common messages and their probable cause:

Deeplinks on iOS are automatically called by the SDK using sharedApplication's openURL method. Since it needs a NSURL instance, the deeplink string needs to be a valid URL accepted by iOS' NSURL class. Please try again with a valid URL.

Note: Use of universal links in deeplinks is discouraged: triggering an universal link from the app implementing them will cause iOS to open safari.

This can happen when you specified a custom action when creating the campaign on the dashboard, but the SDK couldn't execute it.

Make sure you always register your actions at every app start.

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:

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

Key

Description

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.

Description

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

The Landing Message Object

Description

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.

Description

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 : / .

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

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. for more details about message localization rules.

Description

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.

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. for more details about message localization rules.

Here is a valid example:

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.

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

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.
Wrong environment: On iOS, try adding {"sandbox":true} to your json payload.
Invalid custom user ID: Make sure the custom user ID ( / ) was registered by Batch for the OS you are targeting using the Debug tool.

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

Export profile data

Profiles centralize data and events from multiple sources (Apps, Websites, APIs) in a single place based on the Custom ID.

The Profiles API allows you to export profiles data. Use this endpoint to:

Export profile native attributes
Export profile custom attributes
Export profile identifiers
Export profile events

API Description

Lookback

Some kind of exports are logs of detailed events that happened. Those raw events are not kept forever and will stop being available to export after a while: this is documented in the "Lookback" duration for each event kind. Providing a from parameter older than the lookback period will result in an error.

Exports that represent a snapshot of data (such as Profile Attributes) do not have this limitation.

Route

The Profile API exposes a POST endpoint that allows to create an export request:

/profiles/export

Headers and authentication

See .

Profile Attributes

Use this to export custom and native attributes as well as the identifiers of your profiles.

Request structure

The body of the request must contain a valid JSON payload describing the export request to be executed.

Here is a how a complete JSON payload looks like:

You must specify at least one of attributes, identifiers or both in your export request.

The filter parameter is optional. Currently, you can only filter by segment. Specify the segment by providing the segment code* you want to use for this export.

*The segment code is available in two places within the Dashboard on the Segments page:

Either via the "Copy segment code" option in the dropdown menu.
Or by clicking the copy icon on the right-hand side of the modal for the specific segment.

Rate limiting with filter parameter

Please note: when the filter parameter is being passed, we apply a rate limiting of 5 requests per hour (1 new request authorised every 12 minutes), with a maximum authorised burst of 10 requests.

Export file structure

The export will contain a list of attributes. Each attribute is composed of an attribute object and an identifiers object.

Field

Description

Type

Required

Attribute Object

Representation of an attribute object.

Field

Description

Type

Required

Identifiers object

Represents the identifiers of the profile concerned by the event.

Field

Description

Type

Required

Export file sample

This is a sample of the content of the export file you will receive.

Example

Profile Events

Use this to export events associated with your profiles.

Lookback

90 days

Request structure

The body of the request must contain a valid JSON payload describing the export request to be executed.

Here is a how a complete JSON payload looks like:

Export file structure

This export will contain a list of events with it fields and an identifiers object.

Event fields

Field

Description

Type

Required

Identifiers object

Represents the identifiers of the profile concerned by the event.

Field

Description

Type

Required

Event type

Exhaustive list of type for the event.

email_sent: Triggered when the email is sent.
email_delivered: Triggered when the email is successfully accepted by the recipient's email server.
email_open: Triggered when the recipient opens the email.

Export file sample

This is a sample of the content of the export file you will receive.

Example

Profile Reachability Events

Use this to export the reachability events of your profiles.

Lookback

Reachability events are available since October 10, 2024. No events are available prior to this date. Lookback period will be 90 days.

Request structure

The body of the request must contain a valid JSON payload describing the export request to be executed.

Here is a how a complete JSON payload looks like:

Export file structure

The export will contain a list of reachability events. Each event is composed of an event object and an identifiers object.

Field

Description

Type

Required

Event Object

Representation of an reachability event object. It also describes a part of the profile state at the time of the event.

Field

Description

Type

Required

Identifiers object

Represents the identifiers of the profile concerned by the event.

Field

Description

Type

Required

Event reasons

Exhaustive list of reasons for the event.

SUBSCRIBED_TO_SMS_MARKETING: The profile subscribed to SMS marketing.
UNSUBSCRIBED_FROM_SMS_MARKETING: The profile unsubscribed from SMS marketing.
PHONE_NUMBER_ADDED: The profile added a phone number.

Export file sample

This is a sample of the content of the export file you will receive.

Example

Responses

Success

If the POST to the API endpoint is successful you will receive an HTTP 202 confirmation and an export ID. This ID can be used to get status information about your export request using the endpoints.

Failure

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

See the list of potential failures in the API Description.