Analytics Events (MVP)

This document defines recommended analytics instrumentation conventions.

Page docs should list relevant events and link here.

Principles

• Track activation and value moments (connection completed, first reply sent, first KB published).
• Include workspace/org identifiers (non-PII, internal IDs).
• Avoid logging message content or PII in event payloads.

Suggested global events

• auth.sign_in.success
• auth.sign_in.failure
• workspace.created
• workspace.switched
• kb.created
• kb.published
• channel.connected
• channel.disconnected
• comment_responder.reply.generated
• comment_responder.reply.sent
• chatti_live.conversation.assigned
• billing.plan_changed

Dashboard enablement events (future)

These events are recommended when the platform begins turning the Dashboard customer-signals concept into real analytics.

They exist to support future dashboard aggregates and should be implemented only with strict scope, privacy, and governance controls.

Signal events

• customer_signal.detected
  • A message, review, or comment has been classified into a dashboard-relevant signal bucket
• customer_signal.severe_negative_detected
  • A high-risk negative expression has been identified
• customer_signal.success_detected
  • A praise or success-oriented signal has been identified
• customer_signal.theme_clustered
  • A signal has been grouped into a dashboard-relevant friction or opportunity theme

Suggested optional payloads:

• channel_type
• app_surface
• signal_type
• severity
• theme_id

System and triage events

• ai_triage.completed
  • The system has classified and routed an inbound item
• ai_triage.escalation_triggered
  • The item was escalated to human review or a protected workflow
• ai_reply.generated
  • A candidate reply was generated
• ai_reply.sent
  • A reply was actually sent
• ai_reply.kb_gap_detected
  • A missing or weak knowledge signal affected confidence or reply quality

Suggested optional payloads:

• triage_result
• confidence_band
• escalation_reason
• reply_mode (auto, assisted, human)
• kb_gap_type

Outcome events

• interaction.outcome_resolved
  • The issue appears to have been resolved
• interaction.outcome_recovered
  • A previously negative interaction appears to have improved
• interaction.outcome_reopened
  • The issue returned after an apparent resolution
• interaction.outcome_handoff_completed
  • Human escalation completed successfully

Suggested optional payloads:

• outcome_type
• previous_signal_type
• time_to_resolution_ms
• handoff_target
• resolution_path

Dashboard event priorities

Minimum required for first real dashboard analytics

• customer_signal.detected
• customer_signal.severe_negative_detected
• customer_signal.theme_clustered
• ai_triage.completed
• ai_triage.escalation_triggered
• ai_reply.kb_gap_detected

Required before outcome metrics become trustworthy

• interaction.outcome_resolved
• interaction.outcome_recovered
• interaction.outcome_reopened
• interaction.outcome_handoff_completed

Dashboard event to metric mapping

Dashboard metric / module	Minimum event inputs
Dissatisfaction detected	customer_signal.detected with signal_type=dissatisfaction
Severe negative count	customer_signal.severe_negative_detected
Top friction themes	customer_signal.theme_clustered
Escalated for human review	ai_triage.escalation_triggered
Auto / assisted / escalated handling split	ai_triage.completed, ai_reply.sent
KB gaps affecting replies	ai_reply.kb_gap_detected
Resolved / recovered	interaction.outcome_resolved, interaction.outcome_recovered
Reopened issues	interaction.outcome_reopened
Successful human handoff	interaction.outcome_handoff_completed

Payload guidelines

• Required: org_id, workspace_id, user_id (internal), timestamp
• Optional: channel_type, app_surface, result, error_code

Dashboard-oriented optional fields:

• signal_type
• severity
• theme_id
• confidence_band
• triage_result
• reply_mode
• kb_gap_type
• outcome_type
• time_to_resolution_ms