Endpoint and Authentication

Please refer to the API overview section to get the API endpoint, query format and authentication process.

Transactional endpoint update

To improve the stability and confirmity of our API, the transactional endpoint /api/transac is deprecated, but will continue to work before being deleted in the future. Please refer to the section below to get the details about the new endpoint and new options you have for transactional campaigns.

Updated on November 15th, 2019

API Version 3

Some APIs have been improved in the most recent version (V3). In order to use version 3, please add the value "application/vnd.fa.v3" to the Accept header of the request.

List all campaigns

GET /api/campaigns?limit=limit&offset=offset&order=order&app_ids=app_ids&status=status&workflow_types=workflow_types&labels=labels&message_types=message_types&search=search&from=from&to=to

Export endpoint (see how to use it here):

GET /api/campaigns/list_export?order=order

Query parameters

Property Type Discussion Default
app_ids string Comma-separated list of app identifiers to filter by. -
status string Comma-separated list to filter by the state of the campaign. Values are: ongoing, finished, wait_sync, scheduled, draft, failed, canceled. -
workflow_types string Comma-separated list to filter by the type of workflow. Values are: scheduled, contextual, transactional, dynamic -
limit integer Maximum number of campaigns to return in each page. V2: none. V3: 20
offset integer Offset in number of items to navigate through the results. 0
order string Campaigns are ordered by date, descending.
You can add a first ordering by passing one of status, app, start_date, updated_at, created_at		 created_at
labels string A comma separated string of labels. If provided, the API returns campaigns that have at least one of the labels. -
message_types string A comma separated string of message types. Accept values are: push-only (returns only push campaigns), inapp-only (returns only inapp campaigns), push-inapp (returns campaigns that are push and inapp). -
search string A search string that will filter campaigns where the name matches it (case insensitive). -
from string A date string. The result of filtering campaigns with this param depends on the value of the order param. When order is start_date, then this filter will exclude campaigns started before this date. When order is status or created_at, then this filter will exclude campaigns created before this date. When order is updated_at, then this filter will exclude campaigns updated before this date. Otherwise, the parameter is ignored. created_at
to string Same behaviour as the from param, except it filters campaigns created/updated/started until this date. -

Response

Status: 200 OK

{
    "offset": 0,
    "limit": 20,
    "total_count": 1,
    "success": true,
    "result":[
        {
            "identifier": "FACMPGN_UIsHGR9-r5y_fQc7",
            "name": "C1",
            "status": "Ongoing",
            "type": "classic",
            "includes_inapp": true,
            "includes_push": false,
            "adapt_tz": false,
            "variant_strategy": null,
            "labels": [],
            "smart_delivery": false,
            "app_id": "FAAPPLI_0VDvT50",
            "launched_at": 1583770788,
            "start_date": 1583770788,
            "end_date": 1586362788,
            "inapp_ttl": 2592000,
            "updated_at": 1583770832,
            "created_at": 1583770787,
            "snapshot_at": 1583770802,
            "variants": [
                {
                    "id": "PGVAR_PtwwFlM",
                    "name": "Variant A",
                    "language": "fr",
                    "is_default": true,
                    "params": {
                        "inapp": "native",
                        "message_title": "In-app native",
                        "message_content": "In-app native scheduled now without TZ!",
                        "message_btn": "Close",
                        "buttons": []
                    },
                    "custom_json": null
                }
            ],
            "params": {
               "inapp": "native",
               "message_title": "In-app native",
               "message_content": "In-app native scheduled now without TZ!",
               "message_btn": "Close",
                "buttons": []
            },
            "skip_message_limit": false,
            "reach": {
                "count": 10661,
                "optin": 0,
                "total": 10661,
                "token": null
            },
            "stats": {
                "viewed": 0,
                "total_inapp_viewed": 0
            }
        }
    ]
}

Campaign creation

You need to explicitly launch your campaigns

Campaigns you create through the APIs are saved as draft. Once saved, you have to explicitly launch them so that they can start.

To create a campaign, no matter its layout or type, you use a common endpoint:

POST /api/campaign

To launch a saved campaign, use the identifier returned upon creation on the following endpoint:

PUT /api/campaign/campaign_identifier/launch

This section will explain how to create classic, transactional, and dynamic campaigns.

Body parameters

Below is the list of the required fields to create a campaign, plus many of the optional ones. The latter will be illustrated later on in this page.

Property Type Description Default
name string A name for your campaign, never displayed to your customers required
type string Campaign type. classic, transactional, or dynamic required
source string Please pass API required
app_id string The application identifier targeted by this campaign required
includes_push boolean If true, the campaign will send a push notification. required
push_ttl integer Time in seconds after which the push should not be delivered if it hasn't been successfully done yet. 7 days
includes_inapp boolean If true, the campaign will send an in-app notification. required
inapp_ttl integer Time in seconds after which the inapp should not be displayed if it hasn't been successfully done yet. 30 days
start_date timestamp Start of the campaign, in seconds since epoch, or now. required
params object Object with details on the campaign payload. Will be detailed in the examples below required
params[inapp] string Please pass native. You can also use url if you want to send a custom page or parameters, see how to create such a transactional campaigns here. required for in-app
params[message_title] string Title of in-app box required for in-app
params[message_content] string Body of the in-app message required for in-app
params[message_btn] string Default dismiss button required for in-app
params[push_message] string Body of the push message required for push
params[push_title] string Title of the push message -
params[push_subtitle] string Subtitle of the push message (iOS only) -
params[deep_linking_url] string Push notifications can be associated with a deep link URL so that opening the app from the notification drives user to a specific section of your app, or even opens another app. -
params[pushAttachment] string URL to a media to attach to the push -
params[pushCategory] string Name of a category of buttons to use for the push notification - mobile only -
params[push_includes_sound] string URL to a media to attach to the push true
params[push_sound_value] string Sound file to read upon reception of the push message - iOS only -
adapt_tz boolean Send messages at the desired time in each user's timezone false
end_date timestamp End of the campaign, in seconds since epoch. This has no effect on push only campaigns. 30 days after start
filters map Structure holding filters to segment the target audience -
skip_message_limit boolean If a capping is set on the distribution of push messages, this allows to bypass it false
activate_throttling boolean If the campaign should use throttling false

Classic campaign

Minimal classic push campaign

To create a push notification campaign, you need to set these fields:

Example
{
    "name": "Most simple classic push only",
    "type": "classic",
    "source": "API",
    "app_id": "FAAPPLI_0VDvT50",
    "includes_inapp": false,
    "includes_push": true,
    "start_date": "now",
    "params": {
        "push_message": "The push message your customers will see."
    }
}
Response

Status: 200 OK

{
    "result": {
        "campaign_id": "FACMPGN_vRvb99Xme2IeHj"
    },
    "success": true
}

Minimal classic in-app campaign

To create an in-app campaign, you need to set these fields:

Example
{
    "name": "Most simple classic in-app only",
    "type": "classic",
    "source": "API",
    "app_id": "FAAPPLI_0VDvT50",
    "includes_inapp": true,
    "includes_push": false,
    "start_date": "now",
    "params": {
        "inapp": "native",
        "message_title": "inapp title",
        "message_content": "inapp body content",
        "message_btn": "label for the default inapp button"
    }
}
Response

Status: 200 OK

{
    "result": {
        "campaign_id": "FACMPGN_SMdP2t1AjrFPGUfa"
    },
    "success": true
}

Push and in-app classic campaign

To create a campaign with both push and in-app notifications, you need to set these fields:

Example
{
    "name": "Most simple classic in-app + push cmp",
    "type": "classic",
    "source": "API",
    "app_id": "FAAPPLI_0VDvT50",
    "includes_inapp": true,
    "includes_push": true,
    "start_date": "now",
    "params": {
        "push_message": "The push message your customers will see.",
        "inapp": "native",
        "message_title": "inapp title",
        "message_content": "inapp body content",
        "message_btn": "label for the default inapp button"
    }
}
Response

Status: 200 OK

{
    "result": {
        "campaign_id": "FACMPGN_bo1BXXbrx0-dNy9V"
    },
    "success": true
}

Classic campaign with audience targeting using segments

Using segmentation lets you target specific populations of your application audience. To target users through the API, you need to save segments beforehand, and target them based on their unique identifier.

Your campaign payload will need to add the filters[blocks[filters]] key, which requires these fields:

Example
{
    "name": "Push to segment",
    "type": "classic",
    "source": "API",
    "app_id": "FAAPPLI_0VDvT50",
    "includes_inapp": false,
    "includes_push": true,
    "start_date": "now",
    "params": {
        "push_message": "The push message your customers will see."
    }
    "filters": {
        "blocks": [
          {
            "filters": [
              {
                "filter_on": "segments",
                "selection": "any_of",
                "segment_identifiers": ["FASEGMT_uWQ4x3fPuNMt2PjC"],
                "operator": "is_in"
              }
            ]
          }
        ]
      }
}
Response

Status: 200 OK

{
    "result": {
        "campaign_id": "FACMPGN_pqQA34xyA-opMiFs"
    },
    "success": true
}

Push campaign with media as attachment

iOS apps support images and video unlike Android apps when only images are supported.

The field to set for this example is:

Example
{
   "app_id":"FAAPPLI_0VDvT50",
   "adapt_tz":false,
   "contextual_params":null,
   "end_date":null,
   "ends_in":null,
   "filters":null,
   "has_control_group":false,
   "includes_push":true,
   "includes_inapp":false,
   "mobile_moment":null,
   "name":"push with image",
   "optimization_start_date":null,
   "conversion_period":172800,
   "skip_message_limit":true,
   "source":"web",
   "start_date":"now",
   "type":"classic",
   "variants":[
  {
     "name":"Variant A",
     "params":{
        "push_message":"push with image",
        "push_parameters":[

        ],
        "push_multiple_devices":true,
        "pushAttachment":"https://upload.wikimedia.org/wikipedia/commons/0/07/Lascaux2.jpg",
        "pushShowInForeground":false,
        "silent_push":false,
        "push_includes_sound":true
     }
  }
 ],
 "smart_delivery":false,
"related_templates":[

 ],
"labels":[

],
"push_ttl":604800
}
Response

Status: 200 OK

{
    "result": {
        "campaign_id": "FACMPGN_ESRNvbUU8t3B_rjd"
    },
    "success": true
}

Push campaign with emojis

The emojis can be added to the title or the content of the push.

Example
{
    "app_id":"FAAPPLI_0VDvT50",
   "adapt_tz":false,
   "contextual_params":null,
   "end_date":null,
   "ends_in":null,
   "filters":null,
   "has_control_group":false,
   "includes_push":true,
   "includes_inapp":false,
   "mobile_moment":null,
   "name":"push with emojis",
   "optimization_start_date":null,
   "conversion_period":172800,
   "skip_message_limit":true,
   "source":"web",
   "start_date":"now",
   "type":"classic",
   "variants":[
    {
     "name":"Variant A",
     "params":{
        "push_message":"push with emoji 😀",
        "push_parameters":[

        ],
        "push_multiple_devices":true,
        "pushAttachment":null,
        "push_title":"test 🌎",
        "pushShowInForeground":false,
        "silent_push":false,
        "push_includes_sound":true
     }
  }
],
"smart_delivery":false,
"related_templates":[

],
"labels":[

],
"push_ttl":604800
}
Response

Status: 200 OK

{
    "result": {
        "campaign_id": "FACMPGN_fyHfQG0Jo_qcoowO"
    },
    "success": true
}

Inapp campaign with emojis

Example
{
   "app_id":"FAAPPLI_0VDvT50",
   "adapt_tz":false,
   "contextual_params":null,
   "end_date":null,
   "ends_in":null,
   "filters":null,
   "has_control_group":false,
   "includes_push":false,
   "includes_inapp":true,
   "mobile_moment":null,
   "name":"inapp with emoji",
   "optimization_start_date":null,
   "conversion_period":null,
   "skip_message_limit":true,
   "source":"web",
   "start_date":"now",
   "type":"classic",
   "variants":[
    {
     "name":"Variant A",
     "params":{
        "inapp":"native",
        "message_title":"test 🌞",
        "message_content":"inapp native with emoji: 😃",
        "message_btn":"Close",
        "buttons":[

        ]
     }
  }
],
"smart_delivery":false,
"related_templates":[

],
"labels":[

],
"inapp_ttl":2592000
}
Response

Status: 200 OK

{
    "result": {
        "campaign_id": "FACMPGN_du7mDQetKHWo-d3x"
    },
    "success": true
}

Push campaign with multiple filters

The field to be set is:

Example
{
   "app_id":"FAAPPLI_0VDvT50",
   "adapt_tz":false,
   "contextual_params":null,
   "end_date":null,
   "ends_in":null,
   "filters":{
      "operator":"OR",
      "blocks":[
         {
            "operator":"AND",
            "filters":[
               {
                  "filter_on":"language",
                  "operator":"is_in",
                  "language_codes":[
                     "en"
                  ]
               },
               {
                  "filter_on":"campaigns",
                  "condition":"targeted_by",
                  "selection":"any_of",
                  "campaign_identifiers":[
                     "FACMPGN_Z2gUY2wIKArphVwX"
                  ]
               }
            ]
         },
         {
            "operator":"OR",
            "filters":[
               {
                  "filter_on":"customer_attribute",
                  "customer_attribute_identifier":"FACA_T8g-ZXADWHxT",
                  "customer_attribute_type":"string",
                  "operator":"is_in",
                  "values":[
                     "value1"
                  ]
               }
            ]
         }
      ]
   },
   "has_control_group":false,
   "includes_push":true,
   "includes_inapp":false,
   "mobile_moment":null,
   "name":"filters",
   "optimization_start_date":null,
   "conversion_period":172800,
   "skip_message_limit":true,
   "source":"web",
   "start_date":"now",
   "type":"classic",
   "variants":[
      {
         "name":"Variant A",
         "params":{
            "push_message":"filters",
            "push_parameters":[

            ],
            "push_multiple_devices":true,
            "push_title":"test",
            "pushShowInForeground":false,
            "silent_push":false,
            "push_includes_sound":true
         }
      }
   ],
   "smart_delivery":false,
   "related_templates":[

   ],
   "labels":[

   ],
   "push_ttl":604800
}
Response

Status: 200 OK

{
    "result": {
        "campaign_id": "FACMPGN_2ATqMVQ0djsNka_7"
    },
    "success": true
}

Dynamic campaign

Body parameters

Dynamic campaigns introduce new parameters allowing to control the recurrence of the campaign, and the amount of notifications sent to users.

Property Type Description Default
recurrence object Object describing the recurrence pattern of the dynamic campaign required
recurrence[start_time] object Object describing the start of the notification period -
recurrence[start_time][hour] int Starting hour of the notification period must be between 0 and 23 included
recurrence[start_time][min] int Starting minute of the notification period 0
recurrence[end_time] object Object describing the end of the notification period -
recurrence[end_time][hour] int Ending hour of the notification period must be between 1 and 24 included, always greater than the start
recurrence[timezone] string Identifier of the timezone in which to interpret start and end time Use only when adapt_tz is false
recurrence[day_of_week] list[int] Days of the week (Sunday: 0, Saturday: 6) during which the notification period is active required
notif_limit object Object describing limits imposed on the amount of notifications to send to users required
notif_limit[maximum] int Maximum number of notifications to send to a single user -
notif_limit[interval] int Minimal time in hours interval between two successive notifications -

Notify at a specific time: Every week day at 8am

By setting only start_time and leaving end_time empty, notifications will be sent at exactly start_time:

Since you can't create a dynamic campaign without setting limits on the notifications, let's limit them to 1 notification per week:

Example
{
    "name": "Specific time push trigger",
    "type": "dynamic",
    "source": "API",
    "app_id": "FAAPPLI_0VDvT50",
    "includes_inapp": false,
    "includes_push": true,
    "start_date": "now",
    "end_date": 1513607658,
    "params": {
        "push_message": "The push message your customers will see."
    },
    "recurrence": {
        "start_time": {
            "hour": 8,
            "min": 15
        },
        "timezone": "Europe/Paris",
        "day_of_week": [1,2,3,4,5]
    },
    "notif_limit": {
        "interval": 168
    }
}
Response

Status: 200 OK

{
    "result": {
        "campaign_id": "FACMPGN_vRvb99Xme2IeHj"
    },
    "success": true
}

Notify over a period of time: Every Wednesday between 10am and 2pm

In order to notify users anytime they enter an audience over a period of time, we need to set both start_time and end_time:

We don't want to send the notification multiple times to the same user on the same day, so we set a minimal interval of a few hours between two notifications:

Example
{
    "name": "Simple push trigger",
    "type": "dynamic",
    "source": "API",
    "app_id": "FAAPPLI_0VDvT50",
    "includes_inapp": false,
    "includes_push": true,
    "start_date": "now",
    "end_date": 1513607658,
    "params": {
        "push_message": "The push message your customers will see."
    },
    "recurrence": {
        "start_time": {
            "hour": 10
        },
        "end_time": {
            "hour": 14
        },
        "timezone": "America/New_York",
        "day_of_week": [3]
    },
    "notif_limit": {
        "interval": 4
    }
}
Response

Status: 200 OK

{
    "result": {
        "campaign_id": "FACMPGN_vRvb99Xme2IeHj"
    },
    "success": true
}

Notify anytime: On week-ends, anytime of day

If all we want is to notify users as soon as they enter the audience, no matter what time it is, leave both start_time and end_time empty. We still need to specify on which days the campaign is active, in this case let's set it to week-ends.

This time we will set a hard limit of 3 notifications over the lifetime of the campaign, and force an interval of at least 1 month between two of them so we don't use them up too quickly:

Example
{
    "name": "Simple push trigger",
    "type": "dynamic",
    "source": "API",
    "app_id": "FAAPPLI_0VDvT50",
    "includes_inapp": false,
    "includes_push": true,
    "start_date": "now",
    "end_date": 1513607658,
    "params": {
        "push_message": "The push message your customers will see."
    },
    "recurrence": {
        "day_of_week": [0,6]
    },
    "notif_limit": {
        "maximum": 3,
        "interval": 720
    }
}
Response

Status: 200 OK

{
    "result": {
        "campaign_id": "FACMPGN_vRvb99Xme2IeHj"
    },
    "success": true
}

Transactional campaign

Transactional campaigns can contain variable placeholders in their message. These placeholders are defined by a special syntax, starting with *@ and ending with its symetric @*. For example, *@this_is_a_valid_placeholder@*.

Deprecated: Transactional template_variable

The declaration of params[template_variables] array is not supported anymore, now all the varaible are set in the fields and only in the fields, using the special syntax described above.

Transactional campaigns can contain an in-app component. Variables can be used in most fields, as illustrated in the examples below.

The response will contain the campaign_id value. campaign_id can although be found later in the url of the campaign's result page. You can use this value to trigger transanctional campaigns from your system as long as the campaign is still running. Please refer to the Sending transactional campaign messages section for more details on sending transactional campaign messages.

Overview of transactional campaign creation

Example: Transactional push campaign

In this example, we also use a variable in the deep link, so that sliding the notification opens the app on a section defined upon the API call to our server triggering the send.

{
    "name": "Most simple transactional campaign",
    "type": "transactional",
    "source": "API",
    "app_id": "FAAPPLI_0VDvT50",
    "includes_inapp": false,
    "includes_push": true,
    "start_date": "now",
    "params": {
        "push_message": "Hello *@first_name@* *@last_name@*, we hope you a nice day",
        "push_title":"Welcome *@first_name@*",
        "deep_linking_url": "myapp://*@deeplink@*"
    }
}

Example: Transactional in-app campaign

{
    "name": "In-app transactional campaign",
    "type": "transactional",
    "source": "API",
    "app_id": "FAAPPLI_0VDvT50",
    "includes_inapp": true,
    "includes_push": false,
    "start_date": "now",
    "params": {
        "message_title": "Thank you *@first_name@*",
        "message_content": "You just made our day",
        "message_btn": "Redeem your *@amount@*$ gift",
        "inapp": "native"
    }
}

Example: Transactional in-app w/ custom parameters

You can use variables in most text fields of the campaign. This allows you to create a campaign which, for instance, would send the URL of an image, along with specific parameters telling how to display it in the app.

This method can be used to personalize the contents of your app through API calls.

{
    "name": "In-app transactional campaign",
    "type": "transactional",
    "source": "API",
    "app_id": "FAAPPLI_0VDvT50",
    "includes_inapp": true,
    "includes_push": false,
    "start_date": "now",
    "params": {
        "inapp": "url",
        "inapp_content_url": "https://myserver.com/images/*@image_name@*.jpg",
        "inapp_content_title": "custom content",
        "inapp_content_auto_display": false,
        "deep_linking_url": "",
        "inapp_parameters": [{
            "key": "position",
            "value": "*@pos@*"
        }, {
            "key": "width",
            "value": "*@width@*"
        }, {
            "key": "type",
            "value": "headline"
        }]
    }
}

Response

Status: 200 OK

{
    "result": {
        "campaign_api_identifier": "CGN_FOLLOWANALYTICSTEST_1461745425869",
        "campaign_id": "FACMPGN_VCFzh_NpR3Qrru3B"
    },
    "success": true
}

Campaigns list quick stats

This endpoint returns the total numbers of campaigns (of each type) as well as the number of pushes sent and opened and in-apps displayed. The stats can be filtered by providing parameters that create a subset of campaigns.

GET /api/campaigns/quick_stats

Query parameters

Property Type Discussion Default
app_ids string Comma-separated list of app identifiers to filter by -
status string Comma-separated list to filter by the state of the campaign. Values are: ongoing, finished, wait_sync, scheduled, draft, failed, canceled. -
workflow_types string Comma-separated list to filter by the type of workflow. Values are: scheduled, contextual, transactional, dynamic -
search string A string to filter the stats by campaigns that include the search parameter as part of their name -

Response

Status: 200 OK

{
  "total_campaigns": 345,
  "push_campaigns": 240,
  "inapp_campaigns": 170,
  "total_push_sent": 3040,
  "total_push_opened": 1580,
  "total_inapp_displayed": 720
}

Transactional Push and In-App messages

Set of APIs to send messages to specified User Ids and retrieve reports on sendings and hits.

Overview of batch sending and report retrieving

Send a batch of transactional messages

POST /api/campaigns/trigger

  1. Using a JSON

Body parameters

Property Type Description Default
campaign_identifiers array of strings The campaign unique key to identify which campaigns needs to be used for sending the messages. campaign_id should be used here required
send_at datetime A date when the sending should occur, expressed in any ISO format, e.g. 2017-04-06T16:41:44+05:00 -
messages array of objects The parameters of the messages to send to the app’s users required
message[user_id] string The userId to whom the message must be sent required
message[template_variables] object Variables used in the message template. Key is the variable key, value is the value to assign to it for this user. -

Example

{
    "campaign_identifiers":["FACMPGN_fQq2YaB9vrJQuDid"],
    "messages":[
        {
            "user_id":"john365",
            "template_variables":{"lastname":"Doe","firstname":"John", "contractNumber":"ABC56"}
        },
        {
            "user_id":"duce23",
            "template_variables":{"lastname":"Duce","firstname":"JC", "contractNumber":"234AE"}
        }
    ]
}

Response

Status: 200 OK

{
    "success": true,
    "result": {
        "request_id": "A_UNIQUE_REQUEST_ID"
    }
}

Status: 400

{
    "status": "400",
    "success": false,
    "error_message": "Unknown campaign with identifier ..."
}

Status: 400

{
    "status": "404",
    "success": false,
    "error_message": "Campaign with identifier FACMPGN_fQq2YaB9vrJQuDid at index 0 not ready"
}

Status: 400

{
    "status": "405",
    "success": false,
    "error_message": "Missing or empty campaign key..."
}

  1. Using a .csv file

Body parameters

Property Type Description Default
campaign_identifiers array of strings The campaign unique key to identify which campaigns needs to be used for sending the messages. campaign_id should be used here required
send_at datetime A date when the sending should occur, expressed in any ISO format, e.g. 2017-04-06T16:41:44+05:00 -
file File It represents the .csv file uploaded

Example:

The CSV file must be encoded with UTF-8 and have in the header the User and the variables defined in the campaign (here: contractnumber,firstname,lastname):

User,contractnumber,firstname,lastname
john365,ABC56,John,Doe
duce23,234AE,JC,Duce

The file can be directly uploaded as if a part of a web form (set the Body to Form-data, see in the screenshot below). The key for the file must be file.

Response

Status: 200 OK

{
    "success": true,
    "result": {
        "request_id": "A_UNIQUE_REQUEST_ID"
    }
}

Retrieve a sending report

API to get a status report of the messages sent.

GET /api/campaigns/request?request_id=request_id

Query parameters

Property Type Description Default
request_id string The request_id retrieved from transactional message send API result. required

Response

You will receive a link to a CSV report file.

These are the headers of the file:

Property Type Description
campaign_identifier string The campaign identifier, a report can contain multiple campagins
request_id string The request id used to retrieve the report
user_id string The user identifier given when sending the message
device_id string Device identifier indicating where the message was delivered. A user can be seen multiple times if logged on multiple devices.
processed_at date Date of sending attempt, expressed in ISO format
status_code string The status code of the attempt. See list below.
status_details string Details information of the status.
channel string The campaign message type. It can be inapp if the campaign is inapp, or push if the campaign is push.

Example: Sending report

"campaign_identifier","request_id","user_id","device_id","processed_at","status_code","status_details","template_variables","channel"

"FACMPGN_eypZv_bVHJS9qgus","1e457b41-c520-432c-951d-0a1b7342c70e","john365","3f976ddac73f7d80","2020-10-16 11:31:38 +0000","","","""{\""contractnumber\"":\""ABC56\"",\""firstname\"":\""John\"",\""lastname\"":\""Doe\""}""","push"

"FACMPGN_eypZv_bVHJS9qgus","1e457b41-c520-432c-951d-0a1b7342c70e","duce23","20737b5a3667200b","2020-10-16 11:31:38 +0000","","","""{\""contractnumber\"":\""234AE\"",\""firstname\"":\""JC\"",\""lastname\"":\""Duce\""}""","push"

Possible error codes are:

Error code Description
DEVICE_OPT_OUT The user refuses to receive this application push notifications, he is opt-out in FA database or doesn't have a token
MESSAGE_TO_BIG The message was rejected by GCM (Android) or APNS (Apple) because it was too long
VALIDATION_ERROR There is an error pertaining to the message, it could be a message param missing
NO_CONNECTED_DEVICE The user exists in our system but has no targetable device, the user has very likely logged out
USER_UNKNOWN The user_id is not present in FA database

There are also some errors sent by Firebase and APNS, here are some of them:

Error code Description
MismatchSenderId It may be caused by using a wrong FCM key or UDID
Uninstall The user exists in our db and has a device, we've sent the push but APNS/Firebase reported that the given device has uninstalled the app
FPErrTokenUnregistered The device token is inactive
FPErrBadRecipientToken The specified device token is invalid

Status: 200 OK

{
    "success":true,
    "result":{
        "report_url": "<LINK_TO_REPORT_FILE>"
        }
}

Status: 400

{
"status": "400",
"success": false,
"error_message": "No request found for ..."
}

Status: 202

{
"success": true,
"result": "Request not yet complete"
}

Cancel a batch

API to cancel a batch previously scheduled using the transac campaign or through the product UI. It returns the batch as it was scheduled.

PUT /api/campaigns/campaign_identifier/request/request_id/cancel

Query parameters

Property Type Description Default
campaign_identifier string The campaign identifier for which you want to cancel a request. campaign_id should be used here required
request_id string The ID of the batch to cancel. Retrieved in the output of the trigger POST call required

Response

Status: 200 OK

{
    "success":true,
    "result":{
        "campaign_identifier": "CGN_ACMECORP_1401106808015",
        "messages":[
            {
                "user_id":"john365",
                "template_variables":{"lastname":"Doe","firstname":"John","contractNumber":"ABC56"}
            },
            {
                "user_id":"duce23",
                "template_variables":{"lastname":"Duce","firstname":"JC","contractNumber":"234AE"}
            }
        ]
    }
}

Status: 400

{
"status": "400",
"success": false,
"error_message": "Request can't be canceled"
}

Status: 400

{
"status": "400",
"success": false,
"error_message": "The request REQUEST_ID for campaign CGN_ACMECORP_1401106808015 was not found"
}

Retrieve hits for a campaign

API to generate a status report of all message hits for a given transactional campaign.

GET /api/transac/campaignKey/hits?page=page&page_size=page_size&since_date=since_date

Query parameters

Property Type Description Default
campaignKey string The campaign unique key for which you are retrieving stats. campaign_id should be used here required
page integer The page of hits report to retrieve. Negative values causes a 400 error. 1
page_size integer The number of hits to retrieve per page. Range of values is [1..5000]. Values outside range cause a 400 error. 5000
since_date datetime Filter the results to only receive the data from this given date, expressed in any ISO format, e.g. 2017-04-06T16:41:44+05:00 -

Response

Status: 200 OK

{
    "success":true,
    "result":{
        "campaignKey": "THE_CAMPAIGN_KEY",
        "page": 1,
        "page_size": 500,
        "hits":[
            {
                "user_id": "your_user_id_45",
                "time": "2015-11-11T09:51:42Z"
            },
            {
                "user_id": "your_user_id_215",
                "time": "2015-11-13T09:51:44Z"
            },
            {
                "user_id": "your_user_id_45",
                "time": "2015-11-13T09:52:04Z"
            }
        ]
        }
}

Status: 400

{
    "status": "400",
    "success": false,
    "error_message": "Invalid parameter value ..."
}

Status: 404

{
    "status": "404",
    "success": false,
    "error_message": "Unknown campaign key ..."
}

Retrieve hits per user for a campaign

API to generate a status report of the message hits, per user, for a given transactional campaign.

GET /api/transac/campaignKey/hits_per_user?page=page&page_size=page_size&since_date=since_date

Query parameters

Property Type Description Default
campaignKey string The campaign unique key for which you are retrieving stats. campaign_id should be used here required
page integer The page of hits report to retrieve. Negative values causes a 400 error. 1
page_size integer The number of hits to retrieve per page. Range of values is [1..5000]. Values outside range cause a 400 error. 5000
since_date datetime Filter the results to only receive the data from this given date, expressed in any ISO format, e.g. 2017-04-06T16:41:44+05:00 -

Response

Status: 200 OK

{
    "success":true,
    "result":{
        "campaignKey": "THE_CAMPAIGN_KEY",
        "page": 1,
        "page_size": 500,
        "hits":[
            {
                "user_id": "your_user_id_215",
                "hits": 5
                "first_time": "2015-11-11T08:15:40Z",
                "last_time": "2015-11-13T09:51:44Z"
            },
            {
                "user_id": "your_user_id_215",
                "hits": 3
                "first_time": "2015-10-11T10:05:10Z",
                "last_time": "2015-11-13T09:51:00Z"
            },
        ]
    }
}

Status: 400

{
    "status": "400",
    "success": false,
    "error_message": "Invalid parameter value ..."
}

Status: 404

{
    "status": "404",
    "success": false,
    "error_message": "Unknown campaign key ..."
}