Configure destinations for 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.

The MoEngage Cohorts connector sends audiences from Amperity to custom segments in a MoEngage workspace, and keeps each segment in step with its audience. Your MoEngage team targets the segment from MoEngage campaigns and flows. This is not the MoEngage destination, which sends CSV files to an Amazon S3 bucket, or the MoEngage Attributes destination, which sends customer attributes to MoEngage user profiles.

Amperity sends one field to MoEngage: customer_id, the MoEngage customer ID of each person in the audience. MoEngage adds a person to the segment only when it already has a user with that customer ID. This destination does not create users in MoEngage, so a person who has no MoEngage user is not added to the segment, and MoEngage does not report the person as missing.

Each run sends what changed since the last successful run. Amperity removes the people who left the audience, and then adds the people who joined it. Unchanged rows are not sent again, and are reported as sent from cache. The first run sends the whole audience. MoEngage creates the segment the first time Amperity sends to it, with the list name as its name and “Synced from Amperity.” as its description.

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.

Note

MoEngage accepts each request and processes it later. A successful run means that MoEngage accepted every request, not that it matched every person to a user. Check the segment in the MoEngage dashboard under Segment > All Segments after the first send, and compare its size to the audience.

Note

A MoEngage segment holds up to 5 million users. A run whose audience has more than 5 million rows fails before Amperity sends anything. Narrow the audience, or split it into several audiences, each with its own list name.

Amperity sends at most four requests each second, which stays under the 300 requests each minute that Cohort Sync accepts.

Customer IDs

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.

Important

Cohort Sync matches people only to users that MoEngage already has, by customer ID. A customer ID that is not exactly the one your app or website uses for that user in MoEngage matches no one, and MoEngage does not return an error. A run can succeed while the segment stays empty.

Get details

Review the following details before configuring credentials for MoEngage and before configuring Amperity to send audiences to custom segments in a MoEngage workspace.

	Credential settings Required All three credential fields are required. Workspace ID The ID of the MoEngage workspace that Amperity sends to. MoEngage also calls this the App ID. Find it in the MoEngage dashboard under Settings > Account > APIs. MoEngage describes where to find the Workspace ID and API keys in its API authentication guide. API Key A Basic Auth API key from Settings > Account > APIs in the MoEngage dashboard. Amperity sends the Workspace ID as the username and the API key as the password. Give the key access to both the Data APIs and the Segmentation APIs. MoEngage Attributes uses the Data APIs, and MoEngage Cohorts uses Cohort Sync. A key with access to both works for both destinations, so one credential can serve them both. Important Create an API key that only Amperity uses. When a key is regenerated, MoEngage stops accepting the old key immediately, so a key that is shared with another integration stops working in Amperity as soon as someone rotates it for that integration. Data Center The MoEngage data center that hosts the workspace: 01, 02, 03, 04, 05, 06, or 101. Defaults to 01. The data center is the number in the MoEngage dashboard URL. For example, the data center for https://dashboard-01.moengage.com is 01. Amperity sends every request to the API host for this data center. A workspace answers only on its own data center’s host, so a wrong value fails every request, including the connection test. API Firewall When the MoEngage workspace has the API Firewall turned on, add the Amperity IP addresses for allowlists to it. MoEngage refuses requests from addresses that the API Firewall blocks.
	Required configuration settings Customer ID field Required. Select customer_id, which is the only option. The query results must include a column named customer_id that holds each customer’s MoEngage customer ID. Amperity matches the column name without regard to case, so Customer_ID is also accepted. Amperity uses this field to identify each customer across runs, so that it sends only what changed since the last successful run. List name (Required at orchestration) 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.
	A query that returns a customer_id field that holds the ID your app or website uses for each user in MoEngage. Amperity sends only the customer_id field to MoEngage.

Configure credentials

Configure credentials for MoEngage before adding a destination.

An individual with access to MoEngage should use SnapPass to securely share “Workspace ID”, “API Key”, and “Data Center” details with the individual who configures Amperity.

The MoEngage Attributes and MoEngage Cohorts destinations use the same credential type. A credential that you configure for one of them can be selected for the other.

To configure credentials for MoEngage

	From the Settings page, select the Credentials tab, and then click the Add credential button.
	In the Create credential dialog box, do the following: From the Plugin dropdown, select “MoEngage Cohorts”. Assign the credential a name and description that ensures other users of Amperity can recognize when to use this destination.
	The settings that are available for a credential vary by credential type. For the “moengage-api” credential type, configure settings, and then click Save. Required Workspace ID The ID of the MoEngage workspace that Amperity sends to. MoEngage also calls this the App ID. Find it in the MoEngage dashboard under Settings > Account > APIs. MoEngage describes where to find the Workspace ID and API keys in its API authentication guide. API Key A Basic Auth API key from Settings > Account > APIs in the MoEngage dashboard. Amperity sends the Workspace ID as the username and the API key as the password. Give the key access to both the Data APIs and the Segmentation APIs. MoEngage Attributes uses the Data APIs, and MoEngage Cohorts uses Cohort Sync. A key with access to both works for both destinations, so one credential can serve them both. Important Create an API key that only Amperity uses. When a key is regenerated, MoEngage stops accepting the old key immediately, so a key that is shared with another integration stops working in Amperity as soon as someone rotates it for that integration. Data Center The MoEngage data center that hosts the workspace: 01, 02, 03, 04, 05, 06, or 101. Defaults to 01. The data center is the number in the MoEngage dashboard URL. For example, the data center for https://dashboard-01.moengage.com is 01. Amperity sends every request to the API host for this data center. A workspace answers only on its own data center’s host, so a wrong value fails every request, including the connection test.

Add destination

Use a sandbox to configure a destination for MoEngage. Before promoting your changes, send a sample audience, and then verify the results in MoEngage. After verifying the end-to-end workflow, push the destination from the sandbox to production.

To add a destination for MoEngage Cohorts

	Open the Destinations page, select the New destinations button, and then select Orchestration. To configure a destination for MoEngage, do one of the following: Click the row in which MoEngage is located. Destinations list alphabetically and you can scroll up and down the list. Search for MoEngage. Start typing “moe”. The list filters to show only matching destinations. Select “MoEngage Cohorts”.
	Select the credential for MoEngage from the Credential dropdown, and then click Continue. Tip Amperity validates the connection when the destination is saved. If the connection cannot be validated, an error is shown and the destination is not saved. The connection test asks MoEngage to check the Workspace ID, the API key, and the data center together. The test fails when MoEngage does not accept all three, with a message saying that MoEngage did not accept the credential. MoEngage has no Cohort Sync request that only reads, so the connection test cannot check that the API key has access to Cohort Sync. A key that Cohort Sync does not accept passes the test, and then the first send fails.
	In the “Destination settings” dialog box, assign the destination a name and description that ensures other users of Amperity can recognize when to use this destination. Configure business user access By default a destination is available to all users who have permission to view personally identifiable information (PII). Enable the Admin only checkbox to restrict access to only users assigned to the Datagrid Operator and Datagrid Administrator policies. Enable the PII setting checkbox to allow limited access to PII for this destination. Use the Restrict PII access policy option to prevent users from viewing data marked as PII anywhere in Amperity and from sending data to downstream workflows.
	Configure the following settings, and then click “Save”. Customer ID field Required. Select customer_id, which is the only option. The query results must include a column named customer_id that holds each customer’s MoEngage customer ID. Amperity matches the column name without regard to case, so Customer_ID is also accepted. Amperity uses this field to identify each customer across runs, so that it sends only what changed since the last successful run. List name (Required at orchestration) 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.
	After configuring this destination users may use: Orchestrations to send query results Orchestrations and campaigns to send audiences
	Validate the audience with MoEngage by using a sample audience with a very small membership. For example: 10 or 100 members or the minimum audience size recommended by MoEngage. Send the sample audience to MoEngage and verify the sample audience is correct in MoEngage. Make adjustments if necessary. Only send full audiences after validation is complete.

Data validation

Amperity adds every person who joined the audience, except for people that it cannot send to MoEngage. A row whose customer ID contains only whitespace, is one character long, or is a placeholder value that MoEngage does not accept is reported as failed, and the run continues. A row whose customer ID is null or empty is skipped without an error, and a customer ID that appears on more than one row is added once. See Customer IDs, earlier on this page. A person who left the audience with a whitespace-only, one-character, or placeholder customer ID is skipped without an error, because that person was never added to the segment.

Failed rows are reported in the destination’s run details. A run shows at most 25 error messages. The failed-row count still includes every failure, so a problem that affects many rows does not bury the output in copies of one message.

Some conditions stop the entire run instead of failing individual rows. Three of them are caught before any data is sent:

• The query results have no customer_id column.

• The audience has more than 5 million rows.

• In a campaign, the list name that results from the campaign and treatment names is not a name that MoEngage accepts. The message names the list name and says to rename the campaign or treatment, or to change the list name.

The others are MoEngage responses to a request. Each one applies to the whole request, so Amperity stops the run rather than sending the rest of the changes:

• MoEngage rejected the credential. Check the Workspace ID, the API key, and the data center. Confirm that the key was not regenerated, and that it has access to the Data APIs and the Segmentation APIs.

• MoEngage refused the request. MoEngage refuses requests from a suspended workspace, and requests that an API Firewall rule blocks. Confirm that the workspace is active, and that the API Firewall allows the Amperity IP addresses.

• MoEngage rejected the data as malformed. MoEngage rejected a request to add or remove people.

• MoEngage rejected the request for another reason. The message includes the HTTP status code. Sending the same request again does not change the result.

Note

A run that stops partway has already sent the requests before the one that failed. Amperity sends every removal before any addition, so a run that stops partway can leave the segment with people removed but the people who joined not yet added.

Rate-limit responses and server errors from MoEngage are retried automatically with backoff. When they persist after the retries, the run fails. For rate limits, avoid overlapping runs and schedule large sends outside peak hours. For server errors, run the destination again after MoEngage recovers. When Amperity cannot reach MoEngage at all, the run fails with a message that starts with “Could not reach MoEngage”.