डेवलपर्स

Granetra पर निर्माण करें

आपके AI सहायता एजेंटों के लिए एक साफ REST API और साइन किए गए वेबहुक्स। अपने डैशबोर्ड के डेवलपर्स पृष्ठ में एक कुंजी बनाएं और मिनटों में निर्माण शुरू करें।

API कुंजी प्राप्त करें संदर्भ पढ़ें

https://granetra.com/api/v1

REST API

बॉट्स की सूची बनाएं, वार्तालाप और प्रतिलिपियाँ पढ़ें, चैट संदेश भेजें, और एजेंटिक क्रियाओं का प्रबंधन करें — सभी एक स्कोप्ड बियरर कुंजी के साथ।

साइन किए गए वेबहुक्स

जब एक वार्तालाप शुरू होता है, एक आगंतुक मानव से पूछता है, या एक लीड कैप्चर होती है, उस क्षण एक टाइमस्टैम्पेड-HMAC POST प्राप्त करें — पुनः प्रयास और एक डिलीवरी लॉग के साथ।

स्वचालन के लिए बनाया गया

कुंजियों को घुमाएं, उन्हें अपने सर्वर IPs पर लॉक करें, और 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.

हस्ताक्षरों की पुष्टि करना

प्रत्येक वेबहुक में X-Granetra-Signature हेडर होता है जो t=<unix>,v1=<hmac> के रूप में होता है। अपने एंडपॉइंट के साइनिंग सीक्रेट के साथ `${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 के साथ प्रतिक्रिया दें। Non-2xx या टाइमआउट के साथ पुनः प्रयास किया जाता है; एक लंबी विफलता रन स्वचालित रूप से एंडपॉइंट को अक्षम कर देती है।

अपने IPs के लिए एक कुंजी को लॉक करना

एक कुंजी एक वैकल्पिक IP अनुमति सूची (व्यक्तिगत IPv4 पते या CIDR रेंज) ले जा सकती है। जब सेट किया जाता है, तो किसी अन्य पते से अनुरोधों को 403 ip_not_allowed के साथ अस्वीकृत किया जाता है। इसे डैशबोर्ड में प्रति कुंजी प्रबंधित करें।