kakao developers

JavaScript

This document describes how to integrate Kakao Talk Social APIs into your service with the Kakao SDK for JavaScript (hereinafter referred to as 'JavaScript SDK').

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.

Before you begin

Install SDK

Import the JavaScript SDK into your web page and initialize it by referring to Getting Started > JavaScript.

Register Web Platform

To use the JavaScript SDK, you must register the Web platform in advance. Go to [My Application] > [Platform] and register your site domains.

Implement Kakao Login

To use the Kakao Talk Social APIs,

• You must implement Kakao Login beforehand.
• A user has been logged in with a Kakao Account to get tokens.

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.

Call the Kakao.API.request() function, and set url to /v1/api/talk/profile to request Kakao Talk profile.

Kakao.API.request() returns Promise. If the promise is fulfilled, the Kakao Talk profile information is returned. For the detailed response fields, refer to REST API > Retrieve Kakao Talk profile.

Parameter

Name	Type	Description	Required
url	String	Fixed as '/v1/api/talk/friends'.	O

Sample

Kakao.API.request({
  url: '/v1/api/talk/profile',
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

Retrieve friends through picker Login requiredConsent required

This API displays the Friend picker and provides the information of the Kakao Talk friends that a user selects through the picker.

• The JavaScript SDK only supports the full screen type of picker, while the Android and iOS SDK provides both the popup and full screen format of picker.
• To see the supported web browser, refer to Supported web browser.

To use this API,

• You must enable the 'Friends List in Kakao Service(Including profile image, nickname, and favorites)' scope in [My Application] > [Kakao Login] > [Consent items].
• A user must consent to the 'Friends List in Kakao Service(Including profile image, nickname, and favorites)' scope.

Implementation method for picker

You can implement the picker with two methods:

• Popup method
  • The picker appears as the popup window.
  • The selected friends data is returned through Promise.
• Redirect method
  • The picker appears on the current window. 
  • The information about the selected friends is passed to the returnUrl of your service server as a query string through redirection (HTTP 302 Redirect).
  • For this, you must register the domain of returnUrl in [My Appliction] > [Platform] > [Web].

Depending on the selection type of the Friend picker, you need to use a different function.

Function type

Number of selectable friends	Function to use
Only one friend (Single picker)	selectFriend()
Multiple friends (Multi-picker)	selectFriends()

Parameter

Name	Type	Description	Required
title	String	Text to be displayed in the title area of the Friend picker. (Default: "Select Friends")	X
enableSearch	Boolean	Whether to show the Search box for friends. (Default: true)	X
showMyProfile	Boolean	Whether to show my profile. It set to true, users can also select their own profile. (Default: true)	X
showFavorite	Boolean	Whether to show the friends added as Favorite. (Default: true)	X
showPickedFriend	Boolean	Only for the multi-picker. Whether to show the selected friends. (Default: true)	X
maxPickableCount	Number	Only for the multi-picker. Maximum number of the seletable friends. This value must be greater than or equal to minPickableCount. (Default: 30, Maximum: 100)	X
minPickableCount	Number	Only for the multi-picker. Minimum number of the seletable friends. This value must be less than or equal to minPickableCount. (Default: 1, Maximum: 100)	X
returnUrl	String	Required when implementing with the redirect method. Service URL that the information of the selected friends are passed to. IMPORTANT: Only allowed the domain registered in [My Appliction] > [Platform] > [Web].	X
enableBackButton	Boolean	Only for the redirect method Whether to show the back (←) button. - true: the Back button displayed. - false: the Back button no displayed. (Default: true)	X

Sample

// Pop-up method
Kakao.Picker.selectFriends({
  title: 'Select friends',
  maxPickableCount: 10,
  minPickableCount: 1,
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

// Redirect method
// Success: ${returnUrl}?selected=${SelectedUsers}
// Fail: ${returnUrl}?error=${Error}
Kakao.Picker.selectFriends({
  returnUrl: 'https://developers.kakao.com', // Required
  title: 'Select friends',
  maxPickableCount: 10,
  minPickableCount: 1,
});

Response

If the promise is fulfilled, the information of the friends that a user selects from the Friend picker is returned through SelectedUsers.

SelectedUsers: Selected friends data

Name	Type	Description	Required
selectedTotalCount	Number	Number of friends who a user selected on the Friend picker. Refer to If the number of friends passed in response is less than the number of selected friends.	O
users	SelectedUser[]	List of friends data that is passed in the response. Refer to SelectedUser.	X

SelectedUser: Each friend data

Name	Type	Description	Required
uuid	String	User's unique ID used to identify users in a service and used to send a Kakao Talk message. This value may change if a user deletes and then re-creates the Kakao Talk account.	O
id	String	Friend's service user ID. Only the friends who are linked to the app have a service user ID.	X
profile_nickname	String	Friend's profile nickname set in Kakao Talk.	X
profile_thumbnail_image	String	Friend's profile thumbnail image set in Kakao Talk.	X
favorite	Boolean	Whether the friend is added as Favorite.	X

Error

If the request is failed, error code and message are returned. To check its cause and solution, refer to Troubleshooting.

Name	Type	Description	Required
code	Number	Error code.	O
msg	String	Error message.	O

NOTE: If the number of friends passed in response is less than the number of selected friends

The total count of friends a user selected (selectedTotalCount) on the multi-picker may differ from the number of friends passed in the response (SelectedUser).

• Example case: a user A selects the user's friend B on the Friend picker. → Before the request to retrieve friends on the Friend picker is completed, B unlinks from the app. → A selects [Ok] on the Friend picker to request the friend data.
• Result: B who selected on the Friend picker is counted as selectedTotalCount but not included in the response to the request of the friend information.
• For this case, you must notify users that the retrieved friend data is less than the number of friends they selected, considering users' better experience.

Retrieve list of friends Login required Consent required

You can get the list of Kakao Talk friends of the user currently logged in. You can also add optional parameters for sort order, the number of friends to be retrieved on a page, and so on.

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.

Call the Kakao.API.request() function, and set url to /v1/api/talk/friends to request Kakao Talk friends information.

Kakao.API.request() returns Promise. If the promise is fulfilled, a list of friends is returned. For the detailed response fields, refer to REST API > Retrieve list of friends.

If the promise is rejected 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.

Parameter

Name	Type	Description	Required
url	String	Fixed as '/v1/api/talk/friends'.	O
data	Object	Object that contains the parameters to be passed when requesting the API.	X

data: Retrieving list of friends

Name	Type	Description	Required
offset	Number	Offset value that the list of friends starts from. (Default: 0)	X
limit	Number	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	You can sort friends in the list by nickname (Kakao Talk nickname) or favorite (favorite friends). (Default: favorite)	X

Sample

Kakao.API.request({
  url: '/v1/api/talk/friends',
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

See more

• Download JavaScript SDK
• API Reference for JavaScript →
• JavaScript SDK Demo →

Legacy

• Kakao Talk Social for JavaScript SDK v1