SMPP transport

This transport is an SMPP 3.4 client, mostly used for SMS.

Configuration

The transport has the following configuration options:

All the configuration items from the base worker, which you can find at Base worker configuration

transport_name (str)

The name of the AMQP queue to put inbound messages and events on, and to consume outbound messages from. Defaults to smpp

host (str)

The host for the SMPP server. Can be an IPv4 address, IPv6 address, or hostname. Defaults to localhost

port (int)

The port to connect to on the SMPP server. Defaults to 2775

system_id (str)

The client identification for connecting to the SMPP server. This has a maximum length of 15, and must be ASCII. Defaults to smppclient1

password (str)

The password for the client to authenticate itself to the SMPP server. This has a maximum length of 8, and must be ASCII. Defaults to password

system_type (str)

Identifies the type of system to the SMPP server. Has a maximum length of 12 characters, and must be ASCII. Defaults to no system type.

interface_version (int)

Identifies the version of the SMPP protocol used by the client to the SMPP server. 0 to 33 indicates version 3.3 or earlier, 34 indicates version 3.4. Defaults to 34

address_range (str)

Identifies the address or range of addresses served by this client to the server. Maximum length of 40 characters, must be ASCII. Defaults to no address range.

smpp_enquire_link_interval (int)

The amount of time, in seconds, between EnquireLink calls. These calls are to ensure that the communication channel between the client and server is still healthly. Defaults to 55 seconds.

sequencer_class (str)

The python path to the class to use for sequencing. The sequencer is responsible for providing the sequence numbers for PDUs. These start at 1 and end at 0x7FFFFFFF, after which the sequencer should roll over to 1 again. The sequencer numbers are used to link responses from the ESME to the original request, so it’s important that a sequence number isn’t reused while we’re still waiting for a response for it. Defaults to vumi2.transports.smpp.sequencers.InMemorySequencer, which stores the current sequence position in memory. This is not suitable if you have multiple processes connecting to the same ESME, as the memory is not shared, so the sequencer will not be shared, leading to the same sequence number being used in different processes, which will create overlaps. See Sequencers for a list of available sequencers

sequencer_config (dict)

The config that the sequencer_class requires. See Sequencers for what configuration is required for the sequencer classes.

submit_sm_processor_class (str)

The python path to the class used for generating submit short message (outbound message) requests. This class is responsible for taking an outbound vumi message, and returning a list of PDUs that represents that message, that can be sent to the ESME if we want to send that outbound message. Defaults to vumi2.transports.smpp.processors.SubmitShortMessageProcessor, which provides default short message processing that should be usable across a majority of ESMEs. See Submit Short Message Processors for a list of submit short message processors that are available.

submit_sm_processor_config (dict)

The config that submit_sm_processor_class requires. See Submit Short Message Processors for what configuration is required for the various short message processor classes.

sm_processor_class (str)

The python path to the class used for handling extracting inbound messages from deliver short message requests. This class is responsible for taking the DeliverSM PDUs, and generating inbound Messages from them. It also handles combining a multipart SMS that has been split into multiple PDUs. Defaults to vumi2.transports.smpp.processors.ShortMessageProcessor, which should be usable across a majority of SMSCs. See Short Message Processors for a list of short messages processors.

sm_processor_config (dict)

The config that sm_processor_class requires. See Short Message Processors for what configuration is required for the various short message processors.

dr_processor_class (str)

The python path to the class used for handling and extracting delivery reports from deliver short message requests. This class is reposonsible for taking the DeliverSM PDUs, and generating delivery report Events, if the PDU is for a delivery report. Defaults to vumi2.transports.smpp.processors.DeliveryReportProcesser, which provides delivery report processing that should be usable across a majority of SMSCs. See Delivery Report Processors for a list of delivery report processors that are available

dr_processor_config (dict)

The config that dr_processor_class requires. See Delivery Report Processors for what configuration is required for the various delivery report processor classes

smpp_cache_class (str)

The python path to the class used for the SMPP cache. This class is resposible for caching the parts of a multipart message, and for caching the SMPP message IDs for delivery reports. Defaults to vumi2.transports.smpp.smpp_cache.InMemorySmppCache, which stores the data in memory. See SMPP Caches for a list of SMPP caches.

smpp_cache_config (dict)

The config that smpp_cache_class requires. See SMPP Caches for what configuration is required for the SMPP caches that are available.

How it works

The client creates a new connection to the configured host and port. Because the transport is making a connection to the server, it does not support the server initiating the connection, nor the Outbind command.

Once connected, it sends a bind transceiver command, with the configured system_id, password, system_type, interface_version, and address_range. It then waits for a bind transceiver response, after which it can start sending and receiving messages.

Once it has bound, it sends an enquire link request, at the interval specified by smpp_enquire_link_interval, to ensure that the connection is still alive.

Sequencers

Sequencers are responsible for providing sequence numbers for PDUs. SMPP messages are sent asynchronously, so replies are not necessarily in the same order that the requests were sent in. These sequence numbers are used to match replies from the ESME to the requests that we send them, so it’s important that each request that we’re waiting on a reply for has a unique sequence number.

These numbers range between 1 and 0x7FFFFFFF.

In-memory sequencer

vumi2.transports.smpp.sequencers.InMemorySequencer

This sequencer stores the current sequence position in memory. It is provided for simple single-process setups, as well as for easy testing. It has no external requirements.

It is not suitable for cases where the sequence number generator needs to be shared across processes, or if the sequence position needs to be persisited across process restarts.

When it reaches 0x7FFFFFFF, it rolls over back to 1, assuming that the lower sequence numbers have been responded to already.

It has no configuration, any configuration fields passed to it will be ignored.

Submit Short Message Processors

The job of the submit short message processor is to take outbound vumi messages, and convert them into equivalent PDUs to be sent to the ESME, in order to send the outbound message.

Default submit short message processor

vumi2.transports.smpp.processors.SubmitShortMessageProcessor

This sequencer is designed to work with most EMSEs.

It has the following configuration fields:

Warning

These fields will be changed, to something better, and then documentation can be improved showing all the choices for each field.

data_coding (int)

What data encoding to use. This sets both the data_coding field on the PDU, as well as sets the encoding that we use for the message body. The following encodings are supported: SMSC default (GSM03.38), ASCII, Latin 1, JIS (ISO 2022 JP), Cyrllic (ISO-8859-5), Latin/Hebrew (ISO-8859-8), UCS2

multipart_handling (str)

How to handle splitting messages. Defaults to short_message, which does not allow long messages. Other options are: message_payload, which puts the whole message in the message_payload parameter of the PDU, multipart_sar, which splits the message, and puts the part details in the SAR fields of the PDU, and multipart_udh, which splits the message and puts the part details as a header in front of each message part.

service_type (str)

Defaults to none. ESME specific, what string to put in the service_type field of the PDU.

source_addr_ton (int)

Defaults to unknown. The type of number for the source address (the address of the service).

source_addr_npi (int)

Defaults to unknown. The numbering plan indicator for the source address (the address of the service)

dest_addr_ton (int)

Defaults to unknown. The type of number for the destination address (the address of the user).

dest_addr_npi (int)

Defaults to ISDN. The numbering plan indicator for the destination address (the address of the user)

registered_delivery (dict)

The configuration for registered delivery. Takes the following fields:

delivery_receipt (int)

Defaults to no receipt requested. The SMSC delivery receipt to request

sme_originated_acks (list[int])

Defaults to none. Which SME originated acknowledgements to request

intermediate_notification (bool)

Defaults to False. Whether or not to request intermediate notifications

Delivery Report Processors

The job of a delivery report processor is to take DeliverSM PDUs, and if it looks like a delivery report, return an Event representing that delivery report.

Default delivery report processor

vumi2.transports.smpp.processors.DeliveryReportProcesser

This delivery report processor is designed to work with most SMSCs.

It has the following configuration fields:

regex (str)

The regular expression to use to determine and extract the delivery report out of the message body. Defaults to a regular expression that should work for most SMSCs

status_mapping (dict)

A mapping between the delivery report status, and pending, delivered and failed. Defaults to a default mapping that should work for most SMSCs.

Short Message Processors

The job of a short message processor is to take the DeliverSM PDUs, process them, and return the equivalent inbound Message. It also handles multipart messaging, by waiting for all the PDUs that make up a Message, and then returning a single Message once we have all the parts.

Default short message processor

vumi2.transports.smpp.processors.ShortMessageProcessor

This short message processor is designed to work with most SMSCs.

It has the following configuration fields:

data_coding_overrides (dict):

This field can be used to override any of the default codecs used to decode the message body, or provide a codec name for any of the unhandled data codings, eg. if you want to specify OCTET_UNSPECIFIED as ascii. Defaults to no overrides.

SMPP Caches

An SMPP cache caches state that we require for the SMPP transport. Currently it has two jobs:

1. It caches the parts of an inbound multipart message, so that when we have all of the parts, we can submit it as a single message 1. It caches the relation between the SMPP message ID, and the vumi Message ID, so that we can know what message a delivery report is for when we receive it.

In memory SMPP cache

vumi2.transports.smpp.smpp_cache.InMemorySmppCache

This is an SMPP cache implementation that stores the data in memory. Because of this, it is not suitable to share the data across multiple processes, and it will not survive process restarts.

It has the following configuration fields:

timeout (int)

The maximum amount of time to keep SMPP message IDs for received delivery reports. Defaults to 24 hours.

Still to do

The transport is not yet complete, the following things need to still be done

  • Support receiver and transmitter binds, not just transceiver.

  • Better config for processors

  • Outbound messages: support USSD

  • Sequence number generation is currently just in memory. We might want to have this configurable to store in a place like Redis, to be shared across processes.