お客さまに応対するチャットボットを作る

ボットとは何か、何に使えるか

ボットとは、画面の向こうで人が入力しているわけではない、Korat のもうひとつの「利用者アカウント」です。あなた自身のプログラムがリクエストを送ると、ボットが招待されているチャットルームにメッセージが現れます。実際の使い道はたとえば次のとおりです。

• 新しい注文をチャットに通知する——店舗の販売システムに新しい注文が入った ⇒ ボットがお客さまとのチャットルームやスタッフのルームにすぐ書き込みます
• 在庫切れ間近を知らせる——在庫が設定した数を下回った ⇒ ボットが店舗のスタッフのルームに警告を書き込みます
• サーバーやシステムの状態を知らせる——自前の死活監視スクリプトが実行を終えた ⇒ ボットが情シスの見ているグループのルームに結果を報告します

ボットにできないこと（一時的な制約ではなく、データベースから来る実際の事実です）。

• ボットはルームのメッセージを読めません——送信専用です。ただし、ご自身で受信用のウェブフックを設定した場合は別です（ページ後半の技術リファレンスをご覧ください）。なお、ウェブフックを設定しても、現在は実際に何も送信されません。キューを取り出して送信するタイマーが、本番環境でまだ設定されていないためです
• ボットは自分でルームに入れません——すでにそのルームにいる人（またはそのルームを管理する権限を持つ人）が招待する必要があります
• 1つのボットが同時に持てる有効なトークンは2枚までで、1つのアカウントで作れるボットは最大5つです

始め方——4つの手順

1. 1ボットを作る。ボットの名前とユーザー名を決めます（ユーザー名は orderbot のように bot で終わる必要があります）。自分個人ではなく店舗のものにしたい場合は、作成時に店舗を選べます
2. 2トークンをコピーする。作成が終わったときに一度だけトークンが表示されます。すぐ安全な場所にコピーして保管してください。画面を閉じると、実際の値を二度と取り出せません（新しく発行し直すしかありません）
3. 3ボットをルームに招待する。ボットに発言させたいチャットルーム、グループのルーム、スタッフのルームを選びます。招待するには、あなた自身がそのルームにいる（またはそのルームを管理する権限を持つ）必要があります
4. 4最初のメッセージを送る。手順2のトークンを使って Bot API を呼びます。実際に試せる例は次の項目にあります

例——最初のメッセージを送る

宛先は POST https://koratland.com/api/bot/send の1つだけです。リクエストヘッダーにトークンを入れ、どのルームに何を言うかを伝えます。

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 アカウント1つで 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）で確認できます
}

「実行」を1回押すだけですぐ試せます。自動で送りたい場合、たとえば注文を記録している Google スプレッドシートに新しい行が追加されるたびに送りたいときは、Apps Script のトリガー（Triggers）を使い、シートが編集されたとき（onEdit）や、何分おきかにこの関数を呼ぶよう設定します。

同じやり方は、n8n、Make、Zapier のように「HTTP request」や「Webhook」のアクションをすでに持つ自動化ツールでも使えます。同じ URL に POST するよう設定し、X-Bot-Token のヘッダーと、上の例と同じ JSON のボディを指定してください。

よくある問題

エラーコードの全一覧は、下の技術リファレンスの表にあります。

技術リファレンス（開発者向け）

以下は、ご自身で Bot API を呼ぶプログラムを書くかた向けです。すべてのパラメーターの詳細、エラーコードの完全な表、受信用のウェブフックを扱います。

手順1〜3を RPC から直接行う（アプリを使わずに）

お使いのアプリのバージョンに「マイボット」の画面がまだない場合や、自動化したい場合は、ログイン中の利用者のアクセストークン（ボットのトークンではありません）を使い、PostgREST 経由で Supabase の RPC を直接呼びます。3つの手順です。

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 }'

2a. グループのルーム／スタッフのルームに招待する——チャットルームより権限が厳しい

p_kind: "community_room" または "business_room" を、p_target に community_rooms.id／business_rooms.id を添えて送れるようになっています。ただし招待する人は、そのルームの意味に見合った権限の関門を通る必要があり、単なるメンバーであるだけでは足りません。

• グループのルーム——招待する人は、そのルーム自身の規則（read_role／post_role）に照らして実際にそのルームに投稿できる必要があります。普通の雑談のルームならメンバーが招待できますが、管理者専用に設定されたお知らせや裏方のルームでは、グループのオーナーか管理者である必要があります
• 店舗のスタッフのルーム——そのルーム本来の関門（閲覧権限・投稿権限・受信者の規則）をすべて満たしたうえで、さらに teamroom.manage のケイパビリティが常に必要です。会社の内部のルームにボットを連れてくることは「ルームに投稿する」ではなく「ルームを管理する」とみなされるからです

どちらの場合も、そのボットの管理者である（can_manage_bot）ことが常に必要です。共有のルームは、誰かが他人のボットを引っ張ってきて発言させてよい場所ではありません。

メッセージを送る——POST /api/bot/send

トークンの渡し方は2通りあり、どちらか一方を選びます。

# 方法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 でのみ送ってください" }

ボディのフィールド

個人のチャットと店舗の受信箱——どのフィールドで決まるか

kind は宛先のテーブルの種類（チャットルーム／グループのルーム／店舗のスタッフのルーム）を決めます。一方、個人のチャットと店舗の受信箱は kind では区別しません。どちらも同じ chats テーブルの行で、違うのは chats.business_id に値があるかどうかです（値がある＝店舗の受信箱）。招待の権限の検査、利用者のブロックの検査、そして「店舗から先にお客さまへ話しかけられない（conversation_not_open）」という規則も、この列から読み取ります。送る chat_id は、すでに正しいルームである必要があり、API に「個人／店舗」を選ぶパラメーターはありません。

Idempotency-Key と送信の上限

標準の Idempotency-Key ヘッダーか、ボディの client_key フィールドの、どちらか一方を送ります。両方送る場合は値が一致していなければならず、一致しないと 422 idempotency_key_conflict になります。同じキー（同じルーム＋同じキー）で同じリクエストを送り直すと、以前と同じ 200 の応答に "duplicate": true が付いて返り、メッセージが重複して作られることはありません。

上限は2層あります。IP ごと（Worker 自身で 120 リクエスト／分）とボットごと（既定で1つのボットにつき 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 が別の場所を指すのを防ぐためです。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分）、1つのメッセージにつき最大8回まで再送し、そのあとはそのメッセージの送信をあきらめます。受け口が15回連続で失敗した場合（複数のメッセージにまたがっても）、ウェブフックは自動的に無効化され、アプリでボットのオーナーに通知されます。死んだ受け口に永遠に送り続けることはありません。受け口の問題を直したら bot_enable_webhook で再び有効にできます。

エラーコードの全一覧

失敗したときの応答には常に {"ok": false, "reason": "…"} が入ります。判断に使うべきは HTTP のステータスではなく reason です。

成功したときの応答

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

duplicate: true は、このリクエストがすでに以前に送られていたことを意味します（client_key／Idempotency-Key による重複防止）。新しいメッセージは作られませんが、呼び出し側が求めた結果はすでに実際に起きているため、成功（200）として扱います。