Trigger campaigns using APIs trigger-campaigns
About API-triggered campaigns about
With Journey Optimizer, you can create campaigns and then execute them from an external system based on user trigger using the . This allows you to cover various marketing and transactional messaging needs like password resets, OTP token, among others.
To do this, you first need to create an API-triggered campaign in Journey Optimizer, and then launch its execution through an API call.
Available channels for API-triggered campaigns are Email, SMS and Push messages.
➡️ Discover this feature in video
Create an API-triggered campaign create
Configure and activate the campaign create-activate
To create an API-triggered campaign, follow the steps below. Detailed information on how to create a campaign is available in this section.
-
Create a new campaign with the API-triggered type.
-
Choose the Marketing or Transactional category depending on the type of communication that you want to send.
-
Choose one of the supported channels and associated channel configuration to use to send your message, then click Create.
-
Specify a title and a description for the campaign, then click Edit content to configure the message to send.
note note NOTE You can pass additional data into the API payload that you can leverage to personalize your message. Learn more Using a large number or heavy contextual data in your content may impact performances. -
In the Audience section, specify the namespace to use to identify the individuals.
-
If you are creating a transactional-type campaign, the targeted profiles need to be defined in the API call. The Create new profiles option allows you to automatically create profiles that do not exist in the database. Learn more on profile creation at campaign execution
note note NOTE A single API call supports up to 20 unique recipients. Each recipient must have a unique user ID, duplicate user IDs are not permitted. Learn more in the -
For marketing-type campaigns, click the Audience button to choose the audience to target.
-
-
Configure the campaign’s start and end dates.
If you configure a specific start and/or end date for a campaign, it will not be executed outside these dates, and API calls will fail if the campaign is triggered by APIs.
-
Click Review to activate to check that your campaign is correctly configured, then activate it.
You are now ready to execute the campaign from the APIs. Learn more
Execute the campaign execute
Once your campaign has been activated, you need to retrieve the generated sample cURL request and use it into the API to build your payload and trigger the campaign.
-
Open the campaign, then copy-paste the payload request from the cURL request section. This payload includes all personalization (profile and context) variables used in the message. It is available once the campaign is live.
-
Use this cURL request into the APIs to build your payload and trigger the campaign. For more information, refer to the .
API call examples are also available in .
note note NOTE If you have configured a specific start and/or end date when creating the campaign, it will not be executed outside these dates, and API calls will fail.
Use contextual attributes in API-triggered campaigns contextual
With API-triggered campaigns, you can pass additional data in the API payload and use them inside the campaign to personalize your message.
Let’s take this example, where customers want to reset their password, and you want to send them a password reset URL that is generated in a third-party tool. With API-triggered campaigns, you can pass this generated URL into the API payload, and leverage it into the campaign to add it into the message.
In order to use these data in your campaigns, you need to pass them into the API payload, and add them in your message using the personalization editor. To do this, use the {{context.<contextualAttribute>}} syntax, where <contextualAttribute> should match the name of the variable in your API payload containing the data that you want to pass.
The {{context.<contextualAttribute>}} syntax is mapped to a String datatype only.
context.system syntax is restricted to ۶Ƶ internal usage only, and should not be used to pass contextual attributes.Note that, for now, no contextual attribute is available for use in the left rail menu. Attributes must be typed directly in your personalization expression, with no check being performed by Journey Optimizer.
Profile creation at campaign execution profile-creation
In some cases, you may need to send transactional messages to profiles that do not exist in the system. For example if an unknown user tries to reset password on your website.
When a profile does not exist in the database, Journey Optimizer allows you to automatically create it when executing the campaign to allow sending the message to this profile.
To activate profile creation at campaign execution, toggle the Create new profiles option on in the Audience section. If this option is disabled, unknown profiles will be rejected for any sending and the API call will fail.
How-to video video
Learn how to create a campaign and trigger it from an external system based on user interactions, using the Interactive Message Execution REST API.