Aller au contenu
Base de connaissances

Outils de campagne — référence des outils MCP

Les outils de campagne gèrent le cycle de vie des campagnes d’enquête : création des campagnes, affectation des enquêteurs et des viviers de répondants, répartition de la charge de travail et envoi des invitations. De nombreuses opérations suivent un format de réponse groupée avec les champs added/skipped/reasons.

Liste toutes les campagnes, avec un filtre facultatif par projet, par nom ou par statut.

Paramètre Type Obligatoire Par défaut Description
project_id string Non — Filtre par identifiant de projet
name string Non — Filtre par nom de campagne
status string Non — Filtre par statut
limit integer Non 100 Nombre maximal de résultats renvoyés

Renvoie : { items: [...], count, limit }


Récupère une campagne par son identifiant.

Paramètre Type Obligatoire Par défaut Description
campaign_id string Oui — UUID de la campagne

Renvoie : l’objet campagne ou { error }. Il comprend offered_languages : les langues que les répondants peuvent choisir, en commençant par la langue source du questionnaire, puis chaque traduction complète de la version figée, chacune sous la forme { locale, name, human_edited }. Une campagne sans version figée ne propose que la langue source.


Crée une nouvelle campagne. Le mode de la campagne est déterminé automatiquement selon que des enquêteurs sont affectés ou non.

Paramètre Type Obligatoire Par défaut Description
name string Oui — Nom affiché de la campagne
project_id string Oui — Identifiant du projet parent
questionnaire_id string Oui — Questionnaire à utiliser
status string Non "draft" Statut initial : draft, active ou scheduled. Toute autre valeur est refusée
admits_volunteers boolean Oui — Indique si des personnes jamais tirées dans le vivier de la campagne peuvent y participer (participations spontanées, lien ouvert). Pas de valeur par défaut : indiquez-le.
offers_ai_channel boolean Oui — Indique si les répondants peuvent aussi répondre à l’enquête dans leur propre assistant IA. Pas de valeur par défaut : indiquez-le.
intro_text string Lorsque offers_ai_channel est vrai — Qui collecte les données et pourquoi, affiché mot pour mot avant la première question
consent_text string Lorsque offers_ai_channel est vrai — Ce à quoi le répondant consent, affiché mot pour mot ; un paragraphe fixe sur le fournisseur d’IA est toujours ajouté à la suite

Renvoie : l’objet campagne créé.

update_campaign ne modifie status qu’en suivant le cycle de vie de la campagne : draft → active ou scheduled ; scheduled → active ou draft ; active → paused, completed ou aborted ; paused → active, completed ou aborted ; completed ou aborted → draft. Toute autre transition, ou un statut inconnu, est refusée et rien n’est modifié.

update_campaign accepte aussi offers_ai_channel, intro_text et consent_text, chacun facultatif et repris de la campagne enregistrée s’il est omis. Les textes sont vérifiés sur le résultat : activer l’assistant pour une campagne qui contient déjà les deux textes n’exige pas de les fournir à nouveau, et vider un texte alors que l’assistant est proposé est refusé. Désactiver l’assistant invalide tous les codes d’association non encore utilisés ; les répondants déjà connectés peuvent toujours terminer.


Ajoute des enquêteurs (utilisateurs ayant le rôle Enquêteur) à une campagne. Suit le format de réponse groupée.

Paramètre Type Obligatoire Par défaut Description
campaign_id string Oui — UUID de la campagne
user_ids string[] Oui — Liste des identifiants d’utilisateurs à ajouter comme enquêteurs

Renvoie :

{
"campaign_id": "...",
"added": ["uid1"],
"already_present": ["uid2"],
"skipped": [{"id": "uid3", "reason": "User not found"}],
"total_added": 1
}

Motifs d’exclusion : "User not found", "No interviewer role".


Retire des enquêteurs d’une campagne.

Paramètre Type Obligatoire Par défaut Description
campaign_id string Oui — UUID de la campagne
user_ids string[] Oui — Liste des identifiants d’utilisateurs à retirer

Renvoie :

{
"campaign_id": "...",
"removed": ["uid1"],
"not_found": ["uid2"],
"total_removed": 1
}

Change le questionnaire affecté à une campagne.

Paramètre Type Obligatoire Par défaut Description
campaign_id string Oui — UUID de la campagne
questionnaire_id string Oui — UUID du nouveau questionnaire

Renvoie :

{
"campaign_id": "...",
"old_questionnaire_id": "...",
"new_questionnaire_id": "...",
"success": true,
"warning": "Campaign has existing surveys — they reference the old questionnaire"
}

Affecte des répondants donnés à un enquêteur donné au sein d’une campagne, pour répartir la charge de travail.

Paramètre Type Obligatoire Par défaut Description
campaign_id string Oui — UUID de la campagne
interviewer_id string Oui — UUID de l’utilisateur enquêteur
respondent_ids string[] Oui — Liste des identifiants de répondants à affecter

Renvoie :

{
"assigned": ["r1"],
"already_assigned": ["r2"],
"not_in_campaign": ["r3"]
}

Retire des répondants de l’affectation d’un enquêteur. Les répondants restent dans le vivier de la campagne, mais ne sont plus affectés.

Paramètre Type Obligatoire Par défaut Description
campaign_id string Oui — UUID de la campagne
interviewer_id string Oui — UUID de l’utilisateur enquêteur
respondent_ids string[] Oui — Liste des identifiants de répondants à désaffecter

Renvoie :

{
"unassigned": ["r1"],
"not_assigned": ["r2"]
}

Renvoie la charge de travail d’un enquêteur donné dans une campagne : les répondants affectés et l’état d’avancement des enquêtes.

Paramètre Type Obligatoire Par défaut Description
campaign_id string Oui — UUID de la campagne
interviewer_id string Oui — UUID de l’utilisateur enquêteur

Renvoie :

{
"campaign_id": "...",
"interviewer_id": "...",
"assigned_respondents": [
{"id": "...", "name": "...", "email": "...", "age": 35, "gender": "female", "location": "Berlin"}
],
"survey_status": {
"respondent_id": {"survey_id": "...", "status": "completed", "completed": true}
},
"statistics": {
"total_assigned": 10,
"completed": 3,
"in_progress": 2,
"not_started": 5,
"completion_rate": 0.3
}
}

Renvoie les répondants d’une campagne qui ne sont encore affectés à aucun enquêteur.

Paramètre Type Obligatoire Par défaut Description
campaign_id string Oui — UUID de la campagne

Renvoie :

{
"campaign_id": "...",
"unassigned_count": 5,
"unassigned_respondents": [
{"id": "...", "name": "...", "email": "...", "age": 28, "gender": "male", "location": "Munich"}
]
}

Affecte un vivier de répondants à une campagne. Relie le vivier afin que bulk_create_surveys puisse créer des enquêtes pour tous ses répondants.

Paramètre Type Obligatoire Par défaut Description
campaign_id string Oui — UUID de la campagne
pool_id string Oui — UUID du vivier de répondants

Renvoie :

{
"campaign_id": "...",
"pool_id": "...",
"pool_name": "Urban Millennials",
"respondent_count": 200,
"previous_pool_id": null
}

Renvoie le vivier de répondants affecté à une campagne.

Paramètre Type Obligatoire Par défaut Description
campaign_id string Oui — UUID de la campagne

Renvoie (vivier affecté) :

{
"campaign_id": "...",
"pool_id": "...",
"pool_name": "...",
"pool_description": "...",
"respondent_count": 200,
"respondent_ids": ["..."],
"source_type": "strategy",
"source_strategy_id": "...",
"quality_score": 0.95,
"has_pool": true
}

Renvoie (aucun vivier) : { campaign_id, pool_id: null, has_pool: false, message: "..." }


Envoie les e-mails d’invitation à l’enquête aux répondants de la campagne. Envoie de vrais e-mails contenant un lien magique d’accès.

Paramètre Type Obligatoire Par défaut Description
campaign_id string Oui — UUID de la campagne
respondent_ids string[] Non — Répondants précis à inviter
send_to_all_uninvited boolean Non false Envoie à tous les répondants pas encore invités

Chaque invitation est rédigée dans la langue de son destinataire : la langue préférée du répondant lorsque la campagne propose une traduction complète dans cette langue, sinon la langue source du questionnaire.

Renvoie :

{
"campaign_id": "...",
"results": {
"sent": [{"respondent_id": "...", "name": "...", "email": "...", "survey_id": "...", "survey_url": "..."}],
"skipped": [{"respondent_id": "...", "name": "...", "reason": "No email address"}],
"failed": [{"respondent_id": "...", "name": "...", "reason": "Email send failed: ..."}]
},
"summary": {"sent": 8, "skipped": 1, "failed": 1}
}

Lorsque la campagne propose l’assistant IA, chaque e-mail d’invitation ajoute un paragraphe qui signale au répondant l’option IA de sa page d’enquête, et chaque entrée sent porte aussi connector_url, l’adresse du connecteur du répondant.

Conditions d’éligibilité pour chaque répondant :

  • Disposer d’une adresse e-mail
  • notification_preference ne doit pas valoir "none"
  • L’enquête ne doit pas être déjà terminée ni en cours
  • La campagne doit l’accepter. Inviter une personne que la campagne n’a jamais tirée dans son vivier exige une campagne qui admet les volontaires et qui est effectivement sur le terrain : c’est le même contrôle que celui d’une participation spontanée. Son enquête est alors enregistrée comme celle d’un volontaire et non comme un cas tiré, de sorte que le jeu de données peut toujours distinguer les deux.

Motifs d’exclusion : "Respondent not found", "No email address", "Opted out of notifications", "Survey already completed", "Survey already in_progress", ainsi qu’un refus qui nomme la moitié du contrôle d’admission qui a dit non : la campagne n’accepte pas les participations spontanées, ou elle n’est pas actuellement sur le terrain.


Deux des séquences ci-dessus sont aussi disponibles en un seul appel. Ce ne sont pas des raccourcis qui sautent quoi que ce soit : chaque étape est le même outil que ceux documentés sur cette page, si bien que les mêmes enregistrements sont écrits, les mêmes événements d’audit consignés, et tout refus qu’un outil brut vous opposerait vous est renvoyé ici tel quel, avec en plus stopped_at_step, qui nomme l’étape d’où vient l’arrêt. Rien n’est annulé : une chaîne qui s’arrête en cours de route laisse en place ce que les étapes précédentes ont construit, et vous poursuivez avec les outils individuels.

Une chaîne vérifie vos droits pour chaque étape avant de construire quoi que ce soit. Si votre abonnement ne couvre pas une étape ultérieure, l’appel est refusé d’emblée, plutôt que de vous laisser avec une mise sur le terrain à moitié construite.

Exécute toute la chaîne de mise sur le terrain d’une campagne : crée la stratégie d’échantillonnage, génère le vivier de répondants, affecte le vivier à la campagne, publie (et fige) la version du questionnaire que la campagne utilisera sur le terrain, et crée les enquêtes.

Paramètre Type Obligatoire Par défaut Description
campaign_id string Oui — Campagne à préparer. Elle doit déjà nommer le questionnaire que vous comptez utiliser sur le terrain
admits_volunteers boolean Oui aucun La règle d’admission des volontaires pour cette mise sur le terrain, indiquée explicitement. Il n’y a pas de valeur par défaut, et elle doit correspondre au réglage de la campagne elle-même : s’il est erroné, modifiez-le d’abord avec update_campaign
strategy_name string Oui — Nom de la stratégie d’échantillonnage créée par cette exécution
target_size integer Oui — La taille demandée pour le tirage du vivier : nombre de répondants à tirer, avant suréchantillonnage (> 0). Transmise au tirage comme requested_size et enregistrée sur le vivier
factors object[] Non [] Facteurs de distribution démographique par rapport auxquels la stratégie évalue l’adéquation
selection_algorithm string Non "greedy" Algorithme de sélection pour le tirage du vivier ("greedy" ou "random_constrained")
oversample_factor number Non 1.0 Multiplicateur de suréchantillonnage pour le tirage du vivier (≥ 1)
quality_metric string Non "rmse" Métrique avec laquelle la stratégie évalue l’adéquation : "rmse", "mae", "chi_square" ou "max_deviation". Toute autre valeur est refusée avant toute construction
require_email boolean Non false Le tirage du vivier n’admet que des répondants disposant d’une adresse e-mail
pool_name string Non — Nom du vivier généré ; par défaut, un libellé dérivé de la stratégie

La stratégie créée par cette exécution ne contient que factors et quality_metric. Les paramètres de tirage (target_size, oversample_factor, selection_algorithm, require_email) sont transmis à l’étape du vivier et enregistrés sur celui-ci, exactement comme le ferait un appel direct à generate_pool_from_strategy.

Renvoie : ready_to_invite, le strategy_id, pool_id, pool_respondent_count, qml_version_id, les offered_languages que les répondants peuvent choisir pour cette version (comme dans get_campaign) et les surveys_created / surveys_skipped produits, ainsi que next_step. En cas d’arrêt : stopped_at_step avec l’error et le detail propres à l’étape qui a refusé, et tout ce que les étapes précédentes avaient déjà construit.

Pourquoi l’étape de publication compte. Une chaîne construite à la main oublie souvent de publier, et une campagne sans version figée utilise la dernière version du questionnaire au moment de la lecture : une modification faite en cours de terrain change alors silencieusement l’instrument pour des répondants qui ont déjà répondu.

Relancer, c’est tirer à nouveau. Chaque exécution crée une nouvelle stratégie et un nouveau vivier et y rattache la campagne (un vivier est à usage unique), puis parcourt le nouveau vivier en ignorant les répondants qui ont déjà une enquête pour cette campagne. Face à une liste plus grande que target_size, une seconde exécution ajoute donc des répondants nouvellement tirés plutôt que de remplacer qui que ce soit.


Crée les enquêtes de la campagne, puis génère des réponses synthétiques sur celles-ci. Voir mass_fill_surveys pour le rôle de chaque mode de distribution et de chaque profil de persona.

Paramètre Type Obligatoire Par défaut Description
campaign_id string Oui — Campagne dont les enquêtes sont créées puis remplies
distribution string Non "realistic" "realistic", "random" ou "llm"
max_surveys integer Non — Plafond du nombre d’enquêtes de la campagne à remplir
profiles string[] Non ["random"] Noms de personas attribués à tour de rôle aux répondants
concurrency integer Non 1 Parallélisme de la boucle interne du remplissage

Renvoie : surveys_created / surveys_skipped, et un task_id pour le remplissage avec status: "pending". Interrogez-le avec get_task_status exactement comme une exécution de mass_fill_surveys. En cas d’arrêt : stopped_at_step avec l’error et le detail de l’étape qui a refusé, et task_id: null.


Situation Réponse
Campagne introuvable {"error": "Campaign {id} not found"}
Enquêteur absent de la campagne {"error": "Interviewer {id} is not assigned to this campaign"}
Pas de questionnaire ni de vivier {"error": "Campaign has no questionnaire assigned"}

La plupart des outils de campagne qui acceptent des listes d’identifiants renvoient des résultats structurés plutôt que d’échouer sur des éléments individuels :

{
"added": ["id1"],
"already_present": ["id2"],
"skipped": [{"id": "id3", "reason": "User not found"}],
"total_added": 1
}

Ce format s’applique à : add_interviewers_to_campaign, remove_interviewers_from_campaign, assign_respondents_to_interviewer, unassign_respondents_from_interviewer et send_campaign_invitations.

Chaque élément ignoré ou en échec comporte un champ reason qui explique pourquoi il a été exclu de l’opération.