Integrate your Service with Optimove

Overview

Integrate with Optimove to automate customer marketing campaigns through various channels like email, SMS, push notifications, ad networks, and in-app/on-site messaging systems. This document provides instructions for integrating with Optimove, referring to your service as the integration partner. Optimove offers a comprehensive Web services API for seamless data exchange with Optimove's backend, enabling automated campaign execution via your platform.

In this article we will cover the following topics

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

Optimove notifies your system when a campaign is ready to be executed. To enable this, deploy a listener and register it with Optimove's REST API using the RegisterEventListener call. Once registered, Optimove will send an HTTP request with the campaign ID and event type whenever a new campaign is ready.

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

Sync your available templates with Optimove's UI by providing the key-value pairs via API. These pairs should reference the content in your system, such as HTML templates for emails or text content for 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

Retrieve campaign details for the received campaign ID by calling the GetCustomerSendDetailsByChannel API. Provide the designated channel ID from Optimove and the campaign ID received by your listener. For large campaigns, implement the API's paging mechanism to receive all customer IDs. Adjust campaign send times to your locale if needed, as Optimove returns them in UTC (GMT).

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

Push campaign delivery and response metrics to Optimove using the UpdateCampaignMetrics and UpdateCampaignInteractions API calls after executing a campaign. To ensure accurate display in Optimove's reports, make these calls multiple times a day for seven days after campaign execution.

Important Notes about the Integration Process

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.
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.

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 real-time triggered campaign is executed when a customer meets the defined Trigger criteria. The Trigger criteria are made up of one or more real-time 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 real-time 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 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 real-time 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 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 Optimove.

Important Notes about the Integration Process

This integration flow supports Optimove clients who have Optimove's Track and Trigger add-on products.
Client credentials – The code you develop to interface with Optimove via the API must utilize a different set of credentials for each individual client.
Please contact the Product Integration Team to provide the exact Channel ID you should register the real-time 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.