Configure destinations for MoEngage Attributes

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 Attributes connector sends customer attributes from Amperity to user profiles in a MoEngage workspace. MoEngage stores them as user attributes, which your MoEngage team uses to build segments and to personalize messages. This is not the MoEngage destination, which sends CSV files to an Amazon S3 bucket, or the MoEngage Cohorts destination, which keeps a MoEngage segment in step with an Amperity audience.

Each row in the query results is one user. The customer_id column supplies the user’s MoEngage customer ID, which MoEngage uses to find the user. Every other column is sent as a user attribute under the column’s name. See User attributes.

Amperity syncs attributes incrementally. Only the rows that changed since the last successful run are sent, and unchanged rows are reported as sent from cache. MoEngage creates a user for each customer ID that it does not have, and updates the users that it does have. To update existing users only, select the Update existing users only? setting.

Note

This destination uses the MoEngage Data API , sending users with Bulk Import .

Beta

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

Important

The connector reads each row’s customer ID from a column named customer_id. If your query produces the identifier under another name, alias it, for example SELECT loyalty_id AS customer_id. A send whose query results have no customer_id column fails before any data is sent, with a message that names the missing column.

Note

MoEngage accepts each request and processes it later. A successful run means that MoEngage accepted every request, not that it saved every user. MoEngage does not report back to Amperity on the users in a request, so check a few user profiles in the MoEngage dashboard after the first send.

Note

Amperity sends at most 500 users in each request, and at most one request each second. This limits a run to about 30,000 users each minute, or 1.8 million users each hour. MoEngage allows a workspace 60,000 users each minute across all of the workspace’s sources, so this leaves capacity for your other sources. Only changed rows are sent, so a run’s length depends on how many rows changed since the last run.

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.

User attributes

Every column in the query results except customer_id is sent to MoEngage as a user attribute. The column name becomes the attribute name, and the column value becomes the attribute value.

• Standard attributes need MoEngage’s attribute names. To fill a standard MoEngage attribute, name the column with that attribute’s key, for example SELECT email AS u_em. A column with any other name creates or updates a custom attribute with that name.

  Column name	Standard attribute
  u_em	Email
  u_mb	Mobile number
  u_fn	First name
  u_ln	Last name
  u_n	Full name
  u_gd	Gender
  u_bd	Birthdate

  MoEngage lists every standard attribute and its format in the Bulk Import reference.

• Values are sent as your query returns them. Amperity does not convert or check attribute values. A number is sent as a number, a Boolean value as a Boolean value, and text as text. Build the exact value that you want to see in MoEngage in your query.

• Send dates as ISO 8601 text. MoEngage documents date attributes, including u_bd, in ISO 8601 format with a time and a time zone, for example 2020-05-31T03:47:35Z. Amperity sends a date the way the query returns it, so convert a date that is in another form, such as 05/31/2020 or a number of seconds since 1970, in the query. To convert a timestamp that is in UTC, use DATE_FORMAT(birthdate, '%Y-%m-%dT%H:%i:%sZ') AS u_bd.

• A null value clears the attribute. When a column is null for a row, Amperity asks MoEngage to remove that attribute from the user, so that MoEngage matches Amperity. This also clears a value that another source, such as a MoEngage SDK in your app or website, set for that attribute. A column that is empty text, rather than null, is sent as empty text.

• Some attribute names are not accepted. MoEngage does not accept id, _id, or an empty name as an attribute name. A send whose query results have a column with one of these names fails before any data is sent. Rename the column.

Caution

MoEngage reserves the moe_ prefix for its own attributes, and says that it can block a workspace that uses the prefix for custom attributes. Amperity does not check for the prefix, because some standard attributes, such as moe_unsubscribe, use it. Name a column with moe_ only when it fills a MoEngage standard attribute.

Caution

Amperity owns the attributes that it sends. When a row changes, Amperity sends all of the row’s attributes, which overwrites the values that another source, such as a MoEngage SDK, set for the same attributes. Do not send an attribute that another source should own.

Caution

Amperity sends only the rows that are in the query results. A user who drops out of the query results is not sent again, so the attributes that user already has stay in MoEngage, holding their last values. Removing a column from the query has the same effect: the attribute keeps its last value on every user who has it.

To clear an attribute for users who no longer qualify, keep them in the query results and return a null value for that attribute.

Get details

Review the following details before configuring credentials for MoEngage and before configuring Amperity to send customer attributes to user profiles 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. Optional configuration settings Update existing users only? Optional. When selected, MoEngage updates only the users that already have the customer ID in the row, and ignores rows for customer IDs that it does not have. Unselected by default, which means that MoEngage creates a user for every customer ID that it does not have, and updates the rest.
	Query results The query that sends to this destination must return a column named customer_id that holds the ID your app or website uses for each user in MoEngage. Every other column becomes a user attribute named after that column, so the set of columns you return is the set of attributes that reach MoEngage. Name each column that fills a standard attribute with its MoEngage key, such as u_em, and format dates as ISO 8601 text.

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 Attributes”. 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 Attributes

	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 Attributes”.
	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.
	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. Update existing users only? Optional. When selected, MoEngage updates only the users that already have the customer ID in the row, and ignores rows for customer IDs that it does not have. Unselected by default, which means that MoEngage creates a user for every customer ID that it does not have, and updates the rest.
	After configuring this destination users may use orchestrations to send query results MoEngage.
	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 sends every changed row, except for rows that it cannot send to MoEngage. A row is reported as failed, and the run continues, when either of the following is true:

• The row’s customer ID contains only whitespace, is one character long, or is a placeholder value that MoEngage does not accept. A row whose customer ID is null or empty, or repeats another row’s customer ID, is skipped without an error instead. See Customer IDs.

• The row’s attributes are larger than the 100 KB that MoEngage accepts in one request. Send fewer or shorter attributes.

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. Two of them are caught before any data is sent:

• The query results have no customer_id column.

• The query results have a column named id or _id, or a column with an empty 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 query results:

• 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.

• 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 because of the attributes in it, such as an attribute name or a value type that it does not accept. Check the columns in the query results.

• 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. The users in those requests are updated in MoEngage, and the rest are not.

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, because every source that writes to the workspace shares its limit. 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”.