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

    Parameters

    Parameters list

    Basic parameters

    IdDescription
    nameString - Min. 3 chars - Required
    Readable name of the campaign.
    E.g.{"name":"My Engagement Campaign"}
    liveBoolean - 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}
    labelsArray of Strings - Optional
    An array containing the label codes you want to attach to your campaign. You can use labels to filter the list of campaigns that appears on Batch's dashboard and manage global capping: make sure that you fill the "code" field when setting them up.
    E.g.{"labels":["label1","label2"]}

    Message options

    IdDescription
    priorityString - Optional
    Defines the priority of your message on iOS (APNS) and Android (GCM).
    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-sentitive.
    E.g.{"priority":"normal"}
    time_to_liveInteger - Optional
    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.
    A time_to_live of zero results in attempting to deliver the notification once, and will discard it if the device was offline. Negative values are invalid.
    Default values depend on the platform, but as of April 21, 2017, the default values are four weeks for Android, and unlimited for iOS.
    E.g.{"time_to_live":3600}
    gcm_collapse_keyObject - Optional - Android only
    Defines how notifications are managed when an offline device goes online (enabled by default).
    If enabled, the device will only show the most recent notification. If disabled, it will show all the notifications received when the device was offline. You should disable the collapse key if all your notifications matter (E.g. messages, etc). You can use up to 3 different collapse keys if you want users to get only one notification of each kind when coming online (E.g. marketing messages, alert, etc).
    E.g.{"enabled":true,"key":"default"}

    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.

    IdDescription
    push_timeString - 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_timeString - 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"}
    recurrenceObject - Optional
    An object containing parameters to define the recurrency of the campaign.
    end_dateString - 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_unitInteger - Sets the unit of how often the campaign will recur. Acceptable values include: DAILY, WEEKLY, and MONTHLY.
    E.g.{"repeat_unit":"WEEKLY"}
    repeat_frequencyInteger - Sets the frequency of campaign repetition. Uses the above repeat_unit parameter to determine units.
    E.g.{"repeat_frequency":2}
    cappingInteger - Optional
    The maximum number of time a given user can receive the campaign
    E.g.{"capping":1}

    User targeting

    IdDescription
    targetingObject - Optional
    An object containing the targeting property of the campaign. If omitted, all users will be targeted.
    languagesArray 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 all valid language codes.
    E.g.{"languages":["it","fr"]}
    regionsArray 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"]}
    segmentsArray 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"]}
    queryObject - 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_audiencesArray of Strings - An array containing all the custom audiences that should be targeted.

    Message editions

    IdDescription
    messagesArray of Objects - Required
    An object containing the messages to be delivered for each device language targeted in the targeting object. 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\u00e9fi du jour commence dans 5 minutes !"}]
    languageString - Required. Language of this message.
    E.g.{"language":"en"}
    titleString - Optional (except for web push). Title of the push notification. On iOS, the title will only appear on the Apple Watch or in the notification center (since iOS 8).
    E.g.{"title":"Don't give up!"}
    bodyString - Required. Body text of the push notification.
    E.g.{"body":"Just keep training, you'll get better."}
    mediaObject - Optional
    An object containing an icon, a picture, an audio or a video file's URL.
    E.g.{"media":{"icon":"http://mydomain.com/icon.png","picture":"http://mydomain.com/pic.png"}}
    iconString - Android / Windows 10 - URL of the icon file. The file must be a PNG or JPG image, with a minimum width of 192px.
    pictureString - iOS 10+ / Android / Windows 10 - URL of the picture file. The file must be a PNG or JPG image with a minimum width and height of 300px.
    Note: On iOS, make sure your server complies to App Transport Security or that you’ve added the appropriate exceptions in your app and app extension. Here is how a push with an image attachement looks: Example.
    audioString - iOS 10+ - URL of the audio file. The file must be a MP3 file hosted on an HTTPS server that responds to HEAD requests. It must not be larger than 10MB. Here is how a push with an audio attachement looks: Example.
    videoString - iOS 10+ - URL of the video file. The file must be a MPEG-4 file hosted on an HTTPS server that responds to HEAD requests. It must not be larger than 30MB. Here is how a push with a video attachement looks: Example.
    deeplinkString - Max. 255 chars - Optional
    A URL that points to a specific part of your app (i.e. The news you mention in your notification, etc). The deeplink URL is usually be 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. If you decide to use an external URL in your campaign, Batch won't show the open rate.
    custom_payloadString - must be valid JSON - Optional (only available on paid plans)
    A JSON string containing additional parameters that your application can handle when receiving push notifications if configured to do so. The only forbidden key is com.batch. Format is: {"x":"y"}

    Landing message

    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.

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

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

    The action object

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

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

    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 to Pro and Enterprise users 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.

    IdDescription
    b.os_versionString -
    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_versionString -
    Your app version. The expected format is X.Y.Z.
    E.g.{"b.app_version":"2.A.3"}
    b.device_typeString -
    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 PlayStore is available here. Make sure you choose a value in the model column.
    E.g.{"b.device_type":"iPhone8,1"}
    b.carrier_codeInteger -
    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_idBoolean -
    True if the user posesses a Custom User ID in our Userbase.
    E.g.{"b.has_custom_id":true}
    b.transaction_trackedBoolean -
    True if a transaction have been detected from the user.
    E.g.{"b.transaction_tracked":true}
    b.city_codeInteger -
    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}

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

    Please note that the Imported segment won't be selected if you target users based on custom user data (attributes, tags or events).

    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": "Elon Musk announces the ITS",
              "body": "Elon Musk unveiled the biggest rocket ever designed for its Mars spaceship",
              "actions": [
                {
                  "label": "Show",
                  "action": "show_article",
                  "args": {
                    "id": "1054",
                    "category": "high_tech"
                  }
                }
              ]
            }
          ]
        },
        "b": {
          "theme": "light-theme",
          "tracking_id": "article_1054",
          "contents": [
            {
              "language": "en",
              "header": "Latest news",
              "title": "SpaceX's ITS announcement by Elon Musk",
              "body": "Elon Musk unveiled the biggest rocket ever designed for its Mars spaceship",
              "actions": [
                {
                  "label": "Show",
                  "action": "show_article",
                  "args": {
                    "id": "1054",
                    "category": "high_tech"
                  }
                }
              ]
            }
          ]
        }
      }
    }
    

    Note
    Custom Payloads are not A/B testable. Also, A/B Testing is only available starting from the Pro 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://batch-doc.s3.amazonaws.com/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.