API Trigger Campaigns Endpoint

Overview

The below sequential scheme describes the endpoints available to use our campaign APIs:

Using the endpoints described in this page will consume your API Trigger requests quota in your subscription.

Prerequisites

Use an existing template

Creating or cancelling a request applies for ongoing API Trigger campaigns! Hence it requires an API Trigger campaign to be launched (batches cannot be sent on draft campaigns) from GROW before starting to use this API.

To use your template in an API call. Go to your campaign in GROW first and retrieve the campaign identifier of the template you would like to use. A Copy campaign ID CTA will be available in the campaign actions list.

Keep this identifier, you will use in soon to send batches!

Minimum privilege

The only prerequisite to use those APIs is to retrieve a token with minimum privilege: GROW member. Long story short: if you were able to launch a campaign for your tests with this account on GROW UI, you are good.

Check our Authentication API for more information on how to retrieve a token.

Create a request

Endpoint

This endpoint allows sending a batch of transactional messages to a list of users.

Endpoint: POST https://core.bryj.ai/api/campaigns/trigger

This endpoint can leverage 2 different methods:

  • JSON body: useful for testing, not suited for production as it cannot scale to volume.
  • CSV-based batch (recommended): The most scalable option as it can be used to automate batches on the fly.

JSON Body batch

Please find below the parameters to be used in calls made through a JSON Body.

Only for small audiences (a hundred of users per call). We highly recommend using csv-based batch for larger audiences.
PropertyTypeDescriptionDefault
campaign_idStringThe campaign identifierrequired
send_atDatetimeA date when the sending should be done, expressed in the ISO format Date and time of day for calendar date (basic or extended)
%Y%m%dT%H%M%S%z => 20071119T083748-0600 (basic)
%FT%T%:z => 2007-11-19T08:37:48+01:00 (extended)

If this parameter is not set, the batch will be sent “now“.
messagesArray of objectsThe parameters of the messages to send to the app’s usersrequired
message[user_id]StringThe userId to whom the message must be sentrequired
message[template_variables]Object (key – value)The variables used in the message template. Key is the variable key, value is the value to assign to it for this user

Example

{
  "campaign_id":"CMP_Dl3Egjp4HA",
  "send_at": "2022-05-10T13:00:00+01:00",
  "messages": [
    {
      "user_id":"USER_ID1",
      "template_variables": {"lastname":"DUPONT","firstname":"Pierre","contractNumber":"123456"}
    },
    {
      "user_id":"USER_ID2",
      "template_variables":{"lastname":"DUPONT","firstname":"Thomas","contractNumber":"123456"}
    }
  ]
}

CSV-based batch

Please find below the parameters to be used in calls made through a CSV batch.

Recommended for all uses, small or large audiences. This is the most scalable option.
This method requires the file to be attached to the API call (sending the file content in a body will not work)
PropertyTypeDescriptionDefault
campaign_idStringThe campaign identifierrequired
send_atDatetimeA date when the sending should be done, expressed in the ISO format Date and time of day for calendar date (basic or extended)
%Y%m%dT%H%M%S%z => 20071119T083748-0600 (basic)
%FT%T%:z => 2007-11-19T08:37:48+01:00 (extended)
If this parameter is not set, the batch will be sent “now“.
fileFileIt represents the .csv file uploaded (attached) on the body params as form-data.
The CSV file must be encoded with UTF-8, with , as separator, and have in the header the “User” key and the variables names defined in the campaign (in the examples above: contractnumber, firstname, lastname).
The file can be directly uploaded as 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.
The maximum authorized file size is 1 Go.

Example using a local CSV file

This method is useful for manual testing of the API.

  • Query structure in postman
  • File content
User,contractnumber,firstname,lastname
user_id1,123456,Pierre,DUPONT
user_id2,123456,Thomas,DUPONT

Example using a code-based

Towards the end of the documentation, you will find code sample in Ruby on how to call this endpoint. It is your responsibility to adapt this approach to your development language if necessary.

Response

General

  • Status OK: 200 (OK)
{
  "request_id": "REQUEST_ID"
}

The request_id is returned if the request is successful. This id can be used to get the status of the campaign or cancel it.

  • Status KO : HTTP_RESPONSE_ERROR_CODE (ERROR)
{
  "error_message": “ERROR_MESSAGE”
}

Examples

  • Status OK
{
  "error_message": “ERROR_MESSAGE”
}
  • Status: 400 (BAD REQUEST)
{
  "error_message": "You must provide a campaign identifier'"
}
{
  "error_message": "Campaign with identifier FACMPGN_Z6gIfLT8LhIDKSa8 is not ready"
}

Cancel a request

API to cancel a request previously scheduled using the API Trigger campaign or through UI (for now only available for API calls, not yet in the product UI). It returns the request as it was created.

A request which is already processed (sent_at time is passed) cannot be cancelled.

Endpoint

  • PUT : https://core.bryj.ai/api/campaigns/request/request_id/cancel

Parameters (URL):

PropertyTypeDescriptionDefault
request_idstringThe ID of the request to cancel.required

Example:

  • PUT : https://core.bryj.ai/api/campaigns/request/4c74a153ff6f31c7ac75480e06373d6/cancel

Response

{
  "request_id": "REQUEST_ID",
  "campaign_id": "CAMPAIGN_IDENTIFIER",
  "requested_at": "CREATED_AT date as EPOC timestamp",
  "to_be_send_at": "SEND_AT date defined on creation as as EPOC timestamp",
  "messages": "MESSAGE_JSON_OR_LINK_TO_MESSAGE_FILE"
}

Examples:

  • Status: 200 (OK)
{
  "request_id": "4c74a153ff6f31c7ac75480e06373d6b",
  "campaign_id": "CMP_Dl3Egjp4HA",
  "requested_at": 6565465464564,
  "to_be_send_at": 9885454678877,
  "Messages": 
  {
    "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 (Bad Request)
{
  "error_message": "Request can't be canceled"
}
{
  "error_message": "The request 4c74a153ff6f31c7ac75480e06373d6 was not found"
}
Canceling a request less than 5 minutes before sent time will not guarantee, in extreme cases, that the request will be canceled (partially or completely).

Get scheduled requests

API to get the list of scheduled requests for a given campaign.

Endpoint

GEThttps://core.bryj.ai/api/campaigns/campaign_id/request/scheduled

Parameters (URL):

PropertyTypeDescriptionDefault
campaign_idStringThe campaign identifier for which the scheduled requests will be fetched.required

Response

{
  "campaign_id": "CAMPAIGN_IDENTIFIER",
  "requests": [
    {
      "request_id": "REQUEST_ID1",
      "requested_at": "CREATION_DATE_AS_INTEGER",
      "to_be_send_at": "SEND_DATE_AS_INTEGER",
      "messages": [
        {
          "user_id": "USER_ID",
           "template_variables": {...}
        }
      ]
    },
    {
      "request_id": "REQUEST_ID2",
      "requested_at": "CREATION_DATE_AS_INTEGER",
      "to_be_send_at": "SEND_DATE_AS_INTEGER",
      "messages": [
        {
          "user_id": "USER_ID",
           "template_variables": {...}
        }
      ]
    }
  ]
}

Example: 

GET : https://core.bryj.ai/api/campaigns/CMP_Dl3Egjp4HA/request/scheduled

  • Status: 200 OK
{
  "campaign_id": "CMP_Dl3Egjp4HA",
  "requests": [
    {
      "request_id": "b863434d453693a62d306066b80be6c7",
      "requested_at": 1652281434,
      "to_be_send_at": 1654514804,
      "messages": [
        {
          "user_id": "vika-alpha",
           "template_variables": {}
        }
      ]
    },
    {
      "request_id": "885076d997db58abe9b2bd2449912619",
      "requested_at": 1652286782,
      "to_be_send_at": 1654514804,
      "messages": [
        {
          "user_id": "vika-alpha",
          "template_variables": {}
        }
      ]
    }
  ]
}
  • Status: 400 (BAD REQUEST)
{
  "error_message": "Campaign with identifier CMP_Dl3Egjp4HA was not found"
}

Retrieve reports

This API will be useful to build automated reporting on the status of sent batches. It will allow you to know which notifications where sent and if not sent, retrieve potential errors.

As each call will consume your API Trigger requests quota. We advise you to make this call 30 minutes after the batch sending datetime to optimize your quota consumption.

Endpoint

GET https://core.bryj.ai/api/campaigns/report?request_id=REQUEST_ID

Parameters (URL)

PropertyTypeDescriptionDefault
request_idStringThe ID of the request to retrieve report.required

Response

Returned JSON will provide links to CSV reports, available for 1 hour. For every apps (android and iOS), we will have at least one report file.

{
  "request_id": "REQUEST_ID",
  "reports": [
    "https://bucket.s3.eu-west-1.amazonaws.com/.../request_id/202209020739/e93413b2ee9fe97112ab739541c6353f.csv/part-0000",
    "https://bucket.s3.eu-west-1.amazonaws.com/.../request_id/202209020739/e93413b2ee9fe97112ab739541c6353f.csv/part-0000",
    ...
  ]
}

File structure

A report file contains the following columns:

Column nameDescription
app_idThe app identifier
campaign_idThe campaign identifier
user_idThe user id
device_idThe device id
sent_atThe sent at time for pushes, or the published at time for in-apps
request_idThe request id
channelpush or inapp
error_messagePossible values for the error message are the following:
– Empty : message sent successfully
In progress (push results being processed)
Last user not logged in when the targeted user is not logged in anymore
App uninstalled when the targeted user does not have the app installed on its device anymore – retrieved from the push servers
Opt out when the targeted user is not opt-in for pushes anymore – retrieved from the push servers
No device for user when the targeted user has no record in GROW.
FPErrBadRecipientToken when the push token expires
FPErrTokenUnregistered when the push token is not recognized by firebase or apns
FPErrJSONMarshalling when the internal push server have an error when parsing the push message
FPErrPushFailed when firebase or apns could not deliver the push

Appendix – CSV-based batch in Ruby

class TransactionalRequestPost
  def send_request
    # load the csv file (needs to be a File object)
    file = File.new('/Users/ahmed/Documents/test.csv')

    # Body parameters: a valid campaign identifier and a File for the targeted users
    params = {
      campaign_id: 'CMP_lTJytx73_g',
      file: file
    }

    # Headers: content type multipart/form-data and the an authorization token (got from authentication endpoint)
    token = 'Bearer YOUR_AUTHENTICATION_TOKEN'
    headers = {
      'Content-Type' => 'multipart/form-data',
      'Authorization' => token
    }

    # Do a post query
    http_post(headers, **params)
  end

  def http_post(headers, **options)
    # URL
    url = 'https://core.bryj.ai/api/campaigns/trigger'

    # Do an HTTP Post request
    http_party_response = HTTParty.post(url, headers: headers, body: options)

    # Parse the response
    if http_party_response.response.is_a? Net::HTTPOK
      Rails.logger.info "The request '#{http_party_response.parsed_response['request_id']}' was created successfully"
    else
      Rails.logger.info 'The request is failed'
    end
  end
end

Running the example above in a Rails console (Ruby) you will have:

➜ core-backend git:(master) ✗ rails c
Running via Spring preloader in process 27456
Loading development environment (Rails 6.1.6)
[1] pry(main)> test = TransactionalRequestPost.new
=> #TransactionalRequestPost:0x00007fee5033f658
[2] pry(main)> test.send_request
The request 'b615b03a0c538be18cd2c8610cca1d79' was created successfully

Appendix – CSV-based batch in cURL

curl --location --request POST 'https://core.bryj.ai//api/campaigns/trigger' \
--header 'Authorization: Bearer YOUR_AUTHENTICATION_TOKEN' \
--form 'file=@"/YOUR_FILE_PATH/test.csv"' \
--form 'campaign_id="CAMPAIGN_ID"'

Troubleshooting

Bellow the error messages that can be returned by the different endpoints :

  • You must provide a campaign identifier : when the campaign_id is not defined in the parameters
  • Empty campaign identifier : when the campaign_id is an empty String or blank.
  • Campaign identifier must be a String : when the campaign_id is not a String (example: sending a number or an array of String).
  • Unknown campaign with identifier WRONG_CAMPAIGN_ID : when the campaign_id is not found
  • Campaign identifier CMP_XXX for the app identifier APP_XXX is not ready : when the campaign is not started or has ended (finished or stopped).
  • Invalid time format: when the sent_at parameter is not in the accepted format.
  • The delivery time is in the past, please change it : when the sent_at more than 5 minutes in the past.
  • Must provide JSON messages or a CSV file : when there is no attached file and no JSON messages at the same time.
  • Must provide either JSON messages or a CSV file : when there is an attached file and a JSON message at the same time.
  • Unsupported file format - only csv files are supported : when the attached file is not in CSV format.
  • Invalid file : 'User' column is missing : when the CSV file doesn’t contain User in the headers.
  • Invalid messages : 'user_id' key is missing : when the JSON messages don’t contain the key user_id.
  • Invalid file : missing variables : (var1, var2,..) : when not all the variables defined on the campaign message are present in the JSON body of the file.
  • Error when reading CSV file: {message} : when we encounter unexpected error when parsing the CSV file content (examples: not expected file encoding, file not correctly structured or contains not allowed characters).
  • The request WRONG_REQUEST_ID was not found : when the request_id is not found
  • You must provide a request_id : when request_id is not defined in the parameters
  • Request identifier must be a String : when the request_id is not a String.
  • Request already canceled : when trying to cancel an already canceled request.
  • Request can't be canceled : when trying to cancel a request that already started to be processed.
  • Request not processed yet : when trying to get reports for a request not processed yet.
  • Batches not published yet : when trying to get reports for an inapp campaign request not completly published