Développeurs

Développez sur Granetra

Une API REST propre et des webhooks signés pour vos agents de support AI. Créez une clé dans la page Développeurs de votre tableau de bord et commencez à construire en quelques minutes.

Obtenir une clé API Lire la référence

https://granetra.com/api/v1

API REST

Listez les bots, lisez les conversations et les transcriptions, envoyez des messages de chat et gérez les actions agentiques — le tout avec une clé bearer spécifique.

Webhooks signés

Recevez un POST HMAC horodaté au moment où une conversation commence, un visiteur demande un humain, ou un lead est capturé — avec des réessais et un journal de livraison.

Conçu pour l'automatisation

Faites tourner les clés, verrouillez-les sur les adresses IP de votre serveur, et gérez la configuration des bots depuis CI/CD. Tout ce que fait le tableau de bord, via l'API.

Référence API

URL de base : https://granetra.com/api/v1

Authentification

Passez votre clé API en tant que jeton bearer à chaque requête :

Authorization: Bearer gk_your_key_here

Les clés sont spécifiques. Une demande à un point de terminaison pour lequel votre clé n'est pas spécifique renvoie 403 insufficient_scope. Portées disponibles : bots:read, conversations:read, chat:write, actions:read, actions:write.

Points de terminaison

GET	`/bots`	Lister vos bots
GET	`/bots/:id`	Un seul bot
GET	`/bots/:id/conversations`	Lister les conversations
GET	`/conversations/:id`	Une transcription de conversation
POST	`/chat`	Envoyer un message, obtenir une réponse
GET	`/bots/:id/actions`	Lister les actions agentiques d'un bot
POST	`/bots/:id/actions`	Créer une action
PATCH	`/bots/:id/actions/:actionId`	Mettre à jour une action
DEL	`/bots/:id/actions/:actionId`	Supprimer une action

Envoyer un message de chat

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.

Gérer les actions agentiques

Enregistrez vos propres points de terminaison HTTPS comme outils que le bot peut appeler en cours de conversation — gérez-les depuis CI/CD au lieu du tableau de bord. Nécessite le scope actions:write et un bot sur le plan 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": "…" }

Événements Webhook

Chaque livraison est un POST JSON avec cette enveloppe :

{
  "id": "delivery-uuid",
  "type": "handoff.requested",
  "created": "2026-07-20T12:00:00.000Z",
  "data": { "bot_id": "…", "conversation_id": "…" }
}

Types d'événements : conversation.created, handoff.requested, lead.captured.

Vérification des signatures

Chaque webhook contient un en-tête X-Granetra-Signature de la forme t=<unix>,v1=<hmac>. Recalculez le HMAC-SHA256 de `${t}.${rawBody}` avec le secret de signature de votre point de terminaison et comparez :

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));
}

Répondez avec un code 2xx pour accuser réception. Un code non-2xx ou un délai d'attente sera réessayé avec un backoff ; une longue série d'échecs désactive automatiquement le point de terminaison.

Verrouillage d'une clé à vos IP

Une clé peut comporter une liste d'autorisation IP optionnelle (adresses IPv4 individuelles ou plages CIDR). Lorsqu'elle est définie, les demandes provenant de toute autre adresse sont rejetées avec 403 ip_not_allowed. Gérez-la par clé dans le tableau de bord.