Bauen Sie auf Granetra
Eine saubere REST-API und signierte Webhooks fĂĽr Ihre KI-Support-Agenten. Erstellen Sie einen SchlĂĽssel auf der Entwicklersseite Ihres Dashboards und beginnen Sie in wenigen Minuten mit dem Bauen.
https://granetra.com/api/v1REST API
Listen Sie Bots auf, lesen Sie Gespräche und Transkripte, senden Sie Chatnachrichten und verwalten Sie agentische Aktionen — alles mit einem scoped Bearer-Key.
Signierte Webhooks
Erhalten Sie einen timestamped-HMAC POST, sobald ein Gespräch beginnt, ein Besucher um einen Menschen bittet oder ein Lead erfasst wird — mit Wiederholungen und einem Lieferprotokoll.
FĂĽr Automatisierung gebaut
Rotieren Sie SchlĂĽssel, sperren Sie sie an Ihre Server-IP-Adressen und steuern Sie die Bot-Konfiguration ĂĽber CI/CD. Alles, was das Dashboard tut, ĂĽber die API.
API-Referenz
Basis-URL: https://granetra.com/api/v1
Authentifizierung
Ăśbergeben Sie Ihren API-SchlĂĽssel als Bearer-Token bei jeder Anfrage:
Authorization: Bearer gk_your_key_here
SchlĂĽssel sind scoped. Eine Anfrage an einen Endpunkt, fĂĽr den Ihr SchlĂĽssel nicht scoped ist, gibt 403 insufficient_scope zurĂĽck. VerfĂĽgbare Scopes: bots:read, conversations:read, chat:write, actions:read, actions:write.
Endpunkte
| GET | /bots | Listen Sie Ihre Bots auf |
| GET | /bots/:id | Ein einzelner Bot |
| GET | /bots/:id/conversations | Gespräche auflisten |
| GET | /conversations/:id | Ein Gesprächstranskript |
| POST | /chat | Eine Nachricht senden, eine Antwort erhalten |
| GET | /bots/:id/actions | Agentische Aktionen eines Bots auflisten |
| POST | /bots/:id/actions | Eine Aktion erstellen |
| PATCH | /bots/:id/actions/:actionId | Eine Aktion aktualisieren |
| DEL | /bots/:id/actions/:actionId | Eine Aktion löschen |
Chat-Nachricht senden
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.Agentische Aktionen verwalten
Registrieren Sie Ihre eigenen HTTPS-Endpunkte als Werkzeuge, die der Bot während des Gesprächs aufrufen kann – verwalten Sie sie über CI/CD anstelle des Dashboards. Erfordert den actions:write Scope und einen Bot im Scale-Plan.
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-Ereignisse
Jede Lieferung ist ein JSON-POST mit diesem Umschlag:
{
"id": "delivery-uuid",
"type": "handoff.requested",
"created": "2026-07-20T12:00:00.000Z",
"data": { "bot_id": "…", "conversation_id": "…" }
}Ereignistypen: conversation.created, handoff.requested, lead.captured.
Signaturen verifizieren
Jeder Webhook trägt einen X-Granetra-Signature-Header der Form t=<unix>,v1=<hmac>. Berechnen Sie das HMAC-SHA256 von `${t}.${rawBody}` mit dem Signaturgeheimnis Ihres Endpunkts und vergleichen Sie:
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));
}Antworten Sie mit einem beliebigen 2xx, um zu bestätigen. Non-2xx oder ein Timeout wird mit Backoff erneut versucht; ein längerer Fehlerlauf deaktiviert den Endpunkt automatisch.
Einen SchlĂĽssel an Ihre IPs binden
Ein SchlĂĽssel kann eine optionale IP-Whitelist (einzelne IPv4-Adressen oder CIDR-Bereiche) tragen. Wenn festgelegt, werden Anfragen von jeder anderen Adresse mit 403 ip_not_allowed abgelehnt. Verwalten Sie es pro SchlĂĽssel im Dashboard.