BULK SMS API DOCUMENT

Using OAuth 2.0 to Access Bulk SMS APIs

This document explains how SMS client applications should use OAuth 2.0 endpoints to
implement OAuth 2.0 authorization to access Bulk SMS APIs. OAuth 2.0 allows users to access
send SMS endpoint while keeping their usernames, passwords, and other information private.
To begin, obtain OAuth 2.0 client credentials from your service agent. Then your client
application can request an access token and a refresh token from the Bulk SMS Authorization
Server, extract the access token from the response, and send the token to the Send SMS API to
send SMSs.

OAuth 2.0 Login

This endpoint is used to retrieve the refresh and access tokens required to access the send SMS
API.
Request URL:: https://bsms.hutch.lk/api/login

POST /api/login HTTP/1.1Content-Type: application/jsonAccept: */*X-API-VERSION: v1

Sample request body

{
"username": "[email protected]",
"password": "abc@123"
}

Sample response body

{
"accessToken":"eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzdXBlckBteWxpbmV4LmNvbSIsInR5cGUiO
iJhY2Nlc3NUb2tlbiIsImV4cCI6MTYyOTIyMzM0NiwiaWF0IjoxNjI5MjIyNzQ2fQ.QefL26z2LKOeVX9awXj
QajibL9MhzE4XjXqwaQ-ypWSXYbsSptn6wHIHcROtbh5P34MTORpZh98yykBQ298Fkw",
"refreshToken":"eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzdXBlckBteWxpbmV4LmNvbSIsInR5cGUi
OiJyZWZyZXNoVG9rZW4iLCJleHAiOjE2MjkzMDkxNDYsImlhdCI6MTYyOTIyMjc0Nn0.VUtAnwdSjsMesxs90
lw39GvYOLK8QY_cyHiFmYzYGtiX9AtCk1SmvWgn2-lh-5EgWJit6gRssHbeQvH-rqF5RA"
}

You can use the access token to access the send SMS API and the refresh token to renew the
access token when expired.
OAuth 2.0 Token Renew
This endpoint is used to renew the access token required to access the send SMS API, using the
refresh token provided at the login. The refresh token is sent in the header (Authorization:
Bearer [refresh token]).
Request URL :: https://bsms.hutch.lk/api/login/api/token/accessToken

Sample request headers

GET /api/token/accessToken HTTP/1.1

Content-Type: application/json
Accept: */*
X-API-VERSION: v1
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzdXBlckBteWxpbmV4LmNvbSIsInR5cG
UiOiJyZWZyZXNoVG9rZW4iLCJleHAiOjE2Mjk1Njg3NzgsImlhdCI6MTYyOTQ4MjM3OH0.tbA81r58lZv3BT0
lIbV8BT1C8eXEgYVUNn_u75uQtsMGKGEqhtmO1YKeGvG4mQPG6ZBhI_JSa0N9fSUybo-AMg

Sample response body

{
"accessToken": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzdXBlckBteWxpbmV4LmNvbSIsInR5cGUi
OiJhY2Nlc3NUb2tlbiIsImV4cCI6MTYyOTIyMzM0NiwiaWF0IjoxNjI5MjIyNzQ2fQ.QefL26z2LKOeVX9awX
jQajibL9MhzE4XjXqwaQ-ypWSXYbsSptn6wHIHcROtbh5P34MTORpZh98yykBQ298Fkw"
}

If you receive HTTP error code 401 (Unauthorized) for the token renew API request, you should
call the login API to retrieve a fresh set of access and refresh tokens.
OAuth 2.0 Send SMS
This endpoint is used to send SMS, using the access token. The access token is sent in the
header (Authorization: Bearer [access token]).
Request URL :: https://bsms.hutch.lk/api/login/api/sendsms

Sample request headers

POST /api/sendsms HTTP/1.1

Content-Type: application/json
Accept: */*
X-API-VERSION: v1
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzdXBlckBteWxpbmV4LmNvbSIsInR5cG
UiOiJyZWZyZXNoVG9rZW4iLCJleHAiOjE2Mjk1Njg3NzgsImlhdCI6MTYyOTQ4MjM3OH0.tbA81r58lZv3BT0
lIbV8BT1C8eXEgYVUNn_u75uQtsMGKGEqhtmO1YKeGvG4mQPG6ZBhI_JSa0N9fSUybo-AMg

Sample request body

{
"campaignName": "Test campaign",
"mask": "Test",
"numbers": "94780000000",
"content": "Test message"
}

Sample response body

{
"serverRef": 32225
}

If you receive HTTP error code 401 (Unauthorized) for the send SMS API request, you should
call the token renew API to retrieve a fresh access token.
Delivery report Enabling
If the delivery report required need to enable the delivery Report Request field fill in the Body
of send SMS as true.

"campaignName": "Test campaign",

"mask": "Test",

"numbers": "94780000000",

"deliveryReportRequest": true,

"content": "Test message

 Sample PHP Code :: Request Access Token

function login(){

echo "Trying to login\n";

global $config_file;

$post_data = array("username"=>"[email protected]","password"=>"testtest");

$ch = curl_init('https://bsms.hutch.lk/api/login');

curl_setopt_array($ch, array(

CURLOPT_POST => TRUE,

CURLOPT_RETURNTRANSFER => TRUE,

CURLOPT_HTTPHEADER => array(

'Content-Type: application/json',

'Accept: */*',

'X-API-VERSION: v1'

),

CURLOPT_POSTFIELDS => json_encode($post_data)

));

$response = curl_exec($ch);

if($response === FALSE){

die(curl_error($ch));

$responseData = json_decode($response, TRUE);

curl_close($ch);

//echo $responseData['published'];

file_put_contents($config_file, json_encode($responseData, JSON_PRETTY_PRINT));

 Sample PHP Code :: Send SMS

$ch = curl_init('https://bsms.hutch.lk/api/sendsms');

curl_setopt_array($ch, array(

CURLOPT_POST => TRUE,

CURLOPT_RETURNTRANSFER => TRUE,

CURLOPT_HTTPHEADER => array(

'Content-Type: application/json',

'Accept: */*',

'X-API-VERSION: v1',

'Authorization: Bearer '.$access_token

),

CURLOPT_POSTFIELDS => json_encode($post_data)

));

$response = curl_exec($ch);
 Sample VB6 Code

Option Explicit

Private tokenFile As String

Private accessToken As String

Private refreshToken As String

Private userName As String

Private password As String

Public Sub test()

Debug.Print sendSms("test", "Test", "947xxxxxxx", "This is a test message from the Bulk SMSC, using VB")

Debug.Print "Message Sent"

End Sub

Private Sub init()

Close

tokenFile = "E:\path\token.txt"

userName = "[email protected]"

password = "testpwd"

End Sub

Public Function sendSms(campaignName As String, mask As String, numbers As String, content As String) As String

init

Dim ss() As String

ss = readTokenFile()

accessToken = ss(0)
refreshToken = ss(1)

If (accessToken = "error") Then

Call login

ss = readTokenFile()

accessToken = ss(0)

refreshToken = ss(1)

If (accessToken = "error") Then

Debug.Print "Token renewal failed"

sendSms = "Token renewal failed"

Exit Function

End If

End If

'Debug.Print accessToken & "," & refreshToken

sendSms = callSmsApi(campaignName, mask, numbers, content)

End Function

Private Function callSmsApi(campaignName As String, mask As String, numbers As String, content As String) As String

Dim hCon As Object

Dim json As String

Dim URL As String

URL = "https://bsms.hutch.lk/api/sendsms"

json = "{" _

& Chr(34) & "campaignName" & Chr(34) & ":" & Chr(34) & campaignName & Chr(34) & "," _

& Chr(34) & "mask" & Chr(34) & ":" & Chr(34) & mask & Chr(34) & "," _

& Chr(34) & "numbers" & Chr(34) & ":" & Chr(34) & numbers & Chr(34) & "," _
 & Chr(34) & "content" & Chr(34) & ":" & Chr(34) & content & Chr(34) & _

"}"

Debug.Print json

Set hCon = CreateObject("WinHttp.WinHttpRequest.5.1")

With hCon

.Open "POST", URL, False

.setRequestHeader "Content-type", "application/json"

.setRequestHeader "Accept", "*/*"

.setRequestHeader "X-API-VERSION", "v1"

.setRequestHeader "Authorization", "Bearer " & accessToken

.Send json

callSmsApi = .ResponseText

End With

End Function

Private Sub login()

Dim hCon As Object

Dim json As String

Dim response As String

Dim URL As String

URL = "https://bsms.hutch.lk/api/login"

json = "{" _

& Chr(34) & "username" & Chr(34) & ":" & Chr(34) & userName & Chr(34) & "," _

& Chr(34) & "password" & Chr(34) & ":" & Chr(34) & password & Chr(34) & _

"}"

Debug.Print json
 Set hCon = CreateObject("WinHttp.WinHttpRequest.5.1")

With hCon

.Open "POST", URL, False

.setRequestHeader "Content-type", "application/json"

.setRequestHeader "Accept", "*/*"

.setRequestHeader "X-API-VERSION", "v1"

.Send json

response = .ResponseText

End With

response = makePretty(response)

Debug.Print response

writeTokenFile response

End Sub

Private Function readTokenFile() As String()

Dim strFileContent As String

Dim ss(0 To 1) As String

On Error GoTo fileErr:

Open tokenFile For Input As #1

strFileContent = Input(LOF(1), 1)

Close #1

'Debug.Print strFileContent

Dim a() As String

a = Split(strFileContent, ",")

a(0) = strip(a(0))

a(1) = strip(a(1))

Dim b() As String

b = Split(a(0), ":")

ss(0) = b(1)

Dim c() As String

c = Split(a(1), ":")
 ss(1) = c(1)

readTokenFile = ss

Exit Function

fileErr:

ss(0) = "error"

ss(1) = "error"

readTokenFile = ss

End Function

Private Function strip(ByVal x As String)

x = Replace(x, "{", "")

x = Replace(x, "}", "")

x = Replace(x, " ", "")

x = Replace(x, vbTab, "")

x = Replace(x, vbCrLf, "")

x = Replace(x, vbCr, "")

x = Replace(x, vbLf, "")

x = Replace(x, Chr(34), "")

strip = x

End Function

Private Function makePretty(ByVal x As String)

x = Replace(x, "{", "{" & vbCr & vbTab)

x = Replace(x, "}", vbCr & "}")

x = Replace(x, ",", "," & vbCr & vbTab)

x = Replace(x, ":", ": ")

makePretty = x

End Function

Private Function writeTokenFile(strFileContent As String)

 Open tokenFile For Output As #2

Print #2, strFileContent

Close #2

End Function