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
Managing Third Party Subscriptions in Optimove
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.
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.
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
- 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.
- 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.
- 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.
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: By default, any attribute defined as a personalization tag, as well as all the event and parameter values related to the trigger, will be sent as part of the payload for personalization purposes. To exclude one or more of the personalization tags and parameter values for a certain channel, please contact your CSM.
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
- This integration flow supports Optimove clients who have Optimove's Track and Trigger add-on product.
- 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.
- 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.
Managing Third Party Subscriptions in Optimove
Optimove supports three ways third party platforms can share customer opt-in statuses.
Real-time API calls
You can use two real-time APIs calls to share your customer subscription data with Optimove.
As a first step, you will need to call the AddCustomerAttribute API to create the attributes as you would like to see them in your Optimove instance (e.g., Mobile Push Opt-in).
The second step is to populate that attributes for all customers, using the UpdateCustomerAttributes API (note there is a limit of 10,000 customers per call).
Important note: In order to use this option, you will need to have an API user with client permissions for your Optimove instance.
Designated API call for a specific channel
You can upload a list of customers and their opt-in status using the SetCustomerChannelPreference API (note there is a limit of 50,000 customers per call).
This API will populate a table in Optimove’s backend which will then be used to create an opt-in status attribute.
When using this setup you will need to work with your CSM to have the new attribute created for you.
Batch process sent to Optimove
You can share this data as part of your batch process, either as an opt-in column within your "customers" table or as a separate standalone file of subscription users.