Ingestion/Event Model

Unified Voice AI Event Model

Vendor-neutral canonical data model. Provider-specific fields are normalized; original raw payloads are retained for investigation.

Global call ID

zh_call_*

Maps to all provider call IDs in providerCallIds

Normalization

Adapter → CanonicalEvent

Webhook, SDK, OTel, batch, stream share one envelope

Raw retention

call.rawPayloads[]

Full provider payloads for forensic RCA

Core entities

TypeScript definitions in src/types/canonical.ts

OrganizationWorkspaceProjectEnvironmentVoice agentAgent versionProviderPhone numberCallParticipantAudio streamTranscriptUtteranceConversation turnTraceSpanLLM requestASR requestTTS requestTool callWorkflow stepEvaluationEvaluatorMetricScorecardAlertIncidentAnnotationDeploymentExperimentDatasetReportAPI keyWebhookIntegrationSubscriptionUsage recordAudit event

Call entity (excerpt)

interface CallEntity {
  id: string; // zh_call_* global internal ID
  organizationId: string;
  workspaceId: string;
  projectId: string;
  environment: "production" | "staging" | ...
  agentId: string;
  agentVersionId?: string;
  providerCallIds: Record<string, string>; // provider → external id
  sessionId?: string;
  sipCallId?: string;
  direction: "inbound" | "outbound" | "internal";
  from: string;
  to: string;
  fromMasked?: string;
  // ... timestamps, scores, cost, metadata
  rawPayloads?: Array<{ provider, receivedAt, payload }>;
}