Intégrer l’agent commercial dans votre logiciel de chat ou de tickets

Un éditeur exploite pour des négociants en pièces son propre système de tickets et de chat. Les clients doivent obtenir des réponses plus vite, mais personne ne veut qu’un modèle de langage modifie seul une adresse ou envoie une étiquette de retour. La question n’est donc pas de répondre automatiquement, mais de savoir qui peut agir.

L’interface Hub de l’agent sépare nettement les deux : un tour renvoie la réponse et une liste d’actions que votre système doit exécuter. Ce qui porte requiresConfirmation n’a lieu que si votre système le confirme au tour suivant. L’agent formule, votre système agit.

Ce que ce cas suppose

• Un profil configuré. POST /agent/conversations exige un profileId ; sans profil, ni instruction, ni ton, ni permissions.
• Vos propres outils pour les actions. Ce que l’agent propose, votre système doit pouvoir l’exécuter — suivi d’envoi, changement d’adresse, étiquette de retour.
• Un endroit pour recueillir les confirmations. Une action avec requiresConfirmation attend un oui explicite.
• La clé API côté serveur. Cette interface est destinée à votre backend, non au navigateur du client.

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. Lire le contrat. GET /agent/capabilities indique formats, canaux, actionTypes, intents et limits. Le contrat recommande expressément de le lire une fois à l’intégration plutôt que de coder les limites en dur — sinon votre intégration vieillit en silence à la prochaine extension.
2. Créer la conversation. POST /agent/conversations exige profileId et prend en option, entre autres, channel, threadKey, subject et externalRef. Le contrat ne décrit pas l’effet de threadKey à la création ; GET /agent/inbox/conversations se filtre par threadKey comme clé de fil exacte.
3. Exécuter le tour. POST /agent/conversations/{conversationId}/messages renvoie reply, intent, needsHuman, findings et actions. Chaque action porte un type — customer_tool, hub_call, handoff ou request_photo — et, le cas échéant, requiresConfirmation. Les résultats reviennent au tour suivant en toolResults, les confirmations en confirmations.
4. Ajouter sans tour. POST /agent/conversations/{conversationId}/ingest enregistre un message ou une note interne avec author end_user ou note, sans solliciter le modèle. C’est la voie pour les conversations qu’un collègue mène.
5. Clore la conversation. POST /agent/conversations/{conversationId}/close prend un outcome — par exemple sold, not_sold, handed_over ou spam — et en option orderRef. La clôture n’est pas une formalité : elle seule permet d’évaluer ce que l’agent a réellement produit.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"confirmations":[{"actionId":"<actionId>","confirmed":true}]}' \
  'https://api.tapinomahub.com/hub/index.php/agent/conversations/<conversationId>/messages'

Ce que l’on obtient

Au final, votre système répond plus vite sans que l’agent modifie jamais lui-même une commande. Chaque action passe par vos outils, chaque action sensible par une confirmation — et chaque conversation se termine par un résultat exploitable.

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.