This document describes how to integrate Kakao Talk Channel APIs into your service with a REST API.
Tag | Description |
---|---|
Login required | The API marked with this tag requires Kakao Login. You must implement the Kakao Login function first, and then call the corresponding API by using the access token issued when a user logs in. |
Consent required | To use the API marked with this tag, you must enable a specific scope required for the corresponding API. In addition, a user must also consent to the scope. Otherwise, an error occurs or empty value is returned. To check which scopes a user has consented to, you can call the Retrieving consent details API. |
From May 24th, 2021, we provide a new API for checking Kakao Talk Channel relationship. The new API has some changes in the URL, request parameters and response fields ('plus_friends' → 'channels'). You can find information of the legacy API in a separate document. Refer to Notice for more details.
This API enables you to check if a specific user has added or blocked your Kakao Talk Channel connected to your service app. Make sure that this API only informs the relationship between the user and the Kakao Talk Channel connected to the app that made a request. Thus, you cannot get all Kakao Talk Channels' information that the user has added but the channels related to your service only.
To use this API,
After completing the prerequisites above, send a GET request using an access token.
If you are an administrator, you can also use the app's Admin key to check the relationship between a Kakao Talk Channel and a specific user. When requesting using the app's Admin key and a service user ID, make a request from the service server by referring to the code snippet and parameters as follows. Make sure to use the app's Admin key only in the server.
Among Kakao Talk Channels that a user has added or blocked, only the channels connected to your service app return in the response in JSON format. Each channel object in the response contains detailed information, such as whether the user adds or blocks the Kakao Talk Channel currently and the time when the channel has been added or blocked.
In the following situations, permission-related error occurs:
GET /v1/api/talk/channels HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Name | Description | Required |
---|---|---|
Authorization | Access token as a type of user authentication.Authorization: Bearer ${ACCESS_TOKEN} |
O |
Name | Type | Description | Required |
---|---|---|---|
channel_public_ids | String[] |
List of Kakao Talk Channel IDs that you want to check the relationship with a user. | O |
GET /v1/api/talk/channels HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${APP_ADMIN_KEY}
Name | Description | Required |
---|---|---|
Authorization | Admin key as a type of user authentication.Authorization: KakaoAK ${APP_ADMIN_KEY} |
O |
Name | Type | Description | Required |
---|---|---|---|
target_id_type | String |
A type of a service user ID. Fixed as user_id . |
O |
target_id | Long |
Service user ID. | O |
channel_public_ids | String[] |
List of Kakao Talk Channel IDs that you want to check the relationship with a user. | O |
Name | Type | Description | Required |
---|---|---|---|
user_id | Long |
Service user ID. | O |
channels | Channels[] |
Kakao Talk Channel information. | X |
Name | Type | Description | Required |
---|---|---|---|
channel_uuid | String |
Kakao Talk Channel ID for search purpose. | O |
channel_public_id | String |
Kakao Talk Channel ID. | O |
relation | String |
Relationship between a Kakao Talk Channel and a user.ADDED : a user has blocked the channel.BLOCKED : a user has blocked the channel.NONE : a user has not either added or blocked the channel. |
O |
updated_at | Datetime |
Time when a Kakao Talk Channel is added or blocked in UTC*. Only returned if a Kakao Talk Channel is added ( ADDED ) or blocked (BLOCKED ). |
X |
*The time is based on Coordinated Universal Time(UTC), being 9 hours behind Korean Standard Time(KST). For the format of time, refer to RFC3339: Date and Time on the Internet.
curl -v -G GET "https://kapi.kakao.com/v1/api/talk/channels" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
--data-urlencode 'channel_public_ids=["_frxjem","_xnrxjem","_Brxjem"]'
curl -v -G GET "https://kapi.kakao.com/v1/api/talk/channels" \
-H "Authorization: KakaoAK ${APP_ADMIN_KEY}" \
-d "target_id_type=user_id" \
-d "target_id={USER_ID}" \
--data-urlencode 'channel_public_ids=["_frxjem","_xnrxjem","_Brxjem"]'
HTTP/1.1 200 OK
{
"user_id": 1111111,
"channels": [
{
"channel_uuid": "@테스트",
"channel_public_id": "_ZeUTxl",
"relation": "ADDED", // One of ADDED, BLOCKED, NONE
"updated_at": "2021-05-17T05:25:01Z"
}, // Only returned when "relation" is "ADDED" or "BLOCKED".
...
]
}
HTTP/1.1 400 Bad Request
{
"msg": "given account is not connected to any talk user.",
"code": -501
}
Before you use this API, you must consent to the related policy by referring to Prerequisites > Set for customer management.
After that, make a POST
request to create a new customer file as the code snippet below. Set the new file name to file_name
, and set the filtering criteria to schema
. Make sure that you cannot change the schema after defining it once.
If successful, the registered file ID returns as the value of file_id
. The file ID is used to add or delete a user in the customer file through other APIs.
When you register a customer file through this API, you must follow the schema rules:
Number
types are allowed for the value.POST /v1/talkchannel/create/target_user_file HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${REST_API_KEY}
Content-Type: application/json
Name | Type | Description | Required |
---|---|---|---|
channel_public_id | String |
Kakao Talk Channel ID. | O |
schema | JSON |
Define the item and type of customer information to be registered in a customer file. Pairs of key and value type. Supported keys: 생년월일 : birthday국가 : country지역 : region성별 : gender연령 : age구매금액 : purchase amount포인트 : point가입일 : signup date최근 구매일 : recent purchase date응모일 : event application date(Only Korean is supported for keys.) Value type: String or Number |
O |
file_name | String |
Name of a customer file. | O |
Name | Type | Description |
---|---|---|
file_id | Integer |
ID of the customer file that has been created. |
curl -v -X POST "https://kapi.kakao.com/v1/talkchannel/create/target_user_file" \
-H "Authorization: KakaoAK ${REST_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"channel_public_id": "_ZeUTxl",
"file_name": "vip고객리스트",
"schema":{
"생년월일":"string",
"성별":"string",
"연령":"number"
}
}'
HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
"file_id" : 437
}
You can view the customer file information registered for your Kakao Talk Channel through this API. Make a GET
request by specifying channel_public_id
of a Kakao Talk Channel that you want to view its information. If successful, the customer file information you requested returns.
GET /v1/talkchannel/target_user_file HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${REST_API_KEY}
Content-Type: application/json
Name | Type | Description | Required |
---|---|---|---|
channel_public_id | String |
Kakao Talk Channel ID. | O |
Name | Type | Description |
---|---|---|
file_id | Integer |
File ID. |
file_name | String |
File name. |
status | String |
File status. One of using , deleting , failed . |
update_at | String |
The time when the file has been uploaded. |
empty_slot | Integer |
Number of available slots. |
using_slot | Integer |
Number of slots in use. |
curl -v -G GET "https://kapi.kakao.com/v1/talkchannel/target_user_file" \
-H "Authorization: KakaoAK ${REST_API_KEY}" \
-d "channel_public_id=_ZeUTxl"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"results":[
{
"file_id":437,
"file_name": "VIPCustomerList",
"status":"USING",
"update_at":"2019-02-03 13:22:33",
"schema": "{\"birthday\":\"string\",\"gender\":\"string\",\"age\":\"number\"}"
},
...
],
"empty_slot":27,
"using_slot":3
}
You can add user information to the customer file. You can upload information of no more than 2,000 users at a time. You must use either app
(service user ID of Kakao Account) or phone
(mobile phone number of Kakao Talk) for id
, and input the appropriate value for the specified type. Schemas can be specified differently according to customer files, so pass the right value for the corresponding customer file in JSON array format as the sample below.
If successful, file_id
, request_count
(the number of users you requested to add to the customer file), and success_count
(the number of users who have successfully added) return. Make sure that request_count
may differ from success_count
depending on situations.
If the number of users you requested to add to the customer file is different from the number of users who have successfully added, check the followings: - You can only add the users who have added your Kakao Talk Channel as a friend to the customer file. - If 'user_type' is set to 'app', the value of 'id' must be a service user ID that has been issued through Kakao Login. To do so, the user must be linked to your service through a Kakao Account. -If 'user_type' is set to 'phone', the value of 'id' must be the phone number used to sign up for Kakao Talk.
POST /v1/talkchannel/update/target_users HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${REST_API_KEY}
Content-Type: application/json
Name | Type | Description | Required |
---|---|---|---|
file_id | Integer |
File ID. | O |
channel_public_id | String |
Kakao Talk Channel ID. | O |
user_type | String |
Type of ID to be used to identify a user.app or phone app : service user ID of Kakao Account.phone : mobile phone number registered in Kakao Talk. |
O |
users | JSON[] |
A list of users to be added to a customer file, including IDs and schemas. | O |
Name | Type | Description | Required |
---|---|---|---|
id | String |
User ID in the customer file. | O |
field | JSON |
Values for the predefined schema in key-value format. NOTE: Only Number types are allowed for the value. String type value must be transferred to the Number type value by referring to a notice in Kakao Talk Channel Admin Center. |
O |
Name | Type | Description |
---|---|---|
file_id | Integer |
File ID. |
request_count | Integer |
Number of users you requested to add to the customer file. |
success_count | Integer |
Number of users who have successfully added to the customer file. |
curl -v -X POST "https://kapi.kakao.com/v1/talkchannel/update/target_users" \
-H "Authorization: KakaoAK ${REST_API_KEY}" \
-H "Content-Type: application/json" \
--data-urlencode '{
"file_id": 437,
"channel_public_id": "_ZeUTxl",
"user_type": "app",
"users": [
{
"id": "12345",
"field" : {
"생년월일": "2000-01-01",
"성별": "남자",
"age": 19
}
},
...
]
}'
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"file_id": 437,
"request_count": 10,
"success_count": 9
}
You can delete a specific user from one of your customer files registered in the Kakao Talk Channel. Even though your request succeeds, no response returns. See the HTTP status code to check if it succeeds.
POST /v1/talkchannel/delete/target_users HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${REST_API_KEY}
Content-Type: application/json
Name | Type | Description | Required |
---|---|---|---|
file_id | Integer |
File ID. | O |
channel_public_id | String |
Kakao Talk Channel ID. | O |
user_type | String |
Type of ID to be used to identify a user.app or phone app : service user ID of Kakao Account.phone : mobile phone number registered in Kakao Talk. |
O |
user_ids | JSON[] |
A list of users to be deleted from a customer file. | O |
curl -v -X POST "https://kapi.kakao.com/v1/talkchannel/delete/target_users" \
-H "Authorization: KakaoAK ${REST_API_KEY}" \
-H "Content-Type: application/json" \
--data-urlencode '{
"file_id" : 437,
"channel_public_id" : "_ZeUTxl",
"user_type" : "app"
"user_ids" : ["12345"]
}'
HTTP/1.1 200 OK
Content-Length: 0
Content-type: application/json;charset=UTF-8