Version
Optional Fields
Optional fields in SMPP, known as Tag-Length-Value (TLV) parameters, provide additional flexibility and functionality beyond the required fields. These parameters are not mandatory for all operations but can be included to support specific features such as delivery receipts, callback numbers, or extended message attributes.
All optional fields appear at the end of the PDU, in a designated optional parameters section. Within that section, fields can be encoded in any order. Depending on the use case, a PDU may include some, all, or none of the available optional fields. For example, a system submitting a message via submit_sm might include only a callback number TLV, while others may require multiple additional parameters.
Optional TLVs are designed to support a range of wireless technologies, including GSM, CDMA, TDMA, and iDEN, making them widely applicable across different messaging infrastructures.
Below is the full list of optional SMPP parameters (TLVs).
| dest_addr_subunit | Specifies a subaddress or subunit within the destination device. Used when the SMS needs to be routed to a specific component (e.g., SIM, memory module, or application) of a multi-functional device. |
| source_addr_subunit | Same as above, but for the originating device. Useful when indicating the exact origin point within a device that supports multiple messaging components. |
| dest_network_type | Indicates the type of wireless network the destination is using. This could be GSM, CDMA, iDEN, etc. Used by the SMSC to tailor message handling for the target network technology. |
| source_network_type | The corresponding network type for the message originator. Like dest_network_type, this helps with routing or applying network-specific delivery rules. |
| dest_bearer_type | Specifies the bearer service used for delivering the message to the destination—e.g., SMS over GPRS, USSD, or circuit-switched SMS. |
| source_bearer_type | Same as above, but for the message originator. These fields are rarely used in standard SMS delivery, but may be relevant in operator-level implementations or hybrid network setups. |
| dest_telematics_id | Identifies the specific telematics service at the destination. Used when the destination device or application is part of a vehicle system or machine-to-machine (M2M) platform requiring message classification. |
| source_telematics_id | Same as above, but for the source. Useful in M2M communication or specialized data services where sender identity goes beyond standard phone numbers. |
| qos_time_to_live | Defines how long the message is allowed to remain undelivered before the SMSC gives up. Unlike validity_period, this field is focused on QoS enforcement, especially for time-sensitive messages. Expressed in milliseconds. If the message isn’t delivered within this time, it’s dropped. |
| payload_type | Indicates the format or type of content in the message payload. Typically used in MMS or data-heavy environments to classify message content (e.g., binary, multimedia, or protocol-specific formats). Helps systems downstream interpret how to handle the message. |
| additional_status_info_text | Provides a textual description of the message status, usually in deliver_sm or data_sm_resp. Used to give more human-readable context to error codes or delivery outcomes, especially in troubleshooting or logs. |
| receipted_message_id | Returns the original message_id for which a delivery receipt is being generated. This allows the ESME to correlate the receipt with the message it submitted. It’s critical when processing delivery reports in high-volume systems. |
| ms_msg_wait_facilities | Used to indicate that the recipient MS (Mobile Station) has waiting messages (like voicemails or unread texts). Often included in messages that trigger a message waiting indicator (MWI) on the device. This TLV is mostly relevant in operator infrastructure or Voicemail SMS. |
| privacy_indicator | Indicates privacy or confidentiality level. For example, it might flag a message as confidential, requiring special handling (e.g., no storage on intermediate systems). Rarely used in general SMS workflows. |
| source_subaddress | Defines a sub-address for the message originator, allowing routing to or identification of a specific application, module, or logical endpoint on the source side. This is beyond the normal source_addr. |
| dest_subaddress | Same as source_subaddress, but for the recipient. Used when the destination has multiple logical endpoints that need to be addressed separately (e.g., embedded systems, enterprise gateways). |
| user_message_reference | An optional ID assigned by the ESME to track the message. This reference is echoed back in delivery reports or responses and can help match messages to application-level logic. |
| user_response_code | A one-byte field that allows the SMSC or recipient to return a custom response code back to the ESME. Useful in application-driven messaging scenarios (e.g., status codes for interactive or session-based communication). |
| language_indicator | Specifies the language used in the message content. Often used in combination with specific encoding schemes to support language-specific character sets or localization behavior on the receiving device. |
| source_port | Indicates the application port number on the source side. Used in WAP push, EMS, or other binary messaging systems to route the message to a specific application on the sending device. |
| destination_port | Specifies the port number on the destination device where the message should be delivered. Common in mobile applications that listen on specific ports for incoming data (e.g., financial apps, mobile games, system-level services). |
| sar_msg_ref_num | Short for Segmentation and Reassembly Message Reference Number. A shared reference used to group all segments of a multipart message together. |
| sar_total_segments | The total number of segments the original message was split into. Included in each segment so the recipient knows how many parts to expect. |
| sar_segment_seqnum | The sequence number of this particular segment in the multipart message. Starts from 1 and increases with each part. |
| sc_interface_version | Indicates the SMSC’s supported SMPP version. Useful for compatibility checks between the SMSC and ESME. Helps ensure that features or field expectations match between both ends of the connection. |
| display_time | Specifies how long the message should be displayed on the recipient’s device. This is mostly device-specific and not widely supported by all networks. Often used in flash messaging scenarios. |
| ms_validity | Indicates the validity period as understood by the mobile station (MS). This is different from the validity_period parameter, which is SMSC-based. It's relevant when the handset or network terminal enforces message expiry. |
| dpf_result | DPF stands for Delivery Pending Flag. This field is used in delivery reports to indicate whether a message had to be stored by the SMSC before delivery (e.g., if the recipient was temporarily unavailable). |
| set_dpf | Instructs the SMSC to set the DPF flag if the message is stored for delayed delivery. Allows the ESME to track whether delivery was real-time or deferred. |
| ms_availability_status | Indicates whether the recipient mobile station was available at the time of message delivery attempt. Helps applications understand the context of delayed delivery or failures. |
| network_error_code | Provides carrier-specific error codes when message delivery fails. It's structured (usually) as a 3-byte field: • Byte 1: Network type • Byte 2: Error code group • Byte 3: Specific error Used in troubleshooting and analytics to classify failure reasons beyond the general command_status. |
| message_payload | A TLV alternative to the short_message field, used when sending large or binary content. Unlike short_message, this can exceed the usual 140-byte limit and is commonly used for long or concatenated messages. |
| delivery_failure_reason | Returned in delivery receipts to explain why a message failed. While not standardized across all implementations, this field can provide more actionable insight than just a generic error code. |
| more_messages_to_send | A flag used in deliver_sm to indicate that more messages are queued for delivery in the current session. Helps optimize throughput by letting the ESME know to expect additional PDUs without re-requesting them. |
| message_state | Returns the current status of a message, typically used in query_sm_resp or delivery receipts. Values include: • 0x01 – Enroute • 0x02 – Delivered • 0x03 – Expired • 0x05 – Undeliverable • 0x08 – Rejected This TLV is often included alongside receipted_message_id. |
| callback_num | A phone number the recipient can use to call or message back. Used in service-oriented SMS (e.g., two-way chat or customer support) to indicate a return contact point. |
| callback_num_pres_ind | Controls how the callback_num should be presented (e.g., allowed, restricted, or unavailable). Works similarly to CLI (Caller Line Identification) presentation in voice networks. |
| callback_num_atag | An alphanumeric string associated with the callback_num. Typically used to display friendly names or tags (e.g., "Customer Support") alongside the number. |
| number_of_messages | Indicates the number of messages waiting for the recipient (e.g., unread SMS or voicemails). May be used in deliver_sm to update a user’s message waiting indicator (MWI) status. |
| sms_signal | Controls device-specific alert behavior (e.g., vibration, light, sound) when the message arrives. Support is device-dependent and uncommon in general messaging. |
| alert_on_message_delivery | Triggers a special alert on the recipient device when the message is delivered. Similar to a flash SMS or urgent notification. Not widely supported across all networks or devices. |
| its_reply_type | Used to indicate how a terminal (e.g., a smart card or SIM-based app) should respond to a message, especially in interactive or SIM toolkit-based sessions. |
| its_session_info | Contains session-related metadata for ITS (Intelligent Terminal Support) applications. Helps maintain session context between the SMSC and a smart terminal. |
| ussd_service_op | Defines the USSD operation type (e.g., request, response, notification). This TLV is used in SMS-over-USSD gateways or applications that bridge SMPP with USSD interfaces. |
Start innovating with Mobius
What's next? Let's talk!