kakao developers

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

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,

• Set the Kakao Talk Channel addition status and details scope to 'Required consent' or 'Optional consent' in [My Application] > [Kakao Login] > [Consent items].
• A user must consent to the scope. Otherwise, an error occurs. In this case, you can request additional consent from the user.

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:

• If you do not enable Kakao Talk Channel addition status and details in [My Application] > [Kakao Login] > [Consent Items].
• If you set 'Kakao Talk Channel addition status and details' to 'Optional item', a user may not consent to the consent item. In this case, you can request consent from the user again by Requesting additional consent as needed.

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.

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

• Reference for REST API