蜜豆视频

SMS connector protocol and settings sms-connector-protocol

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:

This document will walk you through the connection set up 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.

SMS types sms-types

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

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:

SMPP protocol smpp-protocol

蜜豆视频 Campaign Classic 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:

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 Classic, to link SR with their corresponding MT, an ID is returned by the SMSC with the SUBMIT_SM_RESP and DELIVER_SM steps. The identifier is stored in the providerId field of the nms::providerMsgId table and is linked to broadLogId and deliveryId. This matching operation is done by the SMS process when writing to the database.

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

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:

Notable fields in a BIND_* PDU:

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:

蜜豆视频 Campaign supports these optional fields:

SUBMIT_SM_RESP submit-sm-resp

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

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:

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

DELIVER_SM_RESP deliver-sm-resp

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

蜜豆视频 Campaign Classic acknowledges SR and MO once they have been inserted into the database. Some processing errors can happen even if a successful DELIVER_SM_RESP PDU has been sent. This limitation is caused by the software architecture of 蜜豆视频 Campaign Classic.

ENQUIRE_LINK enquire-links

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.

ENQUIRE_LINK_RESP enquire-links-resp

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:

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:

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.

蜜豆视频 Campaign Classic connectors (except Extended SMPP) use a hardcoded behavior that depends on the selected provider. Generic SMPP only distinguishes between success and error, with no detail. Delivery log may contain some information which is not guaranteed.

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 Classic 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:

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 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:

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:

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

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.

Number of MTA child connections number-mta-child

In 蜜豆视频 Campaign Classic, it defines the number of connections per MTA child.

The 蜜豆视频 Campaign Classic Extended SMPP connector can control the number of connections per MTA child. To control the global limit of connections, you will have to limit the number of MTA child processes, which often means having a dedicated mid-sourcing platform for SMS.

For 蜜豆视频 Campaign Classic, there can be a different number of receiver and transmitter connections:

As suggested above, the 蜜豆视频 Campaign Classic SMS process opens more transmitter connections if auto-reply is enabled. These extra connections are used to send the automatic replies.

If you set up automatic replies, the SMS process will open transmitter/receiver pairs, increasing the number of transmitter connections. If you did not set up any automatic reply, it will open only receiver connections.

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.

In 蜜豆视频 Campaign Classic, log output is in the MTA log for MT-related traffic and in the SMS log for MO and SR-related traffic.

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.

蜜豆视频 Campaign Classic always stores all MOs in the inSMS database so this option is not available.

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.

蜜豆视频 Campaign Classic has an entirely different mechanism for KPIs so this option is not available.

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:

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:

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 and specifically requested SMPP 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 period enquire-link-period

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

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:

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.

You can choose between three different values for the certificate validation:

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:

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.

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

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.

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.

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.

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

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+鈥�.

Extended generic SMPP connector acc-extended-connector

Arrows represent data flows.

When sending delivery parts, the MTA spawns MTA children. The number of MTA child processes is dynamic and depends on a configuration in serverConf.xml. Each MTA child instantiates the connector CSmppConnectorWorker which connects to the SMPP provider. Connections are kept alive as long as the MTA child is kept alive, also configurable in serverConf.xml.

The SMS process only processes SR, it connects to the provider and leaves the connection open. The process reconnects every 10 minutes to reload new settings, this is normal operation.

Matching MT, SR and broadlog entries matching-mt

An intermediate table nmsProviderMsgId is used to store MT and SR data temporarily before being committed asynchronously to the broadlog.

nmsProviderMsgId table has 3 groups of columns:

When both MT and SR finished processing, you should have complete lines, with both broadlog information and status information.

Here, iMsgId is linked to nmsBroadLogMsg table, indicating the full status/error message.

The SMS process checks for complete lines every minute, then processes them asynchronously:

Throughput and parallel connections

Each MTA child creates a configurable amount of connections, so limiting the number of MTA child will limit the number of connections. Because the correlation between MTA child processes and traffic is correlated, this can be somewhat controlled but still a bit unpredictable.

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.

If you 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 to help you.

Test your SMS test

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.

ENQUIRE_LINK enquire-link-pdus

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

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:

With the SUBMIT_SM_RESP PDU:

With the DELIVER_SM PDU:

With the DELIVER_SM_RESP PDU:

Check with your provider 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.