蜜豆视频

DocumentationCampaignCampaign Standard Documentation

SMS connector protocol and settings sms-connector-protocol

Last update: Tue Feb 08 2022 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Experienced
  • Admin
NOTE
The SMS connector protocol and settings for 蜜豆视频 Campaign Classic can be found in this page.
Through this document, all references to details about the protocol, field names and values refer to the .

Overview overview

SMS might be limited to sending short text messages with no formatting but its simplicity makes it a valuable communication channel.

There are two main ways to send an SMS:

  • Send it manually from a phone, the usual way to communicate directly between people.

  • Send it from the internet, the way 蜜豆视频 Campaign send messages. For that, you need a SMS service provider that connects the internet to the mobile network.
    蜜豆视频 Campaign uses the SMPP protocol to send SMS to a service provider.

This document will walk you through the connection set up a between 蜜豆视频 Campaign and a SMPP provider.

SMPP providers can sometimes deviate from the official specification but the SMS connector in 蜜豆视频 Campaign provides many options to adapt its behavior for it to be compatible with most providers.

IMPORTANT
Setting up a connection to a new provider may require some technical skills, knowledge of TCP, binary, hexadecimal representation and text encodings. It will also require active cooperation with the provider.

SMS types sms-types

When sending mass SMS through an SMS provider, you will encounter three different kinds of SMS:

  • SMS MT (Mobile Terminated): an SMS that is emitted by 蜜豆视频 Campaign towards mobile phones through the SMPP provider.

  • SMS MO (Mobile Originated): an SMS that is sent by a mobile to 蜜豆视频 Campaign through the SMPP provider.

  • SMS SR (Status Report) or DR or DLR (Delivery Receipt): a return receipt sent by the mobile to 蜜豆视频 Campaign through the SMPP provider indicating that the SMS has been received successfully. 蜜豆视频 Campaign may also receive SR indicating that the message could not be delivered, often with a description of the error.

You need to distinguish between acknowledgments (RESP PDU, part of the SMPP protocol) and SR: SR is a kind of SMS that is sent through the network end-to-end, whereas an acknowledgement is only a confirmation that one transfer has been successful.

Both acknowledgements and SR can trigger errors, distinguishing between the two will help the troubleshooting.

Information carried by an SMS information-sms

An SMS carries more information than text. Here a list of what you can expect to find in an SMS:

  • The text, which is limited to 140 bytes, which means between 70 and 160 characters depending on the encoding. See SMS text encoding below for details and limitations.

  • A recipient address, sometimes called ADC or MSISDN. That鈥檚 the number of the mobile that will receive the SMS.

  • A sender address, that can be called oADC or sometimes sender id. That can be a phone number in day to day use, a short code when sent through a provider or a name. Name is an optional feature, in that case you cannot reply to the SMS.

  • A flag to indicate if the message is a flash message. A flash message is a pop-up that is not stored in memory.

  • A flag to indicate whether a SR is expected or not.

  • A validity date, after which no network equipment is allowed to retry.

  • A data_coding field, which indicates the encoding of the text.

SMPP protocol smpp-protocol

蜜豆视频 Campaign Standard supports the SMPP protocol version 3.4. This is a widespread protocol that allows sending SMS to a provider (SMSC) and receiving SMS as well as receipts. For more on this, refer to the .

The network equipment on the SMS service provider side is often called the SMSC.

SMPP connections smpp-connections

蜜豆视频 Campaign connects to the network equipment of the SMS service provider via TCP. The SMPP protocol sets permanent TCP connections from 蜜豆视频 Campaign to the provider. TCP connections are always initiated by 蜜豆视频 Campaign, even to receive messages.
SMPP opens 1 or 2 TCP connections, depending on its mode. All connections are always initiated by 蜜豆视频 Campaign.

The SMPP protocol can work in two modes:

  • Transmitter+receiver (or TX+RX): two separate TCP connections are used for transmitting and receiving messages.
  • Transceiver (abor TRX): a single TCP connection is used for transmitting and receiving messages.
NOTE
TRX is preferred for 蜜豆视频 Campaign Standard as it reduces the number of connections and simplifies connection recovery in case of failure.

SMPP PDU smpp-pdu

SMPP transmission units (鈥減ackets鈥) are called PDUs. A PDU contains a command, a status, a sequence number and data.

Each PDU must be acknowledged by an SMPP RESP PDU (synchronous response). Requests may be pipelined: the sender can send many commands without waiting for RESP, the number of requests that may be pipelined at any time is called the window. RESP PDU may arrive in any order, unrelated to the order of their corresponding initiator PDU.

In the separated Transmitter+receiver mode, the connection used depends on the kind of message transmitted. The transmitter connection is used for MT, and the receiver connection is used for MO and SR. Requests and responses for each kind of message are sent over the same TCP connection.

For example, when sending an MT, the transmitter connection is used and the RESP that acknowledges the MT is also sent through the transmitter channel. When you receive an MO (or an SR), the receiver connection is used to receive the MO and to send the RESP that acknowledges the MO.

In 蜜豆视频 Campaign Standard, MT and SR reconciliation is native to the MTA, so there is no dedicated SMS process.

A successful SUBMIT_SM_RESP PDU triggers the 鈥渟ent鈥 message status in the sending log while a successful DELIVER_SM (SR) PDU triggers the 鈥渞eceived鈥 message status.

Security aspects security-aspects

The protocol itself is not encrypted. Most providers implement a variant of IP on allowlist so 蜜豆视频 Campaign server IP addresses have to be declared to the provider.

蜜豆视频 Campaign supports passing a login and a password during the bind phase. It also supports SMPP over TLS. It should be noted that certificates are required for proper security. While the SMPP connector allows bypassing certificate checks, it should only be used for testing since TLS without certificates provides a significantly lower level of security.

The connector uses the default certificates provided by the system openssl library. Usually it鈥檚 provided by the /etc/ssl/certs directory on Debian. This directory is provided by the 鈥渃a-certificates鈥 package by default but it may be customized.

Information in each kind of PDU information-pdu

Each kind of PDU has distinct fields that carry different pieces of information. These PDU are detailed in the .

Each section below describes both the PDU and its synchronous response (*_RESP PDU). All PDUs must be acknowledged by a corresponding RESP, this is a mandatory part of the specification.

PDUs can have optional fields. Only the most common fields are described here. Refer to the for more information.

BIND_TRANSMITTER / BIND_RECEIVER / BIND_TRANSCEIVER bind-transmitter

This PDU is used to initiate a connection to the SMSC. Transmitter, Receiver and Transceiver modes only change the kind of SMS allowed to be transferred over this connection, specifically:

Mode
Kinds of SMS allowed
Transmitter
MT
Receiver
MO + SR
Transceiver
MT + MO + SR

Notable fields in a BIND_* PDU:

  • system_id: Login used for authentication. Set in the external account.

  • password: Password used for authentication. Set in the external account.

  • system_type: Required to be set at a specific value for some providers. Set in the external account, available in all versions. Often distinguishes between different types of contracts, channels, countries, etc.

  • addr_ton and addr_npi: Required by some providers. Set by the Bind TON and Bind NPI settings in the external account.

  • address_range: Required by some providers. Most of the time, this is a list of shortcodes allowed on this connection. Set in the external account.

BIND_*_RESP has no specific field, it confirms whether the connection was successful or not.

UNBIND unbind

This PDU must be sent by the system before disconnecting. It must wait the matching UNBIND_RESP PDU before closing the connection.

Conforming SMSC must not close the connection, the TCP connection is controlled by the 蜜豆视频 Campaign connector.

SUBMIT_SM submit-sm

This PDU sends a MT to the SMSC. Its response PDU gives the ID of the MT.

Notable fields in a SUBMIT_SM PDU:

  • service_type: required by some providers. Set in the delivery properties.

  • source_addr_ton and source_addr_npi: indicates what kind of source address is transmitted. The meaning of these fields is standardized, but since some providers use it differently, you should ask the provider for its correct value. Set in the external account.

  • source_addr: the source address / oADC of the MT. It will be displayed on the mobile phone. Set in the external account and the delivery, the value in the delivery takes precedence over the value of the external account.

  • dest_addr_ton and dest_addr_npi: indicates what kind of destination address is transmitted (e.g. local or international format). The meaning of these fields is standardized, but since some providers use it differently, you should ask the provider for its correct value. Set in the external account.

  • destination_addr: recipient address, phone number or MSISDN.

  • esm_class: used to tell if UDH is used or not in the text field. Enabled automatically by the connector for split SMS if the message_payload mode is not used.

  • priority_flag: priority of this message over others. This is tied to the priority of the delivery itself.

  • validity_period: timestamp after which no retry should be attempted. Set in the delivery itself.

  • registered_delivery: tells whether a SR is requested or not. 蜜豆视频 Campaign always sets this flag except for automatic replies. For multipart messages, the flag is only set for the first part. All versions have the same behavior.

  • data_coding: indicates the encoding used in the text field. See the SMS text encoding section for more information.

  • short_message: the text of the message. If UDH is used, this also contains the UHD header.

蜜豆视频 Campaign supports these optional fields:

  • dest_addr_subunit: used to specify the target of the SMS: flash, mobile or SIM card. Set in the delivery properties.

  • message_payload: when enabled in the external account, long messages will be sent in a single PDU and the text will be transmitted in this field rather than the short_message field.

SUBMIT_SM_RESP submit-sm-resp

This PDU will contain the ID of the MT. This is useful to match it with incoming SR.

IMPORTANT
Many providers transmit the MT ID in hexadecimal. Make sure that you set the ID format in MT acknowledgement setting correctly in the external account.

Some providers send SUBMIT_SM_RESP after sending the SR. To account for that behavior, 蜜豆视频 Campaign waits 30 seconds before replying Invalid message ID to a SR with an unknown ID.

DELIVER_SM delivery-sm

This PDU is sent by the SMSC to 蜜豆视频 Campaign. It contains either a MO or a SR.

Most fields have the same meaning as their SUBMIT_SM counterpart. Here is the list of useful fields:

  • source_addr: source address of the MO/SR. Usually this is a phone number.

  • destination_addr: short code that received the MO or the SR.

  • esm_class: used to tell if the PDU is a MO or a SR.

  • short_message: text of the message. For SR, this contains data described in the Appendix B of the SMPP protocol specification. See SR error management for more details.

蜜豆视频 Campaign is able to read message ID in the receipted_message_id optional field with some configuration tuning.

DELIVER_SM_RESP deliver-sm-resp

This PDU is sent by 蜜豆视频 Campaign to acknowledge SR and MO.

蜜豆视频 Campaign Standard only sends a DELIVER_SM_RESP once all processing steps have been successful. This guarantees that no SR or MO is acknowledged while there is still a risk of processing errors.

This PDU is only used to check that the connection is live. Its frequency should be set according to the provider鈥檚 needs.

The default 60 seconds should match most configurations set in the external account.

This PDU acknowledges that the connection is alive.

Multipart SMS (long SMS) multipart

Multipart SMS, or long SMS, are SMS that are sent in multiple parts. Due to technical limitations in the mobile network protocol, a SMS cannot be larger than 140 bytes or it will need to be split. See the SMS text encoding section to learn more on the number of characters that can fit in a SMS.

Each part of a long message is an individual SMS. These parts travel independently on the network and are assembled by the receiving mobile phone. To handle retries and connectivity problems, 蜜豆视频 Campaign sends these parts in reverse order and requests a SR only on the first part of the message, the last sent. Since the mobile phone only displays a message when its first part is received, retries on additional parts won鈥檛 produce duplicates on the mobile phone.

The maximum number of SMS per message can be set per delivery using the Maximum number of SMS per message setting in the Delivery template. Messages that go above this limit will fail during sending with a SMS too long failure reason.

There are 2 ways to send long SMS:

  • UDH: the default and recommended way to send long messages. In this mode, the connector splits the message in multiple SUBMIT_SM PDUs with UDH information in them. This protocol is the one used by mobile phones themselves. This means that 蜜豆视频 Campaign has the most control over the message generation, making it capable to compute exactly how many parts were sent and how they were split.

  • message_payload: the way to send the whole long message in a single SUBMIT_SM PDU. The provider will have to split it, which means that it is impossible for 蜜豆视频 Campaign to know exactly how many parts have been sent. Some providers require this mode, but we advise you to only use it if they do not support UDH.

See the description of the esm_class, short_message and message_payload fields of the SUBMIT_SM PDU for more details about the protocol and formats.

Throughput capping and windowing throughput-capping

Most providers require a throughput limit for each SMPP connection. This can be achieved by setting a number of SMS in the external account. Note that throughput throttling happens per connection, the total effective throughput is the limit per connection multiplied by the total number of connections. This is detailed in the Simultaneous connections section.

To reach maximum possible throughput, you will need to fine tune the maximum sending window. The sending window is the number of SUBMIT_SM PDUs that can be sent without waiting for a SUBMIT_SM_RESP. See the Sending window setting section for more details.

SR and error management (鈥淎ppendix B鈥) sr-error-management

The SMPP protocol defines standard synchronous errors in RESP PDUs, but it does not define error codes for SR. Each provider uses their own error codes with their meaning.

A recommendation is made in the Appendix B section of the (page 167) but this does not list the actual error codes nor their meaning.

To adapt to error management, the broadlog message system of 蜜豆视频 Campaign has been leveraged to properly provision errors and their severity (hard, soft, etc.).

As mentioned above, there are two different kinds of errors:

  • synchronous replies in the SUBMIT_SM_RESP that happen immediately after the message was sent to the SMSC
  • receipts that may come much later when the mobile received the message or when the message timed out. In that case the error is found in a SR.

When a SR is received, status and error can be found in its short_message field (example for Appendix B conforming implementations). The short_message field of the PDU is often called the text field since it contains text in MT. In case of SR, it contains technical information plus a sub-field named Text. These 2 fields are different and short_message actually contains the Text field and other information.

SR text field format sr-text-field-format

The specification recommends using this format for the SR text field. It is a list of subfields, space-separated with a colon to separate the field name and its value. Field names are case insensitive.

Example of a SR text field matching the Appendix B recommendation:

id:1234567890 sub:001 dlvrd:001 submit date:1608011415 done date:1608011417 stat:DELIVRD err:000 Text:Hello 蜜豆视频 world

The id field is the ID received in the SUBMIT_SM_RESP PDU, the acknowledge of the MT.

sub and dlvrd are supposed to count the amount of delivered parts and delivered messages, but this is not used by 蜜豆视频 Campaign since the broadlog system gives a better, and more integrated information.

submit date and done date fields are indicative timestamps of when the MT was sent and when the SR was sent by the mobile. Expect some problems with time zones or even wrong timestamps given by mobiles with incorrect date set.

The stat field is important since it tells the status of the message. The only important status are DELIVRD, UNDELIV and REJECTD. The DELIVRD status indicates a success, the other two indicate an error. Other values are possible, but they are usually intermediate notifications e.g. the MT reached the mobile carrier, but not the mobile phone. These intermediate notifications are ignored by 蜜豆视频 Campaign.

The err field contains the provider-specific error code. The provider has to give a table of possible error codes along with their meaning to be able to interpret this value.

Finally, the text field usually contains the beginning of the text of the MT. This is ignored by 蜜豆视频 Campaign and some providers don鈥檛 transmit it to avoid PII leakage and network bandwidth consumption. It can be used during troubleshooting to spot the SR matching a test MT more easily by reading this field.

Example of SR processing in 蜜豆视频 Campaign Standard Extended generic SMPP sr-processing

This example displays the case of an implementation following the Appendix B recommendation, default values in the external account, and a successful SMS MT.

id:1234567890 sub:001 dlvrd:001 submit date:1608011415 done date:1608011417 stat:DELIVRD err:000 Text:Hello 蜜豆视频 world

First, the id extraction regex is applied to extract the ID and reconcile it with the corresponding MT.

Then, the status extraction regex and error code extraction regex are applied to extract these fields and are appended to the string.

The broadlog message is constructed with this information, and the original unaltered string is appended for reference:

SR ExampleProvider DELIVRD 000|MESSAGE=id:1234567890 sub:001 dlvrd:001 submit date:1608011415 done date:1608011417 stat:DELIVRD err:000 Text:Hello 蜜豆视频 world

The message is then normalized, removing the MESSAGE part to be able to match multiple messages with the same stat and err codes.

SR ExampleProvider DELIVRD 000|#MESSAGE#

If the message is not already provisioned in the broadlog message table, a new entry will be created, using the whole message as firstText and the normalized message. Then, the connector uses the success and error regex to determine if it was a success or a failure:

  • If it matches the success regex, it will be considered as a success.

  • If it matches the error regex, the message is qualified as an error.

  • If none of these two regex match, the SR is ignored. It might be an intermediate notification, which is not handled by 蜜豆视频 Campaign.

By default, all errors are provisioned as soft errors. This means that hard errors must be provisioned by hand.

SMS text encoding sms-text-encoding

You should always contact the SMSC provider in case of encoding problems. Only the SMSC providers have precise knowledge of the encoding they support and special rules that may apply due to limitations in their technical platform.

SMS messages use a special 7 bits encoding, often called the GSM7 encoding.

In the SMPP protocol, GSM7 text will be expanded to 8 bits per character for easier troubleshooting. The SMSC will pack it into 7 bits per character before it is sent to the mobile. This means that the short_message field of the SMS may be up to 160 bytes long in the SMPP frame whereas it is limited to 140 bytes when sent on the mobile network.

In case of encoding problems, here are some important things to check:

  • Make sure that you know which characters belong to which encoding. GSM7 does not fully support diacritical marks (accents). Especially in French, where 茅 and 猫 are part of GSM7, but 锚, 芒 or 茂 are not. The same applies to Spanish.

  • The C with cedilla (莽) is present only in upper case in the GSM7 alphabet, but some phones render it in lower case or 鈥渟mart鈥 case. The general recommendation is to completely avoid it and remove the cedilla or switch to UCS-2.

  • Do not use ASCII in SMS unless explicitly requested by the SMSC provider. This encoding wastes space because it has 8-bit characters and less coverage than GSM7. This encoding may be required for CDMA networks, used in North America.

  • Latin-1 is not always supported. Check the compatibility with your SMSC provider before attempting to use Latin-1.

  • National language shift tables are not supported by the 蜜豆视频 Campaign connector. You must use UCS-2 or other data_coding instead.

  • UCS-2 and UTF-16 are often mixed by phones. This is a problem when using emojis and other characters not present in UCS-2.

  • Most phones don鈥檛 have font glyphs for all UCS-2 characters. Smartphones tend to be able to display rare characters rather easily, but feature phones generally have limited support to what is useful in the native tongue of the country they were bought in. If you want to use emoji or ASCII-art, test it on a wide variety of phones before sending. 蜜豆视频 Campaign preview does not simulate missing glyphs and will display symbols available on the web browser.

The data_coding field tells you which encoding is used. A major problem is that the value 0 means default SMSC encoding in the specification, which usually refers to GSM7. Check with the SMSC partner which encoding is associated with data_coding = 0 which 蜜豆视频 Campaign only supports. Other data_coding values tend to follow the specification, but the only way to be sure is to check with the SMSC provider.

The maximum size of a message depends on its encoding. This table sums up all the relevant information:

Encoding
Usual data_coding
Message size (characters)
Part size for multipart SMS
Available characters
GSM7
0
160
152
GSM7 basic character set + extension (extended characters take 2 characters)
Latin-1
3
140
134
ISO-8859-1
UCS-2
UTF-16
8
70
67
Unicode (varies from phone to phone)

SMPP external account parameters SMPP-parameters-external

Each implementation of the SMPP protocol has many variations. To improve compatibility and adaptability, many settings are available to change the behavior of the SMPP connector. This section describes every parameter and its effects on the connector.

General parameters and routing general-parameters-routing

Limit MTA instances for this account

It is possible to set a limit to the number of MTA instances allowed to connect to the SMPP provider. When checked, you can specify how many MTAs can be used at most.

This option allows finer control over the number of connections, see Simultaneous connections.

If you set a value higher than the number of running MTAs, all MTAs will run as normal: this option is only a limit and cannot spawn additional MTAs.

If you need to precisely control the number of connections, e.g. provider requirement, it is recommended to always set this option even if the current deployment has the right number of MTAs running. If additional MTAs are added afterwards, the connection limit will still be respected.

Connection settings connection-settings

SMPP connection mode smpp-connection-mode

Sets the connection in transceiver mode or in separated transmitter+receiver mode. When you switch to separated transmitter+receiver mode, settings in the SMPP connection mode section apply to the transmitter and settings in the Receiver connection settings section apply to the receiver connection, only if you checked the Use different parameters for the receiver checkbox.

SMSC implementation name smsc-implementation-name

Sets the name of the SMSC implementation. It should be set to the name of your provider. Contact the administrator or the deliverability team to know what to add in this field. The role of this field is described in the SR error management section.

Server server

The DNS name or IP address of the server to connect to.

Port port

The TCP port to connect to.

Account account

The login of the connection. Passed in the system_id field of the BIND PDU.

Password password

Password of the SMPP connection. Passed in the password field of the BIND PDU.

System type system-type

Value passed in the system_id field of the BIND PDU. Some providers need a specific value here.

Simultaneous connections simultaneous-connections

In 蜜豆视频 Campaign Standard, it defines the number of connections per SMS thread and per MTA process.
The number of MTA process is determined by the deployment: usually there are 2 MTAs and 1 thread. The number of threads can be changed in the config-instance.xml file using the smppConnectorThreads setting. Usually there is 1 MTA process per container and 1 thread per MTA process.

Total connections formula for 蜜豆视频 Campaign Standard:

  • Total connections = Simultaneous connections * number of threads * number of MTAs

Simultaneous connections is set in the external account, number of threads is set in the config-instance.xml file (smppConnectorThreads) and number of MTAs can be limited in the external account.

In separated transmitter/receiver mode, the number of connections above represents the number of transmitter/receiver pairs meaning that there will be twice the number of connections in total.

Enable TLS over SMPP enable-TLS

Use TLS to connect to the provider. The connection will be encrypted. The TLS connection is managed by the OpenSSL library anything applicable to OpenSSL will be true for this connection.

Enable verbose SMPP traces in the log file enable-verbose-log-file

This setting dumps all SMPP traffic in log files. It鈥檚 often required to adjust parameters during initial setup. This must be enabled when troubleshooting the connector and compared to the traffic seen by the provider.

Receiver connection setting receiver-connection

This section is only visible in separated transmitter+receiver mode.

Use different parameters for the receiver receiver-parameters

When the box is unchecked, the same settings are used for transmitter and receiver.

When the box is checked, settings in the Connection settings section will apply to the transmitter and settings in the Receiver connection settings will apply to the receiver.

Receiver server, port, account, password, system type

These settings apply to the receiver when in transmitter+receiver mode. They work like the transmitter part, see above for more details.

SMPP channel settings smpp-channel-settings

Allow character transliteration allow-character-transliteration

Transliteration is the process of finding equivalent characters to missing ones. For example, the French 鈥溍 (e with circumflex accent) character is missing from GSM encoding, but it can be replaced by 鈥渆鈥 without impairing readability.

When this box is unchecked, text encoding will fail if it cannot encode the string exactly as-is.

When this box is checked, text encoding will try to convert the string to an approximate version instead of failing. If some characters have no equivalent in the target encoding, text encoding will fail.

See the Define a specific mapping of encodings setting for a more general explanation of the encoding process.

Store incoming MO in the database incoming-mo-storing

When enabled, incoming MO will be stored in the inSMS table of the database. This table can be queried using the query activity of any workflow.

Enable Real-time KPI updates during SR processing real-time-kpi

When enabled, KPIs will be updated in real-time on the main delivery page when receiving error SR.

The drawback can be low performance because of the database contention it generates. If disabled, statistics are updated by the syncfromexec workflow, running every 20 minutes.

Source number source-number

Defines the default source address for messages. This setting only applies if the source number has been left empty in the delivery.

By default, the source number field is not passed, so the provider will substitute it for the short code.

This enables the sender address/oADC override feature.

Short code short-code

Indicates the main short code of the account. If multiple short codes are used for this account or if the short code is unknown, leave this field empty.

Specifying short code is helpful for two features:

  • The preview will display the short code if no source number is provided. It will reflect the real behavior on the mobile phone.

  • The denylist setting of the auto reply feature only sends to quarantine the user for a specific short code.

Source TON/NPI, destination TON/NPI ton-npi

TON (Type Of Number) and NPI (Numbering Plan Indicator) are described in section 5.2.5 of the (page 117). These values should be set to the provider鈥檚 needs.

They are transmitted as-is in source_addr_ton, source_addr_npi, dest_addr_ton and dest_addr_npi fields of the SUBMIT_SM PDU.

Service type service-type

This field is transmitted as-is in the service_type field of the SUBMIT_SM PDU. Set this to the provider鈥檚 needs.

Throughput and timeouts throughput-timeouts

These settings control all the timing aspects of the SMPP channel. Some providers require very precise control of the message rate, window and retry timings. These settings should be set to values that match the capacity of the provider and the conditions indicated in their contract.

Sending window sending-window

The window is the number of SUBMIT_SM PDUs that can be sent without waiting for a matching SUBMIT_SM_RESP.

Example of a transmission with a maximum window of 4:

The window helps increase the throughput when the network link has a high latency. The value of the window must be at least the number of SMS/s multiplied by the latency of the link in seconds so the connector is never waiting for a SUBMIT_SM_RESP before sending the next message.
If the window is too big, you may send more duplicate messages in case of connection problems. Also, most providers have a very strict limit for the window and refuse messages that go over the limit.

How to calculate the optimal sending window formula:

  • Measure the maximum latency between SUBMIT_SM and SUBMIT_SM_RESP.

  • Multiply this value in seconds to the max MT throughput. This will give the optimal sending window value.

Example: If you have 300 SMS/s set in max MT throughput and there is 100ms latency between SUBMIT_SM and SUBMIT_SM_RESP on average, the optimal value would be 300脳0.1 = 30.

Max MT throughput max-mt-throughput

Maximum number of MT per second and per connection. This setting is strictly enforced, the MTA will never push messages faster than this limit. It is useful for providers that require precise throttling.

To know the total throughput limit, multiply this number by the total number of connections as detailed in the formula above.

0 means no limit, the MTA will send MT as fast as possible.

It is generally recommended to keep this setting under 1000, since it is impossible to guarantee precise throughput above this number unless properly benchmarked on the final architecture. If you need a throughput above 1000, please contact your provider. It may be better to increase the number of connections to go above 1000 MT/s.

Time before reconnection time-reconnection

When the TCP connection is lost, the connector will wait this number of seconds before trying to make a connection.

Expiration period of the MT expiration-period

Timeout between SUBMIT_SM and its matching SUBMIT_SM_RESP. If the RESP is not received on time, the message will be considered as failed and global retry policy of the MTA will apply.

Bind timeout bind-timeout

Timeout between the TCP connect attempt and the BIND_*_RESP reply. When it times out, the connection is closed by the 蜜豆视频 Campaign connector and it will wait Time before reconnection before trying again.

enquire_link is a special kind of PDU sent to keep the connection alive. This period is in seconds. The campaign connector only sends enquire_link when the connection is idle in order to conserve bandwidth. If no RESP is received after twice this period, the connection will be considered dead and a reconnection process will be triggered.

SMSC specifics SMSC-specifics

These settings are advanced settings which adapt the 蜜豆视频 Campaign connector to most SMPP implementation peculiarities.

Define a specific mapping of encodings encoding-specific-mapping

See the SMS text encoding section for details on text encoding.

This setting allows you to define a custom encoding mapping, different from the specification. You will be able to declare a list of encodings, along with their data_coding value.

The MTA will try to encode using the first encoding in the list. If it fails, it will try to use the next encoding on the list, etc. If no encoding can be used to encode the message, an error will happen. Once the encoding is found, the MTA will create the SUBMIT_SM PDU with the encoded text and the data_coding field set with the value specified in the table.

The order of items in the table is important: encodings are tries from top to bottom. You should put the cheapest or most recommended encoding at the top of the list, then followed by more and more expensive encodings.

Please note that UCS-2 will never fail as it can encode all characters supported in 蜜豆视频 Campaign and that the maximum length of an UCS-2 SMS is much smaller: 70 characters only.

You can also use this setting to force a specific encoding to be always used by declaring only 1 line in the mapping table.

The default mapping used when the checkbox is not checked is equivalent to the following table:

data_coding
Encoding
0
GSM
9
UCS-2

This means that the MTA will try to encode the message in GSM. If it succeeds it will send it with data_coding set to 0.

If the message cannot be encoded in GSM, it will be encoded in UCS-2 and will set data_coding to 8.

Enable message_payload enable-message-payload

When unchecked, long SMS will be split by the MTA and sent in multiple SUBMIT_SM PDUs with UDH. The message will be recomposed by the mobile phone following UDH data.

When checked, long SMS will be sent in one SUBMIT_SM PDU, putting the text in the message_payload optional field. See the SMPP specification for details about this.

If this feature is enabled, 蜜豆视频 Campaign will be unable to count SMS parts individually: all messages will be counted as sent in one part.

Send the full phone number send-full-phone-number

When this checkbox is not checked, only digits of the phone number are sent to the provider (destination_addr field of the SUBMIT_SM field). This is the default behavior since the international number indicator, usually a + prefix, is replaced by TON and NPI fields in SMPP.

When the checkbox is checked, the phone number is sent as-is, with no preprocessing and potential spaces, + prefix or pound/hash/star signs.

This feature also has an effect on the behavior of auto reply denylist feature: when the checkbox is not checked, a + prefix will be added to phone numbers inserted into the quarantine table in order to compensate for the + prefix being removed from the phone number by the SMPP protocol itself.

Skip TLS certificate check skip-tls

When TLS is enabled, skip all certificate checks.

When checked, the connection is not secure anymore, it should not be enabled in production.

It can useful for debugging or test purposes.

Bind TON/NPI bind-ton-npi

TON (Type Of Number) and NPI (Numbering Plan Indicator) described in section 5.2.5 of the (page 117). These values should be set to whatever the provider needs.

They are transmitted as-is in addr_ton and addr_npi fields of the BIND PDU.

Address range address-range

Sent as-is in the address_range field of the BIND PDU. This value should be set to whatever the provider needs.

Invalid ID acknowledge count invalid-id

Limits the number of Message ID invalid DELIVER_SM_RESP that can be sent for a single SR.

This should be only used for troubleshooting purpose as a workaround and set to 0 in normal conditions.

Fox example, when setting to 2:

  • The provider sends a SR (DELIVER_SM) with ID 鈥1234鈥.

  • The ID 鈥1234鈥 could not be found in the database.

  • The connector counts 1 Invalid ID error for that ID, so it sends DELIVER_SM_RESP with the 鈥淢essage ID invalid鈥 error code (normal behavior).

  • The provider retries the same SR with ID 鈥1234鈥.

  • The ID 鈥1234鈥 still could not be found in the database.

  • The connector counts 2 Invalid ID error for that ID, so it sends DELIVER_SM_RESP 鈥淥K鈥, even if it was not processed correctly.

  • This feature is meant to flush SR buffers on the provider side when invalid SR block legitimate that messages cannot be processed.

Setting this field to 0 disables the mechanism where Message ID invalid is always returned, this is normal behavior.

Setting this field to 1 makes the connector always respond 鈥淥K鈥 even if the ID is invalid. This should be set to 1 only under supervision, for troubleshooting and for the minimum amount of time, e.g. to recover from a provider-side issue.

Extraction regex of the ID in the SR regex-extraction

SR format is not strictly enforced by the SMPP protocol specification. It is only a recommendation described in Appendix B (page 167) of the specification. Some SMPP implementers format this field differently, so 蜜豆视频 Campaign needs a way to extract the correct field.

By default, it captures up to 10 alphanumeric characters after id:.

The regex must have exactly one capture group with a part contained within parentheses. Parentheses must surround the ID part. The regex format is PCRE.

When adjusting this setting, be sure to include as much context as possible to avoid false triggers. If there are specific prefixes, such as id: in the standard, include them in the regex. Also use word delimiters (\b) as much as possible to avoid capturing text in the middle of a word.

Not including enough context in the regex can introduce a small security flaw: the actual content of the message can be included in the SR. If you only match a specific ID format with no context, e.g. a UUID, it may be parsing the actual text content, e.g. a UUID embedded in the text field, instead of the ID.

Regex applied to determine successful/error status regex-applied

When messages with an unknown stat/err field combination are encountered, these regex are applied on the stat field to determine whether the SR was a success or an error. SR with stat values that don鈥檛 match any of these regexes are ignored.

By default, stat values that begin with DELIV, e.g. DELIVRD in the Appendix B, will be considered as successfully delivered and all stat values that match errors, e.g. REJECTED, UNDELIV, are considered errors.

ID format in MT acknowledgement id-format-mt

This indicates the format of the ID returned in the message_id field of the SUBMIT_SM_RESP PDU.

  • Do not modify: The ID is stored as-is in the database, as ASCII-encoded text. No pre-processing nor filtering occurs.

  • Decimal number: The ID is expected to be a decimal number in ASCII form. Leading and trailing spaces and leading zeros are removed when this setting is used.

  • Hexadecimal number: The ID is expected to be a hexadecimal number in ASCII form, with no leading 0x nor trailing h. The ID is then converted to a decimal number before being stored in the database.

  • Hexadecimal string: The ID is expected to be an ASCII-encoded text that is itself a string of bytes encoded as hexadecimal. For example, in the PDU you will find 0x34 0x31 0x34 0x32 0x34 0x33, which translates to ASCII 鈥414243鈥. This string is then decoded as a hexadecimal string of bytes and you obtain 鈥淎BC鈥 as a result: you will store the ID 鈥淎BC鈥 in the database.

ID format in SR id-format-sr

This indicates the format of the ID captured by the Extraction regex of the ID in the SR. Values have the same meaning and the same behavior as the format in MT above.

SR ID or error code in optional field

If checked, the content of optional fields will be appended to the text processed by regexes above. The text will have the format 0xTAG:VALUE, 0xTAG being the 4-digit hexadecimal value of the tag in upper case e.g. 0x002E.

For example, you might want to capture the ID in the receipted_message_id field. For this, enable this checkbox and the following text will be added to the status:

0x001E:05e3299e-8d37-49d0-97c6-8e4fe60c7739

In this example, 0x001E is the tag of the optional field and the UUID is the value of the field.

In order to capture this value, you may now set the following regex in the Extraction regex of the ID in the SR field:

\b0x001E:([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b
IMPORTANT
You can only capture optional fields that have text (ASCII/UTF-8) values. Specifically, binary fields cannot be captured reliably with the current regex system.

SR ID or error code in text field

If checked, the Text field will be kept during processing of the status text of the SR.

This is useful if the provider places important data in this field like the ID or the status. Usually this field can be safely discarded since it may contain text with a non-ASCII encoding and disrupt regex processing.

Enabling this option may introduce a very small security flaw if the Extraction regex of the ID in the SR field is not specific enough. The content of the Text field may be parsed as an ID and an attacker may use it to inject forged IDs, which may lead to a partial denial of service situation.

Service ID tag

Allows to add a custom TLV. This field sets the tag portion. The value can be customized per delivery in the Service or program ID value in the advanced parameters of the delivery.

This setting only allows adding one TLV option per message.

NOTE
As of the 21.1 release, it is now possible to add more than one optional parameter. For more on this, refer to this section.

Automatic reply sent to the MO automatic-reply

This feature allows to quickly reply text to MO and handle per-short code sending to denylist.

The Keyword and Short code columns define conditions to trigger the auto reply. If both fields match, the MO is sent and the additional action is triggered. To specify a wildcard, you should leave the field empty. Keyword matches against the first alphanumeric word in the MO text, ignoring punctuation and leading spaces. It means that the Keyword field cannot contain spaces and must be a single word.

The Keyword setting is a prefix. For example, if you specify 鈥淎D鈥, it will match 鈥淎D鈥, 鈥淎DAPT鈥 and 鈥淎DOBE鈥. If you have multiple keywords with a common prefix, you need to pay attention to the order since keywords are processed from top to bottom.

The Reply column is the text to reply. No personalization is available in this field. If you leave this field empty, no message will be replied but the additional action will be triggered anyway.

The Additional action column provides an extra action when both Keyword and Short code match, empty short code matches all short codes. You can send to quarantine or remove from quarantine, value none replies to the text. If you specify an Additional action but leave the Reply field empty, the action will be executed but no reply will be sent. Quarantine is applied only for the specified short code, or all short codes if the field is left empty.

IMPORTANT
The send full phone number setting has an impact on the behavior of automatic reply quarantine mechanism: if send full phone number is not checked, the phone number put in quarantine will be prefixed by a plus sign (鈥+鈥) to make it compatible with the international phone number format.

All entries in the table are processed in the specified order, until one rule matches. If multiple rules match a MO, only the topmost rule will be applied.

Automatic reply optional parameters (TLV) automatic-reply-tlv

As of the 21.1 release, you can add optional parameters to automatic reply MT. They are added as optional TLV parameters to the SUBMIT_SM PDU of the reply, as described in the section 5.3 of the (page 131).

For more information about optional parameters, refer to this section.

SMS delivery template parameters sms-delivery-template-parameters

Some parameters may be set per delivery template.

From field from-field

This field is optional. It allows overriding sender address (oADC). The content of this field is placed in the source_addr field of the SUBMIT_SM PDU.

The field is limited to 21 characters by the SMPP specification, but some providers may allow longer values. Note also that very strict restrictions may be applied in some countries, for example length, content, allowed characters.

Delivery parameters delivery-parameters

Maximum number of SMS per message maximum-sms

This setting only works if the Message payload setting is disabled. For more information on this, refer to this page. If the message requires more SMS than this value, an error will be triggered.

The SMS protocol limits SMS to 255 parts, but some mobile phones have trouble putting together long messages with more than 10 parts or so, the limit depends on the exact model. We advise you not to go over 5 parts per message.

Due to how personalized messages work in 蜜豆视频 Campaign, messages can vary in size. Having a great amount of long messages could increase sending costs.

Transmission mode transmission-mode

This field indicates the kind of SMS you wish to transfer: normal or flash messages, storing on the mobile or the SIM card.

This setting is transmitted in the dest_addr_subunit optional field in the SUBMIT_SM PDU.

  • Unspecified sends no optional field in the PDU.

  • Flash sets the value to 1. It sends a flash message that pops up on the mobile and is not stored in memory.

  • Normal sets the value to 0. It sends a normal message.

  • Save on mobile sets the value to 2. It tells the phone to store the SMS in internal memory.

  • Save on terminal sets the value to 3. It tells the phone to store the SMS in the SIM card.

Validity period validity-period

The validity period is transmitted in the validity_period field of the SUBMIT_SM PDU. The date is always formatted as an absolute UTC time format (the date field will end with 鈥00+鈥).

SMPP optional parameters (TLV) smpp-optional-parameters

As of the 21.1 release, you can add multiple optional parameters to every MT sent for this delivery. These optional parameters are added to the SUBMIT_SM PDU of the reply, as described in the section 5.3 of the (page 131).

Each row in the table represents an optional parameter:

  • Parameter: Description of the parameter. Not transmitted to the provider.
  • Tag Id: Tag of the optional parameter. Must be valid hexadecimal, using the format 0x1234. Invalid values will lead to a delivery preparation error.
  • Value: Value of the optional field. Encoded as UTF-8 when it is transmitted to the provider. Encoding format cannot be changed, it is not possible to send binary values or use different encodings such as UTF-16 or GSM7.

If any optional parameter has the same Tag Id as the Service Tag Id defined in the external account, the value defined in this table will prevail.

SMPP connector ACS-SMPP-connector

Arrows represent data flow.

The most important thing to note here is that there are multiple SMPP connector threads. These threads are all identical and share the same configuration. That is why the number of connections is always multiplied by the number of threads.

The number of threads cannot be changed by the customer since it requires changing configuration files.

Description of the behavior of the SMPP connector behavior-smpp-connector

Matching MT, SR and broadlog entries matching-mt-sr

In 蜜豆视频 Campaign, a message is a broadlog entry. In 蜜豆视频 Campaign Standard, external connectors only need to know about the working broadlog table: nmsBroadLogExec. A workflow is in charge of copying broadlog entries back to their specific targeting dimensions (nmsBroadLogXXX).

Unfortunately, SMPP does not allow to send an ID along with a message: the provider gives a MT ID to each MT, then provides one or more SR with the same ID.

The ID given by the provider is stored in the sProviderId column of nmsBroadLogExec table. SR always arrive after the MT was successfully sent and acknowledged, but can sometimes arrive out of order, known in 蜜豆视频 Campaign as outstanding SR. The processing thread stores these SR temporarily in RAM until the complete information arrives.

When an MT is acknowledged (SUBMIT_SM_RESP), sProviderId is immediately updated in database.

Each SR is processed individually by SMPP processing threads. This process is pseudo-synchronous: it is seen as synchronous from the outside, but implemented internally with event-driven implementations. SR are acknowledged only when broadlog has been successfully updated, if an error is encountered the SR is rejected.

Here is the process applied to each SR:

  • The ID of the SR is extracted using a regex.
  • The ID is searched in nmsBroadLogExec:sProviderId.
  • The status + error code are extracted from the SR using regexes.
  • The broadlog message mechanism is used to qualify the error and find the broadlog message ID.
  • The broadlog is updated with all the information above.
  • The SR is acknowledged.

Checking the above steps requires to Enable verbose SMPP traces to manually check that all the steps are correctly applied. This is required each time 蜜豆视频 Campaign is connected to a new SMPP provider.

Before going live checklist

This checklist provides a list of things that you should check before going live. An incomplete setup can lead to many issues.

Check for external account conflicts external-account-conflict

Check that you don鈥檛 have old SMS external accounts. If you leave the test account disabled you run the risk for it to be re-enable on the production system and generate potential conflicts.

Check that no other instance connects to this account. In particular, make sure that the stage environment does not connect to the account. Some providers support this, but it requires very specific configuration both on 蜜豆视频 Campaign side and on the provider鈥檚 platform.

If you need to have multiple accounts on the same 蜜豆视频 Campaign instance that connect to the same provider, contact the provider to make sure that they actually distinguish connections between these accounts. Having multiple accounts with the same login requires extra configuration.

Enable verbose SMPP traces during checks enable-verbose

You should always enable verbose SMPP traces during checks.
Even if you cannot check the logs yourself, it will be easier for Support to help you.

Test your SMS test

  • Send SMS with all kinds of characters
    If you need to send SMS with non-GSM or non-ASCII characters, try sending some messages with as many diverse characters as possible. If you set up a custom character mapping table, send at least one SMS for all possible data_coding values.

  • Check that SR are properly processed
    The SMS should be marked as received in the delivery log. The delivery log should be successful and look like the following:
    SR yourProvider stat=DELIVRD err=000|#MESSAGE
    Check that you changed the delivery provider name. The delivery log should never contain SR Generic on production environments.

  • Check that MO are processed
    If you need to process MO (automatic replies, storing MO in the database,etc.) try to do some tests. Send a few SMS for all automatic reply keywords and check if the reply is fast enough,no more than a few seconds.
    Check in the log that 蜜豆视频 Campaign replies with a successful DELIVER_SM_RESP (command_status=0).

Check PDUs check-pdus

Even if messages look successful, it is important to check that PDUs are properly formatted.

This step is necessary when connecting to a provider that was not connected to 蜜豆视频 Campaign before.

BIND bind

Check that BIND_* PDUs are correctly sent. The most important thing to check is that the provider always returns successful BIND_*_RESP PDUs (command_status = 0).

Check that there aren鈥檛 too many BIND_* PDUs. If there are too many of them, it might indicate that the connection is unstable. See the Issues with unstable connections section for more information.

Check that ENQUIRE_LINK PDUs are regularly exchanged when the connection is idle.

SUBMIT_SM / DELIVER_SM submit-sm-deliver-sm

Send a message, then search in the logs for its corresponding SUBMIT_SM, SUBMIT_SM_RESP, DELIVER_SM and DELIVER_SM_RESP PDUs.

With the SUBMIT_SM PDU:

  • Check that data_coding is correct, 0 by default.
  • Check that short_message is properly encoded. Try decoding it using a hexadecimal converter that supports multiple encodings.

With the SUBMIT_SM_RESP PDU:

  • Check that it was successful, command_status = 0.
  • Check that its body contains a properly formatted ID followed by a 鈥0鈥 byte.

With the DELIVER_SM PDU:

  • Decode the hexadecimal short_message field.
  • Check with a regex checking tool that the regex defined in Extraction regex of the ID in the SR returns exactly one capture group and that it captures the whole ID in the message.
  • Check that the extracted ID matches the one in SUBMIT_SM_RESP.
  • Check that the regex defined in Extraction regex of the status in the SR returns the content of the stat field.
  • Check that the regex defined in Extraction regex of the error in the SR returns the content of the err field.

With the DELIVER_SM_RESP PDU:

  • Check that it was sent quickly after receiving the DELIVER_SM PDU, typically less than 1 second.
  • Check that it was successful, command_status = 0.

Ask the provider if everything is OK provider

Even if your SMS is successful, contact the provider to see if everything is in order.

Disable verbose SMPP traces disable-verbose

Once all checks are complete, the last thing is to Disable verbose SMPP traces to not generate too many logs. You can re-enable them for troubleshooting purposes even on production systems.

recommendation-more-help
3ef63344-7f3d-48f9-85ed-02bf569c4fff