Marketers use Optimove to manage and automate the execution of highly-targeted customer marketing campaigns via channels such as email, SMS, push notifications, ad networks and in-app/on-site messaging systems.
You are probably reading this either because we have a mutual client who is interested in using Optimove to automatically send customer campaigns via your marketing platform, or you wish to integrate an external service with Optimove and act as the middleware. Integrating your service with Optimove to make this a reality is the topic of this document. (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 servers for the purposes of enabling Optimove to automatically execute customer campaigns via your platform. Detailed documentation of the Optimove API is available here: Optimove API Usage Guide.
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 Run Campaign wizard 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 API call. Because this data is included in Optimove’s campaign analysis reports, it is important to call UpdateCampaignMetrics several times a day for seven days following the execution of each campaign.
Note that there are five specific metrics that may be reported using the UpdateCampaignMetrics API call, as seen in this sample extract from a campaign analysis report:
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.
- 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.
- 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.