REST API
ボットのリスト、会話やトランスクリプトの読み取り、チャットメッセージの送信、エージェントアクションの管理 — すべてスコープ付きのベアラキーで行えます。
署名付きウェブフック
会話が始まった瞬間、訪問者が人間を求めたとき、またはリードがキャプチャされたときに、タイムスタンプ付きHMAC POSTを取得 — リトライと配信ログ付き。
自動化のために構築
キーをローテーションし、サーバーIPにロックし、CI/CDからボットの設定を管理します。ダッシュボードが行うすべてをAPI経由で実行。
APIリファレンス
ベースURL： https://granetra.com/api/v1
認証
すべてのリクエストでAPIキーをベアラートークンとして渡してください：
Authorization: Bearer gk_your_key_here
キーはスコープ付きです。あなたのキーがスコープされていないエンドポイントへのリクエストは403 insufficient_scopeを返します。利用可能なスコープ： bots:read, conversations:read, chat:write, actions:read, actions:write.
エンドポイント
| GET | /bots | ボットのリスト |
| GET | /bots/:id | 単一のボット |
| GET | /bots/:id/conversations | 会話のリスト |
| GET | /conversations/:id | 会話のトランスクリプト |
| POST | /chat | メッセージを送信し、返信を取得 |
| GET | /bots/:id/actions | ボットのエージェントアクションのリスト |
| POST | /bots/:id/actions | アクションを作成 |
| PATCH | /bots/:id/actions/:actionId | アクションを更新 |
| DEL | /bots/:id/actions/:actionId | アクションを削除 |
チャットメッセージを送信
curl -X POST https://granetra.com/api/v1/chat \
-H "Authorization: Bearer gk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"bot_id": "00000000-0000-0000-0000-000000000000",
"message": "What are your opening hours?"
}'
# → { "conversation_id": "…", "message_id": "…", "fallback": false, "reply": "We're open 9–5 Mon–Fri." }
# Pass the returned conversation_id back to continue the same thread.エージェントアクションを管理
会話中にボットが呼び出せるツールとして独自のHTTPSエンドポイントを登録します。ダッシュボードではなくCI/CDから管理できます。actions:writeスコープとScaleプランのボットが必要です。
curl -X POST https://granetra.com/api/v1/bots/BOT_ID/actions \
-H "Authorization: Bearer gk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "lookup_order",
"description": "Look up an order status by number",
"url": "https://api.yourstore.com/orders",
"method": "GET",
"parameters": [
{ "name": "order_number", "type": "string", "description": "The order #", "required": true }
]
}'
# → { "ok": true, "id": "…" }Webhookイベント
各配信はこのエンベロープを持つJSON POSTです：
{
"id": "delivery-uuid",
"type": "handoff.requested",
"created": "2026-07-20T12:00:00.000Z",
"data": { "bot_id": "…", "conversation_id": "…" }
}イベントタイプ： conversation.created, handoff.requested, lead.captured.
署名の検証
すべてのWebhookは、t=<unix>,v1=<hmac>形式のX-Granetra-Signatureヘッダーを持っています。エンドポイントの署名シークレットを使用して`${t}.${rawBody}`のHMAC-SHA256を再計算し、比較してください：
import crypto from "node:crypto";
function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const expected = crypto
.createHmac("sha256", secret)
.update(`${parts.t}.${rawBody}`)
.digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}確認のために任意の2xxで応答してください。非2xxまたはタイムアウトはバックオフで再試行されます；長時間の失敗が続くとエンドポイントが自動的に無効になります。
キーをあなたのIPにロック
キーにはオプションのIP許可リスト（個別のIPv4アドレスまたはCIDR範囲）を持たせることができます。設定されている場合、他のアドレスからのリクエストは403 ip_not_allowedで拒否されます。ダッシュボードでキーごとに管理できます。