> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentova.ai/llms.txt > Use this file to discover all available pages before exploring further. # Concepts > Ce que couvre l'API — automatisations, sources de leads, événements et exécutions — et ce qu'elle ne couvre pas ## 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é](https://docs.agentova.ai/security.md) 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 : | Type | Ce qu'elle fait | Canaux (`provider`) | | - | - | - | | `social_comments` | Répond aux commentaires sur vos publications | Facebook, Instagram | | `social_story` | Répond aux réponses à vos stories | Instagram | | `social_messages` | Répond aux messages privés | Facebook, Instagram, WhatsApp | | `lead_ads` | Traite les formulaires Lead Ads (message au prospect, ajout à votre CRM) | Facebook, Instagram | | `email_messages` | Répond aux e-mails | Gmail, Outlook, IMAP | | `crm_source` | Agit quand un contact ou une réponse arrive dans un CRM ou un outil de formulaires | HubSpot, Close, Monday, ClickUp, Typeform, Tally, Odoo, Customer.io… | **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 : | Canal | Pendant la pause | À la réactivation | | - | - | - | | E-mails (Gmail, Outlook, IMAP) | Agentova cesse d'écouter la boîte mail — sauf si un autre agent actif utilise la même boîte. Les e-mails reçus pendant la pause **ne reçoivent aucune réponse**. | La boîte mail est reconnectée. Seuls les e-mails qui arrivent à partir de ce moment sont traités. | | Messages privés (Facebook, Instagram, WhatsApp), commentaires, stories | Ce qui arrive est ignoré | Les nouveaux messages, commentaires et réponses aux stories sont de nouveau traités | | Lead Ads | Les leads sont toujours enregistrés dans Agentova et annoncés par **Lead créé** ; seules les actions de l'automatisation (message, e-mail, appel…) sont sautées | Les actions reprennent pour les nouveaux leads ; celles qui ont été sautées ne sont pas exécutées après coup | | Sources CRM | Agentova cesse de réagir au CRM | Les événements survenus pendant la pause ne sont pas rejoués | | Customer.io | Agentova cesse de lire le segment (il le lit d'habitude toutes les 15 minutes) | Après une pause de plus de 6 heures, les changements du segment survenus pendant la pause ne sont jamais traités ; après une pause plus courte, ils peuvent l'être à la réactivation | 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 : | Source | D'où vient le lead | | - | - | | `widget` | Le formulaire de contact du chatbot de votre site, quand un visiteur le remplit. Les leads créés à la main dans Agentova, là où c'est possible, utilisent aussi `widget`. | | `lead_ads` | Un formulaire Lead Ads Facebook ou Instagram, traité par une automatisation Lead Ads — même quand cette automatisation est en pause | | `telephony` | Un appel qualifié par votre agent téléphonique | | `social` | Un prospect qui a commenté l'une de vos publications Instagram ou Facebook, puis envoyé ses coordonnées (e-mail ou téléphone) en message privé à votre automatisation de commentaires | | `crm` | Un contact entrant d'un CRM connecté (HubSpot, Monday, Customer.io…) pour lequel l'une de vos automatisations CRM s'est exécutée | 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 | Événement | Se produit quand | Ce que vous recevez | | - | - | - | | **Lead créé** (`lead.created`) | Un nouveau lead est capté dans votre espace de travail : le formulaire de contact du chatbot de votre site, un formulaire Lead Ads, votre agent téléphonique, un prospect qui a envoyé ses coordonnées après avoir commenté une publication, ou un contact entrant d'un CRM. Seulement à la création : un lead mis à jour ensuite (par exemple un formulaire de chat envoyé deux fois dans la même conversation) ne déclenche rien de nouveau. | Le lead : nom, e-mail, téléphone, source, agent, champs personnalisés | | **Exécution terminée** (`run.completed`) | L'une de vos automatisations vient de faire quelque chose : répondre à un message, un commentaire ou un e-mail, traiter un formulaire Lead Ads, traiter un contact d'un CRM. | L'exécution : quelle automatisation, ce qui l'a déclenchée, chaque action avec son résultat (`success` ou `failed`), et le résultat global de l'exécution (`success`, `partial` ou `failed`) | | **Statut d'automatisation modifié** (`automation.status_changed`) | Le statut d'une automatisation change réellement, que le changement vienne de l'application Agentova ou de l'API : elle est mise en pause ou réactivée, une source CRM est activée, un échec la fait passer en `error`, ou elle redevient `active` une fois son compte reconnecté. | L'automatisation, avec son nouveau statut | 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](https://docs.agentova.ai/guides/webhooks-and-signatures.md#la-livraison). ## 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. Le `status` 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. | Automatisation | Une exécution est enregistrée quand… | Déclencheur (`trigger_type`) | Actions listées | | - | - | - | - | | Messages privés (Facebook, Instagram, WhatsApp) | votre agent a réellement envoyé une réponse | `message` | la réponse | | E-mails (Gmail, Outlook, IMAP) | un e-mail entrant a été traité | `email` | la réponse envoyée, ou le brouillon enregistré | | Commentaires (Facebook, Instagram) | un commentaire a été traité | `comment` | la réponse publique, le message privé | | Commentaires (Facebook, Instagram), après la réponse du prospect | un prospect a envoyé ses coordonnées en message privé, et les actions de suite de l'automatisation se sont exécutées | `message` | ajout au CRM, message au prospect | | Stories (Instagram) | une réponse à une story a été traitée | `story_reply` | la réponse | | Lead Ads | un formulaire a été reçu et le lead créé | `lead_ads` | message au prospect, ajout au CRM — l'exécution porte aussi l'ID du lead | | Sources CRM | une action s'est exécutée pour un contact entrant | `crm_event` | message (e-mail, WhatsApp), ajout au CRM — l'exécution porte aussi l'ID du lead quand un lead a été créé | 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 `success` et 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). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.