Tracking events | Hellotext

Event tracking turns customer activity into signals that Hellotext can use in customer profiles, segments, attribution, playbooks, journeys, and Inbox.

Signals can come from an integration, Hellotext.js, your backend, a physical store, forms, conversations, or Hellotext’s internal actions. You do not need to track every signal manually or implement every available event.

For the general product concept, start with What are signals?.

Signals, actions, events, and objects

These terms describe different parts of the same flow:

A signal is information Hellotext can interpret when making decisions.
An action defines what happened, such as product.viewed or order.delivered.
An event is one occurrence of that action for a customer or session at a specific time.
An object provides related context, such as the product, cart, order, coupon, or form.

For example, this event says that one customer profile viewed a specific product:

{
  "action": "product.viewed",
  "profile": "PROFILE_ID",
  "object": "PRODUCT_ID",
  "tracked_at": "2026-08-07T12:30:00Z"
}

The action alone is not always enough. product.viewed needs the viewed product, and order actions need the corresponding order.

Most built-in actions use the object.verb format. subscribed and unsubscribed are current exceptions and must not be renamed by adding a prefix.

Built-in actions for integrations

These are the actions an integration can normally track. Use only the actions that represent real activity in your system.

Subscription

subscribed: the customer gave consent and subscribed through a compatible channel.
unsubscribed: the customer withdrew consent or opted out.

Do not use subscribed simply because you created a customer profile. See Who can I message?.

Pages and products

page.viewed: the customer viewed a page.
product.viewed: the customer viewed a specific product.
product.purchased: the customer purchased a product outside a more complete order lifecycle.

Hellotext.js automatically tracks page.viewed with the current URL. A page view does not identify the product by itself, so product.viewed must explicitly include the corresponding product.

If your store uses orders, prefer order actions instead of also tracking product.purchased for the same purchase.

Carts and checkout

cart.viewed: the customer viewed their cart.
cart.added: a product was added to the cart.
cart.removed: a product was removed from the cart.
cart.abandoned: the store determined that the cart was abandoned.
checkout.started: the customer started checkout.

Do not send cart.abandoned simply because the customer left a page. Track it when your store or integration has actually determined that the cart was abandoned.

Orders

order.placed: the customer created the order.
order.confirmed: the business confirmed the order.
order.cancelled: the order was cancelled.
order.shipped: the order left for delivery.
order.delivered: delivery was confirmed.

Track each change when it happens and reuse the same order object. Do not send every state together when the order is created.

Coupons, refunds, and forms

coupon.redeemed: the customer redeemed a coupon.
refund.requested: the customer requested a refund.
refund.received: the business completed the refund.
form.completed: the customer completed a form.

Apps

app.installed: the customer installed an app.
app.removed: the customer removed an app.
app.spent: the customer made a purchase associated with an app.

The correct names are app.installed and app.removed. Do not use the old app.install or app.remove variants.

Actions generated by Hellotext

Hellotext also creates internal signals for messages, conversations, segments, short links, customer profile changes, and playbook decisions. Some actions, such as product.browse_abandoned, product.price_changed, or order.printed_label, belong to internal product processes.

Do not reproduce those actions manually or send them from your integration unless they are explicitly listed as supported in the tracking API reference. Duplicating them can trigger automations or affect reporting incorrectly.

Custom actions

When no built-in action represents what happens in your business, create a custom action from Settings → Actions → Custom or through the API.

Use a stable, descriptive name, for example:

appointment.completed
store_visit.completed
membership.renewed

Do not generate a new name for each customer, order, or date. An action represents one reusable activity type, and each event represents one occurrence.

The custom action must exist before you track the first event. See Create an action.

To define the name, track occurrences, and use the action in journeys or reports, read Custom actions.

A custom event with a positive monetary amount can be evaluated for attribution when Hellotext identifies the customer and finds eligible source and timing evidence. Creating the action does not automatically turn its amount into attributed revenue. See How we attribute sales.

How events reach Hellotext

Integrations

eCommerce, channel, and other platform integrations can create customer profiles, objects, and events automatically. Review what each integration provides and do not send the same events again from your code.

See Setup and integrations and Verify your data and signals after setup.

Hellotext.js

Use Hellotext.js for activity that happens in the browser, such as page views, product views, and cart changes. The library includes the current session to preserve anonymous context.

See the Hellotext.js repository for current instructions.

API

Use the API from your backend for trusted events such as orders, payments, cancellations, shipments, deliveries, and external-system activity.

For a complete implementation, see Integrate a custom store with Hellotext.
To send events from the backend, see External tracking.
To associate anonymous activity, see Tracking unidentified customers.

Manual tracking

You can also use New event inside a customer profile to record one manual occurrence. This does not configure automatic tracking for future events.

Data each event should preserve

Before implementing an action, define:

Identity: the known customer profile or anonymous session.
Object: the related product, cart, order, or other object.
Time: the actual event time through tracked_at when it is not happening in real time.
Value: amount and currency when the action has a monetary value.
Source: the integration or system that produced the activity.

Use stable identifiers and do not send the same event from multiple sources.

Verify tracking

Test with one recognizable customer first:

Confirm that the event appears on the correct customer profile.
Check that the action uses the exact name.
Confirm that the related object is the expected product, cart, or order.
Check that the timestamp represents when the activity happened.
Confirm that the integration did not already create the same event automatically.
Review segments, playbooks, and reports only after validating the underlying data.

If events do not appear where expected, use Troubleshoot missing signals or activity.