API trigger for scenarios

The API trigger for scenarios allows you to send personalized communications to targeted groups of customers. These messages are based on external "world" events like a sports team winning, an article published, a weather event, a back-in-stock product, and more.

With the API trigger, you can trigger one or more scenarios with just a single API call while also managing to filter the right audience and personalize the messages. This new feature simplifies the process, increases efficiency, and reduces costs, as you no longer have to launch campaigns manually.

How to set it up

Review the example setup for an insurance company. This company wants to send out a dangerous weather alert to its clients to discourage them from driving to prevent accidents.

📘

Note

To enable this feature, contact your CSM.

When enabling the API trigger feature, we'll configure a time window (in seconds) during which an API trigger request can be made. For example:

• 1 would mean 1 request per 1 second
• 60 would mean 1 request per minute (60 seconds)

This limit applies to all projects in your account.

If the account contains a project with over 100M customers, the time window will be at least 100 seconds. For projects with 10+M customers, the time window will be at least 10 seconds.

Authentication

Authentication is required as a security measure to send messages to the API trigger. Basic authentication is straightforward and requires the enablement of API trigger permission for the public or private API key.

1. Go to Project Settings > Acess Management > API.
2. Select Private API.
3. Check the API trigger under the Campaigns tab.

4. Save your changes.

Set up a new API trigger

1. Go to Data & Assets > API trigger and click on Add API trigger.
2. Specify the parameters that will be sent in the payload. This insurance company has an external provider of weather alerts per postcode.

Save the API trigger

Once you save your API trigger, the URL of the API trigger and an example payload will be shown.

Implement the calls from an external system to the URL from the previous step. For example, the external provider of weather alerts develops a connection to your endpoint and sends you webhooks with your parameter information.

You can see the received calls in the Trigger log.

Add API trigger node into a Scenario

Go to Campaigns > Scenarios and click + New Scenario.

Select the API trigger you created in the first step.

You can also use the API trigger parameters to filter only specific API calls. This can be the type of weather alert, such as a snowstorm.

Define the conditions

Within the Scenario, use Jinja to access parameters sent in the payload. The format is {{params.name-of-the-parameter}}. Use it in conditions to filter down your target audience or to personalize your campaign content.

Design your message

Select a campaign node of your choice, such as an SMS message. This is what such a weather alert could look like.

Save and deploy.

Use cases

You can send a communication via API trigger for example, when:

• A goal is scored in a football match
• The price of an item in a catalog changes
• Betting odds change
• Weather changes from hot to cold
• A weather alert is issued
• A flight or train is canceled
• A train platform is changed
• An unforeseen event happens (restaurant closes, bus delayed, airline delayed)
• A new blog post is created
• A new product is added to the catalog
• A product comes back into stock
• X hours before a sporting event is about to start to anyone who has bought tickets
• An offer is available in a hotel to all guests

Bloomreach Engagement chooses who to send the communication to based on customer attributes and, optionally, customer event history. Such a choice follows the logic in the scenario builder using the API trigger node and condition nodes.