Conversions - now with time windows!

Read

API Triggered Broadcasts: welcoming a new campaign type!

by Ivana McConnell on Jan 24 2018

Say your app connects volunteers with local charities in need. You want to send a message to your volunteers every time a new charity in their locale puts in a request for volunteers. With API triggered broadcasts, you can send new requests for volunteers, as they come in, to everyone in a specific area and send those messages over any medium like email, SMS, or push.

When sending news or automated updates to groups of people, there’s no reason that these broadcasts can’t be just as relevant as the rest of your Customer.io messaging.

Introducing API Triggered Broadcasts from Customer.io! With this new campaign type, you can automatically send one message to many people quickly in response to an API call— but still use up-to-the-moment data to personalize it. This way, you set up your campaign and messaging once. Then all you need to do is set up your API call and you’re good to go.

Read on to learn more about this new campaign and how it works. We’ve also got a video for you!

What is it & how is it different?

API triggered broadcasts fit the bill when you need to set up a one-to-many message that triggers programmatically.

In a nutshell, API triggered broadcasts are built…

  1. to go out to a large number of recipients
  2. in response to a single REST API call
  3. for messages that recur frequently, with a similar structure but with different data.

The straightforward API triggered broadcast workflow allows you to automate these types of programmatic one-to-many messages without losing any personalization.

Here’s how it compares to the other types of campaigns you can create in Customer.io:

Segment Triggered Event Triggered API Triggered Broadcasts Newsletters
Message-to-recipient-relationship one-to-one one-to-one one-to-many one-to-many
Trigger Individual user behavior or attribute change Individual user performs an event External API call or manual send Manual or scheduled send
Sending Behavior First entering a segment Every time an event is performed Every time an API call is received One-time only
Channels Email, SMS, push, webhook, Slack Email, SMS, push, webhook, Slack Email, SMS, push, webhook, Slack Email only

So how does it work?

Now, when you go to create a new campaign, you’ll see the new API Triggered Broadcasts next to Segment and Event Triggered:

More campaign-triggering flexibility

There are a few differences in campaign creation, which we’ve thoroughly documented for you on our Knowledge base. But the biggest difference (and this campaign’s greatest strength) is the ability to define your recipients via our API at the moment of send. Here’s what we find exciting: this gives you maximum flexibility in targeting for your campaign, right within the API call — you can nest conditions to get as specific as you like. Developers: use any logic your app needs to determine the right targeting. (Here’s our doc on data formatting.)

You can also define recipients manually when you set up the campaign (but the API call is more dynamic and overrides whatever you set here.)

The same data-usage powers

You can use Liquid to leverage user data in API triggered broadcast messages, as with other campaigns in Customer.io, but here’s where a little extra flexibility comes in. Those attributes can be combined with structured data sent from your app that you’ve associated with this broadcast.

Once you set up a campaign, it’s not started; rather, it’s “activated” and waiting for you to let Customer.io exactly when you want to send it, and with which data!

Triggering via the API

That way, the moment you want to send, you can trigger the broadcast via our API, using that campaign’s specific ID. Using this ID, you can send us an API call that triggers this broadcast, dynamically defining your recipients and data at the moment of send, keeping the flexibility and control that Customer.io offers. We’ve written extensive docs on both how to trigger this, as well as how to integrate with our API.

Sending data

Your API call contains, among other things, the data you’d like your message to reference. Say you want to send a news broadcast to the coyotes interested in roadrunner-catching when there’s a roadrunner sighting in their state. Here’s an example of the data that might go with it (in JSON format):

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

Specifying Recipients

And this is the real power of API triggered broadcasts. When that roadrunner is sighted and the API call triggered, you can make sure that it’s targeted to a particular segment (say, coyotes) OR use attributes to specify coyotes interested in hunting whose state is New Mexico, and who are NOT also roadrunners (just to be safe!). Check it out:

{
  "recipients":{
    "and":[
      {
        "segment":{
          "id":7
        }
      },
      {
        "or":[
          {
            "attribute":{
              "field":"state",
              "operator":"eq",
              "value":"NM"
            }
          },
          {
            "attribute":{
              "field":"interest",
              "operator":"eq",
              "value":"hunting"
            }
          },
          {
            "not":{
              "attribute":{
                "field":"species",
                "operator":"eq",
                "value":"roadrunners"
              }
            }
          }
        ]
      }
    ]
  }
}

There’s tons of power in this, so we’ve documented it for you here, so you can be sure you’re formatting the data in the right way.

Measuring your results

As soon as you start sending, metrics will start populating. You’ll be able to see aggregate data, as well as data related to each individual triggered broadcast.

Or view an individual broadcast’s performance as soon as it’s sent:


Need someplace to get started?

We’ve made an intro video for you!


You can also check out our walkthrough of how to set up an RSS feed email campaign using API triggered broadcasts and Zapier to automatically sends new blog posts to your audience.

What’s next?

Too often, when we send mass notices via email or SMS, personalization loses out in favour of expediency. We want you to be able to use Customer.io’s message-programming powers for these larger audiences, too. Want to test a couple variations of a broadcast to find out what works best? Send broadcasts via SMS or Push? Send a specialized email to your most loyal customers whenever you’ve updated your inventory? API Triggered Broadcasts open all of these doors.

This is a brand new campaign type in Customer.io, and we’d love to hear how you use it, as well as what you might like to see from it in the future! Any and all feedback on the feature or its documentation will help us make it better. If you’ve got questions, feedback, or need a hand, we’re here for you win@customer.io!

Share this post

Did you enjoy this article? Spread the word