Integration

Once the session is bound (see Authentication), traffic flows through a small set of PDUs. This page documents what is supported and how the payload is shaped.

Supported PDUs

PDU	Purpose
`bind_transceiver`	Send and receive SMS on the same session.
`bind_transmitter`	Send SMS only.
`bind_receiver`	Receive SMS only.
`submit_sm`	Send a mobile-terminated (MT) message.
`deliver_sm`	Receive DLRs and inbound messages.
`enquire_link`	Keep the session alive.
`unbind`	Log out — SMPP v5.0 only.

Sending messages

Use submit_sm to send an MT. The fields below are recognised; everything else is ignored or rejected depending on the PDU version.

Field	Description	Notes
`source_addr`	Sender (from).	3–11 chars.
`destination_addr`	Recipient MSISDN.	E.164 with country prefix.
`esm_class`	Message mode and type.	See concatenation below.
`registered_delivery`	Whether to request DLRs.	`1` to receive DLRs.
`data_coding`	Character encoding.	See table below.
`short_message`	Message body.	Up to the encoding-dependent length limit.
`message_payload`	Alternative to `short_message` for long messages.	See concatenation.

Example PDU:

{
  "command": "submit_sm",
  "command_id": 4,
  "source_addr": "INSTASENT",
  "destination_addr": "+34676388300",
  "esm_class": 0,
  "registered_delivery": 1,
  "short_message": "example of message"
}

Data coding

Value	Encoding
`0`	GSM7
`3`	ISO-8859-15 (LATIN9)
`8`	UTF-16BE (UCS2)

Message concatenation

Messages that exceed the single-segment limit can be delivered in two ways. Pick whichever fits your SMPP client.

`message_payload`

Put the whole text in message_payload instead of short_message. The server segments for you.

{
  "command": "submit_sm",
  "source_addr": "INSTASENT",
  "destination_addr": "+34666000000",
  "esm_class": 0,
  "registered_delivery": 1,
  "message_payload": "Y, viéndole don Quijote de aquella manera, con muestras de tanta tristeza, le dijo: Sábete, Sancho, que no es un hombre más que otro si no hace más que otro."
}

UDHI segmentation

Set the User Data Header Indicator on esm_class and build the concatenation header yourself.

esm_class = 0x40

The UDH prefix is inserted at the start of the message body:

Byte	Description
`05`	Length of UDH (5 bytes).
`00`	Indicator for concatenated message.
`03`	Subheader length (3 bytes).
`XX`	Message identifier — any hex value, must match across all segments.
`YY`	Total number of segments.
`ZZ`	Sequence number of this segment.

Two-segment example:

# segment 1
esm_class     = 0x40
short_message = 0x05 0x00 0x03 0x05 0x02 0x01 Y, viéndole don Quijote de aquella manera, con muestras de tanta tristeza, le dijo: Sábete, Sancho, que no es un hombre más que

# segment 2
esm_class     = 0x40
short_message = 0x05 0x00 0x03 0x05 0x02 0x02 otro. Todas estas borrascas que nos suceden son señales de que presto ha de serenar el tiempo y han de sucedernos bien las cosas

Receiving DLRs

DLRs come in through deliver_sm PDUs with esm_class=4. The body is a single line in the usual SMPP DLR format:

id:288230378411154593 sub:001 dlvrd:001 submit date:1602260445 done date:1602260345 stat:DELIVRD err:000 text:none

Field	Description
`id`	Instasent message id.
`sub`	Unused.
`dlvrd`	`1` delivered, `0` not delivered.
`submit date`	Send date, `YYMMDDHHMM`.
`done date`	Completion date, `YYMMDDHHMM`.
`stat`	Status — see table below.
`err`	Error code.

DLR statuses

Status	Description
`DELIVRD`	Message delivered to destination.
`EXPIRED`	Message validity period expired.
`DELETED`	Message deleted.
`ACCEPTD`	Message accepted.
`UNDELIV`	Message undeliverable.
`UNKNOWN`	Message in an invalid state.
`REJECTD`	Message rejected.

Receiving inbound messages

Inbound (MO) messages arrive through deliver_sm with esm_class=0. The content is carried on short_message.message.