search

plusfriend / auto_reply

플러스친구 자동응답 API
308 stars 94 forks source link

readme

[안내] 카카오 i 오픈빌더(챗봇 빌더 플랫폼) 문의하기

카카오 i 오픈빌더(https://i.kakao.com) 에 대한 문의는 kakao i developers DevTak(https://i.kakao.com/forum) 에서 받고 있습니다. 카카오 i 오픈빌더를 통한 챗봇 제작 관련 문의는 kakao i developers DevTak에 해주시면 감사하겠습니다.

[공지] 2019년 12월 31일 API형 스마트채팅 서비스가 종료되었습니다.

안녕하세요. 카카오톡 채널팀입니다.
2019년 12월 31일 오전 11시 20분, 사전에 공지드린 대로 API형 스마트채팅 서비스가 종료되었습니다.
앞으로는 챗봇 제작을 위한 전문적인 플랫폼인 카카오 i 오픈빌더를 통해 대화형 인터페이스 챗봇을 제작할 수 있습니다.
해당 플랫폼을 통해 제작된 챗봇은 다양한 형태의 말풍선과 채팅방 내에서 바로 사용할 수 있는 결제, 예약, FAQ 등의 기능을 제공합니다.

Q. API형 스마트채팅으로 제작한 챗봇을 오픈빌더 챗봇으로 바꿀 수 있나요?

A. API형 스마트채팅으로 제작한 챗봇이 오픈빌더로 자동 이전 되거나 카카오가 해당 과정을 지원해 드리지는 않습니다.
오픈빌더를 통해 챗봇을 제작하기 위해서는 공식 에이전시 등을 통해 별도로 챗봇을 제작해야합니다.

Q. API형 스마트채팅으로 제작한 챗봇과 오픈빌더로 제작한 챗봇은 어떤 차이가 있나요?

A. API형 스마트채팅은 카카오가 무료로 지원하는 단순한 형태의 open API입니다.
해당 API를 통해서 제작된 챗봇은 단순한 형태의 기능과 말풍선 형태만을 지원하여 고도화된 챗봇 제작은 불가능 합니다.
반면, 오픈빌더는 챗봇 제작을 위한 전문적인 도구로, 해당 플랫폼을 통해 제작된 챗봇은 다양한 형태의 말풍선과
채팅방 내에서 바로 사용할 수 있는 결제, 예약, FAQ 등의 기능을 제공합니다.

Q. 카카오 공식 에이전시는 어디서 확인할 수 있나요?

A. 카카오 i developers 사이트에서 카카오 공식 에이전시를 소개하고 있습니다.

Q. 카카오 i 오픈빌더는 누구나 사용할 수 있나요?

A. 카카오 계정 이용자라면 누구나 카카오 i 오픈빌더 OBT 신청을 하실 수 있습니다.
OBT 신청이 접수되면 간단한 심사 단계를 거치게 되며, 1주일 이내에 개별적으로
카카오 계정의 이메일 주소로 심사/승인 결과를 안내해 드릴 예정입니다.

Q. 오픈빌더는 무료로 사용할 수 있나요?

A. OBT 기간 이후에는 유료화 될 수 있으며 이는 공지사항 등을 통해 별도로 안내될 예정입니다.

카카오톡 플러스친구 API v. 2.0 개요

이 문서는 플러스친구를 통하여 자동응답 기능을 이용하고자 할 때 사용되는 API에 대해 기술합니다.

1. 이용에 대한 참고사항

  1. 서버간 통신은 보안을 위하여 HTTPS를 쓰도록 권장합니다.
  2. HTTPS를 통하여 API를 이용하는 파트너사 서버는 유효한 공인인증서를 사용해야 합니다.
  3. user_key는 외부에 노출되지 않도록 주의해 주시기 바랍니다.
  4. 플러스친구 API 운영에 대한 정책 및 가이드라인은 플러스친구 이용약관의 API 플랫폼 운영정책을 참고해 주시기 바랍니다.

2. 개인정보 수집 및 이용에 대한 주의사항

  1. API 이용에 대한 주의사항은 서비스 이용약관 '제 26 조 API 플랫폼 서비스'를 따르며, 이를 준수하지 않을 경우 API 서비스 제공을 중단할 수 있습니다.
  2. 회원이 API 플랫폼 서비스를 이용하는 과정에서 이용자의 개인정보 수집이 필요한 경우, 이용자로부터 개인정보 수집 및 이용에 대한 명시적인 동의를 받아야 합니다.
  3. 카카오는 '개인정보 취급위탁 동의'에 따라 안전하게 개인정보 처리 업무를 진행합니다.

3. 이용 시작하기

3.1. 플러스친구 앱 생성

플러스친구에서 자동응답 기능을 사용하기 위해서는 먼저 운영툴을 통해 key 발급을 위한 앱을 등록해야 합니다.

  1. 플러스친구 운영툴의 좌측 '스마트채팅' 메뉴에서 'API형'을 선택합니다.
  2. 앱 정보와 모니터링 메시지를 수신할 전화번호를 입력하고, 개인정보 수집 및 이용에 동의한 뒤 정보를 저장하여 앱을 생성합니다.

3.2. 자동응답 서비스 시작

자동응답 서비스가 개발 완료되어 서비스 가능한 상태가 되면, 다음 단계에 따라 서비스를 시작할 수 있습니다.

  1. API TEST : 등록한 앱 url 우측의 API TEST 버튼을 클릭하여 서비스 시작 가능여부를 체크합니다. 필수 API인 Home Keyboard API가 정상적인 응답을 받지 못하는 경우 서비스 시작이 불가합니다.

  2. 서비스 시작 : API 테스트를 통과한 경우, 서비스 시작 버튼을 클릭하면 자동응답 서비스가 시작됩니다.

    • 기존에 (구) 플러스친구 API를 통해 사용중이던 봇이 있는 경우, 신규 API를 통해 자동응답 서비스를 시작하게 되면 (구)API를 이용한 봇은 자동으로 종료되며 다시 (구) 봇의 형태로 이용할 수 없습니다.
    • (구) 플러스친구에서 제공하던 테스트 플친은 더이상 제공되지 않습니다. 실서비스 적용 전 테스트를 원하시는 경우 테스트 전용으로 사용하실 별도의 플러스친구 계정을 생성하여 테스트를 진행해 주시기 바랍니다.
    • 신규 API 자동응답은 키워드형 자동응답과 동시에 사용할 수 없습니다. 다만 API 자동응답의 서비스 중지 후 키워드형 자동응답을 사용하는 것은 가능합니다.

3.3. 자동응답 서비스 중지

3.4. 클라이언트 테스트

자동응답 기능의 서비스가 시작되면 카카오톡 채팅방에서 직접 자동응답 기능을 실행할 수 있습니다. 신규 자동응답 API를 통한 자동응답 기능은 카카오톡 앱 안드로이드/iOS 5.4.0 버전부터 지원됩니다.

4. 용어 설명

4.1. 수신 API

4.2. app_key

4.3. app_secret

4.4. user_key

5. API specifications

5.1. Home Keyboard API

Specification
필드명 타입 필수여부 설명
keyboard Keyboard Required 키보드 영역에 표현될 버튼에 대한 정보. 생략시 text 타입이 선택된다.

5.2. 메시지 수신 및 자동응답 API

Specification
필드명 타입 필수여부 설명
user_key String Required 메시지를 발송한 유저 식별 키
type String Required text, photo
content String Required 자동응답 명령어의 메시지 텍스트 혹은 미디어 파일 uri
필드명 타입 필수여부 설명
message Message Required 자동응답 명령어에 대한 응답 메시지의 내용. 6.2에서 상세 기술
keyboard Keyboard Optional 키보드 영역에 표현될 명령어 버튼에 대한 정보. 생략시 text 타입(주관식 답변 키보드)이 선택된다. 6.1에서 상세 기술

5.3. 친구 추가/차단 알림 API

Specification
필드명 타입 필수여부 설명
user_key String Required 유저 식별키
http status code code message comment
200 0 SUCCESS 정상 응답

5.4. 채팅방 나가기

Specification
http status code code message comment
200 0 SUCCESS 정상 응답

6. Object

6.1. Keyboard
필드명 타입 필수여부 설명
type String Required buttons: 객관식 응답의 목록을 구성할 수 있음
text: 주관식 응답을 입력받을 수 있음
buttons Array[String] Optional 객관식 응답 내용의 목록
(최대 100개)		 
{
  "type": "buttons",
  "buttons": [
    "선택 1",
    "선택 2",
    "선택 3"
  ]
}
6.2. Message
필드명 타입 필수여부 설명
text String Optional 사용자에게 발송될 메시지 텍스트(최대 1000자)
photo Photo Optional 말풍선에 들어갈 이미지 정보. 1장 제한, JPEG/PNG 포맷. 6.3에서 상세 기술
message_button MessageButton Optional 말풍선에 붙는 링크버튼 정보. 6.2.1에서 상세 기술 
{
  "text": "안녕하세요.",
  "photo": {
    "url": "https://hello.photo.src",
    "width": 640,
    "height": 480
  },
  "message_button": {
    "label": "반갑습니다.",
    "url": "http://hello.world.com/example"
  }
}
6.2.1. MessageButton
필드명 타입 필수여부 설명
label String Required 링크버튼의 타이틀
url String Required 링크버튼의 연결 링크 주소 
{
  "label": "쿠폰확인하기",
  "url": "http://coupon.coupon.com/~~"
}
6.3. Photo
필드명 타입 필수여부 설명
url String Required 이미지 url
width Int Required 이미지 width
height Int Required 이미지 height

이미지 권장 사이즈 : 720 x 630px
지원 파일형식 및 권장 용량 : jpg, png /500KB

{
  "url": "https://photo.src",
  "width": 640,
  "height": 480
}

7. Server information

host port comment
https://ybot.kakao.com 443 https api server

7.1. Proxy Server information

카카오에서 파트너사 서버를 호출하는 경우 아래 3대의 proxy서버를 통하게 됩니다. 파트너사 방화벽 설정을 하게 될 경우 아래 3개의 IP에 대한 ACL을 허용해주시기 바랍니다.

IP
110.76.143.234
110.76.143.235
110.76.143.236

8. Response Code

Success Response
http status code code message comment
200 0 SUCCESS 정상 응답
Error Response
http status code code comment
400 100 bad request
400 201 wrong api key
400 202 wrong bot url
503 203 wrong message format
408 204 request timeout
408 204 wrong keyboard initialization
400 301 profile not found
400 302 user not found
400 303 not user friend
400 400 unsupported media type

9. 질의응답

상단의 issue를 통해 자유롭게 질의응답을 나누실 수 있습니다.

그외 문의사항은 카카오 고객센터로 주시기 바랍니다.