SMS Character Encoding and Charging

1. SMS Content with GSM-7 Characters

If your SMS content contains only GSM-7 characters:

• Standard SMS: 160 characters per charging unit.
• After adding a signature, if the total exceeds 160 characters, the message is charged per 154 characters (concatenated SMS).
• Character counting rules:
  • GSM-7 basic characters: 1 character each
  • GSM-7 extension characters: 2 characters each

2. SMS Content with Non-GSM-7 Characters

If your SMS content contains non-GSM-7 characters (e.g., Chinese, Japanese):

• Standard SMS: 70 characters per charging unit.

3. GSM-7 Encoding Standard

GSM-7 is a character encoding standard that packs the most commonly used letters and symbols in many languages into 7 bits each for usage on GSM networks. Since SMS messages are transmitted in 140 8-bit octets, GSM-7 encoded SMS messages can carry up to 160 characters.

Reference: GSM 03.38 Standard

4. Special Considerations for Malaysia (Country Code: +60)

• Mobile operators require the content header RM 0.00 to be added to every message sent to Malaysia.
• This header informs the recipient that they were not charged for receiving the SMS.
• Sending messages without this header may result in:
  • Content truncation
  • Message delivery failure
• Concatenated messages are supported by all mobile operators except Digi Malaysia, which delivers them as multiple separate messages.

SMS Outbound Sending

Brief

Sending SMS

URL

http://api2.vitelcomm.com/api/sms/mtsend

HTTP Request

POST, using HTTP forms

Content-Type: application/x-www-form-urlencoded (Do not use JSON header)

cURL Example

curl -d "appkey=1&secretkey=2&phone=123&content=abc" http://api2.vitelcomm.com/api/sms/mtsend

Request Example

HTTP form commit, C# code example, Postman example

Parameters

Name	Optional?	Type	Memo
appkey	no	string	SMS app: appkey
secretkey	no	string	SMS app: secretkey
phone	no	string	To phone number (country code + number, e.g., 8615088888888)
content	no	string	Content, must be URL-encoded (UTF-8), max length 1000
source_address	yes	string	From, source address / sender
sys_messageid	yes	string	Message ID in your system. Auto-generated if not provided. Length 10–50, contains only [0-9a-zA-Z-]
short_link	yes	string	Short link; must exist in vitelcomm. Works only when content contains #1#
linkVerbose	yes	string	Whether to gather which number clicks the short link. 1 = yes, 0 = no. Default = no
dr_url	yes	string	DR webhook. Overrides vitelcomm console config. Only for sending to single number.
ext	yes	string	Only supported via HTTP API; returned in DR callback

HTTP Response Example

{"result":"Request successful","messageid":"20d6c660bd664c65bef20026564b0b79","code":"0"}
    

Response Fields

Name	Type	Memo
result	string	Detail message
messageid	string	SMS message ID
code	string	Result code

Memo

HTTP Response Codes

Code	Memo
0	Success
1	App is not available, or wrong appkey / secret
2	Parameters wrong or empty
3	No credit
4	Empty content or contains black list words
5	Content > 1000
6	Phone number invalid
7	Number size more than 50000
8	sourceaddress must be 1-20, numeric or alphabet
9	IP invalid
88	Submit failed
99	System error

SMPP Wrong Codes

Code	Memo
10 [0x0000000A]	sourceaddress (sender) error
81 [0x00000051]	Phone number error
103 [0x00000067]	No credit
260 [0x00000104]	Empty content or contains black list words
69	Unknown error, please contact NOC

SMS Delivery Rate

Share your customer conversion with us, with better service quality.

URL

http://api2.vitelcomm.com/api/smsdr/conversion

HTTP Method

GET

Example

Parameters

Name	Required	Type	Memo
messageid	Y	string	Message ID returned when committing your send SMS request
phone	N	string	The destination phone number
status	N	string	10 = success converted. All other values are treated as non-converted

Response

When successful, you will get a string: success.

If not successful, you will get a string: fail. Example: wrong message ID.

Note

If you call this API without the status parameter, it will be treated as converted.

SMS Delivery Receipt

We provide webhook callbacks to update the sending SMS status.

URL

The webhook URL should be developed and provided by your side, and should use some MQ system to avoid time-consuming operations.

Example: http://106.15.34.94:8989/sms/testDr

HTTP Method

POST x-www-form-urlencoded

For customers registered before May 24, 2023, parameters are in the URL. For customers registered after that, parameters are in the POST body.

Parameters

Name	Required	Type	Memo
phone	Y	string
status	Y	string	2 = success, all other = fail
result	Y	string	DELIVRD / UNDELIV
drtime	Y	string	DR time in format yyyy-MM-dd HH:mm:ss
messageid	Y	string	Message ID returned when committing the request
currency	Y	string	Currency: CNY / USD
price	Y	string	SMS price
rate	Y	string	Currency rate to CNY, e.g., USD 7.05
sendtime	Y	string	SMS send time, format yyyy-MM-dd HH:mm:ss
size	Y	string	Charging SMS size
ext	N	string	Only for HTTP API SMS; returned in callback

Example

Before May 24, 2023 (parameters in URL):

http://106.15.34.94:8080/sms/testDr?result=DELIVRD&size=1&phone=6282167624806&rate=6.4845&price=0.045&messageid=b308d94a73f94e6d84ae975c41f4b2a6&drtime=2021-02-26 10:01:15&currency=USD&sendtime=2021-02-26 10:01:15&status=2
    

After May 24, 2023 (parameters in POST body):

POST http://106.15.34.94:8080/sms/testDr
Content-Type: x-www-form-urlencoded

result=DELIVRD&size=1&phone=6282167624806&rate=6.4845&price=0.045&messageid=b308d94a73f94e6d84ae975c41f4b2a6&drtime=2021-02-26 10:01:15&currency=USD&sendtime=2021-02-26 10:01:15&status=2
    

DR Status Codes

Code	Meaning
DELIVRD = 2	Success
UNDELIV = 5	Fail
REJECTD = 6	Rejected
EXPIRED = 7	Expired
DELETED = 8	Deleted
DND = 9	Do Not Disturb
ESME_RINVSRCADR = 11	Invalid sender
UNKNOWN = 12	Unknown

Status Text

success = success

fail = error

Memo

All DRs will be tried only once. No guarantee of 100% delivery. For re-callbacks, you can manually pull the DR for processing.

Sending Email Verification Code

Brief Description: Sending email verification code.

Request Method

URL: http://api2.vitelcomm.com/api/email/otp

Method: POST

Content-Type: application/json

Parameters

Headers

Parameter	Parameter Value	Required	Type	Description
Content-Type	application/json	Yes	string

Body

Parameter	Type	Required	Description
appKey	string	Yes	Email application appKey
secretKey	string	Yes	Email application secretKey
from	string	Yes	Sender’s email, must be valid email address
to	string	Yes	Recipient’s email, must be valid email address
templateName	string	Yes	Template name
templateData	object	No	Custom replacement data in template
– eAddr	string	No	Address
– userName	string	No	Customer’s name
– nickName	string	No	Customer’s nickname
– gender	string	No	Honorific, e.g., Mr., Ms.
– date	string	No	Date, time
– mobile	string	No	Mobile number
– vCode	string	No	Verification code

Request Example

curl --location --request POST 'http://api2.vitelcomm.com/api/email/otp' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appKey": "asdf",
    "secretKey": "qwer",
    "from": "asdf@qwer.com",
    "to": "qwer@asdf.com",
    "templateName": "temp1",
    "templateData": {
        "eAddr": "",
        "userName": "",
        "nickName": "",
        "gender": "",
        "date": "",
        "mobile": "",
        "vCode": "123456"
    }
}'
    

Response Example

{
    "msg": "Request succeeded",
    "result": "e7b3082a46cf4959a3bc10f5d101d1cc",
    "code": 0
}
    

Response Parameter Description

Parameter	Type	Description
msg	string	Response message
result	string	Email ID
code	string	Response code

Error Codes

Code	Description
0	Request succeeded
601001	Account status exception
601002	Insufficient account balance
601101	Application status exception, appKey/SecretKey mismatch
601102	No quotation for the application
601103	No domain configuration under the application
601104	Domain not verified
601105	Sender’s email address does not exist
601106	Email template does not exist
601107	Email template not approved
601201	Submission failed

Email Verification Code DR Callback

Brief Description: Email verification code delivery receipt (DR) callback.

Request URL

HTTP interface address for DR callback (provided by the user).
Example: http://106.15.34.94:8989/email/callback

Request Method

POST

Parameters

Headers

Parameter	Value	Required	Type	Description
Content-Type	application/json	Yes	string

Body

Parameter	Type	Required	Description
messageId	string	Yes	Email ID
sender	string	Yes	Sender’s email
receiver	array	Yes	Receiver’s email(s)
price	string	Yes	Unit price
result	string	Yes	Status: DELIVRD / UNDELIV
sendTime	string	Yes	yyyy-MM-dd HH:mm:ss

Response Parameter Description

Parameter	Type	Required	Description
string	string	No	success / failure

Email Verification Code Record Query

Brief Description: Email verification code record query.

Request URL

URL: http://api2.vitelcomm.com/api/email/dr

Request Method

POST

Parameters

Headers

Parameter	Value	Required	Type	Description
Content-Type	application/json	Yes	string

Body

Parameter	Type	Required	Description
appKey	string	Yes	Email application appKey
secretKey	string	Yes	Email application secretKey
messageId	string	No	Email ID
startTime	string	No	Start time (yyyy-MM-dd HH:mm:ss)
endTime	string	No	End time (yyyy-MM-dd HH:mm:ss)
current	number	No	Page number, default 1
size	number	No	Number of items per page, default 10, max 100

Request Example

curl --location --request POST 'http://api2.vitelcomm.com/api/email/dr' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appKey": "asdf",
    "secretKey": "qwer"
}'
    

Response Example

{
    "msg": "success",
    "result": {
        "records": [
            {
                "messageId": "7128fd39195d4e2faf85de7f054514e6",
                "customerName": "NX00777-customer",
                "appName": "name2",
                "tplSubject": "123222",
                "sender": "1990336062@qq.com",
                "receiver": "ye.aoxiang@nxtele.com",
                "sellPrice": 0.26500000,
                "sendTime": "2021-02-23T15:39:51",
                "msgResult": "DELIVRD"
            }
        ],
        "total": 1,
        "size": 10,
        "current": 1,
        "orders": [],
        "appKey": "appKey",
        "secretKey": "secretKey",
        "messageId": "7128fd39195d4e2faf85de7f054514e6",
        "startTime": null,
        "endTime": null,
        "sortType": 0,
        "searchCount": true,
        "pages": 1
    },
    "code": 200
}
    

Response Parameter Description

Parameter	Type	Description
msg	string	Response message
result	object	Request result object
records	object	Email record list
messageId	string	Email ID
customerName	string	Customer name
appName	string	Application name
tplSubject	string	Template name
sender	string	Sender email
receiver	string	Receiver email
sellPrice	string	Unit price
sendTime	string	Sending time
msgResult	string	Message result
total	string	Total records
size	string	Items per page
current	string	Current page
appKey	string	Email appKey
secretKey	string	Email secretKey
startTime	string	Start time
endTime	string	End time
sortType	string	Sorting type, default descending
code	string	Response code

Error Codes

Code	Description
0	Request successful
601001	Account status exception
601002	Insufficient account balance
601101	Application status exception, appKey/SecretKey mismatch
601102	No pricing available for the application
601103	No domain configuration under the application
601104	Domain not verified
601105	Sender’s email address does not exist
601106	Email template does not exist
601107	Email template not approved
601201	Submission failed

Voice Verification Code Interface

Brief Description: Interface for sending voice verification codes.

Request URL

URL: http://api2.vitelcomm.com/api/voiceSms/versend

Request Method

POST (Content-Type: application/x-www-form-urlencoded)

Parameters

Parameter	Required	Type	Description
appkey	Yes	string	Voice application appkey
secretkey	Yes	string	Voice application secretkey
phone	Yes	string	Phone number, single submission only
country_code	Yes	string	Country code (digits only, no + sign)
show_phone	Yes	string	Number to be displayed (may be modified)
content	Yes	string	Text content; for verification code, separate digits with ‘-’; must be URL-encoded UTF-8
lang	Yes	string	Language code (e.g., zh, en)
ext	No	string	Custom extension fields; returned on voice receipt

Request Example

curl --location --request POST 'http://api2.vitelcomm.com/api/voiceSms/versend' \
--data-urlencode 'appkey=asdf' \
--data-urlencode 'secretkey=qwer' \
--data-urlencode 'phone=6212345678' \
--data-urlencode 'country_code=62' \
--data-urlencode 'show_phone=123456' \
--data-urlencode 'content=asdfghjk' \
--data-urlencode 'lang=en' \
--data-urlencode 'ext=ext123'
    

Response Example

{
    "result":"Request succeeded",
    "messageid":"20d6c660bd664c65bef20026564b0b79",
    "code":"0"
}
    

Response Parameter Description

Parameter	Type	Description
result	string	Request result description
messageid	string	Voice ID returned by the system
code	string	Result code

Language Codes

Pass only the abbreviation (English) in lang parameter:

af: Afrikaans, ar: Arabic, bn: Bengali, bs: Bosnian, ca: Catalan, cs: Czech, cy: Welsh,
da: Danish, de: German, el: Greek, en: English, eo: Esperanto, es: Spanish, et: Estonian,
fi: Finnish, fr: French, gu: Gujarati, hi: Hindi, hr: Croatian, hu: Hungarian, hy: Armenian,
id: Indonesian, is: Icelandic, it: Italian, ja: Japanese, jw: Javanese, km: Khmer, kn: Kannada,
ko: Korean, la: Latin, lv: Latvian, mk: Macedonian, ml: Malayalam, mr: Marathi, my: Myanmar(Burmese),
ne: Nepali, nl: Dutch, no: Norwegian, pl: Polish, pt: Portuguese, ro: Romanian, ru: Russian,
si: Sinhala, sk: Slovak, sq: Albanian, sr: Serbian, su: Sundanese, sv: Swedish, sw: Swahili,
ta: Tamil, te: Telugu, th: Thai, tl: Filipino, tr: Turkish, uk: Ukrainian, ur: Urdu,
vi: Vietnamese, zh: Chinese, zh-yue: Chinese-Cantonese
    

Error Codes

Code	Description
0	Request succeeded
1	Application unavailable or key error
2	Parameter error or empty
3	Insufficient balance
4	Content empty or contains illegal keywords
5	Content too long
6	Invalid phone number
9	Illegal IP
20	URL does not exist
21	Invalid display number
22	Route not available
23	Invalid country code
27	Frequency limit reached (max sends per hour)
28	TPS rate limit reached
88	Request failed
99	System error

Voice Verification Code Reporting Interface

Brief Description: Interface for reporting the status of sent voice verification codes.

Request URL

http://api2.vitelcomm.com/api/voiceSms/conversion

Request Method

POST (Content-Type: application/json)

Request Example

POST http://api2.vitelcomm.com/api/voiceSms/conversion
Content-Type: application/json

{
    "messageid": "7c9f36842095480189603142a4df76ed",
    "status": 1
}
    

Request Parameters

Parameter	Required	Type	Description
messageid	Yes	String	Voice ID returned when submitting the voice verification code
status	Yes	Integer	1 for successful reporting, 0 for not reported

Response Example

Success:

{"code": "success","info": "success"}
    

Failure:

{"code": "failed","info": "messageid not exist"}
    

Response Parameter Description

Parameter	Type	Description
code	String	Result code: “success” for success, “failed” for failure
info	String	Request result prompt message

Voice Notification Interface

Brief Description: Interface for sending voice notifications.

Request URL

http://api.vitelcomm.com/api/voiceSms/notsend

Request Method

POST (Content-Type: application/x-www-form-urlencoded)

Request Parameters

Parameter	Required	Type	Description
appkey	Yes	string	Voice application appkey
secretkey	Yes	string	Voice application secretkey
phone	Yes	string	Phone number(s), can submit in batches separated by commas (,)
country_code	Yes	string	Country code (digits only, no + sign)
show_phone	Yes	string	Number to be displayed (actual display may vary)
content	Yes	string	Text content (verification codes separated by ‘-’, URL-encoded UTF-8)
lang	Yes	string	Language code (zh, en, etc.)

Request Example

curl --location --request POST 'http://api.vitelcomm.com/api/voiceSms/notsend' \
--data-urlencode 'appkey=asdf' \
--data-urlencode 'secretkey=qwer' \
--data-urlencode 'phone=6212345678' \
--data-urlencode 'country_code=62' \
--data-urlencode 'show_phone=123456' \
--data-urlencode 'content=asdfghjk'
    

Response Example

{"result":"Request succeeded","messageid":"20d6c660bd664c65bef20026564b0b79","code":"0"}
    

Response Parameter Description

Parameter	Type	Description
result	string	Description of the request result
messageid	string	Voice ID returned by the system
code	string	Result code

Language Codes

Examples: zh (Chinese), en (English), ja (Japanese), fr (French), es (Spanish), etc. Full list as required.

Error Codes

Code	Description
0	Request succeeded
1	Application unavailable or key error
2	Parameter error or empty
3	Insufficient balance
4	Content is empty or contains illegal keywords
5	Content is too long
6	Invalid phone number
9	Illegal IP
20	URL does not exist
21	Invalid display number
22	Route not available
23	Invalid country code
88	Request failed
99	System error

WhatsApp Messaging API

Brief Description: Interface for sending WhatsApp messages, receiving delivery receipts, and querying message records.

Send WhatsApp Message

Request URL: http://api2.vitelcomm.com/api/whatsapp/send

Request Method: POST

Content-Type: application/json

Request Body Parameters

Parameter	Type	Required	Description
appKey	string	Yes	Email application appKey
secretKey	string	Yes	Email application secretKey
from	string	Yes	Sender’s WhatsApp number
to	string	Yes	Recipient’s WhatsApp number
content	string	Yes	Message text or template ID
templateData	object	No	Template placeholders and custom variables

Request Example

curl --location --request POST 'http://api2.vitelcomm.com/api/whatsapp/send' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appKey": "asdf",
    "secretKey": "qwer",
    "from": "1234567890",
    "to": "0987654321",
    "content": "Hello, this is a test WhatsApp message",
    "templateData": {
        "name": "John",
        "code": "123456"
    }
}'
    

Response Example

{
    "msg": "Request succeeded",
    "result": "whatsapp-message-id-12345",
    "code": 0
}
    

Response Parameter Description

Parameter	Type	Description
msg	string	Response message
result	string	Message ID
code	integer	Result code (0 = success)

WhatsApp Delivery Receipt (DR) Callback

Request URL: Provided by the user. Example: http://106.15.34.94:8989/whatsapp/callback

Request Method: POST (Content-Type: application/json)

Request Body Parameters

Parameter	Type	Required	Description
messageId	string	Yes	Message ID returned when sending
status	string	Yes	Status: DELIVRD / UNDELIV
sendTime	string	Yes	Send time (yyyy-MM-dd HH:mm:ss)
receiver	array	Yes	Receiver’s WhatsApp number(s)

Response Parameter

success / failure

WhatsApp Message Record Query

Request URL: http://api2.vitelcomm.com/api/whatsapp/dr

Request Method: POST (Content-Type: application/json)

Request Body Parameters

Parameter	Type	Required	Description
appKey	string	Yes	App key
secretKey	string	Yes	Secret key
messageId	string	No	Message ID
startTime	string	No	Start time (yyyy-MM-dd HH:mm:ss)
endTime	string	No	End time (yyyy-MM-dd HH:mm:ss)

WhatsApp Management API

Brief Description: API for managing WhatsApp accounts, templates, and configuration settings.

Get WhatsApp Account Info

Request URL: http://api2.vitelcomm.com/api/whatsapp/account

Request Method: POST

Content-Type: application/json

Request Body Parameters

Parameter	Type	Required	Description
appKey	string	Yes	WhatsApp application key
secretKey	string	Yes	Secret key

Response Example

{
    "msg": "success",
    "result": {
        "accountName": "MyBusiness",
        "phoneNumber": "1234567890",
        "status": "active",
        "templatesCount": 12
    },
    "code": 0
}
    

Response Parameter Description

Parameter	Type	Description
accountName	string	Business account name
phoneNumber	string	Registered WhatsApp phone number
status	string	Account status (active/inactive)
templatesCount	integer	Number of approved templates

Manage WhatsApp Templates

Request URL: http://api2.vitelcomm.com/api/whatsapp/template

Request Method: POST

Content-Type: application/json

Request Body Parameters

Parameter	Type	Required	Description
appKey	string	Yes	WhatsApp application key
secretKey	string	Yes	Secret key
action	string	Yes	Action type: create / update / delete / query
templateName	string	Yes	Name of the template
templateContent	string	No	Content of the template (required for create/update)
placeholders	array	No	List of variables used in the template

Request Example (Create Template)

curl --location --request POST 'http://api2.vitelcomm.com/api/whatsapp/template' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appKey": "asdf",
    "secretKey": "qwer",
    "action": "create",
    "templateName": "verification_code",
    "templateContent": "Hello {{name}}, your code is {{code}}",
    "placeholders": ["name", "code"]
}'
    

Response Example

{
    "msg": "Template created successfully",
    "result": {
        "templateId": "whatsapp-template-12345",
        "status": "pending"
    },
    "code": 0
}
    

Response Parameter Description

Parameter	Type	Description
templateId	string	Unique template ID
status	string	Approval status: pending / approved / rejected

WhatsApp Account Settings

Request URL: http://api2.vitelcomm.com/api/whatsapp/settings

Request Method: POST

Content-Type: application/json

Request Body Parameters

Parameter	Type	Required	Description
appKey	string	Yes	WhatsApp application key
secretKey	string	Yes	Secret key
webhookUrl	string	No	Webhook URL for delivery receipts
callbackEnabled	boolean	No	Enable/disable DR callback

Response Example

{
    "msg": "Settings updated successfully",
    "code": 0
}
    

WhatsApp Integrator API

Brief Description: API for sending WhatsApp messages, receiving delivery receipts, querying message records, and managing WhatsApp templates and accounts.

Send WhatsApp Message

Request URL: http://api2.vitelcomm.com/api/whatsapp/send

Request Method: POST

Content-Type: application/json

Request Body Parameters

Parameter	Type	Required	Description
appKey	string	Yes	WhatsApp application key
secretKey	string	Yes	Secret key
to	string	Yes	Recipient phone number, including country code
templateName	string	Yes	Template name for the message
templateData	object	No	Data to replace placeholders in the template
text	string	No	Free text message if not using a template

Request Example

curl --location --request POST 'http://api2.vitelcomm.com/api/whatsapp/send' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appKey": "asdf",
    "secretKey": "qwer",
    "to": "628123456789",
    "templateName": "verification_code",
    "templateData": {
        "name": "John",
        "code": "123456"
    }
}'
    

Response Example

{
    "msg": "Request succeeded",
    "messageId": "whatsapp-msg-12345",
    "code": 0
}
    

WhatsApp Message Delivery Receipt (DR)

WhatsApp message delivery status callback (configured via webhook).

Callback Body Parameters

Parameter	Type	Required	Description
messageId	string	Yes	Message ID returned by send API
status	string	Yes	DELIVRD / UNDELIV / READ
to	string	Yes	Recipient phone number
sendTime	string	Yes	Message sent timestamp

Response Example

"success"
    

Query WhatsApp Message Records

Request URL: http://api2.vitelcomm.com/api/whatsapp/dr

Request Method: POST

Request Body Parameters

Parameter	Type	Required	Description
appKey	string	Yes	WhatsApp application key
secretKey	string	Yes	Secret key
messageId	string	No	Filter by specific message ID
startTime	string	No	Start time for query (yyyy-MM-dd HH:mm:ss)
endTime	string	No	End time for query (yyyy-MM-dd HH:mm:ss)
current	number	No	Page number, default 1
size	number	No	Records per page, default 10

Response Example

{
    "msg": "success",
    "result": {
        "records": [
            {
                "messageId": "whatsapp-msg-12345",
                "templateName": "verification_code",
                "to": "628123456789",
                "sendTime": "2025-11-28T12:34:56",
                "status": "DELIVRD"
            }
        ],
        "total": 1,
        "current": 1,
        "size": 10
    },
    "code": 0
}
    

Viber Business API

Brief Description: API for sending Viber business messages and receiving delivery receipts via webhooks.

Send Viber Message

Request URL: http://api2.vitelcomm.com/api/viber/send

Request Method: POST

Content-Type: application/json

Request Body Parameters

Parameter	Type	Required	Description
appKey	string	Yes	Viber business application key
secretKey	string	Yes	Secret key
to	string	Yes	Recipient phone number including country code
text	string	Yes	Message content
media	string	No	Optional media URL (image/video)
buttons	array	No	Optional interactive buttons

Request Example

curl --location --request POST 'http://api2.vitelcomm.com/api/viber/send' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appKey": "asdf",
    "secretKey": "qwer",
    "to": "628123456789",
    "text": "Hello, this is a test message from Viber business API!",
    "media": "http://example.com/image.jpg",
    "buttons": [
        {"type": "reply", "title": "Yes", "payload": "yes"},
        {"type": "reply", "title": "No", "payload": "no"}
    ]
}'
    

Response Example

{
    "msg": "Request succeeded",
    "messageId": "viber-msg-12345",
    "code": 0
}
    

Viber Message Delivery Receipt (DR)

Webhook callback to receive delivery and read status.

Callback URL Example

http://106.15.34.94:8989/viber/callback

Callback Body Parameters

Parameter	Type	Required	Description
messageId	string	Yes	Message ID returned by send API
status	string	Yes	DELIVRD / UNDELIV / READ
to	string	Yes	Recipient phone number
sendTime	string	Yes	Message sent timestamp

Response Example

"success"
    

Query Viber Message Records

Request URL: http://api2.vitelcomm.com/api/viber/dr

Request Method: POST

Request Body Parameters

Parameter	Type	Required	Description
appKey	string	Yes	Viber application key
secretKey	string	Yes	Secret key
messageId	string	No	Filter by specific message ID
startTime	string	No	Start time (yyyy-MM-dd HH:mm:ss)
endTime	string	No	End time (yyyy-MM-dd HH:mm:ss)
current	number	No	Page number, default 1
size	number	No	Records per page, default 10

Response Example

{
    "msg": "success",
    "result": {
        "records": [
            {
                "messageId": "viber-msg-12345",
                "to": "628123456789",
                "text": "Hello, this is a test message!",
                "sendTime": "2025-11-28T12:34:56",
                "status": "DELIVRD"
            }
        ],
        "total": 1,
        "current": 1,
        "size": 10
    },
    "code": 0
}
    

Messenger Business API

Brief Description: API for sending Facebook Messenger messages and receiving delivery/read status via webhooks.

Send Messenger Message

Request URL: http://api2.vitelcomm.com/api/messenger/send

Request Method: POST

Content-Type: application/json

Request Body Parameters

Parameter	Type	Required	Description
appKey	string	Yes	Messenger application key
secretKey	string	Yes	Secret key
recipientId	string	Yes	Facebook PSID of the recipient
messageType	string	Yes	Type of message: text, image, template
text	string	Required if messageType=text	Message text content
mediaUrl	string	No	Image/video URL if sending media
buttons	array	No	Optional buttons (template messages)

Request Example

curl --location --request POST 'http://api2.vitelcomm.com/api/messenger/send' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appKey": "asdf",
    "secretKey": "qwer",
    "recipientId": "1234567890",
    "messageType": "text",
    "text": "Hello! This is a test message from Messenger Business API."
}'
    

Response Example

{
    "msg": "Request succeeded",
    "messageId": "messenger-msg-12345",
    "code": 0
}
    

Messenger Delivery & Read Receipt (Webhook)

Webhook callback to receive delivery and read status for Messenger messages.

Callback URL Example

http://106.15.34.94:8989/messenger/callback

Callback Body Parameters

Parameter	Type	Required	Description
messageId	string	Yes	Message ID returned when sending
status	string	Yes	DELIVERED / READ / FAILED
recipientId	string	Yes	Recipient PSID
timestamp	string	Yes	Message event timestamp

Response Example

"success"
    

Query Messenger Message Records

Request URL: http://api2.vitelcomm.com/api/messenger/dr

Request Method: POST

Request Body Parameters

Parameter	Type	Required	Description
appKey	string	Yes	Messenger application key
secretKey	string	Yes	Secret key
messageId	string	No	Filter by message ID
startTime	string	No	Start time (yyyy-MM-dd HH:mm:ss)
endTime	string	No	End time (yyyy-MM-dd HH:mm:ss)
current	number	No	Page number, default 1
size	number	No	Records per page, default 10

Response Example

{
    "msg": "success",
    "result": {
        "records": [
            {
                "messageId": "messenger-msg-12345",
                "recipientId": "1234567890",
                "text": "Hello! This is a test message.",
                "sendTime": "2025-11-28T12:34:56",
                "status": "DELIVERED"
            }
        ],
        "total": 1,
        "current": 1,
        "size": 10
    },
    "code": 0
}
    

Zalo Business API

Brief Description: API for sending messages via Zalo Official Account and receiving delivery/read status via webhook.

Send Zalo Message

Request URL: http://api2.vitelcomm.com/api/zalo/send

Request Method: POST

Content-Type: application/json

Request Body Parameters

Parameter	Type	Required	Description
appKey	string	Yes	Zalo application key
secretKey	string	Yes	Secret key
recipientId	string	Yes	Zalo user ID (UID) of recipient
messageType	string	Yes	Type of message: text, image, template
text	string	Required if messageType=text	Text content of the message
mediaUrl	string	No	Image/video URL if sending media
templateData	object	No	Optional template parameters

Request Example

curl --location --request POST 'http://api2.vitelcomm.com/api/zalo/send' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appKey": "asdf",
    "secretKey": "qwer",
    "recipientId": "1234567890",
    "messageType": "text",
    "text": "Hello! This is a test message from Zalo Business API."
}'
    

Response Example

{
    "msg": "Request succeeded",
    "messageId": "zalo-msg-12345",
    "code": 0
}
    

Zalo Delivery & Read Receipt (Webhook)

Webhook callback to receive delivery and read status for Zalo messages.

Callback URL Example

http://106.15.34.94:8989/zalo/callback

Callback Body Parameters

Parameter	Type	Required	Description
messageId	string	Yes	Message ID returned when sending
status	string	Yes	DELIVERED / READ / FAILED
recipientId	string	Yes	Recipient UID
timestamp	string	Yes	Message event timestamp

Response Example

"success"
    

Query Zalo Message Records

Request URL: http://api2.vitelcomm.com/api/zalo/dr

Request Method: POST

Request Body Parameters

Parameter	Type	Required	Description
appKey	string	Yes	Zalo application key
secretKey	string	Yes	Secret key
messageId	string	No	Filter by message ID
startTime	string	No	Start time (yyyy-MM-dd HH:mm:ss)
endTime	string	No	End time (yyyy-MM-dd HH:mm:ss)
current	number	No	Page number, default 1
size	number	No	Records per page, default 10

Response Example

{
    "msg": "success",
    "result": {
        "records": [
            {
                "messageId": "zalo-msg-12345",
                "recipientId": "1234567890",
                "text": "Hello! This is a test message.",
                "sendTime": "2025-11-28T12:34:56",
                "status": "DELIVERED"
            }
        ],
        "total": 1,
        "current": 1,
        "size": 10
    },
    "code": 0
}
    

Fraud Prevention: Phone Number Check

Brief Description: Verify phone numbers in real-time to prevent fraud, validate format, detect disposable numbers, and check risk level.

Request URL

http://api2.vitelcomm.com/api/fraud/phoneCheck

Request Method

POST

Content-Type: application/json

Request Body Parameters

Parameter	Type	Required	Description
appKey	string	Yes	API application key
secretKey	string	Yes	API secret key
phone	string	Yes	Phone number to check (with country code)
countryCode	string	No	Optional country code if not included in phone number

Request Example

curl --location --request POST 'http://api2.vitelcomm.com/api/fraud/phoneCheck' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appKey": "asdf",
    "secretKey": "qwer",
    "phone": "628123456789",
    "countryCode": "62"
}'
    

Response Example

{
    "msg": "Request succeeded",
    "result": {
        "phone": "628123456789",
        "validFormat": true,
        "carrier": "Telkomsel",
        "lineType": "mobile",
        "riskLevel": "low",
        "isDisposable": false,
        "isFraudulent": false
    },
    "code": 0
}
    

Response Parameter Description

Parameter	Type	Description
phone	string	Phone number being checked
validFormat	boolean	True if the number has valid format
carrier	string	Mobile carrier/operator name
lineType	string	Type: mobile, landline, VOIP, etc.
riskLevel	string	Risk assessment: low, medium, high
isDisposable	boolean	True if number is temporary/disposable
isFraudulent	boolean	True if number is flagged as fraudulent

Error Codes

Code	Description
0	Request succeeded
601001	Account status exception
601002	Insufficient account balance
601101	AppKey/SecretKey mismatch
601201	Request failed

Global Number / Number Privacy

Brief Description: Use global number masking to protect users’ real phone numbers. Calls or messages go through a virtual/proxy number to preserve privacy.

Request URL

http://api2.vitelcomm.com/api/privacy/globalNumber

Request Method

POST

Content-Type: application/json

Request Body Parameters

Parameter	Type	Required	Description
appKey	string	Yes	API application key
secretKey	string	Yes	API secret key
realNumberA	string	Yes	User A’s real phone number
realNumberB	string	Yes	User B’s real phone number
region	string	No	Optional region/country code for proxy number allocation
expiry	string	No	Mask number expiry time (ISO 8601 format)

Request Example

curl --location --request POST 'http://api2.vitelcomm.com/api/privacy/globalNumber' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appKey": "asdf",
    "secretKey": "qwer",
    "realNumberA": "628123456789",
    "realNumberB": "628987654321",
    "region": "ID",
    "expiry": "2025-12-31T23:59:59Z"
}'
    

Response Example

{
    "msg": "Request succeeded",
    "result": {
        "proxyNumber": "+628111223344",
        "realNumberA": "628123456789",
        "realNumberB": "628987654321",
        "expiry": "2025-12-31T23:59:59Z"
    },
    "code": 0
}
    

Response Parameter Description

Parameter	Type	Description
proxyNumber	string	Masked / virtual number provided by the system
realNumberA	string	User A’s real number
realNumberB	string	User B’s real number
expiry	string	Expiry time of the masked number

Error Codes

Code	Description
0	Request succeeded
601001	Account status exception
601002	Insufficient balance
601101	AppKey/SecretKey mismatch
601201	Request failed

Global Number (DID Number)

Brief Description: Allocate a global or DID number for receiving calls and SMS messages. This allows businesses to provide a local presence while routing calls/messages to the backend system securely.

Request URL

http://api2.vitelcomm.com/api/did/allocate

Request Method

POST

Content-Type: application/json

Request Body Parameters

Parameter	Type	Required	Description
appKey	string	Yes	API application key
secretKey	string	Yes	API secret key
countryCode	string	Yes	Country code for the DID number (e.g., US = 1, ID = 62)
region	string	No	Optional region/city code for local number assignment
numberType	string	No	Type of DID number (local, toll-free, mobile)
expiry	string	No	Optional expiry for temporary DID number (ISO 8601 format)

Request Example

curl --location --request POST 'http://api2.vitelcomm.com/api/did/allocate' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appKey": "asdf",
    "secretKey": "qwer",
    "countryCode": "62",
    "region": "Jakarta",
    "numberType": "local",
    "expiry": "2025-12-31T23:59:59Z"
}'
    

Response Example

{
    "msg": "Request succeeded",
    "result": {
        "didNumber": "+628123456789",
        "countryCode": "62",
        "region": "Jakarta",
        "numberType": "local",
        "expiry": "2025-12-31T23:59:59Z"
    },
    "code": 0
}
    

Response Parameter Description

Parameter	Type	Description
didNumber	string	Allocated global/DID number
countryCode	string	Country code
region	string	Region or city for local number
numberType	string	Local / Toll-free / Mobile
expiry	string	Expiration time for temporary numbers

Error Codes

Code	Description
0	Request succeeded
601001	Account status exception
601002	Insufficient balance
601101	AppKey/SecretKey mismatch
601201	Request failed

AICC (Call Center) Integration

Brief Description: Integrate with the AI Call Center (AICC) to make outbound calls, receive call events, and monitor call status through webhooks.

Request URL (Outbound Call)

Send call request to initiate a call via AICC API.
Example: http://api2.vitelcomm.com/api/aicc/call

Request Method

POST

Content-Type: application/json

Request Body Parameters (Outbound Call)

Parameter	Type	Required	Description
appKey	string	Yes	API application key
secretKey	string	Yes	API secret key
phone	string	Yes	Destination phone number (with country code)
callerId	string	Yes	Number displayed as caller ID
templateId	string	No	Optional voice/template to be played during the call
priority	integer	No	Call priority, default is 1
ext	string	No	Optional extension, will return in webhook callback

Request Example

curl --location --request POST 'http://api2.vitelcomm.com/api/aicc/call' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appKey": "asdf",
    "secretKey": "qwer",
    "phone": "628123456789",
    "callerId": "02112345678",
    "templateId": "voiceTemplate1",
    "priority": 1,
    "ext": "custom123"
}'
    

Webhook Callback

All call events (initiated, answered, completed, failed) are sent to your webhook URL. You must provide a publicly accessible endpoint to receive callbacks.

Webhook Example URL

Example: http://yourdomain.com/api/aicc/webhook

Webhook Body Parameters

Parameter	Type	Description
callId	string	Unique ID of the call
phone	string	Destination phone number
status	string	Call status: INITIATED, RINGING, ANSWERED, COMPLETED, FAILED
startTime	string	Call start time (yyyy-MM-dd HH:mm:ss)
endTime	string	Call end time (yyyy-MM-dd HH:mm:ss)
duration	integer	Call duration in seconds
ext	string	Optional extension returned from call request
resultCode	string	Result code for success/failure

Webhook Example (JSON)

{
    "callId": "abc123",
    "phone": "628123456789",
    "status": "COMPLETED",
    "startTime": "2025-11-28 10:00:00",
    "endTime": "2025-11-28 10:02:30",
    "duration": 150,
    "ext": "custom123",
    "resultCode": "0"
}
    

Response to Webhook

Your server must respond with a HTTP 200 OK status and body success to acknowledge the event.

Error Codes

Code	Description
0	Call request succeeded
1	Invalid appKey or secretKey
2	Invalid phone number
3	Insufficient credit/balance
4	Call failed due to network or carrier issue
99	System error

AICC (Call Bot) Integration

Brief Description: Integrate with the AI Call Bot to make interactive outbound calls, collect user responses, and track call progress via webhooks.

Request URL (Start Call)

Send request to initiate a call bot session.
Example: http://api2.vitelcomm.com/api/aicc/callbot

Request Method

POST

Content-Type: application/json

Request Body Parameters

Parameter	Type	Required	Description
appKey	string	Yes	API application key
secretKey	string	Yes	API secret key
phone	string	Yes	Destination phone number
callerId	string	Yes	Caller ID displayed
botScriptId	string	Yes	ID of the voice bot script to use
priority	integer	No	Call priority, default is 1
ext	string	No	Optional extension returned in webhook

Request Example

curl --location --request POST 'http://api2.vitelcomm.com/api/aicc/callbot' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appKey": "asdf",
    "secretKey": "qwer",
    "phone": "628123456789",
    "callerId": "02112345678",
    "botScriptId": "script001",
    "priority": 1,
    "ext": "custom123"
}'
    

Webhook Callback

All call bot events (call started, answered, user input, completed, failed) are sent to your webhook URL.

Webhook URL Example

Example: http://yourdomain.com/api/aicc/callbot/webhook

Webhook Body Parameters

Parameter	Type	Description
callId	string	Unique ID of the call
phone	string	Destination phone number
status	string	Call status: INITIATED, RINGING, ANSWERED, COMPLETED, FAILED
userInput	string	User input collected during call (DTMF, speech-to-text)
startTime	string	Call start time (yyyy-MM-dd HH:mm:ss)
endTime	string	Call end time (yyyy-MM-dd HH:mm:ss)
duration	integer	Call duration in seconds
ext	string	Optional extension returned from call request
resultCode	string	Result code for success/failure

Webhook Example (JSON)

{
    "callId": "abc123",
    "phone": "628123456789",
    "status": "COMPLETED",
    "userInput": "1-2-3",
    "startTime": "2025-11-28 10:00:00",
    "endTime": "2025-11-28 10:02:30",
    "duration": 150,
    "ext": "custom123",
    "resultCode": "0"
}
    

Webhook Response

Respond with HTTP 200 OK and body success to acknowledge the event.

Error Codes

Code	Description
0	Call request succeeded
1	Invalid appKey or secretKey
2	Invalid phone number
3	Insufficient balance
4	Call failed due to network or carrier issue
5	Bot script not found or error
99	System error

Agent (Agency) Integration

Brief Description: Manage and monitor agents (sales, support, or delivery) via API. Create tasks, assign to agents, track status, and receive updates through webhooks.

Request URL (Assign Task)

Send request to create or assign a task to an agent.
Example: http://api2.vitelcomm.com/api/agent/assign

Request Method

POST

Content-Type: application/json

Request Body Parameters

Parameter	Type	Required	Description
appKey	string	Yes	API application key
secretKey	string	Yes	API secret key
agentId	string	Yes	ID of the agent to assign the task
taskId	string	Yes	Unique task ID
taskType	string	Yes	Type of task (e.g., delivery, support, sales)
details	object	No	Custom task details, including description, priority, due date, etc.
ext	string	No	Optional extension field, returned in webhook callbacks

Request Example

curl --location --request POST 'http://api2.vitelcomm.com/api/agent/assign' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appKey": "asdf",
    "secretKey": "qwer",
    "agentId": "agent001",
    "taskId": "task123",
    "taskType": "delivery",
    "details": {
        "description": "Deliver package to customer",
        "priority": "high",
        "dueDate": "2025-12-01 18:00:00"
    },
    "ext": "customInfo123"
}'
    

Webhook Callback

All task updates (assigned, started, completed, failed) are sent to your webhook URL.

Webhook URL Example

Example: http://yourdomain.com/api/agent/webhook

Webhook Body Parameters

Parameter	Type	Description
taskId	string	Unique task ID
agentId	string	Agent ID assigned to the task
status	string	Task status: ASSIGNED, IN_PROGRESS, COMPLETED, FAILED
startTime	string	Task start time (yyyy-MM-dd HH:mm:ss)
endTime	string	Task end time (yyyy-MM-dd HH:mm:ss)
ext	string	Optional extension field returned from request
resultCode	string	Result code for success/failure

Webhook Example (JSON)

{
    "taskId": "task123",
    "agentId": "agent001",
    "status": "COMPLETED",
    "startTime": "2025-11-28 10:00:00",
    "endTime": "2025-11-28 12:30:00",
    "ext": "customInfo123",
    "resultCode": "0"
}
    

Webhook Response

Respond with HTTP 200 OK and body success to acknowledge the event.

Error Codes

Code	Description
0	Task request succeeded
1	Invalid appKey or secretKey
2	Invalid agentId or taskId
3	Insufficient balance or quota
4	Task failed due to system or network error
99	System error

Short Link API

Brief Description: Generate short links from long URLs and query information about the generated short links.

Generate Short Link

Request URL: http://api2.vitelcomm.com/api/shortlink/create

Request Method: POST

Content-Type: application/json

Request Body Parameters

Parameter	Type	Required	Description
appKey	string	Yes	API application key
secretKey	string	Yes	API secret key
longUrl	string	Yes	The original long URL to shorten
customAlias	string	No	Optional custom short link alias
expireTime	string	No	Optional expiration date/time for the short link (yyyy-MM-dd HH:mm:ss)

Request Example

curl --location --request POST 'http://api2.vitelcomm.com/api/shortlink/create' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appKey": "asdf",
    "secretKey": "qwer",
    "longUrl": "https://www.example.com/very/long/url/for/test",
    "customAlias": "my-test-link",
    "expireTime": "2025-12-31 23:59:59"
}'
    

Response Example

{
    "code": 0,
    "msg": "Short link created successfully",
    "result": {
        "shortUrl": "http://nx.link/my-test-link",
        "longUrl": "https://www.example.com/very/long/url/for/test",
        "expireTime": "2025-12-31 23:59:59",
        "alias": "my-test-link"
    }
}
    

Query Short Link Info

Request URL: http://api2.vitelcomm.com/api/shortlink/query

Request Method: GET

Request Parameters

Parameter	Type	Required	Description
appKey	string	Yes	API application key
secretKey	string	Yes	API secret key
shortUrl	string	Yes	Short URL to query

Query Response Example

{
    "code": 0,
    "msg": "Query successful",
    "result": {
        "shortUrl": "http://nx.link/my-test-link",
        "longUrl": "https://www.example.com/very/long/url/for/test",
        "createTime": "2025-11-28 10:00:00",
        "expireTime": "2025-12-31 23:59:59",
        "clickCount": 123
    }
}
    

Error Codes

Code	Description
0	Request succeeded
1	Invalid appKey or secretKey
2	Short URL not found
3	Expired short link
99	System error

Get Customer Balance

Brief Description: Retrieve the current balance and credit balance of a customer account.

Request URL

http://api.vitelcomm.com/api/common/getBalance

Request Method

POST

Content-Type: application/x-www-form-urlencoded

Request Parameters

Parameter	Required	Type	Description
appkey	Yes	string	Any enabled SMS application appkey
secretkey	Yes	string	Any enabled SMS application secretkey

Request Example

curl --location --request POST 'http://api.vitelcomm.com/api/common/getBalance' \
--data-urlencode 'appkey=asdf' \
--data-urlencode 'secretkey=qwer'
    

Response Example

{
    "code": "0",
    "amount_cus": "3788.32",
    "credit_cus": "500",
    "currency": "USD"
}
    

Response Parameter Description

Parameter	Type	Description
code	string	Result code (0 for success)
amount_cus	string	Current account balance
credit_cus	string	Credit balance
currency	string	Currency of the account balance

Note

Error Codes:

Code	Description
0	Request successful