Cloud - API Connection Manual SMS Brandname v1.2 Eng
Cloud - API Connection Manual SMS Brandname v1.2 Eng
LTD
p. 1
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
3.4.4.2. Response API return Client......................................................................................... 19
4. Get delivery report of sent messages............................................................................................... 20
4.1. Get delivery report of Customer Care messages....................................................................20
4.2. Get delivery report of QC Messages....................................................................................... 22
4.2.1. Get the status of Campaign..............................................................................................22
4.2.2. Get status of every single QC message............................................................................ 23
5. Error code table................................................................................................................................ 24
p. 2
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
MANUAL GENERAL INFORMATION
Service Information
Versio
Date PIC Page of change Changed content
n
20/06/202
khiemdd 2.1 page.12 Adding field RequestId
1
1. Overview
1.1. Introduction
This is a description document, instructions for connecting to the SMS service API
Brandname of FPT International Telecommunication Company Limited.
p. 3
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
The document is written to support users, programmers get authentication
information, perform API connection steps to send SMS messages to users.
1.2. Abbreviation list – terms
Abbr./Terms Definition Note
SMS Short message service over
telecommunications network (Short
Messaging Service)
SMS Brandname Brandname Short Message Service
API Application Programming Interface
CSKH Customer Care
QC Advertising
DLR Delivery report
2. Connection Information
2.1. API Information
2.1.1. Information of testing environment
Note that, the test environment only returns a successful or failed connection
response, not sending a message to the user subscriber. To test sending messages to user
subscribers, please switch to production environment
http://sandbox.sms.fpt.net/
2.1.2. Information of production environment
The system supports simultaneous connection via SSL or without SSL through 02
domains as below (these two domains are similar, supporting backup each other)
- http://api01.sms.fpt.net/
- https://api01.sms.fpt.net/
p. 4
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
▪ https://api01.sms.fpt.net/oauth2/token
▪ http://api01.sms.fpt.net/oauth2/token
o Sample data
{
"client_id": "30278d390f3d4e4542fc7A0200b87aA1A9EdF922",
"client_secret": "289bdc6d4cf9d466ab3b4ed8235a66F1cE1E9c78aef94076eB83439fcbf9a630c808a
908",
"scope": "send_brandname_otp send_brandname",
"session_id": "5c22be0c0396440829c98d7ba124092020145753419",
"grant_type": "client_credentials"
}
p. 5
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
3.1.2. Response API return client
2 possible cases might happen, ‘success’ (input valid data) or ‘failed’ (input invalid
data)
- ‘Sucess’ case (HTTP response status codes = 200)
Parameter Data type Description
access_token String Access token return
expires_in Int Expiration duration of token – in second
(s)
token_type String Access token type
scope String Access-allowed Scope
o Data Sample
{
"access_token": "dGk1dVF1ZUNPaW9Rak5aRkdqazF2MkxlaVdnejV0MWQ4WWREUVh4cEJO
U3dWUER3MmJQNmdTNkU4MG93MzY3NURmeGw1OHFQTUNibXpucnN4czNTdmt5Q3QzVH
BsR01HRWFoU3ljdnJPeWJMdHh0VG1VVTlUaDkwUWlWaDR0NUJzQjlqMmhHcEtSM2tvRCt0d
Gc1YTJjcFlOZm9IV2hISnR6QVBKT05IdVpjSnJzWFlJNnFZMmhHc3BLMURpcWVRR3Z2a1h2T2
FydGpJeGJBOWh1YWhtdlk0d0xIMTdHaVpKR2ZLYitHcGljOD0=",
"expires_in": 86400,
"token_type": "Bearer",
"scope": "send_brandname_otp send_brandname"
}
o Data Sample
{
"error": 1008,
"error_description": "Invalid Client Information."
}
3.1.3. Example
Example of using Postman to test and get access token
p. 6
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
3.2. Send domestic Customer Care messages
This Endpoint allows sending Customer Care messages (OTP messages, balance
notifications, bills, class schedules ...) to user subscribers through domestic
telecommunications carriers (Viettel, Vina, Mobi ...)
3.2.1. Request from client to API
- Url send Customer Care messages
o Test Environment(sandbox)
▪ http://sandbox.sms.fpt.net/api/push-brandname-otp
o Production Environment(live)
▪ https://api01.sms.fpt.net/api/push-brandname-otp
▪ http://api01.sms.fpt.net/api/push-brandname-otp
p. 7
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
session_id String Compulsor Session id Random string of characters
y of request (<= 32 characters)
BrandName String Compulsor Brandname Registered Brandname (Note:
y registered this is not the application name
with FPT in Step 2.2)
Phone String Compulsor The phone 84987654321 or 0987654321
y number to
receive the
message.
Format:
84xx or
0xxx
Message String Compulsor The content Example:
y of the ZGF5IGxhIG5vaSBkdW5nIHR
message to lc3Q=
be sent.
Note that
the message
content
must be
encrypted
Base64
RequestId String Option Value Message_sented_from_server_
Option A
(<=100). Message_sented_from_server_
Client can B
choose
definition
of Value
distinguish
the sending
source,
export the
report …
o Data Sample
{
"access_token": "RlNuOGVTSXBWR3czeitUOWw5dTJZa3lQcFJqZ0ZBdkpFdHlKN0lGQW1pV
XUvcTNFeHBPeENyM2JnTUNWbGRWK2Y0QXJQQUhSdDEwZ2pvVjRSS1JqbTdkd29vTm9SRk
FRbGJrcTNSRGtZTTlGZWVoVVpnUGp3dzhLQjN0SUVYc2FqVGdCWnUwa0dVRUExaEgrK0tG
ZDQ5bFRySXYvWXF0a1QvV2FWcGNDNHVx",
p. 8
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
"session_id": "5c22be0c0396440829c98d7ba124092020145753419",
"BrandName": "FTI",
"Phone": "84848486687",
"Message": "ZGF5IGxhIG5vaSBkdW5nIHRlc3Q=",
"RequestId":"tranID-Core01-987654321"
}
o Data Sample
{
"MessageId": "491785",
"Phone": "84848486687",
"BrandName": "FTI",
"Message": "this is the test content",
"PartnerId": "2215",
"Telco": "vina"
}
o Data Sample
{
"error": 1011,
"error_description": "Access token is incorrect."
p. 9
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
}
3.2.3. Example
Example of using Postman to test sending message
p. 10
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
- Data input (Note that the parameter distinguishes between UPPERCASE and
lowercase characters)
Parameter Data Option Description Value
type
access_token String Compulso Access Access token obtained at Step
ry token 3.1
session_id String Compulso Session id Random string of characters(<=
ry of request 32 characters)
BrandName String Compulso Brandname Registered Brandname (Note:
ry registered this is not the application name
with FPT in Step 2.2)
Phone String Compulso The phone 84987654321 or 0987654321
ry number to
receive the
message.
Format:
84xx or
0xxx
Message String Compulso The content Example:
ry of the ZGF5IGxhIG5vaSBkdW5nIHR
message to lc3Q=
be sent.
Note that
the message
content
must be
encrypted
Base64
RequestId String Option Value Message_sented_from_server_
Option A
(<=100). Message_sented_from_server_
Client can B
choose
definition
of Value
distinguish
the sending
source,
export the
report …
p. 11
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
o Data Sample
{
"access_token": "RlNuOGVTSXBWR3czeitUOWw5dTJZa3lQcFJqZ0ZBdkpFdHlKN0lGQW1pV
XUvcTNFeHBPeENyM2JnTUNWbGRWK2Y0QXJQQUhSdDEwZ2pvVjRSS1JqbTdkd29vTm9SRk
FRbGJrcTNSRGtZTTlGZWVoVVpnUGp3dzhLQjN0SUVYc2FqVGdCWnUwa0dVRUExaEgrK0tG
ZDQ5bFRySXYvWXF0a1QvV2FWcGNDNHVx",
"session_id": "5c22be0c0396440829c98d7ba124092020145753419",
"BrandName": "FTI",
"Phone": "1749123456",
"Message": "ZGF5IGxhIG5vaSBkdW5nIHRlc3Q=",
"RequestId":"tranID-Core01-987654321"
}
o Data Sample
{
"MessageId": "491785",
"Phone": "1749123456",
"BrandName": "FTI",
"Message": "This is testing content",
"PartnerId": "2215",
"Telco": "US"
}
p. 12
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
o Data Sample
{
"error": 1011,
"error_description": "Access token is invalid."
}
p. 13
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
3.4.3. Create a campaign
3.4.3.1. Request from client on API
- Url create campaign
o Test Environment(Sandbox)
▪ http://sandbox.sms.fpt.net/api/create-campaign
o Production Environment(Live)
▪ https://api01.sms.fpt.net/api/create-campaign
▪ http://api01.sms.fpt.net/api/create-campaign
- Scope requirement: send_brandname
- Data type: JSON
- Method: POST
- Data input (Note that: the parameter distinguishes between UPPERCASE and
lowercase characters)
Parameter Data type Option Description Value
access_token String Compulsory Access token Access token
obtained from
Step 3.1
session_id String Compulsory Session id of Random string
request of
characters(<=
32 characters)
p. 14
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
CampaignName String Compulsory The name of Random string
the campaign of
you want, note characters(<=
that the 32 characters)
campaign
name cannot
be the same
and each
campaign can
only be used
once
BrandName String Compulsory Brandname Registered
registered with Brandname
FPT (Note: this is
not the
application
name in Step
2.2)
Message String Compulsory The content of Happy
the message to birthday to
be sent. shopee,
discount
coupons for
70% of the
purchase order
ScheduleTime String Compulsory Expected time Example:
to send 2021-06-18
messages to 09:00
user
subscribers.
Format:
yyyy-mm-dd
HH:ii
Quota Int Compulsory Maximum Message has a
number of length of 200
message characters
allowes to send (equivalent to
in a Campaign 2 messages), if
you want to
send a message
to List 1000
p. 15
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
phone
numbers, then
the minimum
Quota needs to
be: 1000x2 =
2000
o Data Sample
{
"access_token": "TjFURGRPZDNqMDF3Sjc0ZkJKbjRhbG5OK2pOZUpnR0tmcVIwdHR6N1haQ
2ViV0Z2ZUNKNmxjRjZ1Rk5WMjRhUnMwWlVzdGNWQ2NRRjBGYmYvVWVLQVZ1NFB5ekc2
OEtpQVRiUVl0dE9CVEJXZXdRSmJpK3BaSGkzaDBsa213RDNTNmcxUlpubzY1Y3k5RXVmZ0V
yM0Q1YTZhZTl5eUtyTjZNWnRkdnlPMWhiaElRL1BNczN5T2FFY1VkaFJlSlNWc3hpR2U0aEsrU
09pMFBhUHMyNzdxdzRaL1JJTzlxQlFCeHZTcEo1VTNyUT0",
"session_id": "5c22be0c0396440829c98d7ba124092020145753419",
"CampaignName": " Promotion program 06/2021",
"BrandName": "FTI",
"Message": " Discount 50% for all purchase order under 100 million dong ",
"ScheduleTime":"2021-06-18 09:00",
"Quota":1000
}
o Data Sample
{
"CampaignCode": "MjIxNQ==60cb06fa1d9bb"
}
o Data Sample
p. 16
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
{
"error": 1014,
"error_description": "Campaign name already exists."
}
3.4.3.3. Example
Example of using Postman to create campaign
p. 17
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
session_id String Compulsory Session id Random string of
của request characters(<= 32
characters)
CampaignCo String Compulsory The Example:
de campaign MjIxNQ==60cb098a0
code has 9ee6
been
successfully
created at
Step 3.4.3
PhoneList String Compulsory List of phone Example:
numbers to 0987654321,0123456
send 789
messages.
Phone
numbers are
separated by
commas (,).
Phone
format: 84xx
or 0xxx
o Data Sample
{
"access_token": "TjFURGRPZDNqMDF3Sjc0ZkJKbjRhbG5OK2pOZUpnR0tmcVIwdHR6N1haQ
2ViV0Z2ZUNKNmxjRjZ1Rk5WMjRhUnMwWlVzdGNWQ2NRRjBGYmYvVWVLQVZ1NFB5ekc2
OEtpQVRiUVl0dE9CVEJXZXdRSmJpK3BaSGkzaDBsa213RDNTNmcxUlpubzY1Y3k5RXVmZ0V
yM0Q1YTZhZTl5eUtyTjZNWnRkdnlPMWhiaElRL1BNczN5T2FFY1VkaFJlSlNWc3hpR2U0aEsrU
09pMFBhUHMyNzdxdzRaL1JJTzlxQlFCeHZTcEo1VTNyUT0",
"session_id": "5c22be0c0396440829c98d7ba124092020145753419",
"CampaignCode": "MjIxNQ==60caff8b6f5a6",
"PhoneList":"0987654321,0987654123"
}
p. 18
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
Parameter Data type Description
NumMessageSent Int Number of messages sent
NumRemainQuota Int Number of messages
(Quota) is left
BatchId String BatchId of QC Message.
BatchId + phone number
(format 84xx) = ID of QC
Message
o Data Sample
{
"NumMessageSent": 2,
"NumRemainQuota": 8,
"BatchId": "qc.2215.1623984019.82989"
}
o Data Sample
{
"error": 1014,
"error_description": "Campaign is already sent."
}
p. 19
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
To the 2nd way, please build in Webhook according to the following format, then provide
the URL and the Authorization Key string to FPT, so that FPT can configure the
callback.
- Url: [http/https]://your-domain-name/your-path
- Method: POST
- Request header:
o Content-Type: application/json
o Accept: application/json
o Authorization: Basic AUTHORIZATION_KEY (Is a random string to
authenticate)
- Request body
o Data input (Note that the parameter distinguishes between UPPERCASE and
lowercase characters)
Parameter Data type Option Description Value
smsid Int Compulsory It will be the 451838640
MessageID of
the
successfully
sent message
API returned
from Step 3.
Status TinyInt Compulsory The last 1: Success
message 2 or -11:
processing Waiting, no
status returned result yet
from Telco 0: Failure
Telco String Option The current Viettel: viettel
Telco company Vinaphone:
of this vina
subscriber Mobifone:
number mobi
VNM: htc
Gtel: beeline
Itelecom: itel
Error String Option Error code or
kèm Detail
error
description
mt_count TinyInt Option Length of
message
p. 20
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
o Data output thành công (HTTP response status codes = 200)
Parameter Data type Option Description Value
status TinyInt Compulsory Request 1: Success
processing
status when
FPT callback
o Data output thất bại (HTTP response status codes <> 200)
o Request body
p. 21
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
4.2. Get delivery report of QC Messages
4.2.1. Get the status of Campaign
API will return campaign details such as: number of sent messages, approved
messages or not approved messages, reasons for not being approved if any
- Url: https://api01.sms.fpt.net/api/detail-ads or
http://api01.sms.fpt.net/api/detail-ads
- Scope requirement: send_brandname
- Data type: JSON
- Method: POST
- Data input (Note that the parameter distinguishes between UPPERCASE and
lowercase characters)
p. 22
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
Parameter Data type Description
CampaignCode String Code of created Campaign
Total String Number of sent QC
messages
Quota String Quota mà Campaign đã tạo
IsSent String 0: Failed to be sent
1: Sent
SendingTime String Sending time of Campaign
StatusDetail[Reason] String Reasons for not being
approved
StatusDetail[Status] String 0: Not approved
1: Approved
p. 23
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
Detail-each-row .csv file is returned
o Data output “failure” (HTTP response status codes <> 200)
Parameter Data type Description
Error Int Error code
Error_description String Detail error description
p. 24
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited
5 or -20 or 55 The message content (template) is not registered or
wrong content sent compared to the registered
template
6 or -18 Content sent exists blocked keywords
7 Content contains Vietnamese characters (Unicode)
when encoding (Direction Viettel Bank)
8 Cannot decrypt, message sent is not encrypted..
(Direction Viettel Bank)
53 or -10 or 902 Wrong phone number
p. 25
This document contains confidential information that is the property of FPT.
Any copy, print, reproduction without FPT's permission is strictly prohibited