손님에게 답하는 채팅 봇 만들기

봇이란 무엇이고 무엇을 할 수 있나

봇은 화면 뒤에 사람이 앉아 타자를 치지 않는, Korat 시스템 안의 또 다른 종류의 "사용자 계정"입니다 — 여러분의 프로그램이 요청을 쏘면 봇이 초대된 채팅방에 메시지가 나타납니다. 실제로 이렇게 씁니다.

• 새 주문을 채팅으로 알리기 — 가게 판매 시스템에 새 주문이 들어오면 ⇒ 봇이 손님과의 채팅방이나 직원 방에 곧바로 알림을 씁니다
• 재고가 곧 떨어진다고 알리기 — 재고가 정해 둔 수량보다 적어지면 ⇒ 봇이 가게 직원 방에 경고를 씁니다
• 서버·시스템 상태 알리기 — 여러분이 만든 상태 점검 스크립트가 끝나면 ⇒ 봇이 IT 팀이 보는 그룹 방에 결과를 보고합니다

봇이 할 수 없는 일(임시 제약이 아니라 데이터베이스에서 온 사실입니다):

• 봇은 방의 메시지를 읽을 수 없습니다 — 나가는 쪽 전용입니다. 여러분이 직접 수신 웹훅을 설정한 경우는 예외입니다(페이지 끝의 기술 레퍼런스를 보세요). 다만 웹훅을 설정해 두어도 오늘은 실제로 아무것도 보내지지 않습니다. 큐를 끌어다 쏘는 시계가 아직 프로덕션에 설정되지 않았기 때문입니다
• 봇은 스스로 방에 들어올 수 없습니다 — 이미 그 방에 있는 사람(또는 그 방을 관리할 권한이 있는 사람)이 언제나 초대해야 합니다
• 봇 하나가 동시에 쓸 수 있는 토큰은 2장까지이며, 계정 하나가 만들 수 있는 봇은 최대 5개입니다

어떻게 시작하나 — 4단계

1. 1봇 만들기. 봇의 이름과 아이디를 정합니다(아이디는 bot으로 끝나야 합니다. 예: orderbot) — 여러분 개인이 아니라 가게의 봇으로 두고 싶다면 만들 때 가게를 고르면 됩니다
2. 2토큰 복사하기. 만들기가 끝나면 시스템이 토큰을 딱 한 번 보여 줍니다 — 곧바로 안전한 곳에 복사해 두세요. 화면을 닫으면 실제 값을 다시 꺼내 볼 방법이 없습니다(새로 발급받아야 합니다)
3. 3봇을 방에 초대하기. 봇이 말하게 할 채팅방, 그룹 방, 직원 방을 고릅니다 — 여러분이 이미 그 방에 있거나 그 방을 관리할 권한이 있어야 초대할 수 있습니다
4. 4첫 메시지 쏘기. 2단계의 토큰으로 Bot API를 호출합니다 — 그대로 따라 할 수 있는 예제가 다음 항목에 있습니다

예제 — 첫 메시지 쏘기

엔드포인트는 POST https://koratland.com/api/bot/send 하나뿐입니다. 요청 헤더에 토큰을 넣고, 어느 방에 무엇을 말할지 알려 주세요.

curl로 하기 (터미널이 익숙한 분께)

curl -X POST "https://koratland.com/api/bot/send" \
  -H "X-Bot-Token: kbot_12_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "chat", "chat_id": 9931, "text": "새 주문이 들어왔습니다" }'

kbot_12_xxxxxxxxxxxxxxxxxxxx는 봇의 실제 토큰으로, 9931은 봇을 초대해 둔 방의 번호로 바꾸세요(방 번호는 앱의 채팅 링크나 "내 봇" 화면의 방 목록에서 볼 수 있습니다).

코드를 짜지 않고 하기 (Google Apps Script)

자기 서버가 없다면 구글 계정 하나로 Google Apps Script를 무료로 쓸 수 있습니다 — script.google.com에 들어가 → 새 프로젝트 → 이 코드를 붙여 넣고 → "실행"을 누릅니다. 처음 실행할 때 인터넷 접근 권한을 묻습니다(여러분 자신의 스크립트이므로 허용해도 안전합니다).

function sendKoratMessage() {
  var url = "https://koratland.com/api/bot/send";
  var payload = {
    kind: "chat",
    chat_id: 9931,              // 여러분의 방 번호로 바꾸세요
    text: "새 주문이 들어왔습니다"   // 보내고 싶은 메시지로 바꾸세요
  };
  var options = {
    method: "post",
    contentType: "application/json",
    headers: { "X-Bot-Token": "kbot_12_xxxxxxxxxxxxxxxxxxxx" },  // 여러분의 봇 토큰으로 바꾸세요
    payload: JSON.stringify(payload)
  };
  var res = UrlFetchApp.fetch(url, options);
  Logger.log(res.getContentText());  // 결과는 "실행 로그"(Execution log)에서 봅니다
}

"실행"을 한 번 누르면 곧바로 시험해 볼 수 있습니다 — 자동으로 쏘게 하고 싶다면, 예를 들어 주문을 적는 Google Sheet에 새 행이 생길 때마다 쏘려면, Apps Script의 트리거(Triggers)로 시트가 수정될 때(onEdit)나 몇 분마다 이 함수를 부르도록 두면 됩니다.

같은 방법을 "HTTP request"나 "Webhook" 동작이 이미 있는 자동화 도구에도 그대로 쓸 수 있습니다. 예를 들어 n8n, Make, Zapier — 같은 URL로 POST를 보내도록 설정하고 X-Bot-Token 헤더와 위 예제와 같은 JSON 본문을 넣으세요.

자주 겪는 문제

모든 오류 코드는 아래 기술 레퍼런스의 표에서 볼 수 있습니다

기술 레퍼런스 (개발자용)

아래 항목은 Bot API를 직접 호출하는 프로그램을 짤 사람을 위한 것입니다 — 모든 파라미터의 상세, 전체 오류 코드 표, 그리고 수신 웹훅.

1~3단계를 RPC로 직접 하기 (앱 없이)

쓰고 있는 앱 버전에 "내 봇" 화면이 아직 없거나 자동으로 처리하고 싶다면, 로그인한 사용자의 Access Token(봇 토큰이 아닙니다)으로 PostgREST를 통해 Supabase의 RPC를 직접 부르세요 — 세 단계입니다.

1. 봇 만들기 — bot_create

curl -X POST "https://<SUPABASE_PROJECT>.supabase.co/rest/v1/rpc/bot_create" \
  -H "apikey: <SUPABASE_ANON_KEY>" \
  -H "Authorization: Bearer <USER_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "p_name": "알림봇",
    "p_username": "notifybot",
    "p_business_id": null,
    "p_about": "주문 상태를 알립니다"
  }'

p_username은 a–z 0–9 _로 4~31자여야 하고 언제나 bot으로 끝나야 합니다(정규식 ^[a-z][a-z0-9_]{2,29}bot$). 봇을 가게의 것으로 두려면 p_business_id를 보내세요 — 호출자는 그 가게의 구성원이어야 하고 bot.manage 권한이 있어야 합니다. 성공 응답은 token을 돌려주는데, 이것이 그 토큰이 평생 한 번 보여 주는 실제 값입니다. 데이터베이스는 sha256 해시만 보관합니다 — 놓치면 새로 발급받아야 하며(bot_rotate_token) 실제 값을 다시 읽을 방법은 없습니다.

{ "ok": true, "bot_id": 12, "user_id": 4821, "username": "notifybot", "token": "kbot_12_…" }

2. 봇을 채팅방에 초대하기 — bot_invite

실제로 그 방에 있는 사람이어야 하고(그 방이 가게 메시지함이라면 가게 직원이어야 합니다), 이 봇을 관리할 수 있어야 합니다(can_manage_bot). p_target은 chats.id입니다.

curl -X POST "https://<SUPABASE_PROJECT>.supabase.co/rest/v1/rpc/bot_invite" \
  -H "apikey: <SUPABASE_ANON_KEY>" \
  -H "Authorization: Bearer <USER_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "p_bot": 12, "p_kind": "chat", "p_target": 9931 }'

2-1. 봇을 그룹 방 / 직원 방에 초대하기 — 채팅방보다 권한이 엄격합니다

p_kind: "community_room" 또는 "business_room"을 p_target(각각 community_rooms.id/business_rooms.id)과 함께 보내는 것은 이미 실제로 됩니다 — 다만 초대하는 사람은 그 방의 의미에 맞는 권한 관문을 통과해야 하며, 단순히 구성원인 것만으로는 되지 않습니다.

• 그룹 방 — 초대하는 사람이 그 방의 규칙(read_role/post_role)에 따라 실제로 그 방에 글을 쓸 수 있어야 합니다. 보통의 대화방은 구성원이 초대할 수 있고, 관리자 전용으로 둔 공지방·백오피스 방은 그룹의 소유자나 관리자만 할 수 있습니다
• 가게 직원 방 — 기존 방의 관문(읽기 권한/글쓰기 권한/수신자 규칙)을 모두 통과하고 여기에 더해 언제나 teamroom.manage capability가 있어야 합니다 — 회사 내부 방에 봇을 데려오는 일은 "방에 글쓰기"가 아니라 "방 관리"에 해당하기 때문입니다

두 경우 모두 언제나 그 봇의 관리자여야 합니다(can_manage_bot) — 공용 방은 아무나 남의 봇을 끌고 들어와 말하게 하는 곳이 아닙니다.

메시지 보내기 — POST /api/bot/send

토큰은 두 가지 방식으로 보낼 수 있고 하나만 고르면 됩니다.

# 방식 1 — Authorization: Bearer
curl -X POST "https://koratland.com/api/bot/send" \
  -H "Authorization: Bearer kbot_12_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-9931-shipped" \
  -d '{ "kind": "chat", "chat_id": 9931, "text": "물건이 가게에서 출발했습니다" }'

# 방식 2 — X-Bot-Token
curl -X POST "https://koratland.com/api/bot/send" \
  -H "X-Bot-Token: kbot_12_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "chat", "chat_id": 9931, "text": "물건이 가게에서 출발했습니다" }'

토큰을 아예 보내지 않으면 401이 돌아옵니다.

{ "ok": false, "reason": "bad_token", "detail": "토큰은 Authorization: Bearer … 또는 X-Bot-Token으로만 보내세요" }

본문의 필드

1:1 채팅과 가게 채팅 — 어느 필드가 가르나

kind는 목적지 테이블의 종류(채팅방 / 그룹 방 / 가게 직원 방)를 가릅니다. 반면 1:1 채팅과 가게 메시지함은 kind로 나뉘지 않습니다 — 둘 다 똑같이 chats 테이블의 행이며, chats.business_id에 값이 있는지 없는지로 갈립니다(값이 있으면 가게 메시지함). 초대 권한 검사, 사용자 차단 검사, 그리고 "가게는 손님에게 먼저 말을 걸 수 없다(conversation_not_open)"는 규칙도 모두 이 칼럼에서 읽습니다 — 보내는 chat_id는 이미 올바른 방이어야 하며, API에는 "개인/사업" 을 고르는 파라미터가 따로 없습니다.

Idempotency-Key와 발송 한도

표준 Idempotency-Key 헤더나 본문의 client_key 필드를 보내세요 — 하나만 고르면 됩니다. 둘 다 보낸다면 값이 같아야 하며, 다르면 422 idempotency_key_conflict가 돌아옵니다. 같은 키(같은 방 + 같은 키)로 같은 요청을 다시 쏘면 "duplicate": true가 붙은 예전 200 응답이 돌아오고 메시지가 또 만들어지지 않습니다.

한도는 두 겹입니다: IP 단위(Worker 자체에서 분당 120 요청)와 봇 단위(봇 하나당 기본 분당 20건, 하루 1000건이며 관리자가 봇마다 조정할 수 있습니다). 둘 다 429와 함께 Retry-After 헤더를 초 단위로 돌려줍니다(IP 단위 = 언제나 60 · 봇 분당 = 60 · 봇 하루 = 3600).

메시지 받기 — 웹훅

봇이 초대된 채팅방에 누군가 메시지를 쓰면(그리고 보낸 이가 봇 자신의 계정이 아니라면 — 봇의 메시지가 자기에게 되돌아오는 것을 막습니다) Korat이 정해 둔 URL로 POST를 쏩니다. 토큰을 받을 때와 마찬가지로, 로그인한 사용자 계정으로 그 봇을 관리할 권한(can_manage_bot)을 가지고 RPC를 통해 설정해야 합니다.

curl -X POST "https://<SUPABASE_PROJECT>.supabase.co/rest/v1/rpc/bot_set_webhook" \
  -H "apikey: <SUPABASE_ANON_KEY>" \
  -H "Authorization: Bearer <USER_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "p_bot": 12, "p_url": "https://your-server.example.com/korat-webhook" }'

{ "ok": true, "secret": "a1b2c3…", "note": "이 secret은 한 번만 보입니다 — 서명을 직접 검증하려면 보관하세요" }

URL은 반드시 https://여야 하며, 내부·루프백·링크로컬 호스트(localhost, 127.0.0.1, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, 모든 클라우드의 메타데이터 엔드포인트 포함)여서는 안 됩니다 — 설정하는 순간 거절하고, 나중에 DNS가 다른 곳을 가리키는 것을 막으려고 쏘기 전에 매번 실제 DNS를 resolve해 다시 확인합니다. secret은 설정하거나 새로 돌릴 때 한 번만 보입니다 — bot_rotate_webhook_secret(p_bot)으로 언제든 새로 돌리고, bot_disable_webhook(p_bot)/bot_enable_webhook(p_bot)으로 직접 끄고 켜며, bot_webhook_status(p_bot)으로 상태를 봅니다(secret은 돌려주지 않습니다).

여러분의 엔드포인트가 받게 될 요청의 모습

POST /korat-webhook HTTP/1.1
Content-Type: application/json
X-Korat-Signature: sha256=<hex>
X-Korat-Timestamp: 1750000000000

{
  "event": "message.created",
  "chat_id": 9931,
  "message_id": 88213,
  "text": "빨간색 있나요",
  "time": "14:02",
  "sender": { "id": 4821, "username": "somchai_p", "name": "솜차이 P." }
}

이것이 전부입니다 — 본문에 누구의 전화번호도, 이메일도, 토큰도 없습니다. 봇은 답하는 데 필요한 만큼의 방·메시지·보낸 이의 신원만 봅니다.

요청을 믿기 전에 서명을 검증하세요

X-Korat-Signature는 HMAC-SHA256(secret, "<timestamp>." + rawBody)를 16진수로 인코딩한 값입니다 — Node.js 예제입니다.

const crypto = require("crypto");
function verify(rawBody, signatureHeader, timestampHeader, secret) {
  const age = Date.now() - Number(timestampHeader);
  if (!(age >= 0 && age < 5 * 60_000)) return false; // 재전송 방지: 5분을 넘기면 안 됩니다
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(`${timestampHeader}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

8초 안에 2xx로 답하면 발송에 성공한 것으로 봅니다 — 그 밖의 응답(Korat이 따라가지 않는 3xx 리다이렉트 포함)이나 아무 응답이 없으면 실패로 보고 재시도 큐에 넣습니다.

엔드포인트가 죽었을 때의 재시도

실패하면 지수적으로 물러납니다(1, 2, 4, 8, 16, 32, 64, 128분). 메시지 하나당 최대 8번까지 하고 그 메시지는 포기합니다. 엔드포인트가 연달아 15번 실패하면(여러 메시지에 걸쳐) 웹훅이 자동으로 꺼지고 봇 소유자에게 앱으로 알림이 갑니다 — 죽은 엔드포인트에 영원히 쏘는 일은 결코 없습니다. 엔드포인트 문제를 고친 뒤 bot_enable_webhook으로 다시 켤 수 있습니다.

전체 오류 코드 표

실패했을 때의 모든 응답에는 언제나 {"ok": false, "reason": "…"}가 있습니다 — 판단에 써야 하는 것은 HTTP status가 아니라 reason입니다.

성공했을 때의 응답

{ "ok": true, "duplicate": false, "message_id": 88213 }

duplicate: true는 이 요청이 앞서 이미 보내졌다는 뜻입니다(client_key/Idempotency-Key로 중복을 막았습니다) — 새 메시지는 만들어지지 않았지만 여전히 성공(200)으로 봅니다. 호출자가 바라던 결과는 이미 실제로 일어났기 때문입니다.