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. Note that Vibes only supports messages up to 900 characters. Messages over 900 characters may be truncated.

📘

The submit_sm protocol 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 TON0 - for messages sent via Shortcode or Longcode
5 - for messages sent via Alphanumeric Code (non-US)
Source NPIAlways 0
Destination TONAlways 0 - Non-US/Canada MDNs must be sent in E.164 format.
Destination NPIAlways 0
System TypeNot used - Leave blank.
Service TypeNot used - Leave blank.
Validity PeriodNot 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_sm operation. This will only be sent if the ESME had requested a delivery receipt via the registered_delivery parameter. The delivery receipt data relating to the original short message will be included in the short_message field of the deliver_sm.
  • SME Delivery Acknowledgement: The user data of the SME delivery acknowledgement is included in the short_message field of the deliver_sm.
  • SME Manual/User Acknowledgement: The user data of the SME delivery acknowledgement is included in the short_message field of the deliver_sm.
  • Intermediate Notification: The user data of the SME delivery acknowledgement is included in the short_message field of the deliver_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 NameSize OctetsTypeSendingReceiving
command_length4IntegerSet to overall length of PDU.Set to overall length of PDU.
command_id4Integersubmit_smdeliver_sm
command_status4IntegerNot used. Set to NULL.Not used. Set to NULL.
sequence_number4IntegerSet 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 NameSize OctetsTypeSendingReceiving
service_typeVaries. Max of 6C-Octet stringUsed 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_ton1IntegerType 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_npi1IntegerNumbering 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_addrVaries. Max of 21.C-Octet StringAddress 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_ton1IntegerType of Number (TON) for destination.Type of Number (TON) for destination.
dest_addr_npi1IntegerNumbering Plan Indicator (NPI) for destination.Numbering Plan Indicator (NPI) for destination.
destination_addrVaries. Max 21.C-octet stringDestination address of this short message. For mobile terminated messages, this is the directory number of the recipient MS.Destination address of destination SME.
esm_class1IntegerIndicates message mode and message type.Indicates Message Type and enhanced network services
protocol_id1IntegerProtocol identifier. Network-specific field.Protocol identifier. Network-specific field.
priority_flag1IntegerDesignates the priority level of the message.Designates the priority level of the message.
schedule_delivery_time1 or 17C-Octet StringThe 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_period1 or 17C-Octet StringThe 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.
registered_delivery1IntegerIndicator 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_flag1IntegerFlag indicating if submitted message should replace an existing message.This field is unused for deliver_sm. It must be set to NULL.
data_coding1IntegerDefines 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_id1IntegerIndicates 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_length1IntegerLength in octets of the short_message user data.Length in octets of the short_message user data.
short_messageVaries. 0 to 254.Octet stringUp 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 NameTypeSendingReceiving
user_message_referenceTLVESME-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_portTLVIndicates 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_subunitTLVThe subcomponent in the destination device which created the user data.N/A
destination_portTLVIndicates 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_subunitTLVThe subcomponent in the destination device for which user data is intended.N/A
sar_msg_ref_numTLVThe reference number for a particular concatenated short message.The reference number for a particular concatenated short message.
sar_total_segmentsTLVIndicates 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_sendTLVIndicates that there are more messages to follow for the destination address.N/A
payload_typeTLVDefines the type of payload (e.g. WDP, WCMP, etc.)Defines the type of payload (e.g. WDP, WCMP, etc.)
message_payloadTLVContains 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_indicatorTLVIndicates the level of privacy associated with the message.Indicates the level of privacy associated with the message.
callback_numTLVA 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_indTLVDefines 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_atagTLVAssociates 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_subaddressTLVThe subaddress of the message originator.The subaddress of the message originator.
dest_subaddressTLVThe subaddress of the message destination.The subaddress of the message destination.
user_response_codeTLVA user response code. The actual response codes are implementation specific.A user response code. The actual response codes are SMS application specific.
display_timeTLVProvides the receiving MS with a display time associated with the message.N/A
sms_signalTLVIndicates the alerting mechanism when the message is received by an MS.N/A
ms_validityTLVIndicates validity information for this message to the recipient MS.N/A
ms_msg_wait_facilitiesTLVThis parameter controls the indication and specifies the message type (of the message associated with the MWI) at the mobile station.N/A
number_of_messagesTLVIndicates the number of messages stored in a mailboxN/A
alert_on_msg_deliveryTLVRequest an MS alert signal be invoked on message delivery.N/A
language_indicatorTLVIndicates the language of an alphanumeric text message.Indicates the language of an alphanumeric text message.
its_reply_typeTLVThe 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_infoTLVSession control information for Interactive Teleservice.Session control information for Interactive Teleservice.
ussd_service_opTLVThis parameter is used to identify the required USSD Service type when interfacing to a USSD system.N/A
network_error_codeTLVN/ANetwork Error Code. May be present for Intermediate Notifications and SMSC Delivery Receipts
message_stateTLVN/AMessage State. Should be present for SMSC Delivery Receipts and Intermediate Notifications.
receipted_message_idTLVN/ASMSC message ID of receipted message Should be present for SMSC Delivery Receipts and Intermediate Notifications.