SMPP v3.4 connectivity

SMPP (Short Message Peer-to-Peer) is the telecom protocol for exchanging SMS over a persistent TCP connection. We accept SMPP v3.4 binds over TLS for high-volume SMS, with the same routes as the REST API.

SMPP or REST?#

You can use both on one account: REST for multichannel and application traffic, SMPP for high-volume SMS.

Provisioning a bind#

SMPP access is set up by our team rather than self-served. When you request access, tell us your destination countries, sender IDs, expected peak throughput and the public IP addresses you will connect from. You receive:

Resellers and wholesale partners can have dedicated binds.

Bind types#

Use a single transceiver bind per connection unless your SMPP client requires separate transmitter and receiver sessions.

Session lifecycle#

1. Open a TLS connection to the host and port you were given.
2. Send bind_transceiver with your system_id and password, and wait for bind_transceiver_resp with command_status 0.
3. Submit messages with submit_sm. Each submit_sm_resp returns the message_id.
4. Receive delivery receipts as deliver_sm and answer every one with deliver_sm_resp.
5. Send enquire_link about every 30 seconds while idle, and reconnect if responses stop.
6. Close with unbind and wait for unbind_resp.

submit_sm_resp only means the message was accepted for delivery. The final outcome arrives later in the delivery receipt.

submit_sm essentials#

Encoding#

One character outside GSM-7 means the whole message must be sent as UCS-2.

Concatenation (long messages)#

Messages longer than one segment are split into parts that the handset reassembles. You can do this in one of two ways:

• Segment it yourself. Send each part as its own submit_sm whose short_message starts with a 6-octet User Data Header (reference number, total parts, part number), and set esm_class to 0x40. The header is why parts hold 153 or 67 characters.
• Send it whole in the message_payload TLV and let the SMSC segment it. Confirm with our team that this is enabled on your bind before relying on it.

Use the same reference number for all parts of a message and a new one for each new message.

Delivery receipts#

When you set registered_delivery to 1, the receipt arrives as a deliver_sm with the receipt bit (0x04) set in esm_class. The text follows the common SMPP receipt format:

id:2603121407537573731 sub:001 dlvrd:001 submit date:2610100914 done date:2610100915 stat:DELIVRD err:000 text:Your OmniDemo code

id matches the message_id from submit_sm_resp. Where present, the receipted_message_id TLV (0x001E) carries the same ID and is easier to parse than the text.

Always answer deliver_sm with deliver_sm_resp. Unacknowledged receipts are re-sent and can lead to throttling of the bind.

Throughput and windowing#

SMPP is asynchronous: you can send several submit_sm PDUs before the responses arrive. The number of unacknowledged PDUs in flight is your window.

• A window of 1 (waiting for each response) is the most common cause of low throughput.
• The documented default is 1,000 messages per second per bind with a window of 100 outstanding submit_sm. Your account's limits are confirmed with your credentials.
• If you receive ESME_RTHROTTLED, slow down and retry with exponential backoff.
• On disconnect, reconnect with backoff and jitter, not in a tight loop, and track outstanding sequence numbers so you can reconcile receipts.
• Higher aggregate throughput comes from more binds, up to the number agreed for your account.

Common command_status codes#

Example session#

This sketch uses the open-source smpp package for Node.js. Any SMPP v3.4 client library (for example jSMPP for Java or python-smpplib) follows the same steps.

import smpp from "smpp";

// Host, TLS port and credentials come with your bind.
const session = smpp.connect({
  url: `ssmpp://${process.env.SMPP_HOST}:${process.env.SMPP_TLS_PORT}`,
  auto_enquire_link_period: 30000,
});

session.bind_transceiver(
  { system_id: process.env.SMPP_SYSTEM_ID, password: process.env.SMPP_PASSWORD },
  (bindResp) => {
    if (bindResp.command_status !== 0) throw new Error(`bind failed: ${bindResp.command_status}`);

    session.submit_sm(
      {
        source_addr_ton: 5,
        source_addr_npi: 0,
        source_addr: "OmniDemo",
        dest_addr_ton: 1,
        dest_addr_npi: 1,
        destination_addr: "447700900123",
        registered_delivery: 1,
        short_message: "Your OmniDemo code is 482913",
      },
      (resp) => console.log("accepted", resp.message_id),
    );
  },
);

session.on("deliver_sm", (pdu) => {
  if (pdu.esm_class & 0x04) console.log("receipt", pdu.short_message.message);
  session.send(pdu.response()); // always acknowledge
});

Check your library's documentation for its TLS URL scheme and encoding options; option names differ between libraries.

Next steps#

• Errors and limits: default limits for REST and SMPP.
• SMS API: the REST alternative, with bulk jobs and lookup.
• Webhooks: delivery statuses for REST traffic.