Kakao Talk Channel

REST API

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

Check Kakao Talk Channel relationship

Basic information

Method	URL	Authorization
`GET`	`https://kapi.kakao.com/v2/api/talk/channels`	Access token Service app admin key

Permission	Prerequisite	Kakao Login	User consent
Required	Admin key Activate Kakao Login Manage consent items Set Kakao Talk Channel	Required	Required: Kakao Talk Channel addition status and details

Checks whether a specific user has added or blocked your Kakao Talk Channel connected to your service app.

Providing a new API

We provide the v2 version for checking Kakao Talk Channel relationship API. You can find information of the v1 API in a separate document.

Kakao Talk Channel webhook

To get a notification when a user adds or blocks one of your Kakao Talk Channels linked to you service, use the Kakao Talk Channel webhook function.

Send a GET request with the access token in the header. If you are an administrator, you can also use the app's Admin key to request. Make sure to use the app's Admin key only in the server.

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.

If an error occurs because the user did not consent to the consent item, you can request consent from the user again by Requesting additional consent as needed.

Request: Using access token

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` Access token as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
channel_ids	`String`	List of Kakao Talk Channel profile IDs that you want to check the relationship with a user. A comma-seperated string. (Example: `_Bxkd,_RQxl,_vxfxm`)	O
channel_id_type	`String`	A type of the Kakao Talk Channel profile ID. Fixed to `channel_public_id`.	X

Request: Using Service app admin key

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` Service app admin key as a type of user authentication.	O
Content-Type	`Content-Type: application/x-www-form-urlencoded;charset=utf-8` The data type of the request.	O

Query parameter

Name	Type	Description	Required
target_id_type	`String`	A type of the user ID. Fixed to `user_id`.	O
target_id	`Long`	Service user ID.	O
channel_ids	`String`	List of Kakao Talk Channel profile IDs that you want to check the relationship with a user. A comma-seperated string. (Example: `_Bxkd,_RQxl,_vxfxm`)	O
channel_id_type	`String`	A type of the Kakao Talk Channel profile ID. Fixed to `channel_public_id`.	X

Response

Body

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 profile ID for search purpose.	O
channel_public_id	`String`	Kakao Talk Channel profile ID.	O
relation	`String`	Relationship between a Kakao Talk Channel and a user. `ADDED`: a user has added the channel. `BLOCKED`: a user has blocked the channel. `NONE`: a user has not either added or blocked the channel.	O
created_at	`Datetime`	Time when a Kakao Talk Channel is added in UTC*. Only returned if a Kakao Talk Channel is added (`ADDED`).	X
updated_at	`Datetime`	Time when a Kakao Talk Channel relationship is changed 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/v2/api/talk/channels" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "channel_ids=_frxjem,_xnrxjem,_Brxjem"

Request: Using admin key

curl -v -G GET "https://kapi.kakao.com/v2/api/talk/channels" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "target_id_type=user_id" \
  -d "target_id=${USER_ID}" \
  -d "channel_ids=_frxjem,_xnrxjem,_Brxjem"

Response: Success

HTTP/1.1 200 OK
{
  "user_id": ${USER_ID},
  "channels": [
    {
      "channel_uuid": "@테스트",
      "channel_public_id": "_ZeUTxl",
      "relation": "ADDED", // One of ADDED, BLOCKED, NONE
      "created_at": "2020-04-18T03:17:05Z", // Only returned when "relation" is "ADDED".
      "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
}

Check multiple users' Kakao Talk Channel relationship

Basic information

Method	URL	Authorization
`GET`	`https://kapi.kakao.com/v2/api/talk/channels/multi`	Service app admin key

Permission	Prerequisite	Kakao Login	User consent
Required	Admin key Activate Kakao Login Manage consent items Set Kakao Talk Channel	Required	Required: Kakao Talk Channel addition status and details

Checks whether specific users have added or blocked your Kakao Talk Channel connected to your service app.

Kakao Talk Channel webhook

To get a notification when a user adds or blocks one of your Kakao Talk Channels linked to you service, use the Kakao Talk Channel webhook function.

You may use this API to check the relationship between your Kakao Talk Channel and a group or all of the users.

Send a GET request with the Service app admin key in the header. Using query parameters, you must pass a service user ID list and a Kakao Talk Channel profile ID list. You can check up to 200 users.

If the request is successful, the response includes the relationship information of each user. The response does not include the user's information that failed to check.

Request

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` Service app admin key as a type of user authentication.	O
Content-Type	`Content-Type: application/x-www-form-urlencoded;charset=utf-8` The data type of the request.	O

Query parameter

Name	Type	Description	Required
target_id_type	`String`	A type of the user ID. Fixed to `user_id`.	O
target_ids	`Long`	A list of service user ID. A comma seperate string.	O
channel_id_type	`String`	A type of the Kakao Talk Channel profile ID. Fixed to `channel_public_id`.	X
channel_ids	`String[]`	List of Kakao Talk Channel profile IDs that you want to check the relationship with a user. A comma seperate string. (Default: A list of all Kakao Talk Channel profile IDs that connected to your service app)	X

Response

Body

이름	타입	설명	필수
-	`TalkChannelsResult[]`	The relationship information of each user.	O

TalkChannelsResult

Name	Type	Description	Required
user_id	`Long`	Service user ID.	O
channels	`Channels[]`	Kakao Talk Channel information.	X

TalkChannelRelation

Name	Type	Description	Required
channel_public_id	`String`	Kakao Talk Channel profile ID.	O
channel_uuid	`String`	Kakao Talk Channel profile ID for search purpose.	O
relation	`String`	Relationship between a Kakao Talk Channel and a user. `ADDED`: a user has added the channel. `BLOCKED`: a user has blocked the channel. `NONE`: a user has not either added or blocked the channel.	O
created_at	`Datetime`	Time when a Kakao Talk Channel is added in UTC*. Only returned if a Kakao Talk Channel is added (`ADDED`).	X
updated_at	`Datetime`	Time when a Kakao Talk Channel relationship is changed 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

curl -v -G GET "https://kapi.kakao.com/v2/api/talk/channels/multi" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "target_id_type=user_id" \
  -d "target_ids=${USER_ID_1},${USER_ID_2},${USER_ID_3}" \
  --data-urlencode 'channel_ids=_frxjem,_xnrxjem,_Brxjem'

Response

HTTP/1.1 200 OK
[
    {
        "user_id": ${USER_ID_1},
        "channels": [
            {
                "channel_public_id": "_xnrxjem",
                "channel_uuid": "@플러스친구",
                "relation": "ADDED",
                "created_at": "2022-11-09T07:08:48Z",
                "updated_at": "2023-07-20T07:21:05Z"
            }
        ]
    }, {
        "user_id": ${USER_ID_2},
        "channels": [
            {
                "channel_public_id": "_xnrxjem",
                "channel_uuid": "@플러스친구",
                "relation": "NONE"
            }
        ]
    },
    ...
]

Response: Excepted for the user that failed to check

HTTP/1.1 200 OK
[
    {
        "user_id": ${USER_ID_1},
        "channels": [
            {
                "channel_public_id": "_xnrxjem",
                "channel_uuid": "@플러스친구",
                "relation": "ADDED",
                "created_at": "2022-11-09T07:08:48Z",
                "updated_at": "2023-07-20T07:21:05Z"
            }
        ]
    }
]

Customer management: Register customer file

Basic information

Method	URL	Authorization
`POST`	`https://kapi.kakao.com/v1/talkchannel/create/target_user_file`	REST API key Service app admin key

Permission	Prerequisite	Kakao Login	User consent
-	REST API key Admin key Set for customer management	-	-

Creates a new customer file.

Define the new file name in file_name and the filtering criteria in schema. Note that the defined Schema cannot be modified later.

If the new customer file is successfully created, the file ID registered as file_id is returned. The file ID is used when adding or removing users from the file.

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

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${APP_KEY}` REST API key or Service app admin key as a type of user authentication.	O

Body

Name	Type	Description	Required
channel_public_id	`String`	Kakao Talk Channel profile 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

Body

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 ${APP_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

Basic information

Method	URL	Authorization
`GET`	`https://kapi.kakao.com/v1/talkchannel/target_user_file`	REST API key Service app admin key

Permission	Prerequisite	Kakao Login	User consent
-	REST API key Admin key Set for customer management	-	-

Retrieves 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

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${APP_KEY}` REST API key or Service app admin key as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
channel_public_id	`String`	Kakao Talk Channel profile ID.	O

Response

Body

Name	Type	Description
empty_slot	`Integer`	The number of available slots.
using_slot	`Integer`	The number of using slots.
results	`Results[]`	Information of each customer file registered for the Kakao Talk Channel.

Result

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 ${APP_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

Basic information

Method	URL	Authorization
`POST`	`https://kapi.kakao.com/v1/talkchannel/update/target_users`	REST API key Service app admin key

Permission	Prerequisite	Kakao Login	User consent
-	REST API key Admin key Set for customer management	-	-

Adds 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?

he 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

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${APP_KEY}` REST API key or Service app admin key as a type of user authentication.	O

Body

Name	Type	Description	Required
file_id	`Integer`	File ID.	O
channel_public_id	`String`	Kakao Talk Channel profile 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 Partner Center.	O

Response

Body

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 ${APP_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

Basic information

Method	URL	Authorization
`POST`	`https://kapi.kakao.com/v1/talkchannel/delete/target_users`	REST API key Service app admin key

Permission	Prerequisite	Kakao Login	User consent
-	REST API key Admin key Set for customer management	-	-

Deletes 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

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${APP_KEY}` REST API key or Service app admin key as a type of user authentication.	O

Body

Name	Type	Description	Required
file_id	`Integer`	File ID.	O
channel_public_id	`String`	Kakao Talk Channel profile 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 ${APP_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

사이드 메뉴

Getting started

Kakao Developers

Login

Communication

Kakao Map

Navigation

Advertisement

Search

More

REST API

Check Kakao Talk Channel relationship

Basic information

Request: Using access token

Header

Query parameter

Request: Using Service app admin key

Header

Query parameter

Response

Body

Channels

Sample

Request: Using access token

Request: Using admin key

Response: Success

Response: Fail, if requesting for a non-Kakao Talk user

Check multiple users' Kakao Talk Channel relationship

Basic information

Request

Header

Query parameter

Response

Body

TalkChannelsResult

TalkChannelRelation

Sample

Request

Response

Response: Excepted for the user that failed to check

Customer management: Register customer file

Basic information

Constraints: Schema

Request

Header

Body

Response

Body

Sample

Request

Response

Customer management: View customer file

Basic information

Request

Header

Query parameter

Response

Body

Result

Sample

Request

Response

Customer management: Add user

Basic information

Request

Header

Body

users

Response

Body

Sample

Request

Response

Customer management: Delete user

Basic information

Request

Header

Body

Sample

Request