SMS

1xBTS delivers SMS between local subscribers and can exchange messages with other networks through an SMPP hub. Local messaging works without a hub or a SIP trunk.

Local messaging

Add each handset in Subscribers with its phone number and IMSI plus ESN or MEID. Confirm that the handset registers, then send a message to another subscriber’s phone number. You can also send from the web dashboard.

The SMSC stores messages in PostgreSQL and retries delivery when a known recipient is offline. Leave the HLR, SMSC, MSC, and serving base station running. The integrated cdma-nib launcher starts the SMSC by default. If you select components explicitly, include --component cdma-smsc.

Connect to an SMPP hub

Choose whether 1xBTS connects and binds to an SMPP server or listens for an incoming bind. Match the system ID and password at both ends, and configure the hub to route your local subscribers’ numbers to this site.

To exchange messages with other 1xBTS networks over the internet, use the hub that 1xBTS hosts. Sign up at the 1xBTS Registry to get connected.

Configuration	Connection
`role: "client"`	1xBTS connects and binds to the server at `hub_addr`.
`role: "server"`	1xBTS listens at `bind_addr` and accepts the hub’s bind.

Connect and bind to a server

Add this block to config/smsc.local.json, replacing the example address and credentials:

{
  "smpp": {
    "role": "client",
    "hub_addr": "192.0.2.10:2775",
    "system_id": "your-site",
    "password": "replace-with-your-password"
  }
}

Listen for an incoming bind

If the hub connects to your site, use this instead:

{
  "smpp": {
    "role": "server",
    "bind_addr": "0.0.0.0:2775",
    "system_id": "your-site",
    "password": "replace-with-your-password"
  }
}

Allow the hub to reach your selected TCP port. The system ID and password must match the credentials the hub uses to bind. SMPP uses plain TCP, so use a private network or VPN for this connection.

Restart the SMSC, or restart cdma-nib if it runs your components together. Look for interconnect bound in the logs to confirm the connection is ready. The link reconnects automatically after a disconnect.

smsc.local.json is gitignored. Keep credentials there instead of editing the shared smsc.json. Omit the smpp block for local-only messaging, or set "smpp": null in the local override to disable an existing configuration.

Test both directions

Send from a local handset to a number assigned to another site on the hub.
Check the message history. A successfully accepted outbound message reaches forwarded.
Send a reply from the other site to your handset’s assigned number and confirm it arrives.

A local subscriber always takes priority over a hub route. A number that is not local goes to the configured hub. Incoming hub messages are delivered only to local subscribers and are never sent back to the hub.

Delivery and retries

State	Meaning
`accepted`	Stored and waiting for delivery or retry.
`paging` / `page_response_received`	A local delivery attempt is in progress.
`delivered`	The serving network reported a delivery acknowledgment.
`forwarded`	The hub accepted responsibility for delivery. This does not confirm receipt on the remote handset.
`failed`	Delivery stopped with a permanent error. Check the recorded failure reason.

Temporary connection failures and unreachable local handsets are retried. Pending messages survive SMSC restarts, and interrupted attempts become eligible for retry. Once the hub accepts a message, 1xBTS stops retrying it locally.

The default retry scan runs every 10 seconds, with at least 10 seconds between failed attempts. An attempt with no outcome becomes eligible for recovery after 120 seconds. Configure these under sweep in smsc.local.json. See the configuration reference for all settings.

Troubleshooting

Symptom	Check
No `interconnect bound` log	Connection role, TCP reachability, system ID, and password.
Outbound message stays `accepted`	Hub connectivity, recipient registration for local messages, and whether `sweep.enabled` is true.
Unknown destination with no interconnect	Add the destination as a local subscriber or configure the SMPP hub.
Hub reply cannot reach a handset	The hub’s route to your site, the local subscriber’s assigned number, and handset registration.
Message is `forwarded` but not received	Check delivery at the hub and destination site. Local acceptance is not a remote handset receipt.

MMS notifications

The same SMS service delivers WAP Push notifications for MMS. Configure the MMS service to enable picture messaging.

Welcome SMS

The configurable welcome SMS policy sends a message to mobiles that are new to the network or have been inactive longer than the configured threshold. Registration handling records each mobile in the HLR mobiles_seen ledger, resolves subscriber state, and injects the welcome message through the normal SMSC delivery path.

In config/msc.local.json:

{
  "welcome_sms": {
    "enabled": true,
    "text": "Welcome to 1xBTS!",
    "originating_number": "0000",
    "inactive_days_threshold": 30
  }
}

Sending via API

Run from the 1xBTS checkout:

grpcurl -plaintext -import-path proto -proto msc_management/v1/service.proto -d '{
  "destination_mdn": "5551234567",
  "message": "Hello from 1xBTS!"
}' localhost:17017 msc_management.v1.MscManagementService/SendSms

bsc.v1.BscService/SendSms on :17016 remains as a compatibility entry point for existing tooling; it forwards to MSC under the hood.