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