Send query results to MoEngage Cohorts

MoEngage is a cross-channel customer engagement platform built for marketers and product owners who value agility over complexity. Use real-time insights and personalized cross-channel communications and adapt to evolving customer expectations.

Note

This destination uses the MoEngage Cohort Sync API . Each segment it creates is a custom segment in MoEngage.

Beta

The MoEngage Cohorts connector is in beta. Contact your Amperity representative to learn more.

Caution

MoEngage archives a segment after 60 days without an update, and an archived segment that was created by Cohort Sync cannot be restored. A run in which nobody joined or left the audience sends nothing to MoEngage. An audience that does not change for 60 days therefore loses its segment in MoEngage.

To start again, change the list name to a name that has not been used in the workspace. The next run creates a new segment and sends the whole audience to it.

Important

MoEngage assigns every segment that Cohort Sync creates to the Default Team. When your workspace uses Teams, people on other teams might not see the segment.

The steps that are required to send audiences to MoEngage from Amperity.

Caution

This destination is available for sending query results to MoEngage after it is configured by a Datagrid Operator or your Amperity representative.

If this destination cannot be selected for orchestrations ask your Datagrid Operator or Amperity representative to configure a destination for sending query results to MoEngage.

Build query

Build a query that returns a customer_id field. Amperity sends only the customer_id field, and MoEngage adds a person to the segment only when it already has a user with that customer ID.

The following example returns customer IDs from the Customer 360 table. Replace app_user_id with the field in your tenant that holds the ID your app or website uses for each user in MoEngage:

SELECT
  app_user_id AS customer_id
FROM Customer_360
WHERE app_user_id IS NOT NULL

Each run removes the people who left the query results since the last run, and then adds the people who joined.

The customer ID is the unique ID that MoEngage identifies a user by. It is usually the ID that your app or website passes to the MoEngage SDK when a user logs in, which is not necessarily the Amperity ID. Confirm which field in Amperity holds the same value before you send, and alias that field as customer_id in the query, for example SELECT loyalty_id AS customer_id.

Amperity sends each customer ID as text, after removing leading and trailing whitespace, and MoEngage matches it exactly. When the field holds a floating-point number, such as a DOUBLE, or a DECIMAL with digits after the decimal point, convert it in the query, for example CAST(CAST(loyalty_id AS BIGINT) AS VARCHAR) AS customer_id. Otherwise the ID 12345 is sent as 12345.0 or 12345.00 and does not match the user in MoEngage.

Return one row for each customer ID. Amperity does not send these rows:

  • A row whose customer ID is null or empty. Amperity skips the row without an error, and counts it with the rows sent from cache.

  • A row whose customer ID repeats another row’s customer ID. Amperity keeps one of the rows and skips the others without an error. Which row it keeps is not determined.

  • A row whose customer ID MoEngage does not accept. This is a customer ID that contains only whitespace, is one character long, or is a placeholder value such as unknown, guest, null, none, n/a, 0, or -1. These values are compared without regard to case. MoEngage lists the values it does not accept in its Data API overview . Amperity reports the row as failed instead of sending it.

Add orchestration

An orchestration defines the relationship between query results and a destination, including the destination and the frequency at which an orchestration runs.

  1. Open the Activations page, select the Orchestrations tab, and then click the Add orchestration button. This opens the Add orchestration dialog box.

  2. From the Object type dropdown, select Query.

  3. From the Object dropdown, select the query for which results is sent to MoEngage.

  4. From the Destination dropdown, select a destination that is configured for sending data to MoEngage.

  5. Verify all settings.

  6. Set the workflow to Manual. You can change this to automatic later, after verifying the end-to-end workflow.

  7. Click Save.

When you add the orchestration, enter a List name. This is the name of the custom segment in MoEngage.

The name of the custom segment in MoEngage. Amperity uses the list name as both the name and the ID of the segment. MoEngage creates the segment the first time Amperity sends to this list name, and Amperity updates that same segment on later runs.

The list name cannot start with a period, contain any of the characters | * ? \ : < > = $ ", be longer than 200 characters, or be All Users. MoEngage can reject a segment name like this without returning an error, so Amperity does not accept it as a list name.

In a campaign, the list name can include the campaign and treatment names, which Amperity fills in when it sends. The same rules apply to the campaign and treatment names, because they become part of the segment name. Amperity checks the list name again after it fills in those names, and a list name that breaks the rules, such as one from a campaign named Q4: VIP, stops the run before anything is sent. Rename the campaign or treatment, or change the list name.

Important

Use a separate list name for each audience that you send to MoEngage. MoEngage never reuses a segment name, even after the segment is archived, so choose a list name that has not been used in the workspace before.

Changing the list name sends the whole audience to a new, empty segment on the next run. Amperity does not rename, update, or delete the segment with the previous name, which stays in MoEngage and is no longer updated.

Run orchestration

Run the orchestration manually to validate that it works.

  1. Open the Activations page, select the Orchestrations tab, and then open the menu for the MoEngage orchestration. Select Run.

  2. The Status column for the orchestration updates to say “Waiting to start”, after which the notifications pane updates to include a notification that shows the current status.

  3. When the orchestration has run successfully, the status is updated to “Completed”.