Kakao Story

KakaoStory API refers to API provided in KakaoStory service. You can make your app login through Kakao Account, which only works for users with Kakao Story.

Below are KakaoStory API, supported currently.

  • Check user: Check if currently logged in user is signed up for KakaoStory.
  • Profile request: Gets kakao Story profile from users who are using KakaoStory currently.
  • Posting: Post photos(multiple photos allowed), articles, links(Scrap) in users kakaoStory.
  • Request mystory: Get one or more mystory information.
  • Delete mystory: Delete mystory.

Please refer to here regarding button when using KakaoStory API .

Before getting started

1. Please check if app is set to use Login API by followingloginbase temolate

2. Check if key used in App sign is registered in settings> general > Platform > Android > Key hash

For details regarding creating key hash, please follow Creating app, step two.

3. Register additional custom scheme for connecting app with Kakao Story posting API.

[kakao_strings.xml]

<resources>
    <string name="kakao_app_key">AAAAAAAAAAAAAAAAAAAAAA</string>
    <string name="kakao_scheme">kakaoAAAAAAAAAAAAAAAAAAAAAA</string>
    <string name="kakaostory_host">kakaostory</string>
</resources>
  • Scheme(kakao_scheme): This is scheme of a app key's characters added to "kakao" characters. example) If app key is AAAAAAAAAAAAAAAAAAAAAA Custom scheme should be kakaoAAAAAAAAAAAAAAAAAAAAAA.
  • Host(kakaostory_host) : Use "kakaostory" as set value.

[AndroidManifest.xml]

<uses-permission android:name="android.permission.INTERNET" />

<application
    ...
    <activity
        android:name=".KakaoStoryMainActivity">
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="@string/kakao_scheme" android:host="@string/kakaostory_host" />
        </intent-filter>
    </activity>
    ...
 </application>

getting started

API request should use KakaoStoryService. As parameter, pass in call back of API request result KakaoStoryHttpResponseHandler. By referring below, implement KakaoStoryHttpResponseHandler .

  • onHttpSuccess(T) : This is the case where API request has succeeded and result T will be returned.
  • onHttpSessionClosedFailure(APIErrorResult) : Receive failure error due to closed session.
  • onNotKakaoStoryUser() : This is the case for callback being called due to user not being kakao story registered user.
  • onFailure(APIErrorResult) : For failure due to reasons beside session being closed and user not being registered for kakao story.
public class KakaoStoryMainActivity extends Activity {

    private void redirectLoginActivity() {
        final Intent intent = new Intent(this, KakaoStoryLoginActivity.class);
        startActivity(intent);
        finish();
    }

    private abstract class MyStoryHttpResponseHandler<T> extends KakaoStoryHttpResponseHandler<T> {
        @Override
        protected void onHttpSessionClosedFailure(final APIErrorResult errorResult) {
            redirectLoginActivity();
        }

        @Override
        protected void onNotKakaoStoryUser(){
            Toast.makeText(getApplicationContext(), "not a KakaoStory user", Toast.LENGTH_SHORT).show();
        }

        @Override
        protected void onFailure(final APIErrorResult errorResult) {
            Toast.makeText(getApplicationContext(), "failed : " + errorResult, Toast.LENGTH_SHORT).show();
        }
    }
}

You can reveal reasons for failure in requesting API, through received parameter as APIErrorResult#getErrorCode()), APIErrorResult#getErrorMessage()). Following errors could be returned upon KakaoTalk API call.

Check 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. Below is an example of User confirmation API

KakaoStoryService.getInstance().requestIsStoryUser(new MyKakaoStoryHttpResponseHandler<KakaoStoryCheckUser>() {
    @Override
    protected void onHttpSuccess(final KakaoStoryCheckUser kakaoStoryCheckUser) {
        Toast.makeText(getApplicationContext(), "succeeded to check story user : " + kakaoStoryCheckUser.isStoryUser(), Toast.LENGTH_SHORT).show();
    }
});

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.

Make KakaoStoryService#requestProfile(KakaoStoryHttpResponseHandler<KakaoStoryProfile>) API call. If you wish to receive image url in https, call KakaoStoryService.html#requestProfile(KakaoStoryHttpResponseHandler<KakaoStoryProfile>, Boolean) API Following is an exmaple for requesting Kakaostory profile.

public void readProfile() {
    KakaoStoryService.getInstance().requestProfile(new MyStoryHttpResponseHandler<KakaoStoryProfile>() {
        @Override
        protected void onHttpSuccess(final KakaoStoryProfile storyProfile) {
              final String nickName = storyProfile.getNickName();
              final String profileImageURL = storyProfile.getProfileImageURL();
              final String thumbnailURL = storyProfile.getThumbnailURL();
              final String backgroundURL = storyProfile.getBgImageURL();
              final Calendar birthday = storyProfile.getBirthdayCalendar();
              final BirthdayType birthDayType = storyProfile.getBirthdayType();
              // display
        }
    }
}

For details on MyStoryHttpResponseHandler, refer getting started.

For success result, KakaoStoryProfile, provided information is described as below.

Element description Methods
NickName KakaoStory nickname String. getNickName()
Profile Image URL Size of KakaoStory profile image URL is 480px * 480px ~ 1024px * 1024px getProfileImageURL()
Profile thumbnail URL Size of KakaoStory profile thumbnail URL is 160px * 213px getThumbnailURL()
Background ImageURL Size of KakaoStory background image URL is 480px * 480px ~ 1024 * 1024px getBgImageURL()
Birthday offering only month and day, not year.
KakaoStory birthday - MMdd format : getBirthday()
KakaoStory birthday - Calendar format : getBirthdayCalendar()
Birthday Type KakaoStory birthday type enum
BirthdayType define whether lunar or solar Calendar
getBirthdayType()

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 of the required element type, when posting, is explained here. Explanation on regarding required element by type will be introduced in session.

Element description default methods
permission Define allowance on who can view my post. Visible to anyone. setPermission(com.kakao.PERMISSION)
Sharing policy Define if others can share my post. Enable share. setShareable(boolean)
URL parameters of Linking to App button 스토리 상세보기 하단에 포스팅 출처 앱 이름 클릭시 이동하는 URL에 붙일 파라미터.
특정 파라미터를 같이 전달하면 포스팅별로 다른 URL 사용 가능.
해당 실행 URL이 존재하지 않으면 마켓 URL로 이동.
없음 setAndroidExecuteParam(String)
setIOSExecuteParam(String)
setAndroidMarketParam(String)
setIOSMarketParam(String)
  • Launch URL
    • Default value is kakao[appkey]: For details about KakaoStory custom scheme, please refer to before getting started.
  • Market URL
    • Default Android market URL : market://details?id=[android package name]
      • Android App market URL is set in settings > general > Platform > Android > market URL.
    • Default iOS market URL : https://itunes.apple.com/app/id[Appstore ID]
      • iOS market URL is set in settings > general > platform > iOS > iPhone market URL (If iPad app exists, set through iPad market URL).
    • If market URL is not set, and app is not installed on device, there will be no response upon clicking the link.
      • If only Android app exists and if it is not set through Setting > General > Platform > iOS, there will be no event upon clicking app redirection button in iPhone kakaostory.

Note Posting

Setting required parameter by using NoteKakaoStoryPostParamBuilder. // NoteKakaoStoryPostParamBuilder, request KakaoStoryService#requestPost(com.kakao.KakaoStoryService.StoryType.Note,com.kakao.KakaoStoryHttpResponseHandler<MyStoryInfo>, android.os.Bundle) API.

Elements Descriptions Default Methods
Text(content) Contents to post.
Restricted to 2048 characters(char).
This is required field. KakaoParameterException error will occur.
None. NoteKakaoStoryPostParamBuilder(String)

MyStoryInfo tells whether it succeeded which includes posting id.

Following is an exmaple for requesting to post article.

    private void requestPostNote(final String storyContent) {
        final NoteKakaoStoryPostParamBuilder postParamBuilder
            = new NoteKakaoStoryPostParamBuilder(storyContent);
        try {
            final Bundle parameters = postParamBuilder.build();
            KakaoStoryService.getInstance().requestPost(
                StoryType.Note,
                new MyKakaoStoryHttpResponseHandler<MyStoryInfo>() {
                    @Override
                    protected void onHttpSuccess(final MyStoryInfo myStoryInfo) {
                        if(myStoryInfo.getId() != null) {
                            // Success
                        } else{
                            // Failure
                        }
                    }
                },
                parameters);
        } catch (KakaoParameterException e) {
            // Parameter error occur
        }
    }

Following is an result example.

story_post_note.png

Posting photo

1. In order to post photo, API must be called in KakaoStoryService#requestMultiUpload(com.kakao.KakaoStoryHttpResponseHandler<String[]>, List<java.io.File>). If upload is successful, photos will be posted with image URL.

Following is an exmaple for requesting to upload image.

private void uploadImage(final List<File> files) {
    try {
        KakaoStoryService.getInstance().requestMultiUpload(new MyKakaoStoryHttpResponseHandler<String[]>() {
            @Override
            protected void onHttpSuccess(final String[] imageURLs) {
                if(imageURLs != null && imageURLs.length != 0)  {
                    // Success
                    // Continue posting photo
                    requestPostPhoto(imageURLs);
                } else {
                    // Failure
                }
            }
        }, files);
    } catch (Exception e) {
        // Failure to upload image.
    }
}

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.

2. Setting required parameter by using PhotoKakaoStoryPostParamBuilder, request KakaoStoryService#requestPost(com.kakao.KakaoStoryService.StoryType.PHOTO, com.kakao.KakaoStoryHttpResponseHandler<MyStoryInfo>, android.os.Bundle) API.

Element Descriptions Default Methods
Image Result of uploaded image, which should be included in posting.
This is required value which means KakaoParameterException will occur if no image is included.
None. PhotoKakaoStoryPostParamBuilder(com.kakao.String[])
Text(content) Description of image being posted.
Restricted to 2048 characters(char).
Selection value
None. setContent(String)

MyStoryInfo tells whether event has succeeded with posting id included.

This is an example of posting photo.

    private void requestPostPhoto(final String[] imageURLs, final String storyContent) {
        final PhotoKakaoStoryPostParamBuilder postParamBuilder
            = new PhotoKakaoStoryPostParamBuilder(imageURLs);
        postParamBuilder.setContent(storyContent);
        try {
            final Bundle parameters = postParamBuilder.build();
            KakaoStoryService.getInstance().requestPost(
                StoryType.PHOTO,
                new MyKakaoStoryHttpResponseHandler<MyStoryInfo>() {
                    @Override
                    protected void onHttpSuccess(final MyStoryInfo myStoryInfo) {
                        if(myStoryInfo.getId() != null) {
                            // Success
                        } else{
                            // Failure
                        }
                    }
                },
                parameters);
        } catch (KakaoParameterException e) {
            // Parameter error occur
        }
    }

Following is an result example.

story_post_photo.png

1. In order to post a link KakaoStoryService#requestGetLinkInfo(com.kakao.KakaoStoryHttpResponseHandler<KakaoStoryLinkInfo>, String) API will be called. Result regarding success KakaoStoryLinkInfo which offers preview.

Below is an example of retrieving information through scrapping and posting its link.

    private void getLinkInfo(final String scrapUrl) {
        KakaoStoryService.getInstance().requestGetLinkInfo(new MyKakaoStoryHttpResponseHandler<KakaoStoryLinkInfo>() {
            @Override
            protected void onHttpSuccess(final KakaoStoryLinkInfo kakaoStoryLinkInfo) {
                if (kakaoStoryLinkInfo != null && kakaoStoryLinkInfo.isValidResult()) {
                    // Success
                    // Continue posting link
                    equestPostLink(kakaoStoryLinkInfo);
                } else {
                    // Failure
                }
            }
        }, scrapUrl);
    }

2. Setting required parameter by using LinkKakaoStoryPostParamBuilder, request KakaoStoryService#requestPost(com.kakao.KakaoStoryService.StoryType.LINK, com.kakao.KakaoStoryHttpResponseHandler<MyStoryInfo>, android.os.Bundle) API.

Element Descriptions Default Methods
Scrap information Link scrap result.
This is required field which means if either url or host does not exists, KakaoParameterException will occur.
None. LinkKakaoStoryPostParamBuilder(
    com.kakao.KakaoStoryLinkInfo)
Text(content) Info about scrap which will be included in posting.
Restricted to 2048 characters(char).
selected value.
None. setContent(String)

Result regarding success MyStoryInfo which includes posting id.

Following is an exmaple for requesting to posting link.

    private void requestPostLink(final KakaoStoryLinkInfo kakaoStoryLinkInfo, final String storyContent) {
        final LinkKakaoStoryPostParamBuilder postParamBuilder
            = new LinkKakaoStoryPostParamBuilder(kakaoStoryLinkInfo);
        postParamBuilder.setContent(storyContent);
        try {
            final Bundle parameters = postParamBuilder.build();
            KakaoStoryService.getInstance().requestPost(
                StoryType.LINK,
                new MyKakaoStoryHttpResponseHandler<MyStoryInfo>() {
                    @Override
                    protected void onHttpSuccess(final MyStoryInfo myStoryInfo) {
                        if(myStoryInfo.getId() != null) {
                            // Success
                        } else{
                            // Failure
                        }
                    }
                },
                parameters);
        } catch (KakaoParameterException e) {
            // Parameter error occur
        }
    }

Following is an result example.

story_post_link.png

MyStory information request

Can request information regarding posts they have made if user has credential in KakaoStory(registered as user in KakaoStory). In order to use this call, it is required to obtain user token after successful login. Currently, only mystory information of posts and photo types are valid. For other types, only their character contents are available to be included.

Success result will be provided as MyStoryInfo, and information follows.

Element Descriptions Methods
Post id(ID) Unique id, which is result returned as result of posting. getId()
Story web URL URL that links storyweb to posting. getUrl()
Media type Media type enum.
StoryType
getMediaType()
Created At RFC3339 internet date/time format. getCreatedAt()
Content Of story structure, this contains the text part. getContent()
Image URL list Only valid in PHOTO Story.
Array of MyStoryImageInfo includes image URL ordered by size.
getMedias()
Comment count Reply counts for post. getCommentCount()
Like count Like counts for post. getLikeCount()
Comment information Only offer in Requesting single mystory.
Reply info for post
Array of StoryComment
getComments()
Like information Only offer in Requesting single mystory.
Like information for the post.
Array of StoryLike
getLikes()
공개 범위 하나의 내스토리 요청에서만 제공.
해당 포스트의 공개 범위 enum. 예) 전체공개, 친구공개, 나만보기
StoryPermission의 enum
getPermission()

Requesting single mystory information

Set post id of requesting mystory, and call API KakaoStoryService#requestGetMyStories(com.kakao.KakaoStoryHttpResponseHandler<MyStoryInfo>, android.os.Bundle).

Element Descriptions Default Methods
Mystory id Post id of requesting information.
This is a required field which means, without it, will cause KakaoParameterException.
None. KakaoStoryMyStoryParamBuilder(String)
    private void getMyStory(final String myStoryId) {
        try {
            final Bundle parameters = new KakaoStoryMyStoryParamBuilder(myStoryId).build();
            KakaoStoryService.getInstance().requestGetMyStory(new MyKakaoStoryHttpResponseHandler<MyStoryInfo>() {
                @Override
                protected void onHttpSuccess(final MyStoryInfo myStoryInfo) {
                    if(myStoryId.equals(myStoryInfo.getId())) {
                        // Success
                    } else {
                        // Failure
                    }

                }
            }, parameters);
        } catch (KakaoParameterException e) {
             // Parameter error occur
        }
    }

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)

Set last mystory id(postid), or set no id in order to retrieve most recent one,and call KakaoStoryService#requestGetMyStories(com.kakao.KakaoStoryHttpResponseHandler<MyStoryInfo[]>, android.os.Bundle) API.

Element Descriptions Default Methods
Mystory id Last post id for information.
Returns multiple created mystory of stories previous to Mystory with id set in the element.
Result will not return Mystory with this post id set(Only previously created mystory with postid)
Post id with most recently edited KakaoStoryMyStoriesParamBuilder(String)
private void getMyStories(final String lastMyStoryId) {
    final Bundle parameters = new KakaoStoryMyStoriesParamBuilder(lastMyStoryId).build();
    KakaoStoryService.getInstance().requestGetMyStories(new MyKakaoStoryHttpResponseHandler<MyStoryInfo[]>() {
        @Override
        protected void onHttpSuccess(final MyStoryInfo[] myStories) {
            // Success
        }
    }, parameters);
}

Delete mystory

User can delete his or her story, posted personally, if user has credential in KakaoStory(registered as user in KakaoStory). In order to use this call, it is required to obtain user token after successful login. Set targeted mystory id(Post id), and call KakaoStoryService#requestDeleteMyStory(com.kakao.KakaoStoryHttpResponseHandler<Void>, android.os.Bundle) API.

Element Descriptions Default Methods
Mystory id Post id of mystory to be deleted.
This is a required field which means, without it, will cause KakaoParameterException.
None. KakaoStoryMyStoryParamBuilder(String)
    private void requestDeleteMyStory(final String myStoryId) {
        try {
            final Bundle parameters = new KakaoStoryMyStoryParamBuilder(myStoryId).build();
            KakaoStoryService.getInstance().requestDeleteMyStory(new MyKakaoStoryHttpResponseHandler<Void>() {
                @Override
                protected void onHttpSuccess(Void resultObj)) {
                    // Success
                }
            }, parameters);
        } catch (KakaoParameterException e) {
             // Parameter error occur
        }
    }

TroubleShooting

For troubleshooting, please follow KakaoStory troubleshooting.


Last Modified : 2018-03-19