Sign in
Analytics

Record a widget or site analytics event

Records one visitor event (page view, widget open, message sent, identify, purchase) against a Clarm widget. Requests are proxied same-origin to the Clarm analytics service, which authenticates the caller from the widget token or widget id in the payload. Events for a visitor who has opted out should carry tracking_disabled: true, which is accepted and discarded.

post/api/track

Request body

eventstring required

Event name, for example page_view, widget_open, message_sent, identify, or purchase.

visitor_idstring required

Stable pseudonymous identifier for the visitor.

widget_idstring

Public widget identifier that authenticates the event when no token is supplied.

organization_idstring

Workspace the widget belongs to. Resolved server-side when omitted.

page_urlstring uri

URL the event happened on.

page_titlestring

Document title of that page.

referrerstring

Referrer of that page view.

timestampstring date-time

When the event happened. Defaults to receipt time.

user_agentstring

Client user agent. Defaults to the request header.

widget_sessionstring

Widget session identifier, when a widget is open.

chat_session_idstring

Conversation identifier, when a chat is running.

has_used_widgetboolean

Whether this visitor has interacted with the widget before.

tracking_disabledboolean

Set when the visitor opted out. The event is accepted and discarded.

dataobject

Event-specific payload, for example identify traits or purchase value.

Example request

{
  "event": "page_view",
  "visitor_id": "v_8f2c19a4",
  "widget_id": "1CwmcOQ75KJq"
}

Response

Event accepted, or discarded because the visitor opted out.

successboolean required

True when the event was accepted.

event_idstring

Identifier of the stored event.

goals_achievedinteger

How many configured goal rules this event satisfied.

tracking_authenticatedboolean

Whether the caller presented a verified widget token.

side_effects_suppressedboolean

Whether downstream integrations were skipped for this event.

messagestring

Human-readable confirmation.

Changes