Kakao i Connect Message::BizMessage(ENG)::BizMessage API::API Reference::XMS

페이지 이동경로

XMS

You can send SMS, LMS, SMS, ISM(International SMS), ILM(International LMS) by XMS API.

Note

  • Before calling every BizMessage API, you must call OAuth 2.0 API in advance.
  • Please refer to the Sample Code document for API-specific codes.
Warning
As the staging server is linked to the Kakao operation server and actually sends messages, please be careful to avoid sending messages incorrectly.

Sending XMS

This API is used to send XMS.

Request

Request Syntax

코드예제Request Syntax of Sending XMS

curl -X POST "https://{base_url}/v2/send/xms" \
-H  "accept: */*" \
-H  "authorization: Bearer {oauthToken}" \
-H  "Content-Type: application/json" \
-d  '{
		  "cid": "202210181600001",
		  "message_type": "SM",
		  "phone_number": "01000000000",
		  "message": "message",
		  "sender_no": "15000000",
		  "title": "title"
		}'

API Method
Method URL
POST https://{base_url}/v2/send/xms
코드예제Path Parameter of Sending XMS
Parameter Type Required Class Category Description
base_url String Y Operating General bizmsg-web.kakaoenterprise.com
Finance bizmsg-bank.kakaoenterprise.com
Stock bizmsg-stock.kakaoenterprise.com
Public institution bizmsg-gov.kakaoenterprise.com
Staging General stg-user.bizmsg.kakaoenterprise.com
Finance stg-bizmsg-bank.kakaoenterprise.com
Stock stg-bizmsg-stock.kakaoenterprise.com
Public institution stg-bizmsg-gov.kakaoenterprise.com

Request Header

코드예제Request Header of Sending XMS
Parameter Type Required Description
accept String Y */*
authorization String Y bearer {oauthToken}
- {oauthToken}: Access token acquired by OAuth 2.0 API
Content-Type String Y application/json

Request Elements

코드예제Request Elements of Sending XMS
Property Type Required Description
client_id String N Customer ID
cid String Y Defined Key ID by corporate customer
message_type String Y Message type
- text(3)
SM: SMS
LM: LMS
MM: MMS
ISM: International SMS
ILM: International LMS
phone_number String Y Mobile number of recipient (including country code (82))
- text(16)
nat_cd String N Country code for international message transmission
- text(10)
message String Y XMS message to be sent
- text(2000)
sender_no String Y Sender(Corporate customer) number
- text(16)
title String N Title while sending LMS, MMS
- text(60)
content_group_id String N [MMS] file group ID
- Response value of MMS image upload API
- Required only when sending MMS
biz_no String N Identification code of the original sender (For reselling purpose)
tax_cd1 String N Settlement Code 1
- Variables defined by the customer for settlement
- text(50)
tax_cd2 String N Settlement Code 2
- Variables defined by the customer for settlement
- text(50)

Responses

Response Syntax

코드예제Response Syntax of Sending XMS

{
  "code": "200",
  "uid": "221018080314511j7usTgzgQDOXvIk",
  "cid": "202210181600001",
  "result": {
    "detail_code": "NRM0000",
    "detail_message": "success"
  }
}

Response Elements

코드예제Response Elements of Sending XMS
Field Type Required Description
code String Y Message delivery result code
100: In processing
200: Success
400: Authorization error
410: Invalid input value
420: File/image error
500: Internal system error
510: Failed to send
520: Failed but can be resent
uid String N Message key ID
cid String N Defined Key ID by customer
Result N Detailed result(For reference)
detail_code String N Detailed result code(For reference)
detail_message String N Detailed result message(For reference)

Uploading MMS File

This API is used to upload Attachments while sending MMS.

Request

Request Syntax

코드예제Request Syntax of Uploading MMS File

curl -X 'POST' \
  'https://{base_url}/v2/upload/message/mms/files' \
  -H 'accept: */*' \
  -H 'Authorization: {oauthToken}' \
  -H 'Content-Type: multipart/form-data' \
  -F 'images=@test_img.jpg;type=image/jpeg'

API Method
Method URL
POST https://{base_url}/v2/upload/message/mms/files
코드예제Path Parameter of Uploading MMS File
Parameter Type Required Class Category Description
base_url String Y Operating General bizmsg-web.kakaoenterprise.com
Finance bizmsg-bank.kakaoenterprise.com
Stock bizmsg-stock.kakaoenterprise.com
Public institution bizmsg-gov.kakaoenterprise.com
Staging General stg-user.bizmsg.kakaoenterprise.com
Finance stg-bizmsg-bank.kakaoenterprise.com
Stock stg-bizmsg-stock.kakaoenterprise.com
Public institution stg-bizmsg-gov.kakaoenterprise.com

Request Header

코드예제Request Header of Uploading MMS File
Parameter Type Required Description
accept String Y */*
authorization String Y bearer {oauthToken}
- {oauthToken}: Access token acquired by OAuth 2.0 API
Content-Type String Y application/json

Request Elements

코드예제Request Elements of Uploading MMS File
Property Type Required Description
files List Y MMS file
- Number of file: Max. 3
- File format: jpg
- File size: Total up to 200KB

Response

Response Syntax

코드예제Response Syntax of Uploading MMS File

{
  "code": "200",
  "result": {
    "detail_code": "NRM00000",
    "detail_message": "success"
  },
  "content_group_id": "20221018-16522115ca"
}

Response Elements

코드예제Response Elements of Uploading MMS File
Field Type Required Description
code String Y Message delivery result code
100: In processing
200: Success
400: Authorization error
410: Invalid input value
420: File/image error
500: Internal system error
510: Failed to send
520: Failed but can be resent
Result N Detailed result(For reference)
detail_code String N Detailed result code(For reference)
detail_message String N Detailed result message(For reference)
content_group_id String N List Group ID of uploaded file
- Input parameter when sending MMS message

Retrieving XMS Delivery List

This API is used to retrieve the list of XMS sent.

Request

Request Syntax

코드예제Request Syntax of Retrieving XMS Delivery List

curl -X 'POST' \
  'https://{base_url}/v2/info/message/search' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {oauthToken}' \
  -H 'Content-Type: application/json' \
  -d '{
    "start_date": "2022-10-18",
    "end_date": "2022-10-18",
    "size": 1000
  }'

API Method
Method URL
POST https://{base_url}/v2/info/message/search
코드예제Path Parameter of Retrieving XMS Delivery List
Parameter Type Required Class Category Description
base_url String Y Operating General bizmsg-web.kakaoenterprise.com
Finance bizmsg-bank.kakaoenterprise.com
Stock bizmsg-stock.kakaoenterprise.com
Public institution bizmsg-gov.kakaoenterprise.com
Staging General stg-user.bizmsg.kakaoenterprise.com
Finance stg-bizmsg-bank.kakaoenterprise.com
Stock stg-bizmsg-stock.kakaoenterprise.com
Public institution stg-bizmsg-gov.kakaoenterprise.com

Request Header

코드예제Request Header of Retrieving XMS Delivery List
Parameter Type Required Description
accept String Y */*
Authorization String Y bearer {oauthToken}
- {oauthToken}: Access token acquired by OAuth 2.0 API
Content-Type String Y application/json

Request Elements

코드예제Request Elements of Retrieving XMS Delivery List
Property Type Required Description
start_date String N Search start date
- Format: yyyy-mm-dd(date)
- End date should be filled with start date.
- If no input is provided, it will retrieve data for the same day.
end_date String N Search end date
- Format: yyyy-mm-dd(date)
- Start date should be filled with end date.
- If no input is provided, it will retrieve data for the same day.
client_id String N ID of the sender
size Integer N List per page
- Max. 1000
- int32
last_uid String N The last Message key ID of the viewed page list.
- Required when viewing the next page
etc1 String N Parameter 1 defined by customer
- text(50)
etc2 String N Parameter 2 defined by customer
- text(50)
status_code String N Message status code
- For details, refer to API Message Status Code.

Response

Response Syntax

코드예제Response Syntax of Retrieving XMS Delivery List

{
  "status": "200",
  "code": "200",
  "count": 4,
  "next": false,
  "code_detail": {
    "detail_code": "NRM00000",
    "detail_message": "success"
  },
  "results": [
    {
      "uid": "221018080314511j7usTgzgQDOXvIk",
      "reg_date": "2022-10-18T08:03:15",
      "status_code": "API_200",
      "kko_status_code": "0000",
      "cid": "11329b64174a4738b049e2a74e93c5c1"
    }
  ]
}

Response Elements

코드예제Response Elements of Retrieving XMS Delivery List
Field Type Requried Description
status String Y Message delivery result code
100: In processing
200: Success
400: Authorization error
410: Invalid input value
420: File/image error
500: Internal system error
510: Failed to send
520: Failed but can be resent
code String N Status code
count Integer N Number of lists when retrieving result
- int64
next Boolean N Whether there is the next page when retrieving the page
last_uid String N The last Key ID of the retrieved page list.
Object N Detailed message status code
detail_code String N Detailed code
detail_message String N Status message
Array N Retrieved list
uid String N Message key ID
cid String N Key ID defined by customer
reg_date String N Message registered date
status_code String N Message status code
- For details, refer to API Message Status Code.
kko_status_code String N Processing result code sent from KakaoTalk
sms_status_code String N SMS status code
error_message String N Error message (upon error)
tax_cd1 String N Settlement code1
- Variable defined by customer for settlement
- text(50)
tax_cd2 String N Settlement code 2
- Variable defined by customer for settlement
- text(50)
etc1 String N Customer value 1
- Variable defined by customer
- text(50)
etc2 String N Customer value 2
- Variable defined by customer
- text(50)
etc3 String N Customer value 3
- Variable defined by customer
- text(50)
etc4 String N Customer value 4
- Variable defined by customer
- text(50)
etc5 String N Customer value 5
- Variable defined by customer
- text(50)
etc6 String N Customer value 6
- Variable defined by customer
- text(50)
etc7 String N Customer value 7
- Variable defined by customer
- text(50)
etc8 String N Customer value 8
- Variable defined by customer
- text(50)
etc9 String N Customer value 9
- Variable defined by customer
- text(50)
etc10 String N Customer value 10
- Variable defined by customer
- text(50)

Retrieving Detailed Delivery List of XMS

The follwing API is to retrieve detailed result of message sent.

Request

Request Syntax

코드예제Request Syntax of Retrieving Detailed Delivery List of XMS

curl -X 'GET' \
  'https://{base_url}/v2/info/message/search/detail/{uid}' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {oauthToken}'

API Method
Method URL
GET https://{base_url}/v2/info/message/search/detail/{uid}
코드예제Path Parameter of Retrieving Detailed Delivery List of XMS
Parameter Type Required Class Category Description
base_url String Y Operating General bizmsg-web.kakaoenterprise.com
Finance bizmsg-bank.kakaoenterprise.com
Stock bizmsg-stock.kakaoenterprise.com
Public institution bizmsg-gov.kakaoenterprise.com
Staging General stg-user.bizmsg.kakaoenterprise.com
Finance stg-bizmsg-bank.kakaoenterprise.com
Stock stg-bizmsg-stock.kakaoenterprise.com
Public institution stg-bizmsg-gov.kakaoenterprise.com
uid String Y Message key ID
ex. 21018173501346cxU7zEswSYSsTmS

Request Header

코드예제Request Header of Retrieving Detailed Delivery List of XMS
Parameter Type Required Description
accept String Y */*
Authorization String Y bearer {oauthToken}
- {oauthToken}: Access token acquired by OAuth 2.0 API

Response

Response Syntax

코드예제Response Syntax of Retrieving Detailed Delivery List of XMS

{
  "code": "200",
  "code_detail": {
    "detail_code": "NRM00000",
    "detail_message": "success"
  },
  "result": {
    "uid": "221018080314511j7usTgzgQDOXvIk",
    "reg_date": "2022-10-18T08:03:15",
    "message_type": "AT",
    "status_code": "API_200",
    "phone_number": "01000000000",
    "template_code": "test_kep_template_005",
    "req_date": "2022-10-18T08:03:14",
    "req_sms_yn": "N",
    "kko_status_code": "0000",
    "message": "message",
    "cid": "11329b64174a4738b049e2a74e93c5c1"
  }
}

Response Elements

코드예제Response Elements of Retrieving Detailed Delivery List of XMS
Field Type Required Description
code String Y Message delivery result code
100: In processing
200: Success
400: Authorization error
410: Invalid input value
420: File/image error
500: Internal system error
510: Failed to send
520: Failed but can be resent
Object N Detailed message status code
detail_code String N Detailed code
detail_message String N Status message
Object N Detailed delivery results of a single message
uid String N Message key ID
reg_date String N Message registered date
message_type String N Mesage type
AT: Alim Talk
AI: Alim Talk image
FT: Friend Talk
FI: Friend Talk image
FW: Friend Talk wide image
SM: SMS
LM: LMS
MM: MMS
ISM: International SMS
status_code String N Message status code
- For details, refer to API Message Status Code.
phone_number String N Mobile number of recipient (including country code (82))
- text(16)
template_code String N The template code registered as the actual message type to be sent
- text(30)
req_date String  N Request date(value present when result exists)(date)
error_message String N Error Message
req_sms_yn String N Whether SMS is requested
req_sms_date String  N SMS request date(date-time)
sender_no String N Sender(Corporate customer) number
- text(16)
sms_type String N Alternative message type
- text(2)
SM: SMS
LM: LMS
MM: MMS
kko_status_code String N Processing result code from KakaoTalk
sms_status_code String N SMS status code
message String N Alim Talk message to send
- text(1000)
sms_message String N SMS message to be sent
- text(4000)
title String N Title of LMS, MMS
- text(60)
cid String N Defined Key ID by corporate customer
kko_title String N Highlighted information in template contents
- text(50)
nat_cd String N Country code for international message transmission
content_group_id String N MMS file group ID(Required when sending MMS)
header String N Title to display at the top of the message
이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

더 자세한 의견은 contact.dkt@kakaocorp.com 으로 제보해주세요.