Actions de page

Enregistrer une action côté site#

Les actions de page permettent au site web d'ouvrir sa propre interface ou de naviguer vers une page approuvée. Installez l'intégration (embed) dans sa version actuelle, puis lancez l'enregistrement une fois le script chargé. Conservez les gestionnaires dans votre application : l'agent reçoit uniquement leurs noms, leurs descriptions et la définition de leurs paramètres, jamais le code des gestionnaires.

MakeAgentFast.registerAction("show_details", {
  description: "Show the details section on this page",
  params: { section: { type: "string", description: "Use delivery or returns" } },
  confirm: true
}, async ({ section }) => {
  const sections = {
    delivery: document.getElementById("delivery-details"),
    returns: document.getElementById("returns-details")
  };
  if (!Object.hasOwn(sections, section) || !sections[section]) {
    throw new Error("Unknown section");
  }
  sections[section].scrollIntoView({ block: "start" });
  return { shown: section };
});

// Run when the page component unmounts:
// MakeAgentFast.unregisterAction("show_details");

Les deux méthodes renvoient un booléen indiquant si l'enregistrement ou la suppression a été accepté. Les noms utilisent des lettres minuscules, des chiffres et des tirets bas (underscores), commencent par une lettre et comptent de 2 à 40 caractères. Il existe neuf emplacements d'enregistrement personnalisés, plus l'action intégrée open_page. Chaque définition autorise cinq paramètres de type chaîne ; tous les paramètres déclarés sont obligatoires, avec des valeurs allant jusqu'à 200 caractères. Les descriptions sont limitées à 200 caractères. Un gestionnaire peut renvoyer une chaîne ou une valeur sérialisable en JSON, jusqu'à 2 Ko, en moins de 10 secondes.

Approuver les actions dans le tableau de bord#

Ouvrez le site web sur lequel l'intégration est installée afin qu'il signale les noms et descriptions de ses actions, puis ouvrez Agent → Actions → Actions de page. Activez la fonctionnalité et autorisez chacune des actions prévues. Les descriptions signalées sont des métadonnées du site web non fiables ; la détection n'approuve rien. Les paramètres sont enregistrés automatiquement.

L'agent ne peut proposer que les actions qui sont à la fois actuellement enregistrées et autorisées. Le customer voit une carte avant l'exécution. Une confirmation est requise, sauf si l'owner marque l'action comme sûre ; confirm: true dans le code de votre site exige toujours un appui de la part du customer. confirm: false seul ne contourne pas la politique de l'owner. Réservez le mode sûr aux modifications d'interface sans conséquence.

L'action intégrée open_page n'a besoin d'aucun gestionnaire. Autorisez-la dans le tableau de bord ; elle accepte un chemin relatif ou une URL HTTP(S) appartenant aux origines de site web autorisées de l'agent. Les chemins relatifs exigent également que l'origine du site web actuel soit autorisée. Elle ne peut pas rediriger vers une destination externe arbitraire.

Signaler un événement avec track#

MakeAgentFast.track("form_error", { formId: "contact" });
MakeAgentFast.track("checkout_help", { step: "delivery" });

Appelez ces méthodes après le chargement de l'embed, et uniquement lorsque l'événement correspondant se produit réellement. Configurez un nom d'événement correspondant dans Relances. Les noms suivent le même format de 2 à 40 caractères ; les données facultatives doivent être un objet JSON d'au plus 1 Ko. N'envoyez pas de valeurs de champs, d'identifiants ni de données de paiement. Les règles s'appliquent selon l'événement, le chemin et le délai ; les métadonnées ne sont ni stockées, ni transmises au modèle, ni utilisées comme preuve de conversion. Un retour true signifie que le loader a accepté l'événement, et non qu'un message a été affiché.

Sécurité et vérification#

Les actions de page fonctionnent dans le widget du site web en production, mais pas dans les channels de messagerie, ni dans les essais de l'owner, ni en voix en direct. Le loader et la frame vérifient l'origine, la source, le slug et les identifiants des requêtes en attente. Les résultats reviennent dans le chat en tant que données de navigateur non fiables, et non comme preuve qu'un enregistrement côté serveur a été modifié. Conservez l'authentification et l'autorisation dans vos propres gestionnaires et votre propre backend ; utilisez les Actions de modification pour les écritures métier ayant des conséquences.

Un délai dépassé n'annule pas le gestionnaire et ne prouve pas qu'il ne s'est rien passé. Ne relancez pas automatiquement une action dont le résultat est incertain. Désenregistrez les gestionnaires lorsque leur composant de page quitte l'écran. Les embeds déjà en cache nécessitent la version actuelle du loader, 20261014-page-actions, pour cette API.

Cette API ne gère pas les paiements et ne fournit pas de connector Shopify.