Send events to 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.

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.

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.

Add orchestration

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

To add an orchestration

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

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

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.

Run orchestration

Run the orchestration manually to validate that it works.

To run the orchestration

1. Open the Activations page, select the Orchestrations tab, and then open the menu for the Attentive 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”.

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.