Actions

The SMPP connector exposes the following clients:

Available clients:

Client	Purpose
Client	Submits, queries, cancels, and replaces messages against an SMSC

For event-driven integration, see the Trigger Reference.

---

Client

An SMPP client bound to an SMSC as TRANSMITTER, RECEIVER, or TRANSCEIVER, for issuing the submit-family operations as an active outbound session. The client binds once at initialization and stays bound for its lifetime.

Configuration

The host, systemId, and password used to bind are required parameters of the client's initialization, ahead of the rest of the configuration below.

ClientConfig

Field	Type	Default	Description
port	int	2775	SMSC port
systemType	string	""	The optional SMPP system_type
bindType	TRANSMITTER|RECEIVER|TRANSCEIVER	TRANSCEIVER	The bind mode. TRANSMITTER and TRANSCEIVER can submit; RECEIVER cannot
bindTimeout	decimal	60	Maximum time, in seconds, the connect-and-bind handshake may take
transactionTimeout	decimal	30	How long a submit-family operation waits for the SMSC's response, in seconds
enquireLinkInterval	decimal	60	How often the client sends a keepalive enquire_link when the session is otherwise idle, in seconds
secureSocket	SecureSocket|InsecureSocket?	()	Transport security. Absent means plaintext TCP

Initializing the client

import ballerina/smpp;

smpp:Client smppClient = check new ("smsc.example.com", systemId, password,
        port = 2775, bindType = smpp:TRANSMITTER);

With TLS:

smpp:Client smppClient = check new ("smsc.example.com", systemId, password,
        port = 3550,
        secureSocket = {
            cert: {path: "./truststore.p12", password: trustStorePass}
        });

Operations

Submit

submit

Submits a message to the SMSC (submit_sm) and waits for the response. Requires bindType: TRANSMITTER or TRANSCEIVER.

Parameters:

Name	Type	Required	Description
sms	TextSms|BinarySms	Yes	The message to send: a TextSms (the client encodes it) or a BinarySms (pre-encoded octets)

Returns: SubmitResult|smpp:Error

Sample code:

smpp:SubmitResult|smpp:Error result = smppClient->submit({
    destinationAddress: "94771234567",
    shortMessage: "Hello from Ballerina!",
    registeredDelivery: smpp:ON_SUCCESS_OR_FAILURE
});
if result is smpp:SubmitResult {
    // Correlate later delivery receipts against result.messageId.
}

submitMulti

Submits one message to several destinations in a single submit_multi request. Requires bindType: TRANSMITTER or TRANSCEIVER.

Parameters:

Name	Type	Required	Description
sms	TextSms|BinarySms	Yes	The message to send; sms.destinationAddress is not used
destinationAddresses	string[]	Yes	The recipient addresses for this batch; must contain at least one

Returns: MultiSubmitResult|smpp:Error

Sample code:

smpp:MultiSubmitResult result = check smppClient->submitMulti(
    {destinationAddress: "", shortMessage: "Flash sale ends tonight!"},
    ["94771234567", "94777654321"]
);

submitData

Submits a message via data_sm instead of submit_sm, the alternative MT transfer PDU some SMSCs prefer for binary/WAP-push payloads. Requires bindType: TRANSMITTER or TRANSCEIVER.

Parameters:

Name	Type	Required	Description
data	TextSms|BinarySms	Yes	The message to send

Returns: SubmitResult|smpp:Error

Sample code:

smpp:SubmitResult result = check smppClient->submitData({
    destinationAddress: "94771234567",
    shortMessageBytes: payloadBytes,
    dataCoding: 0
});

Query, cancel, and replace

queryStatus

Queries the SMSC's current view of a previously submitted message's delivery state (query_sm). Requires bindType: TRANSMITTER or TRANSCEIVER.

Parameters:

Name	Type	Required	Description
messageId	string	Yes	The SMSC's message_id for the message, as returned by submit/submitMulti/submitData
sourceAddress	string	Yes	The message's original source address

Returns: QueryResult|smpp:Error

Sample code:

smpp:QueryResult status = check smppClient->queryStatus(messageId, "94771234567");

cancel

Cancels a previously submitted, not-yet-delivered message (cancel_sm). Requires bindType: TRANSMITTER or TRANSCEIVER.

Parameters:

Name	Type	Required	Description
messageId	string	Yes	The SMSC's message_id for the message to cancel
sourceAddress	string	Yes	The message's original source address
destinationAddress	string	Yes	The message's original destination address

Returns: smpp:Error?

Sample code:

check smppClient->cancel(messageId, "94771234567", "94771234567");

replace

Replaces the text/attributes of a previously submitted, not-yet-delivered message (replace_sm). Requires bindType: TRANSMITTER or TRANSCEIVER.

Parameters:

Name	Type	Required	Description
messageId	string	Yes	The SMSC's message_id for the message to replace
sourceAddress	string	Yes	The message's original source address
sms	TextSms|BinarySms	Yes	The replacement content

Returns: smpp:Error?

Sample code:

check smppClient->replace(messageId, "94771234567",
        {destinationAddress: "94771234567", shortMessage: "Updated text"});

Connection lifecycle

close

Unbinds and releases the underlying SMSC session. Idempotent: closing an already-closed client is a no-op. A closed client cannot be reused; create a new one.

Parameters:

No parameters

Returns: smpp:Error?

Sample code:

check smppClient.close();