kakaotalk-bot 0.1.0__tar.gz

kakaotalk_bot-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.venv/
+.mypy_cache/
+.pytest_cache/

kakaotalk_bot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jade (punch5545)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kakaotalk_bot-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.5
+Name: kakaotalk-bot
+Version: 0.1.0
+Summary: KakaoTalk Bot API client: REST API wrapper, Gateway (WebSocket) client and webhook helpers
+Project-URL: Homepage, https://github.com/punch5545/KakaoTalk-Bot-Wrapper/tree/main/python#readme
+Project-URL: Repository, https://github.com/punch5545/KakaoTalk-Bot-Wrapper
+Project-URL: Issues, https://github.com/punch5545/KakaoTalk-Bot-Wrapper/issues
+Project-URL: Documentation, https://developers.kakao.com/docs/ko/bot/common
+Author: jade (punch5545)
+License: MIT
+License-File: LICENSE
+Keywords: bot,chatbot,gateway,kakao,kakaotalk,websocket
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# kakaotalk-bot (Python)
+
+KakaoTalk Bot API client for Python 3.10+: REST API wrapper (async + sync), Gateway (WebSocket) client
+and webhook helpers. Depends on `httpx` and `websockets`.
+
+```bash
+pip install kakaotalk-bot
+```
+
+## REST API
+
+```python
+from kakaotalk_bot import (
+    KakaoBotClient, KakaoBotSyncClient, KakaoBotApiError,
+    text_response, SkillResponseBuilder, basic_card, web_link_button, message_button, mention_tag,
+)
+
+async with KakaoBotClient(BOT_TOKEN) as client:
+    await client.send_callback(callback_token, text_response("처리가 완료되었습니다."))
+    await client.send_to_group(bot_group_key, text_response("안녕하세요!"))
+    await client.send_to_user(bot_user_key, text_response("안녕하세요!"))  # channel chat only
+
+    commands = await client.get_commands()
+    await client.update_commands([{"buttonName": "도움말"}, {"buttonName": "상담원 연결", "description": "상담원과 연결합니다."}])
+    await client.update_guide("🤖 저와 함께 이런 것들을 할 수 있어요.")
+
+    response = (
+        SkillResponseBuilder()
+        .text(f"안녕하세요 {mention_tag('u1')}!")
+        .mention("u1", bot_user_key)
+        .add(basic_card("제목", "설명", {"imageUrl": "https://example.com/a.png"},
+                        [web_link_button("열기", "https://example.com"), message_button("다시")]))
+        .quick_reply("도움말")
+        .build()
+    )
+    try:
+        await client.send_callback(callback_token, response)
+    except KakaoBotApiError as e:
+        if e.is_callback_token_error:  # -881
+            ...
+
+# Blocking variant with the same methods
+with KakaoBotSyncClient(BOT_TOKEN) as client:
+    client.send_to_group(bot_group_key, text_response("hi"))
+```
+
+Options: `KakaoBotClient(token, base_url=..., timeout=10.0, headers=..., http=httpx.AsyncClient(...))`.
+
+## Gateway (WebSocket)
+
+```python
+import asyncio
+from kakaotalk_bot import KakaoBotGateway, DispatchEvent
+
+gateway = KakaoBotGateway(
+    BOT_TOKEN,
+    # url=..., client=..., auto_reconnect=True, initial_backoff=1.0, max_backoff=30.0,
+    # heartbeat_margin=5.0, handshake_timeout=15.0,
+)
+
+@gateway.on("ready")
+def on_ready(ready):
+    print("bot", ready["bot"]["id"], "session", ready["session_id"])
+
+@gateway.on("MESSAGE_CREATE")
+async def on_message(event: DispatchEvent):
+    # event.data: {"id", "content", "timestamp", "isChannelChatroom", "botGroupKey", "botUserKey", "callbackToken"?}
+    if event.can_reply:
+        await event.reply_text(f"echo: {event.content}")
+
+@gateway.on("error")
+def on_error(exc):
+    print("gateway error:", exc)  # fatal close codes: exc.fatal is True
+
+asyncio.run(gateway.run())          # blocks; reconnects automatically
+# or: task = await gateway.start()  # background task, returns once READY
+#     await gateway.close()
+```
+
+Events: `ready`, `resumed`, `dispatch`, `MESSAGE_CREATE`, `ENTRANCE`, `CHAT_JOIN`, `LEAVE`, `AD_REWARD`,
+`close`, `reconnecting`, `heartbeat_timeout`, `error`. Listeners may be sync or async.
+
+Session persistence: save `gateway.session` and call `gateway.restore_session(session_id, last_seq)`
+before `run()` to RESUME across process restarts.
+
+## Webhook (FastAPI example)
+
+```python
+from fastapi import FastAPI, Request, Response, BackgroundTasks
+from kakaotalk_bot import KakaoBotClient, parse_webhook_event, verify_custom_header
+
+client = KakaoBotClient(BOT_TOKEN)
+app = FastAPI()
+
+@app.post("/webhook")
+async def webhook(request: Request, background: BackgroundTasks) -> Response:
+    if not verify_custom_header(request.headers.get("X-My-Secret"), WEBHOOK_SECRET):
+        return Response(status_code=401)
+    event = parse_webhook_event(await request.body(), client)
+    if event.type == "MESSAGE_CREATE" and event.can_reply:
+        background.add_task(event.reply_text, f"echo: {event.content}")
+    return Response(status_code=204)  # within 1 second
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+mypy kakaotalk_bot
+```

kakaotalk_bot-0.1.0/README.md

@@ -0,0 +1,111 @@
+# kakaotalk-bot (Python)
+
+KakaoTalk Bot API client for Python 3.10+: REST API wrapper (async + sync), Gateway (WebSocket) client
+and webhook helpers. Depends on `httpx` and `websockets`.
+
+```bash
+pip install kakaotalk-bot
+```
+
+## REST API
+
+```python
+from kakaotalk_bot import (
+    KakaoBotClient, KakaoBotSyncClient, KakaoBotApiError,
+    text_response, SkillResponseBuilder, basic_card, web_link_button, message_button, mention_tag,
+)
+
+async with KakaoBotClient(BOT_TOKEN) as client:
+    await client.send_callback(callback_token, text_response("처리가 완료되었습니다."))
+    await client.send_to_group(bot_group_key, text_response("안녕하세요!"))
+    await client.send_to_user(bot_user_key, text_response("안녕하세요!"))  # channel chat only
+
+    commands = await client.get_commands()
+    await client.update_commands([{"buttonName": "도움말"}, {"buttonName": "상담원 연결", "description": "상담원과 연결합니다."}])
+    await client.update_guide("🤖 저와 함께 이런 것들을 할 수 있어요.")
+
+    response = (
+        SkillResponseBuilder()
+        .text(f"안녕하세요 {mention_tag('u1')}!")
+        .mention("u1", bot_user_key)
+        .add(basic_card("제목", "설명", {"imageUrl": "https://example.com/a.png"},
+                        [web_link_button("열기", "https://example.com"), message_button("다시")]))
+        .quick_reply("도움말")
+        .build()
+    )
+    try:
+        await client.send_callback(callback_token, response)
+    except KakaoBotApiError as e:
+        if e.is_callback_token_error:  # -881
+            ...
+
+# Blocking variant with the same methods
+with KakaoBotSyncClient(BOT_TOKEN) as client:
+    client.send_to_group(bot_group_key, text_response("hi"))
+```
+
+Options: `KakaoBotClient(token, base_url=..., timeout=10.0, headers=..., http=httpx.AsyncClient(...))`.
+
+## Gateway (WebSocket)
+
+```python
+import asyncio
+from kakaotalk_bot import KakaoBotGateway, DispatchEvent
+
+gateway = KakaoBotGateway(
+    BOT_TOKEN,
+    # url=..., client=..., auto_reconnect=True, initial_backoff=1.0, max_backoff=30.0,
+    # heartbeat_margin=5.0, handshake_timeout=15.0,
+)
+
+@gateway.on("ready")
+def on_ready(ready):
+    print("bot", ready["bot"]["id"], "session", ready["session_id"])
+
+@gateway.on("MESSAGE_CREATE")
+async def on_message(event: DispatchEvent):
+    # event.data: {"id", "content", "timestamp", "isChannelChatroom", "botGroupKey", "botUserKey", "callbackToken"?}
+    if event.can_reply:
+        await event.reply_text(f"echo: {event.content}")
+
+@gateway.on("error")
+def on_error(exc):
+    print("gateway error:", exc)  # fatal close codes: exc.fatal is True
+
+asyncio.run(gateway.run())          # blocks; reconnects automatically
+# or: task = await gateway.start()  # background task, returns once READY
+#     await gateway.close()
+```
+
+Events: `ready`, `resumed`, `dispatch`, `MESSAGE_CREATE`, `ENTRANCE`, `CHAT_JOIN`, `LEAVE`, `AD_REWARD`,
+`close`, `reconnecting`, `heartbeat_timeout`, `error`. Listeners may be sync or async.
+
+Session persistence: save `gateway.session` and call `gateway.restore_session(session_id, last_seq)`
+before `run()` to RESUME across process restarts.
+
+## Webhook (FastAPI example)
+
+```python
+from fastapi import FastAPI, Request, Response, BackgroundTasks
+from kakaotalk_bot import KakaoBotClient, parse_webhook_event, verify_custom_header
+
+client = KakaoBotClient(BOT_TOKEN)
+app = FastAPI()
+
+@app.post("/webhook")
+async def webhook(request: Request, background: BackgroundTasks) -> Response:
+    if not verify_custom_header(request.headers.get("X-My-Secret"), WEBHOOK_SECRET):
+        return Response(status_code=401)
+    event = parse_webhook_event(await request.body(), client)
+    if event.type == "MESSAGE_CREATE" and event.can_reply:
+        background.add_task(event.reply_text, f"echo: {event.content}")
+    return Response(status_code=204)  # within 1 second
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+mypy kakaotalk_bot
+```

kakaotalk_bot-0.1.0/kakaotalk_bot/__init__.py

@@ -0,0 +1,98 @@
+"""KakaoTalk Bot API client: REST API wrapper, Gateway (WebSocket) client and webhook helpers."""
+from .client import DEFAULT_API_BASE_URL, MAX_COMMANDS, KakaoBotClient, KakaoBotSyncClient
+from .errors import BOT_ERROR_DESCRIPTIONS, KakaoBotApiError, KakaoBotError, KakaoBotGatewayError
+from .events import DispatchEvent, create_dispatch_event, is_dispatch, normalise_frame, parse_frame
+from .gateway import DEFAULT_GATEWAY_URL, LIFECYCLE_EVENTS, KakaoBotGateway, describe_close_code
+from .skill import (
+    MAX_MENTIONS,
+    MAX_OUTPUTS,
+    MAX_QUICK_REPLIES,
+    SkillResponseBuilder,
+    basic_card,
+    button,
+    carousel,
+    commerce_card,
+    guide_button,
+    image_response,
+    invite_button,
+    invite_member_button,
+    item_card,
+    list_card,
+    mention_button,
+    mention_tag,
+    mentions,
+    message_button,
+    operator_button,
+    phone_button,
+    quick_reply,
+    settings_button,
+    share_button,
+    simple_image,
+    simple_text,
+    skill_response,
+    text_card,
+    text_response,
+    web_link_button,
+)
+from .types import CLOSE_CODE_DESCRIPTIONS, EVENT_TYPES, FATAL_CLOSE_CODES, CloseCode, Opcode
+from .webhook import parse_webhook_event, parse_webhook_payload, verify_custom_header
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "KakaoBotClient",
+    "KakaoBotSyncClient",
+    "DEFAULT_API_BASE_URL",
+    "MAX_COMMANDS",
+    "KakaoBotError",
+    "KakaoBotApiError",
+    "KakaoBotGatewayError",
+    "BOT_ERROR_DESCRIPTIONS",
+    "DispatchEvent",
+    "create_dispatch_event",
+    "parse_frame",
+    "normalise_frame",
+    "is_dispatch",
+    "KakaoBotGateway",
+    "DEFAULT_GATEWAY_URL",
+    "LIFECYCLE_EVENTS",
+    "describe_close_code",
+    "SkillResponseBuilder",
+    "skill_response",
+    "text_response",
+    "image_response",
+    "simple_text",
+    "simple_image",
+    "text_card",
+    "basic_card",
+    "list_card",
+    "item_card",
+    "commerce_card",
+    "carousel",
+    "button",
+    "message_button",
+    "web_link_button",
+    "phone_button",
+    "share_button",
+    "operator_button",
+    "invite_button",
+    "mention_button",
+    "invite_member_button",
+    "settings_button",
+    "guide_button",
+    "quick_reply",
+    "mention_tag",
+    "mentions",
+    "MAX_OUTPUTS",
+    "MAX_QUICK_REPLIES",
+    "MAX_MENTIONS",
+    "Opcode",
+    "CloseCode",
+    "EVENT_TYPES",
+    "FATAL_CLOSE_CODES",
+    "CLOSE_CODE_DESCRIPTIONS",
+    "parse_webhook_payload",
+    "parse_webhook_event",
+    "verify_custom_header",
+]

kakaotalk_bot-0.1.0/kakaotalk_bot/client.py

@@ -0,0 +1,289 @@
+"""REST API client for the KakaoTalk Bot API (async and sync variants)."""
+from __future__ import annotations
+
+import json
+from typing import Any, Mapping, Sequence
+
+import httpx
+
+from .errors import KakaoBotApiError
+from .types import CommandsResponse, Guide, SendResult, SkillResponse, UtteranceRequest
+
+DEFAULT_API_BASE_URL = "https://kapi.kakao.com"
+MAX_COMMANDS = 30
+
+
+class _BaseClient:
+    def __init__(
+        self,
+        bot_token: str,
+        *,
+        base_url: str = DEFAULT_API_BASE_URL,
+        timeout: float = 10.0,
+        headers: Mapping[str, str] | None = None,
+    ) -> None:
+        if not bot_token or not isinstance(bot_token, str):
+            raise TypeError("bot_token is required")
+        self._token = bot_token
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._extra_headers = dict(headers or {})
+
+    # -- request helpers ---------------------------------------------------
+
+    def _headers(self, extra: Mapping[str, str] | None = None, *, has_body: bool) -> dict[str, str]:
+        headers = {
+            **self._extra_headers,
+            "Authorization": f"KakaoAK {self._token}",
+            "Accept": "application/json",
+        }
+        if has_body:
+            headers["Content-Type"] = "application/json"
+        if extra:
+            headers.update(extra)
+        return headers
+
+    @staticmethod
+    def _encode(json_body: Any | None) -> bytes | None:
+        if json_body is None:
+            return None
+        return json.dumps(json_body, ensure_ascii=False).encode("utf-8")
+
+    @staticmethod
+    def _handle(response: httpx.Response) -> Any:
+        text = response.text
+        body: Any = None
+        if text:
+            try:
+                body = json.loads(text)
+            except ValueError:
+                body = None
+        if response.status_code >= 400:
+            raise KakaoBotApiError(response.status_code, body, text)
+        return body
+
+    @staticmethod
+    def _message_body(
+        skill_response: SkillResponse,
+        bot_group_key: str | None,
+        bot_user_key: str | None,
+    ) -> dict[str, Any]:
+        if bool(bot_group_key) == bool(bot_user_key):
+            raise TypeError("Exactly one of bot_group_key or bot_user_key must be provided")
+        body: dict[str, Any] = {}
+        if bot_group_key:
+            body["botGroupKey"] = bot_group_key
+        else:
+            body["botUserKey"] = bot_user_key
+        body["skillResponse"] = skill_response
+        return body
+
+    @staticmethod
+    def _validate_commands(utterances: Sequence[UtteranceRequest]) -> list[UtteranceRequest]:
+        items = list(utterances)
+        if len(items) > MAX_COMMANDS:
+            raise ValueError(f"At most {MAX_COMMANDS} commands can be registered")
+        return items
+
+
+class KakaoBotClient(_BaseClient):
+    """Async REST client.
+
+    >>> async with KakaoBotClient(BOT_TOKEN) as client:
+    ...     await client.send_callback(callback_token, text_response("안녕하세요!"))
+    """
+
+    def __init__(
+        self,
+        bot_token: str,
+        *,
+        base_url: str = DEFAULT_API_BASE_URL,
+        timeout: float = 10.0,
+        headers: Mapping[str, str] | None = None,
+        http: httpx.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(bot_token, base_url=base_url, timeout=timeout, headers=headers)
+        self._owns_http = http is None
+        self._http = http or httpx.AsyncClient(timeout=timeout)
+
+    async def __aenter__(self) -> KakaoBotClient:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Any:
+        """Low-level request; exposed for endpoints not yet wrapped."""
+        response = await self._http.request(
+            method,
+            self.base_url + path,
+            content=self._encode(json_body),
+            headers=self._headers(headers, has_body=json_body is not None),
+            timeout=self.timeout,
+        )
+        return self._handle(response)
+
+    # -- messages ----------------------------------------------------------
+
+    async def send_callback(self, callback_token: str, skill_response: SkillResponse) -> SendResult:
+        """POST /v1/bot/callback — reply to an event. Token is single-use and expires in 5 minutes."""
+        if not callback_token:
+            raise TypeError("callback_token is required")
+        result: SendResult = await self.request(
+            "POST",
+            "/v1/bot/callback",
+            json_body={"skillResponse": skill_response},
+            headers={"X-Bot-Callback-Token": callback_token},
+        )
+        return result
+
+    async def send_message(
+        self,
+        skill_response: SkillResponse,
+        *,
+        bot_group_key: str | None = None,
+        bot_user_key: str | None = None,
+    ) -> SendResult:
+        """POST /v1/bot/send_message — proactively message a room or a channel-chat user."""
+        result: SendResult = await self.request(
+            "POST",
+            "/v1/bot/send_message",
+            json_body=self._message_body(skill_response, bot_group_key, bot_user_key),
+        )
+        return result
+
+    async def send_to_group(self, bot_group_key: str, skill_response: SkillResponse) -> SendResult:
+        return await self.send_message(skill_response, bot_group_key=bot_group_key)
+
+    async def send_to_user(self, bot_user_key: str, skill_response: SkillResponse) -> SendResult:
+        return await self.send_message(skill_response, bot_user_key=bot_user_key)
+
+    # -- commands ----------------------------------------------------------
+
+    async def get_commands(self) -> CommandsResponse:
+        """GET /v1/bot/commands"""
+        result: CommandsResponse = await self.request("GET", "/v1/bot/commands")
+        return result
+
+    async def update_commands(self, utterances: Sequence[UtteranceRequest]) -> CommandsResponse:
+        """POST /v1/bot/commands/update — replaces the whole list (max 30)."""
+        result: CommandsResponse = await self.request(
+            "POST", "/v1/bot/commands/update", json_body={"utterances": self._validate_commands(utterances)}
+        )
+        return result
+
+    # -- guide -------------------------------------------------------------
+
+    async def get_guide(self) -> Guide:
+        """GET /v1/bot/guide"""
+        result: Guide = await self.request("GET", "/v1/bot/guide")
+        return result
+
+    async def update_guide(self, contents: str) -> Guide:
+        """POST /v1/bot/guide/update"""
+        result: Guide = await self.request("POST", "/v1/bot/guide/update", json_body={"contents": contents})
+        return result
+
+
+class KakaoBotSyncClient(_BaseClient):
+    """Blocking REST client with the same surface as :class:`KakaoBotClient`."""
+
+    def __init__(
+        self,
+        bot_token: str,
+        *,
+        base_url: str = DEFAULT_API_BASE_URL,
+        timeout: float = 10.0,
+        headers: Mapping[str, str] | None = None,
+        http: httpx.Client | None = None,
+    ) -> None:
+        super().__init__(bot_token, base_url=base_url, timeout=timeout, headers=headers)
+        self._owns_http = http is None
+        self._http = http or httpx.Client(timeout=timeout)
+
+    def __enter__(self) -> KakaoBotSyncClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Any:
+        response = self._http.request(
+            method,
+            self.base_url + path,
+            content=self._encode(json_body),
+            headers=self._headers(headers, has_body=json_body is not None),
+            timeout=self.timeout,
+        )
+        return self._handle(response)
+
+    def send_callback(self, callback_token: str, skill_response: SkillResponse) -> SendResult:
+        if not callback_token:
+            raise TypeError("callback_token is required")
+        result: SendResult = self.request(
+            "POST",
+            "/v1/bot/callback",
+            json_body={"skillResponse": skill_response},
+            headers={"X-Bot-Callback-Token": callback_token},
+        )
+        return result
+
+    def send_message(
+        self,
+        skill_response: SkillResponse,
+        *,
+        bot_group_key: str | None = None,
+        bot_user_key: str | None = None,
+    ) -> SendResult:
+        result: SendResult = self.request(
+            "POST",
+            "/v1/bot/send_message",
+            json_body=self._message_body(skill_response, bot_group_key, bot_user_key),
+        )
+        return result
+
+    def send_to_group(self, bot_group_key: str, skill_response: SkillResponse) -> SendResult:
+        return self.send_message(skill_response, bot_group_key=bot_group_key)
+
+    def send_to_user(self, bot_user_key: str, skill_response: SkillResponse) -> SendResult:
+        return self.send_message(skill_response, bot_user_key=bot_user_key)
+
+    def get_commands(self) -> CommandsResponse:
+        result: CommandsResponse = self.request("GET", "/v1/bot/commands")
+        return result
+
+    def update_commands(self, utterances: Sequence[UtteranceRequest]) -> CommandsResponse:
+        result: CommandsResponse = self.request(
+            "POST", "/v1/bot/commands/update", json_body={"utterances": self._validate_commands(utterances)}
+        )
+        return result
+
+    def get_guide(self) -> Guide:
+        result: Guide = self.request("GET", "/v1/bot/guide")
+        return result
+
+    def update_guide(self, contents: str) -> Guide:
+        result: Guide = self.request("POST", "/v1/bot/guide/update", json_body={"contents": contents})
+        return result