20

API-triggered broadcasts

An API-triggered broadcast is like an event-triggered campaign, but the event—the trigger—represents a group of recipients.

How it works

API-triggered broadcasts provide a way to send a one-to-many campaign on demand. It may help to think of API-triggered broadcasts like event-triggered campaigns, except the event comes from your backend integration and represents a group of people. For example, you might use an API-triggered broadcast to:

• Send news alerts to a group of people interested in a specific topic.
• Alert users interested in an event when tickets go on sale.
• Alert students when registration opens for a new online class.

Unlike a newsletter, you can reference trigger data in your API-triggered broadcasts with liquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable {{customer.first_name}}..

You also can’t have more than 5 broadcasts queued for a single API-triggered broadcast.

Create an API-triggered broadcast

The steps to set up an API-triggered broadcast are fairly simple, but each step includes settings that we’ve explained in the sections below.

1. Go to Broadcasts and click Create Broadcast.
2. Enter a name so your team members can easily find the broadcast on the landing page.
3. Click Messages triggered via API.

   

   
4. (Optional) Click the name and add a description so your team members can tell what the purpose of the broadcast is.

   

   
5. (Optional) Add one or more tags to help you organize and filter your broadcasts on the landing page.
6. Click Set goal. You can choose “No goal” if you don’t want to set one up.
7. Modify your settings und Messages to change what subscription center topic people must be subscribed to to receive messages. If you don’t have the subscription center enabled, we’ll send messages to people who are globally subscribed. Set a message limit if you want people to only receive a certain number of messages from you over a period of time.
8. Click Build at the bottom of the workflow. Click and drag a message, flow control, or data block from the panel onto your canvas. After you add your first block, you can drop subsequent blocks over any plus sign.

   

   
9. Decide your message sending behavior. By default, all messages are set to “Queue draft.” If you want messages to send automatically, click into each message and adjust the dropdown:

   

   
10. After you’re finished building your workflow, click Start Broadcast in the top right to review and start your broadcast. If you haven’t fully set up your broadcast, click Review items and complete setup.
11. Define your recipients and trigger your broadcast.

Set a goal

You can set up a conversion goal to track the success of messages and journeys based on whether or not a person performs an event, enters a segment, or exits a segment after they receive a message from your broadcast.

If a person performs your goal criteria within a configurable time frame after they receive a message in your workflow, we’ll mark the messageThe instance of a message sent to a person. When you set up a message, you determine an audience for your message. Each individual “send”—the version of a message sent to a single member of your audience—is a delivery. and journeyA person or data object’s path through your campaign. converted.

Goals help you determine the success of your broadcast, and follow conversion rates over time to try and improve your messaging strategies. See Goals for more information about conversions; api-triggered broadcasts have the same goal options as campaigns.

We track conversions for the following message/delivery types:

Slack and Create or update person actions are often internal or used for analytics purposes; they don’t always send messages to end-users. For that reason, we don’t attach conversions to them. You can enable webhook conversions on individual webhook actions.

Set up your workflow

The workflow defines the journey for people who receive the broadcast—the messages they receive and the actionsA block in a campaign workflow—like a message, delay, or attribute change. you perform. API-triggered broadcasts perform all actions in the workflow at the same time, so you can’t use delays or time windows in your workflow.

You can, however, send multiple messages if you want, or add additional actions like updating people’s attributes, sending events, and so on.

Define recipients & trigger your broadcast

You can manually define recipients or define them programmatically in your API call.

If you define them manually, you can either trigger the broadcast through the UI too or through an API call.

You might define your recipients in the UI if there’s a common group of people you send these broadcasts to. If you trigger the broadcast through an API call, note that the recipients defined there will override your UI conditions.

Define recipients via UI

After you activate an API-triggered broadcast, you can define the recipients mamnually.

To define your recipients in the UI,

1. Click Workflow.
2. Click Trigger > Edit Conditions.
3. Define your audience based on their attributes, segment membership, and/or message conditions.

Then you can trigger the broadcast through the UI or an API call.

Define recipients via API

In your API call, you can define recipients using a complex set of filters:

{
  "recipients": {
    "and": [
      {
        "attribute": {
          "field": "first_name",
          "operator": "exists"
        }
      },
      {
        "attribute": {
          "field": "likes_baseball",
          "operator": "eq",
          "value": true
        }
      }
    ]
  }
}

{
  "recipients": {
    "or": [
      {
        "segment": {
          "id": 4
        }
      },
      {
        "attribute": {
          "field": "likes_baseball",
          "operator": "eq",
          "value": true
        }
      }
    ]
  }
}

{
  "recipients": {
    "not": {
      "and": [
        {
          "segment": {
            "id": 3
          }
        },
        {
          "attribute": {
            "field": "likes_baseball",
            "operator": "eq",
            "value": true
          }
        }
      ]
    }
  }
}

{
  "recipients": {
    "segment": {
      "id": 3
    }
  }
}

{
  "recipients": {
    "attribute": {
      "field": "likes_baseball",
      "operator": "eq",
      "value": true
    }
  }
}

The people you set must already exist in your workspace. An API-triggered broadcast cannot create new people. Using an ID or an email that doesn’t belong to a person in your workspace will produce errors.

Add custom data for recipients

You can send custom data for each member of your broadcast using per_user_data or data_file_url. You can match data to people by id or email. For example, using the example below, you could use {{trigger.voucher_code}} to provide a custom coupon or voucher for your individual broadcast recipients.

{
    "data": {
        "headline": "Roadrunner spotted in Albuquerque!",
        "date": 1511315635,
        "text": "We received reports of a roadrunner in your immediate area! Head to your dashboard to view more information!"
    },
    "per_user_data": [
        {"id":"wiley","data": {"voucher_code": "FESwYm"}},
        {"email":"road@runner.net","data": {"voucher_code": "cYm6XJ"}}
    ]
}

{
    "data": {
        "headline": "Roadrunner spotted in Albuquerque!",
        "date": 1511315635,
        "text": "We received reports of a roadrunner in your immediate area! Head to your dashboard to view more information!"
    },
    "data_file_url": "https://myFile.example.com"
}

Trigger via UI

To trigger a broadcast through the UI,

1. Go to Triggering Details.
2. (Optional) Under Manual, you can include JSON data. Make sure you preview this data in your messages before you send.

   

   
3. Under Manual, click Trigger a Broadcast. After you confirm, you will immediately trigger the broadcast.

Note, you can’t schedule an API-triggered broadcast through our UI like you can a newsletter.

Trigger via API

In your API call, enter your broadcast ID. You can find it in the Triggering Details tab of an active broadcast.

Define liquid variables with JSON

In the UI or API, you can define liquid variables with JSON data. In the UI, go to Triggering Details. Or in your API call, add info to the data key. Make sure you preview with sample data in your message(s) before triggering the broadcast.

{
  "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!" 
  }
}

Track API-triggered Broadcasts

After you trigger your broadcast, you can track metrics. Go to the Overview tab and you’ll see when you last triggered your broadcast and metrics across all sends.

In the Broadcasts tab, you’ll see a history of all the times you triggered the broadcast, and how many recipients there were for each trigger. Click into an individual broadcast to check its performance.

Duplicate broadcasts

Duplicate an API-triggered broadcast to create your next broadcast faster or to run them in parallel for experimentation. You can copy entire broadcasts to preserve settings like recipient conditions, goals, and message settings in addition to their workflows. You must activate the duplicate broadcast before anyone can enter it.

To duplicate a broadcast:

1. Click broadcast settings  inline with the broadcast you want to copy.
2. Click Duplicate.

The duplicate uses the original broadcast’s name prefixed with [COPY] and appears at the top of the API-triggered broadcast tab. You need to activate it before people can enter the broadcast.

Frequently Asked Questions

What does “queueing” mean?

When you send an API call to trigger a broadcast, we put that broadcast in a queue. When it reaches the front, we start creating and sending messages or storing drafts depending on the sending behaviour you’ve selected. When it finishes, it drops out of the queue!

Per workspace, you can’t have more than 5 broadcasts queued for the same API-triggered broadcast. If you try to send more, you’ll get an error. You can retry the failed requests after the previous broadcasts finish sending.

Why can’t I add delays and/or time windows?

With API-triggered broadcasts, you’re meant to send one message to many people quickly or immediately in response to an API call or a recent change. For that reason, we haven’t added delays or time windows to the feature. That said, if you have a specific use case that necessitates time windows or delays in your broadcast, please let us know!

How many people can I message with a single API-triggered broadcast call?

There is no limit. You can pre-define a segment within Customer.io with the profiles you wish to message, or host a data file containing all profiles you wish to have messaged.