Setting Up Conditional Execution

When executing campaigns, Optimove’s decides which customers are eligible to be in a Target Group based on your batch data. In some cases, you may need a third-party system to approve whether customers within that Target Group are eligible for the campaign, for example for compliance reasons or promo activation.

Conditional Execution is a functionality that creates an approval flow between Optimove and your internal systems via API. This ensures the campaign is executed only for customers who are eligible to receive it according to the conditions of your internal systems, e.g., the Promotion System. You can see Conditional Execution as a toggle in the Campaign Builder.

This article outlines how to set up the API integration to enable Conditional Execution.

Please note: If the Conditional Execution checkbox does not appear in your Optimove UI, ask your Customer Success Manager to activate it.

This article will cover the following topics:

Conditional Execution for Scheduled Campaigns
Conditional Execution for Triggered Campaigns

Please note: All the API calls mentioned throughout this document can be found in the Optimove API Guide. You might also want to refer to Getting Started with the Optimove API.

Conditional Execution for Scheduled Campaigns

Step 1: Register a Listener

Your system needs to register a listener to receive notifications for scheduled Conditional Execution campaigns using EventTypeID=5. Refer to the [RegisterEventListener] API call documentation for details. This step only needs to be done once for all future scheduled conditional campaigns.

Step 2: Optimove Notifies the Listener that the Campaign is Ready to be Sent

Once the campaign using Conditional Execution, Optimove processes the campaign and notifies the listener of your system specified for EventTypeID=5. At this point, Optimove will wait until the Clearance Required By time has arrived before actually scheduling the campaign for execution.

Important Note:

When using Conditional Execution, the Target Group of the campaign will be sent to your internal system in advance, giving your system time to review the customers and decide whether they should receive the campaign. The approval should arrive by the Clearance Required By time, which by default is 30 minutes before campaign execution (configurable upon request).

The Clearance Required By time is communicated to the listener at the time of EventTypeID=5 notification.

The structure of the request:

{
  "EventTypeID":5,
  "TimeStamp":"YYYY-MM-DD HH:MM:SS",
  "CampaignID":x,
  "CampaignDuration":y,
  "ClearanceRequiredBy":"YYYY-MM-DD HH:MM:SS"
}

///Note: ClearanceRequiredBy is calculated by Optimove based on the campaign's selected execution channel(s).

Step 3: Internal Systems Review Which Customers Receive the Campaign

Once your listener receives a notification that the campaign is ready, your system calls GetProcessedCampaignCustomers to retrieve the list of customers included in this campaign.

Step 4: Notify Optimove Which Customers Should Receive the Campaign

Once the customers have been reviewed, your system notifies Optimove that customers should receive the campaign. This is accomplished using the UpdateCustomerPromotionStatus API call.

Step 5: Optimove Sends the Campaign to Eligible Customers

Once the campaign's specified Clearance Required By time arrives, Optimove will schedule the campaign for execution only to the approved customers.

Customers that were not approved will not receive the campaign.

Conditional Execution for Triggered Campaigns

Step 1: Register a Listener

Your system needs to register a listener to receive notifications for triggered Conditional Execution campaigns using triggered_conditional_execution_gateway .

For details, refer to the Set Conditional Gateway documentation. This step only needs to be done once for all future triggered Conditional Execution campaigns and channels.

Step 2: Optimove Notifies the Listener that the Campaign is Ready to be Sent

Once the campaign using Conditional Execution and a customer has met the Trigger criteria, an HTTP request will be sent with a payload containing the campaign and customer details.

The API payload you will receive in real-time is described in 'triggered_conditional_execution_gateway’ API call.

{
  "user": {
    "user_id": "string", // Customer ID or Visitor ID
    "is_visitor": "boolean"
  },
  "campaign": { // The executed occurrence of a specific campaign series
    "id": "string | number", // The ID of the specific campaign in the series AKA Action Serial
    "series_id": "string | number", // The ID of the whole series AKA Plan ID
    "notes": "string",
    "tags": [
      "string"
    ],
    "action": {
      "id": "number", // The unique ID of the action
      "name": "string",
      "promo_codes": ["string"], // Nullable
      "channels": [ // Not nullable
        {
          "id": "number",
          "name": "string",
		      "brand_id": "string | nullable",
          "templates": [ // Nullable
            {
              "id": "number",
              "name": "string"
            }
          ]
        }
      ]
    }
  }
}

Note: "user_id" can be both "customer_id" and "visitor_id", according to the flag "is_visitor".

Step 3: Notify Optimove if the customer is eligible to receive the campaign

Once Optimove sends the HTTP request, it will wait for the approval that the customer is eligible to receive the campaign. To ensure real-time delivery, if a response is not received by the default time (up to 2000 ms) the customer will not receive the campaign.

The expected response is True / False:

True = The customer is eligible to receive the campaign
False = The customer should not receive the campaign

{
    "user_id": "string", 
    "allowed" : "boolean" // True : The user should receive the campaign
                          // False : The user should not receive the campaign
}

Note, you have the option to configure the default time between the range of 0-2500 ms. If you want to change the configuration, please contact your Customer Success Manager.

Step 4: Optimove Sends the Campaign to the Customer

Once Optimove receives approval, the campaign will be sent to the customer using the selected channel/s.

If the customer was not approved by the required time or the customer was not eligible, they will not receive the campaign.

Use Cases

Promo Activation

For campaigns with promotions or bonuses, you may want to ensure that your campaign is sent only to customers for whom the promotion was already activated in your promo/bonus system.

Optimove’s Conditional Execution allows you to ensure that only customers who are eligible for the specific promotion or bonus receive the relevant campaign.

For example, perhaps you want to send an email campaign to 1000 customers, offering a particular promotion (e.g., 10% off the entire store). You will set up the campaign in Optimove so that Optimove will first activate this promotion for the customers in your promotion system. Only after the promotion was successfully activated for these customers, will they receive the campaign.

Optimove will not send the campaign to any customers for whom the promo activation failed (whatever the reason for the failure).

Information about how to add promotions to the system can be found [here].

Compliance Check

Conditional Execution can be used to enforce compliance checks within your campaigns. By integrating with a third-party system that manages compliance checks, Conditional Execution enables the customer eligibility according to regulatory standards.

For instance, Conditional Execution allows you integrate with systems that validate a player's eligibility based on factors like minimum deposit thresholds, account statuses, or geographical location before delivering promotional offers or bonuses. This ensures that promotions are only executed to customers who comply with regulatory guidelines.