Arrêter l’agent commercial sans perdre un seul message

Vendredi soir : la consommation mensuelle approche du budget, et la clé de canal du widget apparaît dans le code d’une page tierce. Les deux exigent une réaction rapide, et aucun ne doit laisser les clients écrire dans le vide.

La commande de l’agent est conçue pour que l’arrêt ne casse rien : il est immédiat, les conversations ouvertes reçoivent une fois un message de clôture, et les messages entrants continuent d’être enregistrés — simplement sans réponse du modèle.

Ce que ce cas suppose

• Un message de clôture préparé. Rédigé pendant l’incident, il sera mal rédigé ; il peut être enregistré dans la commande ou passé avec l’arrêt.
• Un collègue qui voit les messages enregistrés. Enregistrer sans boîte de réception ne fait que déplacer le problème.
• Un déploiement capable de mettre à jour le script du widget sur-le-champ. L’ancienne clé cesse d’agir dès le changement.
• Savoir quel accès est concerné. Une révocation ciblée ne touche que lui ; une révocation globale touche tout le canal.

Le déroulement

Le tableau indique pour chaque étape l’appel compétent et ce qui existe ensuite. La justification de l’étape figure en dessous.

Pourquoi chaque étape est nécessaire

1. Évaluer la situation. GET /agent/usage renvoie pour un mois les montants facturés après remboursements, tours, questions de collègues et conversations — au total, par canal et par jour —, avec balance et budgetState. On décide ainsi s’il faut arrêter tout l’agent ou si un seul canal se distingue.
2. Arrêter. POST /agent/stop prend en option reason et closingMessage. L’arrêt est immédiat ; les conversations ouvertes reçoivent une fois le message de clôture, pour que personne n’attende sans un mot.
3. Continuer d’enregistrer. POST /agent/conversations/record crée une conversation confiée à un collègue, enregistre le message et ne répond pas. C’est la voie prévue pour un compte arrêté ou plafonné : rien n’est perdu, rien n’est facturé.
4. Changer la clé de canal. POST /agent/channels/{channelId}/web-key/rotate délivre la nouvelle webKey une seule fois. L’ancienne cesse aussitôt d’agir — le nouveau tag de script doit donc partir dans le même déploiement.
5. Révoquer un accès de façon ciblée. POST /agent/channels/{channelId}/credentials/revoke avec un purpose supprime exactement un accès — par exemple mail_smtp ou ebay_refresh_token. Sans purpose, tout le canal est révoqué, car un canal sans sa clé serait muet et pourtant actif.
6. Reprendre. POST /agent/resume relance l’exploitation ; dès le message suivant, les tours reçoivent de nouveau une réponse. Les conversations enregistrées entre-temps restent chez le collègue jusqu’à ce qu’il les rende.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"reason":"Monatsbudget erreicht","closingMessage":"Ein Kollege meldet sich persönlich bei Ihnen."}' \
  'https://api.tapinomahub.com/hub/index.php/agent/stop'

Ce que l’on obtient

Il reste un incident où aucun client n’est resté sans réponse, aucune clé n’a valu plus que nécessaire et aucun message n’a été perdu. L’agent tourne de nouveau, et l’intervalle est traçable dans la boîte.

Où cela figure dans la documentation

Les listes de champs contractuelles, les codes d’erreur et les réponses d’exemple se trouvent dans le contrat OpenAPI de cette surface, à l’adresse docs.tapinomahub.com (tapinoma-agent). Tous les cas d’usage classés par surface et par rôle : aperçu des cas d’usage.