Document - Vihat Global Co Ltd

Overview

ViHAT Global is one of messaging providers' solutions worldwide. We will allow the business to send messages to your customers and get message status callbacks.

Every message will pass a set of validations. For examples: Is the phone number valid? Is the balance enough to send? Is the credential still valid to perform request?

Message status

According to the type of channels, you can get the different types of statuses as below descriptions. SMS

Status	Description
DELIVERD	message is successfully delivered to the customer handset
UNDELIV	message is unsuccessfully delivered to the customer handset by some reasons (low coverage, wrong number, etc…)
REJECTD	message is rejected by our or our supplier by some reasons (invalid phone number format, blockage of sender id, etc…)
EXPIRED	the server is unable to deliver the message in a specified amount of time. For instance, when the phone was turned off.
UNKNOWN	unknown error occurred.

Chat apps Viber

Status	Description
DELIVERED	Viber client received the message from the Viber’s server.
SEEN	The user opened Viber and entered the conversation with the specified message.
EXPIRED	A message that was sent but was not able to get delivered to user with the time frame set by sender.

HTTP Methods

Each of channel has a different mechanism to send the message.

Send SMS message

Validations

1. The user's credential at vihatglobal.com 2. User's balance 3. Destination address

HTTP URL

http://rest.simosms.com/MainService.svc/json/SendMultipleMessage_V4_post

Parameters

Field	Required	Description
apiKey (String)	Yes	The key provided once the account was activated at vihatglobal.com. Find it at vihatglobal.com
secretKey (String)	Yes	The key provided once the account was activated at vihatglobal.com. Find it at vihatglobal.com
phone (String)	Yes	The receiver’s phone number. The number must follow the format. Ex: To send the message to Vietnam. The number must be 84968501615
content (String)	Yes	The content will be delivered to the customer handset.
isUnicode (String)	No	Default: 0 (GSM7) If you send the message with another encoding or unicode charset. The value should be 1
originalSender (String)	No	The sender will be displayed at the screen of customer handset. If it is empty, the default sender will be used to deliver.

Sample request


    curl --location --request POST
    'http://rest.simosms.com/MainService.svc/json/SendMultipleMessage_V4_post'
    --header 'Content-Type: application/json'
    --data-raw '{
            "apiKey": "YOUR_API_KEY",
            "secretKey": "YOUR_SECRET_KEY",
            "phone": "84968501615",
            "content": "this is message test",
            "isUnicode": "0",
            "smsType": "8",
            "originalSender": "Facebook"
    }'

Error codes

Code	Description
100	Request success
101	Unauthorize (wrong apiKey or secretKey value)
102	Account is blocked
103	Balance is insufficient
103	Destination not permitted
124	Request is processing

Sample response


    {
        "CodeResult": "100",
        "CountRegenerate": 0,
        "SMSID": "28ea0ba1-8414-4b54-a812-7021086524e4132"
    }

Callback status

You must register the callback URL to get the callback.

Post parameters

Parameter	Description
phone (String)	The customer phone number
reference_id (String)	The message id at vihatglobal that was sent once your request was approved.
status (String)	The status of message
err_code (String)	The delivery error code, by default: It belongs to our partner response code.
delivery_time (String)	The time message was delivered to handset in our timezone
total_price (Decimal)	The currency set on your account
time_zone (String)	The billing timezone

Sample callback


    {
        "phone": "84968501615",
        "reference_id": "28d49817-f373-4dfa-886a-2cb1f79aa81c415",
        "status": "DELIVRD",
        "err_code": "000",
        "delivery_time": "12/3/2021 11:41:58 AM",
        "total_price": "0.0500000",
        "currency": "EUR",
        "time_zone": "GMT/UTC +7:00"
    }

Send Voice OTP

Validations

1. The user's credential at vihatglobal.com 2. User's balance 3. Destination address

HTTP URL

http://rest.simosms.com/MainService.svc/json/v1/send-voice/

Parameters

Field	Required	Description
api_key (String)	Yes	The key provided once the account was activated at vihatglobal.com. Find it at vihatglobal.com
secret_key (String)	Yes	The key provided once the account was activated at vihatglobal.com. Find it at vihatglobal.com
phone_number (String)	Yes (if type equals 1)	The receiver’s phone number. The number must follow the format. Ex: To send the message to Vietnam. The number must be 84968501615
code (String)	Yes	The OTP code will be delivered to the customer handset.
lang (String)	Yes	There are 3 types of supported languages : English (en), Khmer (kh)

Sample request


    curl --location --request POST 'http://rest.simosms.com/MainService.svc/json/v1/send-voice/' \
    --header 'Content-Type: application/json' \
    --data-raw '{
    "api_key": "YOUR_API_KEY",
    "code": "4567",
    "lang": "en",
    "phone_number": "855978226666",
    "secret_key": "YOUR_SECRET_KEY",
    "type": 1
    }'

Error codes

Code	Description
SUCCESS = 100	Submit successfully
INVALID_CREDENTIAL = 101	Wrong api_key or secret_key
INSUFFICENT_BALANCE = 102	Insufficient Balance
BLOCKAGE_USER = 103	Account is blocked
BAD_BODY_REQUEST = 104	Invalid parameters
EQUEST_IS_PROCESSING = 105	Request is processing
INVALID_DESTINATION = 106	Invalid destination
PRICE_NOT_CONFIG = 107	Price is not configured
NOT_SUPPORTED = 109	Not supported
PRICE_VALIDATE_FALSE = 201	Validate price false
UNKNOWN_ERROR = 108	Server error, normally Vihat Global side.

Sample response


    {
        "reference_id": "ee1195c8a1df403a980129cd723be4d8",
        "status_code": 100
    }

Send Voice Using File

Validations

1. The user's credential at vihatglobal.com 2. User's balance 3. Destination address 4. File length

HTTP URL

http://rest.simosms.com/MainService.svc/json/v1/send-voice/

Parameters

Field	Required	Description
api_key (String)	Yes	The key provided once the account was activated at vihatglobal.com. Find it at vihatglobal.com
secret_key (String)	Yes	The key provided once the account was activated at vihatglobal.com. Find it at vihatglobal.com
phone_number (String)	Yes	The receiver’s phone number. The number must follow the format. Ex: To send the message to Vietnam. The number must be 84968501615.
type (String)	Yes	Using value equals 2 to make the voice with recording file.
template_id (String)	Yes	The template given when uploading the file to VHG system.

Sample request


    curl --location --request POST 'http://rest.simosms.com/MainService.svc/json/v1/send-voice/' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "api_key": "YOUR_API_KEY",
        "phone_number": "855968226666",
        "secret_key": "YOUR_SECRET_KEY",
        "type": 2,
        "template_id":"TEMPLATE_ID_GIVEN_BY_VIHAT"
    }'

Error codes

Code	Description
SUCCESS = 100	Submit successfully
INVALID_CREDENTIAL = 101	Wrong api_key or secret_key
INSUFFICENT_BALANCE = 102	Insufficient Balance
BLOCKAGE_USER = 103	Account is blocked
BAD_BODY_REQUEST = 104	Invalid parameters
EQUEST_IS_PROCESSING = 105	Request is processing
INVALID_DESTINATION = 106	Invalid destination
PRICE_NOT_CONFIG = 107	Price is not configured
NOT_SUPPORTED = 109	Not supported
PRICE_VALIDATE_FALSE = 201	Validate price false
UNKNOWN_ERROR = 108	Server error, normally Vihat Global side.

Sample response


    {
        "reference_id": "ee1195c8a1df403a980129cd723be4d8",
        "status_code": 100
    }

Upload File

Validations

1. The user's credential at vihatglobal.com 2. File length 3. File extensions

HTTP URL

https://voice.simosms.com/api/auto-call/recording/upload

Parameters

Field	Required	Description
api_key (String)	Yes	The key provided once the account was activated at vihatglobal.com. Find it at vihatglobal.com
secret_key (String)	Yes	The key provided once the account was activated at vihatglobal.com. Find it at vihatglobal.com
file (String)	Yes	File to upload to the system

Sample request


    curl --location --request POST 'https://voice.simosms.com/api/auto-call/recording/upload' \
    --form 'api_key="YOUR_API_KEY"' \
    --form 'secret_key="YOUR_SECRET_KEY"' \
    --form 'file=@"PATH_TO_YOUR_FILE"'

Error codes

Code	Description
REQ_OK = 100	Submit successfully
REQ_UNAUTH = 101	Wrong api_key or secret_key
NOT_SUPPORTED = 201	Not supported (File should be covered in *.mp3)
EXCEED_FILE_SIZED = 202	Max file length is 5MB
REQUEST_ERROR = 203	Request error
UNKNOWN_ERROR = 108	Server error, normally Vihat Global side.

Sample response


    {
        "status_code": 100,
        "err_message": "",
        "payload": {
        "templateId": "b7856e7a687347bf86793329206356004024"
        }
    }

Send Chatapps message

Viber

Validations 1. The sender id 2. The validity of desination 3. Max text length (1000 UTF-8 characters) 4. Max button caption length (30 UTF-8 characters) 5. Balance check for sending message 6. Maximum a button

HTTP URL

http://rest.simosms.com/MainService.svc/json/v1/send-ott/

Parameters

Field	Required	Description
apiKey (String)	Yes	The key provided once the account was activated at vihatglobal.com. Find it at vihatglobal.com
secretKey (String)	Yes	The key provided once the account was activated at vihatglobal.com. Find it at vihatglobal.com
phone_number (String)	Yes	The receiver’s phone number. The number must follow the format. Ex: To send the message to Vietnam. The number must be 84968501615
channel_type (Number)	Yes	Each channel will have a specified type. Viber: 16
body (Object)	Yes	The jason data that include the message content based on body_type

Body types

Type	Description
Text Only	`{ "body_type": 4, "text": "test message" }`
Text + Button	`{ "body_type": 2, "text": "test message", "buttons": [ { "caption": "Click me", "action": "YOUR_ACTION_URL" } ] }`
Image Only	`{ "body_type": 3, "image": "YOUR_IMG_URL" }`
Text + Image + Button	`{ "body_type": 1, "text": "test message", "image": "YOUR_IMG_URL", "buttons": [ { "caption": "Click me", "action": "YOUR_ACTION_URL" } ] }`

Sample request


    curl --location --request POST
    'http://rest.simosms.com/MainService.svc/json/v1/send-ott/'
    --header 'Content-Type: application/json'
    --data-raw '{
            "api_key": "YOUR_API_KEY",
            "secret_key": "YOUR_SECRET_KEY",
            "sender": "BNTEST",
            "phone_number": "84968501615",
            "channel_type": 16,
            "body": {
            "body_type": 1,
            "text": "test 1",
            "image": "https://resources.simosms.com/resource/imgs/024fa6ef-ef37-4ed7-a5a8-f301f94925ad.png",
            "buttons": [
                    {
                    "caption": "Click me",
                    "action": "https://simosms.com"
                    }
                ]
            }
    }'

Response

Field	Description
code_result	See the code result for details
message_id	Message id used to trace the message status
error_message	The error message describes the response of server based on code_result

Sample response


    {
        "code_result": 100,
        "message_id": "863e431e-30b6-4f71-a5dd-e4a4f2a5dd31227",
        "error_message":""
    }

Callback status

Each sender has a callback URL, it is optional once registering the sender. Its status (DELIVERED, SEEN, EXPIRED) will be sent to the URL per message id.

Callback status post parameters

Parameter	Description
status (String)	The status of message
message_id (String)	Message id used to trace the message status
time (String)	Time of the status sent by Viber
phone_number (String)	The destination number
channel (String)	The channel the message was sent
time_zone (String)	The billing time zone

Sample response


    {
        "status": "SEEN",
        "message_id": "fa77f63d-4eb8-47d0-81c2-0cf436c83b46281",
        "time": "2021-12-15T13:55:03.953",
        "phone_number": "84968501615",
        "channel": "Viber",
        "time_zone": "GMT/UTC +7"
    }

Two-way message

For the 2way message, we will send to the URL per sender with the user's replies

Message replies callback post parameters

Parameter	Description
message (Object)	The message object replied by the user, Excamples `"message": { "text": null, // message text replied by user "media": "MEDIA_URL", //media url stored at Viber "file_name": "VID_20201227_121221.mp4" // media file name }`
message_id (String)	Message id used to trace the message status
time (String)	Time of the status sent by Viber
phone_number (String)	The destination number
channel (String)	The channel the message was sent
time_zone (String)	The billing time zone

Sample response


    {
        "message": {
            "text": null,
            "media": "",
            "file_name": "VID_20201227_121221.mp4"
        },
        "message_id": "204c7ca1-0e7a-460f-bc1f-e2b9b95bfbd2596",
        "time": "2021-12-15T09:12:53",
        "phone_number": "+84986788704",
        "channel": "Viber",
        "time_zone": "GMT/UTC +7"
    }

Code reference

Code	Description
SUB_OK = 100	Submit successfully
AUTH_FAILED = 101	Wrong api_key or secret_key
INVMSG_TYPE = 102	Invalid message type
INVDST_ADDR = 103	Invalid destination address
INSUFF_BALNC = 104	Insufficient Balance
INVREQ_BODY = 105	Invalid request body
INVSRC_ADDR = 106	Cost is not configured for the destination
DEST_NOT_PERMITTD = 108	Destination is not permitted to send
REQ_PROCSSING = 111	Request is processing
USR_INACT_OTT = 112	User credential is not allowed to send message through chat apps
SERVR_ERR = 99	Server error, normally Vihat Global side.

SMPP

For huge volume SMS traffic, we prefer to use SMPP connection for sending message.

SMPP - Connection

Below are the connection details required to connect:

Setting	Value
IP address	125.212.248.242
Port	7889 , 7888
System ID	Your API KEY
Password	Your Secret KEY

Username & Password

Your username and password will be provided once you register the account at Vihat global site. If you observe any issue in connecting process, please contact us at here.

Binding

You can connect to Vihat Global SMPP servers using bind_receiver and bind_transmitter or bind_transceiver.

For relaying DLR back to your platform, Vihat Global servers will send back deliver_sm to any bind connected with the same systemId of the originating submit_sm PDU. This includes if you are sending from multiple sites; we will send to any active bind.

Throughput

Throughput is tailored to each customer’s requirement during our onboarding process. In most cases for each bind connected to Vihat Global SMPP servers, you will be able to submit a maximum of 30 messages per second. You can check with your account manager about specific requirements.

PDUs

The following PDUs are supported by Vihat Global SMPP servers:

bind_receiver
bind_transmitter
bind_transceiver
submit_sm
enquire_link
deliver_sm_resp
unbind

SMPP - Delivery receipt

Vihat Global sends delivery report information in the short_message field of a deliver_sm PDU.

The following format should be expected:


    id:12345678 sub:000 dlvrd:001 submit date:2112310215 done date:2112310215 stat:DELIVRD err:000 text:this is text

Where:

stat: status of message
err: error code for message

Message states

The following message states can be found in a delivery report:

DELIVRD
EXPIRED
UNDELIV
ACCEPTD
UNKNOWN
ENROUTE
REJECTD

SMPP - Data codings

When sending the message to Vihat Global SMPP platform, you must set the correct data encoding values.

We treat DCS 0 and DCS 3 as default GSM 7 encoding
Use DCS 8 for Unicode characters