kakao developers

JavaScript

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

You can test some features described in this document in [Tools] > [JS SDK demo] menu.

JS SDK demooutlink

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 Story APIs,

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

Optional: Get code for sharing or following button

If you want to apply the Kakao Story sharing or following function to your service, you can get a button and source code on Kakao Developers. For the sharing button, go to [Tools] > [Social Plugin] > [Kakao Story] > [Share], specify the URL you want to share, and then click [Generate code]. For the following button, specify your Kakao Story channel ID, and then click [Generate code].

Validate Kakao Story user Login required

This API checks if the user who is currently logged in is using Kakao Story. You can use this API to prevent an error that occurs due to users who are not using Kakao Story.

Call the Kakao.API.request() function, and set url to /v1/api/story/isstoryuser.

Kakao.API.request() returns Promise. For the detailed response fields returned if the promise is fulfilled, refer to REST API > Validate Kakao Story user.

Parameter

Name	Type	Description	Required
url	String	Fixed as /v1/api/story/isstoryuser.	O

Sample

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

Retrieve Kakao Story profile Login required Consent required

This API enables you to retrieve the Kakao Story profile information of the user who is currently logged in.

Users can set their desired profile nicknames and images for Kakao Story, Kakao Talk, and Kakao Account respectively. Thus, profile information retrieved through this API is different from the ones obtained through the Retrieving user information or Retrieving Kakao Talk profile API.

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

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

Parameter

Name	Type	Description	Required
url	String	Fixed as /v1/api/story/profile.	O

Sample

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

Post story Login required Consent required

This API enables you to post a new story on Kakao Story of the user who is currently logged in. This API supports three types of stories — text, photo, and link.

To use this API,

• You must enable the 'Publish posts in KakaoStory' scope in [My Application] > [Kakao Login] > [Consent items].
• A user must consent to the scope. Otherwise, an error occurs.

Story types

Type	Description	URL
Text	Story with text only.	/v1/api/story/post/note
Photo	Story with text and photos.	/v1/api/story/post/photo
Link	Story with text and the information obtained by scrapping a web page.	/v1/api/story/post/link

Posting text story

To post a text story without any photo or web page URL, use this API.

Call the Kakao.API.request() function, and set url to /v1/api/story/post/note. You must also pass the content parameter that contains the text you want to input.

Kakao.API.request() returns Promise. For the detailed response fields returned if the promise is fulfilled, refer to REST API > Post story.

Parameter

Name	Type	Description	Required
url	String	Fixed as /v1/api/story/post/note.	O
data	Object	Object that contains the parameters to be passed when requesting the API.	O

data: Posting text story

Name	Type	Description	Required
content	String	Text to be input in the story. Up to 2048 characters are allowed.	O
permission	String	Audience for the story. One of F (Friends only), A (Public), and M (Private). (Default: A).	X
enable_share	Boolean	Whether to share the story when permission is set to F (Friends only). (Default: false)	X
android_exec_param	String	Parameter to be added to the URL to execute an Android app when selecting the [View on app] button from Kakao Story.	X
ios_exec_param	String	Parameter to be added to the URL to execute an iOS app when selecting the [View on app] button from Kakao Story.	X
android_market_param	String	Parameter to be added to the execution URL when redirecting to an open market from Kakao Story.	X
ios_market_param	String	Parameter to be added to the execution URL when redirecting to the App Store from Kakao Story.	X

Sample

Kakao.API.request({
  url: '/v1/api/story/post/note',
  data: {
    content: 'Type your story.'
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

Posting photo story

To post a story with text and photos,

1. To upload the image files saved on a local device to the Kakao server, call the Kakao.API.request() function, and set url to v1/api/story/upload/multi by passing files. For the response returned if the images are successfully uploaded, refer to REST API > Upload image.
2. Call the Kakao.API.request() function, and set url to /v1/api/story/post/photo. You must pass image_url_list that is obtained in step 1, not pass an arbitrary image URL. For the detailed response fields returned if the promise is fulfilled, refer to REST API > Post story.

Parameter

Name	Type	Description	Required
url	String	Uploading image: Fixed as /v1/api/story/upload/multi. Posting photo story: Fixed as /v1/api/story/post/photo.	O
data	Object	Object that contains the parameters to be passed when requesting the API.	O

data: Uploading image

Name	Type	Description	Required
files	FileList | File[]	List of File objects to be uploaded, which are input in the <input> element.	O

data: Posting photo story

Name	Type	Description	Required
image_url_list	String[]	The path, width and height of the uploaded image obtained through the Uploading image API. For the detailed respond fields, refer to REST API > Response.	O
content	String	Text to be input in the story. Up to 2048 characters are allowed.	X
permission	String	Audience for the story. One of F (Friends only), A (Public), and M (Private). (Default: A).	X
enable_share	Boolean	Whether to share the story when permission is set to F (Friends only). (Default: false)	X
android_exec_param	String	Parameter to be added to the URL to execute an Android app when selecting the [View on app] button from Kakao Story.	X
ios_exec_param	String	Parameter to be added to the URL to execute an iOS app when selecting the [View on app] button from Kakao Story.	X
android_market_param	String	Parameter to be added to the execution URL when redirecting to an open market from Kakao Story.	X
ios_market_param	String	Parameter to be added to the execution URL when redirecting to the App Store from Kakao Story.	X

Sample

var files = document.getElementById('input-file').files;

Kakao.API.request({
  url: '/v1/api/story/upload/multi',
  files: files,
})
  .then(function(uploadedUrls) {
    return Kakao.API.request({
      url: '/v1/api/story/post/photo',
      data: {
        image_url_list: uploadedUrls,
      },
    });
  })
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

Posting link story

To post a story with the information obtained by scrapping a web page,

1. To obtain the web page information to be shared in a story, call the Kakao.API.request() function, and set url to v1/api/story/linkinfo. The web page information is scraped based on the Open Graph Protocol. For the response returned if the images are successfully uploaded, refer to REST API > Scrape web page.
2. Call the Kakao.API.request() function, and set url to /v1/api/story/post/link. You must pass link_info that is obtained in step 1, not pass an arbitrary web page URL. Kakao.API.request() returns Promise. For the detailed response fields returned if the promise is fulfilled, refer to REST API > Post story.

Parameter

Name	Type	Description	Required
url	String	Scraping web page: Fixed as /v1/api/story/linkinfo. Posting link story: Fixed as /v1/api/story/post/link.	O
data	Object	Object that contains the parameters to be passed when requesting the API.	O

data: Scraping web page

Name	Type	Description	Required
url	String	URL of the web page to be scraped.	O

data: Posting link story

Name	Type	Description	Required
link_info	Object	The web page information that is obtained through the Scraping web page API. For the detailed respond fields, refer to REST API > Response.	O
content	String	Text to be input in the story. Up to 2048 characters are allowed.	X
permission	String	Audience for the story. One of F (Friends only), A (Public), and M (Private). (Default: A).	X
enable_share	Boolean	Whether to share the story when permission is set to F (Friends only). (Default: false)	X
android_exec_param	String	Parameter to be added to the URL to execute an Android app when selecting the [View on app] button from Kakao Story.	X
ios_exec_param	String	Parameter to be added to the URL to execute an iOS app when selecting the [View on app] button from Kakao Story.	X
android_market_param	String	Parameter to be added to the execution URL when redirecting to an open market from Kakao Story.	X
ios_market_param	String	Parameter to be added to the execution URL when redirecting to the App Store from Kakao Story.	X

Sample

Kakao.API.request({
  url: '/v1/api/story/linkinfo',
  data: {
    url: 'https://developers.kakao.com',
  },
})
  .then(function(scrappedLink) {
    return Kakao.API.request({
      url: '/v1/api/story/post/link',
      data: {
        link_info: scrappedLink,
      },
    });
  })
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

Retrieve my story Login requiredConsent required

This API enables you to retrieve story information on Kakao Story of the user currently logged in. You can request basic information about the multiple recent stories or a specific story only by specifying a story ID. When requesting a specific story, you can get detailed information about the story, including comments.

To use this API,

• You must enable the 'Read access to KakaoStory posts' scope in [My Application] > [Kakao Login] > [Consent items].
• A user must consent to the 'Read access to KakaoStory posts' scope. Otherwise, an error occurs.

You can use this API in either way:

• Retrieve my story information by specifying the story ID obtained in the response of the Posting story API.
• Retrieve information of the recent stories through the Retrieving multiple stories API.
  • Retrieve my story information by specifying the story ID obtained in the response of the Retrieving multiple stories API.

Depending on whether you request a single story or multiple stories, the request parameters you need to pass are different.

Retrieving specified story

Call the Kakao.API.request() function, and set url to /v1/api/story/mystory. If you want to request a specific story only, you must pass id of the story. In this case, the contents and the comments of the story are returned only.

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

Parameter

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

data: Retrieving specified story

Name	Type	Description	Required
id	String	Story ID to be retrieved.	O

Sample

Kakao.API.request({
  url: '/v1/api/story/mystory',
  data: {
    id: '${STORY_ID}',
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

Retrieving multiple stories

Call the Kakao.API.request() function, and set url to /v1/api/story/mystories. If you want to request multiple stories, you can pass last_id to get information of the recent stories from a specific story. In this case, the response includes only the number of comments and likes.

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

Parameter

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

data: Retrieving multiple stories

Name	Type	Description	Required
last_id	String	Set the last (latest) story ID among the stories that you want to retrieve. The stories from the specified story to the oldest stories are returned, excluding the specified story ID. If not specified, all stories from recent to oldest are returned, which is set as a default.	X

Sample

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

Delete story Login required

This API enables you to delete a story on Kakao Story by specifying a story ID. Because you must pass the ID of the story you want to delete, you need to know the story ID through the Retrieving my story or Posting story API.

Call the Kakao.API.request() function, and set url to /v1/api/story/delete/mystory.

Kakao.API.request() returns Promise, but no data is returned even if the promise is fulfilled.

Parameter

Name	Type	Description	Required
url	String	Fixed as /v1/api/story/delete/mystory.	O
data	Object	Object that contains the parameters to be passed when requesting the API.	O

data: Deleting story

Name	Type	Description	Required
id	String	Story ID to be deleted.	O

Sample

Kakao.API.request({
  url: '/v1/api/story/delete/mystory',
  data: {
    id: '${STORY_ID}',
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

Add Share button

The JavaScript SDK provides the Kakao Story sharing function via a web view, which is not provided by Android and iOS SDK. This function allows you to add a [Share] button to your web page.

Call the Kakao.Story.createShareButton() function that adds the [Share] button allowing a web view presented when a user clicks. Set the position where the [Share] button is added.

Parameter

Name	Type	Description	Required
container	String	ID of the element where the [Share] button is added.	O
url	String	URL of the web page to be shared on Kakao Story.	O
text	String	Text to be input automatically on the Sharing web view.	O

Sample

Kakao.Story.createShareButton({
  container: '#kakaostory-share-button',
  url: 'https://developers.kakao.com',
  text: 'Welcome to Kakao Developers! #developers @kakao :)',
});

Display Sharing web view

This function prompts a web view to write a new story on Kakao Story. When a user clicks the[Share] button, the Kakao.Story.share() function is invoked and a web view for Kakao Login is displayed. After the user logs in with Kakao, the Sharing web view is displayed. If the user has already logged in, the Sharing web view appears directly.

Parameter

Name	Type	Description	Required
url	String	URL of the web page to be shared on Kakao Story.	O
text	String	Text to be input automatically on the Sharing web view.	O

Sample

Kakao.Story.share({
  url: 'https://developers.kakao.com',
  text: 'Welcome to Kakao Developers! #developers @kakao :)',
});

Share via Kakao Story

This function allows users to share a desired information via the Kakao Story app more easily. Note that this function does not inform you if users complete sharing the web page.

To share a specific web page via the Kakao Story app, call the Kakao.Story.open() function. The web page information is scraped based on the Open Graph Protocol.

Parameter

Name	Type	Description	Required
url	String	URL of the web page to be shared on Kakao Story.	O
text	String	Text to be input automatically on the Sharing web view.	O
urlInfo	Object	Information of the scraped web page.	X

urlInfo

Name	Type	Description	Required
title	String	Web page title.	O
desc	String	Web page description.	X
name	String	Web page name.	X
images	String[]	URL of a representative image of the web page.	X

Sample

Kakao.Story.open({
  url: 'https://developers.kakao.com',
  text: 'Welcome to Kakao Developers! #developers @kakao :)',
});

Follow Kakao Story

You can add the [Follow] button to your web page to encourage users to receive news from your Kakao Story Channel. Call the Kakao.Story.createFollowButton() function at the point where the [Follow] button is added. Then, the [Follow] button is added to the corresponding container. When a user clicks the [Follow] button, the JavaScript SDK sends a follow request with the user's information to the corresponding Kakao Story Channel.

This function requires information about the user who is currently logged in. Thus, for those who are not logged in yet, prompt a web view to request to log in firstly.

Parameter

Name	Type	Description	Required
container	String	ID of the element where the [Follow] button is added.	O
id	String	ID of Kakao Story Channel to follow.	O
showFollowerCount	Boolean	Whether to show the number of followers who is following the corresponding channel. Can substitute with the attribute of data-show-follower-count in the container element. (Default: true)	X
type	String	Type of displaying the number of followers. Can substitute with the attribute of data-type in the container element. (Default: horizontal)	X

Sample

Kakao.Story.createFollowButton({
  container: '#kakaostory-follow-button',
  id: 'kakao',
});

See more

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

Legacy

• Kakao Story for JavaScript SDK v1