Introduction

Outbound Segment Sync allows you to send user segments created and used in MoEngage to any destination at a schedule.

With this feature, you can configure your API endpoint, choose the segments you want to sync, define the sync schedule, and see the users in the segment sync to your destination. You can then utilize the segments to enrich your data warehouses, recommendation systems, and so on. 

Custom Destinations

User segments can be synced to multiple destinations. These destinations can be set up in the App Marketplace -> Custom Destinations section. 

Custom Destinations enables you to connect any endpoint to MoEngage. To enable it for your account, raise a request for Custom Destinations in App Marketplace, as shown in the screenshot below. Once enabled, provide your destination name and add an integration to get started. 

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.
      • 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:
   1. • 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:
   1. • 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}}"
      }
    ]
  }
}

Setting up a segment sync

To enable Outbound Segment Sync for your account, raise a request in the All Segments -> Synced Segments tab, as shown in the screenshot below. Once enabled, you will be able to add a custom destination as detailed above. 

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:

1. 1. • 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, destination, schedule, last sync timestamp, latest sync status, 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.