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": "abc@example.com",
"password": "abc@123"
}

Sample response body

"accessToken":"eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzdXBlckBteWxpbmV4LmNvbSIsInR5cGUiOiJhY
2Nlc3NUb2tlbiIsImV4cCI6MTYyOTIyMzM0NiwiaWF0IjoxNjI5MjIyNzQ2fQ.QefL26z2LKOeVX9awXjQaji
bL9MhzE4XjXqwaQ-ypWSXYbsSptn6wHIHcROtbh5P34MTORpZh98yykBQ298Fkw",

"refreshToken":"eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzdXBlckBteWxpbmV4LmNvbSIsInR5cGUiOiJy
ZWZyZXNoVG9rZW4iLCJleHAiOjE2MjkzMDkxNDYsImlhdCI6MTYyOTIyMjc0Nn0.VUtAnwdSjsMesxs90lw39
GvYOLK8QY_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/token/accessToken

Sample request headers

GET /api/token/accessToken HTTP/1.1

Content-Type: application/json
Accept: */*
X-API-VERSION: v1
Authorization: Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzdXBlckBteWxpbmV4LmNvbSIsInR5cGUiOiJyZWZyZXNoVG9rZW4i
LCJleHAiOjE2Mjk1Njg3NzgsImlhdCI6MTYyOTQ4MjM3OH0.tbA81r58lZv3BT0lIbV8BT1C8eXEgYVUNn_u7
5uQtsMGKGEqhtmO1YKeGvG4mQPG6ZBhI_JSa0N9fSUybo-AMg

Sample response body

{
"accessToken":
"eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzdXBlckBteWxpbmV4LmNvbSIsInR5cGUiOiJhY2Nlc3NUb2tlbiI
sImV4cCI6MTYyOTIyMzM0NiwiaWF0IjoxNjI5MjIyNzQ2fQ.QefL26z2LKOeVX9awXjQajibL9MhzE4XjXqwa
Q-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/sendsms

Sample request headers

POST /api/sendsms HTTP/1.1

Content-Type: application/json
Accept: */*
X-API-VERSION: v1
Authorization: Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzdXBlckBteWxpbmV4LmNvbSIsInR5cGUiOiJyZWZyZXNoVG9rZW4i
LCJleHAiOjE2Mjk1Njg3NzgsImlhdCI6MTYyOTQ4MjM3OH0.tbA81r58lZv3BT0lIbV8BT1C8eXEgYVUNn_u7
5uQtsMGKGEqhtmO1YKeGvG4mQPG6ZBhI_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.

If the delivery report required need to enable the delivery Report Request field 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"=>"test@test.com","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 = "test@test.com"
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