Référence des outils MCP
Confirmation des actions
Section intitulée « Confirmation des actions »Chaque outil qui agit sur le monde extérieur en votre nom fonctionne en deux appels :
inboxSendTool, commentActTool (reply, delete), automationManageTool
(pose, updatePose, removePose, replay, catchUp, delete), webhookManageTool
(create, delete), postDeleteTool, contentDeleteTool et
postUpdateTool (status: schedule).
- Le premier appel (sans
confirmationToken) ne fait rien. Il renvoieneedsConfirmation: true, unpreviewqui décrit exactement ce qui se passerait, et unconfirmationToken. - Montrez l’aperçu à l’utilisateur et obtenez un oui explicite.
- Le deuxième appel, avec les mêmes paramètres et le jeton, agit.
Le jeton est lié à votre espace de travail, à l’action et à ses paramètres exacts (un autre texte, une autre URL ou un autre commentaire est refusé). Il sert une seule fois et expire au bout de 15 minutes. Tout autre cas demande un nouveau premier appel.
integrationList
Section intitulée « integrationList »Liste tous les comptes de réseaux sociaux connectés (les canaux) de votre organisation.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
workspace |
string | Non | ID de workspace renvoyé par workspaceList. S’il est fourni, seuls les canaux de ce workspace sont renvoyés |
Retour :
| Champ | Type | Description |
|---|---|---|
id |
string | ID de l’intégration (à utiliser pour planifier des publications) |
name |
string | Nom affiché du compte |
picture |
string | URL de la photo de profil |
platform |
string | Identifiant de la plateforme : instagram-standalone, tiktok, youtube, x, linkedin ou threads |
workspace |
object | Le workspace du canal, sous la forme { id, name } : chaque canal est dans exactement un workspace |
workspaceList
Section intitulée « workspaceList »Liste les workspaces de votre organisation, chacun avec les ids de ses canaux. Un workspace est un dossier de canaux : chaque canal est dans exactement un workspace, et toute organisation en a au moins un. Passez l’id d’un workspace à integrationList pour ne garder que ses canaux. Chaque workspace porte aussi son contexte, rempli dans Paramètres → Workspaces : l’agent le lit avant d’écrire une publication, une réponse ou un DM pour l’un de ses canaux. Voir Workspaces et périmètre.
Paramètres : aucun
Retour :
| Champ | Type | Description |
|---|---|---|
id |
string | ID du workspace, à passer à integrationList comme workspace |
name |
string | Nom affiché du workspace |
channels |
string[] | Les ids des canaux du workspace |
type |
string | PERSONAL, BUSINESS ou CLIENT : votre workspace, votre entreprise, ou celui d’un client |
logo |
string | null | URL du logo du workspace ; null quand son média a été supprimé |
website |
string | null | Site web de la marque |
country |
string | null | Pays de l’audience, ISO 3166-1 alpha-2 (MT) |
timezone |
string | null | Fuseau horaire du workspace, IANA (Europe/Malta) |
about |
string | null | Marque, audience, ton, tels qu’écrits dans l’app (2 000 caractères au plus) |
integrationSchema
Section intitulée « integrationSchema »Renvoie les règles de publication, la longueur maximale et les réglages qu’attend une plateforme. Appelez-le avant de planifier une publication pour savoir ce que la plateforme exige. Lecture seule.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
platform |
string | Oui | La plateforme du canal, telle que la donne integrationList : instagram-standalone, facebook, threads, tiktok, youtube, linkedin ou x |
isPremium |
boolean | Non | X seulement : le compte a X Premium (publications plus longues). À omettre sinon |
Retour :
| Champ | Type | Description |
|---|---|---|
rules |
string | Règles de publication et bonnes pratiques propres à la plateforme |
maxLength |
number | Longueur maximale d’une publication ou d’un commentaire, en caractères |
settings |
object | Schéma JSON des réglages à passer à integrationSchedulePostTool pour cette plateforme |
Une plateforme inconnue renvoie errors.
integrationSchedulePostTool
Section intitulée « integrationSchedulePostTool »Planifie des publications, crée des brouillons ou publie tout de suite sur les réseaux sociaux. C’est l’outil principal pour créer du contenu.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
socialPost |
array | Oui | Tableau des publications à créer |
Chaque élément de socialPost :
| Champ | Type | Requis | Description |
|---|---|---|---|
integrationId |
string | Oui | ID d’intégration renvoyé par integrationList |
contentId |
string | Non | La carte du tableau de contenus dont la publication est tirée, renvoyée par contentListTool. Lie la publication à la carte : la carte passe d’elle-même en PUBLISHED quand la publication est en ligne |
isPremium |
boolean | Oui | Si l’utilisateur est premium |
date |
string | Oui | Date et heure. Sans décalage (2026-11-03T18:00:00) : lue dans le fuseau du workspace du canal (timezone de workspaceList), en UTC si le workspace n’en a pas. Avec un décalage ou Z (2026-11-03T17:00:00Z) : prise telle quelle |
shortLink |
boolean | Oui | Raccourcir ou non les liens de la publication |
type |
string | Oui | draft, schedule ou now |
postsAndComments |
array | Oui | Le contenu de la publication et d’éventuels commentaires |
settings |
array | Oui | Réglages propres à la plateforme, tirés de integrationSchema |
Le retour donne, pour chaque publication, l’heure murale à laquelle elle est programmée (date, YYYY-MM-DD HH:mm), le fuseau utilisé (timeZone) et la façon dont la date a été lue (dateReadIn : offset, workspace ou utc). « À 18 h » se dit donc à l’agent comme à l’app : à l’heure de l’audience, celle du workspace.
Chaque publication revient aussi avec son link, un lien court (https://go.usenadia.com/s/…) qui existe avant sa sortie : il mène au profil du canal tant que la publication n’est pas en ligne, puis à la publication, sans rien faire. On le donne dans une newsletter, une bio ou une autre publication avant la sortie. Il suit la publication quand on la déplace ou la modifie ; une publication supprimée puis programmée à nouveau est une autre publication, avec un autre lien. Une publication sur plusieurs canaux a un lien par canal. link vaut null sur une plateforme dont UseNadia ne sait pas bâtir l’adresse du profil.
Chaque élément de postsAndComments :
| Champ | Type | Description |
|---|---|---|
content |
string | Le texte de la publication, brut (voir la mise en forme plus bas) |
attachments |
array | Tableau d’URL d’images ou de médias |
thumbnail |
string | Facultatif. La couverture de la vidéo d’attachments (son premier .mp4) : l’URL d’un JPEG, idéalement 1080×1920. Un reel Instagram sort avec elle comme couverture, l’image de la grille du profil. N’importe quelle URL publique, signée comprise : UseNadia en garde une copie à la programmation. Ne mettez jamais la couverture dans attachments : elle deviendrait une seconde image |
Chaque élément de settings :
| Champ | Type | Description |
|---|---|---|
key |
string | Nom du réglage |
value |
any | Valeur du réglage (préférez les ID aux libellés quand ils existent) |
Mise en forme du contenu
Section intitulée « Mise en forme du contenu »Envoyez le texte comme une personne le taperait : texte brut, une ligne par phrase,
une ligne vide entre les paragraphes. Pas de HTML, pas de <p>, pas de <br>. Nadia le met en forme
pour chaque plateforme et garde vos retours à la ligne : une ligne vide dans votre texte est une
ligne vide dans la légende publiée, sur Instagram comme sur TikTok.
Freelance en mission longue = CDI déguisé ? Non, et voilà pourquoi.
On me le dit souvent : « t'es pas un vrai entrepreneur ».
Abonne-toi à @vincentleserpent pour apprendre à coder.#freelance #developpeur #cdiLe HTML reste accepté, pour les clients qui en envoient déjà (le tableau de bord, l’API publique) : un contenu qui porte une balise est stocké tel quel, avec ces seules balises.
| Balise | Usage |
|---|---|
<p> |
Une ligne ; un <p></p> vide est une ligne vide |
<h1>, <h2>, <h3> |
Titres |
<strong> |
Texte en gras |
<u> |
Texte souligné |
<ul>, <li> |
Listes |
Publications et commentaires
Section intitulée « Publications et commentaires »Le premier élément de postsAndComments est la publication. Sur les canaux que UseNadia connecte :
instagram-standalone: les éléments suivants sont publiés en commentaires sous la publication, texte seul (un commentaire Instagram ne peut pas porter de média) ;tiktok: les éléments en plus sont ignorés, seul le premier est publié ;youtube: les éléments en plus sont ignorés aussi ;x: chaque élément devient un tweet du fil, publié en réponse au précédent (chaque tweet compte dans le quota de publication de l’offre) ;linkedin: les éléments suivants sont publiés en commentaires sous le post, texte seul ;threads: chaque élément devient une réponse au précédent, enchaînée sous la publication, et peut porter ses propres médias.
Détail et délais entre les parties : Fils et commentaires.
Plusieurs publications
Section intitulée « Plusieurs publications »Pour planifier plusieurs publications (par ex. 20 publications sur des jours différents), ajoutez plusieurs éléments au tableau socialPost, chacun avec sa date et son integrationId.
Retour :
| Champ | Type | Description |
|---|---|---|
postId |
string | L’ID de la publication créée |
integration |
string | L’intégration sur laquelle elle a été publiée |
Si la validation échoue, l’outil renvoie { errors: string } avec le détail de ce qui ne va pas (par ex. un contenu qui dépasse la limite de caractères).
postsListTool
Section intitulée « postsListTool »Lit le calendrier : les publications de l’organisation (brouillons, planifiées et déjà publiées) entre deux dates, ou une seule publication en entier. Lecture seule.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
postId |
string | Non | Seulement cette publication, en entier, avec son fil. Les dates sont alors ignorées |
startDate |
string | Sans postId |
Date UTC du début de la période (par ex. 2026-07-20T00:00:00Z) |
endDate |
string | Sans postId |
Date UTC de la fin de la période (par ex. 2026-07-27T00:00:00Z) |
integrationId |
string | Non | Seulement les publications de ce canal, renvoyé par integrationList |
workspace |
string | Non | Seulement les publications des canaux de ce workspace, un ID renvoyé par workspaceList. Avec integrationId, ce canal doit être dans ce workspace, sinon la liste revient vide |
Retour :
Un objet avec un tableau posts. Chaque élément comporte :
| Champ | Type | Description |
|---|---|---|
id |
string | ID de la publication |
group |
string | L’ID du groupe de la publication (commun à une publication et à ses variantes par canal) |
state |
string | État de la publication (QUEUE, DRAFT, PUBLISHED ou ERROR) |
publishDate |
string | Date et heure UTC de la publication (YYYY-MM-DD HH:mm) |
content |
string | Le texte de la publication, sans HTML. Sur une période, un extrait de 280 caractères ; avec postId, en entier |
integrationId |
string | ID du canal |
channel |
string | Nom affiché du canal |
platform |
string | Identifiant de la plateforme (par ex. instagram-standalone, tiktok, x) |
link |
string | Le lien court de la publication : le profil du canal tant qu’elle n’est pas en ligne, la publication ensuite (voir integrationSchedulePostTool). null pour une publication d’avant les liens, ou sur une plateforme sans adresse de profil |
linkClicks |
object | Les clics sur link, aperçus de lien exclus : total, toPost (envoyés vers la publication), toProfile (envoyés vers le profil du canal, avant la publication), sources ([{ source, clicks }], par le ?src= que portait le lien, le plus cliqué d’abord). null quand link vaut null |
thread |
string[] | Avec postId seulement : les commentaires publiés dessous, dans l’ordre |
releaseId |
string | Avec postId seulement : l’ID de la publication sur la plateforme une fois publiée (l’ID de média des outils Instagram), ou missing quand son média n’est jamais arrivé sur la plateforme |
releaseURL |
string | Avec postId seulement : l’URL de la publication |
missingMedia |
array | Avec postId seulement, quand releaseId vaut missing : les fichiers qui ne sont jamais arrivés sur la plateforme (id, url) |
postUpdateTool
Section intitulée « postUpdateTool »Change la nature d’une publication sans la réécrire : sortir une publication planifiée de la file, y remettre un brouillon, ou enregistrer l’ID donné par la plateforme à une publication faite hors de UseNadia.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
postId |
string | Oui | La publication, renvoyée par postsListTool |
status |
string | Non | draft (hors de la file) ou schedule (de retour dans la file, à sa date) |
releaseId |
string | Non | L’ID de la publication sur la plateforme (ID de média Instagram, ID de vidéo TikTok…), pour que les analyses, les commentaires et les automatisations la retrouvent |
confirmationToken |
string | status: schedule, deuxième appel |
Le jeton du premier appel, une fois que l’utilisateur a dit oui |
Remettre un brouillon dans la file (status: schedule) le fait partir à sa date : c’est donc une action confirmée. Sortir une publication de la file et enregistrer un releaseId n’en sont pas.
Retour : { updated, needsConfirmation?, preview?, confirmationToken?, errors? }.
postDeleteTool
Section intitulée « postDeleteTool »Supprime une publication et tout ce qui est planifié avec elle (ses variantes par canal et son fil). Une publication planifiée est annulée ; une publication déjà publiée est retirée de UseNadia, pas de la plateforme. C’est irréversible, donc c’est une action confirmée : l’aperçu indique la date, le canal et les premiers mots de la publication.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
postId |
string | L’un des deux | La publication, renvoyée par postsListTool |
group |
string | L’un des deux | Le groupe de la publication, renvoyé par postsListTool |
confirmationToken |
string | Deuxième appel | Le jeton du premier appel, une fois que l’utilisateur a dit oui |
Retour : { deleted, group, needsConfirmation?, preview?, confirmationToken?, errors? }.
findSlotTool
Section intitulée « findSlotTool »Le prochain créneau libre dans le planning de publication d’un canal (la file d’attente) : ses créneaux sont des heures sur des jours choisis, parcourus dans l’ordre à partir de maintenant, en sautant ceux déjà pris par une publication. C’est l’outil de « mets-le dans le prochain créneau libre » : l’agent lit la date, puis programme avec integrationSchedulePostTool. Lecture seule.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
integrationId |
string | Non | Le canal. Sans lui, le prochain créneau libre de tout l’espace de travail |
Retour : { date }, en UTC, au format ISO 8601 (avec son Z), à passer telle quelle à integrationSchedulePostTool. Pour l’annoncer à l’utilisateur, l’agent la convertit dans le fuseau du workspace du canal.
scheduleSlotsGetTool
Section intitulée « scheduleSlotsGetTool »Lit les créneaux de publication d’un canal ou d’un workspace entier (la grille de Paramètres → Publication). Un créneau, c’est une heure et les jours où il sert, en UTC : { time, days? }, time en minutes après minuit UTC (18 h 30 UTC = 1110), days de 0 (dimanche) à 6 (samedi), sans days = tous les jours. L’app affiche la grille dans le fuseau du workspace : l’agent convertit avant de les montrer. Lecture seule.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
integrationId |
string | Un des deux | Le canal |
workspaceId |
string | Un des deux | Tous les canaux de ce workspace (renvoyé par workspaceList) |
Retour : { channels: [{ integrationId, times }], aligned, slotsPerWeek } : les créneaux de chaque canal, aligned vrai si tous les canaux ont les mêmes, et le nombre de créneaux par semaine. API : GET /public/v1/integrations/:id/posting-times.
scheduleSlotsSetTool
Section intitulée « scheduleSlotsSetTool »Remplace les créneaux de publication d’un canal, ou de tous les canaux d’un workspace (la grille de Paramètres → Publication). Tous les anciens créneaux sont remplacés ; aucune publication déjà programmée ne bouge. L’agent convertit d’abord l’heure de l’utilisateur (le fuseau du workspace) en UTC, montre le changement et n’appelle l’outil qu’après un oui explicite.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
integrationId |
string | Un des deux | Le canal |
workspaceId |
string | Un des deux | Tous les canaux de ce workspace (renvoyé par workspaceList) |
times |
{ time, days? }[] |
Oui | Les nouveaux créneaux, qui remplacent tous les anciens |
Retour : les créneaux tels qu’écrits, sous la même forme que scheduleSlotsGetTool. API : PUT /public/v1/integrations/:id/posting-times.
automationList
Section intitulée « automationList »Liste les automatisations commentaire → DM du compte (Instagram) : les ID que demandent les réglages Instagram d’une publication, et ce qui tourne déjà sur une publication. Lecture seule.
Une publication désigne son automatisation par un ID dans ses réglages Instagram : automationFlowId (un template dessiné dans l’app), avec automationKeywords et automationVariables. Des mots ou des valeurs envoyés sans l’ID sont refusés à la planification, car rien ne tournerait.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
flowId |
string | Non | Seulement ce template, avec toutes les publications sur lesquelles il est posé |
integrationId |
string | Non | Un canal Instagram, renvoyé par integrationList. Renvoie aussi ce qui tourne sur ses publications |
workspace |
string | Non | Les poses de tous les canaux de ce workspace, un ID renvoyé par workspaceList. Avec integrationId, ce canal doit être dans ce workspace, sinon aucune pose ne revient |
postId |
string | Non | Avec integrationId ou workspace : seulement ce qui tourne sur cette publication. Un ID de publication renvoyé par postsListTool, ou un ID de média Instagram. Une publication pas encore publiée (avec ou sans filtre) : renvoie aussi scheduled |
onlyWithIssues |
boolean | Non | Seulement les poses qui ne tourneront pas en l’état (issues non vide) |
Retour :
| Champ | Type | Description |
|---|---|---|
templates |
array | Les automatisations dessinées dans l’app : id (à passer comme automationFlowId), name, status (DRAFT, ACTIVE, PAUSED ou ARCHIVED : un template ARCHIVED continue de répondre sur les publications où il est déjà posé, mais ne se pose plus sur un nouveau post et ne se modifie plus), ready (ACTIVE et sans erreur : peut aller sur un post tel quel, jamais un archivé), issues, trigger (post_comment ou story_reply : les deux se posent aussi bien sur un post, un reel que sur une story, c’est la publication qui décide ; dm_keyword ne se pose pas encore), keywordsRequired (toujours true : les mots d’un post ; sur une story ils sont facultatifs), variables (les noms à remplir dans automationVariables), variableHints (pour chaque variable, sa description et une valeur d’exemple example, quand le template les donne), poses, posesWithIssues (les publications où il est posé et qui ne répondront pas tant que leurs valeurs ne sont pas corrigées) |
scheduled |
object | Avec postId, une publication Instagram pas encore publiée : postId, integrationId, kind (post ou story), publishDate, flowId (le template posé à sa publication, null s’il n’y en a pas), keywords, variables |
poses |
array | Avec integrationId : les templates qui tournent sur les publications du canal ; avec flowId seul : toutes les publications sur lesquelles ce template est posé. Chacune avec id (le poseId de automationManageTool et automationRunsTool), flowId, flowName, postId, mediaId, keywords, variables, active, issues (codes de ce qui empêche la pose de tourner, vide quand rien ne l’en empêche : variable_without_value quand le template a gagné une variable après la pose, no_keywords, button_title_too_long…), ready (aucun problème, la pose active et son template en ACTIVE ou ARCHIVED), runs |
Chaque pose porte aussi counts, le funnel de la publication : runs (les personnes entrées), replied (ont réécrit après leur commentaire ou leur réponse à la story : un bouton touché, un texte, une question), emails, clicked (ont cliqué au moins un lien reçu, aperçus de lien exclus), waiting et waitingAt, où ces personnes attendent : firstMessage (n’ont jamais touché le premier DM : plus rien ne peut leur être envoyé, Meta n’autorise qu’une réponse privée par commentaire), email (ont répondu au premier DM sans laisser leur e-mail), other (ailleurs), puis done et failed. Les personnes elles-mêmes : automationRunsTool.
Pour reprendre sur une nouvelle publication l’automatisation d’une plus ancienne, lisez la pose de celle-ci avec integrationId et postId, puis planifiez avec les mêmes automationFlowId et automationKeywords, en ne changeant que les valeurs de automationVariables qui diffèrent.
Une pose qui a un problème est sautée sans un mot au commentaire suivant. Après avoir modifié un template (une variable ajoutée ou renommée), listez ses poses avec flowId, puis donnez à chaque pose qui a des issues ses valeurs manquantes avec updatePose de automationManageTool (envoyez toutes les valeurs : variables remplace l’ensemble des valeurs de la pose).
automationManageTool
Section intitulée « automationManageTool »Tout ce que l’API publique fait sur un template ou une pose, sauf dessiner l’arbre des étapes (c’est le rôle de l’éditeur, dans l’app). Une action par appel.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
action |
string | Oui | pose, updatePose, removePose, poll, replay, catchUp, activate, pause, archive, unarchive, delete, rename, createFromPreset |
flowId |
string | Selon l’action | Le template (pose, activate, pause, archive, unarchive, delete, rename) |
poseId |
string | Selon l’action | La pose, renvoyée par automationList (updatePose, removePose, poll, replay, catchUp) |
postId |
string | Non | pose, removePose : une publication ou une story Instagram programmée mais pas encore publiée, renvoyée par postsListTool, à la place d’integrationId et mediaId (ou de poseId) |
integrationId |
string | pose |
Le canal Instagram (aussi rename, createFromPreset) |
mediaId |
string | pose |
La publication déjà en ligne, renvoyée par commentsListTool |
kind |
string | Non | post ou story (par défaut : le déclencheur du template) |
keywords |
string[] | pose, updatePose |
Les mots-clés déclencheurs de cette publication |
variables |
object | pose, updatePose |
Une valeur par variable du template |
active |
boolean | updatePose |
false met la pose en pause |
commentIds |
string[] | replay |
De 1 à 50 ID de commentaires, renvoyés par commentsListTool |
resend |
boolean | Non | replay : relancer un commentaire qui a déjà un run |
name |
string | Non | rename, createFromPreset |
preset |
string | createFromPreset |
lead_magnet, newsletter, link, follow, follow_gate ou blank |
language |
string | Non | createFromPreset : fr (par défaut) ou en |
confirmationToken |
string | Deuxième appel | pose, updatePose, removePose, replay, catchUp, delete : le jeton du premier appel |
Retour : { ok, errors? }, plus pose, template, poll (checked, started), replay (un résultat par commentaire) ou catchUp (matching, started, queued, perMinute) selon l’action. Sur une publication que vous planifiez, passez automationFlowId, automationKeywords et automationVariables dans ses réglages Instagram.
Une publication ou une story déjà programmée mais pas encore publiée reçoit son automatisation après coup : pose avec flowId, postId, keywords et variables (le genre est celui de la publication : une story n’a pas besoin de mot), ou removePose avec postId pour la retirer. Elle est vérifiée comme à la programmation et, à la publication, posée exactement comme si elle avait été dans les réglages dès le départ : inutile de supprimer et reprogrammer la publication (son lien reste le même). Rappelé, pose remplace le template qu’elle porte. Une fois la publication en ligne, posez sur la publication elle-même (integrationId, mediaId). Renvoie scheduled (comme automationList). Côté API : GET, PUT et DELETE /public/v1/posts/{id}/automation.
pose, updatePose, removePose, replay, catchUp et delete sont des actions confirmées : elles font écrire le compte à des personnes, ou ne peuvent pas être annulées. poll, activate, pause, archive, unarchive, rename et createFromPreset agissent tout de suite. activate est refusé tant que le template contient des erreurs.
catchUp rattrape les commentaires déjà là quand le template a été posé sur une publication déjà en ligne : sans lui, un commentaire antérieur à la pose est ignoré. Le premier appel lit les commentaires et renvoie le nombre et les personnes qui recevraient l’automatisation (comments, people), sans rien envoyer ; s’il n’y en a aucun, il répond tout de suite (catchUp.matching vaut 0), rien à confirmer. Confirmé, chaque commentaire démarre la même conversation qu’un commentaire neuf (réponse publique comprise), 10 par minute au plus pour rester sous la limite de Meta (750 réponses privées par heure et par compte) ; UseNadia envoie la suite seul. Les garde-fous sont ceux d’un commentaire neuf, sa date avant la pose mise à part : commentaire de premier niveau, pas les vôtres, moins de 7 jours, un des mots, une fois par personne, jamais un commentaire qui a déjà un run. Côté API : GET puis POST /public/v1/automation-flow-poses/{id}/catch-up.
archive met de côté un template ACTIVE : les publications où il est déjà posé continuent de répondre, mais il ne se pose plus sur de nouveaux posts (pose est refusé, ready vaut false) et ne se modifie plus (rename est refusé). Seul un template ACTIVE s’archive : un template en pause se reprend d’abord, un brouillon se supprime. unarchive le remet en ACTIVE, refusé tant qu’il contient des erreurs. Archivez plutôt que supprimer un template dont les publications doivent continuer à répondre : delete retire ses poses avec lui, et les personnes qui y sont passées.
automationRunsTool
Section intitulée « automationRunsTool »Les personnes passées par une pose : une ligne par personne, les plus récentes d’abord. Lecture seule.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
poseId |
string | Oui | La pose, renvoyée par automationList |
status |
string | Non | PENDING, WAITING, DELAYED, DONE, HANDED_OFF, FAILED ou SKIPPED |
Retour : { runs, total }. Chaque run : id, username, keyword, text (le commentaire ou le message qui l’a déclenché), status, email, tags, isFollower, error (le message de Meta en cas d’échec), startedAt, completedAt, clickedAt (premier clic sur un lien envoyé par le run, null s’il n’a jamais cliqué) et clicks (nombre de clics). Les aperçus de lien qu’Instagram charge pour la vignette ne comptent pas.
commentsListTool
Section intitulée « commentsListTool »Le côté Instagram d’un canal, lu en direct chez Meta : les publications récentes, les stories en ligne en ce moment, ou les commentaires sous une publication. Sur un canal Threads, comments seulement : les réponses à une publication, à tous les niveaux. Lecture seule.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
integrationId |
string | Oui | Le canal Instagram, ou un canal Threads pour comments |
kind |
string | Oui | publications, stories ou comments |
mediaId |
string | comments |
La publication : un ID de média Instagram, ou le releaseId d’une publication lue avec postsListTool |
Retour : publications (id, l’ID de média que surveille une pose, type, caption, permalink, publishedAt, comments, likes) ou comments (id, from sous la forme @username, text, at, replyTo, hidden), les plus anciens d’abord.
commentActTool
Section intitulée « commentActTool »Répond publiquement à un commentaire, le masque ou le réaffiche, ou le supprime sur la plateforme : Instagram, ou Threads (les réponses à une publication).
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
integrationId |
string | Oui | Le canal de la publication : Instagram ou Threads |
commentId |
string | Oui | Le commentaire, renvoyé par commentsListTool |
action |
string | Oui | reply, hide, unhide ou delete |
message |
string | reply |
La réponse publique, 2 200 caractères au plus |
confirmationToken |
string | reply, delete |
Le jeton du premier appel, une fois que l’utilisateur a dit oui |
Une réponse est vue par tout le monde aussitôt et une suppression est définitive : les deux sont donc des actions confirmées. Le jeton est lié à ce commentaire et à ce texte précis, à usage unique, valable 15 minutes. Masquer est réversible et ne demande aucune confirmation.
Sur Threads, ce que la plateforme refuse revient dans errors, avec sa raison : une réponse ne se supprime pas (l’API de Threads ne supprime pas la réponse de quelqu’un d’autre, masquez-la plutôt), seule une réponse de premier niveau qui n’est pas la vôtre se masque, et une réponse publique fait 500 caractères au plus.
Retour : { done, needsConfirmation?, preview?, confirmationToken?, errors? }.
inboxListTool
Section intitulée « inboxListTool »La boîte de messages privés (DM) d’un canal Instagram, lue dans la copie qu’en garde UseNadia : une boîte à la fois, ce qui attend un humain d’abord, les plus récentes d’abord à l’intérieur. Chaque conversation vient avec la personne, la date, son statut (NEEDS_REPLY = un humain attend une réponse, ANSWERED = un vrai échange où vous avez parlé en dernier, AUTO = seule une automatisation a parlé), son étiquette (THANKS, QUESTION, NOISE) et son dernier message ; counts donne le nombre de conversations de chaque boîte. Lecture seule.
Les pièces jointes sont aplaties : une carte envoyée par une automatisation (ManyChat, les automatisations de UseNadia) revient sous forme de son texte avec ses boutons et leurs liens, un Reel ou une publication partagés sous forme de leur permalien.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
integrationId |
string | Oui | Le canal Instagram, renvoyé par integrationList |
box |
string | Non | needs_reply (par défaut), conversations (tout sauf le full auto), auto, thanks (ce qui attend est un merci ou un emoji), organic (les personnes à qui aucune automatisation n’a jamais écrit), read (marquées lues) ou all |
username |
string | Non | Seulement la conversation avec cette personne (@username ou son ID), quelle que soit sa boîte |
limit |
integer | Non | Nombre de conversations, de 1 à 200. Par défaut toutes celles de needs_reply (200 au plus), 25 pour les autres boîtes |
after |
string | Non | Le next de la réponse précédente, pour la page suivante |
Retour :
| Champ | Type | Description |
|---|---|---|
channel |
string | Nom affiché du canal |
box |
string | La boîte lue |
counts |
object | Nombre de conversations de chaque boîte (needs_reply, conversations, auto, thanks, organic, read, all) |
conversations |
array | Chacune avec id (à passer à inboxReadTool), with (@username de la personne), recipientId, participants, updatedAt, status, label, replyWindowOpen (si Instagram accepte encore une réponse : seulement dans les 24 h qui suivent le dernier message de la personne), replyWindowClosesAt et lastMessage |
next |
string | Curseur de la page suivante, null sur la dernière |
errors |
string | Pourquoi rien n’est revenu (un canal qui n’est pas dans l’espace de travail, une erreur de Meta) |
Chaque message, ici et dans inboxReadTool : at, from (@username de l’expéditeur), text, attachments (kind parmi template, reel, share, story_reply, story_mention, image, video…, avec text, url, storyId, buttons), unsupported quand l’API ne montre pas ce type de message (une note vocale, un GIF) et, dans inboxReadTool, automated: true quand une automatisation l’a envoyé ou consommé (le mot-clé, un bouton cliqué, l’e-mail) : ce n’est ni un mot de la personne ni un mot du propriétaire.
Exemple : qui attend une réponse.
{ "integrationId": "abc123" }inboxReadTool
Section intitulée « inboxReadTool »Une conversation privée, lue dans la copie qu’en garde UseNadia : ses 50 derniers messages, les plus anciens d’abord, les précédents avec before. Récupérez d’abord l’ID de la conversation avec inboxListTool. Lecture seule.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
integrationId |
string | Oui | Le canal Instagram |
conversationId |
string | Oui | L’id de la conversation renvoyé par inboxListTool (l’ID de conversation d’Instagram, ou celui de la personne tant qu’Instagram n’a pas encore nommé le fil) |
before |
string | Non | Le before de la réponse précédente, pour les messages plus anciens |
Retour : channel et conversation : id, with, recipientId, updatedAt, replyWindowOpen, replyWindowClosesAt (le moment où Instagram cesse d’accepter une réponse, 24 h après le dernier message de la personne ; ensuite, seule elle peut rouvrir la conversation en écrivant de nouveau), messages, dans la forme décrite sous inboxListTool, tags et before quand il reste des messages plus anciens. Ou errors.
Ici, chaque message porte en plus son id, celui que replyTo d’inboxSendTool cite, et replyTo quand il cite lui-même un message : l’id du message cité. Instagram ne le dit que pour les messages arrivés en direct et pour les vôtres ; un message plus ancien, rattrapé par la synchronisation, n’en porte jamais.
tags, ce que les automatisations savent de la personne, du plus récent au plus ancien : kind: "automation" pour un template qu’elle a déclenché (automationId, automation, son nom, keyword, le mot qu’elle a écrit — vide pour une réponse à une story où tout compte), kind: "tag" pour une étiquette qu’un pas add_tag lui a posée (value) ; dans les deux cas count, combien de fois, et lastAt, la dernière. Lus sur les runs, donc valables pour le passé aussi.
Exemple :
{ "integrationId": "abc123", "conversationId": "t_1234567890" }inboxSendTool
Section intitulée « inboxSendTool »Envoie un message privé (DM) sur un canal Instagram, dans une conversation existante : Instagram ne laisse un compte écrire qu’à quelqu’un qui a écrit en premier.
Un DM est vu par la personne aussitôt et ne se reprend pas : c’est donc une action confirmée. Le premier appel n’envoie rien et renvoie un preview et un confirmationToken, signé sur le canal, le destinataire et le texte exacts, à usage unique, valable 15 minutes. Une fois que l’utilisateur a dit oui à ce destinataire et à ce texte précis, le deuxième appel, avec les mêmes paramètres et le jeton, l’envoie. Changer le texte demande un nouveau premier appel.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
integrationId |
string | Oui | Le canal Instagram |
conversationId |
string | L’un des deux | La conversation, renvoyée par inboxListTool |
recipient |
string | L’un des deux | @username ou ID de la personne, à défaut de conversationId |
text |
string | Oui | Le message, en texte brut, de 1 à 1 000 caractères |
linkUrl |
string | Non | Un lien, envoyé sous forme de bouton sous le texte |
linkButtonText |
string | Non | Libellé de ce bouton, 20 caractères au plus |
replyTo |
string | Non | L’id d’un message de la conversation (renvoyé par inboxReadTool), à vous ou à la personne : le DM le cite, comme « Répondre » dans Instagram |
confirmationToken |
string | Deuxième appel | Le jeton de l’aperçu, seulement une fois que l’utilisateur a dit oui à ce message précis |
Retour : { sent, needsConfirmation?, preview?, confirmationToken?, messageId?, errors? }. Le preview contient channel, integrationId, conversationId, to, recipientId, text, linkUrl, linkButtonText, replyTo et replyWindowClosesAt.
Quand on sait la fenêtre de 24 h fermée, le premier appel refuse déjà avec errors et rien n’est proposé : seule la personne peut rouvrir la conversation. Ne réessayez pas.
Exemple : le premier appel, puis le même avec le jeton.
{ "integrationId": "abc123", "recipient": "@someone", "text": "Here is the guide", "linkUrl": "https://example.com/guide", "linkButtonText": "The guide" }inboxPollTool
Section intitulée « inboxPollTool »Lit tout de suite l’Inbox d’un canal Instagram, pour rattraper ce que le webhook de Meta a manqué : les nouveaux messages privés et les réponses aux stories sont récupérés, et les automatisations qui les attendaient avancent. Le rattrapage horaire tient l’Inbox à jour mais ne fait pas avancer les automatisations : cet outil sert de rattrapage. Rien n’est envoyé.
Paramètres : integrationId (string, requis).
Retour : { polled, channel, conversations, handled, errors? } : conversations, celles lues chez Meta ; handled, les messages entrants qui ont atteint une automatisation en attente.
generateImageTool
Section intitulée « generateImageTool »Génère une image par IA, à joindre à une publication.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
prompt |
string | Oui | Description de l’image à générer |
Retour :
| Champ | Type | Description |
|---|---|---|
id |
string | ID du média |
path |
string | URL de l’image générée |
Mettez le path renvoyé dans le tableau attachments au moment de planifier une publication.
postMoveTool
Section intitulée « postMoveTool »Déplace une publication existante à une autre date et heure. Une date sans décalage est lue dans le fuseau du workspace du canal de la publication (UTC si le workspace n’en a pas) ; avec un décalage ou Z, elle est prise telle quelle. Récupérez d’abord l’ID de la publication avec postsListTool.
Un déplacement est réversible (il suffit de la remettre en place) : contrairement à la planification, il ne passe pas par une confirmation. Une publication déjà publiée ne se déplace pas.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
postId |
string | Oui | La publication à déplacer |
date |
string | Oui | La nouvelle date : YYYY-MM-DDTHH:mm:ss dans le fuseau du workspace du canal, ou avec un décalage / Z |
Retour :
| Champ | Type | Description |
|---|---|---|
moved |
boolean | Si la publication a été déplacée |
postId |
string | L’ID de la publication |
date |
string | Sa nouvelle date, heure murale dans timeZone (YYYY-MM-DD HH:mm) |
timeZone |
string | Le fuseau de cette heure (celui du workspace, ou UTC) |
dateReadIn |
string | Comment la date a été lue : offset, workspace ou utc |
errors |
string | Pourquoi elle n’a pas été déplacée |
videoPerformance
Section intitulée « videoPerformance »Lit les performances des vidéos d’un canal TikTok ou Instagram, à partir de l’historique que UseNadia collecte toutes les 30 minutes. Cet outil n’a pas d’équivalent dans upstream, et c’est lui qui permet de répondre à « comment se porte ma dernière vidéo ».
Il est en lecture seule et n’appelle aucun fournisseur : tout vient des séries collectées. Un canal sans rien de collecté encore répond collected: false, avec la raison.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
integrationId |
string | Oui | Le canal dont on lit les vidéos |
videoId |
string | Non | L’ID de vidéo chez le fournisseur sur laquelle se concentrer. Par défaut, la plus récente |
limit |
number | Non | Combien de vidéos parmi les plus récentes lire, de 1 à 30. 10 par défaut |
Retour, par vidéo : les compteurs actuels (vues, portée, likes, commentaires, partages, enregistrements, temps de visionnage), les taux d’engagement en pourcentage des vues, le taux de swipe actuel (skipRatePercent, Reels Instagram seulement, plus il est bas, mieux c’est), les vues atteintes à des âges fixes (H+4, H+12, H+24, H+48, H+72, H+120, H+168) et les vues gagnées sur les dernières 24 et 48 heures.
La vidéo ciblée est en plus comparée aux autres à son propre âge (rang et médiane), avec une projection à H+120 fondée sur le multiplicateur H+24 → H+120 propre au canal, sa vitesse actuelle, et le nombre d’abonnés avec son gain sur 24 et 48 heures.
channelAnalyticsTool
Section intitulée « channelAnalyticsTool »Les métriques d’un canal sur les derniers jours, lues en direct sur la plateforme (mises en cache une heure) : abonnés, portée, impressions, vues, likes… tout ce que la plateforme fournit. Avec postId, les métriques de cette seule publication publiée. Lecture seule.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
integrationId |
string | Oui | Le canal |
days |
integer | Non | La période, en jours (30 par défaut) |
postId |
string | Non | Une publication publiée de ce canal, à la place du compte |
series |
boolean | Non | true ajoute les points jour par jour de chaque métrique |
Retour : { metrics }. Chaque métrique : label, latest (la dernière valeur), total (la somme sur la période), percentageChange par rapport à la période précédente, et series sur demande. Avec postId, missing: true indique que le média de la publication n’est jamais arrivé sur la plateforme.
analyticsHistoryTool
Section intitulée « analyticsHistoryTool »L’historique brut que UseNadia collecte toutes les 30 minutes sur un canal TikTok ou Instagram, sous forme de séries temporelles : les compteurs du compte, ou ceux de chaque vidéo. Pour une lecture toute faite, videoPerformance passe en premier ; celui-ci sert à un graphique, à un export, ou à une question à laquelle l’autre ne répond pas. Lecture seule.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
integrationId |
string | Oui | Le canal |
kind |
string | Oui | account ou video |
videoId |
string | Non | video : seulement cette vidéo (l’ID de la plateforme) |
from, to |
string | Non | ISO 8601. Par défaut : les 30 derniers jours |
limit, offset |
integer | Non | Pagination |
Retour : { items, total, from, to }, plus videos (titre, couverture, durée des ID présents) et hidden sur les séries vidéo, dans la même forme que les routes d’historique de l’API publique.
contentListTool
Section intitulée « contentListTool »Lit le tableau de contenus : une carte par vidéo, en colonnes IDEA → SCRIPT → VALIDATED → TO_SHOOT → TO_EDIT → TO_SCHEDULE → PUBLISHED. Lecture seule. Cet outil n’a pas d’équivalent dans upstream.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
contentId |
string | Non | Seulement cette carte |
stage |
string | Non | Seulement les cartes de cette colonne |
withNumbers |
boolean | Non | Ajoute les chiffres des cartes publiées (plus lent) |
Retour : un tableau contents. Chaque carte comporte id, externalId (votre propre ID quand la carte a été créée avec un, sinon null), title, stage, tags, hook, hookText (le texte affiché à l’écran pendant les premières secondes), script et notes (en entier), resourceStatus, resourceUrl, resourceBrief, integrationIds, plannedAt, hasVideo, scheduledPosts (les canaux de la publication planifiée à partir d’elle), publishedAt, source (la vidéo d’un autre dont la carte est née, voir contentFromLinkTool ; null sur toute autre carte) et, avec withNumbers, numbers : views, engagementRate, followersGained, leads, emails.
contentCreateTool
Section intitulée « contentCreateTool »Ajoute une carte au tableau. Elle arrive en bas de sa colonne. Une carte est visible sur le tableau et se supprime : cet outil écrit donc directement, sans confirmation, et n’écrase jamais une carte existante.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
title |
string | Oui | Titre court de la vidéo |
stage |
string | Non | La colonne de départ. IDEA par défaut |
hook |
string | Non | L’accroche parlée, les premières secondes |
hookText |
string | Non | Le texte affiché à l’écran pendant les premières secondes |
script |
string | Non | |
notes |
string | Non | |
tags |
string[] | Non | Étiquettes libres, par ex. une série |
resourceStatus |
string | Non | La ressource que la vidéo offre : READY, ou TO_CREATE (la carte reste alors hors de TO_SCHEDULE et de PUBLISHED) |
resourceUrl |
string | Non | Où se trouve la ressource, ou où elle se trouvera |
resourceBrief |
string | Non | Ce que contient la ressource, ou le prompt pour la fabriquer |
integrationIds |
string[] | Non | Canaux visés, renvoyés par integrationList |
plannedAt |
string | Non | Date de publication prévue, en UTC (YYYY-MM-DD HH:mm:ss) |
Crée toujours une nouvelle carte. Pour créer ou mettre à jour une carte par votre propre ID (un import, une chaîne de production), passez par contentUpdateTool avec externalId.
Retour : created, l’id et le stage de la carte, ou errors.
contentFromLinkTool
Section intitulée « contentFromLinkTool »Ajoute au tableau, comme idée, une vidéo publiée par quelqu’un d’autre, à partir de son lien : un TikTok, un reel ou un post vidéo Instagram, un Short YouTube. La carte arrive en tête de IDEA, avec le tag inspiration et la vidéo comme source. C’est la même chose que POST /contents/from-link de l’API publique.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
url |
string | Oui | Le lien de la vidéo, tel que le bouton Partager de l’app le donne (https://www.tiktok.com/@user/video/123, https://vm.tiktok.com/…, https://www.instagram.com/reel/…, https://www.youtube.com/shorts/…) ; un texte qui contient le lien marche aussi |
tags |
string[] | Non | Tags ajoutés à inspiration (20 au plus) |
La carte est créée tout de suite. UseNadia lit ensuite la vidéo en arrière-plan : son auteur, sa légende, sa durée, ses vues du jour, une copie de sa vignette et la transcription de ce qu’elle dit. La vidéo elle-même n’est pas gardée. Relisez la carte avec contentListTool (contentId) une minute plus tard : source.status vaut PENDING pendant la lecture, READY une fois lue, FAILED quand la plateforme a refusé, et source.error dit pourquoi il n’y a pas de transcription (vidéo privée, lien court mort, carrousel photo, vidéo de plus de 10 minutes, YouTube qui refuse les serveurs de UseNadia).
La même vidéo envoyée à nouveau renvoie la carte qui la porte déjà (created: false), et rien n’est relu. Au plus 30 liens par heure et par compte.
Retour : created, content (la carte, sous la forme de contentListTool, avec sa source), message (une phrase courte qui dit où la vidéo est allée) et appUrl (la carte dans l’app) ; ou created: false et errors quand le lien n’est pas une vidéo TikTok, Instagram ou YouTube, ou au-delà du budget horaire.
contentUpdateTool
Section intitulée « contentUpdateTool »Modifie une carte et/ou la déplace dans une autre colonne, en un seul appel. Seuls les champs fournis changent. Récupérez d’abord l’ID de la carte avec contentListTool.
Paramètres : contentId, ou externalId (votre propre ID pour la carte, un import, une chaîne de production : la carte qui le porte est mise à jour, et créée quand aucune ne le porte, title est alors requis et la colonne est IDEA par défaut ; un des deux exactement), puis au choix stage (déplace la carte en bas de cette colonne), title, hook, hookText, script, notes, tags (remplace la liste), resourceStatus, resourceUrl, resourceBrief, integrationIds (remplace la liste), plannedAt, postGroup (lie la carte à une publication déjà au calendrier : le groupe de cette publication, renvoyé par postsListTool ; chaque appel en ajoute un, et la carte passe d’elle-même en PUBLISHED quand la première de ses publications est en ligne).
Retour : updated (et created avec externalId, quand la carte vient d’être créée), l’id et le stage de la carte, ou errors quand la carte n’existe pas dans l’espace de travail, ou quand sa ressource est encore en TO_CREATE et que le déplacement vise TO_SCHEDULE ou PUBLISHED (les champs sont écrits, la carte reste où elle est).
contentDeleteTool
Section intitulée « contentDeleteTool »Supprime une carte du tableau. Les publications planifiées à partir d’elle restent au calendrier. La suppression ne s’annule pas depuis l’app : c’est donc une action confirmée, et l’aperçu nomme la carte.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
contentId |
string | Oui | La carte à supprimer |
confirmationToken |
string | Deuxième appel | Le jeton du premier appel, une fois que l’utilisateur a dit oui |
Retour : { deleted, needsConfirmation?, preview?, confirmationToken?, errors? } ; errors quand la carte n’existe pas dans l’espace de travail.
hooksFormsTool
Section intitulée « hooksFormsTool »La bibliothèque. hooksFormsTool et hooksSearchTool lisent la bibliothèque mesurée par UseNadia : environ 25 800 premières phrases de vidéos de 61 comptes, chacune avec ses vues normalisées (ses vues rapportées à la médiane des vidéos publiées autour d’elle sur le même compte : 5 veut dire cinq fois ce que fait d’habitude ce compte). C’est la même pour tous les comptes, tenue à jour par UseNadia à chaque nouvelle mesure ; les outils ne font que la lire, personne n’y importe d’accroches.
Le quota. Les accroches rendues sont comptées par compte et par jour (UTC), selon l’offre. Une demande au-delà du plafond par appel est rognée, pas refusée : vous recevez le plafond (hooksFormsTool réduit d’abord les exemples par forme, puis le nombre de formes). Une fois le plafond du jour atteint, les deux outils ne rendent plus que le message, jusqu’à 00:00 UTC.
| Offre | Accroches par appel | Accroches par jour (UTC) |
|---|---|---|
| Solo, Starter ultime | 10 | 300 |
| Équipe | 30 | 1 000 |
| Agence | 50 | 3 000 |
| Pendant l’essai de 7 jours, quelle que soit l’offre | 5 | 50 |
Quand un appel est rogné ou refusé, la réponse porte quota : un texte en anglais, écrit pour l’agent, qui donne les accroches rendues et demandées, ce qui reste du jour, l’offre, le renouvellement à 00:00 UTC et l’offre du dessus (pendant l’essai : ce que donne l’offre une fois l’essai converti). L’agent le dit une fois à l’utilisateur, pas à chaque appel.
C’est l’outil à appeler quand quelqu’un veut des accroches pour une vidéo. Renvoie un catalogue de formes d’accroche (des familles) pour la vidéo en préparation, chacune avec de vraies accroches tirées de la bibliothèque : une sur le sujet lui-même quand la bibliothèque en a une, les autres tirées au hasard parmi les accroches de la famille. Deux appels ne donnent jamais les mêmes exemples. Lecture seule.
Les formes sont classées selon leur effet mesuré sur ce type de vidéo, mais l’ordre est faible. Les vues ne certifient jamais une accroche : elles suivent la taille du sujet, donc normViews est une information, pas un classement. La méthode : dire ce que la vidéo apporte et son sujet, écrire une proposition par forme en adaptant la forme de l’exemple (jamais son sujet), laisser la personne choisir. Ne jamais inventer une accroche de zéro, ne jamais en recopier une mot pour mot, ne jamais nommer un créateur.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
nature |
string | Non | Ce que la vidéo apporte : tuto_methode, ressource_outil, liste_conseils, explication_concept, actu, opinion, story_perso, story_tiers, demo_build, humour_sketch, vie_coulisses. Absent : tout le corpus |
q |
string | Non | Mots du sujet (accents et casse ignorés) |
language |
string | Non | fr (par défaut), en ou all |
forms |
integer | Non | Nombre de formes, de 1 à 15. 7 par défaut |
examples |
integer | Non | Vraies accroches par forme, de 1 à 5. 2 par défaut |
Retour : { forms }. Chaque forme : family, label, measuredOn (la nature d’où viennent les chiffres, all = tout le corpus), ratio (les vues comparées au reste à base égale), bangers (part des vidéos à deux fois la base ou plus), accountsFor, accountsAgainst, verdict et examples, chacun avec hook (la première phrase), opening (les quelque 40 premiers mots, pour le contexte seulement), normViews (5 = cinq fois ce que fait d’habitude ce compte), year, nature, subject et onSubject (si cette accroche porte sur le sujet demandé). Plus quota quand l’appel a été rogné ; au plafond du jour, quota seul (voir Le quota).
Exemple :
{ "nature": "liste_conseils", "q": "malte expatriation", "forms": 5 }hooksSearchTool
Section intitulée « hooksSearchTool »Cherche dans la bibliothèque de vraies accroches qui ont marché : environ 25 800 premières phrases de vidéos, chacune avec ses vues rapportées à la base de son compte, la même pour tout compte (voir La bibliothèque). Pour « donne-moi des accroches pour ma vidéo », hooksFormsTool passe en premier ; celui-ci est la recherche par mots, par famille ou par nature. Lecture seule. Expérimental, comme hooksFormsTool.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
q |
string | Non | Mots du sujet, n’importe lesquels. Les accroches qui en contiennent le plus arrivent en premier |
family |
string | Non | Seulement cette famille d’accroches (slug) : promesse_directe, ciblage_si_tu, ressource_cadeau, interdiction_erreur, reset_fantasy, story_perso, story_tiers, verite_cachee, peur_menace, avant_apres, defi_demo, opinion_polemique, actu_nouveaute, comparatif_meilleur, obligation_urgence, chiffre_fait_choc, question… |
nature |
string | Non | Seulement les vidéos de cette nature (mêmes valeurs que hooksFormsTool) |
language |
string | Non | fr (par défaut), en ou all |
minNorm |
number | Non | Plancher de vues normalisées. 2 par défaut (au moins deux fois la base du compte) ; descendez à 1,5 quand le sujet est rare |
limit |
integer | Non | De 1 à 100. 15 par défaut |
withFamilies |
boolean | Non | Renvoie aussi l’effet mesuré de chaque famille d’accroches |
Retour : total (la taille de toute la bibliothèque) et hooks, chacune avec year, language, hook, opening, views, normViews, family, nature, concrete, subject, lockinGestures et matchedWords. Avec withFamilies, families : family, n, accounts, ratio, bangers, accountsFor, accountsAgainst, verdict. Seule une famille au verdict prouvé fait une règle ; les autres se choisissent selon ce qui colle. Plus quota quand l’appel a été rogné ; au plafond du jour, quota seul (voir Le quota).
Exemple :
{ "q": "impôts malte", "minNorm": 1.5, "withFamilies": true }uploadFromUrlTool
Section intitulée « uploadFromUrlTool »Importe une image ou une vidéo dans la bibliothèque de médias à partir d’une URL. Le serveur télécharge lui-même le fichier : les octets ne passent jamais par l’appel MCP ni par l’assistant.
À utiliser avant de planifier une publication quand le média est hébergé ailleurs : une pièce jointe qui n’est pas déjà hébergée sur le domaine de UseNadia échoue à la validation du domaine d’upload. L’URL doit être en HTTPS et seulement joignable depuis le serveur sans connexion : une URL publique, ou une URL signée qui expire (R2, S3, une vidéo qu’un autre outil a transmise avec son lien de téléchargement). Les adresses privées, de loopback et link-local sont refusées, y compris après chaque redirection.
Le fichier passe par les mêmes contrôles qu’un upload direct confirmé (vrai type détecté d’après les octets, ffprobe) et revient avec ses chiffres, pour que l’appelant puisse les comparer à ce qu’annonçait la source : une taille différente veut dire que le téléchargement n’est pas le fichier voulu.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
url |
string | Oui | L’URL HTTPS de l’image ou de la vidéo, joignable sans connexion |
Retour :
| Champ | Type | Description |
|---|---|---|
id |
string | ID du média |
path |
string | URL hébergée, à utiliser dans le tableau attachments |
contentType |
string | video/mp4, image/jpeg, image/png, image/webp ou image/gif : le type lu d’après les octets |
size |
number | Octets stockés |
duration |
number | null | En secondes pour une vidéo, null pour une image |
width, height |
number | Dimensions à l’affichage, rotation appliquée |
codec |
string | Codec de l’image (h264, hevc, png…) |
Les types acceptés et la taille maximale sont ceux de createUploadUrl (500 Mo par défaut). Les erreurs portent un code : URL_UNREACHABLE (pas publique, expirée, ou a répondu par une erreur), FILE_TOO_LARGE, UNSUPPORTED_CONTENT_TYPE, FILE_CORRUPTED, DOWNLOAD_INTERRUPTED.
createUploadUrl
Section intitulée « createUploadUrl »Obtient une URL à usage unique pour téléverser un fichier qui se trouve sur le disque du client (une vidéo coupée et compressée dans le bac à sable de code d’un assistant IA, par exemple), quand il n’y a pas d’URL publique à donner à uploadFromUrlTool. Les octets ne passent jamais par l’appel MCP : le client les envoie en PUT avec curl, puis appelle confirmUpload.
La séquence : createUploadUrl → lancer la commande curl renvoyée → confirmUpload → integrationSchedulePostTool (ou splitVideoIntoStories).
Toute URL d’upload vit sur un hôte à elle (https://upload.usenadia.com/api/uploads/…), qui ne sert rien d’autre : c’est le seul hôte qu’il faut autoriser dans le réseau d’un bac à sable. Elle est valable 15 minutes, pour un seul fichier, du type et de la taille déclarés, dans l’organisation qui l’a demandée, et ne donne accès à rien d’autre.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
filename |
string | Oui | Nom ou chemin du fichier sur le disque du client, repris dans la commande curl ; son nom de base devient le nom du média |
contentType |
string | Oui | video/mp4, image/jpeg, image/png, image/webp ou image/gif |
size |
number | Oui | Taille exacte en octets. 500 Mo au plus par défaut (NADIA_DIRECT_UPLOAD_MAX_BYTES) |
Retour :
| Champ | Type | Description |
|---|---|---|
uploadId |
string | À passer à confirmUpload |
uploadUrl |
string | Où envoyer le fichier en PUT |
method |
string | Toujours PUT |
headers |
object | Les en-têtes exacts à envoyer : Content-Type et Content-Length |
expiresAt |
string | Date ISO, 15 minutes après l’appel |
maxSize |
number | La taille maximale de ce serveur, en octets |
curl |
string | La commande à lancer telle quelle, par ex. curl --fail-with-body -X PUT -T 'reel.mp4' -H 'Content-Type: video/mp4' 'https://upload.usenadia.com/api/uploads/…' |
Le PUT répond 201 avec { uploadId, size }, ou par une erreur dont le message commence par un code : UPLOAD_URL_EXPIRED (410), UPLOAD_URL_ALREADY_USED (409), CONTENT_TYPE_MISMATCH (415), SIZE_MISMATCH (400), FILE_TOO_LARGE / SIZE_EXCEEDED (413), UPLOAD_URL_INVALID (404). Un transfert qui échoue en cours de route n’use pas l’URL : relancez la même commande.
confirmUpload
Section intitulée « confirmUpload »Termine un upload une fois que son PUT a répondu 201. Vérifie la taille, que les octets sont bien du type déclaré et, pour une vidéo, que ffprobe sait la lire (codec, durée, dimensions à l’affichage, avec la rotation d’une vidéo de téléphone appliquée). Ajoute ensuite le fichier à la bibliothèque de médias. Un nouvel appel renvoie le même média.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
uploadId |
string | Oui | Renvoyé par createUploadUrl |
Retour :
| Champ | Type | Description |
|---|---|---|
id |
string | ID du média |
path |
string | URL hébergée, à utiliser dans attachments, ou comme videoUrl dans splitVideoIntoStories |
contentType |
string | Le type déclaré, vérifié |
size |
number | Octets |
duration |
number | null | En secondes, null pour une image |
width / height |
number | À l’affichage |
codec |
string | Par ex. h264 |
Erreurs : FILE_NOT_UPLOADED, UPLOAD_IN_PROGRESS, UPLOAD_URL_EXPIRED, FILE_TYPE_MISMATCH, FILE_CORRUPTED, SIZE_MISMATCH, UPLOAD_NOT_FOUND. Les uploads jamais confirmés sont supprimés au bout de 24 heures.
mediaList
Section intitulée « mediaList »Liste la bibliothèque de médias, les plus récents d’abord. Lecture seule, limitée à votre espace de travail. C’est ainsi qu’un agent trouve la vidéo que vous venez de téléverser depuis votre téléphone, sans vous demander de lien.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
type |
string | Non | video ou image ; les deux s’il est absent |
search |
string | Non | Une partie du nom de fichier, sans tenir compte de la casse |
since |
string | Non | Seulement les médias téléversés à partir de cette date UTC (ISO 8601) |
limit |
number | Non | 20 par défaut, 100 au plus |
cursor |
string | Non | Le nextCursor de l’appel précédent, pour la page suivante |
Retour : media et nextCursor (null sur la dernière page). Chaque média :
| Champ | Type | Description |
|---|---|---|
id |
string | ID du média |
path |
string | URL hébergée : une entrée attachments de integrationSchedulePostTool, l’entrée de transcribe, cutVideo et splitVideoIntoStories |
filename |
string | Nom de fichier d’origine |
type |
string | video ou image |
size |
number | Octets, null si inconnu |
createdAt |
string | Date d’upload, ISO 8601 UTC |
duration |
number | Vidéos seulement : en secondes |
width, height |
number | Vidéos seulement : taille à l’affichage, rotation appliquée (height > width = vertical) |
La taille, la durée et les dimensions sont lues avec ffprobe la première fois qu’un média est listé, puis conservées.
transcribe
Section intitulée « transcribe »Transcrit une vidéo de la bibliothèque avec ElevenLabs Scribe (langue détectée automatiquement), avec les horodatages.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
path |
string | L’un des deux | Chemin renvoyé par mediaList |
mediaId |
string | L’un des deux | Ou l’ID du média |
includeWords |
boolean | Non | Renvoie aussi chaque mot avec ses horodatages. false par défaut |
Retour :
| Champ | Type | Description |
|---|---|---|
mediaId, path |
string | La vidéo transcrite |
language |
string | Langue détectée (ISO 639) |
cached |
boolean | true quand la transcription est relue d’une transcription antérieure |
text |
string | La transcription complète |
segments |
array | Un { start, end, text } par phrase, en secondes |
words |
array | Seulement avec includeWords : { start, end, text } par mot |
cutVideo
Section intitulée « cutVideo »Coupe une vidéo de la bibliothèque à des horodatages exacts. Chaque partie est réencodée
(H.264 + AAC, yuv420p, +faststart, rotation appliquée, résolution d’origine)
et ajoutée à la bibliothèque. Fournissez exactement l’un des deux : cuts ou segments.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
path |
string | Oui | Chemin du mp4, renvoyé par mediaList |
cuts |
number[] | L’un des deux | Secondes où couper : [24.45] donne deux parties qui couvrent toute la vidéo |
segments |
array | L’un des deux | Passages à garder, [{ start, end }] : chacun devient une partie, dans l’ordre donné |
Chaque partie dure au moins 0,5 s, 20 parties au plus, et chaque horodatage tombe dans la vidéo.
Retour : duration (de l’original) et parts, dans l’ordre, chacune avec
id, path, start, end et duration.
splitVideoIntoStories
Section intitulée « splitVideoIntoStories »Découpe une vidéo de la bibliothèque de médias en une série de stories de longueur à peu près égale : 20 secondes sauf demande d’une autre durée, entre 10 et 30. Les coupes tombent dans un silence de la vidéo quand il y en a un assez proche, à intervalles réguliers sinon, et les stories s’enchaînent. La durée est une cible, pas une découpe stricte : quelques secondes de reste sont réparties dans les stories au lieu d’en faire une dernière minuscule (2 min 02 à 20 s donne 6 stories d’environ 20 s ; 30 s donne 2 stories de 15).
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
videoUrl |
string | Oui | URL du mp4 : un path renvoyé par mediaList, uploadFromUrlTool ou confirmUpload, ou l’URL d’une vidéo jointe dans le chat |
targetSeconds |
number | Non | Durée visée pour chaque story, en secondes, de 10 à 30. 20 par défaut |
removeSilences |
boolean | Non | Retire les longues pauses de la vidéo avant de la couper. false par défaut : un agent ne l’active que si l’utilisateur demande explicitement de retirer les silences, jamais de lui-même et jamais en suggestion |
Retour : duration (de la vidéo coupée), silencesRemoved (secondes de silence retirées, 0 si ce n’était pas demandé) et stories, dans l’ordre, chacune avec id, path (la pièce jointe de sa propre publication story), start, end et endsOn : silence (la coupe est tombée dans une pause), even (pas de silence assez proche, coupe à intervalle régulier) ou end (dernière story).
Chaque story se planifie ensuite comme une publication à part avec integrationSchedulePostTool : un socialPost par story, dans l’ordre, exactement une pièce jointe, un contenu vide et le réglage Instagram post_type = story, à une minute d’écart pour que chacune soit publiée avant la suivante.
Exemple :
{ "videoUrl": "https://app.usenadia.com/uploads/2026/10/reel.mp4", "targetSeconds": 15 }notificationsListTool
Section intitulée « notificationsListTool »Les notifications de l’espace de travail, les plus récentes d’abord (la cloche de l’app) : une publication publiée ou en échec, un canal à reconnecter, un e-mail capté par une automatisation… 100 par page. Lecture seule.
Paramètres : page (integer, facultatif, 0 = les plus récentes).
Retour : { notifications, total, page, hasMore }. Chaque notification : id, content (texte brut), link, at.
webhooksListTool
Section intitulée « webhooksListTool »Les webhooks sortants de l’espace de travail et le catalogue des événements auxquels un webhook peut s’abonner. Lecture seule.
Paramètres : webhookId (string, facultatif, seulement celui-ci).
Retour : { webhooks, events }. Chaque webhook : id, name, url, events (vide = tous les événements), integrations (vide = tous les canaux), hasSecret. Le secret de signature lui-même n’est montré qu’une fois, par webhookManageTool à la création.
webhookManageTool
Section intitulée « webhookManageTool »Enregistre, teste ou supprime un webhook sortant.
Paramètres :
| Champ | Type | Requis | Description |
|---|---|---|---|
action |
string | Oui | create, test ou delete |
webhookId |
string | test, delete |
Le webhook |
event |
string | Non | test : l’événement à simuler (par défaut : le premier événement du webhook, ou post.published s’il les reçoit tous) |
name |
string | create |
|
url |
string | create |
Une URL HTTPS publique |
events |
string[] | Non | create : les événements à recevoir (vide = tous), noms tirés de webhooksListTool |
integrationIds |
string[] | Non | create : les canaux (vide = tous), ceux de votre organisation ; un autre id est refusé dès le premier appel |
confirmationToken |
string | create, delete, deuxième appel |
Le jeton du premier appel, une fois que l’utilisateur a dit oui |
create et delete sont des actions confirmées : un webhook envoie à son URL tout ce à quoi il est abonné (DM, e-mails captés…) tant qu’il existe. test agit tout de suite.
Retour : { ok, errors? }, plus webhook à la création, avec son secret, renvoyé une seule fois : les livraisons sont signées avec lui (X-Nadia-Signature, HMAC SHA-256 du corps).
test envoie une livraison à ce seul webhook, sans aucun événement réel : l’enveloppe signée habituelle avec test: true et un data d’exemple (de faux ID test_…, rien n’est publié). Il attend la réponse (une tentative, pas de nouvel essai, délai de 10 secondes) et renvoie { ok, delivered, status, event, deliveryId } : status est le code HTTP qu’a répondu l’URL, null quand rien n’a répondu. Équivaut à POST /public/v1/webhooks/{id}/test.