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].

REST API Test Tooloutlink

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
-	Register platforms Activate Kakao Login Manage consent items	Required	Required: Profile Info(nickname/profile image) Nickname Profile image

This API enables you to get the Kakao Talk profile of the user currently logged in. Note that Kakao Talk profiles may be different from Kakao Account profiles. Refer to Concepts.

Include the access token in the request header, and make a GET request. The response is returned in JSON format. If a user's Kakao Account is not linked to Kakao Talk, an error returns.

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
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.

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
{
  "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
{
  "nickName":"Ryan"
}

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

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "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	Register platforms Activate Kakao Login Manage consent items	Required	Required: Friends List in Kakao Service(Including profile image, nickname, and favorites)

This API enables you to get the friends added in Kakao Talk account linked to the Kakao Account of the user currently logged in.

Include the access token in the request header, and make a GET request. You can also add optional parameters for sort order, the number of friends to be retrieved on a page, and so on.

If the request is successful, a list of friends is returned in JSON format. If the number of Kakao Talk friends is over limit, the results are returned through multiple pages. To get another list of friends on the next page, it would be better to send a GET request with after_url passed in the response and the same access token used when you requested the list of friends, rather than specifying other optional parameters.

If the request fails because the user has not agreed to provide the Friends list, proceed the followings:

• Check if 'Friends List in Kakao Service(Including profile image, nickname, and favorites)' is set to 'Consent during use' in Consent items.
• Request additional consent to the 'Friends List in Kakao Service(Including profile image, nickname, and favorites)' scope.

To see errors you may encounter when calling the Retrieving list of friends API, refer to DevTalk.

Notice: Sort order of friends list

You can set the order of friends list by setting the order parameter. In the case of asc, set as a default, the sort order complies with the following priority depending on the language settings. desc follows the opposite sort order to asc:

• Korean: Sorted first by Korean, special characters, numbers, English, Japanese, and emoji order.
• English: Sorted first by special characters, numbers, English, Japanese, and emoji order. Basically, the friends are sorted with the Korean priority above. However, if you make a request by specifying language information through the Kakao SDK, the friends are sorted with the English priority.

You can also use friend_order with order for the sort order of friends. If you set friend_order to favorite, the sort order above also applies to the favorite friends. For example, if friend_order is set to favorite and order is set to asc, a user's favorite friends come first sorted with the same priority above, and then the rest of friends are sorted as listed above. If you want to sort friends in ascending order of nicknames regardless of the staus of favorites, set order to asc, and friend_order to nickname.

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
}

See more

• Reference for REST API