Configure events for Attentive

Attentive is an SMS and email marketing platform that brands use to run subscriber journeys, segment audiences, and personalize messaging. Send ecommerce and behavioral events to Attentive to trigger journey automations, build audience segments, and attribute revenue to campaigns.

Send ecommerce and conversion events to Attentive to power SMS and email journey triggers, audience segmentation, and revenue attribution. Amperity sends the rows returned by your query to Attentive as events, each identified by a customer email, phone number, or both.

A destination sends a single event type, which you choose from PRODUCT_VIEW, ADD_TO_CART, PURCHASE, CUSTOM_EVENT, or CUSTOM_ATTRIBUTES. To send more than one event type, configure a separate destination for each. See the Attentive API reference for more information.

Beta

The Attentive eCommerce & Conversion Events connector is currently in beta. Contact your Amperity representative to learn more.

Get details

Review the following details before configuring credentials for Attentive and before configuring Amperity to send ecommerce and conversion events to Attentive.

	Credential settings API key Required An API key that authorizes Amperity to send events to Attentive. Attentive generates the key as a bearer token, and Amperity adds it to each request automatically. Generate the key in the Attentive UI under Settings > Integrations > Custom Integrations by creating a new integration. Grant the key all three scopes — ecommerce:write, events:write, and attributes:write — so that one key works for any event type. If the key is revoked or regenerated in Attentive, update the credential in Amperity.
	Attentive settings Event Type Required The type of event this destination sends to Attentive. Select one of PRODUCT_VIEW, ADD_TO_CART, PURCHASE, CUSTOM_EVENT, or CUSTOM_ATTRIBUTES. A destination sends a single event type; to send more than one, configure a separate destination for each. Custom Event Type Name Required when Event Type is CUSTOM_EVENT. The name of the Attentive custom event type to send, exactly as it appears in the Attentive UI (case-sensitive). The event type must already exist in Attentive. Individual rows can override this value with an event_type_name column.
	Request properties A query must return at least one of email or phone. The remaining columns a query returns depend on the destination’s event type. See Event types for the event type each destination sends, and Source columns by event type for the columns each event type accepts.

Configure credentials

Configure credentials for Attentive before adding a destination.

An individual with access to Attentive should use SnapPass to securely share “API key” details with the individual who configures Amperity.

To configure credentials for Attentive

	From the Settings page, select the Credentials tab, and then click the Add credential button.
	In the Credentials settings dialog box, do the following: From the Plugin dropdown, select Attentive eCommerce & Conversion Events. 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 “attentive-ecommerce-offline-events” credential type, configure settings, and then click Save. API key Required An API key that authorizes Amperity to send events to Attentive. Attentive generates the key as a bearer token, and Amperity adds it to each request automatically. Generate the key in the Attentive UI under Settings > Integrations > Custom Integrations by creating a new integration. Grant the key all three scopes — ecommerce:write, events:write, and attributes:write — so that one key works for any event type. If the key is revoked or regenerated in Attentive, update the credential in Amperity.

Add destination

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

To add a destination

	Open the Destinations tab to configure a destination for Attentive. Click the Add Destination button to open the Destination dialog box. Enter the name of the destination and a description. For example: “Attentive purchase events” and “Send purchase events to Attentive.”.
	Credentials allow Amperity to connect to Attentive. The credential type is set automatically. You may use an existing credential or you may add a new one. Select an existing credential from the Credential dropdown. – or – Select Create a new credential from the Credential dropdown. This opens the Credential dialog box.
	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”. Event Type Required The type of event this destination sends to Attentive. Select one of PRODUCT_VIEW, ADD_TO_CART, PURCHASE, CUSTOM_EVENT, or CUSTOM_ATTRIBUTES. A destination sends a single event type; to send more than one, configure a separate destination for each. Custom Event Type Name Required when Event Type is CUSTOM_EVENT. The name of the Attentive custom event type to send, exactly as it appears in the Attentive UI (case-sensitive). The event type must already exist in Attentive. Individual rows can override this value with an event_type_name column.
	After configuring this destination users may use orchestrations to send query results Attentive.
	Validate the audience with Attentive by using a sample audience with a very small membership. For example: 10 or 100 members or the minimum audience size recommended by Attentive. Send the sample audience to Attentive and verify the sample audience is correct in Attentive. Make adjustments if necessary. Only send full audiences after validation is complete.

Build a query

Use a query to build a combination of data that returns one row per event to send to Attentive. Every event type requires at least one customer identifier — an email, a phone number, or both. The remaining columns your query returns depend on the event type the destination sends; review Source columns by event type for the columns each event type accepts.

Bound the query to recent activity so each orchestration sends new events instead of re-sending the full history; choose a window that matches how often the orchestration runs.

A purchase query typically draws one row per line item from the Unified Itemized Transactions table, joined to Customer 360 for identifiers. Rows that share an order_id (with the same identifiers) are grouped into a single purchase event, so return every line item for an order. A query that returns recent purchase line items for use in Attentive is similar to:

SELECT
  c360.email AS email
  ,c360.phone AS phone
  ,txn.order_id AS order_id
  ,txn.order_datetime AS occurred_at
  ,txn.product_id AS product_id
  ,txn.product_id AS product_variant_id
  ,txn.product_description AS name
  ,txn.unit_revenue AS price
  ,txn.item_quantity AS quantity
  ,'USD' AS currency
  ,'WEB' AS sales_channel
FROM Unified_Itemized_Transactions txn
LEFT JOIN Customer_360 c360 ON txn.amperity_id = c360.amperity_id
WHERE txn.order_datetime > (CURRENT_DATE - interval '30' day)
  AND (txn.is_return = FALSE OR txn.is_return IS NULL)
  AND (txn.is_cancellation = FALSE OR txn.is_cancellation IS NULL)
  AND (c360.email IS NOT NULL OR c360.phone IS NOT NULL)

Returns and cancellations are excluded so that only completed purchases are sent. If your products have distinct variants, map the variant identifier to product_variant_id instead of reusing product_id.

Event types

The Event Type setting determines which Attentive endpoint a destination sends to. Each destination sends exactly one event type; to send more than one, configure a separate destination for each. The API key must have all three Attentive scopes — ecommerce:write, events:write, and attributes:write — so that one key works for any event type.

Event Type	Description
PRODUCT_VIEW	A subscriber viewed a product. Sends one event per row.
ADD_TO_CART	A subscriber added a product to their cart. Sends one event per row.
PURCHASE	A subscriber completed a purchase. Line items that share an order are sent together as one event.
CUSTOM_EVENT	Any behavioral event — for example, “Order Shipped” — that triggers a pre-configured Attentive journey. Sends one event per row.
CUSTOM_ATTRIBUTES	Subscriber profile attributes — for example, loyalty tier or preferred category. Sends one update per row.

Note

A CUSTOM_EVENT type must already exist in the Attentive UI before you send it. Rows sent for an event type that does not exist are rejected and skipped. With CUSTOM_ATTRIBUTES, each attribute is locked to the data type Amperity first sends — for example, a value first sent as text cannot later be sent as a number — so plan attribute types before you enable a destination.

Source columns by event type

The columns your query must return depend on the destination’s Event Type. Return each column with the exact lowercase name shown in the tables below: column names are matched exactly, so a column returned as EMAIL or Product_ID is not recognized. Mis-casing an identifier column (email or phone) causes the run to fail; mis-casing any other column causes every row to be skipped. Every event type requires at least one of email or phone; Amperity lowercases and trims the email value and normalizes the phone value to E.164 format.

PRODUCT_VIEW and ADD_TO_CART

Amperity column	Attentive field	Description
email	user.email	Required (one of email or phone). A subscriber email address.
phone	user.phone	Required (one of email or phone). A subscriber phone number. Amperity normalizes it to E.164; a number that cannot be normalized falls back to email only.
product_id	productId	Required. The vendor product identifier. A row missing this value is skipped.
product_variant_id	productVariantId	Required. The vendor product variant identifier. A row missing this value is skipped.
name	name	Optional. The product display name.
price	price.value	Optional. A unit price, as a number or a string (for example, 19.99 or $19.99). Non-numeric or negative values are dropped from the row.
currency	price.currency	Optional. The ISO 4217 currency code for price. Defaults to USD when absent.
quantity	quantity	Optional. The number of units, as a number or a string. Zero, negative, or non-numeric values are dropped from the row.
product_image	productImage	Optional. A product image URL.
product_url	productUrl	Optional. A product page URL.
occurred_at	occurredAt	Optional. When the event occurred, as an ISO 8601 timestamp. Omit to use the time the event is sent. See Data validation for how timestamps in the past are handled.

PURCHASE

Purchase accepts every product view column above, plus the following. Return one row per line item; rows that share the same order_id and identifiers are grouped into a single purchase event. Order-level values — order_id, sales_channel, and occurred_at — are taken from the first row in each group, so return the same values on every line item of an order.

Amperity column	Attentive field	Description
order_id	orderId	Optional. The order identifier. Used both to group line items into one purchase event and by Attentive to deduplicate.
sales_channel	salesChannel.channelType	Optional. The channel the purchase occurred on (for example, WEB or IN_STORE). Amperity converts the value to uppercase.

CUSTOM_EVENT

Amperity column	Attentive field	Description
email	user.email	Required (one of email or phone). A subscriber email address.
phone	user.phone	Required (one of email or phone). A subscriber phone number.
event_type_name	type	Optional. The Attentive custom event type name for this row. Overrides the Custom Event Type Name setting. The value must exactly match an event type already created in the Attentive UI (case-sensitive).
external_event_id	externalEventId	Optional. A unique identifier for the event that Attentive uses to deduplicate.
occurred_at	occurredAt	Optional. When the event occurred, as an ISO 8601 timestamp. Omit to use the time the event is sent.
any other column	properties	Optional. Every other column becomes an event property. Restricted characters ("'(){}[]\|,) are stripped from column names.

CUSTOM_ATTRIBUTES

Amperity column	Attentive field	Description
email	user.email	Required (one of email or phone). A subscriber email address.
phone	user.phone	Required (one of email or phone). A subscriber phone number.
any other column	properties	Required. Every other column becomes a subscriber attribute; at least one is required. Restricted characters ("'(){}[]\|,) are stripped from attribute names.

Note

CUSTOM_ATTRIBUTES has no timestamp field. Unlike the other event types, an occurred_at column is sent as a subscriber attribute named occurred_at rather than as an event time. Because an attribute’s type locks to whatever Amperity first sends, avoid carrying occurred_at over from a PURCHASE or CUSTOM_EVENT query.

Data validation

Amperity validates each row before sending, so that one invalid row does not stop the rest of the events. A row is skipped, and reported, when:

• It has neither a valid email nor a phone number that can be normalized to E.164 — Attentive requires at least one identifier to match a subscriber.

• For PRODUCT_VIEW or ADD_TO_CART, it is missing product_id or product_variant_id.

• For CUSTOM_EVENT, no event type is resolved from either the event_type_name column or the Custom Event Type Name setting.

• For CUSTOM_ATTRIBUTES, it contains no attribute columns beyond the identifiers.

PURCHASE handles invalid line items differently: a line item missing product_id or product_variant_id is excluded from its order and the remaining line items are still sent, so the purchase is skipped only when no line item in the order is valid. Because those dropped line items are not reported individually, return complete product data for every line item to avoid sending an order whose total is quietly short.

Optional values that cannot be used — a non-numeric or negative price, a zero or non-numeric quantity, or an unparseable occurred_at — are dropped from that row individually; the rest of the event is still sent.

Note

An event whose occurred_at is more than 12 hours in the past is still sent and recorded in Attentive’s behavioral history, but it does not trigger journey automations. This is expected when backfilling historical events. Amperity logs the number of such events after each run.

Workflow actions

A workflow will occasionally show an error that describes what prevented a workflow from completing successfully. These first appear as alerts in the notifications pane. The alert describes the error, and then links to the Workflows tab.

Open the Workflows page to review a list of workflow actions, choose an action to resolve the workflow error, and then follow the steps that are shown.

	You may receive a notifications error for a configured Attentive destination. This appears as an alert in the notifications pane on the Destinations tab. If you receive a notification error, review the details, and then click the View Workflow link to open this notification error in the Workflows page.
	On the Workflows page, review the individual steps to determine which steps have errors that require your attention, and then click Show Resolutions to review the list of workflow actions generated for this error.
	A list of individual workflow actions are shown. Review the list to identify which action you should take. Some workflow actions are common across workflows and will often be available, such as retrying a specific task within a workflow or restarting a workflow. These types of actions can often resolve an error. In certain cases, actions are specific and are shown when certain conditions exist in your tenant. These types of actions typically must be resolved and may require steps that must be done upstream or downstream from your Amperity workflow. Amperity provides a series of workflow actions that can help resolve specific issues that may arise with Attentive, including: Invalid credentials
	Select a workflow action from the list of actions, and then review the steps for resolving that error. After you have completed the steps in the workflow action, click Continue to rerun the workflow.

Note

If Attentive rejects a request, Amperity reports the error with Attentive’s response detail — review the field values returned by your query. Rows that Attentive rejects individually (for example, an unknown subscriber, or a custom event type that does not yet exist) are skipped and reported without stopping the rest of the run. If sends are rate limited, Amperity retries automatically.

Invalid credentials

Attentive was unable to accept the API key configured for this workflow. The key may be incorrect or revoked, or it may be missing one of the required Attentive scopes — the key must have ecommerce:write, events:write, and attributes:write.

To resolve this error, verify the API key configured for this workflow in Amperity.

1. In the Attentive UI, confirm the API key is active and has all three required scopes (ecommerce:write, events:write, and attributes:write). Regenerate the key if necessary.

2. Open the Destinations page and update the credential associated with this workflow with a valid API key.

3. Return to the workflow action, and then click Resolve to retry this workflow.