Event entity

Events are a type of entity. An event represents a single occurrence of a specific customer action related to a customer session or a customer profile.

For example, a user updating their cart is considered a single event.

There are two types of events:

Built-in events
Custom events

Built-in events

Built-in events are provided by Talon.One and are tied to a customer session or a customer profile. They are triggered depending on the endpoints used by your integration, and by the content of the requests.

Example

When your integration layer calls the Update customer session endpoint, for instance when a customer adds an item to their cart, an implicit talon_session_updated event happens.

Each event is related to a state:

See Customer session states.

Event name (Rule Builder event type)	Trigger criteria for the event	Triggered by
`talon_session_created` (Customer Session Creation)	A new session integration ID is sent to Talon.One so a new session is created. The `state` property becomes `open`. Example: The customer creates a cart.	Update customer session
`talon_session_updated` (Customer Session Update)	An open session was updated. The `state` property remains `open`. Example: The customer adds an item to the cart.	Update customer session
`talon_session_closed` (Customer Session Closing)	An open session was closed. The `state` property becomes `closed`. Example: The customer completes the payment step.	Update customer session
`talon_session_cancelled`	An open session was cancelled. The `state` property becomes `cancelled`. Example: The customer leaves before checkout.	Update customer session
`talon_session_revoked`	A closed session was cancelled. The `state` property becomes `cancelled`. Example: The customer requests a refund.	Update customer session
`talon_session_partially_returned`	A closed session had some items returned. The `state` property becomes `partially_returned`. Example: The customer returns some of the items and expects the corresponding refund.	Return cart items
`talon_session_reopened`	A closed session was reopened. The `state` property becomes `open`. Example: The closed order has to be modified after payment was processed.	Reopen customer session
`talon_profile_created` (Customer Profile Registration)	A new customer integration ID is sent to Talon.One.	Update customer profile with `runRuleEngine=true`
`talon_profile_updated` (Customer Profile Update)	An existing customer profile was modified.	Update customer profile with `runRuleEngine=true`

Custom events

Custom events are created by you. They contain custom attributes. Custom events cannot be canceled.

You can send these events with the Track Event endpoint and use them in the Rule Builder.

Example

You create an event that triggers when a user visits a page. Let's imagine that this event contains a custom url attribute. When the event is triggered for a given customer session, the url attribute and its value are added to the customer session. You can then use this attribute in the Rule Engine and Integration API.

important

A built-in event may readily fit your business scenario. Review the list of available built-in events before creating custom events.

Creating a custom event

A custom event contains one or more attributes. Even if you do not need an attribute in your use case, the event you create must contain one.

To create a custom event, create a custom attribute of type event, it will also automatically create an attribute:

Open your Application.
Click Account > Tools > Attributes > Create Attribute.
In Entity, select Event.
In Event type, type a new value. This is the event name.
In Type, select the type of the attribute.
In API name, enter the name of the attribute contained in the event.

Example
To have a pageview event that contains a url attribute, Event type is pageview, API name is url.
Fill the other fields as needed and click Create Attribute.

The event now automatically contains a first attribute of the type and API name you just chose. You can now trigger the event or add more attributes to this event. To add more attributes, repeat the procedure, but ensure you always use the same value for Event type.

For more information about custom attributes, see Attributes.

Triggering an event

After you have defined an event, the integration layer can trigger it via the Integration API's Track event endpoint and bind it to a given customer session.

To use the endpoint, ensure you know your event details such as the event type, API name, and the customer session.

For example, assuming we created a pageview event with the url API name, we can call the Track Event endpoint with the following payload:

curl -X POST -H 'Content-Type: application/json' \
 -H 'Authorization: ApiKey-v1 953f4d85715c425cb48676' \
 -d '{
  "profileId": "myprofileid",
  "type": "pageview",
  "attributes": {
    "url": "some value"
  }
}' 'https://mycompany.europe-west1.talon.one/v2/events'

The response contains the effects triggered by the Rule Engine, and all the details of the session, such as cart items and session total.

Using an event in a rule

When the integration layer registers custom events with the Track Event endpoint, you can check specific events in a rule:

In a rule, add the Check for event types condition.
In Event type, select your event type. For example, pageview.
In the next field, select one of the attributes of your event type. Click And... to check extra attributes of your event, if you have any.
Finish your rule by setting an effect and save.

Whenever the selected event type is triggered, the rule is evaluated.

Displaying triggered events

See Displaying events in the Product docs.

Built-in events​

Custom events​

Creating a custom event​

Triggering an event​

Using an event in a rule​

Displaying triggered events​

Related pages​