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.
list_campaigns
Section intitulée « list_campaigns »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 }
get_campaign
Section intitulée « get_campaign »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.
create_campaign
Section intitulée « create_campaign »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.
add_interviewers_to_campaign
Section intitulée « add_interviewers_to_campaign »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".
remove_interviewers_from_campaign
Section intitulée « remove_interviewers_from_campaign »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}update_campaign_questionnaire
Section intitulée « update_campaign_questionnaire »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"}assign_respondents_to_interviewer
Section intitulée « assign_respondents_to_interviewer »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"]}unassign_respondents_from_interviewer
Section intitulée « unassign_respondents_from_interviewer »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"]}get_interviewer_workload
Section intitulée « get_interviewer_workload »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 }}get_unassigned_respondents
Section intitulée « get_unassigned_respondents »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"} ]}assign_pool_to_campaign
Section intitulée « assign_pool_to_campaign »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}get_campaign_pool
Section intitulée « get_campaign_pool »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: "..." }
send_campaign_invitations
Section intitulée « send_campaign_invitations »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_preferencene 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.
Outils de chaîne
Section intitulée « Outils de chaîne »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.
prepare_campaign_fielding
Section intitulée « prepare_campaign_fielding »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.
simulate_campaign_responses
Section intitulée « simulate_campaign_responses »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.
Gestion des erreurs
Section intitulée « Gestion des erreurs »Erreurs courantes
Section intitulée « Erreurs courantes »| 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"} |
Format des opérations groupées
Section intitulée « Format des opérations groupées »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.