kakao developers

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

Tag used in this document

Tag	Description
Login required	The API marked with this tag requires Kakao Login. You must implement the Kakao Login function first, and then call the corresponding API by using the access token issued when a user logs in.
Consent required	To use the API marked with this tag, you must enable a specific scope required for the corresponding API. In addition, a user must also consent to the scope. Otherwise, an error occurs or empty value is returned. To check which scopes a user has consented to, you can call the Retrieving consent details API.

Retrieve Kakao Talk profile Login required Consent required

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.

To use this API,

• You must enable the 'Profile' scope in [My Application] > [Kakao Login] > [Consent items].
• A user must consent to the scope. Otherwise, an empty value is returned.

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

URL

GET /v1/api/talk/profile HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

Response

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

Sample

Request

curl -v -X 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 Login required Consent required

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

To use this API,

1. Get permission. Before permission is granted to your app, you can call this API only for the team members.
2. Enable the 'Friends List in Kakao Service(Including profile image, nickname, and favorites)' scope in [My Application] > [Kakao Login] > [Consent items]. A user must also consent to the scope. To see more about the conditions for providing friend information, refer to Usage policy.

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

URL

GET /v1/api/talk/friends HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

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

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

elements

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

* Deprecated 'allowed_msg' that indicates whether or not the friend allows to receive Kakao Talk messages from the app as Profile visibility option is provided. For more details, refer to 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