Sending a Message
To send a message with SMPP, you’ll use the submit_sm operation, which will submit an SMS to the SMSC to be send to the destination.
The
submit_smprotocol does not support the transaction message mode.
TON/NPI & Other Settings
TON and NPI values may change from aggregator to aggregator, so we’ve created the below table to help you properly set the TON and NPI values on your message sends.
| Source TON | 0 - for messages sent via Shortcode or Longcode 5 - for messages sent via Alphanumeric Code (non-US) |
| Source NPI | Always 0 |
| Destination TON | Always 0 - Non-US/Canada MDNs must be sent in E.164 format. |
| Destination NPI | Always 0 |
| System Type | Not used - Leave blank. |
| Service Type | Not used - Leave blank. |
| Validity Period | Not used - Leave blank. |
For more on the required message settings, please see Encoding & Message Settings.
Receiving a message
The deliver_sm operation is sent by the SMSC to your ESME, which your ESME can then route for delivery, if applicable.
In addition to sending messages, the SMSC uses the deliver_sm operation to transfer the following types of short messages to the ESME:
- SMSC Delivery Receipt: A delivery receipt relating to a message which had been previously submitted with the
submit_smoperation. This will only be sent if the ESME had requested a delivery receipt via theregistered_deliveryparameter. The delivery receipt data relating to the original short message will be included in theshort_messagefield of thedeliver_sm. - SME Delivery Acknowledgement: The user data of the SME delivery acknowledgement is included in the
short_messagefield of thedeliver_sm. - SME Manual/User Acknowledgement: The user data of the SME delivery acknowledgement is included in the
short_messagefield of thedeliver_sm. - Intermediate Notification: The user data of the SME delivery acknowledgement is included in the
short_messagefield of thedeliver_sm.
Parameters
Both the submit_sm and deliver_sm operations have the same parameters, which means that in some cases, some fields may only be used for one. Below you’ll find a table with definitions for both incoming and outgoing messages. For ease of use, we have broken the fields into three categories: header parameters, mandatory parameters, and optional parameters.
Header Parameters
| Field Name | Size Octets | Type | Sending | Receiving |
|---|---|---|---|---|
command_length | 4 | Integer | Set to overall length of PDU. | Set to overall length of PDU. |
command_id | 4 | Integer | submit_sm | deliver_sm |
command_status | 4 | Integer | Not used. Set to NULL. | Not used. Set to NULL. |
sequence_number | 4 | Integer | Set to a unique sequence number. The associated submit_sm_resp PDU will include this number. | Set to a unique sequence number. The associated submit_sm_resp PDU will include this number. |
Mandatory Parameters
| Field Name | Size Octets | Type | Sending | Receiving |
|---|---|---|---|---|
service_type | Varies. Max of 6 | C-Octet string | Used to indicate the SMS Application service associated with the message. Specifying the service_type allows the ESME to- avail of enhanced messaging services such as “replace by service” type - to control the teleservice used on the air interface.Set to NULL for default SMSC settings. | The service_type parameter can be used to indicate the SMS Application service associated with the message. |
source_addr_ton | 1 | Integer | Type of number for source address. If not known, set to NULL (Unknown). | Type of number for source address. If not known, set to NULL (Unknown). |
source_addr_npi | 1 | Integer | Numbering plan indicator for source address. If not known, set to NULL (Unknown). | Numbering plan indicator for source address. If not known, set to NULL (Unknown). |
source_addr | Varies. Max of 21. | C-Octet String | Address of SME which originates this message. If not known, set to NULL (Unknown). | Address of SME which originates this message. If not known, set to NULL (Unknown). |
dest_addr_ton | 1 | Integer | Type of Number (TON) for destination. | Type of Number (TON) for destination. |
dest_addr_npi | 1 | Integer | Numbering Plan Indicator (NPI) for destination. | Numbering Plan Indicator (NPI) for destination. |
destination_addr | Varies. Max 21. | C-octet string | Destination address of this short message. For mobile terminated messages, this is the directory number of the recipient MS. | Destination address of destination SME. |
esm_class | 1 | Integer | Indicates message mode and message type. | Indicates Message Type and enhanced network services |
protocol_id | 1 | Integer | Protocol identifier. Network-specific field. | Protocol identifier. Network-specific field. |
priority_flag | 1 | Integer | Designates the priority level of the message. | Designates the priority level of the message. |
schedule_delivery_time | 1 or 17 | C-Octet String | The short message is to be scheduled by the SMSC for delivery. Set to NULL for immediate message delivery. | This field is unused for deliver_sm. It must be set to NULL. |
validity_period | 1 or 17 | C-Octet String | The validity period of this message. Set to NULL to request the SMSC default validity period. | This field is unused for deliver_sm. It must be set to NULL. |
reqistered_delivery | 1 | Integer | Indicator to signify if an SMSC delivery receipt or acknowledgement will be sent in response to this operation. | Indicates in an ESME acknowledgement is required. |
replace_if_present_flag | 1 | Integer | Flag indicating if submitted message should replace an existing message. | This field is unused for deliver_sm. It must be set to NULL. |
data_coding | 1 | Integer | Defines the encoding scheme of the short message user data. Please note that Vibes uses SMPP 3.4 and the default encoding is ASCII/IA5.. See our encoding article for more information. | Defines the encoding scheme of the short message user data. Please note that Vibes uses SMPP 3.4 and the default encoding is ASCII/IA5.. See our encoding article for more information. |
sm_default_msg_id | 1 | Integer | Indicates the short message to send from a list of predefined (‘canned’) short messages stored on the SMSC. If not using an SMSC canned message, set to NULL. | This field is unused for deliver_sm. It must be set to NULL. |
sm_length | 1 | Integer | Length in octets of the short_message user data. | Length in octets of the short_message user data. |
short_message | Varies. 0 to 254. | Octet string | Up to 254 octets of short message user data. The exact physical limit for short_message size may vary according to the underlying network.Applications which need to send messages longer than 254 octets should use the message_payload parameter. In this case the sm_length field should be set to zero.Note: The short message data should be inserted in either the short_message or message_payload fields. Both fields must not be used simultaneously. | Up to 254 octets of short message user data. The exact physical limit for short_message size may vary according to the underlying network.Applications which need to send messages longer than 254 octets should use the message_payload parameter. In this case the sm_length field should be set to zero.Note: The short message data should be inserted in either the short_message or message_payload fields. Both fields must not be used simultaneously. |
Optional Parameters
| Parameter Name | Type | Sending | Receiving |
|---|---|---|---|
user_message_reference | TLV | ESME-assigned message and reference number. | A reference assigned by the originating SME to the message. In the case that the deliver_sm is carrying an SMSC delivery receipt, an SME delivery acknowledgement or an SME user acknowledgement (as indicated in the esm_class field), the user_message_reference parameter is set to the message reference of the original message. |
source_port | TLV | Indicates the application port number associated with the source address of the message. This parameter should be present for WAP applications. | Indicates the application port number associated with the source address of the message. This parameter should be present for WAP applications. |
source_addr_subunit | TLV | The subcomponent in the destination device which created the user data. | N/A |
destination_port | TLV | Indicates the application port number associated with the destination address of the message. This parameter should be present for WAP applications. | Indicates the application port number associated with the destination address of the message. This parameter should be present for WAP applications. |
dest_addr_subunit | TLV | The subcomponent in the destination device for which user data is intended. | N/A |
sar_msg_ref_num | TLV | The reference number for a particular concatenated short message. | The reference number for a particular concatenated short message. |
sar_total_segments | TLV | Indicates the total number of short messages within the concatenated short message. | Indicates the total number of short messages within the concatenated short message. |
more_messages_to_send | TLV | Indicates that there are more messages to follow for the destination address. | N/A |
payload_type | TLV | Defines the type of payload (e.g. WDP, WCMP, etc.) | Defines the type of payload (e.g. WDP, WCMP, etc.) |
message_payload | TLV | Contains the extended short message user data. Maximum 900 characters with encoding. See Optional Vibes TLVs for more information. Note: The short message data should be inserted in either the short_message or message_payload fields. Both fields should not be used simultaneously.The sm_length field should be set to zero if using the message_payload parameter. | Contains the extended short message user data. Maximum 900 characters with encoding. See Optional Vibes TLVs for more information. Note: The short message data should be inserted in either the short_message or message_payload fields. Both fields should not be used simultaneously.The sm_length field should be set to zero if using the message_payload parameter. |
privacy_indicator | TLV | Indicates the level of privacy associated with the message. | Indicates the level of privacy associated with the message. |
callback_num | TLV | A callback number associated with the short message. This parameter can be included a number of times for multiple callback addresses. | A callback number associated with the short message. This parameter can be included a number of times for multiple callback addresses. |
callback_num_pres_ind | TLV | Defines the callback number presentation and screening. If this parameter is present and there are multiple instances of the callback_num parameter then this parameter must occur an equal number of instances and the order of occurrence determines the particular callback_num_pres_ind which corresponds to a particular callback_num. | N/A |
callback_num_atag | TLV | Associates a displayable alphanumeric tag with the callback number. If this parameter is present and there are multiple instances of the callback_num parameter then this parameter must occur an equal number of instances and the order of occurrence determines the particular callback_num_atag which corresponds to a particular callback_num. | N/A |
source_subaddress | TLV | The subaddress of the message originator. | The subaddress of the message originator. |
dest_subaddress | TLV | The subaddress of the message destination. | The subaddress of the message destination. |
user_response_code | TLV | A user response code. The actual response codes are implementation specific. | A user response code. The actual response codes are SMS application specific. |
display_time | TLV | Provides the receiving MS with a display time associated with the message. | N/A |
sms_signal | TLV | Indicates the alerting mechanism when the message is received by an MS. | N/A |
ms_validity | TLV | Indicates validity information for this message to the recipient MS. | N/A |
ms_msg_wait_facilities | TLV | This parameter controls the indication and specifies the message type (of the message associated with the MWI) at the mobile station. | N/A |
number_of_messages | TLV | Indicates the number of messages stored in a mailbox | N/A |
alert_on_msg_delivery | TLV | Request an MS alert signal be invoked on message delivery. | N/A |
language_indicator | TLV | Indicates the language of an alphanumeric text message. | Indicates the language of an alphanumeric text message. |
its_reply_type | TLV | The MS user’s reply method to an SMS delivery message received from the network is indicated and controlled by this parameter. | N/A |
its_session_info | TLV | Session control information for Interactive Teleservice. | Session control information for Interactive Teleservice. |
ussd_service_op | TLV | This parameter is used to identify the required USSD Service type when interfacing to a USSD system. | N/A |
network_error_code | TLV | N/A | Network Error Code. May be present for Intermediate Notifications and SMSC Delivery Receipts |
message_state | TLV | N/A | Message State. Should be present for SMSC Delivery Receipts and Intermediate Notifications. |
receipted_message_id | TLV | N/A | SMSC message ID of receipted message Should be present for SMSC Delivery Receipts and Intermediate Notifications. |