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.
To use the JavaScript SDK, you must register the Web platform in advance. Go to [My Application] > [Platform] and register your site domains.
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. |
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
.
If the request is successful, isStoryUser
is returned in JSON format. To see more about the response, refer to REST API > Response.
Name | Type | Description | Required |
---|---|---|---|
url | String |
Fixed as /v1/api/story/isstoryuser . |
O |
success | Function(Object) |
Callback function that gets invoked when the API request is successful. | X |
fail | Function(Object) |
Callback function that gets invoked when the API request is failed. | X |
always | Function(Object) |
Callback function that gets invoked regardless of API request results. | X |
Kakao.API.request({
url: '/v1/api/story/isstoryuser',
success: function(response) {
console.log(response);
},
fail: function(error) {
console.log(error);
}
});
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
.
If the request is successful, the Kakao Story profile information is returned in JSON format. To see more about the response, refer to REST API > Response.
Name | Type | Description | Required |
---|---|---|---|
url | String |
Fixed as /v1/api/story/profile . |
O |
success | Function(Object) |
Callback function that gets invoked when the API request is successful. | X |
fail | Function(Object) |
Callback function that gets invoked when the API request is failed. | X |
always | Function(Object) |
Callback function that gets invoked regardless of API request results. | X |
Kakao.API.request({
url: '/v1/api/story/profile',
success: function(response) {
console.log(response);
},
fail: function(error) {
console.log(error);
}
});
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,
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 |
Make sure that depending on the story types, the parameters are different. If the request is successful, the created story ID is returned in JSON format. To see more about the response, refer to REST API > Response.
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.
Name | Type | Description | Required |
---|---|---|---|
url | String |
Fixed as /v1/api/story/post/note . |
O |
success | Function(Object) |
Callback function that gets invoked when the API request is successful. | X |
fail | Function(Object) |
Callback function that gets invoked when 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: Posting text story. |
O |
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 |
Kakao.API.request({
url: '/v1/api/story/post/note',
data: {
content: 'Type your story.'
},
success: function(response) {
console.log(response);
},
fail: function(error) {
console.log(error);
}
});
To post a story with text and photos, use this API.
Before posting a photo story, you must call the Uploading image API in advance and get the uploaded image URI value. With the uploading image function, you can upload an image to the Kakao platform and use the path where the image is uploaded when you request to post a photo story. You must not pass an arbitrary image URL to post a photo story.
When it comes to the image to be uploaded, its size must be less than 10 MB, and you cannot upload more than 10 images. If the image is a GIF file, you can only upload a single image.
Call the Kakao.API.request()
function, and set url
to v1/api/story/upload/multi
first to upload an image. If the request is successful, call the Posting photo story API by setting url
to /v1/api/story/post/photo
in the Kakao.API.request()
function. At this moment, you must pass image_url_list
that contains the image information to be attached to a story. content
that contains the text is an optional parameter when posting a photo story.
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 |
success | Function(Object) |
Callback function that gets invoked when the API request is successful. | X |
fail | Function(Object) |
Callback function that gets invoked when 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: Uploading image, data: Posting photo story. |
O |
Name | Type | Description | Required |
---|---|---|---|
files | FileList | File[] |
List of File objects to be uploaded, which are input in the <input> element. |
O |
Name | Type | Description | Required |
---|---|---|---|
image_url_list | String[] |
The path, width and height of the uploaded image obtained through the Uploading image API. | 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 |
Kakao.API.request({
url: '/v1/api/story/upload/multi',
files: event.target.files,
success: function(imageUrlList) {
Kakao.API.request({
url: '/v1/api/story/post/photo',
data: {
image_url_list: imageUrlList
},
success: function(response) {
console.log(response);
},
fail: function(error) {
console.log(error);
}
})
},
fail: function(uploadError) {
console.log(uploadError);
}
})
To post a story that shares a web page, use this API.
Before posting a link story, you must call the Scraping web page API in advance and get the URL of the web page. The web page is scraped based on the Open Graph Protocol. You must not pass an arbitrary URL to post a link story.
Call the Kakao.API.request()
function, and set url
to v1/api/story/linkinfo
first to scrape a web page. If the request is successful, call the Posting link story API by setting url
to /v1/api/story/post/link
in the Kakao.API.request()
function. At this moment, you must pass link_info
that contains the web page information to be shared in a story. content
that contains the text is an optional parameter when posting a link story.
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 |
success | Function(Object) |
Callback function that gets invoked when the API request is successful. | X |
fail | Function(Object) |
Callback function that gets invoked when 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: Scraping web page, data: Posting link story. |
O |
Name | Type | Description | Required |
---|---|---|---|
url | String |
URL of the web page to be scraped. | O |
Name | Type | Description | Required |
---|---|---|---|
link_info | Object |
The web page information that is obtained through the Scraping web page API. Refer to link_info. |
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 |
Name | Type | Description |
---|---|---|
url | String |
URL of the scraped web page. If a short URL is used for url when requesting the Scraping web page API, the actual URL is passed. |
requested_url | String |
URL passed when requesting to scrap a web page. |
host | String |
URL Host. |
title | String |
Web page title. |
image | String[] |
URL of a representative image of the web page. Up to three images are allowed. |
description | String |
Web page description. |
type | String |
Type of content included on the web page such as "website", "video", and "music". |
section | String |
Section information on a web page. |
Kakao.API.request({
url: '/v1/api/story/linkinfo',
data: {
url: 'https://developers.kakao.com'
},
success: function(linkInfo) {
Kakao.API.request({
url: '/v1/api/story/post/link',
data: {
link_info: linkInfo
},
success: function(response) {
console.log(response);
},
fail: function(error) {
console.log(error);
}
})
},
fail: function(linkError) {
console.log(linkError);
}
})
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 can use this API in either way:
Depending on whether you request a single story or multiple stories, the request parameters you need to pass are different.
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 response includes the contents and the comments of the story.
If the request is successful, the information of the requested story is returned in JSON format. To see more about the response, refer to REST API > Response.
Name | Type | Description | Required |
---|---|---|---|
url | String |
Fixed as /v1/api/story/mystory . |
O |
success | Function(Object) |
Callback function that gets invoked when the API request is successful. | X |
fail | Function(Object) |
Callback function that gets invoked when 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 specified story. |
O |
Name | Type | Description | Required |
---|---|---|---|
id | String |
Story ID to be retrieved. | O |
Kakao.API.request({
url: '/v1/api/story/mystory',
data: {
id: '_AAAA.BBBBBBBBBBBB'
},
success: function(response) {
console.log(response);
},
fail: function(error) {
console.log(error);
}
});
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.
If the request is successful, the information of the stories is returned in JSON format. To see more about the response, refer to REST API > Response.
Name | Type | Description | Required |
---|---|---|---|
url | String |
Fixed as /v1/api/story/mystories . |
O |
success | Function(Object) |
Callback function that gets invoked when the API request is successful. | X |
fail | Function(Object) |
Callback function that gets invoked when 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 multiple stories. |
X |
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 |
Kakao.API.request({
url: '/v1/api/story/mystories',
success: function(response) {
console.log(response);
},
fail: function(error) {
console.log(error);
}
});
This API enables you to delete a story on Kakao Story by specifying a story ID. Since you must pass the ID of the story you want to delete, you need to know the story ID through the Retrieving story or Posting story API.
Call the Kakao.API.request()
function, and set url
to /v1/api/story/delete/mystory
.
Name | Type | Description | Required |
---|---|---|---|
url | String |
Fixed as /v1/api/story/delete/mystory . |
O |
success | Function(Object) |
Callback function that gets invoked when the API request is successful. | X |
fail | Function(Object) |
Callback function that gets invoked when 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: Deleting story. |
O |
Name | Type | Description | Required |
---|---|---|---|
id | String |
Story ID to be deleted. | O |
Kakao.API.request({
url: '/v1/api/story/delete/mystory',
data: {
id: '_AAAA.BBBBBBBBBBBB'
},
success: function(response) {
console.log(response);
},
fail: function(error) {
console.log(error);
}
});
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.
In [Tools] > [Social Plugin] > [Kakao Story] > [Share], you can create the [Share] button and source code.
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 |
Kakao.Story.createShareButton({
container: '#kakaostory-share-button',
url: 'https://developers.kakao.com',
text: 'Welcome to Kakao Developers! #developers @kakao :)'
});
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.
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 |
Kakao.Story.share({
url: 'https://developers.kakao.com',
text: 'Welcome to Kakao Developers! #developers @kakao :)'
});
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.
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 |
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 |
Kakao.Story.open({
url: 'https://developers.kakao.com',
text: 'Welcome to Kakao Developers! #developers @kakao :)'
});
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.
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 |
Kakao.Story.createFollowButton({
container: '#kakaostory-follow-button',
id: 'kakao'
});