L’agent commercial répond dans le widget de votre site

Beaucoup de demandes sur une pièce d’occasion sont les trois mêmes questions : convient-elle à mon véhicule, combien coûte le port, dans quel état est-elle. Elles arrivent le soir et le week-end, et qui attend lundi achète ailleurs. Un formulaire recueille la question mais n’y répond pas.

Le canal site est conçu comme une passerelle navigateur, non comme un appel Hub à identifiant caché : le widget s’authentifie par une clé de canal, remplaçable à tout moment. Votre clé API reste sur le serveur, à sa place.

Ce que ce cas suppose

• Un profil configuré. L’agent répond selon son instruction ; sans profil, ni ton, ni règles, ni permissions.
• Un canal site avec origines autorisées. allowedOrigins définit depuis quelles adresses le widget peut parler — c’est la protection contre l’usage abusif de la clé de canal. À la configuration du widget et au démarrage d’une conversation, l’Origin de la requête doit figurer parmi ces origines, sinon la passerelle répond par origin_not_allowed.
• Le jeton de visiteur. GET /web/channel le délivre ; la passerelle l’attend en retour dans l’en-tête X-Agent-Visitor.
• Un endroit où aboutissent les transferts. needsHuman sans boîte de réception est un avertissement que personne ne lit.

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. Configurer le widget. GET /web/channel renvoie title, greeting, accentColor, locale, pollIntervalSeconds et maxMessageChars. L’interface n’est donc pas câblée dans le script mais chargée du canal — changer le message d’accueil n’exige aucune reconstruction de page.
2. Démarrer la conversation. POST /web/conversations accepte le premier message et exécute aussitôt le premier tour. Reviennent conversationId, seq et la réponse, avec needsHuman et owner. Un second appel pour la première réponse serait une attente évitable.
3. Poursuivre l’échange. POST /web/conversations/{conversationId}/messages exécute chaque tour suivant. Le clientMessageId compte plus qu’il n’y paraît : si un message est renvoyé avec le même clientMessageId, l’appel renvoie la réponse enregistrée au lieu de recommencer.
4. Clore la conversation. POST /web/conversations/{conversationId}/close la termine. Close ne veut pas dire supprimée — l’historique reste traçable dans la boîte, et c’est précisément utile en cas de réclamation.

curl -X POST \
  -H 'X-Agent-Channel-Key: <KANALSCHLUESSEL>' \
  -H 'X-Agent-Visitor: <BESUCHERTOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Passt der Scheinwerfer an einen Golf 7 Facelift?","clientMessageId":"m-1"}' \
  'https://api.tapinomahub.com/agent/api/index.php/web/conversations'

Ce que l’on obtient

Au final, le site répond lui-même aux questions récurrentes et transmet les autres, avec leur historique, à un collègue. Le visiteur n’attend pas lundi, et le collègue ne part pas de zéro.

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.