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

    POST - Create In-App campaign

    The In-App API is made for creating, reviewing, listing, updating and deleting In-App campaigns. If you are not familiar with this type of campaign yet, check our latest guide.

    The structure of this API is very similar to the Campaigns API. Before sending your first campaign, you have to create at least one theme on the In-App theme editor and retrieve its code.

    Request structure

    The create endpoint allows you to create In-App campaigns and reach all your userbase, opt-in to notifications or not. You can also use native and custom attributes as well as Custom Audiences for your targeting.

    Route

    The in-app campaigns API exposes a POST create endpoint at: https://api.batch.com/1.1/BATCH_API_KEY/in-app-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/in-app-campaigns/create" \
    -H "Content-Type: application/json" \
    -H "X-Authorization: BATCH_REST_API_KEY" \
    -d '{
      "name": "Test Campaign",
      "local_start_date": "2017-06-01T14:00:00",
      "live": true,
      "trigger": {
        "capping": 1,
        "when": "NEXT_SESSION"
      },
      "landing": {
        "theme": "HELLO-THEME",
        "image": "https://batch-doc.s3.amazonaws.com/logo_batch_192.png",
        "contents": [
          {
            "language": "en",
            "header": "Welcome",
            "title": "Hello!",
            "body": "How is it going?",
            "actions": [
              {
                "label": "Continue",
                "action": "continue"
              }
            ]
          }
        ]
      }
    }'
    use GuzzleHttp\Client;
    $client = new Client();
    $response = $client->request("POST", "https://api.batch.com/1.1/BATCH_API_KEY/in-app-campaigns/create", [
        "headers" => [
            "Content-Type" => "application/json",
            "X-Authorization" => "BATCH_REST_API_KEY"
        ],
        "json" => [
          "name" => "Test Campaign",
          "live" => true,
          "trigger" => [
            "capping" => 1,
            "when" => "NEXT_SESSION"
          ],
          "landing" => [
            "theme" => "HELLO-THEME",
            "image" => "https://batch-doc.s3.amazonaws.com/logo_batch_192.png",
            "contents" => [
              [
                "language" => "en",
                "header" => "Welcome",
                "title" => "Hello!",
                "body" => "How is it going?",
                "actions" => [
                  {
                    "label" => "Continue",
                    "action" => "continue"
                  }
                ]
              ]
            ]
          ]
        ]
    ]);
    import requests, json
    response = requests.request("POST", "https://api.batch.com/1.1/BATCH_API_KEY/in-app-campaigns/create", 
        headers={
            'Content-Type': 'application/json'
            'X-Authorization': 'BATCH_REST_API_KEY'
        },
        data=json.dumps({
          'name': 'Test Campaign',
          'local_start_date': '2017-06-01T14:00:00',
          'live': True,
          'trigger': {
            'capping': 1,
            'when': 'NEXT_SESSION'
          },
          'landing': {
            'theme': 'HELLO-THEME',
            'image': 'https://batch-doc.s3.amazonaws.com/logo_batch_192.png',
            'contents': [
              {
                'language': 'en',
                'header': 'Welcome',
                'title': 'Hello!',
                'body': 'How is it going?',
                'actions': [
                  {
                    'label': 'Continue',
                    'action': 'continue'
                  }
                ]
              }
            ]
          }
        })
    )

    The BATCH_API_KEY value is either your Live or Dev 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 messages.
    • Live API: Depending on the targeting you set for your campaigns, apps built with the Live API key will receive messages. Apps built with the Dev API key will receive all the messages you send.

    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 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",
      "local_start_date": "2017-06-01T14:00:00",
      "live": true,
      "trigger": {
        "capping": 1,
        "when": "NEXT_SESSION"
      },
      "landing": {
        "theme": "HELLO-THEME",
        "image": "https://batch-doc.s3.amazonaws.com/logo_batch_192.png",
        "contents": [
          {
            "language": "en",
            "header": "Welcome",
            "title": "Hello!",
            "body": "How is it going?",
            "actions": [
              {
                "label": "Continue",
                "action": "continue"
              }
            ]
          }
        ]
      }
    }

    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.

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