SMPP API Supplementary Documentation
Transcript of SMPP API Supplementary Documentation
SMPP API Supplementary Documentation
SMPP API Supplementary Documentation
MessageMedia - SMPP API Supplementary Documentation 2
IntroductionThis document lists the specific features of the SMPP specification supported by the MessageMedia SMPP API.
The MessageMedia SMPP API supports v3.4 of the SMPP specification (except where indicated). http://opensmpp.org/specs/SMPP_v3_4_Issue1_2.pdf
Table of Contents
1. Connection details 3
- 1.1 Server 3
- 1.2 Security 3
- 1.3 Credentials 3
- 1.4 Bind types 3
- 1.5 Simultaneous bind limits 3
- 1.6 Throughput 4
- 1.7 Heartbeating / keep-alive (enquire_link) 4
2. SMPP command support 4
3. Message sending 5
- 3.1 TON and NPI values 5
3.1.1 Type of Number (TON) 5
3.1.2 Number Plan Indicator (NPI) 5
- 3.2 Source address 6
- 3.3 Destination address 6
- 3.4 Scheduled delivery 6
- 3.5 Validity period 7
- 3.6 Requesting delivery receipts (DR) (registered_delivery) 7
- 3.7 Character encoding (data_coding) 7
- 3.8 Long message support 8
3.8.1 About long message handling 8
- 3.9 Custom TLV (optional parameters) 9
4. Receiving DR (delivery receipt) messages 9
- 4.1 Message ID 9
- 4.2 Message (DR) statuses 10
4.2.1 Message status for long (concatenated) messages 10
5. Receiving MO (mobile originated) messages 11
- 5.1 Message ID 11
- 5.2 Character encoding 11
- 5.3 Long messages 11
6. Further information 11
SMPP API Supplementary Documentation
MessageMedia - SMPP API Supplementary Documentation 3
1. Connection details1.1 Server
Address smpp.messagemedia.com
Port 2775
Port (TLS) 3775
The server is located in Sydney, Australia.
1.2 Security
SMPP over SSL / TLS is supported. The certificate is issued to *.messagemedia.com by Thawte.
1.3 Credentials
• Username (SMPP system_id) - maximum length of 15 ASCII characters (16 octets, including NULL terminator)
• Password - maximum length of 8 ASCII characters
These will be provided to you by the MessageMedia support team.
1.4 Bind types
The MessageMedia SMPP API supports the following bind types:
Bind type Capabilities SMPP PDU Required fields Notes
Transmitter (Tx) Submit MT messages bind_transmittersystem_id; password • system_type
is not required
• unbind is supported to cleanly unbind
Receiver (Rx)Receive MO and DR type messages
bind_receiversystem_id; password
Transceiver (TRx)Submit MT and receive MO and DR messages
bind_transceiversystem_id; password
1.5 Simultaneous bind limits
Simultaneous bind limits are configurable for each bind type. Bind limit policy enforcement is configurable to:
• Prevent new: additional binds beyond the configured limit are not accepted (default)
• Kick oldest: Accept the new bind request and terminate (after ~ 30 sec) the oldest bind for the account
MessageMedia will advise you of the number of simultaneous connections available for your account. Additional binds may be provided, based on your needs.
SMPP API Supplementary Documentation
MessageMedia - SMPP API Supplementary Documentation 4
1.6 Throughput
Throughput per bind is dependent on the SMPP client capabilities and location, but rates of up to 60 MT/sec for each bind are possible in ideal circumstances.
1.7 Heartbeating / keep-alive (enquire_link)
Either server or client initiated heartbeats must be enabled (but not necessarily responded to).
Client initiated heartbeat
enquire_link• SMPP API will respond with enquire_link_resp
• Option to drop bind if no request is received after a timeout
Server initiated heartbeat
enquire_link• Interval can be configured
• Can be configured to drop the bind if a response from the client is not received
2. SMPP Command SupportEither server or client initiated heartbeats must be enabled (but not necessarily responded to).
Scope Command PDU PDU response Supported? Notes
Session management
bind_transmitter
bind_transmitter_resp
bind_receiverbind_receiver_resp
bind_transceiver
bind_transceiver_resp
unbind unbind_resp
enquire_linkenquire_link_resp
Message submission & delivery
submit_sm submit_sm_resp
Refer below for details
deliver_sm deliver_sm_resp
Ancillary generic_nack deliver_sm_resp
If we receive a generic_nack, delivery will be retried several times, before giving up. The connection will be unbound and you will need to re-connect.
SMPP API Supplementary Documentation
MessageMedia - SMPP API Supplementary Documentation 5
3. Message Sending3.1 TON and NPI values
3.1.1 Type of Number (TON)
TON Definition Source Destination Notes
0 UnknownMay work for certain numbers, but is not recommended; contact MessageMedia for more details.
1 InternationalTON 1 is the preferred value for most destination numbers. Refer examples below.
2 National
3 Network Specific
4 Subscriber number
5 Alphanumeric
6 Abbreviated
3.1.2 Number Plan Indicator (NPI)
NPI Definition Source Destination Notes
0 Unknown
1 ISDN (E.164) Preferred
6 Land mobile
8 National
SMPP API Supplementary Documentation
MessageMedia - SMPP API Supplementary Documentation 6
3.2 Source address
You may specify null for source_addr and a source address will be assigned from the MM rotary or based on your account preferences.
Number format Example(s) TON value NPI value Notes
International (E.164)+61497675300,61497675300
1 1 This is the preferred format
National 0497675300 2 1
Shortcode 19926646 3, 4
Either TON is acceptable for use of a shortcode
• Maximum length is 20 characters, butmany downstream providers onlysupport 11 characters
• 0-9, a-z, A-Z only; characters such as . - +may be supported, but delivery can notbe guaranteed
Alphanumeric MsgMedia 5
3.3 Destination address
Number format Example(s) TON value NPI value Notes
International (E.164)+61497675300,61497675300
1 1 This is the preferred format
National 0497675300 2 1
Shortcode 19926646Delivery to shortcode numbers is not supported.
Alphanumeric MsgMediaDelivery to alphanumeric addresses is not supported.
3.4 Scheduled delivery
Not currently supported via our SMPP API.
Scheduling is available by using our REST API.
SMPP API Supplementary Documentation
MessageMedia - SMPP API Supplementary Documentation 7
3.5 Validity period
Customers may specify a validity period for a message, after which the message will be discarded. If the message is passed to a downstream service provider who does not support the validity period, it may be delivered after the validity period specified.
Both absolute and relative validity periods are supported.
3.6 Requesting delivery receipts (DR) (registered_delivery)
Delivery receipts may be requested for MT messages by using the registered_delivery parameter. The SMPP API does not currently support returning DRs only on failure or success.
Refer to DR statuses for details of the status values being returned.
3.7 Character encoding (data_coding)
The MessageMedia SMPP API supports the following character sets. The default character set (DCS=0) is GSM Extended 03.38. Refer:
https://en.wikipedia.org/wiki/GSM_03.38#GSM_7-bit_default_alphabet_and_extension_table_of_3GPP_TS_23.038_.2F_GSM_03.38
Character set Support DCS value Message unit Notes
GSM 03.38 basic & extended characters
0140 bytes (octets) = 160 GSM 03.38 basic characters
• Supported for both sending (MT) and receiving (MO)
• GSM Extended characters such as { ^ and € require 2-bytes
Latin 1 / ISO-8859-1 3140 bytes (octets) = 140 ISO-8859-1 characters
MT only
UCS-2 (ISO/IEC-10646) 8140 bytes (octets) = 70 UCS-2 characters
This character set allows use of characters in the Unicode BMP (Basic Multilingual Plane)
SMPP API Supplementary Documentation
MessageMedia - SMPP API Supplementary Documentation 8
3.8 Long message support
The MessageMedia SMPP API supports the sending of messages greater than 160 standard GSM characters. Long messages may be sent using one of the following methods:
Long message method Limits Notes
short_message 255 octetsThe MM gateway will handle segmentation of your message
message_payload 65,535 octets (configurable)
UDH concatenation
• 134 bytes available for message content
• 6 bytes used by UDH header
• Maximum of 255 segments supported
Message content may contain up to 153 GSM 03.38 basic characters or 67 UCS-2 encoded characters
SAR concatenation • 255 segments
3.8.1 About long message handling
Note the following important points in relation to long message handling:
• A message will be considered ‘long’ when the content is more than 140 bytes (octets). This equates to 160 basic GSM characters or 70 UCS-2 encoded characters
• Extended GSM characters require an escape character, and thus consume two bytes.
• Where content includes characters outside of the GSM character set, the message may be sent as Unicode (UCS-2) in 70 character segments.
• Long messages may be concatenated and re-segmented in order to ensure the content can be delivered as intended.
• All segments of a long message must be received by the SMPP API for the message to be successfully delivered.
• MessageMedia will always try to use downstream service providers that support re-concatenation of long messages, but in rare cases this may not be possible.
SMPP API Supplementary Documentation
MessageMedia - SMPP API Supplementary Documentation 9
3.9 Custom TLV (optional parameters)
The MessageMedia SMPP API supports the sending of messages greater than 160 standard GSM characters. Long messages may be sent using one of the following methods:
Name Tag Length Type Description / purpose Use
sending_account
0x1400 1 ~ 65,535 C-Octet String
When authorised to do so, SMPP clients may include this TLV in submit_sm requests to specify the account that the client is sending on behalf of.
May be optional, required or forbidden depending on the configuration of the SMPP account (system ID).
Contact MessageMedia support for more information.
message_flags
0x1401 1 ~ 65,535 C-Octet String
This parameter allows SMPP clients to pass specific flags that can be used to control how MessageMedia sends a message.
Contact MessageMedia support for more information.
May be optional, required or forbidden depending on the configuration of the SMPP account (system ID).
Only characters Aa-Zz and _ (underscore) are allowed. Case in-sensitive.
4. Receiving DR (delivery receipt) messages4.1 Message ID
The receipted_message_id parameter will contain the message ID of the MT message being receipted.
This will be in the format of UUID, version 4, random. These are in the form: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
SMPP API Supplementary Documentation
MessageMedia - SMPP API Supplementary Documentation 10
4.2 Message (DR) statuses
The MessageMedia SMPP API will return message status as a delivery receipt (DR) type message, using a deliver_sm command. Status will be encoded in both:
• the stat sub-field of the short_message parameter, as an abbreviated text status value;
• the message_state optional parameter, as a value
The API makes use of the following message statuses:
Message statusMessage_state value
Stat (short_message)
Type Description
ENROUTE 1 ENROUTE IntermediateThe message is being processed by the messaging centre or has been submitted to a downstream service provider for delivery.
DELIVERED 2 DELIVRD FinalMessage delivery has been confirmed by the service provider, including to the handset (where possible)
EXPIRED 3 EXPIRED FinalThe message validity period expired and the message has been discarded.
UNDELIVERABLE 5 UNDELIV Final
The message can not be delivered. Reasons may include the handset being offline, number being invalid.
An error code value may provide further information.
UNKNOWN 7 UNKNOWN n/aAn error occurred in the SMPP server. The message status can not be returned.
REJECTED 8 REJECTD Final
The message will not be delivered - permanent failure. Reasons may include the destination number being blocked; an account usage threshold being reached;
An error code value may provide further information.
4.2.1 Message status for long (concatenated) messages
Where delivery receipts have been requested for a long (UDH or SAR concatenated) message, the SMPP API will produce DRs for each message segment. Where segments in a long message have different status values, this will be represented in the DRs.
SMPP API Supplementary Documentation
MessageMedia - SMPP API Supplementary Documentation 11
ABOUT MESSAGEMEDIAAs Australia’s largest business mobile messaging service provider and a leading player globally, our mission is to connect our customers with theirs through innovative mobile messaging solutions. Our unparalleled messaging platform ensures customer messages arrive on time and deliver optimum return on investment. The platform is underpinned by our service reliability and quality support to ensure communication solutions are never compromised.
AUSTRALIALevel 24 367 Collins Street Melbourne VIC 3000
T: 1800 009 767E: [email protected]
www.messagemedia.com.au
USA580 Howard Street, Suite 102 San Francisco CA 94111
T: 888-799-9767E: [email protected]
www.messagemedia.com
UKLevel 6 52 Grosvenor Gardens Victoria London SW1W 0AU
T: 0808 234 8246E: [email protected]
www.messagemedia.co.uk
5. Receiving MO (mobile originated) messages5.1 Message ID
Where applicable, MO responses will include the ID of the MT message being responded to within the receipted_message_id parameter.
5.2 Character encoding
MOs will use GSM 03.38 basic & extended character encoding, and DCS value of 0.
5.3 Long messages
If the message content is =< 254 octets, it will be contained within the short_message parameter of the deliver_sm request.
Long MO messages are supported, and depending on the SMPP account configuration, are delivered as:
• Single deliver_sm request, content contained in message_payload. Maximum length of message_payload is configurable.
• Content segmented over multiple MO messages
- Use message_payload if configured; otherwise short_message
- concatenated with either SAR or UDH
- if neither enabled, then as individual message fragments
6. Further informationIf you require further assistance, or would like more information on working with our SMPP API, please contact our Support team.