API-based Entry
Launch a journey whenever you need by sending an API request
Last updated
Launch a journey whenever you need by sending an API request
Last updated
API-based Entry allows you to launch a customer journey the moment a specific business event occurs. To start a campaign, you have to send a special API request.
Here are a few use cases for an API-based Entry:
Inform customers whenever some of your products are back in stock;
Tell users that the price of a popular product has decreased;
Notify subscribers that a new podcast episode is out.
Unlike regular Events, all these business events may occur outside the app. For example, a product's availability can only be checked in an external database. This is where an API-based Entry comes in handy: you can set up sending a request to launch a journey whenever certain changes occur outside of the app (for example, in your external database).
It works as follows:
Create a journey with an API-based Entry. In the Entry settings, you will find the template of the request that launches the journey.
Add segmentation conditions to the request using Segmentation language. You can also add content placeholders to the request to change message content depending on the context.
Automate the request if needed. For example, information about a price change can be immediately sent from the database to the webhook. Once this happens, the webhook should automatically send the request to launch the journey. You can also send the request manually if you don't need automation.
You can send the request an unlimited number of times to change segmentation conditions or the message content.
For more details, follow the instructions below.
You may need help from a developer to set up an API-based Entry.
1. Create a journey with an API-based Entry:
2. Double-click on the API-based Entry step. The Entry configuration window will open.
3. You can modify the push and email content every time the journey is launched by using content placeholders. The value of each placeholder can be changed in the request. If you don't need this option, you can skip this step.
For example, you are creating a journey to notify subscribers when a new podcast episode is released. Using a content placeholder, you can change the podcast title every time you launch the journey.
First, add placeholder names in the API-based Entry setup window. You can use any names that are convenient for you.
Now, create a push or email Preset and insert the placeholder instead of the text you want to modify. The placeholder must be in one of the following formats depending on your needs:
{placeholder_name|format_modifier|} – if the placeholder value is not specified when launching the campaign, users will see empty space in its place.
{placeholder_name|format_modifier} – if the placeholder value is not specified and has not been already assigned to a user (in case you used a Tag as a placeholder), the message will not be sent.
You can also use an existing Tag name instead of a placeholder name. In this case, you have to configure overwriting this Tag value by the value specified in the request as described below.
When configuring the Push or Email step in your journey, select the created preset and turn on the Personalize message with event attributes option. Select the placeholders you want to modify in the request when launching the journey. Choose the API-based Entry entry as the source and the placeholder name as the dynamic attribute:
Click Apply to save changes.
4. In the Entry configuration window, copy the request template to modify it:
5. Add audience filters to the "filter" parameter using Segmentation language or copy the segmentation language from the Segments you've created earlier. Please note that you need to set up the necessary Tags in advance.
For example, if you want to target the journey at users who added the Socks item to their Wishlist, the "filter" value must look as follows:
"filter": "A(\"12345-12345\") * "T(\"Wishlist\", EQ, \"Socks\")"
In this example, you must have a Wishlist Tag configured in your app.
Your application code will be automatically added to the "filter" parameter in the A(\"12345-12345\") format. Please do not remove or modify it.
Also, please keep in mind that quotes ("") and backslashes (\) should be escaped with a backslash (\) in JSON queries.
6. If you’ve set up placeholders, specify the desired content as their values:
7. If the Message Rate Limits option is enabled, the number of users entering the journey at once every second will be limited. You can use the default value of 5000 users per second or set another number.
We recommend keeping the value between 5000 and 10000 users per second. If the value is too low, it might take longer for your audience to enter the journey. If the value is too high, the service that processes your data can be overloaded.
8. If you plan to restart your campaign frequently and don't want the same users to enter the journey multiple times, set Frequency Capping.
For example, you’ve created a campaign to notify users about a price reduction for a specific product. You want to re-launch the journey a few times by sending several requests with different audience filters. In this case, you can add Frequency Capping so that the notification is not sent repeatedly to users that match multiple filters.
9. If you want a journey to launch whenever a certain business event happens, automate the request using the webhook. Once the event occurs, the webhook should automatically send the request to start the journey.
You can also send the request manually if you don't need automation.
If you change the segmentation conditions when sending a new request, this will not affect users who have already entered the journey.
If you change the message content when sending a new request, all users will receive the new version of the message (including those who already entered the journey but have not received this message yet).
