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

페이지 이동경로

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"
  }'

API Method
Method URL
POST https://{base_url}/v2/send/rcs
코드예제Path Parameter of Sending 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 RCS
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 RCS
Parameter 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 RCS
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 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'

API Method
Method URL
POST https://{base_url}/v2/upload/rcs
코드예제Path Parameter of Uploading RCS 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
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 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 RCS File
Property 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 File
Field 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}'

API Method
Method URL
POST https://{base_url}/v2/info/rcs/results
코드예제Path Parameter of Retrieving RCS Delivery Result
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 Result
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 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 Result
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 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}'

API Method
Method URL
PUT https://{base_url}/v2/info/rcs/results/complete/{report_group_id}
코드예제Path Parameter of Closing RCS Delivery List Retrieval Request
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 Request
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 Closing RCS Delivery List Retrieval Request

{
  "code": "200",
  "code_detail": {
    "detail_code": "NRM00000",
    "detail_message": "Success"
  }
}

코드예제Response Elements of Closing RCS Delivery List Retrieval Request
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
}'

API Method
Method URL
GET https://{base_url}/v2/info/rcs/search
코드예제Path Parameter of Retrieving RCS 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
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 List
Property 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 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
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 List
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
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}'

API Method
Methode URL
GET https://{base_url}/v2/info/rcs/search/detail/{uid}
코드예제Path Parameter of Retrieving Detailed List of Delivered 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
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 RCS
Property 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 RCS
Field 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)
이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

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