Un client écrit que le calculateur livré est codé et ne convient pas. Ce n’est pas un cas standard : il s’agit de garantie, d’un retour et peut-être d’un geste commercial. L’agent l’a reconnu et a signalé la conversation à transférer. C’est l’organisation qui décide maintenant, non la technique.
Reprise et restitution sont des actes explicites, non un effet de bord. La raison est simple : le vrai dommage ne vient pas de ce que l’agent ignore, mais de ce que l’agent et l’humain répondent en même temps. D’où un owner unique à tout instant.
| Surface | Rôles |
|---|---|
| Agent commercial | Commerce de pièces, Commerce automobile, Atelier |
Ce que ce cas suppose
- Une interface pour les collègues. La boîte s’ouvre par une session navigateur, pour que tout employé n’ait pas besoin d’une clé API.
- Une règle de responsabilité dans l’équipe. Qui reprend doit aussi rendre la main ; sinon l’agent reste durablement muet sur cette conversation.
- Un regard sur les compteurs. Ce que personne ne lit n’est pas une boîte de réception mais une archive.
- Une décision sur les offres de prix. Les offres se listent séparément — qui ne les regarde pas ne négocie pas, il attend.
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.
| Étape | Appel | Ce qui existe ensuite |
|---|---|---|
| Vue d’ensemble | GET /agent/inbox/summary | Des compteurs plutôt qu’une impression : ouvert, en attente, non lu |
| Filtrer les conversations | GET /agent/inbox/conversations | needsHuman, owner, unread et channelType comme filtres, avec nextCursor |
| Reprendre | POST /agent/inbox/conversations/{conversationId}/takeover | owner passe au collègue ; l’agent cesse de répondre ici |
| Demander de l’aide | POST /agent/inbox/conversations/{conversationId}/assist | answer et suggestedReply comme proposition — l’envoi reste manuel |
| Répondre à la main | POST /agent/inbox/conversations/{conversationId}/reply | deliveryStatus ; mise en file sur messagerie et marketplace, aussitôt considérée comme livrée sur le site |
| Rendre la main | POST /agent/inbox/conversations/{conversationId}/release | L’agent reprend dès que le cas particulier est réglé |
Pourquoi chaque étape est nécessaire
- Vue d’ensemble de la boîte.
GET /agent/inbox/summaryrenvoie les compteurs. L’avantage sur une liste est la décision avant chargement : on voit si quelque chose attend avant d’extraire quarante conversations. - Filtrer les conversations.
GET /agent/inbox/conversationsconnaîtneedsHuman,owner,unread,channelTypeet le terme de rechercheqsur l’objet et l’aperçu, avecnextCursor. Pour une file de travail,needsHumanest le filtre clé — il montre exactement ce que l’agent a cédé lui-même. - Reprendre la conversation.
POST /agent/inbox/conversations/{conversationId}/takeovermet l’ownersur le collègue. Dès lors, l’agent ne répond plus ici. Le champchangedindique si la reprise a réellement pris effet ou si un autre a été plus rapide. - Demander de l’aide à l’agent.
POST /agent/inbox/conversations/{conversationId}/assistrenvoieansweretsuggestedReply, avecfindings. C’est la différence avec un tour : la suggestion va au collègue, non au client. L’envoi reste manuel. - Répondre à la main.
POST /agent/inbox/conversations/{conversationId}/replyenvoie le texte et répond pardeliveryStatus. Selon le contrat, sur un canal messagerie ou marketplace la réponse est mise en file pour livraison, et sur le site elle est aussitôt considérée comme livrée ; le contrat ne définit pas les valeurs dedeliveryStatus. - Rendre la main.
POST /agent/inbox/conversations/{conversationId}/releaserestitue la conversation à l’agent. Sans cette étape, une conversation reprise reste manuelle à jamais — la raison la plus fréquente de l’essoufflement de l’automatisation.
curl -H 'X-Api-Key: <API_KEY>' \ 'https://api.tapinomahub.com/hub/index.php/agent/inbox/conversations?needsHuman=true&limit=25'
Ce que l’on obtient
Il reste une conversation dont la responsabilité était claire à tout instant, et une équipe qui ne traite que les cas nécessitant réellement un humain. L’agent reste compétent pour tout le reste.
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.
Sources et références juridiques
Questions fréquentes
Chaque employé a-t-il besoin d’une clé API ?
Non. Une session navigateur peut être créée pour la boîte ; elle est éphémère et liée à l’interface. La clé API reste dans l’application.
Que se passe-t-il si j’oublie de rendre la main ?
La conversation reste chez le collègue et l’agent n’y répond plus. Ce n’est pas une erreur, mais c’est la voie par laquelle l’automatisation disparaît sans bruit.
L’agent peut-il m’aider à répondre sans envoyer lui-même ?
C’est précisément l’objet de la demande d’aide : elle fournit une réponse et une proposition de formulation au collègue. L’envoi n’a lieu qu’avec l’appel de réponse.