{"id":13726541,"url":"https://github.com/winterjung/chatterbox","last_synced_at":"2025-05-07T21:33:10.682Z","repository":{"id":62561836,"uuid":"117255469","full_name":"winterjung/chatterbox","owner":"winterjung","description":"Python library for Kakaotalk chatbot","archived":true,"fork":false,"pushed_at":"2020-01-05T08:39:07.000Z","size":230,"stargazers_count":77,"open_issues_count":3,"forks_count":16,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-10-31T13:45:14.205Z","etag":null,"topics":["chatbot","chatterbox","fsm","kakaotalk","kakaotalk-bot"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/winterjung.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-12T15:13:22.000Z","updated_at":"2024-10-09T02:22:09.000Z","dependencies_parsed_at":"2022-11-03T15:15:34.371Z","dependency_job_id":null,"html_url":"https://github.com/winterjung/chatterbox","commit_stats":null,"previous_names":["jungwinter/chatterbox"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/winterjung%2Fchatterbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/winterjung%2Fchatterbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/winterjung%2Fchatterbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/winterjung%2Fchatterbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/winterjung","download_url":"https://codeload.github.com/winterjung/chatterbox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224654309,"owners_count":17347721,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chatbot","chatterbox","fsm","kakaotalk","kakaotalk-bot"],"created_at":"2024-08-03T01:03:12.257Z","updated_at":"2024-11-14T16:34:06.259Z","avatar_url":"https://github.com/winterjung.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Chatterbox\n[![license]](/LICENSE)\n[![pypi]](https://pypi.org/project/chatterbox.py/)\n[![pyversions]](http://pypi.python.org/pypi/chatterbox.py)\n[![travis]](https://travis-ci.org/JungWinter/chatterbox)\n[![appveyor]](https://ci.appveyor.com/project/JungWinter/chatterbox)\n[![codecov]](https://codecov.io/gh/JungWinter/chatterbox)\n\n---\n\n\u003cb\u003e[Chatterbox]\u003c/b\u003e는 [카카오톡 플러스친구 자동응답 API]를 활용하여 챗봇을 만들 때 사용되는 파이썬 라이브러리입니다.\n\n**Table of Contents**\n\n- [:memo: Installation](#memo-installation)\n- [:rocket: Example](#rocket-example)\n- [:gem: Usage](#gem-usage)\n  - [Chatter](#chatter)\n    - [`Chatter.route(data)`](#chatterroutedata)\n  - [Response](#response)\n    - [Text(text)](#texttext)\n    - [Photo(url, width, height)](#photourl-width-height)\n    - [MessageButton(label, url)](#messagebuttonlabel-url)\n    - [Keyboard(buttons, type)](#keyboardbuttons-type)\n    - [조합](#%EC%A1%B0%ED%95%A9)\n  - [Base](#base)\n    - [`Chatter.add_base(name, func)`](#chatteradd_basename-func)\n    - [`@Chatter.base(name)`](#chatterbasename)\n    - [`Chatter.home()`](#chatterhome)\n  - [Rule](#rule)\n    - [`Chatter.add_rule(action, src, dest, func)`](#chatteradd_ruleaction-src-dest-func)\n    - [`@Chatter.rule(action, src, dest)`](#chatterruleaction-src-dest)\n    - [주관식 답변 처리하기](#%EC%A3%BC%EA%B4%80%EC%8B%9D-%EB%8B%B5%EB%B3%80-%EC%B2%98%EB%A6%AC%ED%95%98%EA%B8%B0)\n    - [fallback 처리하기](#fallback-%EC%B2%98%EB%A6%AC%ED%95%98%EA%B8%B0)\n- [:pray: Contribution](#pray-contribution)\n- [:link: Related projects](#link-related-projects)\n\n## :memo: Installation\n\n```shell\n$ pip install chatterbox.py\n```\n\n## :rocket: Example\n더 다양한 예제는 [examples]를 참고해주세요.\n\n```python\nfrom flask import Flask, request, jsonify\nfrom chatterbox import Chatter\nfrom chatterbox.response import Text, Keyboard, MessageButton\n\n\napp = Flask(__name__)\nchatter = Chatter()\n\n\n@chatter.base(name='홈')\ndef home_keyboard():\n    home_buttons = ['자기소개', '사이트로 이동하기']\n    return Keyboard(home_buttons)\n\n\n@chatter.rule(action='자기소개', src='홈', dest='홈')\ndef intro(data):\n    message = 'chatterbox를 통해 더 쉽게 카카오톡 봇을 만들 수 있습니다!'\n    return Text(message) + chatter.home()\n\n\n@chatter.rule(action='사이트로 이동하기', src='홈', dest='홈')\ndef web(data):\n    text = Text('자세한 정보를 보고싶으면 사이트로 이동해주세요!')\n    msg_button = MessageButton(label='이동하기',\n                               url='https://github.com/jungwinter/chatterbox')\n    keyboard = chatter.home()\n    return text + msg_button + keyboard\n\n\n@app.route('/keyboard', methods=['GET'])\ndef keyboard():\n    return jsonify(chatter.home())\n\n\n@app.route('/message', methods=['POST'])\ndef message():\n    return jsonify(chatter.route(request.json))\n\n\nif __name__ == '__main__':\n    app.run(debug=True)\n```\n\n## :gem: Usage\n### Chatter\n[FSM(finite-state machine)]을 사용해 유저들의 state를 내부에 저장하고, 요청에 맞는 response를 반환합니다.\n\n#### `Chatter.route(data)`\n[카카오톡 자동응답 api 명세]에 맞는 json 데이터를 인자로 받습니다. `user_key`로 가져온 state와 `content`값을 action으로 적절한 rule을 찾아 등록된 함수를 실행한 후 api 명세에 맞는 response를 반환합니다. rule에 관해선 아래에 서술되어 있습니다.\n\n##### 예제\n```py\n@app.route('/message', methods=['POST'])\ndef message():\n    response = chatter.route(request.json)\n    return jsonify(response)\n```\n\ninput 데이터로 다음과 같은 형식의 dict 객체를 인자로 받습니다.\n\n```json\n{\n  \"user_key\": \"encryptedUserKey\",\n  \"type\": \"text\",\n  \"content\": \"자기소개\"\n}\n```\n\noutput 데이터로 다음과 같은 형식의 Response 객체(dict로 동작함)를 반환합니다.\n\n```json\n{\n  \"message\": {\n    \"text\": \"안녕하세요! 무엇을 도와드릴까요?\"\n  },\n  \"keyboard\": {\n    \"buttons\": [\n      \"오늘의 날씨\",\n      \"취소\"\n    ],\n    \"type\": \"buttons\"\n  }\n}\n```\n\n### Response\n`chatterbox.response`에서 [카카오톡 response object 명세]를 만족하는 클래스를 가져올 수 있습니다.\n\n#### Text(text)\n다음과 같은 dict like 객체를 반환합니다. 멤버 변수로 `text`, `message`를 갖습니다.\n\n```python\nText(text='안녕!')\n```\n\n```json\n{\n  \"message\": {\n    \"text\": \"안녕!\"\n  }\n}\n```\n\n#### Photo(url, width, height)\n다음과 같은 dict like 객체를 반환합니다. 멤버 변수로 `url`, `width`, `height`, `message`를 갖습니다.\n\n```python\nPhoto(url='https://image/url.png',\n      width=500,\n      height=400)\n```\n\n```json\n{\n  \"message\": {\n    \"photo\": {\n      \"url\": \"https://image/url.png\",\n      \"width\": 500,\n      \"height\": 400\n    }\n  }\n}\n```\n\n#### MessageButton(label, url)\n다음과 같은 dict like 객체를 반환합니다. 멤버 변수로 `label`, `url`, `message`를 갖습니다.\n\n```python\nMessageButton(label='이동하기',\n              url='https://github.com/jungwinter/chatterbox')\n```\n\n```json\n{\n  \"message\": {\n    \"message_button\": {\n      \"label\": \"이동하기\",\n      \"url\": \"https://github.com/jungwinter/chatterbox\"\n    }\n  }\n}\n```\n\n#### Keyboard(buttons, type)\n자세한 명세는 [Keyboard object 문서]에서 확인할 수 있습니다. 멤버 변수로 `type`, `buttons`, `keyboard`를 갖습니다.\n\n##### 주관식 입력\n```python\nKeyboard(type='text')\n```\n\n```json\n{\n  \"keyboard\": {\n    \"type\": \"text\"\n  }\n}\n```\n##### 버튼 입력\n```python\nKeyboard(['버튼1', '버튼2'])  # type='buttons'는 생략할 수 있음\n```\n\n```json\n{\n  \"keyboard\": {\n    \"buttons\": [\n      \"버튼1\",\n      \"버튼2\"\n    ],\n    \"type\": \"buttons\"\n  }\n}\n```\n\n#### 조합\n\n```python\ndef intro():\n    text = Text('안녕!')\n    photo = Photo('https://image/url.png', 500, 400)\n    keyboard = Keyboard(['날씨', '시간'])\n    return text + photo + keyboard\n```\n\n위 코드는 아래와 같은 dict 객체를 반환합니다.\n\n```json\n{\n  \"message\": {\n    \"text\": \"안녕!\",\n    \"photo\": {\n        \"url\": \"https://image/url.png\",\n        \"width\": 500,\n        \"height\": 400\n    }\n  },\n  \"keyboard\": {\n    \"buttons\": [\n      \"날씨\",\n      \"시간\"\n    ],\n    \"type\": \"buttons\"\n  }\n}\n```\n\n##### 관계\n```\nResponse\n├── Message\n│   ├── Text\n│   ├── Photo\n│   └── MessageButton\n└── Keyboard\n    ├── ButtonType\n    └── TextType\n\nMessage + Message = Message\nMessage + Keyboard = Response\nResponse + Message = Response\n```\n\n### Base\n#### `Chatter.add_base(name, func)`\n`name`으로 유저가 시작할 state 이름을 지정할 수 있습니다.\n\n\u003e `func`은 인자가 없어야하며 `Keyboard`를 반환해야합니다.\n\n##### 예제\n```python\ndef func():\n    return Keyboard(['버튼1', '버튼2'])\nchatter.add_base(name='홈', func=func)\n```\n\n#### `@Chatter.base(name)`\n`Chatter.add_base()`의 wrapper입니다. 데코레이터로 사용할 수 있습니다.\n\n##### 예제\n```python\n@chatter.base(name='홈')\ndef func():\n    return Keyboard(['버튼1', '버튼2'])\n```\n\n#### `Chatter.home()`\n`Chatter.add_base()`를 통해 등록된 함수 `func`을 실행해 `Keyboard`를 반환합니다.\n\n##### 예제\n```python\n\u003e\u003e\u003e chatter.home()\n{\n  \"keyboard\": {\n    \"buttons\": [\n      \"버튼1\",\n      \"버튼2\"\n    ],\n    \"type\": \"buttons\"\n  }\n}\n```\n\n### Rule\n#### `Chatter.add_rule(action, src, dest, func)`\n유저의 현재 state가 `src`이고 input으로 받은 데이터에서 content가 `action`일 때, `func` 함수를 실행하고 유저의 state를 `dest`로 변경합니다. state를 활용하여 1 depth 이상의 자동응답 시나리오를 구성할 수 있습니다.\n\n\u003e `func` 함수는 반드시 `data`를 인자로 받아야하며 `Response`를 반환해야합니다.\n\n##### 예제\n```python\ndef intro(data):\n    message = 'chatterbox를 통해 더 쉽게 카카오톡 봇을 만들 수 있습니다!'\n    return Text(message) + chatter.home()\n\nchatter.add_rule(action='자기소개', src='홈', dest='홈', func=intro)\n```\n\n#### `@Chatter.rule(action, src, dest)`\n`Chatter.add_rule()`의 wrapper입니다. 데코레이터로 사용할 수 있습니다.\n\n##### 예제\n\n```python\n@chatter.rule(action='자기소개', src='홈', dest='홈')\ndef intro(data):\n    message = 'chatterbox를 통해 더 쉽게 카카오톡 봇을 만들 수 있습니다!'\n    return Text(message) + chatter.home()\n```\n\n#### 주관식 답변 처리하기\n`Keyboard(type='text')`를 반환해 유저의 주관식 답변을 받는 경우 `action='*'`을 사용해 처리할 수 있습니다. 자세한 방법은 [examples/flask_advance.py]를 참고해주세요.\n\n#### fallback 처리하기\n`src='*'`를 사용해 유저가 어떤 state에 있더라도 특정 dest로 이동시킬 수 있습니다.\n\n##### 예제\n```python\n@chatter.rule(action='취소', src='*', dest='홈')\ndef cancel(data):\n    message = '취소하셨습니다.'\n    return Text(message) + chatter.home()\n```\n\n## :pray: Contribution\n[CONTRIBUTING.md]을 참고해주세요.\n\n## :link: Related projects\n* [홍익대학교 학식알리미 셰프 홍]\n\n[Chatterbox]: https://github.com/JungWinter/chatterbox\n[license]: https://img.shields.io/badge/license-MIT-blue.svg\n[pypi]: https://img.shields.io/pypi/v/chatterbox.py.svg\n[pyversions]: https://img.shields.io/pypi/pyversions/chatterbox.py.svg\n[travis]: https://travis-ci.org/JungWinter/chatterbox.svg\n[appveyor]: https://ci.appveyor.com/api/projects/status/ispy5kkm050m0ka5?svg=true\n[codecov]: https://codecov.io/gh/JungWinter/chatterbox/branch/master/graph/badge.svg\n[카카오톡 플러스친구 자동응답 API]: https://github.com/plusfriend/auto_reply\n[examples]: https://github.com/JungWinter/chatterbox/blob/master/examples\n[FSM(finite-state machine)]: https://ko.wikipedia.org/wiki/유한_상태_기계\n[카카오톡 자동응답 api 명세]: https://github.com/plusfriend/auto_reply#specification-1\n[카카오톡 response object 명세]: https://github.com/plusfriend/auto_reply/blob/master/README.md#6-object\n[Keyboard object 문서]: https://github.com/plusfriend/auto_reply/blob/master/README.md#61-keyboard\n[examples/flask_advance.py]: https://github.com/JungWinter/chatterbox/blob/master/examples/flask/flask_advance.py\n[CONTRIBUTING.md]: https://github.com/JungWinter/chatterbox/blob/master/.github/CONTRIBUTING.md\n[홍익대학교 학식알리미 셰프 홍]: https://github.com/JungWinter/chef-hong\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwinterjung%2Fchatterbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwinterjung%2Fchatterbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwinterjung%2Fchatterbox/lists"}