Espace de travail et clés
Une clé API appartient à un espace de travail et le voit en entier. Les clés sont créées et révoquées par les administrateurs de l’espace de travail dans Paramètres → API, avec au plus 10 clés actives ; tous les administrateurs sont prévenus quand une clé est créée. Une clé est révoquée automatiquement quand l’administrateur qui l’a créée quitte l’espace de travail ou cesse d’être administrateur. Les clés ne sont conservées que sous forme d’empreinte : Agentova ne peut pas réafficher une clé après sa création. Voir Sécurité pour les conserver et les remplacer. Un espace de travail sur l’offre gratuite a accès à l’API. L’accès n’est fermé (403 workspace_access_denied) que tant que l’abonnement de l’espace de travail est impayé, en pause ou incomplet.
Il n’existe pas d’environnement de test séparé : pour expérimenter sans toucher à vos vraies automatisations, utilisez un espace de travail réservé aux tests.
Automatisations
Une automatisation, c’est ce qui fait agir l’un de vos agents sur un canal. L’API les liste toutes sous une même forme, quel que soit le canal sous-jacent :
Non couverts en v1 : les agents téléphoniques, le chatbot du site lui-même (c’est un agent, pas une automatisation), les publications programmées sur les réseaux sociaux et les workflows du builder. Une automatisation supprimée ou désactivée dans l’application Agentova, ou dont le compte est déconnecté, n’apparaît pas du tout.
status vaut active, paused, draft ou error. Tout état interne que l’API ne connaît pas est présenté comme error.
L’API construit le name de chaque automatisation en anglais : ce que fait l’automatisation, puis le nom de l’agent, tel qu’il a été saisi dans Agentova — « Comment replies — Support Agent », « Story replies — … », « Message replies — … », « Email replies — … », « Lead Ads — … ». Une source CRM porte le nom de son outil et de ce qu’elle suit — « HubSpot contacts — … », « Typeform responses — … ». Un nom sert à l’affichage : deux automatisations peuvent avoir le même (le même agent sur deux canaux). Pour cibler une automatisation, utilisez donc toujours son id.
Mettre en pause et réactiver
Mettre en pause et réactiver peuvent se répéter sans risque : mettre en pause une automatisation déjà en pause, ou activer une automatisation déjà active, la renvoie inchangée — pas d’erreur, et pas de nouvel événement de statut. L’API répond en 8 secondes au plus. Quand la réactivation prend plus de temps — pour reconnecter une boîte mail, par exemple — la réponse indique le statut à cet instant, et le statut final arrive sous forme d’événement Statut d’automatisation modifié :active, ou error si le canal n’a pas pu être reconnecté.
Rien de ce qui arrive pendant une pause n’est rattrapé ensuite, sauf pour Customer.io après une courte pause :
Seules les automatisations
active et paused peuvent être basculées. Une automatisation draft ou error est refusée (422 automation_not_controllable) : corrigez-la d’abord dans l’application Agentova.
Une boîte mail ne peut être utilisée que par un seul agent actif, comme dans l’application Agentova : réactiver une automatisation d’e-mails dont la boîte est déjà utilisée par un autre agent actif est refusé aussi (422 automation_not_controllable, avec details.reason: account_in_use). Détachez d’abord la boîte mail de l’autre agent dans l’application Agentova.
Leads
Un lead est créé — et Lead créé se produit — depuis cinq endroits :
Un lead
social ou crm n’est créé que si le prospect a donné un e-mail ou un numéro de téléphone, et une seule fois par personne et par automatisation. Son name est ce qu’Agentova connaît : le nom d’utilisateur Instagram ou Facebook pour social, le prénom et le nom issus du CRM pour crm.
Ces cas ne créent pas de lead : les messages privés et les e-mails auxquels vos agents répondent, et les commentaires qui n’aboutissent pas à des coordonnées. Pour les sources CRM autres que Customer.io, le service partenaire qui relaie leurs événements n’indique pas encore à Agentova quelle automatisation a traité un contact : leurs leads ne sont enregistrés que si l’espace de travail n’a qu’une seule automatisation CRM de ce type.
phone est le numéro tel qu’il a été saisi ou capté — il n’est pas normalisé. custom_fields contient les réponses supplémentaires du formulaire ; les clés qui commencent par _ sont internes à Agentova et ne sont jamais exposées.
GET /leads peut filtrer sur source et agent_id. L’agent_id d’un lead téléphonique est celui de l’agent téléphonique, présenté avec le même préfixe agt_… que les autres.
Événements
Quand un échec fait disparaître une automatisation — accès au compte révoqué, boîte mail qui refuse la connexion, canal impossible à reconnecter — l’automatisation sort de l’API et un dernier Statut d’automatisation modifié avec le statut
error est envoyé : quand il arrive, chercher l’automatisation par son ID répond automation_not_found. Supprimer une automatisation ou la désactiver dans l’application Agentova n’envoie rien.
Quand un compte déconnecté est reconnecté dans Agentova, un événement Statut d’automatisation modifié avec le statut active est envoyé pour chaque automatisation qui revient.
Les abonnements webhook ne filtrent que par type d’événement : un abonné reçoit tous les événements de ce type dans l’espace de travail. Filtrez sur source, agent_id, status… de votre côté. Les événements sont livrés au moins une fois et sans ordre garanti — voir Webhooks et signatures.
Exécutions
Une exécution est un passage d’une automatisation, avec la liste des actions qu’elle a menées et leur résultat. Lestatus de chaque action vaut success ou failed. Le status de l’exécution elle-même vaut success quand aucune action n’a échoué (une exécution sans aucune action est aussi success), failed quand toutes les actions ont échoué, et partial sinon — par exemple une réponse à un e-mail qui n’a pas pu être envoyée et a été gardée en brouillon.
Bon à savoir :
- Pas d’exécution quand rien ne s’est passé. Un message auquel votre agent n’a finalement pas répondu ne produit aucune exécution.
- Plusieurs messages à la suite, une seule exécution. Des messages qui arrivent ensemble et reçoivent une réponse commune font une seule exécution.
- Une automatisation Lead Ads sans action configurée enregistre quand même une exécution, avec le statut
successet une liste d’actions vide. Pendant qu’elle est en pause, ses leads sont créés mais aucune action ne s’exécute. - Pas d’exécution pour le chatbot du site.
- Sources CRM : Customer.io enregistre une exécution pour chaque contact sur lequel il agit. Les autres sources CRM (HubSpot, Typeform, Close, Monday, ClickUp, Tally, Odoo…) sont relayées par un service partenaire qui n’indique pas encore à Agentova quelle automatisation a traité un événement : leurs exécutions ne sont enregistrées que si l’espace de travail n’a qu’une seule automatisation CRM de ce type. Un workflow CRM enregistre une exécution par action.
- Sur les commentaires, une action que vous n’avez pas configurée peut apparaître en
success. C’est une limite connue. - Les exécutions sont conservées 90 jours, puis supprimées.
Ce que la v1 ne couvre pas
- Créer, modifier ou supprimer des automatisations ; en déclencher une manuellement.
- Les conversations, contacts, appels téléphoniques, rendez-vous, publications et documents.
- Les permissions par clé : chaque clé voit tout l’espace de travail.
- Les appels depuis un navigateur web : l’API fonctionne uniquement de serveur à serveur (pas de CORS).