Basics

Appboy provides a high performance REST API to allow you to track users, send messages, export data, and more.

What is a REST API?

A REST API is a way to programatically transfer information over the web using a predefined schema. Appboy has created many different endpoints with specific requirements that will perform various actions and/or return various data. API access is done using HTTPS web requests to your company’s REST API endpoint. Typically this is https://api.appboy.com, but your Success Manager will provide an alternative endpoint URL if necessary.

Note: Customers using Appboy’s EU database should use https://rest.api.appboy.eu/. For more information on REST APIs endpoints for customers using Appboy’s EU database see FAQs.

API Definitions

Below is some terminology that you may see in the Appboy REST API documentation and what it means.

Endpoints

Appboy manages a number of different instances for our Dashboard and REST Endpoints. When your account is provisioned you will login to one of the corresponding URLs below. Use the correct REST Endpoint based on which instance you are provisioned to. If you are unsure, open a support ticket or use the table below to match the URL of the dashboard you use to the correct REST Endpoint.

Instance Dashboard URL REST Endpoint
Appboy 01 dashboard.appboy.com https://api.appboy.com
Appboy 02 dashboard-02.appboy.com https://rest-02.iad.appboy.com
Appboy EU dashboard.appboy.eu https://rest.api.appboy.eu

Company Secret Explanation

The company_secret was formerly included with all API requests but has been deprecated as of October 2014. This field will be ignored for all future API requests to ensure backwards compatibility.

App Group Identifier Explanation

The app_group_id indicates the app title with which the data in this request is associated. It can be found in the Developer Console section of the Appboy dashboard.

App Identifier Explanation

For Custom Events and Revenue, you may want to specify a particular variant of the App in which the event occurred. For example, if you have event data on your servers that you know came from the Android version of your app, you might want to indicate that so that it’s reflected on the dashboard. In that case, you will provide the appropriate app identifier. It can be found in the Developer Console section of the Appboy dashboard.

External User ID Explanation

The external_id serves as a unique user identifier for whom you are submitting data. This identifier should be the same as the one you set in the Appboy mobile SDK in order to avoid creating multiple profiles for the same user.

User Alias Object

An alias serves as an alternative unique user identifier. Use aliases to identify users along different dimensions than your core user ID:

  • Set a consistent identifier for analytics that will follow a given user both before and after they have logged in to a mobile app or website.
  • Add the identifiers used by a third party vendor to your Appboy users in order to more easily reconcile your data externally.

Each alias consists of two parts: a name for the identifier itself, and a label indicating the type of alias. Users can have multiple aliases with different labels, but only one name per label.

{
  "alias_name" : (required, string),
  "alias_label" : (required, string)
}

Appboy User ID Explanation

The appboy_id serves as a unique user identifier that is set by Appboy. This identifier can be used to delete users through the REST API in addition to external_ids.

For more information see:

API Limits

The Appboy API infrastructure is designed to handle high volumes of data across our customer base. We enforce API rate limits in order to ensure responsible use of the API.

Initial API rate limit Value
Requests of any kind, legacy Free customers 100 per hour
Requests of any kind, all other customers 50,000 per hour
Requests to the Send endpoint specifying a Segment or Connected Audience 250 per minute
Users modified per User Track request 50 users

REST API rate limit increases are considered based on need for customers who are making use of the API batching capabilities. Please batch requests to our API endpoints: - A single request to the User Track endpoint can contain Purchases, Custom Events and/or Custom Attribute updates for up to 50 users, specified by external_id - A single request to the Messaging endpoints can reach any one of the following: - Up to 50 specific external_ids, each with individual message parameters - A segment of any size created in the Appboy dashboard, specified by its segment_id - An ad-hoc audience segment of any size, defined in the request as a Connected Audience object

The response headers for any valid request include the current rate limit status:

Header Name Description
X-RateLimit-Limit The maximum number of requests that the consumer is permitted to make per hour.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window resets in UTC epoch seconds.
  • If you have questions about API limits please contact your Customer Success Manager or please email Support.

API IP Whitelisting

For additional security, you can specify a whitelist of IP addresses and subnets which are allowed to make REST API requests for a given App Group. To whitelist specific IP addresses or subnets, navigate to the Developer Console in the Appboy dashboard and modify the section shown below:

Developer Console

User Data

The User API allows you to track information on your users by logging data about your users that comes from outside your mobile app. You can also use this API to delete users for testing or other purposes.

All API endpoints have a data payload limit of 4MB. Attempts to post more data than 4MB will fail with an HTTP 413 Request Entity Too Large.

The examples below contain the URL https://api.appboy.com, but some customers will need to use a different endpoint URL, for example if you are hosted in Appboy’s EU data center or have a dedicated Appboy installation. Your Success Manager will inform you should use a different endpoint URL.

User Track Endpoint

This endpoint can be used to record custom events, user attributes, and purchases for users. You can include up to 50 Attributes, Event, and Purchase Objects per request. That is, you can only post attributes for up to 50 users at a time, but in the same API call you can also provide up to 50 events and up to 50 purchases.

Your Endpoint will correspond to your Appboy Instance.

Instance REST Endpoint
Appboy 01 https://api.appboy.com/users/track
Appboy 02 https://rest-02.iad.appboy.com/users/track
Appboy EU https://rest.api.appboy.eu/users/track

User Track Request

POST https://api.appboy.com/users/track
Content-Type: application/json
{
   "app_group_id" : (required, string) see App Group Identifier below,
   "attributes" : (optional, array of Attributes Object),
   "events" : (optional, array of Event Object),
   "purchases" : (optional, array of Purchase Object)
}

Note: Customers using the API for server-to-server calls may need to whitelist api.appboy.com if they’re behind a firewall.

User Attributes Object Specification

An API request with any fields in the Attributes Object will create or update an attribute of that name with the given value on the specified user profile. Use the Appboy User Profile Field names below to update those special values on the user profile in the dashboard or add your own custom attribute data to the user.

{
  // One of "external_id" or "user_alias" is required
  "external_id" : (optional, string) see External User ID below,
  "user_alias" : (optional, User Alias Object),
  // Setting this flag to true will put the API in "Update Only" mode. Attributes objects regarding
  // external_ids which Appboy is unaware of will return a non-fatal error. See Server Responses for details.
  // When using a "user_alias", "Update Only" mode is always true.
  "_update_existing_only" : (optional, boolean),
  // See note below regarding anonymous push token imports
  "push_token_import" : (optional, boolean).
  // Appboy User Profile Fields
  "first_name" : "Jon",
  "email" : "bob@example.com",
  // Custom Attributes
  "my_custom_attribute" : value,
  "my_custom_attribute_2" : {"inc" : int_value},
  "my_array_custom_attribute":[ "Value1", "Value2" ],
  // Adding a new value to an array custom attribute
  "my_array_custom_attribute" : { "add" : ["Value3"] },
  // Removing a value from an array custom attribute
  "my_array_custom_attribute" : { "remove" : [ "Value1" ]},
}

Push Token Import

When importing push tokens from other systems, an external_id is not always available. To maintain communication with these users during your transition to Appboy, you can import the legacy tokens for anonymous users without providing external_id by specifying this parameter.

When specifying push_token_import as true:

  • external_id should not be specified
  • The attribute object must contain a push token
  • If the token already exists in Appboy, the request is ignored; otherwise, Appboy will create a temporary, anonymous user profile for each token to enable you to continue to message these individuals

After import, as each user launches the Appboy-enabled version of your app, Appboy will automatically move their imported push token to their Appboy user profile and clean up the temporary profile.

Custom Attribute Data Types

The following data types can be stored as a custom attribute:

  • Dates (Must be stored in the ISO 8601 format or in the yyyy-MM-dd'T'HH:mm:ss.SSSZ format)
    • Note: Date attributes without a timezone will default to Midnight UTC (and will be formatted on the dashboard as the equivalent of Midnight UTC in the company’s timezone)
  • Strings
  • Floats
  • Booleans
  • Integers
    • Integer custom attributes may be incremented by positive or negative integers by assigning them an object with the field “inc” and the value by which you would like to increment them.
      • Example: "my_custom_attribute_2" : {"inc" : int_value},
  • Arrays
    • In addition to setting the values of an array by saying something like "my_array_custom_attribute":[ "Value1", "Value2" ] you may add to existing arrays by doing something like "my_array_custom_attribute" : { "add" : ["Value3"] }, or remove values from an array by doing something like "my_array_custom_attribute" : { "remove" : [ "Value1" ]}
    • Note: The maximum number of elements in Custom Attribute Arrays defaults to 25. The maximum for individual arrays can be increased to up to 100 in the Appboy Dashboard, under “Manage App Group -> Custom Attributes”. Arrays exceeding the maximum number of elements will be truncated to contain the maximum number of elements. For more information on Custom Attribute Arrays and their behavior, see our Documentation on Arrays.

For information regarding when you should use a Custom Event vs a Custom Attribute, see our Best Practices - User Data Collection documentation.

Appboy User Profile Fields

User Profile Field Data Type Specification  
first_name string  
last_name string  
email string  
dob (Date of Birth) string in format “YYYY-MM-DD”, e.g., 1980-12-21  
country string, we require that country codes be passed to Appboy in the ISO-3166-1 alpha-2 standard  
language string, we require that language be passed to Appboy in the ISO-639-1 standard  
time_zone string String of time zone name from IANA Time Zone Database (e.g., “America/New_York” or “Eastern Time (US & Canada)”). Only valid time zone values will be set
home_city string  
current_location object of the form {“longitude”: -73.991443, “latitude”: 40.753824}  
bio string  
gender string, “M” or “F”  
phone string of digits  
email_subscribe string, available values are “opted_in” (explicitly registered to receive email messages), “unsubscribed” (explicitly opted out of email messages), and “subscribed” (neither opted in nor out).  
push_subscribe string, available values are “opted_in” (explicitly registered to receive push messages), “unsubscribed” (explicitly opted out of push messages), and “subscribed” (neither opted in nor out).  
date_of_first_session (Date at which the user first used the app) string in ISO 8601 format or in yyyy-MM-dd'T'HH:mm:ss.SSSZ format  
date_of_last_session (Date at which the user last used the app) string in ISO 8601 format or in yyyy-MM-dd'T'HH:mm:ss.SSSZ format  
image_url string, url of image to be associated with user profile  
push_tokens array of objects with app_id and token string, e.g., [{"app_id": App Identifier, "token": "abcd"}]  
external_id string String of the unique user identifier
facebook hash containing any of id (string), likes (array of strings), num_friends (integer)  
twitter hash containing any of id (integer), screen_name (string, Twitter handle), followers_count (integer), friends_count (integer), statuses_count (integer)  

Be aware that while you can import language, information Appboy receives from the device takes precedence, and if different, will replace the imported value the next time the user opens your app.

User Attribute Example Request

POST https://api.appboy.com/users/track
Content-Type: application/json
{
  "app_group_id" : "your app group ID",
 "attributes" : [
    {
      "external_id" : "user1",
      "first_name" : "Jon",
      "has_profile_picture" : true,
      "dob": "1988-02-14",
      "music_videos_favorited" : { "add" : [ "calvinharris-summer" ], "remove" : ["nickiminaj-anaconda"] }
    },
  {
      "external_id" : "user2",
      "first_name" : "Jill",
      "has_profile_picture" : false,
      "push_tokens": [{"app_id": App Identifier, "token": "abcd"}]
    },
    {
      "user_alias" : { "alias_name" : "bobby", "alias_label" : "my_internal_ids"},
      "first_name" : "Bobby",
      "has_profile_picture" : false,  
    }
  ]
}

This example contains two User Attribute objects of the allowed 50 per API call.

Event Object Specification

{
  // One of "external_id" or "user_alias" is required
  "external_id" : (optional, string) see External User ID below,
  "user_alias" : (optional, User Alias Object),
  "app_id" : (optional, string) see App Identifier below,
  "name" : (required, string) the name of the event,
  "time" : (required, datetime as string in ISO 8601 or in `yyyy-MM-dd'T'HH:mm:ss.SSSZ` format),
  "properties" : (optional, Properties Object) properties of the event
  // Setting this flag to true will put the API in "Update Only" mode. Event objects regarding
  // external_ids which Appboy is unaware of will return a non-fatal error. See Server Responses for details.
  // When using a "user_alias", "Update Only" mode is always true.
  "_update_existing_only" : (optional, boolean)
}

Each Event Object in the events array represents a single occurrence of a Custom Event by a particular user at the designated time value.

For information regarding when you should use a Custom Event vs a Custom Attribute, see our Best Practices - User Data Collection documentation.

Event Example Request

POST https://api.appboy.com/users/track
Content-Type: application/json
{
  "app_group_id" : "your app group ID",
 "events" : [
    {
      "external_id" : "user1",
      "app_id" : "your-app-id",
      "name" : "watched_trailer",
      "time" : "2013-07-16T19:20:30+01:00"
    },
    {
      "external_id" : "user1",
      "app_id" : "your-app-id",
      "name" : "rented_movie",
      "time" : "2013-07-16T19:20:45+01:00"
    },
    {
      "user_alias" : { "alias_name" : "bobby", "alias_label" : "my_internal_ids"},
      "app_id" : "your-app-id",
      "name" : "watched_trailer",
      "time" : "2013-07-16T19:20:50+01:00"
    }
  ]
}

Purchase Object Specfication

{
  // One of "external_id" or "user_alias" is required
  "external_id" : (optional, string) see External User ID below,
  "user_alias" : (optional, User Alias Object),
  "app_id" : (optional, string) see App Identifier below,
  "product_id" : (required, string) identifier for the purchase, e.g. SKU,
  "currency" : (required, string) ISO 4217 Alphabetic Currency Code,
  "price" : (required, float) value in the base currency unit (e.g. Dollars for USD, Yen for JPY),
  "quantity" : (optional, integer) the quantity purchased (defaults to 1, must be <= 100 -- currently, Appboy treats a quantity _X_ as _X_ separate purchases with quantity 1),
  "time" : (required, datetime as string in ISO 8601),
  "properties" : (optional, Properties Object) properties of the event
  // Setting this flag to true will put the API in "Update Only" mode. Event objects regarding
  // external_ids which Appboy is unaware of will return a non-fatal error. See Server Responses for details.
  // When using a "user_alias", "Update Only" mode is always true.
  "_update_existing_only" : (optional, boolean)
}

Each Purchase Object in the purchases array represents a single purchase by a particular user at a particular time.

Purchase Example Request

POST https://api.appboy.com/users/track
Content-Type: application/json
{
  "app_group_id" : "your-app-group-id",
 "purchases" : [
    {
      "external_id" : "user1",
      "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
      "product_id" : "backpack",
      "currency" : "USD",
      "price" : 40.00,
      "time" : "2013-07-16T19:20:30+01:00",
      "properties" : {
        "color" : "red",
        "monogram" : "ABC",
        "checkout_duration" : 180
      }
    },
    {
      "external_id" : "user1",
      "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
      "product_id" : "pencil",
      "currency" : "USD",
      "price" : 2.00,
      "time" : "2013-07-17T19:20:20+01:00",
      "properties" : {
        "number" : 2,
        "sharpened" : true
      }
    },
    {
      "user_alias" : { "alias_name" : "bobby", "alias_label" : "my_internal_ids"},
      "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
      "product_id" : "pen",
      "currency" : "USD",
      "price" : 2.50,
      "time" : "2013-07-17T19:20:20+01:00",
      "properties" : {
        "color" : "blue",
      }
    }
  ]
}

Properties Object

Custom events and purchases may have event properties. The “properties” values should be an Object where the keys are the property names and the values are the property values. Property names must be non-empty strings less than or equal to 255 characters, with no leading dollar signs. Property values can be integers, floats, booleans, datetimes (as strings in ISO8601 or in yyyy-MM-dd'T'HH:mm:ss.SSSZ format), or strings less than or equal to 255 characters.

User Track Responses

Upon using any of the aforementioned API requests you should receive one of the following three general responses:

Successful Message

Successful messages will be met with the following response:

{
  "message" : "success"
}

Successful Message with Non-Fatal Errors

If your message is successful but has non-fatal errors such as one invalid Event Object out of a longer list of events you will receive the following response:

{
  "message" : "success",
  "errors" : [<minor error message>]
}

Message with Fatal Errors

In the case of a success, any data that was not affected by an error in the errors array will still be processed. If your message has a fatal error you will receive the following response:

{
  "message" : <fatal error message>,
  "errors" : [<minor error message>]
}

Queued Responses

During times of maintenance, Appboy might pause real-time processing of the API. In these situations, the server will return an HTTP Accepted 202 response code and the following body, which indicates that we have received and queued the API call but have not immediately processed it. All scheduled maintenance will be posted to http://status.appboy.com ahead of time.

{
  "message" : "queued"
}

Fatal Error Response Codes

The following status codes and associated error messages will be returned if your request encounters a fatal error. Any of these error codes indicate that no data will be processed.

Error Code Reason / Cause
400 Bad Request Bad Syntax
401 Unauthorized Unknown or missing app group id
404 Not Found Unknown App Group ID (if provided)
429 Rate Limited Over rate limit
5XX Internal server error, you should retry with exponential backoff

Importing Legacy User Data

You may submit data through the Appboy API for a user who has not yet used your mobile app in order to generate a user profile. If the user subsequently uses the application all information following their identification via the SDK will be merged with the existing user profile you created via the API call. Any user behavior that is recorded anonymously by the SDK prior to identification will be lost upon merging with the existing API generated user profile.

The segmentation tool will include these users regardless of whether they have engaged with the app. If you want to exclude users uploaded via the User API whom have not yet engaged with the app you should add the filter – Session Count > 0.

User Delete Endpoint

This endpoint allows you to delete any user profile by specifying their external identifier (UserID). Up to 50 external_ids or appboy_ids can be included in a single request. Only one of external_ids or appboy_ids can be included in a single request. Please note that their associated event data will still exist in the dashboard after you delete the user.

Your Endpoint will correspond to your Appboy Instance.

Instance REST Endpoint
Appboy 01 https://api.appboy.com/users/delete
Appboy 02 https://rest-02.iad.appboy.com/users/delete
Appboy EU https://rest.api.appboy.eu/users/delete

User Delete Request

POST https://api.appboy.com/users/delete
Content-Type: application/json
{
  "app_group_id" : (required, string) App Group Identifier,
  "external_ids" : (optional, array of string) external ids for the users to delete,
  "appboy_ids" : (optional, array of string) appboy ids for the users to delete
}

Users Delete Response

Content-Type: application/json
{
  "deleted" : (required, integer) number of users successfully deleted,
  "invalid_user_ids" : (optional, array of string) each of the identifiers provided in the request that did not correspond to a known user
}

Note: This action CANNOT be undone. It will PERMANENTLY remove users which may cause discrepancies in your data.

New User Alias Endpoint

Use this endpoint to create new user aliases for existing identified users. You can add up to 50 user aliases per request.

Your Endpoint will correspond to your Appboy Instance.

Instance REST Endpoint
Appboy 01 https://api.appboy.com/users/alias/new
Appboy 02 https://rest-02.iad.appboy.com/users/alias/new
Appboy EU https://rest.api.appboy.eu/users/alias/new

New User Alias Request

POST https://api.appboy.com/users/alias/new
Content-Type: application/json
{
   "app_group_id" : (required, string) see App Group Identifier below,
   "user_aliases" : (required, array of New User Alias Object)
}

New User Alias Object Specification

{
  "external_id" : (required, string) see External User ID below,
  // external_ids for users that do not exist will return a non-fatal error. See Server Responses for details.
  "alias_name" : (required, string),
  "alias_label" : (required, string)
}

Sample POST Requests in Various Languages

Python

Note: This request can alternately be completed using the external library Requests.

# Necessary built-in imports to be utilized later
import json
import urllib2

# Define your static variables (app group ID, request url)
request_url = 'https://api.appboy.com/users/track'
app_group_id = "your-app-group-id"

# Define the content type as a dictionary
headers_params = {'Content-Type':'application/json'}

# Store the attribute values of your users as a list of dictionaries
attributes =[
            {'external_id':"python user ID", 'first_attribute':
             "your user's first attribute", 'second_attribute': "your user's second attribute"},
            {'external_id':"your second user's external id",'first_attribute':
             "first attribute", 'second_attribute': "second attribute"}
             ]

# Store the request data as a dictionary
data = {  'app_group_id':app_group_id,
          'attributes' : attributes   }
# Convert the data into JSON format
JSONdata = json.dumps(data)
# Create the request
req = urllib2.Request(request_url, JSONdata, headers_params)
# Open the request
f = urllib2.urlopen(req)
# Get the response code
response = f.read()
# Close the opened request
f.close
# Check that the request worked correctly
print response

# This process can alternately be completed by using the external library
# 'Requests' with the commented out code below:

# import requests
# r = requests.post(request_url, data=data, headers=headers_params)
# print r.status_code
# print r.text

Ruby (using REST Client & MultiJSON)

Note: This post request requires the downloading of the external gems Rest Client and MultiJSON

# Required libraries to import
require 'rest-client'
require 'multi_json'

# Define your static variables (app group ID, request url)
request_url = 'https://api.appboy.com/users/track'
app_group_id = 'your-app-group-id'

# Define the content type as a hash
headers_params = {'Content-Type'=>'application/json'}

# Store the attribute values of your users as an array of hashes
attributes =[
        {'external_id'=>"ruby user ID", 'first_attribute'=>
            "your user's first attribute", 'second_attribute'=> "your user's second attribute"},
        {'external_id'=>"your second user's external id",'first_attribute'=>
            "first attribute", 'second_attribute'=> "second attribute"}
        ]

# Store the request data as a hash
data = {:app_group_id => app_group_id,
        :attributes => attributes}
# Convert the data into JSON format
JSONdata = MultiJson.encode(data)
# Send and check the POST request
puts RestClient.post(request_url, JSONdata, headers_params)

PHP

<?php
# Define your static variables (app group ID, request url)
$app_group_id = 'your-app-group-id';
$request_url = 'https://api.appboy.com/users/track';

// Initialize your users by creating a map containing
// your desired attributes and associated attribute values.

$user1 = array(
       'external_id'=>"php user ID",
       'first_attribute'=> "your user's first attribute",
       'second_attribute'=> "your user's second attribute"
             );
$user2 = array(
       'external_id'=>"your second user's external id",
       'first_attribute'=> "your user's first attribute",
       'second_attribute'=> "your user's second attribute"
             );

// Note: Arrays in php are really ordered maps, hence
// the 'array' initialization associated with each user.

// Instantiate your attributes array using your previously
// defined user maps.
$attributes = array($user1, $user2);

// Organize the data to send to the API as another map
// comprised of your previously defined variables.
$postData = array(
  'app_group_id' => $app_group_id,
    'attributes' => $attributes,
);

// Create the context for the request
$context = stream_context_create(array(
    'http' => array(
        'method' => 'POST',
        'header' => "Content-Type: application/json\r\n",
        'content' => json_encode($postData)
    )
));

// Send the request
$response = file_get_contents($request_url, FALSE, $context);

// Post the response to ensure a successful request
echo $response;

?>

Messaging

Overview

The Appboy messaging API provides you with two distinct options for sending messages to your users. You can provide the message contents and configuration in the API request with the /messages/send and /messages/schedule endpoints. Alternatively, you can manage the details of your message with an API-Triggered Delivery campaign in the dashboard and just control when and to whom it is sent with the campaigns/trigger/send and campaigns/trigger/schedule endpoints. The following sections will detail the request specification for both methods.

The examples below contain the URL https://api.appboy.com, but some customers will need to use a different endpoint URL, for example if you are hosted in Appboy’s EU data center or have a dedicated Appboy installation. Your Success Manager will inform you should use a different endpoint URL.

Note: Similarly to other campaigns, you can limit the number of times a particular user can receive a Messaging API campaign by configuring re-eligibility settings in the Appboy Dashboard. Appboy will not deliver API messages to users that haven’t become re-eligible for the campaign regardless of how many API requests are sent.

Send Endpoints

The send endpoint allows you to send immediate, ad-hoc messages to designated users. If you are targeting a segment, a record of your request will be stored in the Developer Console.

Sending Messages Immediately via API Only

Instance REST Endpoint
Appboy 01 https://api.appboy.com/messages/send
Appboy 02 https://rest-02.iad.appboy.com/messages/send
Appboy EU https://rest.api.appboy.eu/messages/send
POST https://api.appboy.com/messages/send
Content-Type: application/json
{
   "app_group_id": (required, string) see App Group Identifier below,
   // You will need to include at least one of 'segment_id', 'external_user_ids', and 'audience'
   // Including 'segment_id' will send to members of that segment
   // Including 'external_user_ids' and/or 'user_aliases' will send to those users
   // Including both will send to the provided users if they are in the segment
   "broadcast": (optional, boolean) see Broadcast -- defaults to false on 8/31/17, must be set to true if no external_user_ids or aliases are provided,
   "external_user_ids": (optional, array of strings) see External User ID,
   "user_aliases": (optional, array of User Alias Object) see User Alias,
   "segment_id": (optional, string) see Segment Identifier,
   "audience": (optional, Connected Audience Object) see Connected Audience,
   "campaign_id": (optional, string) see Campaign Identifier,
   "override_frequency_capping": (optional, bool) ignore frequency_capping for campaigns, defaults to false,
   "recipient_subscription_state": (optional, string) use this to send messages to only users who have opted in ('opted_in'), only users who have subscribed or are opted in ('subscribed') or to all users, including unsubscribed users ('all'), the latter being useful for transactional email messaging. Defaults to 'subscribed',
   "messages": {
     "apple_push": (optional, Apple Push Object),
     "android_push": (optional, Android Push Object),
     "windows_phone8_push": (optional, Windows Phone 8 Push Object),
     "windows_universal_push": (optional, Windows Universal Push Object),
     "kindle_push": (optional, Kindle/FireOS Push Object),
     "web_push": (optional, Web Push Object),
     "in_app_message": (optional, In-App Message Object),
     "email": (optional, Email Object)
   }
 }

For more information on the “broadcast” flag, see Broadcast below.

Sending Messages via API Triggered Delivery

API Triggered Delivery allows you to house message content inside of the Appboy dashboard, while dictating when a message is sent, and to whom via your API. Please see this section of Appboy Academy for further details.

Instance REST Endpoint
Appboy 01 https://api.appboy.com/campaigns/trigger/send
Appboy 02 https://rest-02.iad.appboy.com/campaigns/trigger/send
Appboy EU https://rest.api.appboy.eu/campaigns/trigger/send
Campaigns
POST https://api.appboy.com/campaigns/trigger/send
Content-Type: application/json
{
  "app_group_id": (required, string) see App Group Identifier below,
  "campaign_id": (required, string) see Campaign Identifier,
  "trigger_properties": (optional, object) personalization key/value pairs that will apply to all users in this request,
  "broadcast": (optional, boolean) see Broadcast -- defaults to false on 8/31/17, must be set to true if "recipients" is omitted,
  "audience": (optional, Connected Audience Object) see Connected Audience,
  // Including 'audience' will only send to users in the audience
  "recipients": (optional, array; if not provided and broadcast is not set to 'false', message will send to entire segment targeted by the campaign) [
    {
      // Either "external_user_id" or "user_alias" is required. Requests must specify only one.
      "user_alias": (optional, User Alias Object) User Alias of user to receive message,
      "external_user_id": (optional, string) External Id of user to receive message,
      "trigger_properties": (optional, object) personalization key/value pairs that will apply to this user (these key/value pairs will override any keys that conflict with trigger_properties above)
    },
    ...
  ]
}

For more information on the “broadcast” flag, see Broadcast below.

Canvas
POST https://api.appboy.com/canvas/trigger/send
Content-Type: application/json
{
  "app_group_id": (required, string) see App Group Identifier below,
  "canvas_id": (required, string) see Canvas Identifier,
  "canvas_entry_properties": (optional, object) personalization key/value pairs that will apply to all users in this request,
  "broadcast": (optional, boolean) see Broadcast -- defaults to false on 8/31/17, must be set to true if "recipients" is omitted,
  "audience": (optional, Connected Audience Object) see Connected Audience,
  // Including 'audience' will only send to users in the audience
  "recipients": (optional, array; if not provided and broadcast is not set to 'false', message will send to the entire segment targeted by the Canvas) [
    {
      "external_user_id": (required, string) External Id of user to receive message,
      "canvas_entry_properties": (optional, object) personalization key/value pairs that will apply to this user (these key/value pairs will override any keys that conflict with canvas_entry_properties above)
    },
    ...
  ]
}

For more information on the “broadcast” flag, see Broadcast below.

Note: The recipients array may contain up to 50 objects, with each object containing a single external_user_id string and canvas_entry_properties object.

Note: Customers using the API for server-to-server calls may need to whitelist api.appboy.com if they’re behind a firewall.

Schedule Endpoints

The schedule endpoints allow you to send messages at a designated time and modify or cancel messages that you have already scheduled.

Create Schedule Endpoint

The create schedule endpoint allows you to schedule a Campaign, Canvas, or other message to be sent at a designated time and provides you with an identifier to reference that message for updates. If you are targeting a segment, a record of your request will be stored in the Developer Console after all scheduled messages have been sent.

Instance REST Endpoint
Appboy 01 https://api.appboy.com/messages/schedule/create
Appboy 02 https://rest-02.iad.appboy.com/messages/schedule/create
Appboy EU https://rest.api.appboy.eu/messages/schedule/create

Scheduling Messages

Use this endpoint to send messages directly from the API.

POST https://api.appboy.com/messages/schedule/create
Content-Type: application/json
{
  "app_group_id": (required, string) see App Group Identifier,
  // You will need to include at least one of 'segment_id', 'external_user_ids', and 'audience'
  // Including 'segment_id' will send to members of that segment
  // Including 'external_user_ids' and/or 'user_aliases' will send to those users
  // Including both a Segment and users will send to the provided users if they are in the segment
  "broadcast": (optional, boolean) see Broadcast -- defaults to false on 8/31/17, must be set to true if users are not specified,
  "external_user_ids": (optional, array of strings) see External User ID,
  "user_aliases": (optional, array of User Alias Object) see User Alias,
  "audience": (optional, Connected Audience Object) see Connected Audience,
  "segment_id": (optional, string) see Segment Identifier,
  "campaign_id": (optional, string) see Campaign Identifier,
  "override_messaging_limits": (optional, bool) ignore global rate limits for campaigns, defaults to false,
  "recipient_subscription_state": (optional, string) use this to send messages to only users who have opted in ('opted_in'), only users who have subscribed or are opted in ('subscribed') or to all users, including unsubscribed users ('all'), the latter being useful for transactional email messaging. Defaults to 'subscribed',
  "schedule": {
    "time": (required, datetime as ISO 8601 string) time to send the message,
    "in_local_time": (optional, bool),
    "at_optimal_time": (optional, bool),
  },
  "messages": {
    "apple_push": (optional, Apple Push Object),
    "android_push": (optional, Android Push Object),
    "windows_push": (optional, Windows Phone 8 Push Object),
    "windows8_push": (optional, Windows Universal Push Object),
    "kindle_push": (optional, Kindle/FireOS Push Object),
    "web_push": (optional, Web Push Object),
    "in_app_message" : (optional, In-App Message Object)
    "email": (optional, Email object)
    "webhook": (optional, Webhook object)
  }
}

For more information on the “broadcast” flag, see Broadcast below.

Schedule API Triggered Campaigns and Canvases

API Triggered Campaigns

Use this endpoint to trigger API Triggered Campaigns, which are created on the Dashboard and initiated via the API. You can pass in trigger_properties that will be templated into the message itself.

POST https://api.appboy.com/campaigns/trigger/schedule/create
Content-Type: application/json
{
  "app_group_id": (required, string) see App Group Identifier,
  "campaign_id": (required, string) see Campaign Identifier,
  // Including 'recipients' will send only to the provided user ids if they are in the campaign's segment
  "recipients": (optional, Array of Recipient Object),
  // for any keys that conflict between these trigger properties and those in a Recipient Object, the value from the
  // Recipient Object will be used
  "audience": (optional, Connected Audience Object) see Connected Audience,
  // Including 'audience' will only send to users in the audience
  // If 'recipients' and 'audience' are not provided and broadcast is not set to 'false',
  // the message will send to entire segment targeted by the campaign
  "broadcast": (optional, boolean) see Broadcast -- defaults to false on 8/31/17, must be set to true if "recipients" object is omitted,
  "trigger_properties": (optional, object) personalization key/value pairs for all users in this send; see Trigger Properties,
  "schedule": {
    "time": (required, datetime as ISO 8601 string) time to send the message,
    "in_local_time": (optional, bool),
    "at_optimal_time": (optional, bool),
  }
}

For more information on the “broadcast” flag, see Broadcast below.

API Triggered Canvases

Use this endpoint to trigger API Triggered Canvases, which are created on the Dashboard and initiated via the API. You can pass in canvas_entry_properties that will be templated into the messages sent by the first steps of the Canvas.

POST https://api.appboy.com/canvas/trigger/schedule/create
Content-Type: application/json
{
  "app_group_id": (required, string) see App Group Identifier,
  "canvas_id": (required, string) see Canvas Identifier,
  // Including 'recipients' will send only to the provided user ids if they are in the campaign's segment
  "recipients": (optional, Array of Recipient Object),
  // for any keys that conflict between these trigger properties and those in a Recipient Object, the value from the
  // Recipient Object will be used
  "audience": (optional, Connected Audience Object) see Connected Audience,
  // Including 'audience' will only send to users in the audience
  // If 'recipients' and 'audience' are not provided and broadcast is not set to 'false',
  // the message will send to entire segment targeted by the Canvas
  "broadcast": (optional, boolean) see Broadcast -- defaults to false on 8/31/17, must be set to true if "recipients" object is omitted,
  "canvas_entry_properties": (optional, object) personalization key/value pairs for the first step for all users in this send; see Trigger Properties,
  "schedule": {
    "time": (required, datetime as ISO 8601 string) time to send the message,
    "in_local_time": (optional, bool),
    "at_optimal_time": (optional, bool),
  }
}

For more information on the “broadcast” flag, see Broadcast below.

The Schedule Object

The parameters for the Campaign and Canvas schedule creation endpoints mirror those of the sending endpoint and add the schedule parameter, which allows you to specify when you want your targeted users to receive your message. If you include only the time parameter in the schedule object, all of your users will be messaged at that time. If you set in_local_time to be true, your users will receive the message at the designated date and time in their respective timezones. If in_local_timeis true, you will get an error response if the time parameter has passed in your company’s time zone. If you set at_optimal_time to be true, your users will receive the message at the designated date at the optimal time for them (regardless of the time you provide). When using local or optimal time sending, do not provide time zone designators in the value of the time parameter (e.g. just give us "2015-02-20T13:14:47" instead of "2015-02-20T13:14:47-05:00").

The response will provide you with a schedule_id that you should save in case you later need to cancel or update the message you schedule:

Content-Type: application/json
{
  "schedule_id" : (required, string) identifier for the scheduled message that was created
}

Note: Customers using the API for server-to-server calls may need to whitelist api.appboy.com if they’re behind a firewall.

Update Schedule Endpoint

The update schedule endpoint allows you to change the schedule or message contents of a scheduled message you previously created.

Instance REST Endpoint
Appboy 01 https://api.appboy.com/messages/schedule/update
Appboy 02 https://rest-02.iad.appboy.com/messages/schedule/update
Appboy EU https://rest.api.appboy.eu/messages/schedule/update

Update Message Schedule

The messages update schedule endpoint accepts updates to either the schedule or messages parameter or both. Your request must contain at least one of those two keys.

POST https://api.appboy.com/messages/schedule/update
Content-Type: application/json
{
  "app_group_id": (required, string) see App Group Identifier below,
  "schedule_id": (required, string) the schedule_id to update (obtained from the response to create schedule),
  "schedule": {
    // optional, see create schedule documentation
  },
  "messages": {
    // optional, see create schedule documentation
  }
}

Update API Triggered Campaign or Canvas Schedules

Instance REST Endpoint
Appboy 01 https://api.appboy.com/trigger/schedule/create
Appboy 02 https://rest-02.iad.appboy.com/trigger/schedule/create
Appboy EU https://rest.api.appboy.eu/trigger/schedule/create
API Triggered Campaigns
POST https://api.appboy.com/campaigns/trigger/schedule/update
Content-Type: application/json
{
  "app_group_id": (required, string) see App Group Identifier below,
  "campaign_id": (required, string) see Campaign Identifier,
  "schedule_id": (required, string) the schedule_id to update (obtained from the response to create schedule),
  "schedule": {
    // required, see create schedule documentation
  }
}
API Triggered Canvases
POST https://api.appboy.com/canvas/trigger/schedule/update
Content-Type: application/json
{
  "app_group_id": (required, string) see App Group Identifier below,
  "canvas_id": (required, string) see Canvas Identifier,
  "schedule_id": (required, string) the schedule_id to update (obtained from the response to create schedule),
  "schedule": {
    // required, see create schedule documentation
  }
}
Updating API Triggered Campaigns and Canvases

Any schedule will completely overwrite the one that you provided in the create schedule request or in previous update schedule requests. For example, if you originally provide "schedule" : {"time" : "2015-02-20T13:14:47", "in_local_time" : true} and then in your update you provide "schedule" : {"time" : "2015-02-20T14:14:47"}, your message will now be sent at the provided time in UTC, not in the user’s local time. Scheduled triggers that are updated very close to or during the time they were supposed to be sent will be updated with best efforts, so last second changes could be applied to all, some, or none of your targeted users.

Delete Schedule Endpoint

The delete schedule endpoint allows you to cancel a message that you previously scheduled before it has been sent.

Delete Message Schedule

Instance REST Endpoint
Appboy 01 https://api.appboy.com/messages/schedule/delete
Appboy 02 https://rest-02.iad.appboy.com/messages/schedule/delete
Appboy EU https://rest.api.appboy.eu/messages/schedule/delete
POST https://api.appboy.com/messages/schedule/delete
Content-Type: application/json
{
  "app_group_id": (required, string) see App Group Identifier below,
  "schedule_id": (required, string) the schedule_id to delete (obtained from the response to create schedule)
}

Delete Scheduled API Trigger Campaign

Instance REST Endpoint
Appboy 01 https://api.appboy.com/trigger/schedule/create
Appboy 02 https://rest-02.iad.appboy.com/trigger/schedule/create
Appboy EU https://rest.api.appboy.eu/trigger/schedule/create
POST https://api.appboy.com/campaigns/trigger/schedule/delete
Content-Type: application/json
{
  "app_group_id": (required, string) see App Group Identifier below,
  "campaign_id": (required, string) see Campaign Identifier,
  "schedule_id": (required, string) the schedule_id to delete (obtained from the response to create schedule)
}

Scheduled messages or triggers that are deleted very close to or during the time they were supposed to be sent will be updated with best efforts, so last second deletions could be applied to all, some, or none of your targeted users.

Get upcoming scheduled Campaigns and Canvases

Instance REST Endpoint
Appboy 01 GET https://api.appboy.com/messages/scheduled_broadcasts
Appboy 02 GET https://rest-02.iad.appboy.com/messages/scheduled_broadcasts
Appboy EU GET https://rest.api.appboy.eu/messages/scheduled_broadcasts
Parameter Required Data Type Description
app_group_id Yes String see App Group Identifier in Parameter Definitions
end_time Yes String in ISO 8601 format End date of the range to retrieve upcoming scheduled Campaigns and Canvases. This is treated as midnight in UTC time by the API.

Example:

https://api.appboy.com/messages/scheduled_broadcasts?app_group_id=X&end_time=2017-09-01T00:00:00-04:00

This endpoint returns information about scheduled Campaigns and scheduled entry Canvases between now and the end_time specified in the request. Only the next occurrence of each Campaign and Canvas is provided. This means that daily recurring messages will only appear once with their next occurrence. Results returned in this endpoint are only for Campaigns and Canvases created and scheduled in the Appboy Dashboard.

Example response:

{
    "scheduled_broadcasts": [
      # Example Canvas
      {
        "name" => String,
        "id" => String,
        "type" => "Canvas",
        "tags" => [String tag names],
        "next_send_time" => "YYYY-MM-DD HH:mm:ss" (may also include time zone if not local/intelligent delivery)
        "schedule_type" => one of "local_time_zones", "intelligent_delivery", or the name of your company's time zone
      },
      # Example Campaign
      {
        "name" => String,
        "id" => String,
        "type" => "Campaign",
        "tags" => [String tag names],
        "next_send_time" => "YYYY-MM-DD HH:mm:ss" (may also include time zone if not local/intelligent delivery)
        "schedule_type" => one of "local_time_zones", "intelligent_delivery", or the name of your company's time zone
      },
    ]
}

Parameter Definitions

App Group Identifier

The app_group_id indicates the app title with which the data in this request is associated and authenticates the requester as someone who is allowed to send messages to the app. It must be included with every request. It can be found in the Developer Console section of the Appboy dashboard.

App Identifier

If you want to send push to a set of device tokens (instead of users), you need to indicate on behalf of which specific app you are messaging. In that case, you will provide the appropriate App Identifier in a Tokens Object. It can be found in the Developer Console section of the Appboy dashboard.

External User ID

A unique identifier for sending a message to specific users. This identifier should be the same as the one you set in the Appboy mobile SDK. You can only target users for messaging who have already been identified through the mobile SDK or the Users API. If you need to send messages to specific users who have not yet been identified to Appboy, consider attaching a Tokens Object (explained below) to your message. A maximum of 50 External User IDs are allowed in a request.

For campaign trigger endpoints, if you provide this field, the criteria will be layered with the campaign’s segments and only users who are in the list of External User IDs and the campaign’s segment will receive the message.

User Alias Object

The User Alias Object consists of two parts: an alias_name for the identifier itself, and an alias_label indicating the type of alias. Users can have multiple aliases with different labels, but only one alias_name per alias_label.

{
  "alias_name" : (required, string),
  "alias_label" : (required, string)
}

Segment Identifier

The segment_id indicates the segment to which the message should be sent. A Segment Identifier for each of the segments you have created can be found in the Developer Console section of the Appboy dashboard. For message endpoints, if you provide both a Segment Identifier and a list of External User IDs in a single messaging request, the criteria will be layered and only users who are in the list of External User IDs and the provided segment will receive the message.

Campaign Identifier

For messaging endpoints, the campaign_id indicates the API Campaign under which the analytics for a message should be tracked. A Campaign Identifier for each of the campaigns you have created can be found in the Developer Console section of the Appboy dashboard. If you provide a Campaign Identifier in the request body, you must provide a message_variation_id in each of the message objects indicating the represented variant of your campaign.

For campaign trigger endpoints, the campaign_id indicates the API ID of the campaign to be triggered. This field is required for all trigger endpoint requests.

Canvas Identifier

For Canvas triggering endpoints, the canvas_id indicates the identifier of the Canvas to be triggered or scheduled. This field is required for all trigger endpoint requests.

Trigger Properties

When using one of the endpoints for sending a campaign with API Triggered Delivery, you may provide a map of keys and values to customize your message. If you make an API request that contains an object in "trigger_properties", the values in that object can then be referenced in your message template under the api_trigger_properties namespace. For example, a request with "trigger_properties" : {"product_name" : "shoes", "product_price" : 79.99} could add the word “shoes” to the message by adding {{api_trigger_properties.${product_name}}}.

Canvas Entry Properties

When using one of the endpoints for triggering or scheduling a Canvas via the API, you may provide a map of keys and values to customize messages sent by the first steps of your Canvas, in the canvas_entry_properties namespace. For example, a request with "canvas_entry_properties" : {"product_name" : "shoes", "product_price" : 79.99} could add the word “shoes” to a message by adding {{canvas_entry_properties.${product_name}}}.

Recipient Object

{
  // Either "external_user_id" or "user_alias" is required. Requests must specify only one.
  "user_alias": (optional, User Alias Object) User Alias of user to receive message,
  "external_user_id": (optional, string) see External User Id,
  "trigger_properties": (optional, object) personalization key/value pairs for this user when sending a Campaign or message; see Trigger Properties,
  "canvas_entry_properties": (optional, object) personalization key/value pairs for this user when triggering a Canvas; see Canvas Entry Properties
}

Broadcast

When sending a message to a segment or campaign audience using an API endpoint, Appboy requires you to explicitly define whether or not your message is a “broadcast” to a large group of users by including a “broadcast” boolean in the API call. That is, if you intend to send an API message to the entire segment that a campaign or Canvas targets, you must include “broadcast: true” in your API call. If the “broadcast” flag is not set to true and an explicit list of recipients it not provided, the API endpoint will return an error. Similarly, including “broadcast: true” and providing a recipient list will return an error. The “broadcast” flag is required in order to protect against accidental sends to large groups of users.

Please note that for backwards-compatibility, this field is only required for API calls made for campaigns and Canvases created after August 15, 2017 that intend to send to the entire audience. It will be mandatory on August 31, 2017 for all campaigns and Canvases for API calls that intend to send to the entire audience. The behavior for API calls to deliver campaigns and canvases created prior to these dates is: if an explicit list of recipients is not provided, the message will send to the entire targeted audience of the campaign or Canvas. That is, until 8/15/17, the “broadcast” field does not have a default value, so you may wish to explicitly set “broadcast: false” in existing API calls. On 8/15/17, it will default to false for newly created Campaigns and Canvases. On 8/31/17, it will default to false for all API calls.

Connected Audience Object

A Connected Audience is a selector that identifies the audience to send the message to. It is composed of either a single Connected Audience Filter, or several Connected Audience Filters in a logical expression using either “AND” or “OR” operators.

Multiple filter example:

{
  "AND":
    [
      Connected Audience Filter,
      {
        "OR" :
          [
            Connected Audience Filter,
            Connected Audience Filter
          ]
      },
      Connected Audience Filter
    ]
}

Connected Audience Filter

These filters are used to create an Connected Audience Object.

Custom Attribute Filter

This filter allows you to segment based on a user’s custom attribute. These filters contain up to three fields:

{
  "custom_attribute":
    {
      "custom_attribute_name": (String) the name of the custom attribute to filter on,
      "comparison": (String) one of the allowed comparisons to make against the provided value,
      "value": (String, Numeric, Boolean) the value to be compared using the provided comparison
    }
}

The custom attribute’s type determines the comparisons that are valid for a given filter.

Custom Attribute Type Allowed Comparisons
String equals, not_equal, matches_regex, does_not_match_regex, exists, does_not_exist
Array includes_value, does_not_include_value, exists, does_not_exist
Numeric equals, not_equal, greater_than, greater_than_or_equal_to, less_than, less_than_or_equal_to, exists, does_not_exist
Boolean equals, does_not_equal, exists, does_not_exist
Time less_than_x_days_ago, greater_than_x_days_ago, less_than_x_days_in_the_future, greater_than_x_days_in_the_future, after, before, exists, does_not_exist

Note: value is not required when using the exists or does_not_exist comparisons. value must be an ISO 8601 DateTime string when using the before and after comparisons.

Examples:

{
  "custom_attribute":
    {
      "custom_attribute_name": "eye_color",
      "comparison": "equals",
      "value": "blue"
    }
}

{
  "custom_attribute":
  {
    "custom_attribute_name": "favorite_foods",
    "comparison": "includes_value",
    "value": "pizza"
  }
}

{
  "custom_attribute":
  {
    "custom_attribute_name": "last_purchase_time",
    "comparison": "less_than_x_days_ago",
    "value": 2
  }
}

Push Subscription Filter

This filter allows you to segment based on a user’s push subscription status. These filters contain two fields:

{
  "push_subscription_status":
  {
    "comparison": (String) one of the two allowed comparisons listed below,
    "value": (String) one of the three allowed values listed below
  }
}
Allowed Comparisons Allowed Values
is, is_not opted_in, subscribed, unsubscribed

Email Subscription Filter

This filter allows you to segment based on a user’s email subscription status. These filters contain two fields:

{
  "email_subscription_status":
  {
    "comparison": (String) one of the two allowed comparisons listed below,
    "value": (String) one of the three allowed values listed below
  }
}
Allowed Comparisons Allowed Values
is, is_not opted_in, subscribed, unsubscribed

Last Used App Filter

This filter allows you to segment based on when was the last time user used the App. These filters contain two fields:

{
  "last_used_app":
  {
    "comparison": (String) one of the allowed comparisons listed below,
    "value": (String) the value to be compared using the provided comparison
  }
}
Allowed Comparisons Allowed Values
after, before DateTime (ISO 8601 string)

Apple Push Object

{
   "badge": (optional, int) the badge count after this message,
   "alert": (required unless content-available is true, string or Apple Push Alert Object) the notification message,
   // Specifying "default" in the sound field will play the standard notification sound
   "sound": (optional, string) the location of a custom notification sound within the app,
   "extra": (optional, object) additional keys and values to be sent,
   "content-available": (optional, boolean) if set, Appboy will add the "content-available" flag to the push payload,
   "expiry": (optional, ISO 8601 date string) if set, push messages will expire at the specified datetime,
   "custom_uri": (optional, string) a web URL, or Deep Link URI,
   "message_variation_id": (optional, string) used when providing a campaign_id to specify which message variation this message should be tracked under (must be an iOS Push Message),
   "asset_url": (optional, string) content URL for rich notifications for devices using iOS 10 or higher,
   "asset_file_type": (required if asset_url is present, string) file type of the asset - one of "aif", "gif", "jpg", "m4a", "mp3", "mp4", "png", or "wav",
   "collapse_id": (optional, string) To update a notification on the user's device once you've issued it, send another notification with the same collapse ID you used previously
   "mutable_content": (optional, boolean) if true, Appboy will add the mutable-content flag to the payload and set it to 1. The mutable-content flag is automatically set to 1 when sending a rich notification, regardless of the value of this parameter.
   "send_to_most_recent_device_only": (optional, boolean) defaults to false, if set to true, Appboy will only send this push to a user's most recently used iOS device, rather than all eligible iOS devices,
   "category": (optional, string) the iOS notification category identifier for displaying push action buttons,
   "buttons" : (optional, array of Apple Push Action Button Objects) push action buttons to display
}

Note: You must include an Apple Push Object in messages if you want users you have targeted to receive a push on their iOS Devices. The total number of bytes in your alert string, extra object, and other optional parameters should not exceed 1912. The Messaging API will return an error if you exceed the message size allowed by Apple. Messages that include the keys ab or aps in the extra object will be rejected.

Apple Push Alert Object

Note: In most cases, alert can just be specified in an apple_push object as a string. You should specify alert as an object only in cases where you need specific localization or Apple Watch customization.

{
   "body": (required unless content-available is true in the Apple Push Object, string) the text of the alert message,
   "title": (optional, string) a short string describing the purpose of the notification, displayed as part of the Apple Watch notification interface,
   "title_loc_key": (optional, string) the key to a title string in the `Localizable.strings` file for the current localization,
   "title_loc_args": (optional, array of strings) variable string values to appear in place of the format specifiers in title_loc_key,
   "action_loc_key": (optional, string) if a string is specified, the system displays an alert that includes the Close and View buttons, the string is used as a key to get a localized string in the current localization to use for the right button’s title instead of "View",
   "loc_key": (optional, string) a key to an alert-message string in a Localizable.strings file for the current localization,
   "loc_args": (optional, array of strings) variable string values to appear in place of the format specifiers in loc_key
}

Apple Push Action Button Object

Note: You must include the category field in the Apple Push Object to use iOS push action buttons. Including the category field will display any associated push action buttons; only include the buttons field if you want to additionally define the buttons’ individual click actions. The Appboy SDK provides a set of default push action buttons for you to use (see the table below). You can also use your own buttons if they have been registered in your app.

Apple Push Action Button Object for Appboy Default Buttons
Category Identifier Button Text Button Action Identifier Allowed Actions
ab_cat_accept_decline Accept ab_pb_accept OPEN_APP, URI, or DEEP_LINK
ab_cat_accept_decline Decline ab_pb_decline CLOSE
ab_cat_yes_no Yes ab_pb_yes OPEN_APP, URI, or DEEP_LINK
ab_cat_yes_no No ab_pb_no CLOSE
ab_cat_confirm_cancel Confirm ab_pb_confirm OPEN_APP, URI, or DEEP_LINK
ab_cat_confirm_cancel Cancel ab_pb_cancel CLOSE
ab_cat_more More ab_pb_more OPEN_APP, URI, or DEEP_LINK
{
  "action_id": (required, string) the button's action identifier,
  "action": (optional, string) one of "OPEN_APP", "URI", "DEEP_LINK", or "CLOSE". Defaults to either "OPEN_APP" or "CLOSE" depending on the button,
  "uri": (optional, string) a web URL or Deep Link URI,
  "use_webview": (optional, boolean) whether to open the web URL inside the app if the action is "URI", defaults to true
}
Apple Push Action Button Object for Categories Defined by Your App
{
  "action_id": (required, string) the button's action identifier,
  "action": (required, string) one of "URI" or "DEEP_LINK",
  "uri": (required, string) a web URL or Deep Link URI,
  "use_webview": (optional, boolean) whether to open the web URL inside the app if the action is "URI", defaults to true
}

Android Push Object

{
   "alert": (required, string) the notification message,
   "title": (required, string) the title that appears in the notification drawer,
   "extra": (optional, object) additional keys and values to be sent in the push,
   "message_variation_id": (optional, string) used when providing a campaign_id to specify which message variation this message should be tracked under (must be an Android Push Message),
   "notification_channel_id": (optional, string) the channel ID the notification will be sent with,
   "priority": (optional, integer) the notification priority value,
   "send_to_sync": (optional, if set to true we will throw an error if "alert" or "title" is set),
   "collapse_key": (optional, string) the collapse key for this message,
   // Specifying "default" in the sound field will play the standard notification sound
   "sound": (optional, string) the location of a custom notification sound within the app,
   "custom_uri": (optional, string) a web URL, or Deep Link URI,
   "summary_text": (optional, string),
   "time_to_live": (optional, integer (seconds)),
   "notification_id": (optional, integer),
   "push_icon_image_url": (optional, string) an image URL for the large icon,
   "accent_color": (optional, integer) accent color to be applied by the standard Style templates when presenting this notification, an RGB integer value,
   "send_to_most_recent_device_only": (optional, boolean) defaults to false, if set to true, Appboy will only send this push to a user's most recently used Android device, rather than all eligible Android devices,
   "buttons" : (optional, array of Android Push Action Button Objects) push action buttons to display,
}

Note: You can send “Big Picture” notifications by specifying the key appboy_image_url in the extra object. The value for appboy_image_url should be a URL that links to where your image is hosted. Images need to be cropped to a 2:1 aspect ratio and should be at least 600x300. Images used for notifications will only display on devices running Jelly Bean (Android 4.1) or higher.

Note: priority will accept values from -2 to 2, where -2 represents “MIN” priority and 2 represents “MAX”. 0 is the “DEFAULT” value. Any values sent that outside of that integer range will default to 0. For more information on which priority level to use, please see our section on Android Notification Priority.

Note: The value for the large icon push_icon_image_url should be a URL that links to where your image is hosted. Images need to be cropped to a 1:1 aspect ratio and should be at least 40x40. Images used for custom notification icons will only display on devices running Honeycomb MR1 (Android 3.1) or higher.

Note: If notification_channel is not specified, Appboy will attempt to send the notification payload with the dashboard fallback channel ID. For more information on notification_channel please see our developer documentation and our academy article.

For more information on collapsing notifications using the collapse_key please see the Android Developer Docs

For more information on send_to_sync messages please see our section on “Silent Android Notifications”

You must include an Android Push Object in messages if you want users you have targeted to receive a push on their Android devices. The total number of bytes in your alert string and extra object should not exceed 4000. The Messaging API will return an error if you exceed the message size allowed by Google.

Android Push Action Button Object

{
  "text": (required, string) the button's text,
  "action": (optional, string) one of "OPEN_APP", "URI", "DEEP_LINK", or "CLOSE", defaults to "OPEN_APP",
  "uri": (optional, string) a web URL or Deep Link URI,
  "use_webview": (optional, boolean) whether to open the web URL inside the app if the action is "URI", defaults to true
}

Kindle/FireOS Push Object

{
   "alert": (required, string) the notification message,
   "title": (required, string) the title that appears in the notification drawer,
   "extra": (optional, object) additional keys and values to be sent in the push,
   "message_variation_id": (optional, string) used when providing a campaign_id to specify which message variation this message should be tracked under (must be an Kindle/FireOS Push Message),
   "priority": (optional, integer) the notification priority value,
   "collapse_key": (optional, string) the collapse key for this message,
   // Specifying "default" in the sound field will play the standard notification sound
   "sound": (optional, string) the location of a custom notification sound within the app,
   "custom_uri": (optional, string) a web URL, or Deep Link URI
}

Note: priority will accept values from -2 to 2, where -2 represents “MIN” priority and 2 represents “MAX”. 0 is the “DEFAULT” value. Any values sent that outside of that integer range will default to 0.

Web Push Object

{
   "alert": (required, string) the notification message,
   "title": (required, string) the title that appears in the notification drawer,
   "extra": (optional, object) additional keys and values to be sent in the push,
   "message_variation_id": (optional, string) used when providing a campaign_id to specify which message variation this message should be tracked under (must be an Kindle/FireOS Push Message),
   "custom_uri": (optional, string) a web URL,
   "image_url": (optional, string) url for image to show,
   "large_image_url": (optional, string) url for large image, supported on Chrome Windows/Android,
   "require_interaction": (optional, boolean) whether to require the user to dismiss the notification, supported on Mac Chrome,
   "time_to_live": (optional, integer (seconds)),
   "buttons" : (optional, array of Web Push Action Button Objects) push action buttons to display
}

Note: The value for image_url should be a URL that links to where your image is hosted. Images need to be cropped to a 1:1 aspect ratio.

Web Push Action Button Object

{
  "text": (required, string) the button's text,
  "action": (optional, string) one of "OPEN_APP", "URI", or "CLOSE", defaults to "OPEN_APP",
  "uri": (optional, string) a web URL
}

Windows Phone 8 Push Object

{
   "push_type": (optional, string) must be "toast",
   "toast_title": (optional, string) the notification title,
   "toast_content": (required, string) the notification message,
   "toast_navigation_uri": (optional, string) page uri to send user to,
   "toast_hash": (optional, object) additional keys and values to send,
   "message_variation_id": (optional, string) used when providing a campaign_id to specify which message variation this message should be tracked under (must be a Windows Phone 8 Push Message)
}

Windows Universal Push Object

See the Windows Universal toast template catalog for details on the options for push_type below.

{
   "push_type": (required, string) one of: "toast_text_01", "toast_text_02", "toast_text_03", "toast_text_04", "toast_image_and_text_01", "toast_image_and_text_02", "toast_image_and_text_03", or "toast_image_and_text_04",
   "toast_text1": (required, string) the first line of text in the template,
   "toast_text2": (optional, string) the second line of text (for templates with > 1 line of text),
   "toast_text3": (optional, string) the third line of text (for the *_04 templates),
   "toast_text_img_name": (optional, string) the path for the image for the templates that include an image,
   "message_variation_id": (optional, string) used when providing a campaign_id to specify which message variation this message should be tracked under (must be a Windows Universal Push Message),
   "extra_launch_string": (optional, string) used to add deep linking functionality by passing extra values to the launch string
}

Note: For more information on using the extra_launch_string parameter for deep linking, see Deep Linking with Windows Universal. For information regarding what a deep link is, please see our FAQ Section.

In-App Message Object Specification

See our Guide to Best Practices for In-App Messages for the details on the different types of in-app messages available.

{
   "type" : (optional, string) one of "SLIDEUP" OR "MODAL" or "FULL", defaults to "SLIDEUP",
   // For "SLIDEUP" messages, old versions of the SDK only support some of the features, so set this to false to avoid sending messages that would not make sense as an older version of the slideups (i.e. includes an image that is referenced by the message). This is not applicable for "MODAL" or "FULL" messages, which are always only sent to new versions
   "also_send_to_slideup_only_versions" : (optional, boolean), defaults to true,
   "message" : (required, string) 140 characters max,
   // all colors should be 8-digit hex strings plus a leading "0x", for example "0xFF00AA88"
   // see http://developer.android.com/reference/android/graphics/Color.html for specifications
   "message_text_color" : (optional, string) hex value for colors, defaults to black or white depending on message type,
   "header" : (optional, string) the header shown, not shown if excluded,
   "header_text_color" : (optional, string) hex value for colors, defaults to black or white depending on message type,
   "background_color" : (optional, string) hex value for colors, defaults to black or white depending on message type,
   "close_button_color" : (optional, string) hex value for colors, defaults to black
   "slide_from" : (optional, string) "TOP" OR "BOTTOM" for "STANDARD" messages, defaults to "BOTTOM",
   "message_close" : (optional, string) "SWIPE" OR "AUTO_DISMISS", defaults to "AUTO_DISMISS",
   // icon should be 4-digit hex string without the leading "0x" from http://fortawesome.github.io/Font-Awesome/cheatsheet/
   // for example, "f042" for the first icon, fa-adjust [&#xf042;]
   // if both image_url and icon are present, image_url will be used
   "icon": (optional, string) Font Awesome icon hex value,
   "icon_color" : (optional, string) hex value for colors, defaults to white,
   "icon_background_color" : (optional, string) hex value for colors, defaults to blue,
   "image_url" : (optional, string) url for image to show when type is "FULL", overrides "icon" if both are present,
   "buttons" : (optional, Array of Button Objects) buttons to show, at most 2 allowed,
   "extras" : (optional, valid Key Value Hash), extra hash,
   // click actions and uri are not applicable if there are buttons and type is MODAL or FULL
   "ios_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "android_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "windows_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "windows8_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "kindle_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "android_china_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "web_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "ios_uri" : (optional, string) valid http or protocol uri,
   "android_uri" : (optional, string) valid http or protocol uri,
   "windows_uri" : (optional, string) valid http or protocol uri,
   "windows8_uri" : (optional, string) valid http or protocol uri,
   "kindle_uri" : (optional, string) valid http or protocol uri,
   "android_china_uri" : (optional, string) valid http or protocol uri,
   "web_uri" : (optional, string) valid http or protocol uri,
   "message_variation_id": (optional, string) used when providing a campaign_id to specify which message variation this message should be tracked under
}

The In-App Message Object should be included in messages when you would like to also deliver an in-app message with the given content to the targeted users.

Button Object

{
   "text": (required, string) text shown on button,
   "text_color": (optional, string) hex value for colors, defaults to white,
   "background_color": (optional, string) hex value for colors, defaults to blue,
   "ios_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "android_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "windows_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "windows8_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "kindle_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "android_china_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "web_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "ios_uri" : (optional, string) valid http or protocol uri,
   "android_uri" : (optional, string) valid http or protocol uri,
   "windows_uri" : (optional, string) valid http or protocol uri,
   "windows8_uri" : (optional, string) valid http or protocol uri,
   "kindle_uri" : (optional, string) valid http or protocol uri,
   "android_china_uri" : (optional, string) valid http or protocol uri,
   "web_uri" : (optional, string) valid http or protocol uri,
}

Email Object Specification

{
  "app_id": (required, string) see App Identifier above,
  "subject": (optional, string),
  "from": (required, valid email address in the format "Display Name <email@address.com>"),
  "reply_to": (optional, valid email address in the format "email@address.com" - defaults to your app group's default reply to if not set),
  "body": (required unless email_template_id is given, valid HTML),
  "plaintext_body": (optional, valid plaintext, defaults to autogenerating plaintext from "body" when this is not set),
  "preheader"*: (optional, string) Recommended length 50-100 characters.
  "email_template_id": (optional, string) If provided, we will use the subject/body values from the given email template UNLESS they are specified here, in which case we will override the provided template,
  "message_variation_id": (optional, string) used when providing a campaign_id to specify which message variation this message should be tracked under,
  "extras": (optional, valid Key Value Hash), extra hash - for SendGrid customers, this will be passed to SendGrid as Unique Arguments,
  "headers": (optional, valid Key Value Hash), hash of custom extensions headers. Currently, only supported for SendGrid customers
}

* For more information and best practices, see here.

Note: An email_template_id can be retrieved from the bottom of any Email Template created within the dashboard. Below is an example of what this ID looks like:

Email Template ID

Webhook Object Specification

{
  "url": (required, string),
  "request_method": (required, string) one of "POST", "PUT", "DELETE", or "GET",
  "request_headers": (optional, Hash) key/value pairs to use as request headers,
  "body": (optional, string) if you want to include a JSON object, make sure to escape quotes and backslashes,
  "message_variation_id": (optional, string) used when providing a campaign_id to specify which message variation this message should be tracked under
}

Server Responses

If your POST payload was accepted by our servers, then successful messages will be met with the following response:

{
  "message" : "success"
}

Note that success only means that the RESTful API payload was correctly formed and passed onto our push notification or email or other messaging services. It does not mean that the messages were actually delivered, as additional factors could prevent the message from being delivered (e.g., a device could be offline, the push token could be rejected by Apple’s servers, you may have provided an unknown user ID, etc.)

If your message is successful but has non-fatal errors you will receive the following response:

{
  "message" : "success", "errors" : [<minor error message>]
}

In the case of a success, any messages that were not affected by an error in the errors array will still be delivered. If your message has a fatal error you will receive the following response:

{
  "message" : <fatal error message>, "errors" : [<minor error message>]
}

Queued Responses

During times of maintenance, Appboy might pause real-time processing of the API. In these situations, the server will return an HTTP Accepted 202 response code and the following body, which indicates that we have received and queued the API call but have not immediately processed it. All scheduled maintenance will be posted to http://status.appboy.com ahead of time.

{
  "message" : "queued"
}

Fatal Errors

The following status codes and associated error messages will be returned if your request encounters a fatal error. Any of these error codes indicate that no messages will be sent.

  • 400 Bad Request - Bad syntax.
  • 400 No Recipients - There are no external IDs or segment IDs or no push tokens in the request
  • 400 Invalid Campaign ID - No Messaging API Campaign was found for the campaign ID you provided
  • 400 Message Variant Unspecified - You provide a campaign ID but no message variation ID
  • 400 Invalid Message Variant - You provided a valid campaign ID, but the message variation ID doesn’t match any of that campaign’s messages
  • 400 Mismatched Message Type - You provided a message variation of the wrong message type for at least one of your messages
  • 400 Invalid Extra Push Payload - You provide the “extra” key for either “apple_push” or “android_push” but it is not a dictionary
  • 400 Max input length exceeded - Caused by:
    • More than 50 external ids
  • 400 No message to send - No payload is specified for the message
  • 400 Slideup Message Length Exceeded - Slideup message > 140 characters
  • 400 Apple Push Length Exceeded - JSON payload > 1912 bytes
  • 400 Android Push Length Exceeded - JSON payload > 4000 bytes
  • 400 Bad Request - Cannot parse send_at datetime
  • 400 Bad Request - in_local_time is true but time has passed in your company’s time zone
  • 401 Unauthorized - Unknown or missing app group id
  • 403 Forbidden - Rate plan doesn’t support or account is otherwise inactivated
  • 404 Not Found - Unknown App Group ID
  • 429 Rate limited - Over rate limit
  • 5XX - Internal server error, you should retry your request with exponential backoff

Sample Requests in Various Languages

Python

Note: This request can alternatively be completed using the external library Requests.

# Necessary built-in imports to be utilized later
import json
import urllib2

# Define your static variables (app group ID, request url)
request_url = 'https://api.appboy.com/messages/send'
app_group_id = 'your app group id'

# Determine which users you want to message
external_user_ids = ['external user id 1', 'external user id 2']

# Define the content type as a dictionary
headers_params = {'Content-Type':'application/json'}

# Define the contents of your message(s)
android_noti = {"alert": "your message",
                "title": "your message title"}
apple_noti = {"alert": "your message",
              "badge": 'remaining badge count (as an integer)'}
# Instantiate your messages variable as a dictionary
messages = {"android_push" : android_noti,
            "apple_push": apple_noti}

# Store the request data as a dictionary
data = {'app_group_id': app_group_id,
        'external_user_ids': external_user_ids,
        'messages' : messages}

# CAMPAIGN TRIGGER ENDPOINT VARIABLES ONLY

request_url = 'https://api.appboy.com/campaigns/trigger/send'
campaign_id = 'your campaign id'

data = {'app_group_id': app_group_id,
        'campaign_id': campaign_id,
        'external_user_ids': external_user_ids}

# CANVAS TRIGGER ENDPOINT VARIABLES ONLY

request_url = 'https://api.appboy.com/canvas/trigger/send'
canvas_id = 'your canvas id'

data = {'app_group_id': app_group_id,
        'canvas_id': canvas_id,
        'canvas_entry_properties': {}
        'external_user_ids': external_user_ids}

# END ENDPOINT-SPECIFIC VARIABLES

# Convert the data into JSON format
JSONdata = json.dumps(data)
# Create the request
req = urllib2.Request(request_url, JSONdata, headers_params)
# Open the request
f = urllib2.urlopen(req)
# Get the response code
response = f.read()
# Close the opened request
f.close()
# Check that the request worked correctly
print response

Ruby (using REST Client & MultiJSON):

Note: This post request requires the downloading of the external gems Rest Client and MultiJSON

# Required libraries to import
require 'rest-client'
require 'multi_json'

app_group_id = 'your app group id'

# Decide which users you wish to target
external_user_ids = ['external user id 1', 'external user id 2']

# Define the content type as a hash
headers_params = {'Content-Type'=>'application/json'}

# Define the contents of your messages
android_noti = {:alert => 'your message',
                :title => 'your message title'}
apple_noti = {:alert => 'your message',
              :badge => 'remaining badge count (as an integer)'}
# Instantiate the messages array        
messages = {'android_push' => android_noti,
            'apple_push' => apple_noti}

# Organize the data to send to the API as a hash
# comprised of your previously defined variables.
data = {:app_group_id => app_group_id,
        :external_user_ids => external_user_ids,
        :messages => messages}

# CAMPAIGN TRIGGER ENDPOINT VARIABLES ONLY

request_url = 'https://api.appboy.com/campaigns/trigger/send'
campaign_id = 'your campaign id'

# Organize the data to send to the API as a hash
# comprised of your previously defined variables.
data = {:app_group_id => app_group_id,
        :campaign_id => campaign_id,
        :external_user_ids => external_user_ids}

# CANVAS TRIGGER ENDPOINT VARIABLES ONLY

request_url = 'https://api.appboy.com/canvas/trigger/send'
canvas_id = 'your canvas id'

# Organize the data to send to the API as a hash
# comprised of your previously defined variables.
data = {:app_group_id => app_group_id,
        :campaign_id => canvas_id,
        :canvas_entry_properties => {},
        :external_user_ids => external_user_ids}

# END ENDPOINT-SPECIFIC VARIABLES

# Convert the data into JSON format
JSONdata = MultiJson.encode(data)
# Send and check the POST request
puts RestClient.post(request_url, JSONdata, headers_params)

PHP

<?php
$app_group_id = 'your app group ID';

// Determine the users you plan to message
$external_user_ids = array('external user id 1', 'external user id 2');

// Establish the contents of your messages array
$android_noti = array('alert' => 'your message',
                      'title' => 'your message title');
$apple_noti = array('alert' => 'your message',
                    'badge' => 'remaining badge count (as an integer)');
// Instantiate the messages array
$messages = array('android_push' => $android_noti,
                  'apple_push' => $apple_noti);

// Organize the data to send to the API as another map
// comprised of your previously defined variables.
$postData = array(
  'app_group_id' => $app_group_id,
  'external_user_ids' => $external_user_ids,
  'messages' => $messages,
);

// CAMPAIGN TRIGGER ENDPOINT VARIABLES ONLY

$request_url = 'https://api.appboy.com/campaigns/trigger/send';
$campaign_id = 'your campaign id';

// Organize the data to send to the API as another map
// comprised of your previously defined variables.
$postData = array(
  'app_group_id' => $app_group_id,
  'campaign_id' => $campaign_id,
  'external_user_ids' => $external_user_ids,
);

// CANVAS TRIGGER ENDPOINT VARIABLES ONLY

$request_url = 'https://api.appboy.com/canvas/trigger/send';
$canvas_id = 'your canvas id';

// Organize the data to send to the API as another map
// comprised of your previously defined variables.
$postData = array(
  'app_group_id' => $app_group_id,
  'canvas_id' => $canvas_id,
  'canvas_entry_properties' => array(),
  'external_user_ids' => $external_user_ids,
);

// END ENDPOINT-SPECIFIC VARIABLES

// Create the context for the request
$context = stream_context_create(array(
    'http' => array(
        'method' => 'POST',
        'header' => "Content-Type: application/json\r\n",
        'content' => json_encode($postData)
    )
));

// Send the request
$response = file_get_contents($request_url, FALSE, $context);

// Print the response to ensure a successful request
echo $response;

?>

Email Sync

Users’ email subscription status can be updated and retrieved via Appboy using a RESTful API. You can use the API to setup bi-directional sync between Appboy and other email systems or your own database.

The examples below contain the URL https://api.appboy.com, but some customers will need to use a different endpoint URL, for example if you are hosted in Appboy’s EU data center or have a dedicated Appboy installation. Your Success Manager will inform you should use a different endpoint URL.

API Specification

All API requests are made over HTTPS. Below are the paths for each email sync endpoint:

URL HTTP Verb Functionality
/email/unsubscribes GET Retrieving Objects
/email/status POST Creating Objects
/email/bounce/remove POST Removing Objects
/email/spam/remove POST Removing Objects

Your Endpoint will correspond to your Appboy Instance.

Instance REST Endpoint
Appboy 01 https://api.appboy.com/email/
Appboy 02 https://rest-02.iad.appboy.com/email/
Appboy EU https://rest.api.appboy.eu/email/

Querying Unsubscribed Emails

GET https://api.appboy.com/email/unsubscribes

Parameter Required Data Type Description
app_group_id Yes String see App Group Identifier in Parameter Definitions
start_date No * String in YYYY-MM-DD format Start date of the range to retrieve unsubscribes, must be earlier than end_date. This is treated as midnight in UTC time by the API.
end_date No * String in YYYY-MM-DD format End date of the range to retrieve unsubscribes. This is treated as midnight in UTC time by the API.
limit No Integer Optional field to limit the number of results returned. Defaults to 100, maximum is 500.
offset No Integer Optional beginning point in the list to retrieve from
email No * String If provided, we will return whether or not the user has unsubscribed

* You must provide either an email or a start_date, and an end_date.

Note: If your date range has more than limit number of unsubscribes, you will need to make multiple API calls, each time increasing the offset until a call returns either fewer than limit or zero results.

Sample response

Entries are listed in descending order.

{
  "emails": [
    {
      "email": "foo@appboy.com",
      "unsubscribed_at": "2016-08-25 15:24:32 +0000"
    },
    {
      "email": "bar@appboy.com",
      "unsubscribed_at": "2016-08-24 17:41:58 +0000"
    },
    {
      "email": "baz@appboy.com",
      "unsubscribed_at": "2016-08-24 12:01:13 +0000"
    }
  ],
  "message": "success"
}

Querying Hard Bounced Emails

GET https://api.appboy.com/email/hard_bounces

Parameter Required Data Type Description
app_group_id Yes String see App Group Identifier in Parameter Definitions
start_date No * String in YYYY-MM-DD format Start date of the range to retrieve hard bounces, must be earlier than end_date. This is treated as midnight in UTC time by the API.
end_date No * String in YYYY-MM-DD format End date of the range to retrieve hard bounces. This is treated as midnight in UTC time by the API.
limit No Integer Optional field to limit the number of results returned. Defaults to 100, maximum is 500.
offset No Integer Optional beginning point in the list to retrieve from
email No * String If provided, we will return whether or not the user has hard bounced

* You must provide either an email or a start_date, and an end_date.

Note: If your date range has more than limit number of hard bounces, you will need to make multiple API calls, each time increasing the offset until a call returns either fewer than limit or zero results.

Sample response

Entries are listed in descending order.

{
  "emails": [
    {
      "email": "foo@appboy.com",
      "hard_bounced_at": "2016-08-25 15:24:32 +0000"
    },
    {
      "email": "bar@appboy.com",
      "hard_bounced_at": "2016-08-24 17:41:58 +0000"
    },
    {
      "email": "baz@appboy.com",
      "hard_bounced_at": "2016-08-24 12:01:13 +0000"
    }
  ],
  "message": "success"
}

Changing Email Subscription Status

POST https://api.appboy.com/email/status
Content-Type: application/json

This endpoint allows you to set the email subscription state for your users. Users can be “opted_in”, “unsubscribed”, or “subscribed” (not specifically opted in or out).

You can set the email subscription state for an email address that is not yet associated with any of your users within Appboy. When that email address is subsequently associated with a user, the email subscription state that you uploaded will be automatically set.

Parameter Required Data Type Description
app_group_id Yes String see App Group Identifier in Parameter Definitions
email Yes String or Array String email address to modify, or an Array of up to 50 email addresses to modify.
subscription_state Yes String Either “subscribed”, “unsubscribed”, or “opted_in”.

Removing Hard Bounces

POST https://api.appboy.com/email/bounce/remove
Content-Type: application/json

This endpoint allows you to remove email addresses from your Appboy bounce list. We will also remove them from the bounce list maintained by your email provider.

Parameter Required Data Type Description
app_group_id Yes String see App Group Identifier in Parameter Definitions
email Yes String or Array String email address to modify, or an Array of up to 50 email addresses to modify.

Removing Spam

This endpoint allows you to remove email addresses from your Appboy spam list. We will also remove them from the spam list maintained by your email provider.

POST https://api.appboy.com/email/spam/remove
Content-Type: application/json
Parameter Required Data Type Description
app_group_id Yes String see App Group Identifier in Parameter Definitions
email Yes String or Array String email address to modify, or an Array of up to 50 email addresses to modify.

Example Unsubscribe CURL

The following example CURL demonstrates how to unsubscribe a user from receiving email via the Appboy APIs:

curl -X POST -H "Content-Type: application/json" -d '{"app_group_id":"YOUR_APP_GROUP_ID","email":"EMAIL_TO_UNSUBSCRIBE","subscription_state":"unsubscribed"}' https://api.appboy.com/email/status

Export

The examples below contain the URL https://api.appboy.com, but some customers will need to use a different endpoint URL, for example if you are hosted in Appboy’s EU data center or have a dedicated Appboy installation. Your Success Manager will inform you should use a different endpoint URL.

User Export

Users by UserID Endpoint

This endpoint allows you to export data from any user profile by specifying their external identifier (UserID). Up to 50 external_ids can be included in a single request.

Instance REST Endpoint
Appboy 01 https://api.appboy.com/users/export/ids
Appboy 02 https://rest-02.iad.appboy.com/users/export/ids
Appboy EU https://rest.api.appboy.eu/users/export/ids
POST https://api.appboy.com/users/export/ids
Content-Type: application/json
{
    "app_group_id" : (required, string) App Group API Identifier,
    // Either "external_ids" or "user_aliases" are required. Requests must specify only one.
    "external_ids" : (optional, array of string) external ids for users to export,
    "user_aliases" : (optional, array of User Alias Object) user aliases for users to export,
    "fields_to_export" : (optional, array of string) name of user data fields to export, e.g. ['first_name', 'email', 'purchases'], defaults to all if not provided
}

Users by UserID Endpoint API Response:

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "users" : (optional, array of object) the data for each of the exported users,
    "invalid_user_ids" : (optional, array of string) each of the identifiers provided in the request that did not correspond to a known user
}

For an example of the data that is accessible via this endpoint see the Sample User Export Output section of this documentation.

Users by UserID Example CURL

curl -X POST -H "Content-Type: application/json" -d '{"app_group_id":"YOUR_APP_GROUP_ID_FROM_DEVELOPER_CONSOLE","external_ids":["external_id1", "external_id2"],"fields_to_export": ["field1", "field2"]}' https://api.appboy.com/users/export/ids

Users by Segment Endpoint

This endpoint allows you to export all the users within a segment. User data is exported as multiple files of user JSON objects separated by new lines (i.e. one JSON object per line).

If you have added your S3 credentials to Appboy, then each file will be uploaded in your bucket as a zip file with the key format that looks like “segment-export/SEGMENT_ID/YYYY-MM-dd/RANDOM_UUID-TIMESTAMP_WHEN_EXPORT_STARTED/filename.zip”. We will create 1 file per 5,000 users to optimize processing. You can then unzip the files and concatenate all of the csv files to a single file if needed. If you specify an output_format of gzip, then the file extension will be .gz instead of .zip.

If you do not have S3 credentials provided, the response to the request provides the url where a zip file containing all the user files can be downloaded. The URL will only become a valid location once the export is ready. Please be aware that if you do not have S3 credentials, there is a limitation on the amount of data that you can export from this endpoint. In most cases this limit is about 5 gigabytes, which is usually around 500,000 to 1 million user profiles. In the event that you have not added S3 credentials and you attempt to export a segment that is too large, Appboy will notify the person who last edited the segment that you must provide S3 credentials in order to export the segment.

In either scenario, you may optionally provide a callback_endpoint to be notified when the export is ready. If the callback_endpoint is provided, we will make a post request to the provided address when the download is ready. The body of the post will be “success”:true. If you have not added S3 credentials to Appboy, then the body of the post will additionally have the attribute “url” with the download url as the value.

Larger user bases will result in longer export times. For example, an app with 20 million users could take an hour or more.

Instance REST Endpoint
Appboy 01 https://api.appboy.com/users/export/segment
Appboy 02 https://rest-02.iad.appboy.com/users/export/segment
Appboy EU https://rest.api.appboy.eu/users/export/segment
POST https://api.appboy.com/users/export/segment
Content-Type: application/json
{
    "app_group_id" : (required, string) App Group API Identifier,
    "segment_id" : (required, string) identifier for the segment to be exported,
    "callback_endpoint" : (optional, string) endpoint to post a download url to when the export is available,
    "fields_to_export" : (optional, array of string) name of user data fields to export, e.g. ['first_name', 'email', 'purchases'], defaults to all if not provided,
    "output_format" : (optional, string) When using your own S3 bucket, allows to specify file format as 'zip' or 'gzip'. Defaults to zip file format
}

Note: The segment_id for a given segment can be found on our Developer Console within your dashboard or you can use the Segment List Endpoint.

Users by Segment Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "object_prefix": (required, string) the filename prefix that will be used for the JSON file produced by this export, e.g. 'bb8e2a91-c4aa-478b-b3f2-a4ee91731ad1-1464728599',
    "url" : (optional, string) the url where the segment export data can be downloaded if you do not have your own S3 credentials
}

Note: Once made available, the url will only be valid for a few hours. As such, we highly recommend that you add your own S3 credentials to Appboy.

Users by Segment Example CURL

curl -X POST -H "Content-Type: application/json" -d '{"app_group_id":"YOUR_APP_GROUP_ID_FROM_DEVELOPER_CONSOLE","segment_id":"INSERT_SEGMENT_ID_HERE","fields_to_export": ["field1", "field2"]}' https://api.appboy.com/users/export/segment

Sample User Export File Output

User export object (we will include the least data possible - if a field is missing from the object it should be assumed to be null, false, or empty):

{
    "external_id" : (string),
    "user_aliases" : [
      {
        "alias_name" : (string),
        "alias_label" : (string)
      }
    ],
    "appboy_id": (string),
    "first_name" : (string),
    "last_name" : (string),
    "email" : (string),
    "dob" : (string) date for the user's date of birth,
    "home_city" : (string),
    "country" : (string),
    "phone" : (string),
    "language" : (string) ISO-639 two letter code,
    "time_zone" : (string),
    "last_coordinates" : (array of float) [lon, lat],
    "gender" : (string) "M" | "F",
    "total_revenue" : (float),
    "attributed_campaign" : (string),
    "attributed_source" : (string),
    "attributed_adgroup" : (string),
    "attributed_ad" : (string),
    "push_subscribe" : (string) "opted_in" | "subscribed" | "unsubscribed",
    "email_subscribe" : (string) "opted_in" | "subscribed" | "unsubscribed",
    "custom_attributes" : (object) custom attribute key value pairs,
    "custom_events" : [
        {
            "name" : (string),
            "first" : (string) date,
            "last" : (string) date,
            "count" : (int)
        },
        ...
    ],
    "purchases" : [
        {
            "name" : (string),
            "first" : (string) date,
            "last" : (string) date,
            "count" : (int)
        },
        ...
    ],
    "devices" : [
        {
            "model" : (string),
            "os" : (string),
            "carrier" : (string),
            "idfv" : (string) only included for iOS devices,
            "idfa" : (string) only included for iOS devices when IDFA collection is enabled,
            "ad_tracking_enabled" : (bool)
        },
        ...
    ],
    "push_tokens" : [
        {
            "app" : (string) app name,
            "platform" : (string),
            "token" : (string)
        },
        ...
    ],
    "apps" : [
        {
            "name" : (string),
            "platform" : (string),
            "version" : (string),
            "sessions" : (string),
            "first_used" : (string) date,
            "last_used" : (string) date
        },
        ...
    ],
    "campaigns_received" : [
        {
            "name" : (string),
            "last_received" : (string) date,
            "engaged" : {
                "opened_email" : (bool),
                "opened_push" : (bool),
                "clicked_email" : (bool),
                "clicked_in_app_message" : (bool)
            },
            "converted" : (bool),
            "api_campaign_id" : (string),
            "variation_name" : (optional, string) exists only if it is a multivariate campaign,
            "variation_api_id" : (optional, string) exists only if it is a multivariate campaign,
            "in_control" : (optional, bool) exists only if it is a multivariate campaign
        },
        ...
    ],
    "cards_clicked" : [
        {
            "name" : (string)
        },
        ...
    ]
}

Segment Export

Segment List Endpoint

This endpoint allows you to export a list of segments, each of which will include it’s name, Segment API Identifier, and whether it has analytics tracking enabled. The segments are returned in groups of 100 sorted by time of creation (oldest to newest by default). Archived segments are not included.

GET https://api.appboy.com/segments/list

Instance REST Endpoint
Appboy 01 https://api.appboy.com/segments/list
Appboy 02 https://rest-02.iad.appboy.com/segments/list
Appboy EU https://rest.api.appboy.eu/segments/list
Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
page No Integer The page of segments to return, defaults to 0 (returns the first set of up to 100)
sort No Integer Pass the value -1 to sort by creation time from newest to oldest

Example URL: https://api.appboy.com/segments/list?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&page=1

Segment List Endpoint API Response:

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "segments" : [
        {
            "id" : (string) Segment API Identifier,
            "name" : (string) segment name,
            "analytics_tracking_enabled" : (boolean) whether the segment has analytics tracking enabled,
            "tags" : (array) tag names associated with the segment
        },
        ...
    ]
}

Segment Analytics Endpoint

This endpoint allows you to retrieve a daily series of the size of a segment over time for a segment with analytics tracking enabled.

GET https://api.appboy.com/segments/data_series

Instance REST Endpoint
Appboy 01 https://api.appboy.com/segments/data_series
Appboy 02 https://rest-02.iad.appboy.com/segments/data_series
Appboy EU https://rest.api.appboy.eu/segments/data_series
Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
segment_id Yes String Segment API Identifier
length Yes Integer Max number of days before ending_at to include in the returned series - must be between 1 and 100 inclusive
ending_at No DateTime (ISO 8601 string) Point in time when the data series should end - defaults to time of the request

Note: The segment_id for a given segment can be found on our Developer Console within your dashboard or you can use the Segment List Endpoint.

Example URL: https://api.appboy.com/segments/data_series?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&segment_id=3bbc4555-8fa0-4c9b-a5c0-4505edf3e064&length=7&ending_at=2014-12-10T23:59:59-05:00

Segment Analytics Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "data" : [
        {
            "time" : (string) date as ISO 8601 date,
            "size" : (int) size of the segment on that date
        },
        ...
    ]
}

Segment Details Endpoint

This endpoint allows you to retrieve relevant information on the segment, which can be identified by the segment_id.

GET https://api.appboy.com/segments/details

Instance REST Endpoint
Appboy 01 https://api.appboy.com/segments/details
Appboy 02 https://rest-02.iad.appboy.com/segments/details
Appboy EU https://rest.api.appboy.eu/segments/details
Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
segment_id Yes String Segment API Identifier

Note: The segment_id for a given segment can be found on our Developer Console within your dashboard or you can use the Segment List Endpoint.

Example URL: https://api.appboy.com/segments/details?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&segment_id=3bbc4555-8fa0-4c9b-a5c0-4505edf3e064

Segment Details Endpoint API Response

Content-Type: application/json
{
      "message": (required, string) the status of the export, returns 'success' when completed without errors,
      "created_at" : (string) date created as ISO 8601 date,
      "updated_at" : (string) date last updated as ISO 8601 date,
      "name" : (string) segment name,
      "description" : (string) human-readable description of filters,
      "tags" : (array) tag names associated with the segment
}

Campaign Export

Campaign List Endpoint

This endpoint allows you to export a list of campaigns, each of which will include its name, Campaign API Identifier, whether it is an API Campaign, and Tags associated with the campaign. The campaigns are returned in groups of 100 sorted by time of creation (oldest to newest by default).

Note: Archived campaigns will not be included in the API response unless include_archived is specified. Paused campaigns, however, will be returned by default.

GET https://api.appboy.com/campaigns/list

Instance REST Endpoint
Appboy 01 https://api.appboy.com/campaigns/list
Appboy 02 https://rest-02.iad.appboy.com/campaigns/list
Appboy EU https://rest.api.appboy.eu/campaigns/list
Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
page No Integer The page of campaigns to return, defaults to 0 (returns the first set of up to 100)
include_archived No Boolean Whether or not to include archived campaigns, defaults to false
sort No Integer Pass the value -1 to sort by creation time from newest to oldest

Example URL: https://api.appboy.com/campaigns/list?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&page=1&include_archived=true

Campaign List Endpoint API Response:

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "campaigns" : [
        {
            "id" : (string) Campaign API Identifier,
            "name" : (string) campaign name,
            "is_api_campaign" : (boolean) whether the campaign is an API Campaign,
            "tags" : (array) tag names associated with the campaign
        },
        ...
    ]
}

Campaign Analytics Endpoint

This endpoint allows you to retrieve a daily series of various stats for a campaign over time.

GET https://api.appboy.com/campaigns/data_series

Instance REST Endpoint
Appboy 01 https://api.appboy.com/campaigns/data_series
Appboy 02 https://rest-02.iad.appboy.com/campaigns/data_series
Appboy EU https://rest.api.appboy.eu/campaigns/data_series
Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
campaign_id Yes String Campaign API Identifier
length Yes Integer Max number of days before ending_at to include in the returned series - must be between 1 and 100 inclusive
ending_at No DateTime (ISO 8601 string) Date on which the data series should end - defaults to time of the request

Note: The campaign_id for API campaigns can be found on the Developer Console page and the campaign details page within your dashboard or you can use the Campaign List Endpoint.

Example URL: https://api.appboy.com/campaigns/data_series?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&campaign_id=3bbc4555-8fa0-4c9b-a5c0-4505edf3e064&length=7&ending_at=2014-12-10T23:59:59-05:00

Campaign Analytics Endpoint API Response

Multi-channel Response
Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "data" : [
        {
            "time" : (string) date as ISO 8601 date,
            "conversions" : (int),
            "revenue": (float),
            "conversions_by_send_time": (int),
            "messages" : {
                "email" : [
                    {
                        "sent" : (int),
                        "opens" : (int),
                        "unique_opens" : (int),
                        "clicks" : (int),
                        "unique_clicks" : (int),
                        "unsubscribes" : (int),
                        "bounces_including_dropped" : (int),
                        "delivered" : (int),
                        "reported_spam" : (int)
                    },
                    ...
                ],
                "in_app_message" : [
                    {
                        "sent" : (int),
                        "impressions" : (int),
                        "opens" : (int)
                    },
                    ...
                ],
                "android_push" : [
                    {
                        "sent" : (int),
                        "direct_opens" : (int),
                        "total_opens" : (int),
                        "bounces" : (int)
                    },
                    ...
                ],
                ...
            }
        },
        ...
    ]
}
Multi-variate Response
Content-Type: application/json
{
    "data" : [
        {
            "time" : (string) date as ISO 8601 date,
            "conversions" : (int),
            "revenue": (float),
            "conversions_by_send_time": (int),
            "messages" : {
                "android_push" : [
                    {
                        "variation_name" : (optional, string),
                        "sent" : (int),
                        "direct_opens" : (int),
                        "total_opens" : (int),
                        "bounces" : (int),
                        "unique_recipients" (int),
                        "conversions" : (optional, int),
                        "revenue" : (optional, float),
                        "conversions_by_send_time" : (optional, int)
                    },
                    {
                        "variation_name" : (optional, string),
                        "sent" : (int),
                        "direct_opens" : (int),
                        "total_opens" : (int),
                        "bounces" : (int),
                        "unique_recipients" (int),
                        "conversions" : (optional, int),
                        "revenue" : (optional, float),
                        "conversions_by_send_time" : (optional, int)
                    },
                    {
                        "variation_name" : "Control Group",
                        "enrolled" : (int),
                        "unique_recipients" (int),
                        "conversions" : (optional, int),
                        "revenue" : (optional, float),
                        "conversions_by_send_time" : (optional, int)
                    },
                    ...
                ],
                ...
            }
        },
        ...
    ]
}

Possible message types are email, in_app_message, android_push, apple_push, kindle_push, windows_phone8_push, and windows_universal_push. All push message types will have the same statistics shown for android_push above.

Campaign Details Endpoint

This endpoint allows you to retrieve relevant information on the campaign, which can be identified by the campaign_id.

GET https://api.appboy.com/campaigns/details

Instance REST Endpoint
Appboy 01 https://api.appboy.com/campaigns/details
Appboy 02 https://rest-02.iad.appboy.com/campaigns/details
Appboy EU https://rest.api.appboy.eu/campaigns/details
Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
campaign_id Yes String Campaign API Identifier

Note: The campaign_id for API campaigns can be found on the Developer Console page and the campaign details page within your dashboard or you can use the Campaign List Endpoint.

Example URL: https://api.appboy.com/campaigns/details?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&campaign_id=3bbc4555-8fa0-4c9b-a5c0-4505edf3e064

Campaign Details Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "created_at" : (string) date created as ISO 8601 date,
    "updated_at" : (string) date last updated as ISO 8601 date,
    "name" : (string) campaign name,
    "schedule_type" : (string) type of scheduling action,
    "channels" : (array) list of channels to send via,
    "first_sent" : (string) date and hour of first sent as ISO 8601 date,
    "last_sent" : (string) date and hour of last sent as ISO 8601 date,
    "tags" : (array) tag names associated with the campaign,
    "messages": {
        "message_variation_id" (string) => {
            "channel": (string) channel type of the message (eg., "email", "ios_push", "webhook"),
            "name": (string) name of the message in the Dashboard (eg., "Variation 1")
            ... channel-specific fields for this message, see below ...
        }
    }
}

The messages hash will contain information about each message. Example message responses for channels are below:

Push Channels

{
    "channel": (string) description of the channel, such as "ios_push" or "android_push"
    "alert": (string) alert body text,
    "extras": (hash) any key-value pairs provided
}

Email Channel

{
    "channel": "email"
    "subject": (string) subject,
    "body": (string) HTML body (truncated after 10kb),
    "from": (string) from address and display name,
    "reply_to": (string) reply-to for message, if different than "from" address,
    "title": (string) name of the email,
    "extras": (hash) any key-value pairs provided
}

Webhook Channel

{
    "channel": "webhook"
    "url": (string) url for webhook,
    "body": (string) payload body,
    "type": (string) body content type,
    "headers": (hash) specified request headers,
    "method": (string) HTTP method (e.g., "POST" or "GET"),
}

Control Messages

{
    "channel": (string) description of the channel that the control is for
    "type": "control"
}

Canvas Data Export

Canvas List Endpoint

This endpoint allows you to export a list of Canvases, including the name, Canvas API Identifier and associated Tags. The Canvases are returned in groups of 100 sorted by time of creation (oldest to newest by default).

Note: Archived Canvases will not be included in the API response unless the include_archived field is specified. Canvases that are stopped but not archived, however, will be returned by default.

Endpoint Details

GET https://api.appboy.com/canvas/list

Instance REST Endpoint
Appboy 01 https://api.appboy.com/canvas/list
Appboy 02 https://rest-02.iad.appboy.com/canvas/list
Appboy EU https://rest.api.appboy.eu/canvas/list
Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
page No Integer The page of Canvases to return, defaults to 0 (returns the first set of up to 100)
include_archived No Boolean Whether or not to include archived Canvases, defaults to false
sort No Integer -1 if returning list sorted by time of creation from newest to oldest, defaults to sorting oldest to newest
{
  "canvases" : [
  	{
  		"id" : (string) Canvas API Identifier,
  		"name" : (string) Canvas name,
  		"tags" : (array) tag names associated with the Canvas,
  	},
    ... (more Canvases)
  ],
  "message": (required, string) the status of the export, returns 'success' when completed without errors
}

Canvas Details Endpoint

This endpoint allows you to export metadata about a Canvas, such as its name, when it was created, its current status, and more.

Endpoint Details

GET https://api.appboy.com/canvas/details

Instance REST Endpoint
Appboy 01 https://api.appboy.com/canvas/details
Appboy 02 https://rest-02.iad.appboy.com/canvas/details
Appboy EU https://rest.api.appboy.eu/canvas/details
Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
canvas_id Yes String Canvas API Identifier
{
  "created_at": (string) date created as ISO 8601 date,
  "updated_at": (string) date updated as ISO 8601 date,
  "name": (string) Canvas name,
  "archived": (boolean) whether Canvas is archived,
  "schedule_type": (string) type of scheduling action,
  "first_entry": (string) date of first entry as ISO 8601 date,
  "last_entry": (string) date of last entry as ISO 8601 date,
  "channels": (array of strings) step channels used with Canvas,
  "variants": [
    {
      "name": (string) name of variant,
      "first_step_id": (string) api identifier of first step in variant,
    },
    ... (more variations)
  ],
  "tags": (array of strings) tag names associated with the Canvas,
  "steps": [
    {
      "name": (string) name of step,
      "id": (string) api identifier of the step,
      "next_step_ids": (array of strings) api identifiers of steps following step,
      "channels": (array of strings) channels used in step,
    },
    ... (more steps)
  ],
  "message": (required, string) the status of the export, returns 'success' when completed without errors
}

Canvas Data Series Endpoint

This endpoint allows you to export time series data for a Canvas.

Endpoint Details

GET https://api.appboy.com/canvas/data_series

Instance REST Endpoint
Appboy 01 https://api.appboy.com/canvas/data_series
Appboy 02 https://rest-02.iad.appboy.com/canvas/data_series
Appboy EU https://rest.api.appboy.eu/canvas/data_series
Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
canvas_id Yes String Canvas API Identifier
ending_at Yes DateTime (ISO 8601 string) Date on which the data export should end - defaults to time of the request
starting_at No DateTime (ISO 8601 string) Date on which the data export should begin (either length or starting_at are required)
length No String Max number of days before ending_at to include in the returned series - must be between 1 and 14 inclusive (either length or starting_at required)
include_variant_breakdown No Boolean Whether or not to include variant stats (defaults to false)
include_step_breakdown No Boolean Whether or not to include step stats (defaults to false)
include_deleted_step_data No Boolean Whether or not to include step stats for deleted steps (defaults to false)
{
  "data": {
    "name": (string) Canvas name,
    "stats": [
      {
        "time": (string) date as ISO 8601 date,
        "total_stats": {
          "revenue": (float),
          "conversions": (int),
          "conversions_by_entry_time": (int),
          "entries": (int)
        },
        "variant_stats": (optional) {
          "00000000-0000-0000-0000-0000000000000": (api identifier for variant) {
            "name": (string) name of variant,
            "revenue": (int),
            "conversions": (int),
            "conversions_by_entry_time": (int),
            "entries": (int)
          },
          ... (more variants)
        },
        "step_stats": (optional) {
          "00000000-0000-0000-0000-0000000000000": (api identifier for step) {
            "name": (string) name of step,
            "revenue": (float),
            "conversions": (int),
            "conversions_by_entry_time": (int),
            "messages": {
              "email": [
                {
                  "sent": (int),
                  "opens": (int),
                  "unique_opens": (int),
                  "clicks": (int),
                  ... (more stats)
                }
              ],
              ... (more channels)
            }
          },
          ... (more steps)
        }
      },
      ... (more stats by time)
    ]
  },
  "message": (required, string) the status of the export, returns 'success' when completed without errors
}

Canvas Data Summary Endpoint

This endpoint allows you to export rollups of time series data for a Canvas, providing a concise summary of a Canvas’ results.

Endpoint Details

GET https://api.appboy.com/canvas/data_summary

Instance REST Endpoint
Appboy 01 https://api.appboy.com/canvas/data_summary
Appboy 02 https://rest-02.iad.appboy.com/canvas/data_summary
Appboy EU https://rest.api.appboy.eu/canvas/data_summary
Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
canvas_id Yes String Canvas API Identifier
ending_at Yes DateTime (ISO 8601 string) Date on which the data export should end - defaults to time of the request
starting_at No DateTime (ISO 8601 string) Date on which the data export should begin (either length or starting_at required)
length No String Max number of days before ending_at to include in the returned series - must be between 1 and 14 inclusive (either length or starting_at required)
include_variant_breakdown No Boolean Whether or not to include variant stats (defaults to false)
include_step_breakdown No Boolean Whether or not to include step stats (defaults to false)
include_deleted_step_data No Boolean Whether or not to include step stats for deleted steps (defaults to false)
{
  "data": {
    "name": (string) Canvas name,
    "total_stats": {
      "revenue": (float),
      "conversions": (int),
      "conversions_by_entry_time": (int),
      "entries": (int)
    },
    "variant_stats": (optional) {
      "00000000-0000-0000-0000-0000000000000": (api identifier for variant) {
        "name": (string) name of variant,
        "revenue": (float),
        "conversions": (int),
        "entries": (int)
      },
      ... (more variants)
    },
    "step_stats": (optional) {
      "00000000-0000-0000-0000-0000000000000": (api identifier for step) {
        "name": (string) name of step,
        "revenue": (float),
        "conversions": (int),
        "conversions_by_entry_time": (int),
        "messages": {
          "android_push": (name of channel) [
            {
              "sent": (int),
              "opens": (int),
              "influenced_opens": (int),
              "bounces": (int)
              ... (more stats for channel)
            }
          ],
          ... (more channels)
        }
      },
      ... (more steps)
    }
  },
  "message": (required, string) the status of the export, returns 'success' when completed without errors
}

News Feed Export

News Feed List Endpoint

This endpoint allows you to export a list of news feed cards, each of which will include it’s name and Card API Identifier. The cards are returned in groups of 100 sorted by time of creation (oldest to newest by default).

GET https://api.appboy.com/feed/list

Instance REST Endpoint
Appboy 01 https://api.appboy.com/feed/list
Appboy 02 https://rest-02.iad.appboy.com/feed/list
Appboy EU https://rest.api.appboy.eu/feed/list
Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
page No Integer The page of cards to return, defaults to 0 (returns the first set of up to 100)
include_archived No Boolean Whether or not to include archived cards, defaults to false
sort No Integer Pass the value -1 to sort by creation time from newest to oldest

Example URL: https://api.appboy.com/feed/list?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&page=1&include_archived=true

News Feed List Endpoint API Response:

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "cards" : [
        {
            "id" : (string) Card API Identifier,
            "type" : (string) type of the card - NewsItem (classic cards), CaptionedImage, Banner or DevPick (cross-promotional cards),
            "title" : (string) title of the card,
            "tags" : (array) tag names associated with the card
        },
        ...
    ]
}

News Feed Analytics Endpoint

This endpoint allows you to retrieve a daily series of engagement stats for a card over time.

GET https://api.appboy.com/feed/data_series

Instance REST Endpoint
Appboy 01 https://api.appboy.com/feed/data_series
Appboy 02 https://rest-02.iad.appboy.com/feed/data_series
Appboy EU https://rest.api.appboy.eu/feed/data_series
Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
card_id Yes String Card API Identifier
length Yes Integer Max number of units (days or hours) before ending_at to include in the returned series - must be between 1 and 100 inclusive
unit No String Unit of time between data points - can be “day” or “hour” (defaults to “day”)
ending_at No DateTime (ISO 8601 string) Date on which the data series should end - defaults to time of the request

Note: The card_id for a given card can be found the Developer Console page and on the card details page within your dashboard or you can use the News Feed List Endpoint.

Example URL: https://api.appboy.com/feed/data_series?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&card_id=3bbc4555-8fa0-4c9b-a5c0-4505edf3e064&length=24&unit=hour&ending_at=2014-12-10T23:59:59-05:00

News Feed Analytics Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "data" : [
        {
            "time" : (string) point in time - as ISO 8601 extended when unit is "hour" and as ISO 8601 date when unit is "day",
            "clicks" : (int) ,
            "impressions" : (int),
            "unique_clicks" : (int),
            "unique_impressions" : (int)
        },
        ...
    ]
}

News Feed Details Endpoint

This endpoint allows you to retrieve relevant information on the card, which can be identified by the card_id.

GET https://api.appboy.com/feed/details

Instance REST Endpoint
Appboy 01 https://api.appboy.com/feed/details
Appboy 02 https://rest-02.iad.appboy.com/feed/details
Appboy EU https://rest.api.appboy.eu/feed/details
Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
card_id Yes String Card API Identifier

Note: The card_id for a given card can be found the Developer Console page and on the card details page within your dashboard or you can use the News Feed List Endpoint.

Example URL: https://api.appboy.com/feed/details?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&card_id=3bbc4555-8fa0-4c9b-a5c0-4505edf3e064

News Feed Details Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) The status of the export, returns 'success' when completed without errors,
    "created_at" : (string) Date created as ISO 8601 date,
    "updated_at" : (string) Date last updated as ISO 8601 date,
    "name" : (string) Card name,
    "publish_at" : (string) Date card was published as ISO 8601 date,
    "end_at" : (string) Date card will stop displaying for users as ISO 8601 date,
    "tags" : (array) Tag names associated with the card,
    "title" : (string) Title of the card,
    "image_url" : (string) Image URL used by this card,
    "extras" : (dictionary) Dictionary containing key-value pair data attached to this card,
    "description" : (string) Description text used by this card
}

KPI Export

Monthly Active Users Endpoint

This endpoint allows you to retrieve a daily series of the total number of unique active users over a 30 day rolling window.

GET https://api.appboy.com/kpi/mau/data_series

Instance REST Endpoint
Appboy 01 https://api.appboy.com/kpi/mau/data_series
Appboy 02 https://rest-02.iad.appboy.com/kpi/mau/data_series
Appboy EU https://rest.api.appboy.eu/kpi/mau/data_series
Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
length Yes Integer Max number of days before ending_at to include in the returned series - must be between 1 and 100 inclusive
ending_at No DateTime (ISO 8601 string) Point in time when the data series should end - defaults to time of the request
app_id No String App API Identifier; if excluded, results for all apps in app group will be returned

Example URL: https://api.appboy.com/kpi/mau/data_series?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&length=7&ending_at=2014-12-10T23:59:59-05:00

Monthly Active Users Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "data" : [
        {
            "time" : (string) date as ISO 8601 date,
            "mau" : (int)
        },
        ...
    ]
}

Daily Active Users Endpoint

This endpoint allows you to retrieve a daily series of the total number of unique active users on each date.

GET https://api.appboy.com/kpi/dau/data_series

Instance REST Endpoint
Appboy 01 https://api.appboy.com/kpi/dau/data_series
Appboy 02 https://rest-02.iad.appboy.com/kpi/dau/data_series
Appboy EU https://rest.api.appboy.eu/kpi/dau/data_series
Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
length Yes Integer Max number of days before ending_at to include in the returned series - must be between 1 and 100 inclusive
ending_at No DateTime (ISO 8601 string) Point in time when the data series should end - defaults to time of the request
app_id No String App API Identifier; if excluded, results for all apps in app group will be returned

Example URL: https://api.appboy.com/kpi/dau/data_series?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&length=7&ending_at=2014-12-10T23:59:59-05:00

Daily Active Users Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "data" : [
        {
            "time" : (string) date as ISO 8601 date,
            "dau" : (int)
        },
        ...
    ]
}

New Users Endpoint

This endpoint allows you to retrieve a daily series of the total number of new users on each date.

GET https://api.appboy.com/kpi/new_users/data_series

Instance REST Endpoint
Appboy 01 https://api.appboy.com/kpi/new_users/data_series
Appboy 02 https://rest-02.iad.appboy.com/kpi/new_users/data_series
Appboy EU https://rest.api.appboy.eu/kpi/new_users/data_series
Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
length Yes Integer Max number of days before ending_at to include in the returned series - must be between 1 and 100 inclusive
ending_at No DateTime (ISO 8601 string) Point in time when the data series should end - defaults to time of the request
app_id No String App API Identifier; if excluded, results for all apps in app group will be returned

Example URL: https://api.appboy.com/kpi/new_users/data_series?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&length=7&ending_at=2014-12-10T23:59:59-05:00

New Users Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "data" : [
        {
            "time" : (string) date as ISO 8601 date,
            "new_users" : (int)
        },
        ...
    ]
}

Uninstalls Endpoint

This endpoint allows you to retrieve a daily series of the total number of uninstalls on each date.

GET https://api.appboy.com/kpi/uninstalls/data_series

Instance REST Endpoint
Appboy 01 https://api.appboy.com/kpi/uninstalls/data_series
Appboy 02 https://rest-02.iad.appboy.com/kpi/uninstalls/data_series
Appboy EU https://rest.api.appboy.eu/kpi/uninstalls/data_series
Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
length Yes Integer Max number of days before ending_at to include in the returned series - must be between 1 and 100 inclusive
ending_at No DateTime (ISO 8601 string) Point in time when the data series should end - defaults to time of the request
app_id No String App API Identifier; if excluded, results for all apps in app group will be returned

Example URL: https://api.appboy.com/kpi/uninstalls/data_series?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&length=7&ending_at=2014-12-10T23:59:59-05:00

Uninstalls Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "data" : [
        {
            "time" : (string) date as ISO 8601 date,
            "uninstalls" : (int)
        },
        ...
    ]
}

Sessions Analytics Export

Sessions Series Endpoint

This endpoint allows you to retrieve a series of the number of sessions for your app over a designated time period.

GET https://api.appboy.com/sessions/data_series

Instance REST Endpoint
Appboy 01 https://api.appboy.com/sessions/data_series
Appboy 02 https://rest-02.iad.appboy.com/sessions/data_series
Appboy EU https://rest.api.appboy.eu/sessions/data_series
Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
length Yes Integer Max number of units (days or hours) before ending_at to include in the returned series - must be between 1 and 100 inclusive
unit No String Unit of time between data points - can be “day” or “hour” (defaults to “day”)
ending_at No DateTime (ISO 8601 string) Point in time when the data series should end - defaults to time of the request
app_id No String App API Identifier retrieved from the Developer Console to limit analytics to a specific app
segment_id No String Segment API Identifier indicating the analytics enabled segment for which sessions should be returned

Example URL: https://api.appboy.com/sessions/data_series?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&length=24&unit=hour&ending_at=2014-12-10T23:59:59-05:00&app_id=3bbc4555-8fa0-4c9b-a5c0-4505edf3e064

Sessions Series Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "data" : [
        {
            "time" : (string) point in time - as ISO 8601 extended when unit is "hour" and as ISO 8601 date when unit is "day",
            "sessions" : (int)
        },
        ...
    ]
}

Custom Events Analytics Export

Custom Events List Endpoint

This endpoint allows you to export a list of custom events that have been recorded for your app. The event names are returned in groups of 250, sorted alphabetically.

GET https://api.appboy.com/events/list

Instance REST Endpoint
Appboy 01 https://api.appboy.com/events/list
Appboy 02 https://rest-02.iad.appboy.com/events/list
Appboy EU https://rest.api.appboy.eu/events/list
Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
page No Integer The page of event names to return, defaults to 0 (returns the first set of up to 250)

Example URL: https://api.appboy.com/events/list?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&page=1

Custom Events List Endpoint API Response:

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "events" : [
        "Event A",
        "Event B",
        "Event C",
        ...
    ]
}

Custom Events Series Endpoint

This endpoint allows you to retrieve a series of the number of occurrences of a custom event in your app over a designated time period.

GET https://api.appboy.com/events/data_series

Instance REST Endpoint
Appboy 01 https://api.appboy.com/events/data_series
Appboy 02 https://rest-02.iad.appboy.com/events/data_series
Appboy EU https://rest.api.appboy.eu/events/data_series
Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
event Yes String The name of the custom event for which to return analytics
length Yes Integer Max number of units (days or hours) before ending_at to include in the returned series - must be between 1 and 100 inclusive
unit No String Unit of time between data points - can be “day” or “hour” (defaults to “day”)
ending_at No DateTime (ISO 8601 string) Point in time when the data series should end - defaults to time of the request
app_id No String App API Identifier retrieved from the Developer Console to limit analytics to a specific app
segment_id No String Segment API Identifier indicating the analytics enabled segment for which event analytics should be returned

Example URL: https://api.appboy.com/events/data_series?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&event=Event%20A&length=24&unit=hour&ending_at=2014-12-10T23:59:59-05:00&app_id=3bbc4555-8fa0-4c9b-a5c0-4505edf3e064

Custom Events Series Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "data" : [
        {
            "time" : (string) point in time - as ISO 8601 extended when unit is "hour" and as ISO 8601 date when unit is "day",
            "count" : (int)
        },
        ...
    ]
}

Revenue Analytics Export

Products List Endpoint

This endpoint allows you to export a list of products that have been purchased in your app. The product names are returned in groups of 250, sorted alphabetically.

GET https://api.appboy.com/purchases/product_list

Instance REST Endpoint
Appboy 01 https://api.appboy.com/purchases/product_list
Appboy 02 https://rest-02.iad.appboy.com/purchases/product_list
Appboy EU https://rest.api.appboy.eu/purchases/product_list
Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
page No Integer The page of product names to return, defaults to 0 (returns the first set of up to 250)

Example URL: https://api.appboy.com/purchases/product_list?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&page=1

Products List Endpoint API Response:

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "products" : [
        "Product A",
        "Product B",
        "Product C",
        ...
    ]
}

Revenue Series Endpoint

This endpoint allows you to retrieve a series of the money spent in your app over a designated time period.

GET https://api.appboy.com/purchases/revenue_series

Instance REST Endpoint
Appboy 01 https://api.appboy.com/purchases/revenue_series
Appboy 02 https://rest-02.iad.appboy.com/purchases/revenue_series
Appboy EU https://rest.api.appboy.eu/purchases/revenue_series
Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
length Yes Integer Max number of units (days or hours) before ending_at to include in the returned series - must be between 1 and 100 inclusive
product No String The name of the product to which revenue numbers should be limited (defaults to total revenue across all products)
unit No String Unit of time between data points - can be “day” or “hour” (defaults to “day”)
ending_at No DateTime (ISO 8601 string) Point in time when the data series should end - defaults to time of the request
app_id No String App API Identifier retrieved from the Developer Console to limit analytics to a specific app

Example URL: https://api.appboy.com/purchases/revenue_series?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&product=Product%20A&length=24&unit=hour&ending_at=2014-12-10T23:59:59-05:00&app_id=3bbc4555-8fa0-4c9b-a5c0-4505edf3e064

Revenue Series Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "data" : [
        {
            "time" : (string) point in time - as ISO 8601 extended when unit is "hour" and as ISO 8601 date when unit is "day",
            "revenue" : (float) revenue in USD
        },
        ...
    ]
}

Purchase Quantity Series Endpoint

This endpoint allows you to retrieve a series of the number of purchases made in your app over a designated time period.

GET https://api.appboy.com/purchases/quantity_series

Instance REST Endpoint
Appboy 01 https://api.appboy.com/purchases/quantity_series
Appboy 02 https://rest-02.iad.appboy.com/purchases/quantity_series
Appboy EU https://rest.api.appboy.eu/purchases/quantity_series
Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
length Yes Integer Max number of units (days or hours) before ending_at to include in the returned series - must be between 1 and 100 inclusive
product No String The name of the product to which purchase numbers should be limited (defaults to total purchases across all products)
unit No String Unit of time between data points - can be “day” or “hour” (defaults to “day”)
ending_at No DateTime (ISO 8601 string) Point in time when the data series should end - defaults to time of the request
app_id No String App API Identifier retrieved from the Developer Console to limit analytics to a specific app

Example URL: https://api.appboy.com/purchases/quantity_series?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&product=Product%20A&length=24&unit=hour&ending_at=2014-12-10T23:59:59-05:00&app_id=3bbc4555-8fa0-4c9b-a5c0-4505edf3e064

Purchase Quantity Series Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "data" : [
        {
            "time" : (string) point in time - as ISO 8601 extended when unit is "hour" and as ISO 8601 date when unit is "day",
            "purchase_quantity" : (int)
        },
        ...
    ]
}

Fatal Error Response Codes

The following status codes and associated error messages will be returned if your request encounters a fatal error. Any of these error codes indicate that no data will be processed.

Error Code Reason / Cause
400 Bad Request Bad Syntax
401 Unauthorized Unknown or missing app group id
429 Rate Limited Over rate limit
5XX Internal server error, you should retry with exponential backoff

Raw Event Stream Data Export

The Raw Event Stream provides your brand with a comprehensive view of standard events, custom events and their associated properties in two separate CSV files, one of the events and one of the event properties. Therefore, Appboy’s Raw Event Stream endpoint allows your company to view all the events data Appboy records through your applications.

Walkthrough

The following walkthrough will allow you to receive your app’s raw events data. It will take you step-by-step through the process of understanding how to:

  1. Link your Amazon S3 Credentials
  2. Request your Data Export Files
  3. Receive your Data Export Files
  4. Read your Data Export Files

Note: You need to complete Step 1 only once to set-up. Any additional Raw Event Stream Data Export only requires completing Steps 2-4.

Begin by linking your brand’s Amazon S3 account to your Appboy dashboard here. By linking your account to the dashboard, Appboy can push your requested data files to your Amazon S3 Bucket where you will later retrieve the files.

Note: If you are running into any difficulties at this stage, please refer to Amazon Web Services’ internal documentation for troubleshooting.

Step 2: Request your Data Export Files

To access your company’s Raw Event Stream data, you must query Appboy’s API endpoint. A common way to query API endpoints is through cURL requests; however, you may use whichever HTTP library you prefer. cURL requests allow for any two given endpoints to communicate regardless of programming language or setup. These commands are especially helpful tools for sending and receiving files.

We’ve provided an example cURL request which will trigger the data export:

 curl -X POST https://api.appboy.com/raw_data/export -H "Content-Type: application/json" -d '{"app_group_id":"YOUR_APP_GROUP_ID","starting_at":"YOUR_START_TIME","ending_at":"YOUR_END_TIME","event_names": ["EventA", "EventB"]}'

Note: For details on Raw Event Export API parameters click here.

The cURL request communicates to Appboy’s API Endpoint the specific details of your data request. For example:

  1. Which event(s) are you requesting? (Ex. $push_opened and $email_opened)
  2. What is the time frame of your dataset? (Ex. Ending at 2016-02-23T22:49:05+00:00)
  3. What specific app groups do you want to limit the data export to? (Ex. iOS and Android)

Data is loaded into Appboy’s Raw Event Export after each UTC day and make take up to 72 hours from when the UTC day has ended to be loaded. In order to check if the timeframe you are requesting has been loaded, please use the Raw Event UTC Day Loaded Status Endpoint.

Depending on the time interval you have selected, there may be multiple files included in the export. If you specify an output_format of gzip, then the file extension will be .gz instead of .zip”.

If you added a callback_endpoint parameter in your cURL request for a callback notification, Appboy will notify you when your data is ready for download. Otherwise, feel free to check back in your S3 bucket periodically to see if your data has been exported.

After querying the Appboy API Endpoint, you should receive the following response confirming that we have received your request (If you have not, we recommend you double-check to see if you filed a valid request):

Content-Type: application/json
{
    "success":true,
    "message":"success"
}

Note: Only one export request will be processed at a time. If Appboy receives multiple data export requests from your brand, we will return a 429 error code indicating that you have hit your rate limit.

Step 3: Receive your Data Export Files

There are multiple ways to retrieve data from your S3 bucket. We recommend reading Amazon’s S3 documentation for detailed instructions on the download process.

Congratulations! After the Appboy server processes your request and sends the requested data to your S3 Bucket, you will can easily download the files onto your machine.

Step 4: Read your Data Export files

The requested data will be uploaded to your S3 bucket in two different file formats.

  1. The first CSV file format export contains information for the events that you have requested. Its file name will be formatted like this: “appboy-event-data/app_groups/APP_GROUP_ID/YYYY-mm-dd-HH-MM-events.csv.zip”.

  2. The second CSV file format export contains information for the event properties associated with your requested events. On the exported log, each event property will be tied to a specific event ID and includes the data and data type of the property. Its file name will be formatted like this: “appboy-event-data/app_groups/APP_GROUP_ID/YYYY-mm-dd-HH-MM-event_properties.csv.zip”.

Based on the volume of data that is being exported, there may be more than 1 events file and more than 1 event_properties file per day. Depending on the volume of the data export, the export may take up to a few hours to complete.

Consult this table for help understanding Appboy’s standard events and event properties.

Reference

Parameters

Reference the chart below for the various required and optional parameters you can include in your query.

Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
starting_at Yes DateTime (ISO 8601 string) Point in time in which the data export should begin
ending_at Yes DateTime (ISO 8601 string) Point in time in which the data export should end
       
app_ids No Array PI Identifiers retrieved from the Developer Console. Use the app_id “api” for events from the REST API. When set, the export will be limited to these specific apps, otherwise all data will be exported
callback_endpoint No String Endpoint URL Appboy will hit once the export has finished
event_names No Array of Strings Array of event names to export (i.e., custom event names or Appboy Event Names); when set, only these events will be exported. You can find these events and associated event properties in the following charts below.
output_format No String The file format that will be used for output files. Allowed values are “zip” or “gzip”. Unrecognized output formats will export as zip files.

Note: The current duration limit of this data export feature is one week and only data from the past 3 months may be exported.

Appboy’s Raw Event export is serviced by a dedicated data warehouse. Data is loaded into this data warehouse one UTC day at a time and may not be available until 72 hours after the UTC day has ended. In order to check if the timeframe you are requesting has been loaded, please use the Raw Event UTC Day Loaded Status Endpoint.

If your company’s time zone is not UTC, please be aware that events for “one day’s” worth of your data may be on multiple UTC days. For example, for customers in Eastern Time requesting data for June 3rd, data may not be complete until after the import of UTC June 4th into the data warehouse.

Given this, Appboy recommends requesting data exports ending two days before the request date and ensuring that you export a continuous range of data. For example, if you are requesting data on June 5th, your export’s timeframe should end on June 3rd or earlier. But if your time zone is before UTC, in order to capture the entirety of June 3rd data, you may need to wait until after the UTC June 4th import has completed before exporting.

Events and Event Properties Chart

Reference the chart below for all of Appboy’s Standard Events, Event Properties and their descriptions.

Event Name Event Description Associated Event Properties Event Property Descriptions
$session_started Session started N/A N/A
$session_ended Session ended $duration Session Duration Output in ISO 8601 string (YYYY:MM:HH:mm)
$iap In-App Purchases $amount The amount spent in a given in-app purchase
    $currency The currency used in an in-app purchase transaction
    $product_id The product ID of any given in-app purchase
    $quantity The amount of times a custom event was performed
$push_opened Push Notification Direct Open $button_action_type The action type of the push action button clicked e.g. URI, DEEP_LINK, NONE, etc.
    $button_string The button identifier of the push button clicked e.g. ab_pb_yes, etc.
    $campaign_id The Campaign ID that the push notification is tied to
    $canvas_id The Canvas ID that this push notification is tied to
    $canvas_step_id A message’s step ID within a Canvas
    $canvas_step_variation_id The Canvas Step Variant ID the notification is tied to
    $canvas_variation_id The Canvas ID that this push notification is tied to
    $message_variation_id The Message Variant ID that the push notification is tied to. This string is of the format “channel - variation_name - variation_api_id”
$ios_push_foreground iOS Push Notification Received While App Was Foregrounded N/A N/A
$in_app_message_impression In-App Messaging Impression $campaign_id The Campaign ID that the push notification is tied to
    $message_variation_id The Message Variant ID that the in-app message notification is tied to. This string is of the format “channel - variation_name - variation_api_id”
$in_app_message_clicked In-App Messaging Clicked $button_index Index of IAM button clicked i.e. 0 or 1
    $campaign_id The Campaign ID that the push notification is tied to
    $message_variation_id The Message Variant ID that the in-app message notification is tied to. This string is of the format “channel - variation_name - variation_api_id”
$slideup_impression Original In-App Messaging Impression N/A N/A
$slideup_clicked Original In-App Messaging Click $button_index Index of IAM button clicked i.e. 0 or 1
$campaign_received Campaign Received by User (one event will be logged per channel $campaign_id The Campaign ID that the notification is tied to
    $message_variation_id The Message Variant ID that the notification is tied to
$canvas_entry User Enters Canvas $canvas_id The Canvas ID that this notification is tied to
    $canvas_step_id A message’s step ID within a Canvas
    $canvas_variation_id The Canvas ID that this notification is tied to
    $in_control_group Indicates if user is in the control group
$canvas_step_received Canvas Step Received by User, one event will be logged per channel $canvas_id The Canvas ID that this notification is tied to
    $canvas_step_id A message’s step ID within a Canvas
    $canvas_step_variation_id The Canvas Step Variant ID the push is tied to
    $canvas_variation_id The Canvas variation ID that this notification is tied to
$card_clicked News Feed Click $card_id Newsfeed Card ID that the user’s click is tied to
$card_impression News Feed Impression $card_id Newsfeed Card ID that the user’s impression is tied to
$email_delivered Email Delivered $email User’s Email Address
$email_opened Email Open $email User’s Email Address
    $campaign_id The Campaign ID that the email message is tied to
    $message_variation_id The Message Variant ID that the email message is tied to. This string is of the format “channel - variation_name - variation_api_id”
$email_clicked Email Click $url URL clicked
    $campaign_id The Campaign ID that the email message is tied to
    $message_variation_id The Message Variant ID that the email message is tied to. This string is of the format “channel - variation_name - variation_api_id”
$email_unsubscribed User Unsubscribes From Email N/A N/A
$email_marked_as_spam User Marks Email as Spam $email User’s Email Address
$email_bounced Email Address Bounces N/A N/A
$email_soft_bounced Email Soft Bounces $email User’s Email Address
$first_used_app User Uses App For the First Time N/A N/A
$campaign_converted User Converts From Campaign $conversion_behavior_index A value 0-3 referring to a specific conversation event tied to a user’s conversion
$canvas_converted User Converts From Canvas $conversion_behavior_index A value 0-3 referring to a specific conversation event tied to a user’s conversion
$news_feed_viewed Appboy News Feed Is Viewed N/A N/A
$attribution_data_received Install Attribution From Source $attributed_source The attributed source of the install
$uninstalled User Uninstall Detected N/A N/A

Raw Event UTC Day Loaded Status Endpoint

Instance REST Endpoint
Appboy 01 GET https://api.appboy.com/raw_data/status
Appboy 02 GET https://rest-02.iad.appboy.com/raw_data/status
Appboy EU GET https://rest.api.appboy.eu/raw_data/status

Data is loaded into Appboy’s Raw Event Export after each UTC day. This endpoint allows one to query if a given UTC day has been loaded into Appboy’s Raw Event Export.

Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
date Yes Date (YYYY-MM-DD string) UTC Date to check if it is loaded

This endpoint will respond with JSON with a boolean key loaded that indicates if a given UTC day has loaded.

Example URL: https://api.appboy.com/raw_data/status?app_group_id=X&date=2017-08-31

Example Response

Content-Type: application/json
{
  "loaded": true,
  "message": "success"
}

API Campaigns

Campaigns sent through the Messaging API can have the same detailed reporting and retargeting options as campaigns created on the dashboard. This section of the documentation will detail how to generate a campaign_id to include in your API calls and take advantage of this feature.

Step 1: Click “API Campaigns” on the “Campaigns” page

Navigate to the Appboy Campaigns page in your company dashboard and click “Create Campaign” then click “API Campaigns”

API Campaigns

Step 2: Configuring API Campaigns

  1. Add a descriptive title so you can find the results on our campaigns page after you’ve sent your messages.
  2. Click the “Add Message” button and add the messages types which will be included in your API campaign.
  3. Optionally add a conversion event to track user conversions on a specific action or campaign goal.
  4. Click “Save Campaign” and you’re set to begin your API campaign.
  5. Include the generated campaign_ID fields with your API request where noted in the Messaging API - Send Endpoint Spec

Configuring API Campaigns

API Connectivity Issues

Appboy’s API endpoints use a CDN that routes traffic to the closest POP based on DNS information. If you are having issues connecting or notice that you are connecting to a POP that is not efficient, please make sure to use your provider’s DNS servers or DNS servers that are setup in the same data center as your server and have proper IP location meta information associated with them.

We have noticed that a handful of firewalls attempt to modify or secure HTTPS/TLS traffic which interferes with connections to Appboy’s API endpoints. If your servers are behind any sort of physical firewall, please disable any HTTPS/TLS acceleration or modifications that the firewall(s) and/or router(s) are performing. Additionally, you can whitelist outbound traffic to our CDN providers (Fastly.com) to see if that resolves the issue.

Occasionally, iptables setups that filter on SYN/ACK/RST packets can also cause issues, so if you are using iptables on your host you could also whitelist outbound traffic to our CDN providers (Fastly.com) to see if that resolves the issue.

If you are still having network issues with connecting to Appboy’s API Endpoint, please provide an MTR Test and the results from Fastly Debug while experiencing an issue and submit that with your support request.
Note that the test results must be obtained from a server that is having issues connecting to Appboy’s API endpoint, not from a development machine. A network capture (tcpdump or .pcap file) will also be helpful if it can be obtained.

Whitelisting Appboy’s API Endpoint IP Ranges

To whitelist Appboy’s API endpoint through your firewall, our CDN provides access to the list of assigned IP ranges via a JSON dump. You can access the public list of Fastly IP ranges here.

TLS 1.0 & 1.1 Deprecation

Background

Appboy is deprecating known weak Transport Layer Security (TLS) ciphers in both TLS 1.0 and 1.1, in accordance with recommendations made by the PCI Security Standards Council in two phases concluding in May 2018.

This change is not being made in response to any breach or issue related to Appboy’s platform, but as a precautionary measure to maintain our best-in-class security and data standards, and to proactively safeguard our clients and their customers.

In recent years, a number of systematic security issues associated with both TLS and its predecessor, Secure Sockets Layer (SSL), including POODLE, Heartbleed, LOGJAM, and others, threatened encrypted web traffic and exposed portions of the internet to security breaches. Along with other technology companies, Appboy has previously taken action to disable weak encryption protocols and ciphers as attacks are discovered—for instance, by removing support for SSLv3 in 2014.

More recently, the PCI Security Standards Council released encryption-related guidance in April 2015 for the Payment Card Industry Data Security Standard (PCI-DSS). The guidance excludes SSL 3.0, TLS 1.0, and some of the cipher suites supported by TLS 1.1 from their protocol list of strong cryptographic ciphers, and encourages companies from discontinuing support for those protocols or ciphers to ensure the security of internet users.

A cipher suite is a combination of algorithms that provide encryption, authentication, and communications integrity when negotiating a secure SSL or TLS connection. When it’s discovered that it’s possible for a given cipher to be broken—whether or not there are any current known attacks—the cipher is considered to have “weaknesses” that could enable future attacks. By excluding these TLS ciphers from PCI DSS compliance requirements, the PCI DSS Council is requiring service providers to support only best-in-class encryption standards. The PCI DSS Council has set a deadline of June 30, 2018 for compliance with the encryption requirement to drop support for TLS 1.0 and TLS 1.1.

Appboy’s Deprecation Plan

In order to comply with the PCI DSS Council’s recommendations, Appboy will be raising the minimum versions of TLS that we support on our Services. To give you a better idea about our compliance plan and its potential impact on your brand and your end users, there are two main phases to our plan to be aware of:

Phase 1: October 1, 2017

Appboy will remove the ability to use the following ciphers from Appboy’s Web Dashboard and REST APIs:

TLS_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA256 TLS_RSA_WITH_AES_256_GCM_SHA384 TLS_RSA_WITH_AES_128_CBC_SHA256 TLS_RSA_WITH_AES_128_GCM_SHA256 TLS_RSA_WITH_3DES_EDE_CBC_SHA

This change should not impact customers accessing the Appboy Dashboard, as all modern web browsers support more secure ciphers. However, if you do experience a SSL encryption error when accessing the web dashboard after October 1, you will be able to fix the issue by simply upgrading to the latest version of your web browser.

Your engineering team should ensure that they aren’t using any of these ciphers for server-to-server communication with Appboy’s REST APIs. If they are, they’ll need to update their code to use more secure encryption ciphers prior to October 1 in order to continue making use of Appboy’s APIs. However, in order to maintain support for old and outdated mobile devices which may be using weak ciphers, Appboy will continue to support these ciphers on the APIS that received data from our SDKs.

Phase 2: May 31, 2018

Appboy will be disabling support for TLS 1.0 and TLS 1.1 across all Appboy Services on May 31, 2018—including the Appboy Dashboard, REST APIs, and APIs that communicate with our SDKs. We’ll also remove support for the ciphers listed above in connection with the APIs that receive SDK data. That means that all TLS 1.0 and 1.1 communication to and from Appboy will not be supported by our network as of this date.

As a result of this change, some old or outdated mobile devices—likely ones running early versions of Android—may lose the ability to communicate with Appboy, barring them from sending data to Appboy or receiving in-app messages from Appboy. However, we anticipate that the change will affect only a small number of devices. Any devices that are affected will also lose the ability to communicate with any PCI-compliant website or service a month later on June 30, 2018, the date set by the PCI DSS Council for removal of TLS 1.0 and TLS 1.1 ciphers.

Action Plan

If your brand is making use of Appboy’s REST APIs, please speak to your engineering team to ensure that all server-to-server calls to Appboy s using TLS 1.2 by the listed above in order to avoid an interruption of service. Be aware that some programming languages—such as Java 7—use older versions of TLS by default, so your engineering team may need to take some code changes to support the upgraded encryption requirements.

Apple devices will not be affected by Appboy’s planned deprecation because Apple has required TLS 1.2 since the end of 2016. The same is true of modern web browsers, so we do not anticipate that these changes will have any impact on Web SDK usage. However, Android devices running Android 4.4 (KitKat) or lower may not use TLS 1.2 by default, so please take steps to upgrade any of your Android integrations to at least Appboy SDK version 2.0.3 (which uses TLS 1.2 by default, if a given device can support it) by May 31, 2018.

Finally, because of the known weaknesses in TLS 1.0 and the TLS 1.1 cipher suite, it’s possible that attacks could arise in the future which would require Appboy to speed up our deprecation plan, in order to safeguard the security of all our customers. Appboy will monitor the state of security and any relevant attacks associated with TLS 1.0 and 1.1 protocols, and will keep you in the loop if we learn of any attacks that will alter the timeline laid out above. But because of this potential impact, we highly recommend that you work with your engineering team to ensure that your API calls to Appboy are secured with TLS 1.2, and that you plan to upgrade to the latest Android SDK in the coming months.