Clés d'API, webhooks et approbations#

Trame peut être relié à un service externe — un outil no-code, un script maison, un agent IA. Tout se pilote depuis Réglages → Avancé, sans écrire une ligne de code : vous y créez des clés, vous décidez ce que chacune a le droit de faire, et vous suivez ce qui se passe.

Cet écran est réservé aux administrateurs de l'espace. Un autre compte y lit simplement « Réservé à l'administrateur. »

Clés de l'API#

Une clé permet à un service externe d'agir dans Trame. Elle agit avec vos accès aux boîtes : elle ne voit jamais plus que vous.

Créer une clé. Choisissez d'abord son type :

• Intégration — pour un outil ou un script.
• Agent IA — pour un assistant automatisé. Une option supplémentaire apparaît alors : « Demander une approbation humaine avant chaque écriture » (voir plus bas).

Donnez-lui ensuite un nom parlant (le vôtre, pas un identifiant technique : « Facturation — nouvelles conversations »), puis cochez ses permissions parmi : lire les conversations, actions conversations, lire / modifier les contacts, lire / modifier le calendrier, lire / modifier les tâches, lire les statistiques, créer des brouillons.

La clé n'est affichée qu'une seule fois, à sa création. Copiez-la immédiatement : elle n'est jamais relisible ensuite. Si elle est perdue, révoquez-la et créez-en une autre.

Autoriser l'envoi de messages#

L'envoi est volontairement hors de la liste des permissions : c'est une case à part, jamais pré-cochée, à activer explicitement par la case « Autoriser l'envoi de messages (mail:send) ». L'écran en rappelle la portée juste sous la case :

L'envoi engage le porteur de la clé. Le contenu, les destinataires et le moment de l'envoi sont déterminés par votre intégration : Trame ne relit ni ne modère les messages. Un message parti est irréversible. Vous pouvez désactiver ce droit à tout moment, sans toucher aux autres permissions de la clé.

Deux règles à connaître :

• L'envoi n'est pas accordable à une clé Agent IA — ce droit est réservé aux clés Intégration. Basculer une clé en cours de création sur « Agent IA » retire automatiquement l'option.
• Le droit d'envoi s'accorde et se retire à tout moment sur une clé existante, par le bouton « Autoriser l'envoi » / « Retirer l'envoi » de sa ligne. Cela n'affecte aucune autre permission.

Suivre et révoquer#

La liste des clés indique, pour chacune : son nom, ses permissions en clair, son type (badge agent), sa date de création et la date de son dernier appel — ou « jamais utilisée », ce qui permet de repérer une clé oubliée. Révoquer une clé la désactive immédiatement ; elle reste listée, marquée « révoquée », pour garder la trace de ce qui a existé.

Approbations agents#

Quand une clé Agent IA a été créée avec l'approbation humaine, chaque écriture est bloquée jusqu'à votre décision. Les demandes en attente s'affichent dans la section Approbations agents : nom de l'agent, outil appelé, portée demandée, et un dépliant « Voir l'opération et les données » qui montre exactement ce qui serait fait.

Deux boutons : Refuser, ou Approuver. Une confirmation vous rappelle alors que l'action est exécutée immédiatement et qu'en cas d'échec elle ne pourra pas être relancée. Une demande laissée en attente trop longtemps expire d'elle-même et n'est jamais exécutée.

Webhooks#

Un webhook prévient votre service dès qu'il se passe quelque chose dans Trame — une assignation, un commentaire, une étiquette posée. Renseignez l'adresse à appeler, cochez les événements qui vous intéressent (aucun coché = tous), et ajoutez le webhook.

Comme pour une clé, le secret de signature n'est montré qu'une fois : copiez-le tout de suite. Il sert à votre service à vérifier que l'appel vient bien de Trame.

Limite : 20 webhooks par organisation.

Journal des livraisons#

Sous les webhooks, le journal des livraisons conserve l'historique des envois : identifiant, nombre de tentatives, dernier code de réponse connu, et statut (en cours, réussi, en échec). C'est là qu'on regarde en premier quand une intégration « ne reçoit rien » : le journal dit si Trame a bien tenté l'appel, et ce que le service d'en face a répondu.

Pour la référence technique complète (routes, formats, signature, SDK), voir la section Developers de cette documentation.