Event Tracking & Analytics
The Events API provides transparency into how helpline information is displayed to and used by end users. This feature captures two discrete, timestamped signals to measure the user journey:ย
- helplineDisplay: Captures when a helpline is shown to a user.
- helplineClick: Captures when a user takes action to contact a helpline.
Key Benefits
- Billing Transparency: Provides transparency for ThroughLine and customers to ensure billing is based on verified usage data.
- Compliance & Impact Reporting: Through exportable analytics, simplifies reporting to regulators and stakeholders based on documented reach and user activity.
- Load Management: Allows ThroughLine to monitor and manage load across helplines to ensure service availability.
- Conversion Insights: Uses a unique identifier to calculate the click-through rate (CTR) from display to contact.
Data Flow
The following diagram illustrates how event data travels from your application to the ThroughLine analytics dashboard.
%%{init: {
"theme": "base",
"themeVariables": {
"fontFamily": "Lato, system-ui, sans-serif",
"fontSize": "15px",
"lineColor": "#9ba3aa",
"primaryTextColor": "#0f2027",
"clusterBkg": "#ffffff",
"clusterBorder": "#c2c9cc",
"edgeLabelBackground": "#ffffff"
},
"flowchart": {
"curve": "basis",
"nodeSpacing": 60,
"rankSpacing": 75,
"padding": 18,
"htmlLabels": true
}
}}%%
flowchart TB
client("<b>Client application</b><br/><span style='color:#5c6f77'>Partner system / 3rd-party integration</span>")
subgraph throughline[" ThroughLine systems "]
direction TB
display("<b>POST /v2/events/helplineDisplay</b><br/><span style='color:#5c6f77'>helplineId + sessionId + timestamp</span>")
clickEvt("<b>POST /v2/events/helplineClick</b><br/><span style='color:#5c6f77'>+ contactMethod required</span>")
dashboard("<b>Dashboard</b><br/><span style='color:#5c6f77'>Looker dashboard with CSV export</span>")
end
client -->|"Display"| display
client -->|"Click"| clickEvt
display --> dashboard
clickEvt --> dashboard
%% โโ ThroughLine brand styling โโ
classDef entry fill:#ede9e1,stroke:#d8d1c4,color:#0f2027,rx:12,ry:12;
classDef api fill:#eef4f6,stroke:#7bb5b9,color:#0f2027,rx:12,ry:12;
classDef dash fill:#dcebec,stroke:#2b8e94,color:#0f2027,stroke-width:1.5px,rx:12,ry:12;
class client entry;
class display,clickEvt api;
class dashboard dash;
style throughline fill:#fbfdfe,stroke:#c2c9cc,stroke-width:1.5px,stroke-dasharray:6 5;
%% coral for user-initiated events, teal for internal flow
linkStyle 0,1 stroke:#e8886c,stroke-width:2.5px;
linkStyle 2,3 stroke:#2b8e94,stroke-width:2.5px;Events Endpoints
These endpoints are used to report the two core signals. Detailed schemas are available in the API Referencethe API Reference.
Method | Endpoint | Required Parameters | Description |
|---|---|---|---|
POST | /v2/events/helplineDisplay | helplineId (string) ๏ปฟ sessionId (string) ๏ปฟ timestamp (ISO 8601) | Report when a helpline is displayed to a user. |
POST | /v2/events/helplineClick | helplineId (string) ๏ปฟ sessionId (string) ๏ปฟ timestamp (ISO 8601) ๏ปฟ contactMethod (enum) | Report when a user clicks a contact method for a helpline. |
Parameter Definitions
The Events API utilizes two primary identifiers to link these signals:
- helplineId: This string must match the unique ID for the helpline entity retrieved from the /helplines endpoint.
- sessionId: An opaque string provided by the client to link a "display" event to a "click" event.
- Flexibility: You may use any identifier you prefer, such as a GUID or a hashed string.
- Consistency: The ID must remain unique and consistent for the duration of a single user session to allow for accurate conversion rate calculations.
- Anonymity: Because this ID is partner-provided and contains no PII, it ensures user anonymity while still providing measurable impact tracking.
Contact Method Values
The contactMethod field is an enum used to report which specific channel a user chose to contact.
๏ปฟ๏ปฟcontact_method๏ปฟ๏ปฟ | ๏ปฟ๏ปฟDescription๏ปฟ๏ปฟ |
|---|---|
phone | Phone call |
sms | SMS / text message |
onlineChat | Online chat |
website | Visit to the website |
tty | TTY / relay call |
reportingForm | Online reporting form |
Privacy & Quota Information
- No Personal Data: No personally identifiable information is collected at any stage.
- Service-Level Data: Events record what happened (helpline ID), how (click), and when (timestamp). Never who.
- Quota Exemption: Event API calls do not count against the standard API display quota.
Batch Upload
We also support batch event uploads, which is useful if youโre unable to deliver events in real-time. This is an asynchronous process, consisting of an initial upload followed by a status poll:
Method | Endpoint | Body content | Description |
|---|---|---|---|
POST | /v2/events/batch | An array of helplineDisplay and helplineClick events. | Upload up to 1M/150MiB of events (whichever is smaller) and receive a job ID. |
GET | /v2/events/batch/jobs/:jobId | None | Get the in-progress status or the terminal result. |
Once the job is complete, the status payload will tell you how many events were valid, how many failed validation, and what was wrong with each of them. More details are available in the API Referencethe API reference.
By default, valid events are stored and invalid events are rejected; you should investigate and fix the failures and then re-submit them individually. Itโs important in this default mode that you donโt re-submit events that were accepted, as they will cause duplication in your reporting.
However if youโd prefer, you can specify on upload that the batch be treated atomically: in this mode, even one failure will reject storage of the entire batch, allowing you to fix the errors and then resubmit the entire payload without risk of duplication.