The Wait Until API Event Activity is a new Journey Builder activity released as part of the April 2021 Salesforce Marketing Cloud Release. It allows you to create a real-time experience for contacts by allowing an external event to trigger an action mid-journey. You can add the Wait Until API Event activity at any point inside your journey and when your customers reach that point in the journey, they will be held until an event occurs, before moving to the next activity in the journey. This activity has a mandatory split into two paths: for customers who take action and for customers who don’t, which allows you to create customized experiences for all contacts.

There are multiple use cases for this kind of activity, for example, moving subscribers to a different path in an abandoned cart journey when they finalize the purchase or triggering a confirmation email as soon as they take a specific action on your website. You could even get creative and use this activity to trigger an action as soon as your subscribers click on a specific link in an email you sent, which I will cover later in this article.

Configuring a Wait Until Event activity

The Wait Until Event Activity can be used in any kind of journey, and the journey doesn’t need to be triggered by an API event – the activity will work just as well in journeys with Data Extension, Salesforce, and other Entry Sources available. Configuring the Wait Until Event activity in a journey is very simple and takes just a few steps:

1. Drag the Wait Until API Event activity onto the canvas. The system adds a no-event path to the canvas for contacts who don’t respond.
2. Click to open the wait activity.
3. Select an API event or create one.
4. Click the Filter Criteria tab and set the filter criteria. You can use Contact data or Journey event data for the filter. Journey event data is the data related to the API event you chose rather than the journey’s entry source.
5. Click Done.
6. Click the Maximum Wait Duration tab and set the maximum number of hours or days contacts are held in this activity before taking the no-event path.
7. Click Summary and review your settings.
8. Click Done. Don’t forget to configure the no-event path. You can re-engage customers or have them exit the journey.

Upon creating a new API event for the Wait Until Event activity, you will be asked to choose a Data Extension – it can be either the Data Extension you are currently using for your journey or a different one. If you choose to use the same Data Extension as the one you’re using for the journey, make sure that you’re using a composite primary key or no primary key at all, as the Wait Until Event API will essentially add a duplicate record to your Data Extension each time it’s triggered.

Configuring the Wait Until Event API call

This is where it gets a little wild, as there is no technical documentation for the Wait Until Event API. The documentation redirects you to the API Event Entry Source documentation but turns out that the Wait Until Event API is exactly the same thing: you’re injecting contacts into a journey, with the only difference that they do not start from the beginning, but from the point where they were held in the Wait Until Event activity. If you’re not familiar with the API Event Entry Source and Firing an Entry Event, check out this article: Add subscribers to a Journey from a CloudPage using Fire Entry Event

For the purpose of this article, I built a simple Double Opt-In journey triggered by API:

First, I would make an API call to add subscribers to the journey. They would also be added to the journey’s Data Extension, where I was passing just two parameters – their email address and their DOI status, which in this case, was false:

	Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
	POST /interaction/v1/events
	Content-Type: application/json
	Authorization: Bearer YOUR_ACCESS_TOKEN
	{
	"ContactKey": {{emailAddress}},
	"EventDefinitionKey": {{EventDefinitionKey}},
	"Data": {
	"email": {{emailAddress}},
	"DOIConfirmed": "false" }
	}

view raw FireEntryEvent hosted with ❤ by GitHub

As mentioned earlier, I did not have a primary key in my Data Extension, which allowed for a duplicate record to be added to the Data Extension with a different DOI status when the API call was made:

	Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
	POST /interaction/v1/events
	Content-Type: application/json
	Authorization: Bearer YOUR_ACCESS_TOKEN
	{
	"ContactKey": {{emailAddress}},
	"EventDefinitionKey": {{WaitUntilEventActivityAPIkey}},
	"Data": {
	"email": {{emailAddress}},
	"DOIConfirmed": true }
	}

view raw WaitUntilEventActivityAPI hosted with ❤ by GitHub

This turned out to work very well and the contacts were immediately released from the Wait Until Event activity.

Other use cases for the Wait Until Event activity

Another use case that came to my mind was using this new activity instead of an Engagement Split inside a journey. When working with Engagement Splits, you need to set a specific wait time after which the journey will check whether the contact clicked on a link in the email or not. The Wait Until Event activity would allow you to take an action immediately after someone clicks on the link, without having to wait until the pre-defined amount of time passes.

To make that happen, I have created a CloudPage which serves the sole purpose of making the API call to release the contact who clicked on a link from the Wait Until Event activity and then redirects the contact to the target website. Instead of including a static link in your email, eg. http://www.salesforce.com, use the CloudPagesURL function to direct your subscribers to the CloudPage first, and include your link in a Redirect function at the end of the CloudPage. The contact clicking on the link doesn’t see any difference, as the redirect happens instantly and they are taken directly to the target page, and in the background, the contact gets released from the Wait Until Event activity and the journey continues. Here is the code I used on the CloudPage:

	%%[
	SET @emailAddress = AttributeValue("emailaddr")
	/* if needed, fetch other parameters passed from the CloudPagesURL function*/
	IF NOT EMPTY(@emailAddress) THEN
	]%%
	<script runat="server">
	Platform.Load("Core", "1");
	try {
	var email = Variable.GetValue("@emailAddress")
	//authenticate to get access token
	var authEndpoint = 'https://{{your endpoint}}.auth.marketingcloudapis.com/' //add your tenant specific endpoint
	var payload = {
	client_id: {{client Id}}, //add your client id
	client_secret:{{client Secret}}, //add your client secret
	grant_type: "client_credentials"
	};
	var url = authEndpoint + '/v2/token'
	var contentType = 'application/json'
	var accessTokenRequest = HTTP.Post(url, contentType, Stringify(payload));
	if (accessTokenRequest.StatusCode == 200) {
	var tokenResponse = Platform.Function.ParseJSON(accessTokenRequest.Response[0]);
	var accessToken = tokenResponse.access_token
	var rest_instance_url = tokenResponse.rest_instance_url
	};
	//make api call to release subscriber from the Wait Until Activity
	if (email != null && accessToken != null) {
	var headerNames = ["Authorization"];
	var headerValues = ["Bearer " + accessToken];
	var jsonBody = {
	"ContactKey": {{ContactKey}}, //pass the Contact Key
	"EventDefinitionKey": {{Wait Until Activity API Key}}, //add the Wait Until Activity API Key
	"Data": {
	//in the payload pass any data required in your data extension and
	//include the data as defined in the filter criteria in Wait Until Activity definition
	}
	};
	var requestUrl = rest_instance_url + "/interaction/v1/events";
	var fireEntryEvent = HTTP.Post(requestUrl, contentType, Stringify(jsonBody), headerNames, headerValues);
	var respo = fireEntryEvent.Response.toString();
	if (fireEntryEvent.StatusCode == 201) {
	Redirect('https://www.salesforce.com&#39;,false); //define the link where subscriber should be redirected
	}
	};
	} catch (error) {
	Write("<br><h2>Sorry, something went wrong.</h2><br>" + Stringify(error));
	}
	</script>
	%%[ELSE]%%
	Sorry, something went wrong.
	%%[ENDIF]%%

view raw WaitUntilEventActivityAPI-link-tracking.html hosted with ❤ by GitHub

When creating the CloudPage, remember to include the credentials of the Installed Package and in the payload of the call made to the Wait Until Event activity make sure to include all the data required in the Data Extension you’re using as well as defined in the filter inside the Wait Until Event activity.

---

Questions? Comments?

Leave a comment below or email me at zuzanna@sfmarketing.cloud.

---