API連携

マイ API

自社の REST API を、AI ボットの「ツール」として登録します。コードをデプロイする必要はなく、ダッシュボードで仕様を書き、テストし、接続すれば完了です。

#動作

仕様に登録した オペレーション 1 つが、AI が使えるツール 1 つになります。AI はオペレーションの説明を読み、会話の中でいつどのツールを使うかを自分で判断し、必要な値を埋めて呼び出します。

お客様: 「DM-10001 の注文はどこまで来ていますか？電話番号の下 4 桁は 1234 です」
AI → verify_customer(order_no, phone_last4) → お客様を確認
AI → get_order(order_no) — 顧客 ID は本人確認の結果から自動で埋まります
AI: 「CJ 大韓通運で配送中です。[配送を照会する](…)」

リクエストは Cliptalk のサーバー が送ります。キーはサーバーだけで使い、AI モデルには応答データだけが渡されます。

POST https://www.mydomain.com/api/shop/verify
Authorization: Bearer ••••••
Content-Type: application/json

{ "order_no": "DM-10001", "phone_last4": "1234" }

→ 200
{ "ok": true, "customer": { "id": "cus_1001", "name": "クリップ" } }

GET https://www.mydomain.com/api/shop/customers/cus_1001/orders/DM-10001
Authorization: Bearer ••••••

→ 200
{ "ok": true, "order": { "status": "shipped", "status_label": "配送中", … } }

#はじめ方

1
スタジオを開く
プロジェクト → AI ボット → コネクタ マイ API（カスタム定義） → API 仕様を作成。
2
テンプレートを選ぶ
業種に合う標準コネクタを選ぶと、プロジェクトの自社ドメインを基準にしたアドレス（https://www.mydomain.com/api/…）で仕様が埋まります。仕様は API リファレンスにあります。先に体験するなら「デモショップ」サンプルを、最初から作るなら空の仕様を選んでください。
3
保存
上部の保存。シークレットは保存した Base URL に結び付くので、先に保存します。
4
シークレットを入力
シークレット タブでキーを保存します。デモは デモキーを入れる を押してください。
5
テスト
API テスト タブで verify_customer → get_order の順に呼び出します。
6
接続
保存して AI ボットに接続。ウィジェットで「注文を照会してください」と言ってみてください。

#基本設定

項目	説明
`Base URL`	すべてのオペレーションパスの前に付くアドレス。https 必須、公開インターネットのアドレスのみ。例: https://api.example.com/v1
`認証方式`	なし / Bearer トークン / API キーヘッダー / Basic / クエリパラメータ。キーの値ではなく、シークレットの「名前」を選びます。
`追加ヘッダー`	すべてのリクエストに付く固定ヘッダー。キーが必要なら {{secrets.NAME}} で参照します。
`応答タイムアウト`	2〜30 秒。超えると失敗になり、AI がお客様へお詫びします。
`本人確認の案内文`	最初のあいさつに「（…を教えていただくと始まります）」と表示されます。
`できること`	最初のあいさつに一覧で出す機能の説明。
`API 利用ルール`	AI への追加ルール（例: 発送済みの注文は返品を案内する）。

{
  "name": "自社ショップ API",
  "baseUrl": "https://api.example.com/v1",
  "timeoutMs": 12000,
  "auth": { "type": "header", "secret": "API_KEY", "headerName": "x-api-key" },
  "headers": [
    { "name": "X-Store-Id", "value": "store_77" },
    { "name": "X-Store-Token", "value": "{{secrets.STORE_TOKEN}}" }
  ],
  "verifyHint": "注文番号と電話番号の下 4 桁を教えてください",
  "capabilities": ["注文・配送の照会", "発送前の注文キャンセル"]
}

#オペレーションの書き方

項目	説明
`ツール名`	英小文字・数字・_（例: get_order）。動詞で始めると AI が理解しやすくなります。
`説明`	いちばん重要です。何を返すか、いつ使うか、前提条件を具体的に書きます。
`メソッド・パス`	GET/POST/PUT/PATCH/DELETE と Base URL の後ろのパス。{name} は path パラメータです。
`種類`	照会: すぐ呼ぶ · 本人確認: お客様を確認し、結果を覚える · 処理: お客様の同意後に実行
`結果の位置`	応答のうち AI に渡す部分（例: data.orders）。空なら全体。
`顧客情報の位置`	（本人確認）成功応答の中の顧客オブジェクトの位置。既定は customer。
`プレビュー（dry_run）`	（処理）まず dry_run:true で呼び、結果をお客様に見せ、同意後に dry_run:false で実行。

良い説明: 「本人確認済みのお客様の最近の注文一覧（注文番号・商品・金額・状態）を新しい順に照会する。配送の問い合わせでは最初に使う。」
弱い説明: 「注文 API」

オペレーションは 5〜15 個くらいが適当です。似たものが多すぎると AI が迷います。

#パラメータ

パラメータには位置（path · query · body · header）と 値の出どころ があります。

値の出どころ	説明	例
`AI が会話から埋める`	お客様の発言から AI が値を取ります。説明・例・許可値を書くと正確になります。	order_no, date
`本人確認の顧客情報`	本人確認の成功応答にある顧客オブジェクトから取ります。AI が勝手に変えられないので安全です。	customer_id ← id
`固定値`	いつも同じ値。	limit = 10

body パラメータ名にドットを付けると入れ子のオブジェクトになります: address.zip → {"address":{"zip":"…"}}

顧客 ID のように「誰のデータか」を決める値は、必ず 本人確認の顧客情報 で埋めてください。AI に埋めさせると、別のお客様の ID を入れようとする操作を止めにくくなります。API サーバー側でも所有権を再確認してください。

{
  "name": "get_order",
  "title": "注文詳細・配送照会",
  "description": "注文 1 件の詳細（商品、決済金額、配送状態、送り状番号）を照会する。",
  "method": "GET",
  "path": "/customers/{customer_id}/orders/{order_no}",
  "kind": "read",
  "params": [
    { "name": "customer_id", "in": "path", "type": "string",
      "required": true, "source": "customer", "value": "id" },
    { "name": "order_no", "in": "path", "type": "string",
      "required": true, "source": "model",
      "description": "注文番号", "example": "DM-10001" }
  ]
}

#本人確認

顧客情報を扱うには、本人確認 種類のオペレーションが 1 つ必要です。お客様が伝えた情報（注文番号 + 電話番号の下桁、予約番号 + 名前など）を API に送り、一致したら顧客オブジェクトを返してください。

成功応答の顧客オブジェクト（既定の位置 customer）は相談の間記憶され、「本人確認の顧客情報」パラメータに使われます。
顧客オブジェクトは短く: id と name 程度。パスワード・トークン・カードなどのフィールドは自動で除かれます。
本人確認が必要なオペレーションは、確認前には呼ばれません（Cliptalk がブロックします）。
失敗時は { "ok": false, "message": "…" } を返すと、AI がその文でもう一度尋ねます。

// 成功
{ "ok": true, "customer": { "id": "cus_1001", "name": "クリップ", "grade": "VIP" } }

// 失敗（HTTP 200 でも ok:false なら失敗）
{ "ok": false, "error": "not_found",
  "message": "注文番号と電話番号の下 4 桁が一致するお客様が見つかりませんでした。" }

#処理オペレーションとお客様の確認

処理種類（キャンセル・変更・申請）は、AI が呼んでもすぐには実行されません。

AI が処理ツールを呼ぶと、Cliptalk が提案を作ります。プレビューがオンなら、このとき dry_run: true で API を呼び、結果を受け取ります。
お客様には内容とともに はい いいえ ボタンが表示されます。
同意すると同じ値で dry_run: false を呼び、実際に処理します。結果は相談記録に「AI 処理記録」メモとして残ります。
30 分たつと提案は期限切れになります。

プレビュー応答に summary（文字列の配列）を入れると、確認カードにそのまま表示されます。

// POST …/orders/DM-10002/cancel  { "dry_run": true }
{
  "ok": true,
  "dry_run": true,
  "summary": [
    "注文番号: DM-10002",
    "商品: ワイヤレス充電パッド 15W x2",
    "返金予定額: 38,000 ウォン（3〜5 営業日）"
  ]
}

// お客様の同意後 { "dry_run": false }
{
  "ok": true,
  "status": "cancelled",
  "message": "注文 DM-10002 をキャンセルしました。"
}

#シークレット

API キー・トークン・パスワードは シークレット タブだけで入力します。

入力と同時に AES-256-GCM で暗号化して保存され、保存後は 誰にも再表示されません（管理者を含む）。変えるときは同じ名前で新しい値を保存します。
AI モデル、ブラウザ、チャット履歴、テスト結果のどこにもキーの値は出ません。API が応答にキーを返しても伏せられます。
キーは 保存したときの Base URL のドメインにだけ 送られます。仕様のアドレスを別ドメインに変えるとキーはロックされ、再入力が必要です（編集権限のある人がアドレスを変えてキーを持ち出すのを防ぎます）。
仕様では、認証設定のシークレット名か、ヘッダー値の {{secrets.NAME}} でのみ参照します。パラメータ（クエリ・本文）には入れられません。

推奨: ボット専用のキーを新しく発行し、照会と必要な処理だけができる最小権限にしてください。可能なら API サーバーで Cliptalk サーバーの IP だけを許可するとより安全です。漏えいが疑われるときは発行元で破棄し、新しいキーを保存してください。

// 認証設定 — Authorization: Bearer <API_KEY の値>
"auth": { "type": "bearer", "secret": "API_KEY" }

// 追加ヘッダーから参照
"headers": [
  { "name": "X-Store-Token", "value": "{{secrets.STORE_TOKEN}}" }
]

// こうしない（仕様に平文で残る）
"headers": [{ "name": "x-api-key", "value": "sk_live_abc123" }]

#API テスト

API テスト タブは、AI が会話中に呼ぶのと同じように Cliptalk サーバーからリクエストを送ります。保存前の編集内容でもテストできます。

応答 — ステータスコード、応答時間、サイズ、JSON 本文
AI が受け取る結果 — 結果の位置とサイズ制限を適用したあと、AI に渡る内容
送ったリクエスト — 実際の URL・ヘッダー・本文（キーは伏字）
対処 — 401・404・タイムアウトなど、失敗原因ごとの案内

本人確認のオペレーションを先にテストすると、返ってきた顧客情報が テスト用の顧客情報 に自動で入り、続いて顧客情報が必要なオペレーションをテストできます。処理オペレーションは既定で dry_run プレビューとして呼ばれます。

テストはプロジェクトあたり毎分 30 回までです。

#OpenAPI の取り込み

すでに OpenAPI 3 / Swagger 2 の文書がある場合は、JSON・取り込み タブに貼るとオペレーションを一度に作れます。パス・パラメータ・JSON リクエスト本文・認証方式を変換します（最大 30 個）。

取り込んだあとは必ず整えてください。不要なオペレーションをオフにし、説明を「いつ使うか」中心に直し、顧客 ID パラメータを「本人確認の顧客情報」に変え、GET 以外の種類（処理 / 照会）を確認します。

#制限

項目	値
`オペレーション数`	最大 30（推奨 5〜15）
`オペレーションあたりのパラメータ`	最大 25
`シークレット`	最大 10
`リクエストの制限時間`	2〜30 秒（既定 12 秒）
`応答サイズ`	1MB まで読み、AI には約 12,000 字まで渡す
`アドレス`	https + 公開インターネットのみ。社内網・localhost・クラウドのメタデータアドレスはブロック。リダイレクトは追わない
`適用`	保存後、最大 20 秒で新しい会話から