Back to top

Veoo SMPP API

This API provides a gateway for allowing customers to send messages via SMPP.

SMPP API specification

SMPP v3.4 Protocol Implementation guide for GSM / UMTS (Standard documentation)

SMPP account details

  • Parameters
    • host: (required, String) - DNS endpoint, will be provided on connection stage. In case you cannot use DNS please connect to 54.247.109.144 which is static IP address.
    • port: (required, Integer) - will be provided on connection stage
    • username: (required, String) - your username
    • password: (required, String) - your password

Maximum instances (binds): 5 per SMPP account. Maximum throughput: 50 sms/s for both destinations (sent messages and DLRs/MOs).

Supported SMPP PDUs

  • PDUs
    • bind_transmitter / bind_transmitter_resp
    • bind_receiver / bind_receiver_resp
    • bind_transceiver / bind_transceiver_resp
    • enquire_link / enquire_link _resp
    • unbind / unbind_resp
    • submit_sm / submit_sm_resp
    • deliver_sm / deliver_sm_resp
    • generic_nack

Source Address

Sent to Veoo Type Of Number (TON) Description Number Plan Indicator (NPI) Description Arrive on handset
461234567889 0x00 Unknown 0x01 ISDN/telephone numbering plan (E163/E164) 461234567889
1234567889 0x00 Unknown 0x01 ISDN/telephone numbering plan (E163/E164) 1234567889
461234567889 0x01 International 0x01 ISDN/telephone numbering plan (E163/E164) +461234567889
1234567889 0x02 National 0x01 ISDN/telephone numbering plan (E163/E164) 461234567889
88998 0x03 Network Specific 0x00 Unknown 88998
Veoo 0x05 Alphanumeric 0x00 Unknown Veoo
  • Type of source address is defined by the source address TON and NPI parameters
    • Alphanumeric sender is limited to a maximum length of 11 characters.
    • MSISDN sender maximum length is 16.
    • Special characters like white space and underscores are not recommended to use within originator text as we cannot guarantee delivery of these messages.

Destination address

Sent to Veoo Type Of Number (TON) Description Number Plan Indicator (NPI) Description
461234567889 0x01 International 0x01 MSISDN

MSISDN Format

In GSM, MSISDN is built up as:

MSISDN CC + NDC + SN
CC Country Code
NDC National Destination Code
SN Subscriber Number

For further information on the MSISDN format, see the ITU-T specification E.164.

Throughput and throttling

Throughput is the maximum number of MT messages per second that can be sent from the SMPP account to Veoo. Default value is 30 for both destinations (sent messages and DLRs/MOs). To increase the value, contact your account manager.

Note, in case you hit your throughput limit, the submissions will be rejected with throttling error “SMPP_ESME_RTHROTTLED = 0x00000058” in submit_sm_resp. In this case, you will need to re-submit the messages.

The throughput can be restricted by the capacity of the operator receiving the MT messages.

It is recommended to set your enquire_link requests to 60 seconds.

esm_class Parameter

The esm_class parameter is used to indicate special message attributes associated with the short message.

Default Setting: 0x00.

  • If an ESME encodes GSM User Data Header information in the short message user data, it must set the UDHI flag in the esm_class field (see next paragraph).

  • If the SMSC delivers a short message that contains GSM User Data Header information encoded in the short_message or message_payload parameter, it must set the UDHI flag in the esm_class field.

  • For GSM networks, the concatenation related optional parameters (sar_msg_ref_num, sar_total_segments, sar_segment_seqnum) or port addressing related optional parameters (source_port, destination_port) cannot be used in conjunction with encoded User Data Header in the short_message (user data) field. This means that the above listed optional parameters cannot be used if the User Data Header Indicator flag is set.

ESME -> SMSC PDU Encoding

  • The esm_class is encoded as follows in the submit_sm (ESME -> SMSC) PDU:

Note: We do recommend to use esm_class=0 or esme_class=3 for short messages. For concatenated messages please check the next paragraph.

Dictation Bits 7 6 5 4 3 2 1 0 Meaning
Messaging Mode 1-0 x x x x x x 0 0 Default SMSC Mode (e.g. Store and Forward)
Messaging Mode 1-0 x x x x x x 0 1 Datagram mode
Messaging Mode 1-0 x x x x x x 1 0 Forward (i.e. Transaction) mode
Messaging Mode 1-0 x x x x x x 1 1 Store and Forward mode (use to select Store and Forward mode if Default SMSC Mode is non Store and Forward)
Message Type 5-2 x x 0 0 0 0 x x Default message Type (i.e. normal message)
Message Type 5-2 x x 0 0 1 0 x x Short Message contains ESME Delivery Acknowledgement
Message Type 5-2 x x 0 1 0 0 x x Short Message contains ESME Manual/User Acknowledgement
GSM Network Specific Features 7-6 0 0 x x x x x x No specific features selected
GSM Network Specific Features 7-6 0 1 x x x x x x UDHI Indicator (only relevant for MT short messages)
GSM Network Specific Features 7-6 1 0 x x x x x x Set Reply Path (only relevant for GSM network)
GSM Network Specific Features 7-6 1 1 x x x x x x Set UDHI and Reply Path (only relevant for GSM network)
  • The esm_class parameter is encoded as follows in a deliver_sm (SMSC -> ESME) PDU:

Note: All unlisted values for bits 5-2 and 7-6 are reserved.

Note: We do recommend to use esm_class=4 in deliver_sm PDU.

Dictation Bits 7 6 5 4 3 2 1 0 Meaning
Messaging Mode 1-0 x x x x x x x x not applicable - ignore bits 0 and 1
Message Type 5-2 x x 0 0 0 0 x x Default message Type (i.e. normal message)
Message Type 5-2 x x 0 0 0 1 x x Short Message contains SMSC Delivery Receipt
Message Type 5-2 x x 0 0 1 0 x x Short Message contains SME Delivery Acknowledgement
Message Type 5-2 x x 0 0 1 1 x x reserved
Message Type 5-2 x x 0 1 0 0 x x Short Message contains SME Manual/User Acknowledgement
Message Type 5-2 x x 0 1 0 1 x x reserved
Message Type 5-2 x x 0 1 1 0 x x Short Message contains Conversation Abort (Korean CDMA)
Message Type 5-2 x x 0 1 1 1 x x reserved
Message Type 5-2 x x 1 0 0 0 x x Short Message contains Intermediate Delivery Notification
GSM Network Specific Features 7-6 0 0 x x x x x x No specific features selected
GSM Network Specific Features 7-6 0 1 x x x x x x UDHI Indicator set
GSM Network Specific Features 7-6 1 0 x x x x x x Set Reply Path
GSM Network Specific Features 7-6 1 1 x x x x x x Set UDHI and Reply Path

Concatenated Messages

In order to send long (concatenated) message via SMPP the esm_class parameter must be set as one of two possible options:

  1. esm_class: 64 = 00000x40

  2. esm_class: 67 = 00000x43

The concatenation UDH values are inserted at the start of the message body.

Concatenation UDH structure:

Byte Description
05 Length of UDH (5 bytes)
00 Indicator for concatenated message
03 Subheader Length (3 bytes)
XX message identification - can be any hexadecimal number but needs to match the UDH Reference Number of all concatenated SMS
YY Number of pieces of the concatenated message
ZZ Number of this part (used by the mobile to concatenate the split messages)

Remark: The maximum number of characters per concatenated message depends on the encoding:

  1. 153 characters for 7-bit encoding (e.g. Latin-1/9 and GSM8)

  2. 134 characters for 8-bit encoding (Binary)

  3. 67 characters for 16-bit encoding (Unicode)

Validity Period

Currently, there is a way to define a global “validity_period” header for messages routed via SMPP connections.

“Validity Period” can be added to the config file.

The SMPP time format is documented in section 7.1 of the SMPP v3.4 spec, which I’ve excerpted below. As this setting will currently apply to all messages, you’ll want to be sure to use “relative” format.


SMPP Time Format

In this interface, all time/date related fields will be in ASCII with the following format: “YYMMDDhhmmsstnnp” where “YY” last two digits of the year (00-99) “MM” month (01-12) “DD” day (01-31) “hh” hour (00-23) “mm” minute (00-59) “ss” second (00-59) “t” tenths of second (0-9) “nn” Time difference in quarter hours between local time (as expressed in the first 13 octets) and UTC (Universal Time Constant) time (00-48). “p” - “+” Local time is in quarter hours advanced in relation to UTC time. “-” Local time is in quarter hours retarded in relation to UTC time. “R” Local time is relative to the current SMSC time.

Note: Where responses are reported by the SMSC the local time of the SMSC will be given, and the format will be “YYMMDDhhmmss”, with the same definitions as above.

7.1.1.1 Absolute Time format This is the default format used by SMPP. Scheduled delivery times and expiry times are specified in their global UTC format, including the quarter hour offset and direction symbol “+” or “-”.

7.1.1.2 Relative Time Format Relative Time can be indicated by setting the UTC orientation flag to “R” instead of “+” or “-”. In this form, the SMSC interprets the time format as the number of years, months, days, hours, minutes and seconds from the current SMSC time. Values for tenths of seconds “t” and UTC offset “nn” are ignored and should be set to “0” and “00” respectively. For example, the following time format “020610233429000R”:

  • would be interpreted as a relative period of 2 years, 6 months, 10 days, 23 hours, 34 minutes and 29 seconds from the current SMSC time. Note: An SMSC operator may choose to impose a limit on relative time offsets, thus either rejecting a message that exceeds such a limit or reducing the offset to the maximum relative time allowed.

Default validity period on Veoo platform set to 72 hours.

Example of standard SMPP configuration

Below is example of standard SMPP bind configuration file (taken from Kannel):

group = smsc
    smsc = smpp
    smsc-id = smsc_veoo
    allowed-smsc-id = smsc_veoo
    smsc-admin-id = smsc_veoo
    host = smpp-eu.veoo.com
    port = 7300 // or 7400 for SSL connection
    transceiver-mode = true
    throughput = 30 // default value
    smsc-username = <username provided by your account manager>
    smsc-password = <password provided by your account manager>
    validityperiod = 4320 // 72 hours as accepted by most of the mobile carriers and suppliers, optional parameter
    interface-version = 34
    system-type = ""
    log-file = "/opt/kannel/var/log/smsc_veoo.log"
    log-level = 0
    enquire-link-interval = 60

Delivery Reports

SMPP provides for return of an SMSC delivery receipt via the deliver_sm PDU, which indicates the delivery status of the message. The informational content of an SMSC Delivery Receipt is inserted into the short_message parameter of the deliver_sm operation. The default format for this Delivery Receipt is same as proposed by SMPP 3.4 specification Appendix B:

id:IIIIIIIIII sub:SSS dlvrd:DDD submit date:YYMMDDhhmm done date:YYMMDDhhmm stat:DDDDDDD err:E text: . . . . . . . . .

Where:

  • id - the message ID allocated to the message by the server.

  • sub - the number of short messages originally submitted.

  • dlvrd - the number of short messages delivered.

  • submit date - the date and time at which the short message was submitted.

  • done date - the date and time at which the short message reached its final state stat - the final status of the message.

  • stat - the final status of the message.

  • err - where appropriate this may hold a network specific error code or an SMSC error code.

  • text - the first 20 characters of the short message.

Please note SMPP v3.3 and v3.4 differ, such that message IDs returned from an SMPP 3.3 connection are encoded as hex whereas 3.4 SMPP connections return message IDs as ASCII encoded integers.

Error Specification

Messages states

The error codes are provided in status reports according to the SMPP Protocol Specification v3.4 Issue 1.2 Appendix B. The following are the error codes Veoo LTD will be sending (please note that those errors are also sent for the messages submitted via HTTP API):

Error code Description State Label Action Required
000 VEOO_DELIVERED DELIVERD Delivered to handset
041 VEOO_REJ_ORIGINBLOCKED REJECTD Shortcode / Network / User combination is disallowed Remove from database
042 VEOO_REJ_BLOCKED REJECTD Subscriber is blocked Remove from database
043 VEOO_REJ_STOPPED UNDELIV Subscriber in stopped state Remove from database
044 VEOO_REJ_INVSERVICE REJECTD Missing or Invalid Service ID Adjust service_id value
045 VEOO_REJ_AVE REJECTD Age verification failed Remove from database
046 VEOO_REJ_DEAD REJECTD Handset was not chargeable for a long time This rejection occurs when no MTs have been delivered to this MSISDN for this service for an extended period. It indicates the MSISDN is no longer billable by this service, and should be removed from your billing database in accordance with country compliance regulations.
048 VEOO_REJ_MVNOMSISDN REJECTD MVNO MSISDN cannot be billed Remove from database
049 VEOO_REJ_NOMORE_SMS UNDELIV All allowed charged messages sent No need to continue to submit the messages this day. Please continue next day.
050 VEOO_FAIL_QUITEHRS UNDELIV Quite hours Please try to resubmit a message in allowed hours. For most networks it will be daytime hours.
051 VEOO_REJ_SBSRBD UNDELIV Subscriber is already subscribed Subsriber is already subsribed to the service. No need to retry
056 VEOO_FAIL_BADSUB UNDELIV Unknown subscriber HLR or remove from database
057 VEOO_FAIL_EXPIRED EXPIRED Network time out Retry later
058 VEOO_FAIL_NOCREDIT UNDELIV Insufficient credit Retry as per operator requirements
059 VEOO_FAIL_PORTEDOUT UNDELIV MSISDN is ported away from operator HLR or remove from database
060 VEOO_FAIL_UNKNOWN UNDELIV Unknown error Report to Veoo
061 VEOO_FAIL_UNSUPPORT UNDELIV Handset error Retry or report to Veoo
062 VEOO_FAIL_ABSENTSUB UNDELIV Absent subscriber HLR or remove from database
063 VEOO_FAIL_ROAMING UNDELIV Subscriber is roaming Retry later
064 VEOO_FAIL_SYSERROR UNDELIV System error Report to Veoo
065 VEOO_FAIL_NOSMSSERVICE UNDELIV Teleservice not provisioned Remove from database
066 VEOO_FAIL_EXPIRED UNDELIV Expired Report to Veoo
067 VEOO_FAIL_TEMPERR UNDELIV Temporary error Report to Veoo
068 VEOO_FAIL_REJCTD UNDELIV Rejected Report to Veoo
069 VEOO_OA_BLOCKED UNDELIV Call bared Remove from database
070 VEOO_FAIL_RJCTD REJECTD Rejected Report to Veoo
071 VEOO_SPAM_RJCTD UNDELIV Spam/Flood Protection Retry later
072 VEOO_SS7_ERR UNDELIV Routing/SS7 error Report to Veoo
073 VEOO_SPAM_DLTD DELETE Spam/Flood Protection Retry later
074 VEOO_FAIL_ABSENTSBXP EXPIRED Absent subscriber HLR or remove from database
075 VEOO_FAIL_UNKN UNKNOWN Unknown error Report to Veoo
076 VEOO_RJCTD_ABSENTSBXP REJECTD Absent subscriber HLR or remove from database
077 VEOO_REJ_NOTSBSRBD REJECTD User is not subscribed to the service Remove from database
078 VEOO_REJ_NOCREDIT REJECTD Insufficient credit Retry as per operator requirements
079 VEOO_EXP_UNSUPPORT EXPIRED Handset error Retry or report to Veoo
080 VEOO_FAIL_ENC REJECTD Incorrect data_coding value Adjust data_coding value
081 VEOO_FAIL_VDPR EXPIRED Message validity period has expired Retry later
082 VEOO_EXP_BLOCKED EXPIRED Subscriber is blocked Remove from database
083 VEOO_RJCTD_BADSUB REJECTD Unknown subscriber Remove from database
084 VEOO_OA_BLOCKED_EXP EXPIRED Call Barred Remove from database
086 VEOO_EXP_ROAMING EXPIRED Subscriber is roaming Retry later
087 VEOO_FAIL_INVALID_OA UNDELIV Invalid Source Address Please use allowed/valid source address
088 VEOO_FAIL_INVALID_ESM REJECTD Invalid esm_class field data Please use appropriate esm_class, as per SMPP spec
089 VEOO_FAIL_INVALID_ESM REJECTD Invalid message length That happens when you submit concatenated message and split its parts incorrectly. Please refer to https://docs.veoo.com/docs/smpp_docs#header-concatenated-messages for more details
090 VEOO_FAIL_SRV_RSRS UNDELIV Operation was rejected due to insufficient server resources There is a load on MNO side, please re-submit the message later
091 VEOO_MNOSUBSEXP EXPIRED Subscription has expired on Operator side Last successful billing was done more than 90 days earlier, user is unsubscribed on operator’s side - please unsibsribe end-user
092 VEOO_FAIL_INVALID_UDH REJECTD Invalid UDH length indicator The message was submitted with unsupported or wrong UDH indicator.
093 VEOO_MT_QIF UNDELIV MT Queue is Full There is a queue that is full. Please retry later.
205 VEOO_DND_BLOCK UNDELIV DND Restriction In case subsriber would like to receive messages ask him to contact operator in order to remove DND till then do not retry

Encoding

Default SMSC encoding

Data Coding Description
0x00 Default GSM 7 bit encoding
0x03 ISO8859-1 (Latin-1), only characters within GSM-7 character table can be parsed to handset
0x08 UCS2/UTF-16BE

GSM 7 bit default alphabet and extension table

3GPP TS 23.038 / GSM 03.38
x0 x1 x2 x3 x4 x5 x6 x7 x8 x9 xA xB xC xD xE xF
0x @ £ $ ¥ è é ù ì ò Ç LF Ø ø CR Å å
1x Δ _ Φ Γ Λ Ω Π Ψ Σ Θ Ξ ESC Æ æ ß É
2x SP ! # ¤ % & ( ) * + , . /
3x 0 1 2 3 4 5 6 7 8 9 : ; < = > ?
4x ¡ A B C D E F G H I J K L M N O
5x P Q R S T U V W X Y Z Ä Ö Ñ Ü §
6x ¿ a b c d e f g h i j k l m n o
7x p q r s t u v w x y z ä ö ñ ü à
1B 0x FF
1B 1x ^
1B 2x { } \
1B 3x [ ~ ]
1B 4x |
1B 5x
1B 6x
1B 7x

ISO/IEC 8859-1 table, Latin-1

ISO/IEC8859-1
x0 x1 x2 x3 x4 x5 x6 x7 x8 x9 xA xB xC xD xE xF
0x
1x
2x SP ! # $ % & ( ) * + , . /
3x 0 1 2 3 4 5 6 7 8 9 : ; < = > ?
4x @ A B C D E F G H I J K L M N O
5x P Q R S T U V W X Y Z [ \ ] ^ _
6x ` a b c d e f g h i j k l m n o
7x p q r s t u v w x y z { { } ~
8x
9x
Ax NBSP ¡ ¢ £ ¤ ¥ ¦ § ¨ © ª « ¬ SHY ® ¯
Bx ° ± ² ³ ´ µ · ¸ ¹ º » ¼ ½ ¾ ¿
Cx À Á Â Ã Ä Å Æ Ç È É Ê Ë Ì Í Î Ï
Dx Ð Ñ Ò Ó Ô Õ Ö × Ø Ù Ú Û Ü Ý Þ ß
Ex à á â ã ä å æ ç è é ê ë ì í î ï
Fx ð ñ ò ó ô õ ö ÷ ø ù ú û ü ý þ ÿ

Last updated at 18 Sep 2019 13:09