Keyda Business
JapanEnglish サインイン 無料で始める
Keyda Business ドキュメントガイド

アクション：自社システムからの回答

アクションを使うと、ボットはチャットの途中で貴社のシステムから情報を照会できます。注文の所在、配送予定日、予約が確定しているかなどです。顧客が質問すると、ボットは必要な情報を集め、貴社のAPIを呼び出し、返ってきた内容をもとに顧客の言語で回答します。

ボットが動作する場所ならどこでも使えます：ウェブサイトウィジェット、ボットリンクとQRコード、そしてAndroid、iOS、React Native、Flutter、Ionicの各アプリ。インストールや更新は不要です。呼び出しは当社のサーバーから行われるため、APIの認証情報がブラウザやスマートフォンに渡ることはありません。

始める前に：ボットとは誰でもチャットできます

ボットは公開チャットです。注文番号だけで注文を閲覧できるなら、誰でも番号を片っ端から入力して当てることができてしまいます。

本人の顧客しか知らない2つの情報 — 注文番号と、その注文のメールアドレスまたは電話番号 — を尋ね、両方が一致した場合にのみAPIが注文を返すようにしてください。それ以外は「見つかりません」と応答してください。

ボットは3つの方法で役立ちますが、いずれもその確認の代わりにはなりません。顧客が実際に入力した値のみを送信すること、1つのチャットや1つのアドレスからの照会回数を制限すること、そしてレスポンスのどのフィールドを見てよいかを選べることです。

設定する

ダッシュボードで アクション を開き、新しいアクション を選択します。この画面はオーナーと管理者が閲覧できます。

  • 名前 — 自分用の名前。例：「注文状況」。
  • ボットはいつこれを使うべきですか？ — 新しい同僚に説明するように一文で：「顧客が注文の所在や到着予定日を尋ねる。」
  • APIアドレス — GET または POST、および https:// アドレス。値が入る場所に {{order_id}} を書いてください。
  • ボットが顧客に尋ねる項目 — 最大6件。それぞれに、あなたの言葉によるラベル（「注文番号」）、API側で使う名前（order_id）、形式（任意のテキスト、数値、メールアドレス、電話番号）があります。
  • ヘッダー — APIキーまたはトークン。暗号化して保存され、二度と表示されません。
  • ボットに共有するフィールドを限定 — 任意。status, eta, items[].name のように、ボットが使用してよいレスポンスの部分を列挙します。それ以外はAIが見る前に除外されます。

テスト を押してサンプルの値を入力すると、送信されたリクエストと、ボットに渡される内容そのものを確認できます。次に テスト 画面で実際に試してください：「注文48213はどこですか？メールアドレスは asha@example.com です」。

APIが受け取る内容

GET の場合、アドレスに配置した値が埋め込まれ、残りはクエリ文字列に追加されます：

GET https://api.yourshop.com/orders/48213?email=asha%40example.com

POST の場合、値はJSONボディになります：

POST https://api.yourshop.com/lookup
Content-Type: application/json

{"order_id":"48213","email":"asha@example.com"}

各リクエストには、貴社のヘッダーに加えて以下のヘッダーも含まれます：

ヘッダー内容
webhook-idこのリクエストの一意のid
webhook-timestamp送信時刻（秒単位）
webhook-signature署名 — 下記参照
X-Keyda-BotボットのClient ID
X-Keyda-Actionアクションのキー。例：order_status
X-Keyda-Conversation送信元のチャット

返すべき内容

8秒以内に JSON または短い1行のプレーンテキストで応答してください。

  • 200 とデータ — ボットはそこから回答します。小さく保ち、わかりやすいフィールド名を使ってください。内部コードより {"status":"shipped","eta":"2 October"} のほうがうまく機能します。
  • 404 は該当なしの場合 — ボットは顧客にその旨を伝え、入力内容の確認を促します。
  • それ以外の応答、または時間内に応答がない場合 — ボットは謝罪し、貴社の連絡先を案内し、そのチャットにはフラグが付けられます。理由はアクション画面に表示されます。

リダイレクトには従わず、256 KB を超えるレスポンスは読み取られません。

署名を確認する

リクエストは Standard Webhooks 方式で署名されるため、既存のライブラリを利用できます。署名シークレットはアクション画面にあります。

手動で行う場合：id、タイムスタンプ、ボディそのものをピリオドで連結し、シークレット（whsec_ の後の部分をbase64デコードしたもの）を使ってHMAC-SHA256で署名し、比較します。

const crypto = require('crypto');

function isFromKeyda(req, rawBody, secret) {
  const id = req.headers['webhook-id'];
  const ts = req.headers['webhook-timestamp'];
  const given = String(req.headers['webhook-signature'] || '').replace(/^v1,/, '');
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // older than 5 minutes
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const want = crypto.createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest('base64');
  return given.length === want.length
    && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(want));
}

GET リクエストではボディが空のため、署名対象のテキストはピリオドで終わります。値そのものも署名に含めたい場合は POST を使用してください。

ボットによる使われ方

  • 不足している情報は、短い質問を1つずつ尋ねて集め、チャットの中で顧客が先に伝えた内容は記憶しています。
  • 値を推測することはありません。顧客が入力していなければ、ボットが尋ねます。
  • 1メッセージにつき照会は1回です。保存済み回答が引き続き優先されるため、手動で回答済みの質問がAPIを呼び出すことはありません。
  • 照会の回答が別の顧客に再利用されることはありません。
  • 照会1回は、AIが書く他の返答と同じく回答1件として数えられます。

チャット では、照会から得られた回答の下にその旨が表示されます。どのアクションが実行され、どう終了したかです。顧客が入力した値は会話記録にのみ残り、他の場所には保存されません。

制限

ボット1つにつきアクション8件、アクション1件につき値6件とヘッダー8件、呼び出し1回につき8秒。1つのチャットで10分間に6回、1つのインターネットアドレスで1時間に20回まで照会でき、貴社のAPIがボットから受け取る呼び出しは1分あたり最大120回です。

アクションは情報を読み取るためのものです。注文のキャンセルや返金など、何かを変更するアドレスには向けないでください。そうした操作には、ボットがまだ備えていない確認ステップが必要です。

Next: Widget API →