3rd Party SMS API

Adeona Technologies (Pvt) Ltd

v

1|Page Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

Contents

1. Revision History .................................................................................................................................... 4

2. Register with https://e-sms.dialog.lk .................................................................................................... 6
3. Access Token generation ...................................................................................................................... 6
4. SMS API (Version 2)............................................................................................................................. 10
5. Check created campaign status for a transaction id (Version 2) ........................................................ 15
6. Plugins ................................................................................................................................................. 18
6.1. Working Scenario ............................................................................................................................ 18
6.2. Java.................................................................................................................................................. 19
6.2.1. Supported Projects ..................................................................................................................... 19
6.2.1.1. Maven projects ....................................................................................................................... 19
6.2.1.2. Spring Boot maven projects .................................................................................................... 19
6.2.2. Installation .................................................................................................................................. 19
Apache Maven ........................................................................................................................................ 19
Gradle Groovy DSL ................................................................................................................................. 19
v
6.2.3. Quick Start................................................................................................................................... 20
6.2.3.1. Get Access token ..................................................................................................................... 20
6.2.4. Save Access token in local memory ............................................................................................ 22
6.2.5. Check whether the access token expired or not ........................................................................ 22
6.2.6. Send SMS..................................................................................................................................... 23
6.2.7. Check created campaign status for a transaction id ................................................................... 25
6.3. PHP .................................................................................................................................................. 27
6.3.1. Installation .................................................................................................................................. 27
6.3.2. Quick Start................................................................................................................................... 28
6.3.2.1. Get Access token ..................................................................................................................... 28
6.3.3. Save Access token in local memory ............................................................................................ 30
6.3.4. Check whether the access token expired or not ........................................................................ 30
6.3.5. Send SMS..................................................................................................................................... 31
6.3.6. Check created campaign status for a transaction id ................................................................... 33
7. Send SMS via GET Request.................................................................................................................. 35
8. Check account balance via GET Request............................................................................................. 40
9. Error Codes ......................................................................................................................................... 42

2|Page Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

10. Delivery report API .......................................................................................................................... 43

3|Page Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

1. Revision History

Version Date User Description

1.0 - - Initial Version

1.1 2021-07-05 Sadisha Source address added to

campaign creation
request
1.2 2021-07-08 Sadisha New parameter called
transaction_id added to
sms api. Updated the
requests and responses.
Added a new enpoint to
check status of a
transaction.
1.3 2021-07-21 Sadisha Added CURL Request for
every API

1.4 2021-07-22 Sadisha Token expiration time is

v set to 12 hours.

1.5 2021-07-28 Vishwa Java, PHP plugin were

created.

1.6 2022-06-23 Sadisha Send SMS via GET

request added

1.7 2022-06-23 Sadisha Updated the responses

for SMS via GET request

1.8 2022-07-27 Sadisha • Add a new

response status
for SMS via GET
request.
• Added a new GET
request to view
account balance
for users who are
consuming SMS
via GET request.

4|Page Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

1.9 2022-08-19 Sadisha New parameter to
specify payment method
added to the endpoint
corresponding to sending
SMS via GET request.
New error codes added
for section 9 of this
document.
2.0 2022-08-22 Sadisha Endpoints added to send
SMS and check created
campaign status for a
transaction id (Version 2)
2.1 2022-10-07 Sadisha New push notification
parameter enabled to
push delivery
notifications for SMS APIs
2.2 2022-11-04 Roshan SMS API v1 was
depreciated. Error code
2012 was added related
to get request SMS.
2.3 2023-05-15 Roshan Update the length of E-
SMS API transaction id.

2.4 2023-06-16
v Sadisha A new error codes were
introduced in SMS API
version 2 and send SMS
via GET requests to
indicate if too many
requests were detected
from the user.
2.5 2023-06-22 Roshan E-SMS API request
limitations were defined.

5|Page Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

2. Register with https://e-sms.dialog.lk

3. Access Token generation

Please note that this API should be call only on initial request and on access token expiration
only
End point: https://e-sms.dialog.lk/api/v1/login
Method: HTTP POST
Type: application/json

Request Parameters
Parameter name Description Mandatory/ Optional Data type
username Username registered Mandatory String
with Smart Messenger
password Password
v registered Mandatory String
with Smart Messenger

JSON Object sent via Post Method

{

"username": "947xxxxxxxx",

"password": "ABC"

cURL Code snippet

curl --location --request POST 'https://e-sms.dialog.lk/api/v1/login' \
--header 'Content-Type: application/json' \
--data-raw '{ "username":"XXXXXX", "password":"XXXXX" }'

6|Page Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

Response

Parameter name Description Mandatory/ Data type

Optional
status Status of the request Mandatory String
comment Comment to find the Mandatory String
failure reason if
failed
token Token to be use for Mandatory String
future
communications
during sending SMS
and refreshing token
expiration Time after which Mandatory int
token is expired
(time in seconds).
Valid only for 12
hours
remainingCount Login Count (User Mandatory Int
v
has 5 attempts to
enter the correct
password. If exceeds,
account will be
locked)
refreshToken Plan for future use optional
refreshExpiration Time after which optional
token is expired
(time in seconds).
Valid only for 7 days
userData Data Object Optional Object
This is empty for a
failed response
userData -> id User ID Optional Number
userData -> fname User First Name Optional String
userData -> lname User Last Name Optional String
userData -> address User Address Optional Object
userData -> mobile User Mobile Optional Number
userData -> email User Email Optional String

userData -> defaultMask User Default Mask Optional String

userData -> additional_mask User Additional Mask Optional Object
List if available

7|Page Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

 userData -> additional_mask -> Additional Mask Optional String
mask
userData -> walletBalance User Wallet Balance Optional Number
accountType Type of the account Optional Number
accountLocked Indicate the account Optional Int
lock status
accountStatus Status whether Optional int
active or not active
walletBalance Available balance of Optional Float
the account.
Additional_addons Addons that Optional String
activated for the
user account.
data Future use Optional String
errCode Corresponding Error Mandatory Int
Code (Check the
error code definition
section)

If success
{
"status": "success", v
"comment": "You have logged in",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6NDgxMiwidXNlcm5hbW
UiOiJzYWRpc2hh",
"remainingCount": null,
"expiration": 43200,
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpX.JpZCI6NDgxMiwidXNlcm5hb
WUiOiJzYWRpc2hh",
"refreshExpiration": 604800,
"userData": {
"id": <user_id>,
"fname": <fname>,
"lname": <lname>,
"address": <address>,
"mobile": <user_mobile>,
"email": <user_email>,
"defaultMask": <user_deafault_mask>,
"additional_mask": [
{
"mask": <mask_1>
},
{
"mask": <mask_2>

8|Page Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

 }
],
"accountType": <account type>,
"agreeToTerms": <agreement>,
"accountLocked": <account lock status>,
"accountStatus": <account status active/inactive>,
"campaignTwoPhaseLock": 0,
"walletBalance": <user_account_balance>,
"additional_addons": <additional addons >
},
"data": "",
"errCode": ""
}

Note: token received in the above success response should be used as the Authorization token.
EX: "Bearer<space>" + token

If failed
{
"status": "failed", v
"comment": <reason>,
"token": null,
"remainingCount": <remaining login attempts>,
"expiration": null,
"refreshToken": null,
"refreshExpiration": null,
"userData": null,
"data": "",
"errCode": <corresponding error code>
}

9|Page Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

4. SMS API (Version 2)
Version 2 is the updated version for creating sms campaigns. This version is optimized
compared to its predecessor.

End point: https://e-sms.dialog.lk/api/v2/sms

Method: HTTP POST
Type: application/json

Request Parameters
Header Parameter Description Mandatory/ Optional Data type
name If optional value
should be empty

Authorization Token received Mandatory String

v
during login
Format as follows
"Bearer<space>" +
accessToken

Parameter name in Description Mandatory/ Data type

body Optional

msisdn Number list array which has Mandatory Array

9 digit mobile numbers in
the following format

Ex:
[
{
mobile: ”7XXXXXXXX”
},
{
mobile: ” 7XXXXXXXX”
}
]

10 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

 message Message that should be Mandatory String
sent to customer
sourceAddress Source address or the mask Optional String
which is visible to customer.
If source Address is not
(since this is optional)
defined. Default mask
attached with the user
account will be used.
Maximum length: 11
transaction_id Every request should have a Mandatory Int
unique integer between 1
digit to maximum of 18
digits combined.
payment_method 0-pay using my esms wallet, Optional Int (0 Or 4)
4-pay using my esms API
package (Only available for
package users)
If you are a new user,set
this value to 0.
This parameter is an
optional vparameter where is
case not found, we assume
it is 0. 0 is for a wallet
payment
push_notification_url Endpoint to which delivery Optional String
notifications are pushed.
(Delivery reports are only
pushed if this parameter is
defined)

Sample JSON Object

{
"msisdn":
[
{ "mobile": "714551682" },
{ "mobile": "763625800" },
{ "mobile": "763625800" }
],
"sourceAddress": "Adeona",

11 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

 "message": "This is a test message",
"transaction_id": "<unique number for each transaction>",
"payment_method": "<payment_method>",
"push_notification_url": "https://xxx/xx?",
}

cURL Code snippet

curl --location --request POST ' https://e-sms.dialog.lk /api/v2/sms' \
--header 'Authorization: Bearer XXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--data-raw '{
"sourceAddress": "test_mask",
"message": "test message",
"transaction_id": "1001",
"payment_method": "4",
"msisdn": [
{
"mobile": "799999999" v
},
{
"mobile": "799999998"
}

],
"push_notification_url": " https://xxx/xx?",
}'

12 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

Response
Parameter name Description Mandatory/ Data type
Optional
Status Status of the request Mandatory String
Comment Comment to find the Mandatory String
failure reason if failed
Data Data Object Optional Object
This is empty for a failed
response
data -> campaignId Created campaign id Optional Number
data -> campaignCost Created campaign cost Optional Number
data -> walletBalance User Wallet Balance Optional Number
data -> userMobile User Mobile Optional Number
data -> userId User ID Optional Number
data -> duplicatesRemoved Duplicate numbers Optional Number
removed from the msisdn
list
data -> invalidNumbers Invalid numbers removed Optional Number
from the msisdn list
data -> Mobile
v numbers who Optional Number
mask_blocked_numbers blocked messages form
the specified mask
errCode Error Code Mandatory String

If success
{
"status": "success",
"comment": "Campaign Created, Campaign ID <campaign_id>, Campaign payment of (LKR)
<campaign_cost> was successful",
"data": {
"campaignId": <campaign_id>,
"campaignCost": <campaign_cost>,
"walletBalance": <available_wallet_balance>,
"userMobile": <user_mobile>,
"userId": <user_id>,
"duplicatesRemoved": <duplicates_removed_from_the_msisdn_list>,
"mask_blocked_numbers": <mobiles_who_blocked_the_mask>,

13 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

 "userId": <user_id>,
},
"errCode": ""

If failed
{
"status": "failed",
"comment": "<reason>",
"data": "",
"errCode": <relevant_eror_code>
}

Note: SMS API has demonstrated its reliability and efficiency within the tested limit of 1000
v is designed to handle high message volumes, surpassing this
recipient numbers. While the API
limit may have adverse effects on its performance for the particular user. We strongly advise
against exceeding the recommended limit to prevent potential disruptions in service, delayed
message delivery, or degraded performance.

14 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

5. Check created campaign status for a transaction id (Version 2)

Version 2 is the updated version for checking campaign status using transaction id. This version
is optimized compared to its predecessor.

End point: https://e-sms.dialog.lk/api/v2/sms/check-transaction

Method: HTTP POST
Type: application/json

Request Parameters
Header Parameter Description Mandatory/ Optional Data type
name If optional value
should be empty

Authorization Token received Mandatory String

during login
v
Format as follows
"Bearer<space>" +
accessToken

Parameter name in Description Mandatory/ Data type

body Optional

transaction_id Every request should have a Mandatory Int

unique integer between 1
digit to maximum of 18
digits combined.

Sample JSON Object

{
"transaction_id": "<transaction_id>",
}

15 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

cURL Code snippet

curl --location --request POST 'https://e-sms.dialog.lk/api/v2/sms/check-transaction' \

--header 'Authorization: Bearer XXXXXXXXX' \
--header 'Content-Type: application/json' \
--data-raw '{
"transaction_id":"126"
}'

Response
Parameter name Description Mandatory/ Data type
Optional
status Status of the Mandatory String
request
comment Comment to find Mandatory String
the failure reason if
failed
data Data Object Optional Object
This is empty for a
v failed response
data -> campaign status Status of the Optional String
created campaign
errCode Corresponding Mandatory String
Error Code
transaction_id Transaction ID sent Mandatory Int
by the user

If success
{
"status": "success",
"comment": "campaign found for the transaction id:<id> ",
"data": {
"campaign status": "completed"
},
"errCode": "",
"transaction_id": "<transaction_id>"
}

16 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

If failed
{
"status": "failed",
"comment": "<reason>",
"data": "",
"errCode": "<error_code>",
"transaction_id": "<transaction_id>"

17 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

 6. Plugins
6.1. Working Scenario

Get Access Token

Save Access Token in local

memory

Check whether the access

When Token token is exipred or not
Expired
v
Send SMS

Check created campaign

status for a transaction id

18 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

 6.2. Java
6.2.1. Supported Projects
6.2.1.1. Maven projects
6.2.1.2. Spring Boot maven projects
6.2.2. Installation
Find sample maven project based on Java Jdk 8 to guide how to communicate with SMS API
library from https://github.com/adeonatech/Java-SMS-API-lib-maven-sample and find latest
version of library in Maven Central Repository when click on the maven badge in README.md.
Then add the dependency to your project.

Apache Maven

<dependency>
v
<groupId>net.adeonatech</groupId>
<artifactId>SmsAPI</artifactId>
<version>1.0.5</version>
</dependency>

Gradle Groovy DSL

implementation 'net.adeonatech:SmsAPI:1.0.5'

19 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

 6.2.3. Quick Start
6.2.3.1. Get Access token
After sign up in https://esms.dialog.lk you must need to get access token using username,
password:

1. Create the object of “TokenBody” for set data to get token:

TokenBody tokenBody = new TokenBody();

2. Set username through object:

tokenBody.setUsername(<YOUR USERNAME>);

3. Set password through object:

tokenBody.setPassword(<YOUR PASSWORD>);

4. Create the object of “SendSMSImpl”

v to use method to get token :
SendSMSImpl sendSMS = new SendSMSImpl();

5. Get token using “getToken()” method through object:

sendSMS.getToken(<new TokenBody()>){
return <new TokenResponse()>
}
6. Get “TokenResponse” type return values:
a. Get token
sendSMS.getToken(<new TokenBody()>).getToken();
b. Get comment
sendSMS.getToken(<new TokenBody()>).getComment();
c. Get status
sendSMS.getToken(<new TokenBody()>).getStatus();
d. Get remaining count
sendSMS.getToken(<new TokenBody()>).getRemainingCount();

20 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

 e. Get expiration
sendSMS.getToken(<new TokenBody()>).getExpiration();
f. Get refresh token
sendSMS.getToken(<new TokenBody()>).getRefreshToken();
g. Get refresh expiration
sendSMS.getToken(<new TokenBody()>).getRefreshExpiration();
h. Get error code
sendSMS.getToken(<new TokenBody()>).getErrCode();
i. Get user data
i. Get wallet balance
sendSMS.getToken(<new TokenBody()>).getUderData().getWalletBalance();
ii. Get default mask
sendSMS.getToken(<new TokenBody()>).getUderData().getDefaultMask();
iii. Get email
v
sendSMS.getToken(<new TokenBody()>).getUderData().getEmail();
iv. Get mobile
sendSMS.getToken(<new TokenBody()>).getUderData().getMobile();
v. Get address
sendSMS.getToken(<new TokenBody()>).getUderData().getAddress();
vi. Get last name
sendSMS.getToken(<new TokenBody()>).getUderData().getLname();
vii. Get first name
sendSMS.getToken(<new TokenBody()>).getUderData().getFname();
viii. Get id
sendSMS.getToken(<new TokenBody()>).getUderData().getId();
ix. Get additional masks
sendSMS.getToken(<new
TokenBody()>).getUderData().getAdditional_mask().get(0).getMask();

21 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

example:

TokenBody tokenBody = new TokenBody();

tokenBody.setUsername("nimal");
tokenBody.setPassword("Admin#67!");

SendSMSImpl sendSMS = new SendSMSImpl();

String token = sendSMS.getToken(tokenBody).getToken();

6.2.4. Save Access token in local memory

v should save it in the local memory. When call for every other
After getting the access token you
methods you should set the saved access token as a parameter to get success response.

6.2.5. Check whether the access token expired or not

When access token expired the response by sendSMS.getToken(<new
TokenBody()>).getComment() will be “Authentication Token Expired”. Then again get new
token and save it to the local memory and continue your process.

22 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

 6.2.6. Send SMS

1. Create the object of “SendTextBody” for set data to get token:

SendTextBody sendTextBody = new SendTextBody();

2. Set source address through object:

SendTextBody.setSourceAddress(<YOUR SOURCE ADDRESS>);

3. Set message through object:

sendTextBody.setMessage(<YOUR MESSAGE>);

4. Set transaction id through object:

sendTextBody.setTransaction_id(<YOUR TRANSACTION ID>);

5. Set msisdns through creating

v the object of “SendSMSImpl”:
SendSMSImpl sendSMS = new SendSMSImpl();
sendTextBody.setMsisdn(sendSMS.setMsisdns(new String[]{“<MOBILE 1>”,”< MOBILE
2>”}));

6. Send SMS using “sendText()” method through created object of “SendSMSImpl”:

sendSMS.sendText(<new SendTextBody()>, <String token>){
return <new SendTextResponse()>
}
7. Get “SendTextResponse” type return values:
a. Get comment
sendSMS.sendText(<new SendTextBody()>, <String token>).getComment();
b. Get status
sendSMS.sendText(<new SendTextBody()>, <String token>).getStatus();
c. Get error code
sendSMS.sendText(<new SendTextBody()>, <String token>).getErrCode();

23 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

 d. Get data
i. Get invalid numbers
sendSMS.sendText(<new SendTextBody()>, <String token>).getData().getInvalidNumbers();
ii. Get default mask
sendSMS.sendText(<new SendTextBody()>, <String token>).getData().getInvalidNumbers();
iii. Get duplicates removed
sendSMS.sendText(<new SendTextBody()>, <String token>).getData().getDuplicatesRemoved();
iv. Get user id
sendSMS.sendText(<new SendTextBody()>, <String token>).getData().getUserId();
v. Get user mobile
sendSMS.sendText(<new SendTextBody()>, <String token>).getData().getUserMobile();
vi. Get wallet balance
sendSMS.sendText(<new SendTextBody()>, <String token>).getData().getWalletBalance();
vii. Get campaign cost
sendSMS.sendText(<new SendTextBody()>,
v <String token>).getData().getCampaignCost();
viii. Get campaign id
sendSMS.sendText(<new SendTextBody()>, <String token>).getData().getCampaignId();

example:

SendSMSImpl sendSMS = new SendSMSImpl();

SendTextBody sendTextBody = new SendTextBody();

sendTextBody.setMsisdn(sendSMS.setMsisdns(new String[]{"71XXXXXXX", "71XXXXXXX"}));

sendTextBody.setSourceAddress("sourse1");
sendTextBody.setMessage("Hi! this is test from JAVA lib");
sendTextBody.setTransaction_id("144");

TransactionBody transactionBody = new TransactionBody();

transactionBody.setTransaction_id("144");

String response = sendSMS.sendText(sendTextBody,

sendSMS.getToken(tokenBody).getToken()).getStatus();

24 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

 6.2.7. Check created campaign status for a transaction id

1. Create the object of “TransactionBody” for set data to get token:

TransactionBody transactionBody = new TransactionBody();

2. Set transaction id through object:

transactionBody.setTransaction_id(<YOUR TRANSACTION ID>);

3. Create the object of “SendSMSImpl”:

SendSMSImpl sendSMS = new SendSMSImpl();

4. Get campaign status for the transaction id using “getTransactionIDStatus()” method

through created object of “SendSMSImpl”:
sendSMS.getTransactionIDStatus(<new TransactionBody()>, <String token>){
return <new TransactionResponse()>
v
}
5. Get “TransactionResponse” type return values:
a. Get comment
sendSMS.getTransactionIDStatus(<new TransactionBody()>, <String token>).getComment();
b. Get status
sendSMS.getTransactionIDStatus(<new TransactionBody()>, <String token>).getStatus();
c. Get error code
sendSMS.getTransactionIDStatus(<new TransactionBody()>, <String token>).getErrCode();
d. Get transaction id
sendSMS.getTransactionIDStatus(<new TransactionBody()>, <String
token>).getTransaction_id();
e. Get data
i. Get campaign status
sendSMS.getTransactionIDStatus(<new TransactionBody()>, <String
token>).getDataTransaction().getCampaign_status();

25 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

example:

SendSMSImpl sendSMS = new SendSMSImpl();

TransactionBody transactionBody = new TransactionBody();

transactionBody.setTransaction_id("144");

String campaignStatus =
sendSMS.getTransactionIDStatus(transactionBody,sendSMS.getToken(tokenBody).getToken()).getDataTransaction
().getCampaign_status();

26 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

 6.3. PHP
6.3.1. Installation
Find library source code from https://github.com/adeonatech/PHP-SMS-API-lib and download it
to your selected path. Then call

<?php

require(‘<YOUR LIBRARY PATH>/PHP-SMS-API-lib-main/send_sms_impl.php’);

?>

inside your PHP code.

27 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

 6.3.2. Quick Start
6.3.2.1. Get Access token
After sign up in https://esms.dialog.lk you must need to get access token using username,
password:

1. Create the object of “SendSMSImpl” to use method to get token:

$sendSmsImpl = new SendSMSImpl();

2. Set username through object:

$tokenBody->setUsername(<YOUR USERNAME>);

3. Set password through object:

$tokenBody->setPassword(<YOUR PASSWORD>);

4. Create the object of “TokenBody”

v for set data to get token:
$tokenBody = new TokenBody();

5. Get token using “getToken()” method through object:

$sendSmsImpl->getToken(<new TokenBody()>){
return <new TokenResponse()>
}
6. Get “TokenResponse” type return values:
a. Get token
$sendSmsImpl->getToken((<new TokenBody()>)->getToken();
b. Get comment
$sendSmsImpl->getToken((<new TokenBody()>)->getComment();
c. Get status
$sendSmsImpl->getToken((<new TokenBody()>)->getStatus();
d. Get remaining count
$sendSmsImpl->getToken((<new TokenBody()>)->getRemainingCount();

28 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

 e. Get expiration
$sendSmsImpl->getToken((<new TokenBody()>)->getExpiration();
f. Get refresh token
$sendSmsImpl->getToken((<new TokenBody()>)->getRefreshToken();
g. Get refresh expiration
$sendSmsImpl->getToken((<new TokenBody()>)->getRefreshExpiration();
h. Get error code
$sendSmsImpl->getToken((<new TokenBody()>)->getErrCode();
i. Get user data
i. Get wallet balance
$sendSmsImpl->getToken((<new TokenBody()>)->getUderData()-
>getWalletBalance();
ii. Get default mask
$sendSmsImpl->getToken((<new TokenBody()>)->getUderData()->getDefaultMask();
v
iii. Get email
$sendSmsImpl->getToken((<new TokenBody()>)->getUderData()->getEmail();
iv. Get mobile
$sendSmsImpl->getToken((<new TokenBody()>)->getUderData()->getMobile();
v. Get address
$sendSmsImpl->getToken((<new TokenBody()>)->getUderData()->getAddress();
vi. Get last name
$sendSmsImpl->getToken((<new TokenBody()>)->getUderData()->getLname();
vii. Get first name
$sendSmsImpl->getToken((<new TokenBody()>)->getUderData()->getFname();
viii. Get id
$sendSmsImpl->getToken((<new TokenBody()>)->getUderData()->getId();
ix. Get additional masks
$sendSmsImpl->getToken((<new TokenBody()>)->getUserData()->
getAdditionalMask()[0]['mask']

29 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

example:

$sendSmsImpl = new SendSMSImpl();

$tokenBody = new TokenBody();

$tokenBody->setUsername("nimal”);
$tokenBody->setPassword("Admin#67!");

$sendTextBody = new SendTextBody();

$token = $sendSmsImpl->getToken($tokenBody)->getToken();

6.3.3. Save Access token in local memory

After getting the access token you should save it in the local memory. When call for every other
methods you should set the saved access token as a parameter to get success response.
v

6.3.4. Check whether the access token expired or not

When access token expired the response by $sendSmsImpl->getToken((<new TokenBody()>)-
>getComment() will be “Authentication Token Expired”. Then again get new token and save it
to the local memory and continue your process.

30 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

 6.3.5. Send SMS

1. Create the object of “SensSMSImpl” to send SMS:

$sendSmsImpl = new SendSMSImpl();

2. Create the object of “SendTextBody” for set data to get token:

$sendTextBody = new SendTextBody();

3. Set source address through object:

$sendTextBody->setSourceAddress(<YOUR SOURCE ADDRESS>);

4. Set message through object:

$sendTextBody->setMessage(<YOUR MESSAGE>);

v
5. Set transaction id through object:
$sendTextBody->setTransactionId(<YOUR TRANSACTION ID>);

6. Set msisdns through the created object of “SendSMSImpl”:

$sendTextBody->setMsisdn($sendSmsImpl->setMsisdns(array("<MOBILE 1>","<MOBILE 2>")));

7. Send SMS using “sendText()” method through created object of “SendSMSImpl”:

$sendSmsImpl->sendText(<new SendTextBody>,$token){
return <new SendTextResponse>
}
8. Get “SendTextResponse” type return values:
a. Get comment
$sendSmsImpl->sendText(<new SendTextBody>,$token)->getComment();
b. Get status
$sendSmsImpl->sendText(<new SendTextBody>,$token)->getStatus();

31 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

 c. Get error code
$sendSmsImpl->sendText(<new SendTextBody>,$token)->getErrCode();
d. Get data
i. Get invalid numbers
$sendSmsImpl->sendText(<new SendTextBody>,$token)->getData()->getInvalidNumbers();
ii. Get default mask
$sendSmsImpl->sendText(<new SendTextBody>,$token)->getData()->getInvalidNumbers();
iii. Get duplicates removed
$sendSmsImpl->sendText(<new SendTextBody>,$token)->getData()->getDuplicatesRemoved();
iv. Get user id
$sendSmsImpl->sendText(<new SendTextBody>,$token)->getData()->getUserId();
v. Get user mobile
$sendSmsImpl->sendText(<new SendTextBody>,$token)->getData()->getUserMobile();
vi. Get wallet balance
$sendSmsImpl->sendText(<new SendTextBody>,$token)->getData()->getWalletBalance();
v
vii. Get campaign cost
$sendSmsImpl->sendText(<new SendTextBody>,$token)->getData()->getCampaignCost();
viii. Get campaign id
$sendSmsImpl->sendText(<new SendTextBody>,$token)->getData()->getCampaignId();
example:

$sendSmsImpl = new SendSMSImpl();

$sendTextBody = new SendTextBody();

$sendTextBody->setSourceAddress("source1");
$sendTextBody->setMsisdn($sendSmsImpl->setMsisdns(array("71XXXXXXX","71XXXXXXX")));
$sendTextBody->setTransactionId("146");
$sendTextBody->setMessage("Hi this is test from PHP");

$transactionBody = new TransactionBody();

$transactionBody->setTransactionId("146");

$response = $sendSmsImpl->sendText($sendTextBody, $sendSmsImpl->getToken($tokenBody)-

>getToken())->getData()->getUserId();

32 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

 6.3.6. Check created campaign status for a transaction id

1. Create the object of “SendSMSImpl”:

$sendSmsImpl = new SendSMSImpl();

2. Create the object of “TransactionBody” for set data to get token

$transactionBody = new TransactionBody();

3. Set transaction id through object:

$transactionBody->setTransactionId (<YOUR TRANSACTION ID>);

4. Get campaign status for the transaction id using “getTransactionIDStatus()” method

through created object of “SendSMSImpl”:
$sendSmsImpl->getTransactionIDStatus (<new TransactionBody>, <$token>){
return <new TransactionResponse>
v
}
5. Get “TransactionResponse” type return values:
a. Get comment
$sendSmsImpl->getTransactionIDStatus (<new TransactionBody>, <$token>)->getComment();
b. Get status
$sendSmsImpl->getTransactionIDStatus (<new TransactionBody>, <$token>)->getStatus();
c. Get error code
$sendSmsImpl->getTransactionIDStatus (<new TransactionBody>, <$token>)->getErrCode();
d. Get transaction id
$sendSmsImpl->getTransactionIDStatus (<new TransactionBody>, <$token>)-
>getTransactionId();
e. Get data
i. Get campaign status
$sendSmsImpl->getTransactionIDStatus (<new TransactionBody>, <$token>)->getData()-
>getCampaignStatus();

33 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

example:

$sendSmsImpl = new SendSMSImpl();

$transactionBody = new TransactionBody();

$transactionBody->setTransactionId("146");

$campaignStatus = $sendSmsImpl->getTransactionIDStatus($transactionBody, $sendSmsImpl-

>getToken($tokenBody)->getToken())->getData()->getCampaignStatus();

34 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

7. Send SMS via GET Request

Prerequisite: ESMS admin has to provide the ability to use this functionality. By default, it is not
available.

How to generate esmsqk ? (Key to send SMS via GET)

Once you log into the eSMS portal, you can see a section which is named as URL Message Key

35 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

Why can’t I see URL Message Key section on my dashboard?

• Try clearing your browser cache and login again.

• If the issue still exists, you don’t have the necessary access to consume this resource.
Please request administrator assistance to enable the feature.

End point: https://e-sms.dialog.lk/api/v1/message-via-url/create/url-

campaign?esmsqk=<key> & list=<number_list> &source_address=<mask>
&message=<message>
Method: HTTP GET

Request Params
Parameter name Description Mandatory/ Optional Data type

If optional value should

be empty
v
esmsqk Client key to send messages via Mandatory String
GET requests. This can be
generated via eSMS user portal.
eSMS user account can only
have one key.
(If a new key is generated, the
old key will be invalid)
list Comma separated mobile Mandatory String
number list.
Each mobile number has to be
either of the following formats.
i.799999999 (9 digits)
ii.0799999999(10 digits)
iii. 94799999999

(11digits)

source_address Source address or the mask Optional (If not defined, String
which is visible to customer. default mask of the user
will be used)

36 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

 message Message that should be sent to Mandatory String
customer
paymentType Payment method for the Optional Integer
campaign. As for now, only via
package (4) and via wallet (0) are
the available payment methods.

Note:
0: payment via wallet
4: payment via package
If paymentType is not defined or
empty, it is considered as a
payment made via wallet.

push_notification_url Endpoint to which delivery Optional String

notifications are pushed. (Delivery
reports are only pushed if this
parameter is defined)

Sample Request v
https://e-sms.dialog.lk/api/v1/message-via-url/create/url-
campaign?esmsqk=eyJhbGciOiJIUzI1NiIsInR5c&list=0799999999,
799999999,94799999999&source_address=test&message=Welcome&push_notification_url=ht
tps://xx/xx'

cURL Code snippet

curl --location --request GET 'http://localhost:3000/api/v1/message-via-url/create/url-
campaign?esmsqk=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MTUsImlhdCI6MTY1NTM1
MDkyNCwiZXhwIjo0Nzc5NTUzMzI0fQ.EqylAmt1_CWOEpcrQA--kRiW-
qFHNktMTz6Y1YDA1f4&list=0714551682,763625800,94777337045&source_address=adeona&
message=Welcome&push_notification_url=https://xx/xx'' \
--data-raw ''

37 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

Response
Parameter name Description Mandatory/ Data type
Optional
<integer_value> Integer value Mandatory Integer
(Check the
response id table)

If success
1

If failed
<error_id>

v
Note: Get Request SMS API has demonstrated its reliability and efficiency within the tested limit
of 100 recipient numbers. While the API is designed to handle high message volumes, surpassing
this limit may have adverse effects on its performance for the particular user. We strongly advise
against exceeding the recommended limit to prevent potential disruptions in service, delayed
message delivery, or degraded performance.

38 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

 Response id Description
1 Success
2001 Error occurred during campaign creation
2002 Bad request
2003 Empty number list
2004 Empty message body
2005 Invalid number list format
2006 Not eligible to send messages via get
requests (Admin haven’t provided the
access level)
2007 Invalid key (esmsqk parameter is invalid)
2008 Not enough money in the user's wallet or
v not enough messages left in the package
for the user. (When consuming package
payments)
2009 No valid numbers found after the removal
of mask blocked numbers.
2010 Not eligible to consume packaging
2011 Transactional error
2012 Doesn’t have the access for mask.
2020 Too many requests

Above response id(s) only valid for send SMS via get requests (section 7).

39 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

8. Check account balance via GET Request
Prerequisite: Only available for users who are eligible for sending SMS via GET requests.
(Section 7)
End point: https://e-sms.dialog.lk/api/v1/message-via-url/
check/balance?esmsqk=<key>
Method: HTTP GET

Request Params
Parameter name Description Mandatory/ Data type
Optional

If optional value
should be empty

esmsqk Client key tov send messages via GET Mandatory String
requests. This can be generated via eSMS
user portal. eSMS user account can only
have one key.
(If a new key is generated, the old key will
be invalid)

Sample Request
https://e-sms.dialog.lk/api/v1/message-
viaurl/check/balance?esmsqk=eyJhbGciOiJIUzI1NiIsInR5c

If success
1|<balance>
Pipe mark separate the status and the balance. In the above,1 is the success and it is followed by
“|” and then the account balance

If failed
<error_id>|0

40 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

Pipe mark separates the status and the balance. In the above, <error_id> is for a failure (check
table below) and it is followed by “|” and the account balance will be 0 for all failed requests.

Response id Description
1|<balance> Success
2001|0 Error occurred during campaign creation
2002|0 Bad request
2006|0 Not eligible to send messages via get
requests (Admin haven’t provided the
access level)
2007|0 Invalid key (esmsqk parameter is invalid)

Above response id(s) only valid for send SMS via get requests (section 8).

41 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

9. Error Codes
Below error codes are not applicable to section 8(Send SMS via GET Request) and section 9(Check
account balance via GET Request) of this document.

Error Code Description

100 Invalid Token (Token Expired)
101 Invalid Request Parameters
102 User account not found or not a valid account
103 Logical Error
104 Transaction ID is already used
105 Invalid Token Signature
106 Token not found in the header (Or token is not attached as a bearer
token)
107 One or morevmandatory parameters in the request in either missing or
invalid
108 User don’t have such active mask eligible to send messages
109 There is no single valid mobile number after removing invalids,
duplicates and mask blocked numbers from msisdn list.
110 Not eligible to consume packaging
111 Package payments can only be used for campaigns scheduled for this
month.
112 Number of messages left in the package is less than the campaign
messages.
113 Package Maintenance Downtime.
114 Not enough wallet balance to run the campaign.
115 Username or password invalid
116 Account locked
117 Too many requests

42 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd

 999 Internal Server Error

10. Delivery report API

If 3rd party passes “push_notification_url” in the API request, then eSMS platform will send
delivery notifications as GET request.

Following is the format that eSMS system is calling 3rd party platforms. Therefore, it is mandatory
to implement delivery report end point as per below.

Method: HTTP GET

Request format: <end point passed in “push_notification_url”>campaignId=<campaign ID
returned in the response of campaign creation API>&msisdn=<MSISDN/ mobile
number>&status=<status>
Sample request
v
https://adeonatech.net/api/v1/delivery-report-
listner?campaignId=25&msisdn=94777888665&status=1

Possible values for status

Status Description
1 Successfully submitted to SMSC
2 SMS submission failed due to number not valid Or connectivity failure
3 Successfully delivered
4 Delivery failed

For delivery success scenario eSMS will send status code 1 and 3. Order of the status code
submission is not guaranteed. Therefore, its 3rd parties responsibility to develop the application
processing accordingly.

43 | P a g e Confidential – All right reserved to Adeona Technologies (Pvt) Ltd