Legacy JavaScript

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

Before you begin

Install SDK

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

Retrieve Kakao Talk profile

Basic information

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.

Call the Kakao.API.request() function, and set url to /v1/api/talk/profile to request Kakao Talk profile. You do not need to set the HTTP request header and other parameters because the JavaScript SDK v1 proceeds automatically and sends a request instead.

Parameter

Name	Type	Description	Required
url	String	Fixed as '/v1/api/talk/friends'.	O
success	Function(Object)	Callback function that gets invoked when the API request is successful.	X
fail	Function(Object)	Callback function that gets invoked if the API request is failed.	X
always	Function(Object)	Callback function that gets invoked regardless of the API request results.	X

Sample

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

If the request is successful, the Kakao Talk profile information is returned in JSON format. To see more about the response, refer to REST API.

Retrieve friends through picker

Basic information

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 displays the Friend picker and provides the information of the Kakao Talk friends that a user selects through the picker.

• The JavaScript SDK v1 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.

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 the callback functions such as success, fail, and always.
• 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
success	Function(Object)	Only used when implementing with the pop-up method. Callback function that gets invoked when the API request is successful.	X
fail	Function(Object)	Only used when implementing with the pop-up method. Callback function that gets invoked if the API request is failed.	X
always	Function(Object)	Only used when implementing with the pop-up method. Callback function that gets invoked regardless of the API request results.	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,
  success: function(response) {
    console.log(response);
  },
  fail: 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,
});

If the request is successful, 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

Basic information

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)

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.

Call the Kakao.API.request() function, and set url to /v1/api/talk/friends to request Kakao Talk friends information. You do not need to set the HTTP request header and other parameters because the JavaScript SDK v1 proceeds automatically and sends a request instead.

Parameter

Name	Type	Description	Required
url	String	Fixed as '/v1/api/talk/friends'.	O
success	Function(Object)	Callback function that gets invoked when the API request is successful.	X
fail	Function(Object)	Callback function that gets invoked if the API request is failed.	X
always	Function(Object)	Callback function that gets invoked regardless of API request results.	X
data	Object	Object that contains the parameters to be passed when requesting the API. Refer to data: Retrieving list of friends.	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',
  success: function(response) {
    console.log(response);
  },
  fail: function(error) {
    console.log(error);
  }
});

If the request is successful, a list of friends is returned in JSON format. To see more about the response, refer to REST API.

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.

See more

• Download JavaScript SDK v1
• API Reference for JavaScript SDK v1 →
• Message Template Builder →