analytics

Record a foreground usage-session event

post/api/analytics/usage-sessions/events

Request body

event_idstring uuid required

Client-generated idempotency UUID for this event

session_idstring uuid required

UUID shared by start, heartbeat and end

event_type'start' | 'heartbeat' | 'end' required

occurred_atstring date-time required

Timezone-aware client timestamp

channel'native_app' | 'web'

Delivery channel used for an app-open event.

platform'ios' | 'android' | 'web'

Runtime platform used for an app-open event.

form_factor'mobile' | 'tablet' | 'desktop'

Physical device class used for an app-open event.

app_versionstring nullable

device_idstring uuid nullable

Required on start; reuse the native chat device UUID

Example request

{
  "app_version": "2.5.0",
  "channel": "native_app",
  "device_id": "8ec8e128-c659-4f91-b230-d19b57c8392d",
  "event_id": "b02bdff8-93fd-445b-b11b-9bd75db6d93d",
  "event_type": "start",
  "form_factor": "mobile",
  "occurred_at": "2026-08-27T10:15:00Z",
  "platform": "ios",
  "session_id": "cf1064f2-b040-4698-b48a-880764778bc1"
}

Response

Successful Response

event_idstring uuid required

session_idstring uuid required

event_type'start' | 'heartbeat' | 'end' required

recorded_atstring date-time required

foreground_secondsinteger required

status'active' | 'ended' required

createdboolean required

False when event_id was already processed

Changes

No recorded changes to this endpoint across all 2 revisions of this API.