Get all events by customer for session

The tracking endpoints require the org.tracking role, the one role a chat key has, so they can be called directly from a customer's browser or app. Each visitor gets a trackingId. If you don't send one, Kustomer creates it and, in a browser, stores it in a cookie so later calls from the same visitor reuse it. Events from a visitor who hasn't been identified are anonymous. Once you call an identity endpoint with the visitor's email, phone or externalId, Kustomer finds or creates the matching customer, and later events for that trackingId are recorded as that customer's events.

The Customers (Events) endpoints are the read side. They need a regular API key with event read access, and return customer_event resources from the customer's event history. That history holds tracking events, grouped into sessions, and also records of changes to the customer, such as a kustomer.customer.update event whose changes lists each attribute's before and after values.

Events

An event has a name and optional meta. The name must start with a letter and use only letters, digits, -, _ and ., up to 255 characters; Kustomer stores it with a tracking. prefix, so viewed-pricing is read back in trackingEvent as tracking.viewed-pricing. meta holds up to 100 properties, typed like custom attributes. Kustomer adds the suffix for you: a number named cartTotal is stored as cartTotalNum, a string as …Str (unless the name already ends in Str or At), and any other value is stored as JSON text in a …Txt property. Events also record the caller's approximate location. Each event belongs to a session (sessionId), which Kustomer assigns when you don't provide one.

Identities

An identity links a trackingId to a customer. Kustomer matches on the trackingId, externalId, email or phone you send, then updates the customer with the other fields in the request (name, company, username, locale, timeZone, tags, custom and so on); new emails and phone numbers are added to the customer's existing lists. The response is an identity with the matched customer in relationships.customer. Its trackingId can differ from the one you sent if the person was already known, so use the returned value for later events.

Which endpoint to use

POST /v1/tracking/event returns 204 No Content; the identity endpoints return 201 with the identity. Each session in the sessions list has firstEventAt, lastEventAt and an event count. The deprecated all-events endpoint now returns 404 Not Found: read session events instead, or use conversation events for a conversation's history.