# SMPP specification
___

The **Short Message Peer-to-Peer (SMPP)** is an open, industry-standard protocol used by the telecommunication industry for exchanging SMS messages between SMS application systems and Short Message Service Centers (SMSC).

The connection between the application and the Infobip SMPP server is [SMPP version 3.4](http://opensmpp.org/specs/SMPP_v3_4_Issue1_2.pdf) (versions 3.3 and 5.0 are not supported).

___

## Supported SMPP features

### SMPP traffic security [#smpp-traffic-security-supported-smpp-features]

Use a dedicated user with credentials intended only for broadcasting SMPP API traffic. This ensures proper account administration and keeps your SMPP API traffic secure.

If your SMPP traffic originates from static IP addresses, contact your **account manager** and provide a list of your source IP addresses to be safelisted for the user responsible for broadcasting SMPP API traffic. To connect to the Infobip SMPP server, use the hostnames listed in the [Bind parameters](#bind-parameters-supported-smpp-features) section.

For a secure connection, send the bind request to the encrypted SSL/TLS endpoint `smpp2.infobip.com:8887`.

### Bind parameters [#bind-parameters-supported-smpp-features]

Note
The length of the password required depends on your SMPP library rather than the SMPP v3.4 protocol itself. Use a library that supports passwords longer than 8 characters. If you need additional information, contact our [Support](mailto:support@infobip.com) to adjust the password strength policy on your account.

| Name                     | Mandatory | Description                                                                                                      |
|--------------------------|-----------|------------------------------------------------------------------------------------------------------------------|
| system_id                | Yes       | The user's username created on the Infobip platform.                                                             |
| password                 | Yes       | Provided for each client.                                                                                        |
| IP address               | Yes       | Primary: **smpp3.infobip.com** <br/> Secondary: **smpp1.infobip.com** <br/> SSL: **smpp2.infobip.com** <br/><br/> For different accounts, choose the hostname based on the Data Center (DC) location to ensure that logs are properly displayed (for example, use `smpp-id1.infobip.com` for accounts located in Indonesia). |
| port                     | Yes       | 8888 (primary and secondary) <br/> 8887 (SSL)                                                                      |
| timeout (keep alive or msg)  | Yes       | 30 seconds                                                                                                           |
| system_type              | No        | Optional                                                                                                         |

Important
You can bind as a transmitter, receiver, or a transceiver. To receive delivery reports, you must bind as a **transceiver** or a **receiver**.

You will receive delivery reports only if your route provides delivery reporting. Delivery reports will be sent equally over all of your available sessions capable of receiving them (transceiver or receiver).

By default, you can bind with up to **4 sessions**. There are no other throughput (TPS) limitations besides internet speed.

___

## PDU types

- `bind_transmitter`
- `bind_receiver`
- `bind_transceiver`
- `unbind`
- `submit_sm`
- `deliver_sm`
- `enquire_link`

___

## Data coding schemes

Setting DCS to 0 or 1 will apply the **IA5/GSM7** coding scheme to the message (GSM7 being the default Infobip SMSC alphabet).

Set DCS = 3 for **Latin1** (ISO-8859-1), and DCS = 8 for sending messages as **Unicode/UCS-2** (ISO/IEC-10646).

___

## Scheduled delivery

Scheduled delivery is supported over the SMPP protocol using **relative time format**.

`070605040302100R`

For example, that would mean that the message will be delivered in 7 years, 6 months, 5 days, 4 hours, 3 minutes, 2 seconds and 1 tenth of a second from now.

___

## Command status

Each request to our system will receive an acknowledgement as per SMPP v 3.4 standard, including `command_status`. Most relevant command statuses, including Infobip-specific ones, are in the table below:

| command_status | PDU          | Description                                  |
|----------------|--------------|----------------------------------------------|
| 0x0000000E    | bind_resp    | Invalid credentials                          |
| 0x00000022 / 34 | submit_sm_resp | Network not covered                        |
| 0x000000FF / 255 | submit_sm_resp | Account has insufficient balance           |
| 0x0000000a    | submit_sm_resp | Invalid source address                       |
| 0x0000000b    | submit_sm_resp | Invalid destination address                  |
| 0x0000000c    | submit_sm_resp | Duplicate or invalid messageID               |
| 0x000004a1    | submit_sm_resp | System error or channel disabled             |
| 0x0000009F    | submit_sm_resp | Invalid optional parameter length            |

___

## Delivery report format

Delivery report in this format will be returned in short message field of deliver_sm PDU:

`id:{message_id} sub:{message_sub} dlvrd:{message_dlvrd}`
`submit date:{message_submit_date} done date:{message_done_date}`
`stat:{message_stat} err:{message_err}`

___

## Delivery statuses

- `DELIVRD`
- `EXPIRED`
- `UNDELIV`
- `ACCEPTD`
- `UNKNOWN`
- `ENROUTE`
- `REJECTD`

___

## GSM error codes

GSM error codes are returned in DLRs and explain the status of the message (whether intermediate or final). Error code will be returned in the `short_message` as a part of delivery information, or (if enabled by Infobip specialists) in Optional TLV 0x423.

Check the possible [error codes](https://www.infobip.com/docs/response-status-and-error-codes).

___

## Flash notifications

You can use your Infobip SMPP account to send Flash notifications. Such notifications are immediately displayed on the mobile phone screen upon arrival and are not stored in the memory of the device. Use your default `system_id` and password to send Flash notifications by submitting messages with Data Coding set to 16 (or 24 for Unicode).

Long SMS feature is not supported for Flash notifications. Delivery reports will be sent to you using DeliverSM PDU.

___

## Number lookup

Using the Infobip SMPP account, you can request [Number Lookup](https://www.infobip.com/number-lookup) data. To use Number Lookup, you can use your default `system_id` and `password`, setting `system_type = HLR` in Bind PDU.

**SubmitSM PDU** is used for submitting the Number Lookup request, with the `destAddress` parameter set to the required destination address. All other parameters will be ignored (srcAddress, TON/NPI, and so on).

Infobip Number Lookup subsystem will respond using a regular **SubmitSMResp**, containing the `message_id` reference.

Once the Number Lookup request has been finalized on the Infobip system, you will receive **DeliverSM PDU**, containing the short message with: **IMSI** for the required destAddress **or** an **error code** in case of failure, plus additional **optional info fields**, depending on your package.

| Optional info fields                         | Type       | Hex    | Decimal |
|----------------------------------------------|------------|--------|---------|
| Original network name                        | TLVString  | 0x1412 | 5138    |
| Original network prefix                      | TLVString  | 0x140B | 5131    |
| Original country                             | TLVString  | 0x1422 | 5154    |
| Original country code                        | TLVString  | 0x1423 | 5155    |
| Original country prefix                      | TLVString  | 0x1424 | 5156    |
| Ported network name                          | TLVString  | 0x1413 | 5139    |
| Ported country prefix                        | TLVString  | 0x1442 | 5186    |
| Ported network prefix                        | TLVString  | 0x143e | 5182    |
| Ported network country name                  | TLVString  | 0x143f | 5183    |
| Is number ported                             | TLVInt     | 0x1421 | 5153    |
| Roaming network name                         | TLVString  | 0x1414 | 5140    |
| Roaming network prefix                       | TLVString  | 0x1419 | 5145    |
| Roaming country name                         | TLVString  | 0x1415 | 5141    |
| Roaming country code                         | TLVString  | 0x1417 | 5143    |
| Roaming country prefix                       | TLVString  | 0x1420 | 5152    |
| MCCMNC                                       | TLVString  | 0x1416 | 5142    |
| Price per message(multiplied by 100 for compatibility reasons) | TLVInt | 0x1418 | 5144    |
| Serving HLR                                  | TLVString  | 0x1409 | 5129    |
| Is number correct                            | TLVInt     | 0x1425 | 5157    |

| Extra-optional info fields | Type    | Hex    | Decimal |
|----------------------------|---------|--------|---------|
| IMSI                       | Oct     | 0x1403 | 5123    |

In case that the Number Lookup request was successful, DeliverSM will be as follows (`IMSI 219101100935850`):

`addr: 0 0 38591xxxxxxx`
`addr: 0 0 0000000000`
`msg: id:40072910491427628 sub:001 dlvrd:001 submit date:1007291049 done date:1007291049 stat:DELIVRD err:000`
`IMSI:219101100935850 MSC:38591016 HLR:38591xxxxxxx ORN:VipNet PON:VipNet RON:VipNet ROC:HR MCCMNC:21910`
`opt: (oct: (tlv: 1059) 030000) (byte: (tlv: 1063) 2) (str: (tlv: 30) 40072910491427628) (str: (tlv: 5129)38591xxxxxxx) (str: (tlv: 5138) VipNet) (str: (tlv: 5139) VipNet) (str: (tlv: 5140) VipNet) (str: (tlv:5141) Croatia ) (str: (tlv: 5143) HR) (str: (tlv: 5142) 21910) (int: (tlv: 5144) 1) (str: (tlv: 5145) 91) (str: (tlv: 5152) 385) (int: (tlv: 5153) 1) (str: (tlv: 5154) Croatia ) (str: (tlv: 5155) HR) (str: (tlv: 5156) 385) (int: (tlv: 5157) 1) ) (extraopt: (oct: (tlv: 5123) 323139313031313030393335383530) )`

If an error occurred, DeliverSM will be as follows:

`addr: 0 0 38591xxxxxxx`
`addr: 0 0 0000000000`
`msg: id:40072910491419819 sub:001 dlvrd:001 submit date:1007291049 done date:1007291049 stat:UNDELIV err:001`
`IMSI: MSC: ORN:VipNet MCCMNC:`
`opt: (oct: (tlv: 1059) 030001) (byte: (tlv: 1063) 5) (str: (tlv: 30) 40072910491419819) (str: (tlv: 5138) VipNet) (str: (tlv: 5142) ) (int: (tlv: 5144) 1) (int: (tlv: 5153) 0) (str: (tlv: 5154) Croatia ) (str: (tlv: 5155) HR) (str: (tlv: 5156) 385) (int: (tlv: 5157) 1) )`

___

## URL Shortening

You can use your SMPP connection in conjunction with the [URL Shortening](https://www.infobip.com/docs/url-shortening) functionality using the following TLVs:

| Optional fields  | Type      | Hex    | Decimal | Value                               | Notes                                               |
|------------------|-----------|--------|---------|-------------------------------------|-----------------------------------------------------|
| Shorten Url      | TLVString | 0x1494 | 5268‬   | Any value will enable               | Not required if Custom Domain TLV is set            |
| Custom Domain    | TLVString | 0x1495 | 5269‬   |                                     | http:// or https:// are not required in the custom domain |
| Remove Protocol  | TLVString | 0x1496 | 5270‬   | Boolean                             |                                                     |
---