Introduction

Outbound Segment Sync allows you to sync and send with ease valuable customer segments created on MoEngage to any other platform in your tech stack.

You can sync these segments across various platforms, including Ad networks, Loyalty platforms, Recommendation engines, Experimentation tools, and more, to drive various business use cases such as driving targeted engagement, making more data-driven decisions, etc.

Use cases

Brands can leverage Outbound Segment Sync to sync impactful segments across tools, enabling targeted engagement, data-driven decisions, and other business use cases. Here are some examples:

Sync segments to a Data Warehouse

Gain deeper insights and enhance data-driven decision-making by seamlessly syncing segments to your Data Warehouse for in-depth analysis.

Sync segments to a Loyalty platform

Enhance customer loyalty programs by syncing segments, enabling personalized rewards and promotions tailored to individual preferences.

Sync segments to an In-App Personalization platform

Create highly personalized user experiences by syncing segments, ensuring that each user gets content and features that match their preferences.

Sync segments to an Ad network

For precision-targeted advertising campaigns, sync your segments, ensuring your ads reach the most relevant audiences.

Sync customer segments to an Experimentation platform

Conduct A/B/n tests with precision by syncing segments to compare different customer groups' responses and behaviors.

Sync segments to a CRM platform

Improve customer interaction tracking by syncing segments, providing better insights into customer behaviors and preferences.

Sync segments to a Customer Service platform

Provide top-notch personalized support by syncing segments, so your customer service teams can better understand and assist individual customers.

Syncing segments using this feature is quick and straightforward. Just choose your destination platform, select desired user segments, set the sync frequency, and start syncing.

To begin, you first need to set up and connect with the destination platform. There are two ways to do that. Learn more about these in the next section.

Connect Destinations

There are two ways of setting up, and connecting with the destination platform:
1. Using partner integrations
2. Configure custom destination using an API endpoint

Before we deep dive into these two methods, you must request access to enable Custom Destinations. To do so you can navigate to:
App Marketplace -> Click on Explore -> Select Integrate tab -> Request Access

Once enabled, you can get started with any of the two methods below.

Using partner integrations

MoEngage provides preexisting partner integrations that simplify the configuration process and API endpoint testing. With just a few clicks, you can start syncing segments to partner platforms. Check out the partner help docs for more information on these integrations.

Storyly 

Configure custom destination using an API endpoint

To set up a destination using API endpoints, go to the App Marketplace and navigate to the Custom Destinations section. Add a custom destination and configure it.

Setting up a Custom Destination to sync segments to your endpoint

1. Provide an integration name to identify your endpoint.
2. Provide a URL Endpoint to sync the data. Example:  https://api.example.com/segments
3. Provide a list of key-value pairs that can be added to the headers and parameters as per your requirement. This is optional.
4. Authentication - Basic auth and No auth are supported.
5. Choose the user identifier you want to sync from the MoEngage user segment to your endpoint. This should be a key that uniquely identifies a user at your destination. You can rename this key as per the user identifier at your destination. 
6. Request Body:
   1. • add_users - This list contains the users to be added to a particular segment.
      • remove_users - This is the list that contains the users to be removed from a particular segment.
      • Both add_users & remove_users fields are not mandatory in one request: Only one of these can come in the request payload, or both of them can come in the request payload or they can be an empty array as well.
      • These keys cannot be removed. However, they can be renamed as per your destination.
        
      • [Optional] List of Key-Value pairs can be added to the list of add and remove users as per your requirement.
7. Choose the throttle:
   
   • MoEngage will send 25000 requests per minute.
   • Each request can have between 100 to 10000 users simultaneously that can be set in the throttle.
8. Allow resync of all users in the segment to the destination: 
   • In case of any issue with a particular sync, your destination might hold incorrect users in the segment. To maintain the accurate state of the users in a segment, you have the option of resyncing all users in the segment.
   • Choosing to allow resync all users will enable the action on each synced segment. However, do ensure that the destination should be able to drop all users in the segment and allow the resync of the entire segment once again.
9. Request Preview - When you edit the destination configuration, you can view the updated request body that will be sent by MoEngage.
10. Test your connection by sending a sample user value to the configured destination. You will also be able to see the response - either successful or failed along with the message received from the destination.

API Request Format

When MoEngage sends a segment to your API endpoint, the request format will be as below: 

Request Body:

{
  "type": "segment_sync",
  "pagination": {
    "total_pages": 14,
    "page_count": 12
  },
  "data": {
    "moengage_sync_id": "{{sync_id}}",
    "moengage_sync_name": "{{sync_name}}",
    "moengage_execution_id": "{{execution_id}}",
    "moengage_integration_id": "{{integration_id}}",
    "add_users": [
      {
        "moengage_distinct_id": <moengage_user_id>,
        "partner_user_id": "{{uid99}}"
      },
      {
        "moengage_distinct_id": <moengage_user_id>,
        "partner_user_id": "{{uid00}}"
      }
    ],
    "remove_users": [
      {
        "moengage_distinct_id": <moengage_user_id>,
        "partner_user_id": "{{uid98}}"
      },
      {
        "moengage_distinct_id": <moengage_user_id>,
        "partner_user_id": "{{uid01}}"
      }
    ]
  }
}

.

Definition of IDs in the above payload

1. “moengage_sync_id": It is a unique ID given to the sync started for a particular segment, which will differentiate it from other synced segments
2. “moengage_sync_name”: It is the name of the segment that is being synced
3. “moengage_execution_id": A unique ID will be assigned to the sync execution to differentiate that sync from multiple syncs which is possible for a particular segment
4. “moengage_integration_id": This ID is generated when a segment is mapped to a particular integration destination. Thus, the mapping of the segment with the integration destination denotes the moengage_integration_id
5. “moengage_distinct_id”: It is a unique ID assigned to a user by the MoEngage system. This is different from the ID that the customer/partner has assigned to the user
6. “partner_user_id": This is a unique ID that the customer/partner sends through their system to MoEngage so that they can identify the user as per their conventions

Structure for Key-Value pair

Payload should contain the structure when a key Value pair is added.

curl --location --request POST
''
-H 'Content-Type: application/json'
--data-raw '{
"type": "segment_sync",
"pagination": {
"total_pages": 1,
"page_count": 1
},
"data": {
"moengage_sync_id": "sync_id",
"moengage_sync_name": "sync_name",
"moengage_execution_id": "execution_id",
"moengage_integration_id": "integration_id",
"add_users": [
{
"moengage_distinct_id": "moengage_user_id",
"key_format_1": "value_format_1",
"key_format_2": "value_format_2",
"user_attribute": ""
}
],
"remove_users": [
{
"moengage_distinct_id": "moengage_user_id",
"key_format_1": "value_format_1",
"key_format_2": "value_format_2",
"user_attribute": "uid99"
}
]
}
}'

Error Descriptions

Setting up a segment sync

Now that you have already configured your destination platform, you can get started setting up a segment sync.

To set up a new synced segment:

Step 1: Choose a custom segment to sync

In the Segment -> All segments page, select a Custom Segment and click on the action Sync Segment in the action dropdown. 

Step 2: Choose the destination

The destinations configured in Custom Destinations in App Marketplace will be available in the dropdown. Choose the destination from the available options or add a new destination for sync.

Step 3: Choose a schedule of sync and set up notification preferences

The sync can be either a one-time transfer of the users in a segment to the destination or a continuous periodic update of the latest status of the segment.

If periodic, segments can be synced daily, weekly, and monthly. Hourly syncs can be enabled on a case-by-case basis. Please connect with your account manager to enable hourly syncs for your account. 

You can also set up email ids to receive notifications of the following:

• Any update in the sync configuration
• Successful execution of sync
• Failure of sync

Periodic Outbound Segment Sync

In periodic outbound segment sync, MoEngage will send the entire users in the segment only in the first sync. For the subsequent syncs, MoEngage follows the change data capture process, where we compare the previous sync to the current status of the segment and send only the difference in the users.

This difference is sent in two lists - add_users (which contains the list of users to be added to the segment) and remove_users (which contains the list of users to be removed from the segment). This difference is also maintained by MoEngage for the action Resync Last Difference, which syncs only the last difference to the destination. This option is provided to address any data discrepancy at the destination.

View All Outbound Synced Segments

You can view the list of synced segments in the All Segments → Synced Segments tab. Sync details such as the segment name, latest sync status, destination, schedule, last sync timestamp, and the actions that can be performed on the sync are available on this page.

Actions on Outbound Synced Segments

Sync Status

Each synced segment can be in either one of the following 5 statuses:

View Details of an Outbound Synced Segment

Clicking on the synced segment name or View action, you will be redirected to the details page of that synced segment.

Sync details such as destination, schedule, latest sync status, sync updated by, updated time, sync schedule, last synced time, next sync time, and a link to the parent custom segment will be available on the detail page.

Sync configurations such as the synced user attribute, sync schedule, and notification preferences are also available on the detail page. 

You can perform all actions associated with a sync from this page - Edit, Run Adhoc Sync, Pause sync, Resync All Users, Resync Last Difference, and Archive sync.

On the details page of a synced segment, you can also view the Sync history of all the sync executions performed for this segment.

Sync History

The sync history shows the details of each time the segment has been synced to the destination at the scheduled frequency.

• Run time - The time at which the sync was executed
• Status of execution - Each sync execution can be in one of the following statuses -
  •  Complete - The sync ran successfully, and all rows have been sent to the required destination
  •  Processing - The sync is currently running to the required destination
  •  Failed - There was a failure in the execution of the sync.
• No. of users added - Count of users with <synced user attribute> added to the custom segment since the last time the sync was processed. This list of users is synced to the destination under 'add_users' in the Request Body.
• No. of users removed - Count of users with <synced user attribute> removed from the custom segment since the last time the sync was processed. This list of users is synced to the destination under 'remove_users' in the Request Body.
• Total no. of users - This is the number of users with <synced user attribute> present in the parent custom segment.

FAQs

1. Can we remove the 30-minute cool-off period?
    - No, the 30-minute cool-off period cannot be removed. To avoid any interruption to the ongoing sync and avoid chances of incorrect data sync, as a precautionary measure, the cool-off period is set by default.
   
   
2. What does 'API already failed' mean?
    - This error will be shown if the API call is failed but still, a reattempt is made to make the API call. Some possible reasons for the “API already failed” error are:
   • Network connectivity issues: The API call could have failed because there was an issue with network connectivity, such as a weak signal or a server that is down.
   • Lack of authorization or authentication: The API call requires some form of authorization or authentication from the client side, and this could have been missing or invalidated, leading to the API failing.
   • Server Overloading: Too many requests are being handled by the server, causing the server to become overloaded and unable to handle further requests, which could result in an API failure.

3. Can I change the Sync name to a name of my choice?
    - No, currently there is no provision to edit/change the Sync name

4. What happens if the Segment name is edited midway, would the name get updated in the API call? and what if another segment of the same name is created? will both the API calls have the same sync name?
    - It is not recommended to perform any kind of action on the segment while sync is going on. It might lead to an interruption in the sync. Meanwhile, any changes made to the segment midway through the sync, the change will not reflect immediately. It will reflect after the cool-off period of 30 minutes. Please be careful while Editing, Renaming, and Archiving a segment in case one or more syncs exist for the same. When the parent custom segment is renamed, the sync name does not reflect the new name of its parent custom segment.

5. Can I pass more than 1 attribute in Segment sync?
    - No, as per the current MoEngage system, it is not possible to pass more than one attribute in a Segment sync.

6. Can I personalize the KV pair or have a dynamic timestamp?
    - Customers can personalize the KV (Key-Value) pair to their specific needs. However, please note that at this time dynamic Key Value is not supported, e.g. dynamic timestamp is not supported. Key value pairs need to be static.

7. What is the retrial mechanism and what is the timeout period?
    - The retrial mechanism allows the customer/partner’s system to call MoEngage APIs in multiple attempts. However, there is a limit assigned to the retrial mechanism. In total 3 retry attempts can be made with the maximum frequency/timeout being 1 retry/3 seconds.