POST - Create campaign

The Push Campaigns API is made for 1-to-many interactions. It allows you to send notifications to a large audience of users. You can use it to target all your userbase or a specific segment of users relying on Batch segmentation (see more here).

You can use the Push Campaigns API to send generic/optional notifications. Here are a few examples:

• Medias: Breaking news, interest based notifications, etc.
• E-commerce: Flash sales, abandoned cart reminder, etc.
• Fitness: Workout reminders, subscription offers, etc.

Request structure

The create endpoint allows you to create push campaigns and target all your userbase, your own segments (attributes, events) or to segments generated by Batch (country/language, dormant users, app version, etc).

Route

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

Here are examples of valid cURL, PHP or Python requests syntax:

curl -X POST "https://api.batch.com/1.1/BATCH_API_KEY/campaigns/create" \
-H "Content-Type: application/json" \
-H "X-Authorization: BATCH_REST_API_KEY" \
-d '{
	"name": "Test Campaign",
	"live": true,
	"push_time": "now",
	"messages": [{
		"language": "en",
		"body": "Hello!"
	}]
}'

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

The API key changes push behaviour:

• Dev API: Only apps built with the Dev API Key will receive notifications.
• Live API: Depending on the targeting you set for your campaigns, apps built with the Live API key will receive notifications. Apps built with the Dev API key will receive all the notifications you send.

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.

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.

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.

Post data

The body of the request must contain a valid JSON payload with all the parameters you chose to add for your campaign: campaign name, schedule, recurrency, targeting, messages and more.

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

{
  "name": "Test Campaign",
  "push_time": "now",
  "live": true,
  "messages": [
    {
      "language": "en",
      "title": "Hello!",
      "body": "How's it going?"
    }
  ]
}

REQUIRED >
Check out the list of available parameters to create your first push campaign with the API.

Responses

Success

If the POST to the API endpoint is successfull you will receive an HTTP 201 confirmation and a token:

{ "campaign_token": "a0082dc6860938a26280bd3ba927303b" }

Once you get your token, you can use it to update your campaign or check the stats with the API.

If you don't receive the notification after a successful POST, make sure your app is not opened in the foreground (iOS) and check again your integration.

Failure

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

• AUTHENTICATION_INVALID (Http status code: 401, Error code: 10)
• API_MISUSE (Http status code: 403, Error code: 12)
• ROUTE_NOT_FOUND (Http status code: 404, Error code: 20)
• MISSING_PARAMETER (Http status code: 400, Error code: 30)
• MALFORMED_PARAMETER (Http status code: 400, Error code: 31)
• MALFORMED_JSON_BODY (Http status code: 400, Error code: 32)
• SERVER_ERROR (Http status code: 500, Error code: 1)
• MAINTENANCE_ERROR (Http status code: 503, Error code: 2)
• TOO_MANY_REQUESTS (Http status code: 429, Error code: 60)
  If you get a "too many requests" response, please wait for at least 5 seconds before trying again. Further requests might still return this error.