Skip to content

Script API

Everything your handler script can call, imported from the smpp namespace:

from siphon import smpp, cache, log

There are four kinds of thing here: decorators that register handlers, the objects handlers receive (Pdu, Bind, Session, AlertNotification), the send helpers that push PDUs out, and config readouts. Handlers are async def and are resolved from the registry on every PDU, so edits hot-reload.

Decorators

@smpp.on_bind

Authorises an inbound bind. Receives a Bind; return bind.accept() or bind.reject(status, reason). A bare truthy/falsy return also works.

@smpp.on_bind
async def authorise(bind):
    expected = await cache.get(f"esme_pw:{bind.system_id}")
    if expected is None:
        return bind.reject("ESME_RINVSYSID", f"unknown system_id {bind.system_id!r}")
    if bind.password != expected:
        return bind.reject("ESME_RINVPASWD", "bad password")
    return bind.accept()

Closed by default

With no @smpp.on_bind handler registered, all binds are rejected. You must opt ESMEs in.

@smpp.on_pdu("<command>")

Registers a handler for an inbound PDU command. The handler receives (pdu, session). Supported commands:

submit_sm, submit_sm_multi, deliver_sm, data_sm, cancel_sm, query_sm, replace_sm, alert_notification.

@smpp.on_pdu("submit_sm")
async def on_submit(pdu, session):
    return pdu.reply(message_id="abc123")

For alert_notification the first argument is an AlertNotification, not a Pdu. If no handler is registered for a command, the default applies.

@smpp.on_session("bound" | "unbound")

Fires on session lifecycle transitions, for both inbound ESMEs and outbound binds. Receives a Session. Use it to maintain your system_id → session_id map so you can MT-deliver back later.

@smpp.on_session("bound")
async def bound(session):
    if session.kind == "esme":
        await cache.set(f"esme_session:{session.system_id}", session.session_id)

@smpp.on_session("unbound")
async def unbound(session):
    if session.kind == "esme":
        await cache.delete(f"esme_session:{session.system_id}")

Objects

Pdu

The script-side view of an SMPP message, mirroring the SMPP 3.4 fields. Common fields:

Field Type Notes
source_addr / destination_addr str Addresses.
source_addr_ton / source_addr_npi int Type-of-number / numbering-plan.
dest_addr_ton / dest_addr_npi int Same for the destination.
short_message bytes The message payload (raw bytes, not decoded text).
esm_class int ESM class bits (0x04 = delivery receipt, etc.).
data_coding int DCS.
registered_delivery int Whether the sender wants a receipt.
service_type str Service type (§5.2.11); empty for the default.
priority_flag int Priority level (§5.2.14).
validity_period str How long the message stays valid, in the SMPP time format (§7.1.1, absolute or relative); empty for the SMSC default.
schedule_delivery_time str When to first attempt delivery, same format; empty for immediate.
replace_if_present_flag int 1 asks for a pending message with the same addresses to be replaced.
sm_default_msg_id int Index of a canned SMSC message; 0 when unused.
message_id str Present on responses / management PDUs.
destinations list submit_sm_multi only — the address list.
is_dlr bool deliver_sm only — true if it's a delivery receipt.
receipt dict | None deliver_sm only — the parsed receipt (below).
is_tpdu bool Whether the payload looks like a GSM TPDU.

Replies (return the result from your handler):

Call Effect
pdu.reply(message_id="…") Accept with a message id (ESME_ROK).
pdu.reply(command_status="ESME_RSUBMITFAIL") Reject with a status.
pdu.reply() or returning None Default ESME_ROK ack.
pdu.reply_query(message_state=…, final_date=…, error_code=…) Answer a query_sm.

command_status is what goes on the wire, and it alone decides between accept and reject: a message_id passed together with a reject status does not turn the rejection into an acceptance. Any status name from SMPP 3.4 Table 5-2 is accepted. Unknown status strings raise immediately, so a typo fails fast rather than silently sending the wrong status.

The validity and scheduling fields are carried by submit_sm, submit_sm_multi and replace_sm (which has no replace_if_present_flag). A deliver_sm has them in its layout too, but SMPP 3.4 §4.6.1 requires them NULL there, so expect them empty. They are empty / 0 on the other commands.

The receipt dict (for deliver_sm where is_dlr):

{ "id": "...", "stat": "DELIVRD", "err": "000",
  "submit_date": "...", "done_date": "...", "text": "...", "raw": "..." }

Bind

Passed to @smpp.on_bind.

Field / method Meaning
system_id The ESME's claimed identity.
password The bind password to verify.
client_addr The peer's network address (for allow-listing / logging).
bind.accept() Accept the bind.
bind.reject(status, reason) Reject; reason is logged.

Session

Passed to session/PDU handlers.

Field Meaning
kind "esme" (an inbound ESME) or "bind" (one of your outbound binds).
session_id Stable id for the session; the target for deliver_to / data_to / alert_to.
system_id The peer's system id.
client_addr The peer's network address.

AlertNotification

First argument to @smpp.on_pdu("alert_notification"). Carries source_addr (and TON/NPI) of the now-available MS, and esme_addr. It's a notification — there's nothing to reply.

Send helpers

All send helpers are awaitable. Outbound helpers target an outbound bind by bind= name; inbound helpers target a bound ESME by session_id=. Most return an SmppResp; query_via returns a QueryResp.

Outbound — to an upstream SMSC (by bind name)

Helper Sends Returns
submit_via(bind, …) submit_sm SmppResp
submit_multi_via(bind, destinations=[…], …) submit_sm_multi SmppResp
data_via(bind, …) data_sm SmppResp
cancel_via(bind, …) cancel_sm SmppResp
query_via(bind, message_id=…, …) query_sm QueryResp
replace_via(bind, message_id=…, …) replace_sm SmppResp
resp = await smpp.submit_via(
    bind="aggregator-eu",
    source_addr=pdu.source_addr,
    destination_addr=pdu.destination_addr,
    short_message=pdu.short_message,      # bytes
    data_coding=pdu.data_coding,
    registered_delivery=pdu.registered_delivery,
)
if resp:                                  # the SMSC answered ESME_ROK
    upstream_id = resp.message_id
elif resp.throttled:                      # ESME_RTHROTTLED / ESME_RMSGQFUL
    ...                                   # back off and retry later
else:
    log.warning(f"rejected: {resp.command_status}")

Inbound — to a bound ESME (by session_id)

Helper Sends
deliver_to(session_id, …) deliver_sm (MT or a delivery receipt with esm_class=0x04)
data_to(session_id, …) data_sm
alert_to(session_id, …) alert_notification
resp = await smpp.deliver_to(
    session_id=esme_session,
    source_addr=pdu.destination_addr,
    destination_addr=pdu.source_addr,
    short_message=receipt_body,           # bytes
    esm_class=0x04,                       # delivery receipt
)
if not resp:                              # e.g. ESME_RX_T_APPN: keep it, retry
    ...

Response objects

A send helper has three kinds of outcome, and they are kept apart.

The peer answered. You get a response object carrying the command_status from the response PDU, whatever it was. A response is not an acceptance: the object is truthy only for ESME_ROK.

Field Type Meaning
ok bool True only for ESME_ROK. bool(resp) is the same thing.
command_status str Status name, e.g. "ESME_RTHROTTLED". A value outside SMPP 3.4 Table 5-2 (reserved or vendor-specific) reads as its hex literal, e.g. "0x00000401".
command_status_code int The same status as the number that was on the wire.
throttled bool True for ESME_RTHROTTLED and ESME_RMSGQFUL — the peer wants you to back off. The message was not accepted.
message_id str The SMSC-assigned id (submit_via, submit_multi_via, query_via). Empty for the other helpers, and whenever the status is not ESME_ROK — a rejected submit_sm_resp has no body.

QueryResp adds message_state, final_date and error_code, which are only meaningful when ok.

Nothing usable came back. The helper raises smpp.SmppSendError, a RuntimeError subclass. Its reason says which case it was:

reason Meaning Was the message taken?
"timeout" No response within the session's response_timer_ms. Unknown.
"closed" The session ended while the request was outstanding (peer closed, enquire-link failure, unbind). Unknown.
"nack" The peer answered generic_nack. command_status / command_status_code on the exception carry its status. No.
"unanswered" The session reported a failure without a response while it was still up — in practice a generic_nack carrying ESME_RSYSERR, which is not distinguishable from a failed write at this layer. Not acknowledged; treat as not taken.

The exception also carries command (e.g. "submit_sm").

The session was not there to begin with. KeyError: the bind is not currently bound (it may be mid-reconnect), or no ESME session has that session_id.

try:
    resp = await smpp.submit_via(bind="aggregator-eu", ...)
except smpp.SmppSendError as e:
    if e.reason in ("timeout", "closed"):
        ...                               # outcome unknown: retrying may duplicate
    else:
        ...                               # not taken: safe to retry or re-route
except KeyError:
    ...                                   # bind down: try the next route
else:
    if not resp:
        ...                               # rejected: resp.command_status says why

max_msg_per_sec on a bind paces what you send. It does not react to what the peer answers: an ESME_RTHROTTLED response is handed to you as above and the pacing carries on at the configured rate, so backing off further is the script's call. See the gateway example.

Config readouts

Read (never write) the loaded configuration:

Call Returns
smpp.config() The full parsed config.
smpp.bind_address() The inbound listener address.
smpp.binds() The list of configured outbound binds ([{name, host, …}]).
smpp.routing_rules() (default_chain, rules) for your routing logic.

Testing your scripts

You can unit-test SMPP scripts without a running SMSC. The siphon-sip SDK (pip install siphon-sip) mocks the smpp namespace — the same decorators, PDU objects, and send helpers described above — and ships an SmppTestHarness that dispatches binds, PDUs, and lifecycle events into your handlers so you can assert on the replies and on what your script sent back:

from siphon_sdk.smpp_testing import SmppTestHarness

def test_gateway_authorises_and_submits():
    harness = SmppTestHarness()
    harness.load_script("examples/gateway.py")

    # bind_transceiver → @smpp.on_bind
    assert harness.bind("esme1", password="s3cret")

    # submit_sm → @smpp.on_pdu("submit_sm")
    reply = harness.submit_sm(source_addr="15550100",
                              destination_addr="15550101",
                              short_message=b"hi")
    assert reply.ok

    # a DLR delivered on an outbound bind is routed back to the ESME
    harness.deliver_sm(esm_class=0x04,
                       short_message=b"id:msg-1 stat:DELIVRD err:000")
    assert harness.sent[0][0] == "deliver_to"

The mock also gives IDEs and LLMs the full type hints and docstrings for the namespace, which helps when authoring scripts. The mock tracks this crate's runtime surface — CI (scripts/check_sdk_parity.py) fails if they drift.

Hot reload, restated

Handlers are looked up per-PDU, so editing your script (and letting SIPhon reload it) takes effect on the next message — no restart, no rebind. Keep handlers free of import-time side effects, and keep cross-message state in siphon.cache, not module globals, so a reload mid-traffic is safe.