Kakao Story

Kakao Story API refer to an API provided by kakao story service. It can be used with apps that has kakao account login functionality and can only be used upon kakao story users.

Followings are API provided .

Please refer to here regarding button when using KakaoStory API.

Confirm user

Check if logged in user is registered for KakaoStory. In order to use this call, it is required to obtain user token after successful login.

[Request]

GET /v1/api/story/isstoryuser HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}

Request with GET method which user token is included in the header.
For example,

curl -v -X GET https://kapi.kakao.com/v1/api/story/isstoryuser \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

[Response]

If response have succeeded, include values below in JSON object inside response body.

key description type
isStoryUser Check if user is kakao story user. if it's true, it means the user is a kakao story registered user. Boolean

For example,

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "isStoryUser":true
}

Profile request

Profile request is a way to obtain profile information of kakaostory users. In order to use this call, it is required to obtain user token after successful login.

[Request]

GET /v1/api/story/profile HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}

Make request with user token inside header through GET method. With user token, parameter below can be added selectively.

key description required
secure_resource Whether imgage url should be returned in https. true/false X


For example,

curl -v -X GET https://kapi.kakao.com/v1/api/story/profile \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

[Response]

If request succeed, response body should include below values in JSON object.

key description type
nickName Kakaostory nickName. String
profileImageURL Kakaostory profile image URL. 480px * 480px ~ 1024px * 1024px size String
thumbnailURL Kakaostory Thumbnail profile image URL. 160px * 213px size String
bgImageURL Kakaostory background image URL. 480px * 480px ~ 1024px * 1024px size String
permalink Kakaostory permanent link. Web URL for visiting mystory. String
birthday Kakaostory birthday. MMdd form with no year information included . String
birthdayType Kakaostory birthday type. Describes enum type with Gregorian, Lunar types. "SOLAR" or "LUNAR"

For example,

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "nickName":"Hong Gildong",
  "profileImageURL":"http://xxx.kakao.com/.../aaa.jpeg",
  "thumbnailURL":"http://xxx.kakao.com/.../bbb.jpeg",
  "bgImageURL":"http://xxx.kakao.co.kr/.../ccc.jpg",
  "permalink": "https://story.kakao.com/XXXXX",
  "birthday":"1231",
  "birthdayType":"SOLAR"
}

Posting

This is a function for posting data to user's own Kakao Story(current KakaoStory users only). In order to use this call, it is required to obtain user token after successful login.

There are 3 ways to post to kakaoStory.

  • story_note.png 글(Note) : Write article and post it on your own KakaoStory.
  • story_photo.png 사진(Photo) : Upload photo and share stories by posting in KakaoStory.
  • story_link.png 링크(Link) : Post by scraping page. Post information to KakaoStory through its URL

All types of posting required elements are explained here. Each type's required elements are explained in session section .

key description required type
permission Permission on whether to open posting to public or to friends.
F : Open to friends, A : Open to public, M : Private
Default is A.
X String
enable_share If it's open to friends, permission on whether friends can share targeted posting .
If it's open to public, it must be sharable with no option involved.
default value to false.
X Boolean
android_exec_param Parameter to be added to Android app launch URL.
Included in default URL "kakao[appkey]://kakaostory" as parameter.
X String
ios_exec_param Parameter to be added to iOS app launch URL.
Included in default URL "kakao[appkey]://kakaostory" as parameter.
X String
android_market_param Parameter to be added to Android app market URL.
Included in default URL "market://details?id=[android package name]" as parameter .
X String
ios_market_param Parameter to be added to iOS app market URL.
Included in default URL "https://itunes.apple.com/app/id[app store ID]" as parameter .
X String
  • If URL is not valid, clicking on posting reference app's name will direct to market URL.
  • If you have not set market URL, there will be no response from device with app not installed when clicking the link.
    • For example, if only Android app exists, and setting > general > platform > iOS has not been set, there will be no response from iphone upon clicking app redirection button in kakao story.

Note posting

[Request]

POST /v1/api/story/post/note HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded;charset=utf-8

With user token, common parameter + parameters below will be requested using POST method.

key description required type
content Contents to be in posting.
restriction of 2048 characters.
It may be user typed content or content from the app it self.
O String

For example,
If you wish to go public with "This cafe is really awesome!" content when posting and make URL to redirect to upon click to kakao[appkey]://kakaostory?cafe_id=1234 in Android and kakao[appkey]://kakaostory?cafe_id=1234 in iOS follow below.

curl -v -X POST https://kapi.kakao.com/v1/api/story/post/note \
 -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
 --data-urlencode 'content=This cafe is really awesome!' \
 --data-urlencode 'android_exec_param=cafe_id=1234' \
 --data-urlencode 'ios_exec_param=cafe_id=1234'

[Response]

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id":"AAAAAAA.BBBBBBBBBBB"
}

If it's a success, HTTP StatusCode 200 will appear and posting id will be returned.

Photo posting

1. In order to post photo, image upload API must be called.
If upload succeed, URI for image file, given as a response should be included as parameter in posting API, prior to request being made.
Uploaded image must be 10MB below in size and restricted to 10 in numbers. In case of gif, file will be restricted to 1 in numbers.

Random image URL can not be included in story posting. Only image uploaded using API can be used .

[Request]

POST /v1/api/story/upload/multi HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}
Content-Type: multipart/form-data; boundary=---------------------------012345678901234567890123456

Before making POST method request, user's token will be included in the header and upload file's binary included in file field.

key description required type
file
(multi support)
or name that start with file name. example) file[0], file[1], file1 's'
Uploading file binary.
In Content-Disposition, filename should be included ( Refer multipart )
O binary
---------------------------012345678901234567890123456
Content-Disposition: form-data; name="file"; filename="your_image.jpg"
Content-Type: image/jpeg

...
---------------------------012345678901234567890123456

For example,

curl -v -X POST https://kapi.kakao.com/v1/api/story/upload/multi \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@/aaaa/bbbb/cccc/0.jpg" \
  -F "file=@/aaaa/bbbb/dddd/0.jpg"

PHP

<?php
   $uploadfile1="your_example_image_1.jpg";
   $uploadfile2="your_example_image_2.jpg";
   $ch = curl_init("https://kapi.kakao.com/v1/api/story/upload/multi");
   curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"));
   curl_setopt($ch, CURLOPT_POSTFIELDS, array('file[0]'=>"@$uploadfile1", 'file[1]'=>"@$uploadfile2"));
   curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
   $postResult = curl_exec($ch);
   curl_close($ch);
   print "$postResult";
?>

Python

import requests

upload_photo_url = 'https://kapi.kakao.com/v1/api/story/upload/multi'
post_photo_url = 'https://kapi.kakao.com/v1/api/story/post/photo'

files = {'file': open('your_picture.jpeg', 'rb')}

token = 'YOUR TOKEN HERE'
headers = {'Authorization': 'Bearer {0}'.format(token)}

upload_result = requests.post(upload_photo_url, headers=headers, files=files)

post_photo_payload = {'image_url_list': upload_result.text}
post_result = requests.post(post_photo_url, headers=headers, data=post_photo_payload)

print post_result

[Response]

If request suceed, image's path and it's size will be returned once the request succeed.

For example,

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
    "/aaaaa/bBbbbBbbbB/CCcCcC1ccCCcCCCCCCcc1c/img.png?width=150&height=150",
    "/aaaaaa/bBbbbbbBbBb/dDdDDDDDddddDdddddDDDDDd/img.jpg?width=1080&height=1920"
]

2. Make request using photo posting API With selected content to be uploaded with image and result of image upload.

[Request]

POST /v1/api/story/post/photo HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded;charset=utf-8

Request using POST method with user token common parameter + below parameter values.

key description required type
image_url_list Image upload result, which will be posted on posting.
Use response of Image upload .
O Json array object based String
content Image content regarding posting .
Max of 2048 characters.
It can be details written by user or can be a content automatically filled by app.
X String

For example,
With the image uploaded from above example, "This cafe is really awesome!" can be posted with allowance of disclosing and sharing content to friends as below.

curl -v -X POST https://kapi.kakao.com/v1/api/story/post/photo \
 -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
 -d 'permission=F' \
 -d 'enable_share=true' \
 --data-urlencode 'content=This cafe is really awesome!' \
 --data-urlencode 'image_url_list=['/aaaaaaaaaaaaaaaaa/bbbbbbbbbbbbbbbbbbbbbb/img.jpg?width=6200&height=3100','/aaaaaaaaaaaaaaaaa/dddddddddddddddddddddd/img.jpg?width=6200&height=3100']'

[Response]

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id":"AAAAAAA.CCCCCCCCCCC"
}

If success, HTTP StatusCode 200 and posting id will be returned.

1. In order to make link posting, you must make API call to retrieve information from the link given. If you have successfully retrieved information, preview can be provided with returned result.

[Request]

GET /v1/api/story/linkinfo HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}

With user token, below parameter will be requested using GET method.

key description required type
url Retrieve information from url you wish to scrap. O String

For example, if you wish to scrap https://developers.kakao.com

curl -v -X GET https://kapi.kakao.com/v1/api/story/linkinfo?url=http://bit.ly/1wwLqDl \
     -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

[Response]

If request succeed, response body should include below values in JSON object

key description type
url Scrapped URL address. For shorten URL, this is resolution URL String
requested_url Original URL which has been requested. URL before resolution String
host Requested Host name String
title Web page title String
image Main image address for targeted web page. Max 3. String
description Targeted webpage description String
section Targeted web page section information String
type 해당 웹 페이지가 포함하는 콘텐츠의 타입 정보. 예) website, video, music 등 String

For example,

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "url":"https://developers.kakao.com/",
  "requested_url":"http://bit.ly/1wwLqDl",
  "host":"developers.kakao.com",
  "title":"Kakao Developers_",
  "image":["http://dn-l1-story.kakao.co.kr/dn/bc995u/hydnh8wbKi/dz59YCCjyZSXNmDgTPpPa0/img.jpg?height=630&width=1200"],
  "description":"To make our dream of better world come true, Kakao now launch kakao app development platform service.",
  "section":"",
  "type":"website"
}

2. With retrieved scrap information, make a call with API with contents you wish to select included.

[Request]

POST /v1/api/story/post/link HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded;charset=utf-8

Request using POST method with user token common parameter + below parameter values.

key description required type
link_info linkinfo's result value O String
content Selective information that will be included with scrap information.
Maximum of 2048 characters.
It can be details written by user or can be a content automatically filled by app.
X String

For example,
If you wish to post "better than expected!" with information retrieved from above example as public posting, you can follow below example.

curl -v -X POST https://kapi.kakao.com/v1/api/story/post/link \
-H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
--data-urlencode 'link_info={
                             "url":"https://developers.kakao.com/",
                             "requested_url":"http://bit.ly/1wwLqDl",
                             "host":"developers.kakao.com",
                             "title":"Kakao Developers_",
                             "image":["http://dn-l1-story.kakao.co.kr/dn/bc995u/hydnh8wbKi/dz59YCCjyZSXNmDgTPpPa0/img.jpg?height=630&width=1200"],
                             "description":"To make our dream of better world come true, Kakao now launch kakao app development platform service.",
                             "section":"",
                             "type":"website"
                            }' \
--data-urlencode 'content=better than expected!'

[Response]

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id":"AAAAAAA.DDDDDDDDDDD"
}

If success, HTTP StatusCode 200 and posting id will be returned.

MyStory information request

Can request information regarding posts they have made if user has credential in KakaoStory(registered as user in KakaoStory). Required to obtain user token after successful login, in order to use this call.

Result should include information below.

key description type
id This is unique id by story as posting result String
url web url which can lead to mystory String
media_type Story type. "NOTE" "PHOTO" "NOT_SUPPORTED"
created_at Story created time String
RFC3339 internet date/time format.
content Text part of story. String
media Provided only when media_type is PHOTO. Object's array with image URL by size
comment_count number of comments signed i32
like_count number of likes signed i32
comments Comment contents and comment authors. Only provided for Single my story information request "text" and "writer" structured json
"writer" : "display_name" and "profile_thumbnail_url" structured
likes Like contents and it's author . Only provided for Single my story information request "emotion" and "actor" structured json
"emotion" : "LIKE" "COOL" "HAPPY" "SAD" "CHEER_UP" "NOT_DEFINED"
"actor" : Components such as "write".
permission Allowance on who can view my post "PUBLIC" "FRIEND" "ONLY_ME"

Requesting single mystory information

Set post id of requesting mystory, and call API for requesting single mystory information.

[Request]

GET /v1/api/story/mystory HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}

Request using GET method with user token and parameter below included.

key description required type
id Mystory id of information wishing to retrieve O String

For example,
If you wish to obtain information on previous photo posting,

curl -v -X GET https://kapi.kakao.com/v1/api/story/mystory?id=0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ \
     -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

[Response]

If request succeed, response body should include Kakaostory-mystory-information values in JSON object

For example,
If you obtain previous photo posting information

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id": "AAAAAAA.CCCCCCCCCCC",
    "url": "http://story-web.kakao.com/AAAAAAA/CCCCCCCCCCC",
    "media_type": "PHOTO",
    "created_at": "2014-06-13T07:58:20Z",
    "comment_count": 1,
    "like_count": 1,
    "content": "This cafe is really awesome!",
    "media": [
        {
            "original":"http://xxx.kakao.co.kr/.../img.png?width=150&height=150",
            "xlarge":"http://xxx.kakao.co.kr/.../img_xl.jpg?width=150&height=150",
            "large":"http://xxx.kakao.co.kr/.../img_l.jpg?width=150&height=150",
            "medium":"http://xxx.kakao.co.kr/.../img_m.jpg?width=150&height=150",
            "small":"http://xxx.kakao.co.kr/.../img_s.jpg?width=150&height=150"
        }
    ],
      "comments": [
        {
          "text": "Where am I?",
          "writer": {
            "display_name": "Han summer",
            "profile_thumbnail_url": "http://xxxx.kakao.co.kr/.../ABCDEFG.jpeg"
          }
        }
      ],
      "likes": [
        {
          "emotion": "COOL",
          "actor": {
            "display_name": "Yeobada",
            "profile_thumbnail_url": "http://xxxx.kakao.co.kr/.../1234566.jpeg"
          }
        }
      ]
}


Requesting multiple mystory information

Request most recently posted or previously posted mystorys info in multiple quantities. You can retrieve as much as 18 information at once. Targeted ids my story info will not be included in result.(targeted id will only be a pin point of mystories retrieving as result)

[Request]

GET /v1/api/story/mystories HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}

Request using GET method with user token and parameter below included.

key description required type
last_id Last story id of information wishing to be retrieved.
Returns multiple mystory information from the point of previous informations of last_id.
Mystory information of post_id will not be included.
Default value is the most recent mystory id.
X String

For example,
If you wish to retrieve information of previous mystory photo posting

curl -v -X GET https://kapi.kakao.com/v1/api/story/mystories?last_id=0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ \
     -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

[Response]

If request suceed, response body will be in JSON object Kakaostory-mystory-informationwith Array included.

For example,

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
    {
        "id": "AAAAAAA.BBBBBBBBBBB",
        "url": "http://story-web.kakao.com/AAAAAAA/BBBBBBBBBBB",
        "media_type": "NOT_SUPPORTED",
        "created_at": "2014-06-13T07:58:26Z",
        "comment_count": 3,
        "like_count": 4,
        "content": "better than expected!"
    },
    {
        "id": "AAAAAAA.CCCCCCCCCCC",
        "url": "http://story-web.kakao.com/AAAAAAA/CCCCCCCCCCC",
        "media_type": "PHOTO",
        "created_at": "2014-06-13T07:58:20Z",
        "comment_count": 1,
        "like_count": 1,
        "content": "This cafe is really awesome!",
        "media": [
            {
                "original":"http://xxx.kakao.com/.../img.png?width=150&height=150",
                "xlarge":"http://xxx.kakao.com/.../img_xl.jpg?width=150&height=150",
                "large":"http://xxx.kakao.com/.../img_l.jpg?width=150&height=150",
                "medium":"http://xxx.kakao.com/.../img_m.jpg?width=150&height=150",
                "small":"http://xxx.kakao.com/.../img_s.jpg?width=150&height=150"
            }
        ]
    },
    {
        "id": "AAAAAAA.DDDDDDDDD",
        "url": "http://story-web.kakao.com/AAAAAAA/DDDDDDDDD",
        "media_type": "NOTE",
        "created_at": "2014-06-13T07:58:17Z",
        "comment_count": 0,
        "like_count": 10,
        "content": "A Rainbow - William Wordsworth\n\n..."
    },
    ...
]

Deleting mystory

User can delete his or her story, posted personally, if user has credential in KakaoStory.(registered as user in KakaoStory) Required to obtain user token after successful login, in order to use this call.

Set targeted mystory id(Post id), and call, and call API for deleting mystory.

[Request]

DELETE /v1/api/story/delete/mystory HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}

With user token included and parameter values as below, make request using DELETE.

key description required type
id Mystory id to be deleted O String

For example,
If you wish to delete photo posting

curl -v -X DELETE https://kapi.kakao.com/v1/api/story/delete/mystory?id=0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ \
     -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

[Response]

If request succeed, Http Status will return as 200 and there will be no response body.

HTTP/1.1 200 OK
Content-Length: 0
Content-type: application/json;charset=UTF-8

Last Modified : 2017-07-31