RCS
The RCS service is an integrated messenger standard developed by Global System for Mobile Communications Association(GSMA), and provides various services such as group chatting, content sharing, brand creation, etc.
You can use this API to send RCS to users based on their phone number.
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 RCS
This API is used to send RCS.
Request
Request Syntax
코드예제Request Syntax of Sending RCS
curl -X POST "https://{base_url}/v2/send/rcs" \
-H "accept: */*" \
-H "authorization: Bearer {oauthToken}" \
-H "Content-Type: application/json" \
-d '{
"cid": "202210181700001",
"message_type": "RCSSMS",
"phone_number": "01000000000",
"template_code": "SMwThM00",
"agency_id": "kakaoenterprise1",
"ad_flag": "Y",
"footer": "080-0000-0000",
"sender_no": "0316001021",
"copy_allowed": true,
"body": [
{
"title": "RCSMMS Title",
"description": "RCSMMS Main text",
"media": "maapfile://0001"
}
],
"fall_back_yn": true,
"fall_back_message_type": "SM",
"fall_back_title": "test",
"fall_back_message": "alternative message"
}'
Method | URL |
---|---|
POST | https://{base_url}/v2/send/rcs |
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 |
|||
General | stg-bizmsg-bank.kakaoenterprise.com |
||||
Finance | stg-bizmsg-stock.kakaoenterprise.com |
||||
Public institution | stg-bizmsg-gov.kakaoenterprise.com |
Request Header
표Request Header of Sending RCSParameter | 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 RCSParameter | Type | Required | Description |
---|---|---|---|
cid | String | Y |
Defined Key ID by corporate customer |
message_type | String | Y |
Message type |
RCSSMS : SMS |
|||
RCSLMS : LMS |
|||
RCSMMS : MMS |
|||
RCSTMPL : RCS template |
|||
phone_number | String | Y |
Mobile number of recipient (including country code (82 ))- text(16) |
template_code | String | Y |
RCS template code - Even if it is not RCSTMPL type, basic template code for each type must be input. - text(30) |
agency_id | String | Y |
ID of brand agency - Available upon contract |
client_id | String | N |
Customer ID |
ad_flag | String | Y |
Whether it is advertising message - text(1) |
Y (default): Yes |
|||
N : No |
|||
footer | String | N |
Phone number registered for rejection - Available only when ad_flag is Y |
sender_no | String | Y |
Sender(Corporate customer) number - Used for alternative sending, random value available when not in use - text(16) |
copy_allowed | Boolean | N |
Whether allowed to copy RCS contents |
true (default): copy allowed |
|||
false : copy not allowed |
|||
Array | N |
Main text of [RCSSMS, RCSLMS, RCSMMS] message - More than 2 bodies are sent as a carousel, and delivery fails if the limit for each type is exceeded. |
|
RCSSMS : Body is up to 1, button per Body is up to 1 |
|||
RCSLMS : Body is up to 1, button per Body is up to 3 |
|||
RCSMMS : Body is up to 6, button per Body is up to 2 depending on basic template code |
|||
title | String | Y |
Title of RCS message |
description | String | Y |
Main text of RCS |
RCSSMS : Max. 100 Byte |
|||
RCSLMS : Max. 1300 Byte |
|||
RCSMMS total per card: Max. 1300 Byte |
|||
RCSTMPL sum of fixed part and variable part: Max. 90 Byte |
|||
media | String | N |
URL of [RCSMMS] attachments uploaded in advance |
button | Array | N |
Configure the button according to the standard of GSMA RCC.07 3.6.10.4 ‘suggestions’ - Please refer to Button Data Example |
tmpl_decription | String | N |
[RCSTMPL] Descriptive main text of template for using Free type template - Input every main text including variable part - total length of variable part is up to 90 characters |
tmpl_variable | Map | N |
[RCSTMPL] JSON formatted with key(variable name) - value(value) pair for using cell type template - Include only variable, total length of variable part is up to 90 characters |
biz_no | String | N |
Identification code of the original sender (For reselling purpose) |
fall_back_yn | Boolean | Y |
Whether to send alternative messages |
true : to use |
|||
false (default): Not to use |
|||
fall_back_message_type | String | N |
Message type of alternative message - text(2) |
SM : SMS |
|||
LM : LMS |
|||
fall_back_title | String | N |
Title of alternative message - 60 Byte |
fall_back_message | String | N |
Main text of alternative message - text(2000) |
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) |
Button Data Example
Response
Response Syntax
코드예제Response Syntax of Sending RCS
{
"code": "100",
"result": {
"detail_code": "OK",
"detail_message": null
},
"uid": "2210181656511076scJhgrcTG+U+jB",
"cid": "2022101800001"
}
Response Elements
표Response Elements of Sending RCSField | 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 result(For reference) | |
detail_code | String | N |
Detailed result code(For reference) |
detail_message | String | N |
Detailed result message(For reference) |
uid | String | N |
Message key ID |
cid | String | N |
Defined Key ID by customer |
NOTE
Please refer to the Sample Code document for API-specific codes.
Uploading RCS File
This API is used to upload the files before sending RCS.
Request
Request Syntax
코드예제Request Syntax of Uploading RCS File
curl -X 'POST' \ 'https://{base_url}/v2/upload/rcs' \
-H 'accept: */*' \
-H 'Authorization: Bearer {oauthToken}' \
-H 'Content-Type: multipart/form-data' \
-F 'image=@test_img.jpg;type=image/jpg' \
-F 'description=For Christmas events'
Method | URL |
---|---|
POST | https://{base_url}/v2/upload/rcs |
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 |
|||
General | stg-bizmsg-bank.kakaoenterprise.com |
||||
Finance | stg-bizmsg-stock.kakaoenterprise.com |
||||
Public institution | stg-bizmsg-gov.kakaoenterprise.com |
Request Header
코드예제Request Header of Uploading RCS FileParameter | 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 RCS FileProperty | Type | Required | Description |
---|---|---|---|
image | File | Y |
Details of RCS file - @test_img.jpg;type=image/{image type} - {image type}: jpg or png - File size: max. 1MB |
description | File | Y |
Description of RCS file |
Response
Response Syntax
코드예제Response Syntax of Uploading RCS File
{
"code": "200",
"result": {
"detail_code": "200",
"detail_message": null
},
"file_id": "BR.xCu2bm23hj.d924474ec319404e898fb62192374fbf",
"url": "maapfile://BR.xCu2bm23hj.d924474ec319404e898fb62192374fbf",
"expiry_date": "2024-01-17T00:00:00.000+09"
}
Response Elements
코드예제Response Elements of Uploading RCS FileField | Type | Required | Description |
---|---|---|---|
code | String | N |
Result code |
Object | N |
Result detail - Refer to API Message Status Code |
|
detail_code | String | N |
Result code detail - Refer to API Message Status Code |
detail_message | String | N |
Result message detail - Refer to API Message Status Code |
file_id | String | N |
Created file ID |
url | String | N |
Uploaded image URL |
expiry_date | String | N |
Expiration date |
Retrieving RCS Delivery Result
This API is used to Retrieving RCS Delivery Result. When using RCS, you can get up to 1000 results through the requesting RCS result request API.
Note
After requesting message results, Closing RCS Delivery List Retrieval Request API must be called so that the processed results are not retrieved again.
Request
Request Syntax
코드예제Request Syntax of Retrieving RCS Delivery Result
curl -X 'GET' \
'https://{base_url}/v2/info/rcs/results' \
-H 'accept: */*' \
-H 'Authorization: Bearer {oauthToken}'
Method | URL |
---|---|
POST | https://{base_url}/v2/info/rcs/results |
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 |
|||
General | stg-bizmsg-bank.kakaoenterprise.com |
||||
Finance | stg-bizmsg-stock.kakaoenterprise.com |
||||
Public institution | stg-bizmsg-gov.kakaoenterprise.com |
Request Header
코드예제Request Header of Retrieving RCS Delivery ResultParameter | 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 RCS Delivery Result
{
"code": "200",
"code_detail": {
"detail_code": "NRM00000",
"detail_message": "success"
},
"report_group_id": "5799598466530692318",
"results": [
{
"uid": "220830105315335+dsk43BTSrG1g3V",
"client_id": "test00001",
"cid": "209fcb9da31d46b4a01278cd187c7289",
"status": "API_200",
"rcs_status": "success"
}
]
}
Response Elements
표Response Elements of Retrieving RCS Delivery ResultField | 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 |
Code detail | |
detail_code | String | N |
Detailed code |
detail_message | String | N |
Detailed message |
report_group_id | String | N |
Unique number of RCS result group |
Array | N |
List of RCS result | |
uid | String | N |
Message key ID |
client_id | String | N |
Client ID |
cid | String | N |
Key ID defined by customer |
status | String | N |
Message status code - For details, refer to API Message Status Code |
rcs_status | String | N |
Result code of RCS processing |
success : success |
|||
fallback_status | String | N |
Result code of fallback - For details, refer to API Message Status Code |
Closing RCS Delivery List Retrieval Request
The following API is used to close the request of retrieving the delivery result of RCS.
Request
Request Syntax
코드예제Request Syntax of Closing RCS Delivery List Retrieval Request
curl -X 'PUT' \
'https://{base_url}/v2/info/rcs/results/complete/{report_group_id}' \
-H 'accept: */*' \
-H 'Authorization: Bearer {oauthToken}'
Method | URL |
---|---|
PUT | https://{base_url}/v2/info/rcs/results/complete/{report_group_id} |
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 |
|||
General | stg-bizmsg-bank.kakaoenterprise.com |
||||
Finance | stg-bizmsg-stock.kakaoenterprise.com |
||||
Public institution | stg-bizmsg-gov.kakaoenterprise.com |
||||
report_group_id | String | Y |
Unique number of message result group - ex. 5799598466530692318 |
Request Header
코드예제Request Header of Closing RCS Delivery List Retrieval RequestParameter | 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 Closing RCS Delivery List Retrieval Request
{
"code": "200",
"code_detail": {
"detail_code": "NRM00000",
"detail_message": "Success"
}
}
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 |
Message status code | |
detail_code | String | N |
Detailed code |
detail_message | String | N |
Detailed message |
Retrieving RCS Delivery List
This API is used to Retrieve the list of RCS sent.
Request
Request Syntax
코드예제Request Syntax of Retrieving RCS Delivery List
curl -X 'POST' \
'https://{base_url}/v2/info/rcs/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
}'
Method | URL |
---|---|
GET | https://{base_url}/v2/info/rcs/search |
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 |
|||
General | stg-bizmsg-bank.kakaoenterprise.com |
||||
Finance | stg-bizmsg-stock.kakaoenterprise.com |
||||
Public institution | stg-bizmsg-gov.kakaoenterprise.com |
Request Header
코드예제Request Header of Retrieving RCS Delivery ListProperty | 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 RCS Delivery ListProperty | 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 |
status | String | N |
RCS status code |
service_type | String | N |
Service type code |
RCSSMS : SMS |
|||
RCSLMS : LMS |
|||
RCSMMS : MMS |
|||
RCSTMPL : RCS |
Response
Response Syntax
코드예제Response Syntax of Retrieving RCS Delivery List
{
"status": "200",
"code": "200",
"count": 5,
"next": false,
"code_detail": {
"detail_code": "NRM00000",
"detail_message": "success"
},
"results": [
{
"uid": "221018080602083Uk~v+QosQZGZPYD",
"reg_date": "2022-10-18T08:06:02",
"status": "API_200",
"rcs_status": "success",
"cid": "e2fddce9509f4153bf220f1cc356b594"
}
]
}
Response Elements
코드예제Response Elements of Retrieving RCS Delivery ListField | 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 |
|||
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 | String | N |
Message status code - For details, refer to API Message Status Code |
rcs_status | String | N |
RRCS status code |
fallback_status | String | N |
Result code of fallback status |
error_message | String | N |
Error message |
tax_cd1 | String | N |
Settlement code 1 - Variable defined by customer for settlement - text(50) |
tax_cd2 | String | N |
Settlement code 2 - Variable defined by customer for settlement - text(50) |
Retrieving Detailed List of Delivered RCS
This API is used to retrieve the detailed list of RCS sent status.
Request
Request Syntax
코드예제Request Syntax of Retrieving Detailed List of Delivered RCS
curl -X 'GET' \
'https://{base_url}/v2/info/rcs/search/detail/{uid}' \
-H 'accept: */*' \
-H 'Authorization: Bearer {oauthToken}'
Methode | URL |
---|---|
GET | https://{base_url}/v2/info/rcs/search/detail/{uid} |
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 List of Delivered RCSProperty | 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 List of Delivered RCS
{
"code": "200",
"code_detail": {
"detail_code": "NRM00000",
"detail_message": "success"
},
"result": {
"uid": "221018080602083Uk~v+QosQZGZPYD",
"client_id": "ADMINTEST001",
"cid": "e2fddce9509f4153bf220f1cc356b594",
"reg_date": "2022-10-18T08:06:02",
"phone_number": "01000000000",
"message_base_id": "SS000000",
"service_type": "RCSSMS",
"body": "message",
"buttons": "[{}]",
"fallback_yn": false,
"req_date": "2022-10-18T08:06:02",
"res_date": "2022-10-18T08:06:06",
"sent_date": "2022-10-18T08:06:02",
"time_stamp": "2022-10-18T08:06:03",
"status": "API_200",
"rcs_status": "success",
"mno_info": "SKT"
}
}
Response Elements
코드예제Response Elements of Retrieving Detailed List of Delivered RCSField | Type | Required | Description |
---|---|---|---|
code | String | N |
Status code |
200 (OK): Success code, token information response |
|||
401 (Unauthorized): Invalid authority |
|||
403 (Forbidden): Server rejected the request. |
|||
404 (Not Found): Server couldn’t find requested resource. |
|||
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 |
client_id | String | N |
Defined Key ID by corporate customer |
cid | String | N |
Message registered date |
reg_date | String | N |
Message registered date |
phone_number | String | N |
Mobile number of recipient (including country code (82 )) |
callback | String | N |
Customer outgoing number |
message_base_id | String | N |
Message basic code |
message_group_id | String | N |
Message group code |
service_type | String | N |
Service type code |
RCSSMS : SMS |
|||
RCSLMS : LMS |
|||
RCSMMS : MMS |
|||
RCSTMPL : RCS template |
|||
body | String | N |
Message data to be sent |
buttons | [String] | N |
Button data |
fallback_yn | Boolean | N |
Whether to send alternative message |
true : Send alternative message |
|||
false (default): Not to send alternative message |
|||
fallback_type | String | N |
Type of alternative sending(SMS,LMS) |
fallback_calback | String | N |
fallback sending number |
fallback_subject | String | N |
fallback title |
fallback_message | String | N |
fallback main text |
req_date | String | N |
RCS outgoing time(date) |
res_date | String | N |
Result reception time(date) |
sent_date | String | N |
KT → mobile carrier outgoing time(date) |
time_stamp | String | N |
Mobile carrier → device reception time(date) |
status | String | N |
Status code |
rcs_status | String | N |
RCS result code |
fallback_status | String | N |
Fallback result code |
error_message | String | N |
Error message |
mno_info | String | N |
Mobile carrier(SKT, KT, LGU) |