SMS Orchestrator — Event Schemas

Status: populated Owner: Platform Engineering Last updated: 2026-04-18 Companion: APPLICATION_LOGIC · DATA_MODEL

Event type format: {service}.{aggregate}.{event}.v{N} (see NAMING).

1. Consumed

Subject	Stream	Producer	Retention
sms.outbound.request	SMS_OUTBOUND	sms-orchestrator (HTTP accept path)	WorkQueue, 24h

sms.outbound.request.v1

interface OutboundSmsRequest {
  schemaVersion: '1';
  messageId: string;           // UUIDv4
  tenantId: string;
  accountId: string;
  to: string;                  // E.164
  from: string;
  body: string;
  messageType: 'SMS' | 'FLASH_SMS';
  segmentCount: number;
  enqueuedAt: string;          // ISO 8601
  callbackUrl?: string;
  metadata?: Record<string, string>;
}

NATS headers: Nats-Msg-Id = messageId, traceparent, X-Tenant-Id.

2. Produced

Subject	Stream	Consumer(s)	Retention
smpp.operator.{operatorId}	SMPP_OUTBOUND	smpp-connector	WorkQueue, 24h
sms.outbound.retry	SMS_RETRY	ops + analytics	Limits, 7d
sms.outbound.deadletter	SMS_DLQ	ops + remediation	Limits, 30d
sms.events.status	SMS_EVENTS	webhook-dispatcher, billing-service, analytics-service	Limits, 7d

smpp.operator.{operatorId}.v1

interface SmppOutboundMessage {
  schemaVersion: '1';
  messageId: string;
  tenantId: string;
  accountId: string;
  to: string;
  from: string;
  body: string;
  segmentCount: number;
  messageType: 'SMS' | 'FLASH_SMS';
  operatorId: string;
  routeId: string;
  routedAt: string;
  enqueuedAt: string;
  callbackUrl?: string;
  metadata?: Record<string, string>;
}

Headers: X-Correlation-ID = messageId, X-Operator-ID = operatorId, traceparent (propagated).

sms.outbound.retry.v1

interface SmsRetryEvent {
  schemaVersion: '1';
  messageId: string;
  tenantId: string;
  attempt: 1 | 2 | 3;
  reason: string;
  failedAt: string;
}

sms.outbound.deadletter.v1

interface SmsDeadLetterEvent {
  schemaVersion: '1';
  messageId: string;
  tenantId: string;
  accountId: string;
  to: string;
  from: string;
  body: string;
  attemptCount: number;
  failureReason: string;
  failedAt: string;
}

sms.events.status.v1

interface SmsStatusChangedEvent {
  schemaVersion: '1';
  messageId: string;
  tenantId: string;
  accountId: string;
  previousStatus: MessageStatus;
  newStatus: MessageStatus;
  at: string;
  operatorId?: string;
  reason?: string;
}

3. Retention Classes

Class	Subjects	Why
Operational	smpp.operator.*, sms.outbound.request, sms.outbound.retry	Drop after process
Regulated	sms.events.status	Billing audit trail — keep 7d then archive
Audit	sms.outbound.deadletter	Incident forensics — keep 30d

4. PII Policy

• Event payloads include destination MSISDN (to) and body — regulated content.
• Event streams are NOT exported raw to analytics (ClickHouse or Grafana) without PII scrub; downstream consumers responsible.
• No event body stored in Loki logs.