페이지 이동경로
  • Docs>
  • Kakao Talk Channel>
  • REST API

Kakao Talk Channel

REST API

This document describes how to integrate Kakao Talk Channel APIs into your service with a REST API.

Tag used in this document
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.

Check Kakao Talk Channel relationship Login required Consent required

IMPORTANT: Providing a new 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:

Request: Using access token

URL
GET /v1/api/talk/channels HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Description Required
Authorization Access token as a type of user authentication.
Authorization: Bearer ${ACCESS_TOKEN}
O
Parameter
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

Request: Using admin key

URL
GET /v1/api/talk/channels HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${APP_ADMIN_KEY}
Header
Name Description Required
Authorization Admin key as a type of user authentication.
Authorization: KakaoAK ${APP_ADMIN_KEY}
O
Parameter
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

Response

Name Type Description Required
user_id Long Service user ID. O
channels Channels[] Kakao Talk Channel information. X
Channels
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.

Sample

Request: Using access token
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"]'
Request: Using admin key
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"]'
Response: Success
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".
    ...
  ]
}
Response: Fail, if requesting for a non-Kakao Talk user
HTTP/1.1 400 Bad Request
{
    "msg": "given account is not connected to any talk user.",
    "code": -501
}

Customer management: Register customer file

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.

Constraints: Schema

When you register a customer file through this API, you must follow the schema rules:

  • You must use the supported keys in Korean if the customer information is a string.
  • When assigning a new key, "앱유저아이디" and "전화번호" are not allowed. Only Number types are allowed for the value.
  • A schema can contain up to 30 items.

Request

URL
POST /v1/talkchannel/create/target_user_file HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${REST_API_KEY}
Content-Type: application/json
Parameter
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

Response

Name Type Description
file_id Integer ID of the customer file that has been created.

Sample

Request
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"
        }
    }'
Response
HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
  "file_id" : 437
}

Customer management: View customer file

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.

Request

URL
GET /v1/talkchannel/target_user_file HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${REST_API_KEY}
Content-Type: application/json
Parameter
Name Type Description Required
channel_public_id String Kakao Talk Channel ID. O

Response

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.

Sample

Request
curl -v -G GET "https://kapi.kakao.com/v1/talkchannel/target_user_file" \
    -H "Authorization: KakaoAK ${REST_API_KEY}" \
    -d "channel_public_id=_ZeUTxl"
Response
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
}

Customer management: Add user

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.

What if some users are not added to the customer file?

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.

Request

URL
POST /v1/talkchannel/update/target_users HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${REST_API_KEY}
Content-Type: application/json
Parameter
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
users
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

Response

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.

Sample

Request
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
                }
            },
            ...
        ]
    }'
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
 "file_id": 437,
 "request_count": 10,
 "success_count": 9
}

Customer management: Delete user

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.

Request

URL
POST /v1/talkchannel/delete/target_users HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${REST_API_KEY}
Content-Type: application/json
Parameter
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

Sample

Request
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"]
    }'
Response
HTTP/1.1 200 OK
Content-Length: 0
Content-type: application/json;charset=UTF-8

See more