smpp-connector — API Contracts

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

smpp-connector is not fronted by Kong Gateway. It has no public HTTP API. Its primary interface is NATS JetStream (inbound consumption + outbound publication) and SMPP 3.4 (external MNO sessions).

1. NATS Subjects

1.1 Consumed Subjects

Subject	Stream	Consumer group	Payload type
`smpp.operator.{operatorId}`	`SMS_DISPATCH`	`smpp-connector-{operatorId}`	`SmsDispatchCommand`

The subject is parameterised by operatorId (UUID). Each smpp-connector instance subscribes only to subjects for its assigned operators.

1.2 Published Subjects

Subject	Stream	Payload type	Trigger
`sms.dlr.inbound`	`DLR_EVENTS`	`DlrInboundEvent`	MNO sends `deliver_sm` DLR PDU
`operator.health`	`OPERATOR_EVENTS`	`OperatorHealthEvent`	Session state changes (BOUND/UNBOUND/FAILBACK)

2. Internal HTTP API (Management Only)

Served on port 3001. Not routed through Kong.

Method	Path	Description
`GET`	`/health`	Liveness probe
`GET`	`/ready`	Readiness probe — checks SMPP session and Redis
`GET`	`/metrics`	Prometheus metrics scrape
`GET`	`/sessions`	Returns current SMPP session states (internal ops use)

GET /sessions — Response

{
  "sessions": [
    {
      "operatorId": "550e8400-e29b-41d4-a716-446655440001",
      "operatorName": "Roshan-AF",
      "state": "BOUND",
      "bindMode": "TRANSCEIVER",
      "lastBoundAt": "2026-04-18T10:00:00.000Z",
      "reconnectAttempts": 0
    }
  ]
}

3. Dependency: operator-management-service Internal API

smpp-connector calls this endpoint to retrieve credentials before each bind attempt.

GET /internal/operators/{operatorId}/smpp-credentials
Authorization: Bearer {internal-service-token}

Response 200:
{
  "operatorId": "550e8400-...",
  "host": "smpp1.roshan.af",
  "port": 2775,
  "systemId": "smsgtw01",
  "password": "s3cr3t",       ← only transmitted over mTLS; never logged
  "tpsLimit": 100,
  "bindMode": "TRANSCEIVER",
  "backupOperatorId": "550e8400-...-0002"  ← null if no backup
}

The password field is fetched from HashiCorp Vault by operator-management-service and proxied to smpp-connector over an internal mTLS connection. smpp-connector holds the password only in memory for the duration of the bind attempt.

4. SMPP 3.4 PDU Interface (External — MNO)

PDU type	Direction	Purpose
`bind_transceiver`	→ MNO	Establish full-duplex session
`bind_transceiver_resp`	← MNO	Confirm bind
`bind_transmitter`	→ MNO	Fallback TX-only bind
`bind_receiver`	→ MNO	Fallback RX-only bind
`submit_sm`	→ MNO	Send outbound SMS
`submit_sm_resp`	← MNO	Confirm PDU received; contains `message_id`
`deliver_sm`	← MNO	Inbound DLR receipt
`deliver_sm_resp`	→ MNO	Acknowledge DLR received
`enquire_link`	→ MNO	Heartbeat ping every 30 s
`enquire_link_resp`	← MNO	Heartbeat pong
`unbind`	↔ MNO	Graceful session teardown
`unbind_resp`	↔ MNO	Confirm unbind

1. NATS Subjects​

1.1 Consumed Subjects​

1.2 Published Subjects​

2. Internal HTTP API (Management Only)​

GET /sessions — Response​

3. Dependency: operator-management-service Internal API​

4. SMPP 3.4 PDU Interface (External — MNO)​