페이지 이동경로
  • Docs>
  • Kakao Talk Social>
  • REST API

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

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. To see the difference of profile information between Kakao Talk and Kakao Account, refer to Understand 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

Key

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

countryISO

As of June 1, 2021, the 'countryISO' field (Country where a user is using Kakao Talk) is removed from the response of the Retrieving Kakao Talk profile API. Refer to DevTalk for more details.

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 failed because the user has not agreed to provide Friends List in Kakao Service(Including profile image, nickname, and favorites), 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)'.

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

Key
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
profile_nickname String Friend's profile nickname. X
profile_thumbnail_image String Friend's profile thumbnail image.
Only HTTPS is supported.
X
id Long Service user ID. O
uuid String User's unique ID used to send a Kakao Talk message. O
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