페이지 이동경로
  • 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.

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 Register platforms
Activate Kakao Login
Manage consent items
Set Kakao Talk Channel		 Required Required:
Kakao Talk Channel addition status and details
IMPORTANT: 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.

Note

To get an alarm when a user adds or blocks your Kakao Talk Channel, use Kakao Talk Channel callback.

This API enables you to check if a specific user has added or blocked your Kakao Talk Channel connected to your service app.

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.
(EX: _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
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.
(EX: _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 Register platforms
Activate Kakao Login
Manage consent items
Set Kakao Talk Channel		 Required Required:
Kakao Talk Channel addition status and details

Note

To get an alarm when a user adds or blocks your Kakao Talk Channel, use Kakao Talk Channel callback.

This API enables you to check if specific users have added or blocked your Kakao Talk Channel connected to your service app. 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
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
Permission Prerequisite Kakao Login User consent
- Set for customer management - -

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

Header
Name Description Required
Authorization Authorization: KakaoAK ${REST_API_KEY}
REST API 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 ${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

Basic information
Method URL Authorization
GET https://kapi.kakao.com/v1/talkchannel/target_user_file REST API key
Permission Prerequisite Kakao Login User consent
- Set for customer management - -

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

Header
Name Description Required
Authorization Authorization: KakaoAK ${REST_API_KEY}
REST API 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 ${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

Basic information
Method URL Authorization
POST https://kapi.kakao.com/v1/talkchannel/update/target_users REST API key
Permission Prerequisite Kakao Login User consent
- Set for customer management - -

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

Header
Name Description Required
Authorization Authorization: KakaoAK ${REST_API_KEY}
REST API 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 Admin 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 ${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

Basic information
Method URL Authorization
POST https://kapi.kakao.com/v1/talkchannel/delete/target_users REST API key
Permission Prerequisite Kakao Login User consent
- Set for customer management - -

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

Header
Name Description Required
Authorization Authorization: KakaoAK ${REST_API_KEY}
REST API 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 ${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

Kakao Talk Channel> REST API