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": "…" }웹훅 이벤트
각 배달은 다음과 같은 형식의 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.
서명 검증
모든 웹훅은 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로 거부됩니다. 대시보드에서 키별로 관리하세요.