Event System

Event System Overview

Event architecture from SDK to backend

Event Architecture

Two different "event" concepts in KYCIS:

Concept	Where	Meaning
Ingestion Event	`POST /v1/events` body field `event`	Analytics + session merge rules
Activity Stream	`GET /api/activity` → `items[].kind`	Dashboard grouping bucket

Event Flow

SDK Event
  ↓
POST /v1/events
  ↓
Backend Processing
  ↓
Session Store Update
  ↓
Activity Stream
  ↓
Dashboard / Voice Context

Activity Stream Kinds

`kind`	Produced When	Payload Highlights
`event`	Any `POST /v1/events`	Full event body + trace
`schema_push`	Screen schema processed	Schema hash, screen id
`trigger`	Trigger evaluation	Decision, reason, signals
`session_start`	Session start	Room, user, trace
`session_stop`	Session stop	User, trace
`reengagement`	With session stop	Recommended, channel, reason

Ingestion Event Types

All events require: user_id, session_id, event, timestamp

Optional shared fields: client_id, mapping_version, screen, screen_id, invoke_source, traceparent, trace_id, request_id, properties

Event Type Summary

Event	SDK Method	Purpose
`identity`	`AI.setUser()`	User identification
`error_reported`	`AI.trackError()`	Generic errors
`validation_failed`	`AI.trackValidationFailure()`	Field validation
`component_input`	`AI.reportComponentInput()`	Redacted input hints
`screen_schema`	`AI.registerScreenSchema()`	Full schema registry
`screen_schema_lazy`	Implicit	Minimal screen beacon
`voice_conversation_turn`	Voice agent	Conversation telemetry

Event Processing

Backend Ingestion (`POST /v1/events`)

Merge body trace fallbacks
store.upsert_event(payload_dict)
Create/update session by session_id
Push to activity feed with trace

Session State Updates

Events update in-memory session:

latest_event — full event payload
screen — from payload when present
user_id — from event
last_validation_failure — from validation_failed

Context Building

Voice agent context built from:

Session state (screen, errors, validation history)
KYC knowledge base (screen aliases, rules)
Component input hints (redacted)
Static system prompt

Trace Correlation

All events carry trace headers:

traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
X-Request-ID: req-123-456

Activity stream includes trace object for correlation.

Event Frequency Guidelines

Event	Frequency	Debounce
`identity`	Once per user session	—
`screen_schema`	Once per schema version	Lazy push on navigation
`component_input`	On meaningful changes	300-500ms recommended
`validation_failed`	On each failure	Immediate
`error_reported`	On each error	Immediate

Validation

Verify events in /api/activity:

Check kind matches expected
Verify payload.event type
Confirm trace fields present
Review session continuity

Assistant Entry UX

Voice assistant entry points and UI patterns

Sending Events

When and how to emit each event type

On this page

Event Architecture Event Flow Activity Stream Kinds Ingestion Event Types Event Type Summary Event Processing Backend Ingestion (POST /v1/events)Session State Updates Context Building Trace Correlation Event Frequency Guidelines Validation