Actions : des réponses issues de votre propre système

Une action permet à votre bot de consulter quelque chose dans votre propre système en pleine discussion — où en est une commande, quand elle sera livrée, si une réservation est confirmée. Le client demande, le bot recueille ce dont il a besoin, appelle votre API et répond à partir de ce qui revient, dans la langue du client.

Cela fonctionne partout où votre bot fonctionne : le widget de site web, votre lien de bot et votre QR code, et les applications Android, iOS, React Native, Flutter et Ionic. Rien n'est installé ni mis à jour — l'appel est effectué depuis nos serveurs, vos identifiants API n'atteignent donc jamais un navigateur ni un téléphone.

Avant de commencer : n'importe qui peut discuter avec votre bot

Votre bot est une discussion publique. Si un numéro de commande suffit à lui seul pour voir une commande, n'importe qui peut saisir des numéros jusqu'à ce que l'un d'eux fonctionne.

Le bot aide de trois façons, mais aucune ne remplace cette vérification : il n'envoie que les valeurs réellement saisies par le client, il limite le nombre de recherches qu'une discussion ou une adresse peut effectuer, et vous pouvez choisir quels champs de la réponse il est autorisé à voir.

En configurer une

Ouvrez Actions dans le tableau de bord et choisissez Nouvelle action. Les propriétaires et les administrateurs peuvent voir cet écran.

• Nom — pour vous, par exemple « Statut de commande ».
• Quand le bot doit-il l'utiliser ? — une phrase, comme vous l'expliqueriez à un nouveau collègue : « Le client demande où est sa commande ou quand elle arrivera. »
• Adresse de votre API — GET ou POST, et une adresse https://. Écrivez {{order_id}} là où va une valeur.
• Ce que le bot demande au client — jusqu'à six valeurs. Chacune a un libellé avec vos mots (« Numéro de commande »), le nom utilisé par votre API (order_id) et un type : texte libre, un nombre, une adresse e-mail ou un numéro de téléphone.
• En-têtes — votre clé API ou jeton. Stocké chiffré et plus jamais affiché.
• Ne partager que ces champs avec le bot — facultatif. Listez les parties de la réponse que le bot peut utiliser, par exemple status, eta, items[].name. Tout le reste est écarté avant que l'IA ne le voie.

Cliquez sur Tester, saisissez des valeurs d'exemple, et vous voyez la requête envoyée et exactement ce que le bot recevrait. Essayez ensuite pour de vrai sur l'écran Test : « Où est ma commande 48213 ? Mon e-mail est asha@example.com ».

Ce que reçoit votre API

Avec GET, les valeurs que vous avez placées dans l'adresse sont remplies et les autres sont ajoutées à la chaîne de requête :

GET https://api.yourshop.com/orders/48213?email=asha%40example.com

Avec POST, les valeurs forment le corps JSON :

POST https://api.yourshop.com/lookup
Content-Type: application/json

{"order_id":"48213","email":"asha@example.com"}

Chaque requête contient aussi vos propres en-têtes et ceux-ci :

Ce qu'il faut renvoyer

Répondez en moins de 8 secondes avec du JSON, ou une courte ligne de texte brut.

• 200 avec les données — le bot répond à partir de celles-ci. Restez concis et utilisez des noms de champs clairs : {"status":"shipped","eta":"2 October"} fonctionne mieux que des codes internes.
• 404 quand rien ne correspond — le bot le dit au client et lui demande de vérifier ce qu'il a saisi.
• Tout autre cas, ou pas de réponse à temps — le bot s'excuse, propose vos coordonnées, et la discussion est signalée pour vous. La raison est affichée sur l'écran Actions.

Les redirections ne sont pas suivies, et une réponse de plus de 256 KB n'est pas lue.

Vérifier la signature

Les requêtes sont signées à la manière Standard Webhooks, vous pouvez donc utiliser une bibliothèque existante. Votre secret de signature se trouve sur l'écran Actions.

À la main : joignez l'id, l'horodatage et le corps exact avec des points, signez le tout avec HMAC-SHA256 en utilisant le secret (la partie après whsec_, décodée en base64), puis comparez.

const crypto = require('crypto');

function isFromKeyda(req, rawBody, secret) {
  const id = req.headers['webhook-id'];
  const ts = req.headers['webhook-timestamp'];
  const given = String(req.headers['webhook-signature'] || '').replace(/^v1,/, '');
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // older than 5 minutes
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const want = crypto.createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest('base64');
  return given.length === want.length
    && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(want));
}

Pour une requête GET, le corps est vide, donc le texte signé se termine par un point. Utilisez POST si vous voulez que les valeurs elles-mêmes soient couvertes par la signature.

Comment le bot l'utilise

• Il demande tout ce qui manque, une courte question à la fois, et se souvient de ce que le client a dit plus tôt dans la discussion.
• Il ne devine jamais une valeur. Si le client ne l'a pas saisie, le bot la demande.
• Une recherche par message. Vos réponses enregistrées passent toujours en premier, donc une question à laquelle vous avez répondu à la main n'appelle jamais votre API.
• Les réponses issues d'une recherche ne sont jamais réutilisées pour un autre client.
• Une recherche compte comme une réponse, comme toute autre réponse rédigée par l'IA.

Dans Discussions, une réponse issue d'une recherche l'indique en dessous : quelle action a été exécutée et comment elle s'est terminée. Les valeurs saisies par le client restent dans la transcription et nulle part ailleurs.

Limites

Les actions lisent des informations. N'en pointez pas une vers une adresse qui modifie quelque chose — annuler une commande ou effectuer un remboursement nécessite une étape de confirmation que le bot n'a pas encore.