API REST et webhooks

Une seule API derrière tout : l'inbox, Telegram, Discord, le serveur MCP et la CLI en sont tous des clients.

Principes

• Adresse de base : https://app.inngame.app/v1 (l'ancienne https://inngame.meffysto.workers.dev/v1 marche toujours)
• Authentification : Authorization: Bearer ig_sk_… (une clé d'API). La clé détermine l'organisation.
• Format : JSON en entrée et en sortie. Les dates sont en millisecondes Unix. Les identifiants sont des chaînes préfixées (cnv_…, msg_…, eu_… pour les joueurs, bug_…).
• Erreurs : un statut hors 2xx avec {"error": "code", "message": "…"}. Codes courants : invalid_api_key (401), requires_reply / requires_admin (403), human_approval_required / human_session_required (403 : réservé à une personne connectée, quel que soit le droit de la clé), conversation_not_found, bug_not_found, app_not_found (404 ; aussi pour tout ce qui appartient à une autre organisation), invalid_request (422).
• Droits : read < reply < all. Dans les tableaux ci-dessous, all correspond aux droits d'admin. Chaque écriture est notée dans le journal d'actions.
• Limites : 300 requêtes par minute par clé d'API ; pour les joueurs, 20 messages ou envois de fichiers et 60 événements par minute. Au-delà, vous recevez 429 rate_limited : attendez une minute et réessayez.
• Pagination : les listes renvoient jusqu'à 50 éléments (100 au plus avec limit) et un curseur : passez nextBefore comme before pour les conversations, ou le plus ancien seq comme before pour les messages.

curl "https://app.inngame.app/v1/conversations?status=open&unread=1" \
  -H "Authorization: Bearer $INNGAME_API_KEY"

Conversations et messages

Cartes

Ajoutez une card à un message pour afficher un bouton dans le chat :

{
  "body": "Sorry about that! Here's a little something.",
  "card": {
    "kind": "item",                 // review | offer | link | screen | item | refund | restore
    "label": "Claim",
    "item": { "id": "gems_500", "name": "500 gems", "quantity": 1 }
  }
}

Autres champs : url (lien, repli pour l'avis), screen et value (écran), offerId (offre). Une carte item ne se récupère qu'une fois ; vous recevez un webhook item.claimed pour donner l'objet sur votre serveur. Seule une personne connectée peut envoyer une carte item : les clés d'API reçoivent 403 human_approval_required.

Omettez label sur les cartes review et refund pour afficher le texte du SDK dans la langue du joueur (« Laisser un avis », « Demander un remboursement »). Les cartes envoyées par Inngame lui-même portent le libellé anglais par défaut plus "defaultLabel": true ; les SDK 0.2.2 et suivants le remplacent par le texte traduit.

Joueurs

Apps, organisation et clés

Bugs

Les mêmes bugs que sur la page Bugs de l'inbox. Chaque bug a une url vers cette page, que vos coéquipiers peuvent ouvrir depuis Telegram, Discord, le point hebdomadaire ou le résumé d'un agent.

Remboursements

FAQ et automatisations

Une automatisation a un triggerEvent (un événement du jeu ou un événement d'abonnement comme trial_started, subscription_cancelled, billing_issue), une frequency, une audience (règles sur les métadonnées du joueur), un delay (now, minutes ou local_time) et des actions : message, card (offre, lien, écran, objet), review, open_chat, wait.

Routes du SDK

Les SDK appellent /v1/sdk/* avec la clé publique de l'app dans X-App-Key et un jeton d'appareil en bearer. Ne les utilisez directement que si vous écrivez votre propre client (un jeu web, un autre moteur).

Webhooks

Les webhooks envoient des événements à votre serveur : donner les objets récupérés, garder une trace des remboursements, prévenir quelqu'un lors d'une vague de bugs. Gérez-les dans l'inbox (Réglages → Webhooks) ou par l'API, connecté en admin. Les clés d'agent ne peuvent ni créer ni lire de webhooks, même avec le droit all : un webhook peut envoyer chaque message vers n'importe quelle adresse, c'est donc une personne qui le met en place.

Chaque envoi est un POST avec un corps JSON, un user-agent Inngame-Webhooks/1 et un en-tête inngame-signature. Répondez en 2xx sous 8 secondes. Les envois ratés (erreurs réseau, délais dépassés, 408, 429 et 5xx) sont retentés après environ 1 et 5 minutes, puis 30 minutes, 2, 6 et 12 heures : sept tentatives sur à peu près une journée. Un autre 4xx vaut refus et n'est pas retenté. Les nouvelles tentatives gardent le même id d'événement : rendez votre traitement idempotent. Le dernier résultat figure sur le webhook (last_status, last_error, tentatives pending). POST /webhooks/:id/test n'envoie un ping qu'à ce webhook.

{
  "id": "evt_8sd7f6g5h4j3k2l1m0n9",
  "type": "item.claimed",
  "created": 1793452800000,
  "appId": "app_...",
  "data": {
    "messageId": "msg_...",
    "conversationId": "cnv_...",
    "player": { "id": "eu_...", "externalId": "player-1842", "steamId": null },
    "card": { "kind": "item", "label": "Claim", "item": { "id": "gems_500", "name": "500 gems", "quantity": 1 }, "claimedAt": 1793452800000 },
    "action": "claimed"
  }
}

Liste des événements

Vérifier les signatures

L'en-tête ressemble à ceci :

inngame-signature: t=1793452800,v1=pZ3f…Kq8

• t est l'heure Unix en secondes de l'envoi de l'événement.
• v1 est le HMAC-SHA256 de la chaîne t + "." + corps brut, avec votre secret de webhook comme clé, encodé en base64url (sans remplissage).
• Calculez-le sur le corps brut de la requête, avant tout parsing JSON. Comparez en temps constant, et refusez les événements dont le t date de plus de 5 minutes.

// Node.js (Express)
import crypto from "node:crypto";

app.post("/inngame-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("inngame-signature") ?? "";
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const t = Number(parts.t);
  const body = req.body.toString("utf8");
  const expected = crypto
    .createHmac("sha256", process.env.INNGAME_WEBHOOK_SECRET)
    .update(`${t}.${body}`)
    .digest("base64url");
  const ok =
    parts.v1 &&
    parts.v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected)) &&
    Math.abs(Date.now() / 1000 - t) < 300;
  if (!ok) return res.status(400).send("bad signature");

  const event = JSON.parse(body);
  if (event.type === "item.claimed") grantItem(event.data.player, event.data.card.item);
  res.sendStatus(200);
});

# Python
import base64, hashlib, hmac, time

def verify(header: str, body: bytes, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = parts.get("t", "")
    mac = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).digest()
    expected = base64.urlsafe_b64encode(mac).rstrip(b"=").decode()
    return hmac.compare_digest(parts.get("v1", ""), expected) and abs(time.time() - int(t)) < 300