Setting Up Conditional Execution

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 Webhook

Register one or more webhooks to receive notifications for triggered Conditional Execution campaigns. All webhooks will receive all notifications, and Optimove will respect the first response received for each customer and campaign action within the defined timeout. This step only needs to be done once for all future triggered conditional campaigns. Refer to the CreateWebhook API call documentation for details. Additional webhook management APIs include GetWebhooks, GetWebhookById, and DeleteWebhook.

Webhook Registration API Call:

• CreateWebhook
  • Request payload:
    JSON

    {
      "url": "string" // The webhook's URL. Not Null.
    }
    

  • Response payload 201 Created:
    JSON

    {
      "url": "https://example.com/webhook",
      "id": "webhook1" // "string"
    }
    

Step 2: Optional - Define Tenant Settings

Define the response timeout (default is 5000 milliseconds) and, optionally, a shared HMAC secret string for authorization with Optimove using the UpdateWebhookSettings API call. A minimal timeout is recommended to ensure campaigns are sent as close to real-time as possible. You can retrieve settings with GetWebhookSettings or update specific properties with PatchWebhookSettings.

Tenant Settings API Call:

• UpdateWebhookSettings
  • Request payload:
    JSON

    {
      "timeout": "number", // In milliseconds, default value is 5000 (5 seconds). Not Null.
      "secret": "string" // Optional. Used for HMAC signature verification.
    }
    

  • Response payload 200 Ok:
    JSON

    {
      "timeout": "number",
      "secret": "string"
    }
    

Step 3: Request Activation of Triggered Conditional Execution

Contact your Customer Success Manager (CSM) or Customer Success Engineer (CSE) to enable triggered conditional execution for your site. Once enabled, you can activate it per campaign action in the Campaign Builder.

Note: The above steps are only required once.

Step 4: Optimove Notifies the Webhook(s) that the User is Eligible for a Campaign

When a user completes the required trigger events and is eligible for a triggered campaign, Optimove sends a notification to the registered webhook(s) with details about the campaign and user.

Notification Payload:

{
  "timestamp": "long", // Epoch UNIX milliseconds when Optimove sent the request
  "conditional_execution_approval_deadline": "long", // Deadline for approvals
  "request_uid": "string", // Unique Identifier for this request
  "is_hashed": "boolean", // Is the user ID hashed
  "user": {
    "user_id": "string", // Customer ID or Visitor ID
    "is_visitor": "boolean",
    "personalization": {
      "attribute_key1": "attribute_value1",
      "attribute_key2": "attribute_value2"
    }
  },
  "occurrence": {
    "date": "ISO Date: yyyy-MM-dd",
    "series_id": "string",
    "occurrence_id": "string",
    "notes": "string",
    "tags": ["string"],
    "communication_type": "triggered",
    "action": {
      "id": "number",
      "name": "string",
      "is_control": "boolean",
      "promotions": [
        {
          "name": "string",
          "code": "string"
        }
      ],
      "channels": [
        {
          "id": "number",
          "name": "string",
          "brand_id": "string",
          "template": {
            "id": "number",
            "name": "string"
          }
        }
      ]
    }
  },
  "trigger_context": {
    "id": "number",
    "name": "string",
    "events": [
      {
        "key": "string",
        "timestamp": "long",
        "parameters": [
          "param_key1": "param_value1",
          "param_key2": "param_value2"
        ]
      }
    ]
  }
}

 

Step 5: Internal Systems Review if the User Should Receive the Campaign

Perform internal checks or use a third-party vendor to verify if the user should receive the campaign based on your criteria.

Step 6: Notify Optimove if the User Should Receive the Campaign

Before the defined timeout, send Optimove a response indicating whether the user should receive the campaign using the SendWebhookApproval API call.

Approval API Call:

• SendWebhookApproval
  • Headers:
    • optimove-tenant-id
    • optimove-notification-type = conditional_execution_approval
    • optimove-signature-version = 1
    • optimove-signature-content = HMAC(requestBody, shared_secret, 'sha1')
  • Payload:
    JSON

    {
      "timestamp": "long", // Epoch UNIX milliseconds of when the request was sent
      "request_uid": "string", // The Request ID from Optimove
      "approved": "boolean", // True: user should receive the campaign; False: user should not
      "additional_data": {} // Optional. Additional data, not used by Optimove
    }
    

Step 7: Optimove Sends the Campaign to the User

If the user is approved before the timeout, Optimove sends the campaign. If the campaign has a delayed execution, the delay starts from the moment of approval. The “Campaign Triggered” notification (Event Type 11) is sent at this point.

Note: Campaigns with triggered conditional execution cannot be sent using the web page pop-up channel.