Skip to main content

smpp-connector — Event Schemas

Status: populated | Last updated: 2026-04-18

1. Consumed Events​

1.1 SmsDispatchCommand​

NATS Subject: smpp.operator.{operatorId} Published by: sms-orchestrator

interface SmsDispatchCommand {
  /** Schema version */
  version: '1.0';

  /** Unique event identifier (UUID v4) */
  eventId: string;

  /** Internal message UUID (from sms-orchestrator) */
  messageId: string;

  /** Destination E.164 number */
  to: string;

  /** Source address / sender ID */
  from: string;

  /** Message text (UTF-8) */
  text: string;

  /** Resolved SMPP operator to use */
  operatorId: string;

  /** Account that owns this message */
  accountId: string;

  /** Message type */
  messageType: 'SMS' | 'FLASH';

  /** Character encoding to use */
  encoding: 'GSM7' | 'UCS2';

  /** How to handle messages exceeding single PDU capacity */
  longMessageStrategy: 'CSMS' | 'TLV';

  /** ISO 8601 — when sms-orchestrator enqueued this message */
  enqueuedAt: string;

  /** ISO 8601 — message expiry; do not transmit after this time */
  expiresAt: string;
}

2. Published Events​

2.1 DlrInboundEvent​

NATS Subject: sms.dlr.inbound Consumed by: dlr-processor

interface DlrInboundEvent {
  /** Schema version */
  version: '1.0';

  /** Unique event identifier (UUID v4) */
  eventId: string;

  /** ISO 8601 — when the DLR was received */
  occurredAt: string;

  /** Internal message UUID (looked up via MessageCorrelation) */
  messageId: string;

  /** MNO-assigned message ID from submit_sm_resp */
  operatorMessageId: string;

  /** Operator that delivered the DLR */
  operatorId: string;

  /** SMPP message_state mapped to internal enum */
  status: DlrStatus;

  /** ISO 8601 — MNO reported delivery time, if present */
  deliveredAt: string | null;

  /** Raw SMPP error code, if any (e.g. 099 = Absent Subscriber) */
  smppErrorCode: string | null;
}

type DlrStatus =
  | 'DELIVERED'
  | 'UNDELIVERABLE'
  | 'EXPIRED'
  | 'DELETED'
  | 'ACCEPTED'
  | 'UNKNOWN'
  | 'REJECTED';

Example payload:

{
  "version": "1.0",
  "eventId": "b1c23d44-0002-4a1b-9c8d-abcdef123456",
  "occurredAt": "2026-04-18T10:35:00.000Z",
  "messageId": "msg-0000-0001-0002-0003",
  "operatorMessageId": "7984321",
  "operatorId": "550e8400-e29b-41d4-a716-446655440001",
  "status": "DELIVERED",
  "deliveredAt": "2026-04-18T10:34:58.000Z",
  "smppErrorCode": null
}

2.2 OperatorHealthEvent​

NATS Subject: operator.health Consumed by: routing-engine, operator-management-service

interface OperatorHealthEvent {
  /** Schema version */
  version: '1.0';

  /** Unique event identifier (UUID v4) */
  eventId: string;

  /** ISO 8601 — when the event was emitted */
  occurredAt: string;

  /** Internal UUID of the operator whose session changed */
  operatorId: string;

  /** Human-readable operator name */
  operatorName: string;

  /** New session health status */
  status: 'BOUND' | 'UNBOUND' | 'FAILBACK';

  /** Previous session health status */
  previousStatus: 'BOUND' | 'UNBOUND' | 'FAILBACK' | null;

  /** Optional human-readable reason for state change */
  reason?: string;
}

Example payload (UNBOUND):

{
  "version": "1.0",
  "eventId": "c2d34e55-0003-4b2c-0d9e-bcdef2345678",
  "occurredAt": "2026-04-18T10:40:00.000Z",
  "operatorId": "550e8400-e29b-41d4-a716-446655440001",
  "operatorName": "Roshan-AF",
  "status": "UNBOUND",
  "previousStatus": "BOUND",
  "reason": "enquire_link timeout after 10s"
}