Kakao Talk Social

REST API

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

You can test the features described in this document in [Tools] > [REST API Test].

Retrieve Kakao Talk profile

Basic information

Method	URL	Authorization
`GET`	`https://kapi.kakao.com/v1/api/talk/profile`	Access token

Permission	Prerequisite	Kakao Login	User consent
-	Activate Kakao Login Manage consent items	Required	Required: Profile Info(nickname/profile image) Nickname Profile image

Retrieves Kakao Talk profile information linked to the Kakao Account of the logged-in user.

Kakao Talk profile and Kakao Account profile

You can check the types and differences of user profiles available through the Kakao API in User profile.

Request

Header

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

Response

Body

Name	Type	Description	Required
id	`Long`	Service user ID.	O
nickName	`String`	Kakao Talk nickname. Required user consent: Profile Info(nickname/profile image) or Nickname	X
profileImageUrl	`String`	Kakao Talk profile image URL with a size of 640x640 pixels. Only `HTTPS` is supported. Required user consent: Profile Info(nickname/profile image) or Profile image	X
thumbnailUrl	`String`	Kakao Talk profile thumbnail image URL with a size of 110x110 pixels. Only `HTTPS` is supported. Required user consent: Profile Info(nickname/profile image) or Profile image	X

* countryISO: Deprecated, refer to DevTalk for more details.

Providing separated scopes for profile information

From June 25, 2021, we provide the profile information separated as 'Nickname' and 'Profile image'. You can request consent to desired profile information by setting desired scopes respectively. If you create a new app, the separated scopes for profile information are applied to the app. If you have enabled the 'Profile Info(nickname/profile image)' scope, you can continue to use that scope. In this case, you do not need to change the app settings, and there is no change in API response. But if you want to use the new scpes in the existing app, fill out the request form. In this case, the API response may change. Refer to Notice for more details.

Sample

Request

curl -v -G GET "https://kapi.kakao.com/v1/api/talk/profile" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Response: Success, if user consents to 'Profile Info(nickname/profile image)'

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "id": 1234567,
  "nickName":"Ryan",
  "profileImageURL":"https://xxx.kakao.co.kr/.../aaa.jpg",
  "thumbnailURL":"https://xxx.kakao.co.kr/.../bbb.jpg"
}

Response: Success, if user consents to 'Nickname' only

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "id": 1234567,
  "nickName":"Ryan"
}

Response: Success, if user consents to 'Profile image' only

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "id": 1234567,
  "profileImageURL":"https://xxx.kakao.co.kr/.../aaa.jpg",
  "thumbnailURL":"https://xxx.kakao.co.kr/.../bbb.jpg"
}

Response: Success, if user consents to none of required consent items

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{}

Response: Fail, If user's Kakao Account is not linked to Kakao Talk

HTTP/1.1 400 Bad Request
{
  "msg": "given account is not connected to any talk user.",
  "code": -501
}

Retrieve list of friends

Basic information

Method	URL	Authorization
`GET`	`https://kapi.kakao.com/v1/api/talk/friends`	Access token

Permission	Prerequisite	Kakao Login	User consent
Required	Activate Kakao Login Manage consent items	Required	Required: Friends List in Kakao Service(Including profile image, nickname, and favorites)

Retrieves Kakao Talk friend information linked to the Kakao Account of the logged-in user.

Note: User consent

If the request fails because the user did not agree to provide the Kakao Talk friends list, request again after obtaining user consent by referring to the below.

Check whether [Friends list in Kakao services] is set to use in Consent item.
Obtain user consent for 'Friends list in Kakao services' with Request additional consent API.

Note: Friend list sort order

The friend list is sorted in ascending order (asc) or descending order (desc) depending on the parameter (order). If the default sort order 'asc' is used, the detailed sort order is as below. If 'desc' is used, sorting is applied in the reverse order of the below.

Korean: Sorted in the order of Korean, special characters, numbers, English, Japanese, and emoji.
English: Sorted in the order of special characters, numbers, English, Japanese, Korean, and emoji.

By default, sorting is based on Korean, but if the language is set in the Kakao SDK, sorting is based on English. If you requested favorites-first sorting by setting friend_order to favorite, it is sorted in the order of favorite friends and then other friends, and the same detailed sort order is applied to each.

Request

Header

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

Query parameter

Name	Type	Discription	Required
offset	`Integer`	Offset value that the list of friends starts from. (Default: `0`)	X
limit	`Integer`	Maximum number of friends to be retrieved per page. (Maximum: `100`, Default: `10`)	X
order	`String`	Sort order of friends list. `asc` or `desc`. `asc`: Sort in ascending order. `desc`: Sort in descending order. (Default: `asc`)	X
friend_order	`String`	Sort option for the list of friends. `favorite`: Sort first by favorite friends. `nickname`: Sort by Kakao Talk nickname. (Default: `favorite`)	X

Response

Body

Name	Type	Description	Required
elements	`Friend[]`	A list of each friend's detailed information in `JSON` format.	X
total_count	`Integer`	Total number of Kakao Talk friends.	O
before_url	`String`	Previous page URL. If there is no previous page, `null` is returned.	X
after_url	`String`	Next page URL. If there is no next page, `null` is returned.	X
favorite_count	`Integer`	Number of friends added as `favorite`.	X

Friend

Name	Type	Description	Required
id	`Long`	Service user ID.	O
uuid	`String`	User's unique ID used to send a Kakao Talk message.	O
profile_nickname	`String`	Friend's profile nickname.	X
profile_thumbnail_image	`String`	Friend's profile thumbnail image. Only `HTTPS` is supported.	X
favorite	`Boolean`	Whether or not the friend is added as a favorite. `true`: Added as favorite. `false`: Not added as favorite.	X

* allowed_msg: Deprecated. Whether or not the friend allows to receive Kakao Talk messages. For more details, refer to Profile visibility option and DevTalk.

Sample

Request: List of three friends

curl -v -G GET "https://kapi.kakao.com/v1/api/talk/friends" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "limit=3"

Request: Next page of list of friends

curl -v -G GET "https://kapi.kakao.com/v1/api/talk/friends" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "offset=3" \
  -d "limit=3" \
  -d "order=asc"

Response: Success

HTTP/1.1 200 OK
{
    "elements": [
        {
            "profile_nickname": "Apeach",
            "profile_thumbnail_image": "https://xxx.kakao.co.kr/.../aaa.jpg",
            "id": 00000000001,
            "uuid": "abcdefg0001",
            "favorite": true
        },
        {
            "profile_nickname": "Ryan",
            "profile_thumbnail_image": "https://xxx.kakao.co.kr/.../bbb.jpg",
            "id": 00000000002,
            "uuid": "abcdefg0002",
            "favorite": false

        },
        {
            "profile_nickname": "Jordy",
            "profile_thumbnail_image": "https://xxx.kakao.co.kr/.../ccc.jpg",
            "id": 00000000003,
            "uuid": "abcdefg0003",
            "favorite": false
        }
    ],
    "total_count": 11,
    "after_url": "https://kapi.kakao.com/v1/api/talk/friends?offset=3&limit=3&order=asc",
    "favorite_count": 1
}

Response: Fail, If user's Kakao Account is not linked to Kakao Talk

HTTP/1.1 400 Bad Request
{
  "msg": "NotExistTalkUserException",
  "code": -501
}

Retrieve Kakao Talk profiles by user list

Basic information

Method	URL	Authentication
`GET/POST`	`https://kapi.kakao.com/v2/api/talk/profiles`	Service app admin key

Permission	Prerequisites	Kakao Login	Consent items
Required: Consent items	Admin key Activate Kakao Login Consent items	Required	Required: Profile information (Nickname/Profile image) Nickname Profile image

Retrieves the Kakao Talk profile list of service users.

You can also retrieve the Kakao Talk profile list that a specified user can view.

How Retrieve Kakao Talk profiles with user list API works

The API call fails if the request includes any user IDs in target_ids that are not registered.
If the request includes the reference user ID (viewer_id), it returns the profile information that the user can view.
The returned profile information follows Multi-profile display priority.

Request

Header

Name	Description	Required
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` Authentication method, requests authentication using the Service app admin key.	O
Content-Type	`Content-Type: application/x-www-form-urlencoded;charset=utf-8`. Request data type.	O

Query parameter

Name	Type	Description	Required
target_ids	`Long[]`	List of user IDs whose Kakao Talk profiles to retrieve.	O
target_id_type	`String`	`target_id` type, fixed to `user_id` (user ID).	O
viewer_id	`Long`	User ID used as the reference when retrieving Kakao Talk profiles. If `viewer_id` is not provided, only the Kakao Talk profiles of the users specified in `target_ids` are returned.	X
viewer_id_type	`String`	`viewer_id` type, fixed to `user_id` (user ID).	X

Response

Body

Name	Type	Description	Required
viewer	`TalkProfileInfo`	Kakao Talk profile information of the user corresponding to the requested `viewer_id`. Provided only when `viewer_id` is included in the parameters.	X
targets	`TalkProfileInfo[]`	Kakao Talk profile information list of the users specified in `target_ids`. Important: If the user is a friend of the `viewer_id` user, the multi-profile as displayed to that user is applied and returned.	O

TalkProfileInfo

Name	Type	Description	Required
user_id	`Long`	User ID, app-specific user unique ID assigned when a Kakao Account is linked to an app.	O
nickname	`String`	Kakao Talk profile nickname. Required consent items: Nickname, or Profile information (Nickname/Profile image).	X
profile_image	`String`	Kakao Talk profile image URL. Required consent items: Profile image, or Profile information (Nickname/Profile image).	X
thumbnail_image	`String`	Kakao Talk profile thumbnail image URL. Required consent items: Profile image, or Profile information (Nickname/Profile image). Note: Delete previous profile image URL on profile change.	X

Example

Request

curl -X GET "https://kapi.kakao.com/v2/api/talk/profiles" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
  -d "viewer_id=12345" \
  -d "viewer_id_type=user_id" \
  -d "target_ids=[9876,5432]" \
  -d "target_id_type=user_id"

Response: Success, when viewer_id is provided

HTTP/1.1 200 OK
{
  "viewer": {
    "user_id": 12345,
    "nickname": "xxx",
    "profile_image_url": "http://yyy.kakao.com/dn/.../img_640x640.jpg",
    "thumbnail_image_url": "http://yyy.kakao.com/.../img_110x110.jpg",
  },
  "targets": [
  {
    "user_id": 9876,
    "nickname": "yyy",
    "profile_image_url": "http://yyy.kakao.com/dn/.../img_640x640.jpg",
    "thumbnail_image_url": "http://yyy.kakao.com/.../img_110x110.jpg",
  },
  {
    "user_id": 5432,
    "nickname": "zzz",
    "profile_image_url": "http://yyy.kakao.com/dn/.../img_640x640.jpg",
    "thumbnail_image_url": "http://yyy.kakao.com/.../img_110x110.jpg",
  }
  ]
}

Response: Success, when only nickname consent item is set as required or the user consented only to nickname

HTTP/1.1 200 OK
{
  "targets": [
    {
      "user_id": 9876,
      "nickname": "yyy",
    },
  ]
}

Response: Failure, when viewer_id is not a registered user

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
  "code": -101,
  "msg": "NotRegisteredUserException"
}

Response: Failure, when at least one profile target user is not registered to the service

HTTP/1.1 400 Bad request
Content-Type: application/json;charset=UTF-8
{
  "code": -2,
  "msg": "invalid target_ids. can get the profile only to registered users."
}

See more

Reference for REST API

사이드 메뉴

Docs Home

Getting started

Kakao Developers

Login

Communication

Kakao Map

Navigation

Advertisement

Search

More

REST API

Retrieve Kakao Talk profile

Basic information

Kakao Talk profile and Kakao Account profile

Request

Header

Response

Body

Sample

Request

Response: Success, if user consents to 'Profile Info(nickname/profile image)'

Response: Success, if user consents to 'Nickname' only

Response: Success, if user consents to 'Profile image' only

Response: Success, if user consents to none of required consent items

Response: Fail, If user's Kakao Account is not linked to Kakao Talk

Retrieve list of friends

Basic information

Note: User consent

Note: Friend list sort order

Request

Header

Query parameter

Response

Body

Friend

Sample

Request: List of three friends

Request: Next page of list of friends

Response: Success

Response: Fail, If user's Kakao Account is not linked to Kakao Talk

Retrieve Kakao Talk profiles by user list

Basic information

How Retrieve Kakao Talk profiles with user list API works

Request

Header

Query parameter

Response

Body

TalkProfileInfo

Example

Request

Response: Success, when viewer_id is provided

Response: Success, when only nickname consent item is set as required or the user consented only to nickname

Response: Failure, when viewer_id is not a registered user

Response: Failure, when at least one profile target user is not registered to the service

See more

Was this helpful?

REST API

Retrieve Kakao Talk profile

Retrieve list of friends

Retrieve Kakao Talk profiles by user list

See more