API Triggered Broadcasts - Formatting Broadcast Data

Basic data formatting

We ask that you send us your data in JSON format, and recommend that you do so via our API.

Here’s a basic example of what some data might look like in JSON format:

{
  "data": {
    "headline": "Roadrunner spotted in Albuquerque!",
    "date": "January 24, 2018", 
    "text": "We've received reports of a roadrunner in your immediate area! Head to your dashboard to view more information!" 
  }
}

This can then be used as sample data in our Composer preview.

Overriding Recipients

For API Triggered Broadcasts, you can set recipients via the UI.

Defining recipients in the UI

This is useful for when you know your recipients will always need to meet the same condition(s). However, if you’re sending many Broadcasts with the same layout but only small differences between them (e.g., “Breaking News!” notifications, each with slightly different groups of users), we offer the option to set your recipient conditions in your API call. Here’s how to do that.

Keep in mind that recipients set via the API will override what is set in the UI.

General syntax

Here’s a condensed version of the formatting we’re going to use:

recipients_filter = '"recipients":{'(and|or|not|segment|attribute)'}';
and = '"and":['1*(recipients_filter)']'
or = '"or":['1*(recipients_filter)']'
segment = '"segment":{"id":'number'}'
attribute = '"attribute'":{"field":'string',"operator":'operator',"value":'string|number'}'
operator = '"eq"'|'"exists"'


A few examples follow, to show this syntax in context.

Specify recipients with segments

Find your segment ID You’ll need the numerical ID for each segment you’d like to target. This can be found in the UI by hovering over the segment info icon in the Segment Overview:

Finding segment ID - segment overview

Or on the individual segment page:

Finding segment ID - individual segment

Then, you can use it to define or override recipients with JSON that looks like this:

{
  "data": {
    "headline": "Roadrunner spotted in Albuquerque!",
    "date": "January 24, 2018", 
    "text": "We've received reports of a roadrunner in your immediate area! Head to your dashboard to view more information!" 
  },
  "recipients": {
    "segment": {
          "id": 1
        }
  }
}


Using multiple segment IDs

Here, you’ll need to format a boolean expression of segment IDs in JSON, like this:

"recipients": {
  "or": [
    {
      "segment": {
        "id": 7
      }
    },
    {
      "segment": {
        "id": 8
      }
    }
  ]
}

This would target people who belong to either segment 7 or 8. Use and if you’d like to target people in both segments.

Specify recipients with attributes

In addition to segment IDs, you can also specify or override recipients with attribute conditions. These accept two operators: eq and exists. If you need an is not equal or does not exist condition, use the not operator on an eq/exists attribute condition.

Note that you’ll need to separate the operator and value into separate entries!

{
  "data": {
    "headline": "Roadrunner spotted in Albuquerque!",
    "date": "January 24, 2018", 
    "text": "We've received reports of a roadrunner in your immediate area! Head to your dashboard to view more information!" 
  },
  "recipients": {
    "attribute": {
        "field": "interest",
        "operator": "eq",
        "value": "roadrunners"
    }
  }
}

Combining segments and attributes

Alternately, you can use a combination of segment and attribute conditions, using the general syntax above. Here’s an example of how to do that, with some simple data to go with it:

{
  "data":{
    "headline":"Roadrunner spotted in Albuquerque!",
    "date":"January 24, 2018",
    "text":"We've received reports of a roadrunner in your immediate area! Head to your dashboard to view more information!"
  },
  "recipients": {
    "and": [
      {
        "segment": {
          "id": 1
        }
      },
      {
        "or": [
          {
            "attribute": {
              "field": "interest",
              "operator": "eq",
              "value": "roadrunners"
            }
          },
          {
            "attribute": {
              "field": "state",
              "operator": "eq",
              "value": "NM"
            }
          },
          {
            "not":{
              "attribute": {
                "field": "species",
                "operator": "eq",
                "value": "roadrunners"
              }
            }
          }
        ]
      }
    ]
  }
}

Recipient List

In some situations it might be desirable to specify a list of recipients. These can be provided either through a list of customer ids or a list of email addresses.

Customer IDs

The list of customer ids is provided as a JSON array in the attribute ids.

If any of the customer ids in this array does not exist, the trigger API returns an error to the caller. If the boolean attribute id_ignore_missing is set to true the missing ids are ignored.

Here’s an example of how to do that, with some simple data to go with it:

{
  "data":{
    "headline":"Roadrunner spotted in Albuquerque!",
    "date":"January 24, 2018",
    "text":"We've received reports of a roadrunner in your immediate area! Head to your dashboard to view more information!"
  },
  "ids": ["wiley", "roadrunner", "acme"],
  "id_ignore_missing": true
}

Email Addresses

The list of emails addresses is provided as a JSON array in the attribute emails.

If any of the email addresses in this array do not correspond to an existing customer the trigger API returns an error to the caller. If the boolean attribute email_ignore_missing is set to true missing emails are ignored.

If any of the email addresses in this array corresponds to multiple customer ids the trigger API returns an error to the caller. If the boolean attribute email_add_duplicates is set to true all matching customers are added as recipients. Warning: be careful as this means that the same email address will be mailed multiple times.

For example, imagine you have the following sets of customers and attributes:

id: wiley
email: wiley@coyote.com

id: willey
email: wiley@coyote.com

In this case if you are matching on wiley@coyote.com there are two corresponding customers.

Here’s an example of the full JSON using emails.

{
  "data":{
    "headline":"Roadrunner spotted in Albuquerque!",
    "date":"January 24, 2018",
    "text":"We've received reports of a roadrunner in your immediate area! Head to your dashboard to view more information!"
  },
  "emails": ["wiley@coyote.com", "road@runner.net", "support@acme.com"],
  "email_ignore_missing": true,
  "email_add_duplicates": true
}