Actions de modification

Définir une modification#

Utilisez une action de modification pour mettre à jour un enregistrement dans votre propre système, par exemple pour annuler une commande. Ouvrez Agent → Actions, configurez le secret de votre agent dans Clients connectés, puis ajoutez une Action de modification : un nom unique, une description des cas d'utilisation, un point de terminaison HTTPS public et des entrées de type chaîne déclarées. Un nom tel que cancel_order devient l'outil du modèle change_cancel_order. Les modifications des actions existantes sont enregistrées automatiquement ; attendez l'indicateur d'enregistrement.

Laissez l'option Client connecté requis activée pour les enregistrements privés. Votre point de terminaison doit tout de même vérifier que le client authentifié est autorisé à accéder à l'enregistrement demandé, à partir de son identifiant vérifié. Un nom, un e-mail ou un numéro de commande saisi dans le chat ne constitue pas une preuve d'identité. Si vous désactivez ce paramètre, customer peut être nul : n'autorisez alors que les modifications adaptées à des visiteurs anonymes. Les paiements sont en dehors du périmètre de cette fonctionnalité.

Choisir l'approbation du propriétaire#

La confirmation du client est requise dans tous les modes :

Consultez les demandes en attente dans Agent → Actions → Approbations. Le propriétaire du site peut approuver ou refuser. Si des alertes privées Telegram pour le propriétaire sont associées, l'alerte comporte aussi les boutons Approuver / Refuser. Seul le chat privé du propriétaire associé peut les utiliser ; les appuis expirés ou répétés ne peuvent pas déclencher une nouvelle exécution. L'approbation expire 24 heures après la confirmation du client. Le client reçoit le résultat, y compris un refus ou une expiration. Les exécutions récentes affichent le statut, les horodatages, la référence et l'identifiant du client.

Ce que reçoit votre point de terminaison#

Aucune requête n'est envoyée lorsque le modèle propose la modification. Après la confirmation du client et l'éventuelle approbation requise du propriétaire, Make Agent Fast envoie :

POST /agent/cancel-order HTTP/1.1
Content-Type: application/json
x-maf-timestamp: <unix-seconds>
x-maf-signature: v1=<64-lowercase-hex-characters>
x-maf-idempotency-key: c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b

{
  "version": 1,
  "action": "cancel_order",
  "runId": "c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b",
  "requestId": "c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b",
  "siteId": "YOUR_SITE_ID",
  "input": { "order_id": "A128" },
  "customer": { "id": "customer_123", "email": "customer@example.com" }
}

action n'inclut pas le préfixe change_. Les deux identifiants et l'en-tête d'idempotence restent identiques lors des nouvelles tentatives. input ne contient que des chaînes déclarées et nettoyées des espaces superflus ; customer est nul ou correspond à l'objet vérifié comprenant id et, en option, email/name.

Utilisez le vérificateur de signature des consultations : HMAC-SHA256 avec le secret de votre agent sur "maf-webhook-v1:" + timestamp + "." + rawBody, en hexadécimal minuscule précédé de v1=. Vérifiez les octets d'origine, la fraîcheur de l'horodatage, le site et l'action attendus, ainsi que l'appartenance au client avant toute écriture. Dédoublonnez de façon atomique x-maf-idempotency-key avec votre modification et conservez le résultat. Une requête répétée doit renvoyer le résultat enregistré sans modifier à nouveau l'enregistrement. Le verrouillage de la plateforme ne peut pas remplacer le dédoublonnage dans votre système.

Renvoyer un résultat#

Renvoyez un JSON 2xx avec le champ obligatoire status (done, pending ou failed) et les champs facultatifs message, reference et card :

{
  "status": "done",
  "message": "Order cancelled.",
  "reference": "A128",
  "card": {
    "kind": "status",
    "title": "Order A128",
    "fields": [{ "label": "Order", "value": "A128" }]
  }
}

La carte de statut facultative requiert title et fields ; kind: "status" est facultatif. Elle prend en charge status: { label, tone }, reference, asOf et link: { label, url }, comme dans les consultations. Les tons possibles sont neutral, success, warning ou danger ; les liens doivent être des URL HTTPS sûres. Les champs de schéma inconnus sont rejetés. Gardez des textes courts et simples. Le status de niveau supérieur détermine le résultat ; le libellé de la carte ne peut pas transformer un résultat en attente en succès.

Utilisez done uniquement lorsque la modification est terminée, pending lorsqu'elle est encore en cours de traitement, et failed en cas d'échec avéré. Les délais d'attente dépassés, les erreurs réseau, les erreurs 5xx et les réponses invalides sont considérés comme incertains (unknown). Le rapprochement réessaie après une minute, puis cinq minutes, avec au maximum trois tentatives d'exécution et la même clé ; la planification des files d'attente peut retarder ces délais. Une erreur HTTP 4xx échoue sans nouvelle tentative. Si l'incertitude persiste après épuisement des tentatives, l'exécution échoue et le propriétaire est averti, mais cela ne prouve pas que votre système n'a effectué aucune modification. Vérifiez avant de lancer une autre exécution. pending ne déclenche pas de nouvelle exécution.

Envoyer un rappel final signé#

Lorsqu'une exécution pending ou unknown est résolue, envoyez une réponse finale par POST à https://makeagent.fast/api/agent/actions/RUN_ID/callback. Envoyez le même contrat de réponse avec status: "done" ou "failed" ; pending n'est pas accepté ici.

Contrat de rappel mis à jour le 2026-10-14 : signez maf-callback-v1: + runId + : + timestamp + . + rawBody. Si le corps contient runId, il doit correspondre à l'identifiant d'exécution du chemin ; une différence renvoie 400. Les signatures d'une autre exécution ou de l'ancien format non lié renvoient 403.

import { createHmac } from "node:crypto";

const body = JSON.stringify({ status: "done", reference: "A128" });
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = createHmac("sha256", agentSecret)
  .update(`maf-callback-v1:${runId}:${timestamp}.${body}`)
  .digest("hex");
const response = await fetch(
  `https://makeagent.fast/api/agent/actions/${encodeURIComponent(runId)}/callback`,
  {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-maf-timestamp": timestamp,
      "x-maf-signature": `v1=${signature}`,
    },
    body,
  },
);

Utilisez le secret de votre agent conservé côté serveur et l'identifiant d'exécution reçu dans la requête d'origine. Le rappel utilise maf-callback-v1:, et non l'espace de noms de la requête sortante. Le décalage d'horodatage doit rester inférieur à cinq minutes. Les signatures invalides renvoient 403 ; les corps invalides renvoient 400 ; une exécution déjà terminée ou incompatible renvoie 409. Un rappel répété n'écrase pas le résultat final. Effectuez la rotation de ce secret en même temps que votre configuration d'identité et de signature du point de terminaison.

Confirmation du client et accusés#

Le client examine les entrées exactes et appuie sur Confirmer ou Annuler dans la proposition. Une proposition expire après 15 minutes ; une nouvelle proposition pour la même action et la même conversation remplace l'ancienne. La confirmation utilise un jeton lié à cette exécution, à ce site et à ce visiteur. Saisir « oui » ou cliquer sur une carte de confirmation générique n'autorise pas la modification. Les boutons de répétition sont inactifs et n'appellent pas votre point de terminaison.

Sur le web, le widget ouvert interroge régulièrement les accusés non terminaux, d'abord toutes les cinq secondes, puis toutes les 30 secondes, pendant 24 heures au maximum. Un accusé peut indiquer : demandé, en attente du propriétaire, en cours, en attente (pending), vérification d'un résultat inconnu, terminé, échoué, refusé, annulé ou expiré. Seul done confirme l'achèvement.

Les propositions sur les canaux fonctionnent uniquement dans les chats privés, jamais dans les groupes ou les canaux publics. Les accusés différés utilisent la file d'envoi durable : les messages privés ordinaires de bot Telegram sont pris en charge ; WhatsApp, Messenger, Instagram et Telegram Business exigent un message entrant enregistré dans les dernières 24 heures, vérifié à nouveau au moment de l'envoi. L'envoi différé n'est pas disponible pour les requêtes invité Telegram, Discord et KakaoTalk. Les fenêtres fermées et les connexions désactivées peuvent empêcher la livraison ; l'historique des exécutions enregistre néanmoins le résultat.

Limites et tests#

Utilisez un point de terminaison contrôlé pour vérifier la confirmation, l'annulation, l'approbation, le délai d'attente dépassé, la gestion des clés en double et les rappels finaux. Vérifiez ses enregistrements, et pas seulement le texte de l'accusé. La répétition prouve qu'aucune écriture externe n'a lieu ; ce n'est pas un test d'exécution du point de terminaison. Testez chaque canal privé prévu avant de vous fier aux accusés.