Introduction

Outbound Segment Sync allows you to sync and send valuable customer segments created in MoEngage to any other platform in your tech stack. You can sync these segments across various platforms, including ad networks, loyalty platforms, recommendation engines, and experimentation tools. This helps drive various business use cases, including targeted engagement and data-driven decision-making.

Use Cases

Brands can use Outbound Segment Sync to sync impactful segments across tools, enabling targeted engagement and other business strategies.

• 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 receives 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 personalized support by syncing segments so your customer service teams can better understand and assist individual customers.
• Sync segments from one MoEngage App to another: Using Outbound Segment Sync with the Cohort Sync API makes it easy to sync your segments across multiple MoEngage apps. For more information, refer Sync Segments from One MoEngage App to Another.

Integration

Option 1: Use 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. For more information, refer to the Storyly partner help document for more information on these integrations.

Option 2: Configure a Custom Destination Using an API Endpoint

To set up a destination by using API endpoints, navigate to the App Marketplace and select the Custom Destinations section. Add a custom destination and configure it by following the steps below.

Step 1: Create a Connected App

To create a connected app:

1. On the left navigation menu in the MoEngage dashboard, click App marketplace.
2. On the App marketplace page, click + Create app.
3. In the Create app dialog box, enter the following details:

   Field	Description
   App name	Type the app name.
   App type	Click Outbound Segment Sync (Export MoEngage segments to your app).

4. Click Create. This adds your connected app as a destination in MoEngage. You will be directed to the connected app page.
   

Step 2: Add an Integration

After creating the app, you must configure the integration details to inform MoEngage where and how to send the segment data.

1. On the connected app page in App marketplace, click the Integrate tab, and then click + Add integration.
2. In the Connection details section, enter the following details to sync segments to your endpoint:

   Field	Description
   Integration Name	Enter an integration name to identify your endpoint.
   URL Endpoint	Enter a URL endpoint to sync the data. Example: https://api.example.com/segments If your system requires IP whitelisting, refer here.
   Key-Value Pairs	[Optional] Enter a list of key-value pairs that can be added to the headers and parameters as per your requirement.
   Authentication	Supported options are Basic auth and No auth.
   User Identifier	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.
   Request Body	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. Note: Both add_users and remove_users fields are not mandatory in one request. Only one of these or both can exist in the request payload, or they can be an empty array as well. You cannot remove these keys. However, they can be renamed as per your destination. [Optional] You can add a list of Key-Value pairs to the list of add and remove users as per your requirement.
   Throttle	MoEngage will send 25000 requests per minute. Each request can have between 100 and 10000 users simultaneously, which you can set in the throttle.
   Allow resync	Allow resync of all users in the segment to the destination: In the event of an issue with a particular sync, your destination may contain incorrect users in the segment. To maintain the accurate state of the users in a segment, you can resync all users in the segment. Choosing to allow resync of all users will enable the action on each synced segment. However, ensure that the destination is able to drop all users in the segment and allow the resync of the entire segment once again.
   Request Preview	When you edit the destination configuration, you can view the updated request body that will be sent by MoEngage.

   
   Test your connection by sending a sample user value to the configured destination. You can also view the response - either successful or failed with the message received from the destination.

   info	Information You can add multiple integrations by clicking + Add integration.

API Request Format

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

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 Payload

1. moengage_sync_id: A unique ID given to the sync started for a particular segment, which will differentiate it from other synced segments.
2. moengage_sync_name: The name of the segment that is being synced.
3. moengage_execution_id: A unique ID 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: 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: A unique ID that the customer/partner sends through their system to MoEngage so that they can identify the user according to their conventions.

Structure for Key-Value Pairs

The payload should contain the structure when a key-value pair is added:

cURL

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

Step 3: Set Up a Segment Sync

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

To set up a new synced segment:

1. Choose a custom segment to sync

In the Segment > All segments page, select a Custom Segment and click Sync Segment in the action drop-down list.

2. Choose the destination

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

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. Contact 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 one of the following 5 statuses:

Sync Segments from One MoEngage App to Another

Using Outbound Segment Sync and our Cohort Sync API, you can sync segments from one MoEngage app to another. This helps cross-regional teams to function synchronously and have better targeting.

Step 1: Log in to Your Source App

To get started, log in to the app you want to send segments from (source). Ensure that Outbound Segment Sync is already enabled in this app.

Step 2: Create a New Custom Destination

To set up a new custom destination, go to the App Marketplace and navigate to the Custom Destinations section. Add a new custom destination called "MoEngage".

Step 3: Create a New Endpoint

In the newly created Custom Destination, click + Add integration to configure a new endpoint. Give your endpoint a name like your destination app name. Follow the other fields as described: 

Once the above fields are configured, you can test the connection. If all your details are correct, then the test should be successful. Save the integration.

Step 4: Sync a Segment to Your Destination App

Follow the details above to sync your segments to your destination app.

View Details of an Outbound Synced Segment

Clicking 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