Zum Inhalt springen
Wissensdatenbank

Kampagnen-Tools – MCP-Tool-Referenz

Kampagnen-Tools verwalten den Lebenszyklus von Umfragekampagnen: Kampagnen anlegen, Interviewer und Befragtenpools zuweisen, die Arbeitslast verteilen und Einladungen versenden. Viele Operationen verwenden ein Batch-Antwortmuster mit den Feldern added/skipped/reasons.

Alle Kampagnen auflisten, optional gefiltert nach Projekt, Name oder Status.

Parameter Typ Erforderlich Standard Beschreibung
project_id string Nein — Nach Projekt-ID filtern
name string Nein — Nach Kampagnenname filtern
status string Nein — Nach Status filtern
limit integer Nein 100 Höchstzahl der zurückgegebenen Ergebnisse

Rückgabe: { items: [...], count, limit }


Eine Kampagne über ihre ID abrufen.

Parameter Typ Erforderlich Standard Beschreibung
campaign_id string Ja — UUID der Kampagne

Rückgabe: Kampagnenobjekt oder { error }. Es enthält offered_languages: die Sprachen, die Befragte wählen können – zuerst die Quellsprache des Fragebogens, dann jede vollständige Übersetzung der gepinnten Version, jeweils als { locale, name, human_edited }. Eine Kampagne ohne gepinnte Version bietet nur die Quellsprache an.


Eine neue Kampagne anlegen. Der Kampagnenmodus ergibt sich automatisch daraus, ob Interviewer zugewiesen sind.

Parameter Typ Erforderlich Standard Beschreibung
name string Ja — Anzeigename der Kampagne
project_id string Ja — ID des übergeordneten Projekts
questionnaire_id string Ja — Zu verwendender Fragebogen
status string Nein "draft" Anfangsstatus: draft, active oder scheduled. Alles andere wird abgelehnt
admits_volunteers boolean Ja — Ob Personen teilnehmen dürfen, die nie in den Pool der Kampagne gezogen wurden (spontan Teilnehmende, der offene Link). Kein Standardwert: Geben Sie ihn an.
offers_ai_channel boolean Ja — Ob Befragte die Umfrage auch in ihrem eigenen KI-Assistenten beantworten dürfen. Kein Standardwert: Geben Sie ihn an.
intro_text string Wenn offers_ai_channel true ist — Wer die Daten erhebt und warum; wird vor der ersten Frage wortwörtlich angezeigt
consent_text string Wenn offers_ai_channel true ist — Worin die befragte Person einwilligt; wird wortwörtlich angezeigt, gefolgt von einem festen Absatz über den KI-Anbieter, der immer angehängt wird

Rückgabe: das angelegte Kampagnenobjekt.

update_campaign ändert status nur entlang des Lebenszyklus der Kampagne: draft → active oder scheduled; scheduled → active oder draft; active → paused, completed oder aborted; paused → active, completed oder aborted; completed oder aborted → draft. Jeder andere Übergang oder ein unbekannter Status wird abgelehnt, und nichts wird geändert.

update_campaign akzeptiert außerdem offers_ai_channel, intro_text und consent_text, jeweils optional; fehlt ein Wert, bleibt der gespeicherte erhalten. Geprüft werden die Texte am Endzustand: Wer den Assistenten für eine Kampagne einschaltet, die bereits beide Texte enthält, muss sie nicht erneut angeben, und einen Text zu leeren, während der Assistent angeboten wird, wird abgelehnt. Schalten Sie den Assistenten aus, verfallen alle noch nicht verwendeten Kopplungscodes; bereits verbundene Befragte können ihre Umfrage noch abschließen.


Einer Kampagne Interviewer (Benutzer mit Interviewer-Rolle) hinzufügen. Verwendet das Batch-Antwortmuster.

Parameter Typ Erforderlich Standard Beschreibung
campaign_id string Ja — UUID der Kampagne
user_ids string[] Ja — Liste der Benutzer-IDs, die als Interviewer hinzugefügt werden

Rückgabe:

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

Gründe für das Überspringen: "User not found", "No interviewer role".


Interviewer aus einer Kampagne entfernen.

Parameter Typ Erforderlich Standard Beschreibung
campaign_id string Ja — UUID der Kampagne
user_ids string[] Ja — Liste der zu entfernenden Benutzer-IDs

Rückgabe:

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

Den einer Kampagne zugewiesenen Fragebogen ändern.

Parameter Typ Erforderlich Standard Beschreibung
campaign_id string Ja — UUID der Kampagne
questionnaire_id string Ja — UUID des neuen Fragebogens

Rückgabe:

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

Bestimmte Befragte innerhalb einer Kampagne einem bestimmten Interviewer zuweisen, um die Arbeitslast zu verteilen.

Parameter Typ Erforderlich Standard Beschreibung
campaign_id string Ja — UUID der Kampagne
interviewer_id string Ja — Benutzer-UUID des Interviewers
respondent_ids string[] Ja — Liste der zuzuweisenden Befragten-IDs

Rückgabe:

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

Befragte aus der Zuweisung eines Interviewers entfernen. Die Befragten bleiben im Pool der Kampagne, sind aber nicht mehr zugewiesen.

Parameter Typ Erforderlich Standard Beschreibung
campaign_id string Ja — UUID der Kampagne
interviewer_id string Ja — Benutzer-UUID des Interviewers
respondent_ids string[] Ja — Liste der Befragten-IDs, deren Zuweisung aufgehoben wird

Rückgabe:

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

Die Arbeitslast eines bestimmten Interviewers in einer Kampagne abrufen – zugewiesene Befragte und den Abschlussstand ihrer Umfragen.

Parameter Typ Erforderlich Standard Beschreibung
campaign_id string Ja — UUID der Kampagne
interviewer_id string Ja — Benutzer-UUID des Interviewers

Rückgabe:

{
"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
}
}

Befragte einer Kampagne abrufen, die noch keinem Interviewer zugewiesen sind.

Parameter Typ Erforderlich Standard Beschreibung
campaign_id string Ja — UUID der Kampagne

Rückgabe:

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

Einer Kampagne einen Befragtenpool zuweisen. Verknüpft den Pool, sodass bulk_create_surveys Umfragen für alle Befragten im Pool anlegen kann.

Parameter Typ Erforderlich Standard Beschreibung
campaign_id string Ja — UUID der Kampagne
pool_id string Ja — UUID des Befragtenpools

Rückgabe:

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

Den einer Kampagne zugewiesenen Befragtenpool abrufen.

Parameter Typ Erforderlich Standard Beschreibung
campaign_id string Ja — UUID der Kampagne

Rückgabe (Pool zugewiesen):

{
"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
}

Rückgabe (kein Pool): { campaign_id, pool_id: null, has_pool: false, message: "..." }


Umfrage-Einladungen per E-Mail an die Befragten einer Kampagne senden. Versendet echte E-Mails mit Zugang per Magic Link.

Parameter Typ Erforderlich Standard Beschreibung
campaign_id string Ja — UUID der Kampagne
respondent_ids string[] Nein — Bestimmte Befragte, die eingeladen werden
send_to_all_uninvited boolean Nein false An alle noch nicht eingeladenen Befragten senden

Jede Einladung ist in der Sprache ihres Empfängers verfasst: in der bevorzugten Sprache der befragten Person, wenn die Kampagne darin eine vollständige Übersetzung anbietet, andernfalls in der Quellsprache des Fragebogens.

Rückgabe:

{
"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}
}

Bietet die Kampagne den KI-Assistenten an, enthält jede Einladungs-E-Mail einen zusätzlichen Absatz, der die befragte Person auf die KI-Option auf ihrer Umfrageseite hinweist, und jeder Eintrag in sent trägt außerdem connector_url, die Connector-Adresse für Befragte.

Voraussetzungen je befragter Person:

  • Sie muss eine E-Mail-Adresse haben
  • notification_preference darf nicht "none" sein
  • Die Umfrage darf nicht bereits abgeschlossen oder in Bearbeitung sein
  • Die Kampagne muss sie zulassen. Jemanden einzuladen, der nie in ihren Pool gezogen wurde, erfordert eine Kampagne, die Freiwillige zulässt und sich aktiv in der Feldphase befindet – dieselbe Schranke, die auch spontan Teilnehmende passieren. Ihre Umfrage wird dann als Freiwillige erfasst, nicht als gezogener Fall, sodass der Datensatz beides weiterhin unterscheiden kann.

Gründe für das Überspringen: "Respondent not found", "No email address", "Opted out of notifications", "Survey already completed", "Survey already in_progress" sowie eine Ablehnung, die nennt, an welcher Hälfte der Zulassungsprüfung es scheiterte – die Kampagne nimmt keine spontan Teilnehmenden an, oder sie befindet sich derzeit nicht in der Feldphase.


Zwei der oben beschriebenen Abfolgen gibt es auch als einzelnen Aufruf. Sie sind keine Abkürzungen, die etwas auslassen: Jeder Schritt ist dasselbe auf dieser Seite dokumentierte Tool; es werden also dieselben Datensätze geschrieben, dieselben Audit-Ereignisse erfasst, und jede Ablehnung, die ein einzelnes Tool liefern würde, erhalten Sie hier unverändert – plus stopped_at_step, das nennt, aus welchem Schritt ein Abbruch kam. Nichts wird rückgängig gemacht; eine Kette, die mittendrin abbricht, hinterlässt also, was die früheren Schritte aufgebaut haben, und Sie machen mit den einzelnen Tools weiter.

Eine Kette prüft Ihre Berechtigung für jeden Schritt, bevor sie irgendetwas aufbaut. Deckt Ihr Abonnement einen späteren Schritt nicht ab, wird der Aufruf vorab abgelehnt, statt Ihnen eine halb aufgebaute Feldphase zu hinterlassen.

Die gesamte Feldvorbereitungskette einer Kampagne ausführen: die Stichprobenstrategie anlegen, den Befragtenpool erzeugen, den Pool der Kampagne zuweisen, die Fragebogenversion veröffentlichen (und pinnen), mit der die Kampagne ins Feld geht, und die Umfragen anlegen.

Parameter Typ Erforderlich Standard Beschreibung
campaign_id string Ja — Vorzubereitende Kampagne. Sie muss bereits den Fragebogen nennen, mit dem Sie ins Feld gehen wollen
admits_volunteers boolean Ja keiner Die Regel dieser Feldphase zur Zulassung von Freiwilligen, ausdrücklich angegeben. Es gibt keinen Standardwert, und sie muss mit der Einstellung der Kampagne übereinstimmen – ändern Sie diese zuerst mit update_campaign, falls sie falsch ist
strategy_name string Ja — Name der Stichprobenstrategie, die dieser Lauf anlegt
target_size integer Ja — Gewünschte Größe der Poolziehung: Zahl der zu ziehenden Befragten vor dem Oversampling (> 0). Wird als requested_size an die Ziehung übergeben und im Pool gespeichert
factors object[] Nein [] Demografische Verteilungsfaktoren, an denen die Strategie misst
selection_algorithm string Nein "greedy" Auswahlalgorithmus für die Poolziehung ("greedy" oder "random_constrained")
oversample_factor number Nein 1.0 Oversampling-Multiplikator für die Poolziehung (≥ 1)
quality_metric string Nein "rmse" Kennzahl, mit der die Strategie die Übereinstimmung bewertet: "rmse", "mae", "chi_square" oder "max_deviation". Jeder andere Wert wird abgelehnt, bevor etwas aufgebaut wird
require_email boolean Nein false Die Poolziehung lässt nur Befragte mit E-Mail-Adresse zu
pool_name string Nein — Name des erzeugten Pools; standardmäßig eine aus der Strategie abgeleitete Bezeichnung

Die Strategie, die dieser Lauf anlegt, enthält nur factors und quality_metric. Die Ziehungseinstellungen (target_size, oversample_factor, selection_algorithm, require_email) gehen an den Pool-Schritt und werden im Pool gespeichert, genau wie bei einem direkten Aufruf von generate_pool_from_strategy.

Rückgabe: ready_to_invite, die strategy_id, pool_id, pool_respondent_count, qml_version_id, die offered_languages, die Befragte für diese Version wählen können (wie bei get_campaign), und die erzeugten surveys_created / surveys_skipped, dazu next_step. Bei einem Abbruch: stopped_at_step mit error und detail des ablehnenden Schritts sowie alles, was frühere Schritte bereits aufgebaut hatten.

Warum der Veröffentlichungsschritt wichtig ist. Eine von Hand gebaute Kette vergisst häufig das Veröffentlichen, und eine Kampagne ohne gepinnte Version verwendet bei jedem Lesen den jeweils neuesten Stand des Fragebogens – eine Änderung mitten in der Feldphase verändert dann stillschweigend das Instrument für Befragte, die bereits geantwortet haben.

Ein erneuter Lauf zieht erneut. Jeder Lauf legt eine neue Strategie und einen neuen Pool an und bindet die Kampagne neu daran (ein Pool ist nur einmal verwendbar), legt dann für den neuen Pool Umfragen an und überspringt Befragte, die für diese Kampagne bereits eine Umfrage haben. Bei einem Befragtenbestand, der größer als target_size ist, ergänzt ein zweiter Lauf daher neu gezogene Befragte, statt jemanden zu ersetzen.


Die Umfragen der Kampagne anlegen und anschließend synthetische Antworten darüber erzeugen. Was die einzelnen Verteilungsmodi und Persona-Profile bewirken, steht unter mass_fill_surveys.

Parameter Typ Erforderlich Standard Beschreibung
campaign_id string Ja — Kampagne, deren Umfragen angelegt und dann gefüllt werden
distribution string Nein "realistic" "realistic", "random" oder "llm"
max_surveys integer Nein — Obergrenze, wie viele Umfragen der Kampagne gefüllt werden
profiles string[] Nein ["random"] Persona-Namen, die reihum auf Befragte verteilt werden
concurrency integer Nein 1 Parallelität der inneren Schleife beim Füllen

Rückgabe: surveys_created / surveys_skipped und eine task_id für das Füllen mit status: "pending". Fragen Sie sie mit get_task_status ab, genau wie einen mass_fill_surveys-Lauf. Bei einem Abbruch: stopped_at_step mit error und detail des ablehnenden Schritts sowie task_id: null.


Situation Antwort
Kampagne nicht gefunden {"error": "Campaign {id} not found"}
Interviewer nicht in der Kampagne {"error": "Interviewer {id} is not assigned to this campaign"}
Kein Fragebogen/Pool {"error": "Campaign has no questionnaire assigned"}

Die meisten Kampagnen-Tools, die Listen von IDs annehmen, liefern strukturierte Ergebnisse, statt an einzelnen Einträgen zu scheitern:

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

Dieses Muster gilt für: add_interviewers_to_campaign, remove_interviewers_from_campaign, assign_respondents_to_interviewer, unassign_respondents_from_interviewer und send_campaign_invitations.

Jeder übersprungene oder fehlgeschlagene Eintrag enthält ein Feld reason, das erklärt, warum er von der Operation ausgeschlossen wurde.