Parameters

Parameters list

Basic parameters

Id	Description
name	String - Min. 3 chars - Required Readable name of the campaign. E.g.{"name":"My Engagement Campaign"}
live	Boolean - Required Value that sets the campaign to live. A false value will save the campaign as a draft but not activate it E.g.{"live":true}
labels	Array of Strings - Optional - Max. 3 labels 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. E.g.{"labels":["label1","label2"]}

Message options

Id	Description
priority	String - Optional Defines the priority of your message on iOS (APNS) and Android (FCM) . Default value on iOS and Android is high. Acceptable values include: normal or high . 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. Switch to Normal priority if your notifications are not time-sensitive. Note: On iOS, if you set 'push_type' to 'background', this value is ignored and set to 'normal'. E.g.{"priority":"normal"}
time_to_live	Integer - Optional Android/Web 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. A time_to_live of zero results in attempting to deliver the notification once, and will discard it if the device was offline. 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 messages 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"}

Timing and delivery

There are two timezone parameters to choose from: local_push_time and push_time. One of the two timezone parameters must be included.

Id	Description
push_time	String - Required - Conflicts with local_push_time Time that Batch servers will start sending push notifications GMT (UTC+0000). Format is yyyy-MM-ddTHH:mm:ss or now to activate and send the campaign immediately. E.g.{"push_time":"2015-12-01T14:25:00"}
local_push_time	String - Required - Conflicts with push_time A value that defines the campaign send time in terms of the user's device. Batch servers will send push notifications at the selected time for each time zone. The campaign will take 24 hours to complete if users exist in all time zones (only for the Live API key). Format is yyyy-MM-ddTHH:mm:ss E.g.{"local_push_time":"2015-12-01T14:25:00"}
recurrence	Object - Optional An object containing parameters to define the recurrency of the campaign. end_date String - Time that the recurring campaign will stop sending. Format is yyyy-MM-ddTHH:mm:ss . Optional E.g.{"end_date":"2015-12-03T14:25:00"} repeat_unit String - Sets the unit of how often the campaign will recur. Acceptable values include: DAILY , WEEKLY , and MONTHLY . E.g.{"repeat_unit":"WEEKLY"} repeat_frequency Integer - Sets the frequency of campaign repetition. Uses the above repeat_unit parameter to determine units. E.g.{"repeat_frequency":2}
capping	Integer - Optional The maximum number of time a given user can receive the campaign E.g.{"capping":1}

User targeting

Id

Description

targeting

Object - Optional An object containing the targeting property of the campaign. If omitted, all users will be targeted. languages Array of Strings - An array containing all device languages to be targeted. All language codes in this array must be contained in the messages object. See here for matching rules and valid language codes. E.g.{"languages":["it","fr"]} regions Array of Strings - An array containing all the geographical regions codes to be targeted. See here for all valid region codes. E.g.{"regions":["FR","US"]} segments Array of Strings - An array containing the smart segments to be targeted. Acceptable values include: NEW , ONE_TIME , ENGAGED , DORMANT and IMPORTED . If you ommit this field or pass [], all users, included imported ones, will be targeted. E.g.{"segments":["ENGAGED","NEW"]} query Object - A mongo inspired query object containing filters & operators, based on native attributes (app version, OS version, etc) and custom users data (attributes, tags & events defined by you in the SDK) . custom_audiences Array of Strings - An array containing all the custom audiences that should be targeted.

Message editions

Id	Description
messages	Array of Objects - Required, disallowed when push_type is 'background' An object containing the messages to be delivered for each device language targeted in the targeting object. See here for message localization rules and valid language codes. The title and body of your notification can contain emojis. E.g.[{"language":"en","body":"Today's challenge starts in 5 minutes!"},{"language":"fr","body":"Le défi du jour commence dans 5 minutes !"}] language String - Optional Language of this message. If null or missing, this message will be for the application's default language. E.g.{"language":"en"} title String - Optional (except for web push) - Supports message personalization 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!"} body String - Required - Supports message personalization Body text of the push notification. E.g.{"body":"Just keep training, you'll get better."} deeplink String - Max. 255 chars - Optional - 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 based on a URL scheme that you specify within your app, but can be a relative one if you decide to read it manually. If you decide to use an external URL in your campaign, Batch won't show the open rate. Messages without a deeplink (explicitely set to null or omitted) will inherit the campaign-level one, if set. If deeplinks are set both at message-level and campaign-level, the former will take priority over the later. media Object - Optional Please see the media object bellow. Messages without media (explicitely set to null or omitted) will inherit the campaign-level one(s), if set. If medias are set both at message-level and campaign-level, the former will take priority over the later.
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 / Web - URL of the icon file. The file must be a PNG or JPG square image, at least 192px side. picture String - Supports message personalization iOS 10+ / Android / Windows 10 / Web - URL of the picture file. The file must be a PNG or JPG image with a minimum width and height of 300px. 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. 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. 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.
deeplink	String - Max. 255 chars - 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 based on a URL scheme that you specify within your app, but can be a relative one if you decide to read it manually. If you decide to use an external URL in your campaign, Batch won't show the open rate. Deeplinks can also be set on each message of the campaign.
custom_payload	String - must be valid JSON - 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 message

On iOS and Android, you have the ability to add a landing message to your push campaign. This will display a landing view using the theme and content of your choosing, allowing you to have complex interactions following a push notification.

The landing message is defined under the landing key at the root of the payload and the following fields are allowed. landing conflicts with deeplink.

Id	Description
theme	String - Required The code of the theme to use for your landing view E.g.{"theme":"dark_base_theme"}
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"}
tracking_id	String - Optional A tracking ID that you will receive in your application if set E.g.{"tracking_id":"OPEA20161005"}
contents	Array of Objects - Required The contents of the landing message. Per language messages can be defined. See here for message localization rules and valid language codes. language String - Required The language of the message E.g.{"language":"en"} 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"} image_description String - Optional The description of the image used for accessibility purposes E.g.{"image_description":"Boeing 747"} 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 a valid example:

{
  "name": "Airport Information",
  "live": false,
  "push_time": "now",
  "messages": [
    {
    "language": "fr",
    "title": "Bienvenue à l'aéroport Charles de Gaulle",
    "body": "Boutiques, restaurants, zones de relaxation, correspondances vers Paris... Retrouvez toutes les informations utiles !"
  },
  {
    "language": "en",
    "title": "Welcome to Charles de Gaulle Airport!",
    "body": "Shops, restaurants, relaxation areas, transfers to Paris city center\u2026 See our practical information!"
  }],
  "landing": {
    "theme": "MODAL-WITH-IMAGE",
    "image": "https://batch-flights.com/img/airport.jpg",
    "tracking_id": "welcome message",
    "contents": [
      {
      "language": "en",
      "header": "Welcome",
      "title": "Find your way in Charles de Gaulle airport",
      "body": "Shops, transfers, restaurants: Everything you need to know about Paris' airport.",
      "image_description": "Airport",
      "actions": [{
        "action": "batch.deeplink",
        "label": "Know More",
        "args": {
          "l": "https://batch-flights.com/en/travelguide"
        }
      }, {
        "action": "batch.dismiss",
        "label": "Later"
      }]
    },
    {
      "language": "fr",
      "header": "Bienvenue",
      "title": "Votre passage à Charles de Gaulle",
      "body": "Retrouvez toutes les informations utiles pour faire votre check-in et attendre votre avion en toute tranquilité.",
      "image_description": "Aéroport",
      "actions": [{
        "action": "batch.deeplink",
        "label": "Consulter le guide",
        "args": {
          "l": "https://batch-flights.com/fr/guidevoyageur"
        }
      }, {
        "action": "batch.dismiss",
        "label": "Plus tard"
      }]
    }]
  }
}

The query object

For advanced usage, you can pass a query object to the targeting. This is a homemade syntax, inspired by MongoDB. This feature is available on paid plans for native and custom attributes.

Native attributes

Native attributes allow you to target users based on their OS and app version, their device type or the number of days since they installed your app.

Native attributes must be added in query, as a targeting property.

Id	Description
b.os_version	String - The Android or iOS version.The expected format is X.Y.Z. The OS version cannot contain any letter. E.g.{"b.os_version":"5.1.1"}
b.app_version	String - Your app version. The expected format is X.Y.Z. E.g.{"b.app_version":"2.A.3"}
b.device_type	String - The device type / model. The full list of Apple model names is available here and a list of all the Android devices supported by the Play Store is available here . Make sure you choose a value in the model column. E.g.{"b.device_type":"iPhone8,1"}
b.carrier_code	Integer - Your user's carrier. The code provided by Batch is a combination of the Mobile country code (MCC) and the Mobile network code (MNC) . The full list of MCC and MNC codes is available here . E.g.{"b.carrier_code":20815}
age(b.install_date)	Duration - Number of days elapsed since the install (install: the first time Batch SDK sees the user) . The days are counted in sections of 24 hours from the hour of install. E.g.{"age(b.install_date)":1}
age(b.last_visit_date)	Duration - Number of days elapsed since your users' last session. The days are counted in sections of 24 hours from the last session. E.g.{"age(b.install_date)":1}
b.has_custom_id	Boolean - True if the user posesses a Custom User ID in our Userbase. E.g.{"b.has_custom_id":true}
b.transaction_tracked	Boolean - True if a transaction have been detected from the user. E.g.{"b.transaction_tracked":true}
b.city_code	Integer - You user's city detected by Batch using IP geolocation. E.g.{"b.city_code":2988507}
age(b.last_push_date)	Duration - Number of days elapsed since the last time you sent your user a push via the dashboard or the Campaigns API. E.g.{"age(b.last_push_date)":2}
isNear(int latitude, int longitude, string radius, duration time)	Boolean - True if the last collected user's location is within the given radius around the coordinates during the last X hours. Batch SDK must be allowed to collect geolocation to enable this query. E.g.{"isNear(48.8407578796295,2.351546582031233,5000m,12h)":true}
b.is_push_optin	Boolean - True if the install is opt-in to push, meaning that it can receive and display push notifications. E.g.{"b.is_push_optin":false}
b.os_model	String - Web push only The OS model as indicated by the browser’s User-Agent. E.g.{"b.os_model":"Windows"}
b.browser_model	String - Web push only The browser model as indicated by the browser’s User-Agent. E.g.{"b.browser_model":"Chrome"}
b.device_category	String - Web push only Allows you to target users depending on their device category (as indicated by the browser's User-Agent): mobile or desktop. Note: Tablets belong to the mobile category. E.g.{"b.device_category":"mobile"}

By default, a Duration object is an Integer that represents a number of days. This object can be in any other time unit if it is given a String with the value and the unit. For instance "12h" represents a number of hours. E.g.{"age(b.last_push_date)": “12h”}

Instead of age(), you can also use date() on date attributes. This function will return a UTC timestamp Integer.

RECOMMENDED: Users coming from an older version of your app and upgrading to a version with Batch's SDK (after a first release or a token import) are considered as new installs. If you are planning to use this attribute to send 1-3-7 days post-install notifications, we recommend that you wait at least 7 days to make sure you only target your new users.

Custom user data

You can send custom user data from your app (iOS / Android) or using the Custom Data API.

Attributes

Custom attributes are prefixed with c. or u. if they are sent from the Custom Data API, and are simple key/value data. You can use them to collect a:

• String

• Number / Decimal

• Boolean

• Date

Tags collections

Tags are prefixed with t. or ut. if they are sent from the Custom Data API, and are sets of tags.

Events

Events are prefixed with e. and have a key, an occurence date, an optional label, and an optional data object.

Recommended Take a look at this guide to know more on custom data and learn how to tag your app.

Operators

• $eq Equal to. This is the default and thus can be ommited.

• $lt Lower than <

• $lte Lower or equal than <=

• $gt Greater than >

• $gte Greater or equal than >

• $contains Checks if the tag collection has one of the requested tag

• $containsAll Checks if the tag collection has all of the requested tag

Basic examples

Send a push to all users who live in Paris :

{
  "targeting": {
    "query": {
      "c.city": {
        "$eq": "Paris"
      }
    }
  }
}

As explained above, $eq is the default so we can ommit it:

{
  "targeting": {
    "query": {
      "c.city": "Paris"
    }
  }
}

All users with app version 1.0.1

{
  "targeting": {
    "query": {
      "b.app_version": {
        "$gte": "1.0.1"
      }
    }
  }
}

Users who installed your app 1 day ago and use an iPhone 6.

{
  "targeting": {
    "query": {
      "$and": [
        {
          "age(b.install_date)": 1
        },
        {
          "b.device_type": {
            "$gt": "iPhone7,2"
          }
        }
      ]
    }
  }
}

When you need multiple conditions, the first level of your query needs to be an $and, with an array of conditions.

Functions and advanced example

Date attribute needs a function to be queried; that's why we showed you age(b.install_date) before.

We plan to introduce more functions to our API to enable events querying in the upcoming weeks.

From now on, we will only show the query. Just remember it goes in targeting.query.

Users intersted by Rugby or Football, who installed in the last 10 days, and subscribed to your paid offer.

{
  "$and": [
    {
      "t.interest": {
        "$contains": [
          "Rugby",
          "Football"
        ]
      }
    },
    {
      "age(b.install_date)": {
        "$lte": 10
      }
    },
    {
      "c.paidSubscriber": true
    }
  ]
}

Users who installed your app since at least 10 days, living in Paris, at least Android 5.0, using the version 3.1.1 of your app, and subscribed to both France & Sport push notifications

{
  "$and": [
    {
      "age(b.install_date)": {
        "$gte": 10
      }
    },
    {
      "c.city": "Paris"
    },
    {
      "b.os_version": {
        "$gte": "5.0"
      }
    },
    {
      "b.app_version": "3.1.1"
    },
    {
      "t.push_optin": {
        "$containsAll": [
          "France",
          "Sport"
        ]
      }
    }
  ]
}

Imported users: Push tokens stored in the "imported" segment (e.g. users who haven't updated to a version of your app containing Batch SDK), can only be segmented based on data provided in the initial import file.

A/B Testing

A/B tested marketing campaigns work a little bit differently than standard ones.

Messages

You will need to change what you put in the messages key. It should become an object, rather than an array.

In that object, you need to have have two keys: "a" and "b". You've guessed it, these are your A and B messages. Their content works exactly like messages does for standard campaigns: they're an array of messages objects, with all of your translations.

Here's a quick example of a A/B tested campaign, implying you still have all the other keys:

{
  "messages": {
    "a": [
      {
        "language": "en",
        "title": "Hello!",
        "body": "How is it going?"
      },
      {
        "language": "fr",
        "title": "Salut!",
        "body": "Ça va?"
      }
    ],
    "b": [
      {
        "language": "en",
        "title": "Hey!",
        "body": "How are you?"
      },
      {
        "language": "fr",
        "title": "Coucou!",
        "body": "Tu vas bien?"
      }
    ]
  }
}

Landing messages

Same as standard messages, you can A/B test your landing messages. To do that, you simply need to define two keys a and b under the landing key. Each key must contain a valid landing message object, as described above.

{
  "landing": {
    "a": {
      "theme": "dark-theme",
      "tracking_id": "article_1054",
      "contents": [
        {
          "language": "en",
          "header": "Latest news",
          "title": "ESA's Hera Mission files near Mars",
          "body": "The flyby is a significant milestone in Hera’s journey to the binary asteroid system Didymos",
          "actions": [
            {
              "label": "Show",
              "action": "show_article",
              "args": {
                "id": "1054",
                "category": "space"
              }
            }
          ]
        }
      ]
    },
    "b": {
      "theme": "light-theme",
      "tracking_id": "article_1054",
      "contents": [
        {
          "language": "en",
          "header": "Latest news",
          "title": "Hera flies by Mars",
          "body": "The flyby is a significant milestone in Hera’s journey to the binary asteroid system Didymos",
          "actions": [
            {
              "label": "Show",
              "action": "show_article",
              "args": {
                "id": "1054",
                "category": "space"
              }
            }
          ]
        }
      ]
    }
  }
}

Note Custom Payloads are not A/B testable. Also, A/B Testing is only available starting from the Developer plan.

cURL example

Here is an example of a valid cURL CLI request syntax:

curl -H "Content-Type: application/json" -H "X-Authorization: BATCH-PUSH-API-TOKEN" -X POST -d
"@payload.json" "https://api.batch.com/API_VERSION_NUMBER/BATCH_API_KEY/campaigns/create"

where payload.json:

{
  "name": "Test Campaign",
  "local_push_time": "2015-06-01T14:00:00",
  "live": true,
  "targeting": {
    "languages": [
      "it"
    ],
    "regions": [
      "FR",
      "US"
    ],
    "segments": [
      "ONE_TIME",
      "ENGAGED",
      "NEW"
    ],
    "query": {
      "age(b.install_date)": 1
    }
  },
  "messages": [
    {
      "language": "en",
      "title": "Hello!",
      "body": "How is it going?"
    },
    {
      "language": "fr",
      "title": "Salut!",
      "body": "Ça va?"
    }
  ],
  "recurrence": {
    "end_date": "2015-06-30T00:00:00",
    "repeat_unit": "DAILY",
    "repeat_frequency": 1
  },
  "capping": 1,
  "images": {
    "icon": "https://static.batch.com/documentation/logo_batch_192.png"
  },
  "custom_payload": "{\"tag\":\"wake up push\", \"landing_screen\":\"greeting\"}"
}

The above example will start a recurring campaign on June 1, 2015 at 14:00 (2PM), sending to users based on their device time.

• It is set as "live": true so will begin at the designated time, versus resting as a draft requiring further action before sending.

• The optional targeting object has been included to specify the device language, region, and targeted segments. If this object were not included, all users would be targeted. In this case, we used the native attribute age(b.install_date) to target users who installed the app one day ago.

• Within the messages object each targeted language has been given a message. It's worth noting two things here:

  • title is optional but recommended.

  • You must have a message object for the default language of your app, as set within the Batch dashboard.

• This campaign uses the recurrence optional object to have the campaign repeat every day at the originally defined time of 14:00 until June 6, 2015 at 00:00.

• The custom_payload here implies that the app being pushed to can handle a dictionary string of "tag" with a value of "wake up push" and "landing_screen" with "greeting". These are not required but can be added if desired.