# Integration

Supported PDUs, submit_sm fields, message concatenation, DLRs over deliver_sm and inbound handling for the Transactional API over SMPP.

Once the session is bound (see [Authentication](/transactional-api/smpp/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:

```json
{
  "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.

```json
{
  "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`.