Aerialink SMPP API 3.4 Documentation

Accessing the Aerialink SMSC over SMPP

The following details will be required for your ESME to connect with the Aerialink SMSC:

v5 Host: smpp5.aerialink.net
v4 Host: smsc.aerialink.net
Port: 2775 (Plain socket)
Port: 3550 (Secure socket - Transport Layer Security (TLS) 1.1 and 1.2 Compliant)
Mode: transmitter, receiver, or transceiver

Note: Aerialink recommends bind transceiver mode.

Note2: When binding in, always configure your server with the Aerialink DNS host name (smsc.aerialink.net) and not the IP address.

Authentication

Authentication is required to access the Aerialink SMPP API. The authentication requirements consist of two layers; Firewall and Credentials which are described below.

Firewall

Prior to accessing the Aerialink SMPP API, all accounts must white list their network server specific IP addresses (/32) or network subnet (/subnet). This can be done within the Aerialnk Platform portal under the Authentication section within the API area.

Credentials

All SMPP API connections require a SystemID and Password to be able to establish your bind to our gateway. Your credentials can be obtained within the Aerialnk Platform portal under the Authentication section within the API area.

Note that some accounts may have multiple credential sets depending on your specific configuration which you may have requested. Subsequently each credential set may have different related permissions to API resources or associated resource assets such as Short Codes, Long Codes, or Alphanumeric Codes used for Messaging services.

Configuration Settings

Account Configuration Settings

Refer to your account for the following configuration values:

• Host IP: This is the Aerialink SMSC Host Address
• Host Port: This is the Aerialink SMSC Host Port
• System Identifier: The username for your SMPP bind connection
• Password: The password for your SMPP bind connection

General Configuration Settings:

System Type

The system type is typically used to access unique or proprietary features of an SMSC. The default setting of “SMPP” can be used for the Aerialink network, however it is not currently required for your bind.

• system-type=SMPP

The address range for your ESME client

These values will tell your EMSE what format to process the message addressing as on the bind level. The recommended settings are “1” for both the TON and NPI. The address range is typically optional unless your EMSE requires it.
addr-ton=1
addr-npi=1
address-range=[optional]

Source Address for your ESME client

• source-ton=[X]
• source-npi=[Y]
  If the TON and NPI are not provided in your submit, the default for your account and code (Short Code, Long Code, Alphanumeric Code) will be used.

Source address for each SMS Submit

This value should match one of your provisioned Short Codes, Long Codes, or Alphanumeric Codes. For Long Codes the value should be set to the fully qualified Long Code which includes the Country Code, but without the +. Example: For Short Code “1234”, for Long Code “13105551212”, or for an Alphanumeric Code “AERIALINK” (This is an example only. Do not use these values in your configuration.)

• source-address=[1xxxYYYzzzz]

Address Range

This is the address range that your ESME client serves in yoru application. These values will tell your EMSE what format to process the message addressing as on the bind level. The recommended settings are “1” for both the TON and NPI. The address range is typically optional unless your EMSE requires it.
addr-ton=1
addr-npi=1
address-range=[optional]

Destination Address

The TON and NPI should be set to a value of “1” each.

• destination-ton=1
• destination-npi=1
• destination-address=[1xxxYYYzzzz]
  The destination address should always be in full international format excluding the plus sign. Example “13105551212” (This is an example only. Do not use this values in your configuration.)

Transaction Timeout

• Transaction Timeout: 60
• Idle Timeout: 0
• Keep Alive Timeout: 45
• Number Transceiver Connection: 1

Message Send Rate

This is how many messages per second your gateway is allowed to send. Aerialink imposes strict limits on SMPP bind throughput and depending on the communication code; Short Code, Long Code, or Alphanumeric Code there are strict limits imposed by Operators/Carriers which Aerialink will aggresively enforce. Please see Throughput Limits for more information. If you require additional throughput, please contact Aerialink Customer Support with your request for consideration.

• message-rate=10

Synchronous or Asynchronous Mode

Aerialink supports both Synchronous or Asynchronous ESME Modes. If your ESME is set to “synchronous” mode, yoru ESME will wait for the response from the Aerialink SMSC server when sending a message. Asynchronous mode will not. We recommend you run your ESME in Synchronous mode.

• mode=synchronous

Network Retry on Error

Your ESME should not retry a submit when there is a network error. Instead the issue should be addressed on the bind level to determine what the cause is for the network error.

Transient Retry on Errors

Your ESME should not retry a submit when there is a network error. Instead the issue should be addressed on the bind level to determine what the cause is for the network error.

TON and NPI

About TON & NPI

Type of Number (TON)

The Type of Number (TON) setting is used to tell both your EMSE the format of the addressing (bind addressing) that will be processed for inbound messages as well as tell the Aerialink network (source and destination addressing) how it should be processed for submits. There are three separate pairs of TON and NPI values; receiving addressing, source addressing, and destination addressing. These definitions are derived from the ETSI GSM 03.40 specification, which defines the SMS protocol. The SMPP specification defines the following TON values:

If you wish to specific a special value for the TON, the available options are:

• 0: Unknown
• 1: International
• 2: National
• 3: Network Specific
• 4: Subscriber Number
• 5: Alphanumeric
• 6: Abbreviated

Aerialink does not generally require specific TON values from your bind to our network. We store specific values as defaults for your routes, connections, and communication assets (Short Code, Long Code, Alphanumeric Code). See TON and NPI defaults below.

Numbering Plan Identification (NPI)

The Numbering Plan Identification setting is used to tell both your EMSE the numbering plan associated with your messaging. The SMPP specification defines the following TON values:

If you wish to specific a special value for the NPI, the available options are:

• Unknown = 0
• ISDN/telephone numbering plan (E163/E164) = 1
• Data numbering plan (X.121) = 3
• Telex numbering plan (F.69) = 4
• Land Mobile (E.212) =6
• National numbering plan = 8
• Private numbering plan = 9
• ERMES numbering plan (ETSI DE/PS 3 01-3) = 10
• Internet (IP) = 13
• WAP Client Id (to be defined by WAP Forum) = 18

Receive Timeout

The amount of time your ESME should wait while receiving a message
receive-timeout=20

Enquire Link or Ping Interval

This is how often your ESME will send the EnquireLink PDU to the Aerialink SMSC to verify that the connection is still healthy. Aerialink recommends this be set to 60 seconds.
ping-interval=60

Connection Attempts

This is the number of connection attempts your ESME will make until it gives up. This should be set to a reasonable number but not an infinite account. If you have a server that is unable to negotiate a connection but continues to try infinately you will risk your IP address or Subnet being black listed by the Aerialink firewall.
retries=[Customer Defined Value, Not Infinite]

Connection Retry Interval

This setting specifies how long your ESME will wait in between each connection attempt. Aerialink recommends 900 seconds which is 15 minutes. This will allow any temporary network issues to subside. Continued failues should be escalated to the Aerialink Support Team for assistance.
retry-interval=900

TON and NPI Defaults

Aerialink will generally default both your TON and NPI to the values they should be to insure your messages are delivered properly. If you have special reasons for controlling these settings on your side, please contact the Aerialink Support Team. The default values used by Aerialink are as follows:

Short Code (3 digits to 8 digits in length)

If the source code/address is a Short Code

• TON = 3
• NPI = 0

Long Code (10 digits to 15 digits in length, excludes the plus sign)

If the source code/address is a Long Code the recommended settings and default settings that Aerialink will use are:

• TON = 1
• NPI = 1

Alphanumeric

If the source code/address is Alphanumeric (contains both letters and numbers or only letters)

• TON = 5
• NPI = 0

SMPP Bind Configuration 

Your SMPP connection will maintain a socket connection to our network. The following bind configuration is recommended for your ESME.

Role and Mode

For SMPP API connections, Aerialink supports both the ESME and SMSC roles as well as all three operation types; transmitter, receiver, and transceiver modes. If you would like to connect as the SMSC role, please contact our customer support to obtain approval.

SMPP Bind Configuration Cache

At the point your bind is established your connection will cache both your provisioned Short Codes, Long Codes, Throughput Allowance, and your Routing details. Any changes to this configuration will require a rebind.

SMPP Official Specification

For details on the SMPP Specification, see SMPP API Specification Version 3.4.

Throughput Limits

The Aerialink SMPP API imposes two types of limits on the throughput use of our API unless special arrangements have been made. These limits exist to protect the Aerialink network as well as adhere to operator/carrier requirements. If you need your limits adjusted, please contact the Aerialink Support Team with a change request and an explanation for the change. Any violation of your account/resource limits may subject your service to immediate termination.

Account-Level Limits

SMPP Connection - Aggregate Maximum Request Limit

• 100,000 requests p/day
• 1,000,000 requests p/month

Resource-Specific Limits

Messages API

The table below details the throughput limit per each messaging route. for more information about registered number types, see Basic Code Information.

SMPP Route-Specific Status Codes

10DLC Route SMPP 3.4 Status Codes

Toll-Free Route SMPP 3.4 Status Codes

Toll-Free Route MM4 Status Codes

Data Coding Scheme Values

DCS values signify the Data Coding Scheme you have set to pass your messages to Aerialink. See the industry-universal list of DCS values below.

esm_class Parameter

The esm_class parameter is used to indicate special message attributes associated with SMS

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.
• 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

esm_class is encoded as follows in the submit_sm, submit_multi and data_sm (ESME -> SMSC) PDUs:

SMSC -> ESME PDU Encoding

The esm_class parameter is encoded as follows in a deliver_sm and data_sm (SMSC -> ESME) PDUs:

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