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

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 specify a particular user and retrieve the Kakao Talk profile list as displayed to that user.

Retrieve Kakao Talk profile API and Retrieve Kakao Talk friends list API request each service user's profile and friends list using the user's authentication information. In contrast, this API allows a service administrator to retrieve service users' Kakao Talk profile information using the service Admin key.

If you pass the list of user IDs to retrieve in the request, the API returns each user's Kakao Talk profile list. If at least one user in the target list is not registered to the service, the API call fails and returns an error.

If a target user has set multi-profile, the profile information with multi-profile applied is returned. If the viewer and the target user are friends, the profile information (Nickname, Image) displayed to the viewer is returned. The information returned as nickname and profile image URL follows Criteria for providing profile information.

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