Overview

Marketers use Optimove to manage and automate the execution of highly-targeted customer marketing Scheduled and Realtime campaigns via channels such as email, SMS, push notifications, ad networks, and in-app/on-site messaging systems. You are probably reading this because we have a mutual client interested in using Optimove to send customer campaigns via your marketing platform automatically, or you wish to integrate an external service with Optimove and act as the middleware.

This document will walk you through the steps necessary to integrate with Optimove.

Throughout this document, the service being integrated with Optimove is referred to as “your service” even though it is understood that you might be integrating a service operated by a third party. Optimove exposes a rich Web services API that provides all the functionality you need to easily exchange data with Optimove’s backend for the purposes of enabling Optimove to execute customer campaigns via your platform automatically.

Detailed documentation of the Optimove API is available here: Optimove API Usage Guide.

 

Jump to:

Scheduled Campaigns Integration Flow

Triggered Campaigns Integration Flow

Scheduled Campaigns Integration Flow

How the Integration Process Works

This diagram presents an overview of how information flows between Optimove and your service:

 

 

These depicted flows are detailed in the following sections.

Flow 1: Register a Listener to Receive Notifications of Campaigns to be Executed

Whenever Optimove completes processing a campaign for execution by your system, Optimove will notify your system that there is a campaign waiting to be executed. For this purpose, you will need to deploy a “listener” and register it with the Optimove REST API.

Register the URL of your service using the RegisterEventListener API call.

This only needs to be done once, unless you wish to change the address of your service endpoint and/or register additional routes for other execution channels.

Once your listener is registered, Optimove will notify it any time a new campaign is ready, by sending an HTTP request with a payload containing the campaign ID and the event type.

Flow 2: Synchronize the List of Available Templates

In order for the templates available in your system to be selectable by marketers when scheduling campaigns within the Optimove UI, the list of available templates must be synchronized between your service and Optimove via API. In other words, your service will provide the Optimove API with the key-value pairs that point to the content in your system (for example, the HTML template for emails or the text content of SMS messages).

The API calls used to manage the templates available for use within Optimove are:

  • AddChannelTemplates – Provides Optimove with the names and IDs of templates that will be available for selection by marketers when scheduling a campaign to be executed by your service
  • DeleteChannelTemplates – Removes previously-added templates
  • GetChannelTemplates – Retrieves an array of all defined template IDs and associated names

Once templates are added to Optimove, marketers can select them in Optimove’s Campaign Builder when setting up a campaign that will be executed via your service:

Important note: Your system should call the appropriate API function(s) every time that a new template is added, a template is deleted or a template’s name has been changed. This will ensure that the list available to marketers within Optimove is always accurate and up to date.

Flow 3: Notify Listener that a New Campaign is Ready

As soon as Optimove has completed preparing each new campaign, it will notify your registered listener and provide the campaign’s ID.

Flow 4: Retrieve Campaign Execution Details

When your listener receives notification of a new campaign, your system needs to retrieve the details for the campaign ID that was received by the listener. These details include the list of customer IDs to receive the campaign, the template ID(s) to use, the scheduled time(s) and any personalization tag data.

This is accomplished by calling using the GetCustomerSendDetailsByChannel API call. This call requires the designated channel ID that Optimove provided you, and the campaign ID received by your listener.

Note: Optimove returns all campaign times in UTC (the GMT time zone). You may need to adjust the actual campaign send times based on your locale.

Flow 5: Execute the Campaign

This step occurs within your system and does not involve Optimove. Your system should execute each campaign according to the campaign details received by your system from Optimove.

Flow 6: Update Response Metrics

Following the execution of a campaign, your system should push campaign delivery and response metrics to Optimove using the UpdateCampaignMetrics and UpdateCampaignInteractions API calls.

In order to ensure this data is displayed properly within the Optimove’s campaign analysis and customer explorer reports, it is important to call UpdateCampaignMetrics and UpdateCampaignInteractions several times a day for seven days following the execution of each campaign.

Important Notes about the Integration Process

  1. Client credentials – The code you develop to interface with Optimove via the API must utilize a different set of credentials for each individual client. Optimove or the client can provide you with these credentials. These credentials are required by the Login API call, which must be called prior to making any other API calls.
  2. Push notification apps – If your service generates push notifications, your system can differentiate between apps by adding app IDs and associated app names that will appear in the Optimove UI for selection by marketers. You can maintain the list of available apps using the AddChannelApps and DeleteChannelApps API calls.
  3. Personalization tags – Your system may retrieve additional attributes that can be used to personalize the content of each individual customer’s communications (e.g., first name, account balance). In order to implement this capability, you and the client should agree on the attributes to be supported and then provide a list of the attribute names to the Optimove integration team. Once implemented, your system will be able to retrieve the attribute values for each customer in a campaign using the CustomerAttribtues parameter of the GetCustomerSendDetailsByChannel API call.
  4. Response paging – To ensure that your system receives all customer IDs for large campaigns, you should implement the API’s paging mechanism when retrieving campaign details. For details, refer to Response Paging for Customer-related Functions.

FAQs

  • If my system requires a different matching attribute, such as email or phone number, can we receive it from the Optimove API?
    In our experience, the client usually provides this information directly to you. In some cases, the client decides to store this information within Optimove, in which case your system can retrieve it as a CustomerAttribute (see Personalization tags, above).
  • Can GetCustomerSendDetailsByChannel sometimes return different template IDs and/or send times for different customer IDs?
    Yes. Because marketers can define multiple template conditions, different template IDs and/or send times may be associated with different customers within a single campaign.
  • Is it possible to register different listeners for different execution channels?
    Yes. If, for example, your service handles both SMS and email, you can register a separate listener for each channel and they will not interfere with each other.

Triggered Campaigns Integration Flow

Within Optimove, a realtime triggered campaign is executed when a customer meets the defined Trigger criteria. The Trigger criteria are made up of one or more realtime events.
Example: The Trigger for a campaign is defined as visiting a specific webpage 3 times (3 webpage visit events). When a customer visits the webpage above 3 times, the Trigger criteria will have been met and a campaign should be executed.

How the Integration Process Works

This diagram presents an overview of how information flows between Optimove and your service, for the purpose of sending realtime triggered campaigns:

These depicted flows are detailed in the following sections.

Flow 1: Register a Listener to Receive Notifications When Customers Meet the Trigger Criteria

Whenever Optimove detects that a customer met the Trigger criteria, Optimove will notify your system so that you can execute a campaign. For this purpose, you will need to deploy a “listener” and register it with the Optimove REST API.

Register the URL of your service using the RegisterEventListener API call with EventTypeID = 11 to a dedicated channel ID. This only needs to be done once, unless you wish to change the address of your service endpoint and/or register additional routes for other execution channels.

Once your listener is registered, Optimove will notify it any time a customer meets the Trigger criteria, by sending an HTTP request with a payload containing the campaign and customer details.

Flow 2: Synchronize the List of Available Templates

In order for the templates available in your system to be selectable by marketers when creating campaigns within the Optimove UI, the list of available templates must be synchronized between your service and Optimove via API. In other words, your service will provide the Optimove API with the key-value pairs that point to the content in your system (for example, the HTML template for emails or the text content of SMS messages).

The API calls used to manage the templates available for use within Optimove are:

  • AddChannelTemplates – Provides Optimove with the names and IDs of templates that will be available for selection by marketers when scheduling a campaign to be executed by your service
  • DeleteChannelTemplates – Removes previously-added templates
  • GetChannelTemplates – Retrieves an array of all defined template IDs and associated names

Once templates are added to Optimove, marketers can select them in Optimove’s Campaign Builder when setting up a campaign that will be executed via your service.

Important note: Your system should call the appropriate API function(s) every time that a new template is added, a template is deleted or a template’s name has been changed. This will ensure that the list available to marketers within Optimove is always accurate and up to date.

Flow 3: Notify Listener that a Customer has Met the Trigger Criteria

As soon as Optimove has detected that 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 realtime is described in RegisterEventListener under "EventTypeID = 11".

The payload contains the trigger name and, among other information, the customer, campaign, action, channel, and template IDs. Including the relevant Personalization keys and values.

Important note: Any attribute defined as a personalization tag will be sent as part of the payload.

Flow 4: Execute the campaign

This step occurs within your system and does not involve Optimove. Your system should execute each campaign immediately upon receiving the campaign details from your system from Optimove.

Important Notes about the Integration Process

  1. This integration flow supports Optimove clients who have Optimove's Track and Trigger add-on product.
  2. Client credentials – The code you develop to interface with Optimove via the API must utilize a different set of credentials for each individual client. Optimove or the client can provide you with these credentials. These credentials are required by the Login API call, which must be called prior to making any other API calls.
  3. Please contact the Product Integration Team to provide you with the exact Channel ID you should register the realtime listener (RegisterEventListener), and synchronize your templates to (AddChannelTemplates #2 above).

FAQs

  • Is it possible to register different listeners for different execution channels?
    Yes. If, for example, your service handles both SMS and email, you can register a separate listener for each channel and they will not interfere with each other.
  • If my system requires a different matching attribute, such as email or phone number, can we receive it from event type 11?
    Typically, the client provides this information directly to you. Some clients decide to store this information within Optimove, in which case, if the customer has configured this information as a personalization tag, your system can retrieve it from the "personalization" object within event type 11.