GMS (v2)

An API for sending GMS (Global Messaging Service) messages from within the country to other countries.

Character encoding is based on UTF-8 by default.

This API can deliver message sending results through a WebHook.

GMS API (v2)

Path variable

Please ensure that path variables (enclosed in curly braces {}) within each URI are not omitted when making the call, referring to the following information.

code	description
service_id	service id domestic(korea) → global : gms-kg global → domestic(korea) : gms-gk

GMS API (v2)

POST https://gi8f5tsosp.apigw.ntruss.com/{service_id}/v2/send

The API sends SMS messages based on the country code.

Messages will only be sent to valid phone numbers written in international format (e.g., 41793026727).

It is advisable to use the E.164 number format, which is internationally standardized with a maximum length of 15 digits.

Typically, it starts with a plus sign (+) followed by the country code, network code, and subscriber number.

Non-E.164 formatted phone numbers may still work depending on the handset or network.

Headers

Name	Type	Description
Authorization*	string	userID;secret_key
Content-Type*	string	application/json;charset=utf-8

Request Body

Name	Type	Description
messages*	object	Detailed data for message sending (up to 10 records)
from	string	The sender of the SMS message should be in English characters, with a length of 3 ~ 13 characters for letters and 3 ~14 for numbers. If a separate sender is not used, "ONSMS" will be used.
to*	string	Receiver number This should be in international format. (EX : 41793026727)
messageId	string	Message unique key
text*	string	Message content
echo_to_webhook	string	The string to be received along with the webhook from the user via API PLEX (up to 256 bytes).
bulkId	string	Request unique key (in case of sending multiple messages in a single request).
smsCount	number	Number of SMS messages (count of SMS messages sent to a single destination).

200: OK Response returned successfully.

Request Body Example

{
    "messages": [
        {
            "from": "ONSMS",
            "to": "+8210xxxxxxxx",
            "text": "gms-kg-2 test 01",
            "messageId": "user_key1",
            "echo_to_webhook": "echo test"
        },
        {
            "from": "ONSMS",
            "to": "+8210xxxxxxxx",
            "text": "gms-kg-2 test 02",
            "echo_to_webhook": "echo test"
        }
    ]
}

Response Body

Even if the response HTTP status returns as 200, it does not necessarily indicate the successful acceptance of all requests.

(You can verify the acceptance status for each sent item through the response code field.)

key		type	description
results		object array	Message reception data.
	msg_key	string	Message unique key.
	code	string	Reception result code (Refer to API PLEX response codes).
	desc	string	Detailed reception result code.

Success

{
    "results": [
        {
            "code": "C100",
            "msg_key": "user_key_1",
            "desc": "success"
        },
        {
            "code": "C341",
            "msg_key": "4b68ca16-7aa8-4a17-b74c-2b8e4adb13f8",
            "desc": "success"
        }
    ]
}

Invalid request or error

{
    "code": "C401_1",
    "name": "authorization fail - authorization field error",
    "description": "there is no authorization key or value in http header"
}

Invalid request within the list

{
  "results": [
        {
            "code": "G141",
            "desc": "수신번호 예외",
            "msg_key": "user_key1"
        },
        {
            "code": "C100",
            "desc": "success",
            "msg_key": "user_key2"
        }
    ]
}

API PLEX response codes

code	HTTP status	title	description
C100	200	success
C400_1	400	Invalid data type	Refer to the description in the response body
C400_2	400	Invalid request parameter	Refer to the description in the response body
C400_3	400	Missing required parameters	Refer to the description in the response body
C401_1	401	Missing authorization key in the header
C401_2	401	Error in the authorization value in the header	Unable to separate values with ';'
C401_3	401	Invalid authorization value in the header	Cannot find valid authorization information
C404_1	404	Data not found	Refer to the description in the response body
C500_1	500	Internal server error	Refer to the description in the response body
G110	200	API unique ID exception (incorrect URL)
G141	200	Recipient number exception
G142	200	Invalid echo_to_webhook	Exceeded 256 bytes or type error
G150	200	Insufficient credit
G160	200	Exceeded the maximum allowed for a single transmission