Skip to main content

​
Endpoint

POST /api/sdk/events
Send a batch of behavioral events (page views, clicks, form submissions, etc.) for tracking and analysis. Events are used by the AI’s awareness system to understand user behavior patterns.

​
Authentication

Requires your publishable widget key in the Authorization header: 
Authorization: Bearer ab_live_xxxxxxxxxxxxxxxx

​
Request Body

​
events
array
required
Array of event objects (max 100 per batch).
​
user_id
string
The user’s external ID. If provided, events are linked to the user record. The user is automatically upserted (created if new, updated with a fresh last_seen timestamp if existing).
​
session_id
string
Session identifier to group events.

​
Event Object

Each event in the array should have:
​
event_type
string
required
The type of event (e.g., "click", "page_view", "form_submit", "error").
​
element_selector
string
CSS selector of the element involved (for click events, etc.).
​
page_url
string
The URL where the event occurred.
​
metadata
object
Additional data about the event. Max 10,000 bytes per event.

​
Example

curl -X POST https://api.haloagents.ai/api/sdk/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ab_live_xxxxxxxxxxxxxxxx" \
  -d '{
    "user_id": "user_123",
    "session_id": "sess_abc123",
    "events": [
      {
        "event_type": "page_view",
        "page_url": "/settings/integrations",
        "metadata": { "referrer": "/dashboard" }
      },
      {
        "event_type": "click",
        "element_selector": "#connect-stripe-btn",
        "page_url": "/settings/integrations"
      }
    ]
  }'
Response: 
{
  "success": true
}

​
Notes

  • Events are collected automatically by the built-in tracker. You typically don’t need to call this endpoint directly unless building a custom integration.
  • The user record is created or updated (last seen timestamp) when user_id is provided.
  • Field lengths are sanitized: event_type is capped at 100 chars, element_selector at 500 chars, page_url at 2,000 chars, and session_id at 200 chars.