0% found this document useful (0 votes)
51 views26 pages

Cloud - API Connection Manual SMS Brandname v1.2 Eng

Uploaded by

nguyenson131380
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
0% found this document useful (0 votes)
51 views26 pages

Cloud - API Connection Manual SMS Brandname v1.2 Eng

Uploaded by

nguyenson131380
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 26

FPT TELECOM INTERNATIONAL CO.

LTD

API CONNECTION MANUAL


OF SMS BRANDNAME SERVICE

Hanoi, June 2021


Table of Content
1. Overview..............................................................................................................................................3
1.1. Introduction.................................................................................................................................... 4
1.2. Abbreviation list – terms............................................................................................................4
2. Connection Information..................................................................................................................... 4
2.1. API Information......................................................................................................................... 4
2.1.1. Information of testing environment.................................................................................. 4
2.1.2. Information of production envinroment........................................................................... 4
2.2. Instructions for getting authentication information............................................................ 4
3. Instructions for API Connection....................................................................................................... 6
3.1. Get access token.......................................................................................................................... 6
3.1.1. Request from client to API.................................................................................................6
3.1.2. Response API return client................................................................................................ 7
3.1.3. Example............................................................................................................................... 8
3.2. Send domestic Customer Care messages.................................................................................. 9
3.2.1. Request from client to API.................................................................................................9
3.2.2. Response API return for Client....................................................................................... 10
3.2.3. Example............................................................................................................................. 11
3.3. Send International Customer Care Messages........................................................................ 12
3.3.1. Request from client to API...............................................................................................12
3.3.2. Response API return Client............................................................................................. 13
3.4. To send messages QC................................................................................................................14
3.4.1. Some rules of sending messages QC................................................................................14
3.4.2. Process of sending QC messages via API........................................................................ 15
3.4.3. Create a campaign............................................................................................................ 15
3.4.3.1. Request from client on API..........................................................................................15
3.4.3.2. Response API return to Client.....................................................................................17
3.4.3.3. Example......................................................................................................................... 17
3.4.4. Send messages................................................................................................................... 18
3.4.4.1. Request from client to API...........................................................................................18

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

Service Name: SMS Brandname Service


Representative:
Receiving Date:
Manual Information

Manual Name: API Connection Manual of SMS Brandname Service


Author: TamTM11, KhiemDD
Created Date: June 2nd, 2021
Change Log

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/

3. Instructions for API Connection


API use token for Authorization, 2 Steps are needed in order to connect to send
messages:
- Get token
- Use the obtained token to send messages.
3.1. Get access token
3.1.1. Request from client to API
- Url get access token
o Test environment (sandbox):
▪ http://sandbox.sms.fpt.net/oauth2/token
o Production environment (live):

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

- Data type: JSON


- Method: POST
- Data input (Note that the parameter distinguishes between UPPERCASE and
lowercase characters)
Parameter Date Type Option Description Value
grant_type String Compulsor Type authorizations, client_credentials
y currently only
client_credentials is
allowed
client_id String Compulsor Application identifier client_id in your
y string. How to get: see application
section 2.2. Instructions
for getting authentication
information
client_secret String Compulsor Application identifier client_secret in your
y string. How to get: see application
section 2.2. Instructions
for getting authentication
information
scope String Compulsor Licenced Scope. System send_brandname_ot
y allows 2 scopes - the p send_brandname
scope when creating an (each scope
application. See section separated by a
2.2. Instructions for space)
getting authentication
information
session_id String Compulsor Session id of request Random string of
y characters (<= 32
characters)

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"
}

- ‘Failure’ cases (HTTP response status codes <> 200)


Parameter Data type Description
error Int Error code
error_description String Detail error description

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

- Scope requirement: send_brandname_otp


- Data type: JSON
- Method: POST
- Data input
Parameter Data Option Descriptio Value
type n
access_token String Compulsor Access Access token đã lấy ở Step 3.1
y token

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"
}

3.2.2. Response API return for Client


2 possible cases might happen, “success” (input valid data) or ‘failure’ (input invalid
data)
‘Success’ cases (HTTP response status codes = 200)

Parameter Data type Description


MessageId Int ID of sent message
Phone String Phone number of sent message
BrandName String The brandname is used to send
message
Message String Sent message content
PartnerId String ID of parter sent message
Telco String Telco supplier of the phone
number

o Data Sample
{
"MessageId": "491785",
"Phone": "84848486687",
"BrandName": "FTI",
"Message": "this is the test content",
"PartnerId": "2215",
"Telco": "vina"
}

- ‘Failure’ cases (HTTP response status codes <> 200)

Parameter Data type Description


Error Int Error code
Error_description String Detail error description

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

3.3. Send International Customer Care Messages


This endpoint will allow sending customer service messages (OTP messages, balance
notifications, invoices, class schedules ...) to overseas subscribers through
telecommunications networks of countries around the world (these carriers of USA,
Singapore, China ...)
3.3.1. Request from client to API
- Url to send messages
o Test Environment(Sandbox)
▪ http://sandbox.sms.fpt.net/api/push-brandname-international
o Production Environment(Live)
▪ https://api01.sms.fpt.net/api/push-brandname-international
▪ http://api01.sms.fpt.net/api/push-brandname-international
- Scope requirement: send_brandname_otp
- Data type: JSON
- Method: POST

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"
}

3.3.2. Response API return Client


2 possible cases might happen, ‘success’ (input valid data) or ‘failure’ (input invalid
data)
- “Success” case(HTTP response status codes = 200)
Parameter Data type Description
MessageId Int ID of sent message
Phone String Phone number of sent message
BrandName String The brandname is used to send
message
Message String Sent message content
PartnerId String ID of partner sent message
Telco String Telco supplier of the phone
number

o Data Sample
{
"MessageId": "491785",
"Phone": "1749123456",
"BrandName": "FTI",
"Message": "This is testing content",
"PartnerId": "2215",
"Telco": "US"
}

- “Failure” case (HTTP response status codes <> 200)


Parameter Data type Description
Error Int Error code
Error_description String Detail error description

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."
}

3.4. To send messages QC


3.4.1. Some rules of sending messages QC
- Time to receive orders of the Telco: from 8:30 a.m. to 4:30 p.m. on Weekdays
(from Monday to Friday)
- Durantion of QC message approval: 2-3h
- Partner can schedule messages to be sent to user subscribers all days of the week
(from Monday to Sunday) but note that the time frame is allowed to send as below,
beyond this time frame - QC messages will blocked
Time frame Status
Allowed to send QC
Morning 08:00 - 11:30
message
Afternoon Allowed to send QC
13:30 - 20:00
Evening message

3.4.2. Process of sending QC messages via API

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
}

3.4.3.2. Response API return to Client


2 possible cases might happen, “success” (input valid data) or ‘failure’ (input invalid
data)
- “Success” case (HTTP response status codes = 200)

Parameter Data type Description


CampaignCode String Campaign code when
successfully created

o Data Sample
{
"CampaignCode": "MjIxNQ==60cb06fa1d9bb"
}

- “Failure” case (HTTP response status codes <> 200)


Parameter Data type Description
Error Int Error code
Error_description String Detail error description

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

3.4.4. Send messages


3.4.4.1. Request from client to API
- Url sending QC message
o Test Environment(Sandbox)
▪ http://sandbox.sms.fpt.net/api/push-brandname-ads
o Production Environment(Live)
▪ https://api01.sms.fpt.net/api/push-brandname-ads
▪ http://api01.sms.fpt.net/api/push-brandname-ads

-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
at Step 3.1

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"
}

3.4.4.2. Response API return Client


2 possible cases might happen, “success” (input valid data) or ‘failure’ (input invalid
data)
- “Success” case (HTTP response status codes = 200)

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"
}

- “Failure” case (HTTP response status codes <> 200)


Parameter Data type Description
Error Int Error code
Error_description String Detail error description

o Data Sample
{
"error": 1014,
"error_description": "Campaign is already sent."
}

4. Get delivery report of sent messages


4.1. Get delivery report of Customer Care messages
The response response from the API when sending the message in Step 3 above is not
the final state of the message sent to the user subscriber, it is just a response to the
interaction between the client and the API.
There are two ways to check the last sending status, which Telco sends down to the
user subscription:
- 1st way: Log-in to https://portal.sms.fpt.net/ with the account that has been granted
to look up and send messages (Portal provided by FPT to send messages, look up
...)
- 2nd way: Build a webhook (Reverse APIs) for FPT to callback the results of
messages sent from Telco

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)

Parameter Data type Option Description Value


status TinyInt Compulsory Request 0: Failure
processing
status when
FPT callback
desc String Option Detail Example:
Description “Invalid data”

- Example request FPT will callback with Postman


o Request header

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)

Parameter Data type Option Description Value


access_token String Compulsory Access token Access token
obtained at
Step 3.1
CampaignCode String Compulsory Campaign code
of sent QC
messages

o Data output “success” (HTTP response status codes = 200)

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

o Data output “failure” (HTTP response status codes <> 200)

Parameter Data type Description


Error Int Error code
Error_description String Detail error description

4.2.2. Get status of every single QC message


The API will return log details for each subscriber number according to the csv file
list. Note that: QC message results will be unreal-time as that of Customer Care
meassage, usually the results will be returned after sending time 3-5 working days.
- Url: https://api01.sms.fpt.net/api/dlr-ads or http://api01.sms.fpt.net/api/dlr-ads
- 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 at
Step 3.1
campaign_code String Compulsory Campaign code
of sent QC
messages

o Data output “success” (HTTP response status codes = 200)

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

5. Error code table


Error code Description
1001 Invalid Request
1002 Client is not allowed to access
1003 Access is denied
1004 Response requirement type is not supported
1005 Invalid scopes
1006 Server error
1007 Server temporarily unable to process requests from
client
1008 Client information is invalid (wrong client_id or
client_secret)
1009 Invalid permission type
1010 Scope is insufficient permission to access
1011 Invalid Access token
1012 Access token has been changed
1013 Access token is expired
1014 Input parameter error
1015 This permission type is not supported
1016 The number of messages sent has exceeded the
quota
2501 or 1 Duplicate message in 5 minutes
2502 Sending quota has expired
2503 The sending quota has not been configured yet
2504 or 54 Brandname is not activated or locked
2505 or -11 Phone number is blocked
2506 Service error
2507 Undefined error
2 or -8 Brandname has not been registered with Telco yet
3 Service error from Telco
4 or -14 or 901 Message length exceeds rules of Telco

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

You might also like