Kakao Developers

페이지 이동경로

문서>
카카오스토리>
JavaScript

카카오스토리

JavaScript

이 문서는 Kakao SDK for JavaScript(이하 JavaScript SDK)를 사용한 카카오스토리 기능 구현 방법을 안내합니다.

JavaScript SDK는 Android, iOS SDK와 달리 카카오스토리 공유 기능을 웹뷰 형태로 제공합니다. 사용자는 카카오 로그인 후 웹 페이지에 삽입된 공유 버튼을 클릭해 스토리를 쓰거나 웹 페이지 정보를 공유할 수 있습니다.

이 문서에 포함된 기능 일부는 [도구] > [JS 데모]를 통해 사용해 볼 수 있습니다.

사용자 확인하기

기본 정보

권한	사전 설정	카카오 로그인	사용자 동의	레퍼런스
-	플랫폼 등록 카카오 로그인 활성화 동의 항목	필요	-	`request()`

현재 로그인한 사용자가 카카오스토리를 사용하고 있는지 확인합니다. 카카오스토리 미사용으로 인한 에러를 방지할 수 있습니다.

url 값을 /v1/api/story/isstoryuser로 지정해 Kakao.API.request() 함수를 호출합니다. Kakao.API.request()는 Promise를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.

파라미터

이름	타입	설명	필수
url	`String`	`/v1/api/story/isstoryuser` 로 고정	O

예제

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

프로필 가져오기

기본 정보

권한	사전 설정	카카오 로그인	사용자 동의	레퍼런스
-	플랫폼 등록 카카오 로그인 활성화 동의 항목	필요	필요: 프로필 정보(닉네임/프로필 사진) 닉네임 프로필 사진 카카오스토리 프로필 URL	`request()`

현재 로그인한 사용자의 카카오스토리 프로필을 불러옵니다.

사용자는 카카오계정, 카카오톡, 카카오스토리에 각각 프로필을 설정할 수 있으므로, 카카오스토리 프로필 가져오기 API로 불러온 프로필은 사용자 정보나 카카오톡 프로필 가져오기 API로 조회한 정보와 별개입니다.

url 값을 /v1/api/story/profile로 지정해 Kakao.API.request() 함수를 호출합니다. Kakao.API.request()는 Promise를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.

파라미터

이름	타입	설명	필수
url	`String`	`/v1/api/story/profile` 로 고정	O

예제

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

스토리 쓰기

현재 로그인한 사용자의 카카오스토리에 새로운 스토리를 작성합니다.

스토리 종류

스토리 쓰기는 다음 세 가지 종류의 API를 제공합니다.

타입	설명	URL
글(Note)	텍스트로 구성된 스토리	`/v1/api/story/post/note`
사진(Photo)	텍스트와 사진으로 구성된 스토리	`/v1/api/story/post/photo`
링크(Link)	텍스트와 스크랩할 웹 페이지에서 얻은 정보로 구성된 스토리	`/v1/api/story/post/link`

작성하려는 스토리의 종류에 따라 전달해야 할 파라미터가 다릅니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.

글 스토리 쓰기

기본 정보

권한	사전 설정	카카오 로그인	사용자 동의	레퍼런스
-	플랫폼 등록 카카오 로그인 활성화 동의 항목	필요	필요: 카카오스토리 글 작성(story_publish)	`request()`

사진이나 웹 페이지 URL 등 다른 요소 없이 글로만 구성된 스토리를 게시할 때 사용합니다.

url 값을 /v1/api/story/post/note로 지정해 Kakao.API.request() 함수를 호출합니다. 글 스토리 쓰기 시, 스토리 내용 텍스트를 담은 data 하위의 content 파라미터를 필수 전달해야 합니다.

파라미터

이름	타입	설명	필수
url	`String`	`/v1/api/story/post/note` 로 고정	O
data	`Object`	API에 전달할 파라미터	O

data: 글 스토리 쓰기

이름	타입	설명	필수
content	`String`	스토리에 들어갈 글, 2048자(char) 미만으로 제한	O
permission	`String`	스토리 공개 범위 `F`: 친구에게만 공개 `A`: 전체 공개 `M`: 나만 보기 (기본값: `A`)	X
enable_share	`Boolean`	친구 공개 스토리인 경우 공유 설정 (기본값: `false`)	X
android_exec_param	`String`	스토리의 [해당 앱으로 이동] 버튼을 눌렀을 때 Android 앱 실행 URL에 붙일 파라미터	X
ios_exec_param	`String`	스토리의 [해당 앱으로 이동] 버튼을 눌렀을 때 iOS 앱 실행 URL에 붙일 파라미터	X
android_market_param	`String`	스토리에서 오픈마켓으로 이동할 때 실행 URL에 붙일 파라미터	X
ios_market_param	`String`	스토리에서 앱스토어로 이동할 때 실행 URL에 붙일 파라미터	X

예제

Kakao.API.request({
  url: '/v1/api/story/post/note',
  data: {
    content: '스토리에 들어갈 글을 작성해주세요.',
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

사진 스토리

기본 정보

권한	사전 설정	카카오 로그인	사용자 동의	레퍼런스
-	플랫폼 등록 카카오 로그인 활성화 동의 항목	필요	필요: 카카오스토리 글 작성(story_publish)	`request()`

사진과 글로 구성된 스토리를 게시할 때 사용합니다.

주의: 이미지 URL

사진 스토리 쓰기 요청 시 이미지 업로드하기를 통해 구한 URL만 사용할 수 있습니다. 임의의 데이터 전달 시 요청에 실패합니다.

이미지 업로드하기 API를 통해 스토리 쓰기에 사용할 이미지를 카카오 플랫폼에 업로드하여 이미지의 경로와 크기 정보를 구할 수 있습니다. 업로드할 이미지의 크기는 10MB 이하, 갯수는 10개 이하여야 합니다. 단, GIF 파일은 1개만 올릴 수 있습니다.

이미지를 업로드하려면 url 값을 /v1/api/story/upload/multi로 지정해 Kakao.API.request() 함수를 호출합니다. 이미지 업로드에 성공하면 사진 스토리 쓰기 API를 호출하는 함수를 호출합니다.

사진 스토리 쓰기 API는 url값을 /v1/api/story/post/photo로 지정해 Kakao.API.request() 함수로 호출합니다. 글 스토리 쓰기 시, 스토리 내용 텍스트를 담은 content는 선택 파라미터이나, 스토리에 첨부할 이미지 정보를 담은 image_url_list 파라미터는 필수로 전달해야 합니다.

Kakao.API.request()는 Promise를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.

파라미터

이름	타입	설명	필수
url	`String`	이미지 업로드하기: `/v1/api/story/upload/multi`로 고정 사진 스토리쓰기: `/v1/api/story/post/photo` 로 고정	O
data	`Object`	API에 전달할 파라미터 자세한 내용은 data: 이미지 업로드하기, data: 사진 스토리 쓰기 확인	O

data: 이미지 업로드하기

이름	타입	설명	필수
files	`FileList \| File[]`	`<input>` 태그를 통해 입력된 업로드할 `File` 객체 목록	O

data: 사진 스토리 쓰기

이름	타입	설명	필수
image_url_list	`String[]`	이미지 업로드하기 API를 통해 얻은 이미지들의 경로와 이미지의 가로와 세로 길이	O
content	`String`	스토리에 들어갈 글, 2048자(char) 미만으로 제한	X
permission	`String`	스토리 공개 범위 `F`: 친구에게만 공개 `A`: 전체 공개 `M`: 나만 보기 (기본값: `A`)	X
enable_share	`Boolean`	친구 공개 스토리인 경우 공유 설정 (기본값: `false`)	X
android_exec_param	`String`	스토리의 [해당 앱으로 이동] 버튼을 눌렀을 때 Android 앱 실행 URL에 붙일 파라미터	X
ios_exec_param	`String`	스토리의 [해당 앱으로 이동] 버튼을 눌렀을 때 iOS 앱 실행 URL에 붙일 파라미터	X
android_market_param	`String`	스토리에서 오픈마켓으로 이동할 때 실행 URL에 붙일 파라미터	X
ios_market_param	`String`	스토리에서 앱스토어로 이동할 때 실행 URL에 붙일 파라미터	X

예제

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);
  });

링크 스토리

기본 정보

권한	사전 설정	카카오 로그인	사용자 동의	레퍼런스
-	플랫폼 등록 카카오 로그인 활성화 동의 항목	필요	필요: 카카오스토리 글 작성(story_publish)	`request()`

웹 페이지를 공유하는 스토리를 게시합니다.

주의: 웹 페이지 스크랩 정보

링크 스토리 쓰기 요청 시 웹 페이지 스크랩하기 API를 통해 구한 웹 페이지 스크랩 정보만 사용할 수 있습니다. 임의의 데이터 전달 시 요청에 실패합니다.

링크 스토리 쓰기 API 호출 전, 웹 페이지 스크랩하기 API를 호출하여 스토리에 사용할 웹 페이지 정보를 미리 스크랩해야 합니다. url 값을 /v1/api/story/linkinfo로 지정해 Kakao.API.request() 함수를 호출합니다. 웹 페이지는 오픈 그래프 프로토콜(Open Graph Protocol)을 기반으로 스크랩합니다.

웹 페이지 스크랩 성공 시, 링크 스토리 쓰기 API를 호출할 수 있습니다. url 값을 /v1/api/story/post/link로 지정해 Kakao.API.request() 함수를 호출합니다. 스토리 내용 텍스트를 담은 content는 선택 파라미터이나, 스토리에 첨부할 링크 정보를 담은 link_info 파라미터는 필수로 전달해야 합니다.

Kakao.API.request()는 Promise를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.

파라미터

이름	타입	설명	필수
url	`String`	웹 페이지 스크랩하기: `/v1/api/story/linkinfo`로 고정 링크 스토리 쓰기: `/v1/api/story/post/link`로 고정	O
data	`Object`	API에 전달할 파라미터 자세한 내용은 data: 웹 페이지 스크랩하기, data: 링크 스토리 쓰기 확인	O

data: 웹 페이지 스크랩하기

이름	타입	설명	필수
url	`String`	스크랩할 웹 페이지 URL	O

data: 링크 스토리 쓰기

이름	타입	설명	필수
link_info	`Object`	웹 페이지 스크랩하기 API를 통해 얻은 스크랩할 웹 페이지 정보	O
content	`String`	스토리에 들어갈 글, 2048자(char) 미만으로 제한	X
permission	`String`	스토리 공개 범위 `F`: 친구에게만 공개 `A`: 전체 공개 `M`: 나만 보기 (기본값: `A`)	X
enable_share	`Boolean`	친구 공개 스토리인 경우 공유 설정 (기본값: `false`)	X
android_exec_param	`String`	스토리의 [해당 앱으로 이동] 버튼을 눌렀을 때 Android 앱 실행 URL에 붙일 파라미터	X
ios_exec_param	`String`	스토리의 [해당 앱으로 이동] 버튼을 눌렀을 때 iOS 앱 실행 URL에 붙일 파라미터	X
android_market_param	`String`	스토리에서 오픈마켓으로 이동할 때 실행 URL에 붙일 파라미터	X
ios_market_param	`String`	스토리에서 앱스토어로 이동할 때 실행 URL에 붙일 파라미터	X

link_info

이름	타입	설명
url	`String`	스크랩한 웹 페이지 URL 단축 URL의 경우 실제 URL
requested_url	`String`	요청 시 전달된 URL
host	`String`	URL Host
title	`String`	웹 페이지 타이틀
image	`String[]`	웹 페이지의 대표 이미지 URL, 최대 3개
description	`String`	웹 페이지 설명
type	`String`	웹 페이지가 포함한 콘텐츠 타입 정보 website, video, music 등
section	`String`	웹 페이지 섹션 정보

예제

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);
  });

스토리 가져오기

현재 로그인한 사용자의 카카오스토리에서 스토리 목록을 불러옵니다.

다음 두 가지 방법으로 스토리를 가져올 수 있습니다.

여러 개의 스토리 가져오기를 통해 최근 스토리 정보 받아 특정 스토리를 스토리 ID로 지정하여 스토리 정보 받기
여러 개의 스토리 가져오기를 통해 최근 스토리 정보 받기

스토리 가져오기 요청 시 하나의 스토리를 요청하는지, 여러 개의 스토리를 요청하는지에 따라 전달해야 할 파라미터가 다릅니다.

여러 스토리 가져오기

기본 정보

권한	사전 설정	카카오 로그인	사용자 동의	레퍼런스
-	플랫폼 등록 카카오 로그인 활성화 동의 항목	필요	필요: 카카오스토리 글 작성(story_publish)	`request()`

여러 개의 스토리를 요청합니다.

last_id 파라미터를 지정하면 특정 스토리부터 그 이전 정보를 가져올 수 있습니다. 요청 성공 시, 응답에는 댓글(comments)과 느낌(likes) 수가 포함됩니다.

url 값을 /v1/api/story/mystories로 지정해 Kakao.API.request() 함수를 호출합니다. Kakao.API.request()는 Promise를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.

파라미터

이름	타입	설명	필수
url	`String`	`/v1/api/story/mystories` 로 고정	O
data	`Object`	API에 전달할 파라미터	X

data: 여러 개의 스토리 가져오기

이름	타입	설명	필수
last_id	`String`	정보를 원하는 마지막 스토리 아이디 해당 스토리를 제외하고, 그 이전에 작성된 스토리 정보가 제공됨 기본 값은 가장 최근 작성된 스토리 아이디 파라미터 미포함 시 가장 최근 스토리 정보부터 제공	X

예제

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

특정 스토리 가져오기

기본 정보

권한	사전 설정	카카오 로그인	사용자 동의	레퍼런스
-	플랫폼 등록 카카오 로그인 활성화 동의 항목	필요	필요: 카카오스토리 글 목록(story_read)	`request()`

하나의 스토리를 지정해 요청합니다.

스토리 ID를 필수 전달해야 합니다. 특정 스토리 ID를 지정하여 요청하면 해당 스토리의 댓글을 포함한 상세 정보를 받을 수 있습니다.

url 값을 /v1/api/story/mystory로 지정해 Kakao.API.request() 함수를 호출합니다. Kakao.API.request()는 Promise를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.

파라미터

이름	타입	설명	필수
url	`String`	`/v1/api/story/mystory` 로 고정	O
data	`Object`	API에 전달할 파라미터	O

data: 하나의 스토리 가져오기

이름	타입	설명	필수
id	`String`	정보를 원하는 스토리 아이디	O

예제

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

내 스토리 삭제하기

기본 정보

권한	사전 설정	카카오 로그인	사용자 동의	레퍼런스
-	플랫폼 등록 카카오 로그인 활성화 동의 항목	필요	필요: 카카오스토리 글 목록(story_read)	`request()`

현재 로그인한 사용자의 카카오스토리에서 지정한 ID에 해당하는 스토리를 삭제합니다.

삭제할 스토리 게시물의 ID를 알고 있어야 요청 가능하므로, 내 스토리 가져오기 또는 스토리 쓰기 요청을 통해 해당 스토리의 ID를 확인하거나, 참고할 수 있는 스토리 ID 값이 있어야 합니다.

url 값을 /v1/api/story/delete/mystory로 지정해 Kakao.API.request() 함수를 호출합니다. Kakao.API.request()는 Promise를 반환합니다. 요청 성공 시 반환 내용은 REST API를 참고합니다.

파라미터

이름	타입	설명	필수
url	`String`	`/v1/api/story/delete/mystory` 로 고정	O
data	`Object`	API에 전달할 파라미터	O

data: 내 스토리 삭제하기

이름	타입	설명	필수
id	`String`	삭제할 스토리 ID	O

예제

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);
  });

공유 버튼 추가하기

기본 정보

권한	사전 설정	카카오 로그인	사용자 동의	레퍼런스
-	플랫폼 등록	-	-	`createShareButton()`

웹 페이지에 카카오스토리 공유 버튼을 추가하는 기능입니다. Kakao.Story.createShareButton()을 호출하면 버튼을 생성합니다 해당 버튼을 클릭하면 공유하기 웹뷰(Web view)를 띄우는 기능이 추가됩니다. container 파라미터로 카카오스토리 공유 버튼이 나타날 위치를 지정합니다.

공유하기 버튼 만들기

[도구] > [소셜 플러그인] 메뉴에서 내 웹 페이지에 맞춘 크기의 카카오스토리 공유하기 버튼과 소스코드를 손쉽게 만들어 쓸 수 있습니다.

파라미터

이름	타입	설명	필수
container	`String`	카카오스토리 공유하기 버튼을 추가할 위치의 Element ID	O
url	`String`	카카오스토리에 공유할 웹 페이지 URL	O
text	`String`	공유하기 웹뷰(Webview)에 자동으로 입력되도록 할 본문 내용	O

예제

Kakao.Story.createShareButton({
  container: '#kakaostory-share-button',
  url: 'https://developers.kakao.com',
  text: '카카오 개발자 사이트로 놀러오세요! #개발자 #카카오 :)',
});

공유하기 화면 띄우기

기본 정보

권한	사전 설정	카카오 로그인	사용자 동의	레퍼런스
-	플랫폼 등록	-	-	`share()`

카카오스토리에 새로운 스토리를 쓰는 웹뷰를 띄우는 기능입니다. 공유 버튼 클릭 시 Kakao.Story.share()를 호출합니다. 사용자가 공유 버튼을 클릭하면 카카오 로그인 웹뷰가 나타나고, 로그인 후 공유하기 웹뷰가 나타납니다. 만약 이미 로그인한 상태라면 바로 공유하기 웹뷰를 띄웁니다.

파라미터

이름	타입	설명	필수
url	`String`	카카오스토리에 공유할 웹 페이지 URL	O
text	`String`	공유하기 웹뷰(Webview)에 자동으로 입력되도록 할 본문 내용	O

예제

Kakao.Story.share({
  url: 'https://developers.kakao.com',
  text: '카카오 개발자 사이트로 놀러오세요! #개발자 #카카오 :)',
});

카카오스토리 앱으로 공유하기

기본 정보

권한	사전 설정	카카오 로그인	사용자 동의	레퍼런스
-	플랫폼 등록	-	-	`open()`

Kakao.Story.open()을 호출하면 카카오스토리 앱을 통해 지정한 웹 페이지를 공유할 수 있습니다. 웹 페이지 정보는 오픈 그래프 프로토콜(Open Graph Protocol) 기반으로 스크랩합니다.

이 API는 특정 정보를 카카오스토리 앱에 전달해 보다 쉽게 공유할 수 있도록 도와주는 기능입니다. 사용자가 웹 페이지를 공유 완료했는지는 알려주지 않습니다.

파라미터

이름	타입	설명	필수
url	`String`	공유할 웹 페이지 URL	O
text	`String`	공유하기 웹뷰(Webview)에 자동으로 입력되도록 할 본문 내용	O
urlInfo	`UrlInfoObject`	웹 페이지를 스크랩한 정보	X

UrlInfoObject

이름	타입	설명	필수
title	`String`	웹 페이지 타이틀	O
desc	`String`	웹 페이지 설명	X
name	`String`	웹 페이지 이름	X
images	`String[]`	웹 페이지 대표 이미지 URL	X

예제

Kakao.Story.open({
  url: 'http://blog.kakaocorp.co.kr/390',
  text: '카카오검색에서 카카오스토리를! #카카오스토리 #카카오검색 :)',
});

소식 받기

기본 정보

권한	사전 설정	카카오 로그인	사용자 동의	레퍼런스
-	플랫폼 등록	-	-	`createFollowButton()`

사용자가 특정 카카오스토리 채널의 소식을 받을 수 있도록 하는 기능입니다. 소식 받기 버튼을 배치할 위치에서 Kakao.Story.createFollowButton()를 호출합니다. container 위치에 구독 버튼이 생성되며, 버튼 클릭 시 카카오 JavaScript SDK가 로그인한 사용자 정보로 id에 해당하는 카카오스토리 채널에 구독 요청을 보냅니다.

이 기능은 로그인한 사용자 정보로 구독 요청을 보내는 방식으로 동작합니다. 따라서 사용자가 로그인되어 있지 않다면 카카오 로그인 웹뷰를 통해 먼저 로그인하는 과정을 거칩니다.

파라미터

이름	타입	설명	필수
container	`String`	버튼을 추가할 위치의 Element ID	O
id	`String`	소식 받기할 카카오스토리 채널 ID	O
showFollowerCount	`String`	해당 채널 구독자 수 'container' Element의 data-show-follower-count Attribute로 대신할 수 있음	X
type	`String`	구독자 수 노출 형태 'container' Element의 data-type Attribute로 대신할 수 있음	X

예제

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

Legacy

카카오스토리의 Legacy Kakao SDK for JavaScript(이하 Legacy JavaScript SDK) 개발 가이드는 다음 링크에서 확인할 수 있습니다. 추후 Legacy JavaScript SDK에 대한 지원이 중단될 수 있으므로, 가급적 빠른 시일 내에 최신 버전 JavaScript SDK로 변경할 것을 권장합니다.

menu

시작하기

로그인

커뮤니케이션

지도/로컬

내비게이션

검색

인공지능

광고

결제

더 보기

카카오스토리

JavaScript

사용자 확인하기

기본 정보

파라미터

예제

프로필 가져오기

기본 정보

파라미터

예제

스토리 쓰기

스토리 종류

글 스토리 쓰기

기본 정보

파라미터

data: 글 스토리 쓰기

예제

사진 스토리

기본 정보

파라미터

data: 이미지 업로드하기

data: 사진 스토리 쓰기

예제

링크 스토리

기본 정보

파라미터

data: 웹 페이지 스크랩하기

data: 링크 스토리 쓰기

link_info

예제

스토리 가져오기

여러 스토리 가져오기

기본 정보

파라미터

data: 여러 개의 스토리 가져오기

예제

특정 스토리 가져오기

기본 정보

파라미터

data: 하나의 스토리 가져오기

예제

내 스토리 삭제하기

기본 정보

파라미터

data: 내 스토리 삭제하기

예제

공유 버튼 추가하기

기본 정보

파라미터

예제

공유하기 화면 띄우기

기본 정보

파라미터

예제

카카오스토리 앱으로 공유하기

기본 정보

파라미터

UrlInfoObject

예제

소식 받기

기본 정보

파라미터

예제

Legacy

더 보기