API trigger for scenarios

The API trigger for scenarios lets you send personalized communications to targeted customer groups based on external events. These events can include a sports team winning, an article being published, a weather alert, a product returning to stock, and more.

With the API trigger, you can trigger one or more scenarios with a single API call while filtering the right audience and personalizing the messages. This simplifies the process, increases efficiency, and reduces costs by removing the need to launch campaigns manually.

Use cases

You can use the API trigger to send a communication when any of the following happens:

• A goal is scored in a football match.
• The price of a catalog item changes.
• Betting odds change.
• The weather changes from hot to cold.
• A weather alert is issued.
• A flight or train is canceled.
• A train platform has changed.
• An unforeseen event happens, such as a restaurant closing, a bus delay, or an airline delay.
• A new blog post is created.
• A new product has been added to the catalog.
• A product comes back in stock.
• A sporting event is about to start, and customers have bought tickets.
• An offer becomes available to current hotel guests.

Bloomreach determines who receives the communication based on customer attributes and, optionally, customer event history. This follows the logic defined in the scenario builder using the API trigger node and condition nodes.

Set up an API trigger

The following steps walk through an example setup for an insurance company. This company wants to send a dangerous weather alert to its clients to discourage driving and prevent accidents.

📘

Note

To enable this feature, contact your Customer Success Manager.

Understand the time window

When enabling the API trigger feature, a time window (in seconds) is configured to define how often an API trigger request can be made. For example:

• 1 means 1 request per 1 second.
• 10 means 1 request per 10 seconds.
• 60 means 1 request per minute (60 seconds).

This limit applies to all projects in your account. If your account contains a project with over 100,000,000 customers, the time window is at least 100 seconds. For projects with over 10,000,000 customers, the time window is at least 10 seconds.

Set up authentication

Authentication is required to send messages to the API trigger. Basic authentication requires enabling the API trigger permission for the public or private API key.

1. Go to Project Settings > Access Management > API.
2. Select Private API.
3. Under the Campaigns tab, check API trigger.

4. Save your changes.

Create an API trigger

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

Save the API trigger

Once you save your API trigger, the URL and an example payload are displayed.

Implement the calls from an external system to this URL. In this example, the external weather alert provider develops a connection to your endpoint and sends webhooks with your parameter information.

You can view all received calls in the Trigger log.

If you exceed the configured time window limit, you receive an HTTP 429 Too Many Requests error:

{
    "success": false,
    "errors": [
        "You are allowed to send 1 request per 10 seconds. Try again later"
    ]
}

Add the API trigger to a scenario

1. Go to Campaigns > Scenarios and click + New Scenario.
2. Select the API trigger you created.

You can also use API trigger parameters to filter specific API calls, such as filtering for a specific type of weather alert, like 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 your target audience or personalize your campaign content.

Design your message

Select a campaign node of your choice, such as an SMS message. Here's an example of what a weather alert SMS could look like.

Save and deploy your scenario.