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 Admin key

Requirements		See also
Kakao login usage setting Register redirect URI	Set consent items: `plusfriends` Connect Kakao Talk Channel to app	Error code

Returns the relationship between the current user and Kakao Talk Channels connected to your 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.

Request user consent

If an error occurs because the user has not consented to the Kakao Talk Channel addition status and details consent item, use Request additional consent to request consent.

Request: Using access token

Header

Name	Description	Required
Authorization	Access token as a type of user authentication. `Authorization: Bearer ${ACCESS_TOKEN}`	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-separated string. (Example: `_Bxkd,_RQxl,_vxfxm`, Default: all Kakao Talk Channel profile IDs linked to the app)	X
channel_id_type	`String`	`channel_ids` type, fixed to `channel_public_id`.	X

Request: Using Service app admin key

Header

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

Query parameter

Name	Type	Description	Required
target_id_type	`String`	`target_id` type, 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-separated string. (Example: `_Bxkd,_RQxl,_vxfxm`, Default: all Kakao Talk Channel profile IDs linked to the app)	X
channel_id_type	`String`	`channel_ids` type, 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	`Enum`	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 RFC3339 format based on 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 RFC3339 format based on UTC). Only returned if a Kakao Talk Channel is added (`ADDED`) or blocked (`BLOCKED`).	X

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": 1234567890, // ${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`	Admin key

Requirements		See also
Kakao login usage setting Register redirect URI	Set consent items: `plusfriends` Connect Kakao Talk Channel to app	Error code

Returns the relationships between multiple users and Kakao Talk Channels connected to your 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.

Request

Header

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

Query parameter

Name	Type	Description	Required
target_id_type	`String`	`target_ids` type, fixed to `user_id`.	O
target_ids	`Long`	A comma-separated list of service user IDs (Maximum: 200 users).	O
channel_id_type	`String`	`channel_ids` type, 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-separated string. (Default: A list of all Kakao Talk Channel profile IDs that connected to your service app)	X

Response

Body

Name	Type	Description	Required
-	`TalkChannelsResult[]`	Relationship information for each user. Users whose relationship could not be checked are excluded.	O

TalkChannelsResult

Name	Type	Description	Required
user_id	`Long`	Service user ID.	O
channels	`TalkChannelRelation[]`	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	`Enum`	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 RFC3339 format based on 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 RFC3339 format based on UTC). Only returned if a Kakao Talk Channel is added (`ADDED`) or blocked (`BLOCKED`).	X

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": 1234567890, // ${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": 2345678901, // ${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": 1234567890, // ${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 Admin key

Requirements	See also
Customer management API policy agreement	Error code

Registers a new customer file.

Conditions for use

Define the new file name in file_name and filtering criteria in schema.
A defined schema cannot be edited.
The file ID (file_id) returned after registration is used to add or remove 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	REST API key or Service app admin key as a type of user authentication. `Authorization: KakaoAK ${APP_KEY}`	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 Admin key

Requirements	See also
Customer management API policy agreement	Error code

Returns customer file information registered for a Kakao Talk Channel.

Request

Header

Name	Description	Required
Authorization	REST API key or Service app admin key as a type of user authentication. `Authorization: KakaoAK ${APP_KEY}`	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	`Enum`	File status `using`: In use `deleting`: Deleting `failed`: 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 Admin key

Requirements	See also
Customer management API policy agreement	Error code

Adds user information to the customer file.

Note: What to check if some users are not added to the customer file

Invalid user information and the following cases can prevent users from being added, so the requested and successfully added user counts may differ:

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	REST API key or Service app admin key as a type of user authentication. `Authorization: KakaoAK ${APP_KEY}`	O

Body

Name	Type	Description	Required
file_id	`Integer`	File ID.	O
channel_public_id	`String`	Kakao Talk Channel profile ID.	O
user_type	`Enum`	Type of ID to be used to identify a user. `app`: service user ID of Kakao Account. `phone`: mobile phone number registered in Kakao Talk.	O
users	`User[]`	A list of users to be added to a customer file, including IDs and schemas (Maximum: 2,000 users).	O

User

Name	Type	Description	Required
id	`String`	User ID. Pass a service user ID or Kakao Talk phone number according to `user_type`.	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 Admin key

Requirements	See also
Customer management API policy agreement	Error code

Deletes a specific user from one of your customer files registered in the Kakao Talk Channel.

Request

Header

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

Body

Name	Type	Description	Required
file_id	`Integer`	File ID.	O
channel_public_id	`String`	Kakao Talk Channel profile ID.	O
user_type	`Enum`	Type of ID to be used to identify a user. `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

Map

Navigation

Advertisement

Search

More

REST API

Check Kakao Talk Channel relationship

Basic information

Request user consent

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

Conditions for use

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

Note: What to check if some users are not added to the customer file

Request

Header

Body

User

Response

Body

Sample

Request

Response

Customer management: Delete user

Basic information

Request

Header