Sending SMS over SMPP

Who SMPP is for

Use SMPP if you already run an SMS gateway or an SMPP client and want to keep one open connection to Sendozi. Everything else can use the HTTP API, which needs no persistent connection.

A message sent over SMPP passes the same checks as one sent over the HTTP API: approved KYC, a Sender ID approved on the route, a funded wallet, opt-outs and Do Not Disturb, and for transactional traffic the approved templates. It is priced and charged the same way, and it appears in the Console under Messages like any other send. There is no sandbox over SMPP: every accepted message is live.

Getting an SMPP account

1. 1

   Get your workspace ready

   KYC approved, the wallet funded, and a Sender ID approved on the route you will send on. For transactional traffic, the Sender ID also needs approved templates; see Transactional SMS.

2. 2

   Ask Sendozi for an account

   SMPP accounts are created by Sendozi, not in the Console. Send your workspace name, the fixed public IP addresses your SMPP client connects from, and whether the account is for transactional or promotional traffic.

3. 3

   Receive the connection details

   The workspace owner receives an email from support@sendozi.com with the host, port, system ID, password, route, bind limit, messages per second and your allowed IPs. Keep the password private; if it is ever exposed, reply to that email and Sendozi will reset it.

4. 4

   Connect and test

   Bind from one of your allowed IPs, send a message to your own phone, and check that its delivery receipt arrives. Your allowed IPs are admitted within a minute of the account being created.

Connection settings

After 10 failed binds in 15 minutes from one system_id or one address, further binds are refused without being checked. A wrong system_id and a wrong password get the same answer.

Sending a message: submit_sm

A submit_sm_resp with command_status 0 means the message is queued, not delivered. Its message_id is 16 hexadecimal characters, and the delivery receipt carries the same id: store it as a string. Live promotional messages accepted outside 08:30 to 19:30 WAT are queued and sent when the window opens; transactional messages go at any hour.

Transactional accounts

• Every message must be one of the Sender ID's approved transactional templates, with its variables filled in. Sendozi matches the text to the template itself, so there is no template_id to send.
• The matched template's event type is used, and each message counts as its own event.
• Text that matches no approved template is refused with 0x00000402.
• The Sender ID's per-minute and daily transactional limits apply; past them, submit_sm is refused with ESME_RTHROTTLED (0x00000058).

Long messages

• Send a long message as parts with a concatenation header (8-bit reference, IEI 0x00, or 16-bit, IEI 0x08), as parts with the sar_msg_ref_num, sar_total_segments and sar_segment_seqnum parameters, or whole in message_payload.
• Each part is answered with its own message_id and gets its own delivery receipt. The message is sent, and priced and charged as one message, when its last part arrives.
• All parts must arrive within a minute. If they do not, nothing is sent or charged, and the parts already answered receive UNDELIV receipts with err 011 (when receipts were asked for).
• If a message is refused after its first parts were answered, those parts receive UNDELIV receipts with the reason in err.
• The whole message may be up to 1000 characters of GSM text, or 469 with Unicode characters. Longer messages are refused with ESME_RSUBMITFAIL (0x00000045).

Delivery receipts

A receipt is a deliver_sm with esm_class 0x04, sent on a transceiver or receiver bind. Its source_addr is the recipient's number and its destination_addr is your Sender ID. It carries the receipted_message_id and message_state parameters, and this text, with dates as YYMMDDhhmm in WAT:

id:3f9a1c0b7d2e4a68 sub:001 dlvrd:001 submit date:2609261432 done date:2609261432 stat:DELIVRD err:000 text:

• Answer every receipt with deliver_sm_resp status 0. A receipt that is not acknowledged is sent again 30 seconds later.
• Receipts wait for you while no receiver bind is open, and are dropped if not collected within 72 hours.
• A message with no report from the network within 72 hours gets an EXPIRED receipt with err 010.

Status codes

Examples

Most SMS gateways and platforms only need the settings above entered as a new SMSC connection. If you are writing your own client, these show a bind, a submit_sm and receipt handling. Use the host, system ID and password from your email.

const smpp = require("smpp");

const session = smpp.connect({ url: "smpp://smpp.sendozi.com:2775", auto_enquire_link_period: 30000 });

session.bind_transceiver({ system_id: process.env.SMPP_SYSTEM_ID, password: process.env.SMPP_PASSWORD }, (bind) => {
  if (bind.command_status !== 0) return console.error("Bind refused:", bind.command_status);

  session.submit_sm({
    source_addr: "AcmeBank", source_addr_ton: 5, source_addr_npi: 0,
    destination_addr: "2348012345678", dest_addr_ton: 1, dest_addr_npi: 1,
    registered_delivery: 1,
    // Text longer than one SMS: send it in message_payload, or split it with a UDH.
    short_message: "Your code is 482913. It expires in 10 minutes.",
  }, (resp) => {
    if (resp.command_status === 0) console.log("Queued:", resp.message_id);
    else console.error("Refused: 0x" + resp.command_status.toString(16));
  });
});

// Receipts arrive on the same bind. Acknowledge every one.
session.on("deliver_sm", (pdu) => {
  console.log("Receipt for", pdu.receipted_message_id, pdu.short_message.message);
  session.send(pdu.response());
});

import os
import smpplib.client
import smpplib.consts
import smpplib.gsm

client = smpplib.client.Client("smpp.sendozi.com", 2775)
client.set_message_sent_handler(lambda pdu: print("Queued:", pdu.message_id))
client.set_message_received_handler(lambda pdu: print("Receipt for", pdu.receipted_message_id))

client.connect()
client.bind_transceiver(system_id=os.environ["SMPP_SYSTEM_ID"], password=os.environ["SMPP_PASSWORD"])

# make_parts splits long text and adds the concatenation header.
parts, encoding_flag, msg_type_flag = smpplib.gsm.make_parts("Your code is 482913. It expires in 10 minutes.")
for part in parts:
    client.send_message(
        source_addr_ton=smpplib.consts.SMPP_TON_ALNUM,
        source_addr_npi=smpplib.consts.SMPP_NPI_UNK,
        source_addr="AcmeBank",
        dest_addr_ton=smpplib.consts.SMPP_TON_INTL,
        dest_addr_npi=smpplib.consts.SMPP_NPI_ISDN,
        destination_addr="2348012345678",
        short_message=part,
        data_coding=encoding_flag,
        esm_class=msg_type_flag,
        registered_delivery=True,
    )

client.listen()

Not offered over SMPP

• query_sm, cancel_sm, replace_sm, submit_multi and data_sm are answered with ESME_RINVCMDID. Look a message up, or cancel a queued send, in the Console or over the HTTP API.
• Replies from handsets are not delivered.
• There is no sandbox: test with a real message to your own phone.