Zum Inhalt springen
Wissensdatenbank

Tools für Befragte — MCP-Tool-Referenz

Die Tools für Befragte verwalten die Zielpersonen von Umfragen – Befragte anlegen, aktualisieren und löschen, sie für Tests in großer Zahl erzeugen und Einladungen zu Umfragen versenden. Befragte sind keine Benutzer der Plattform; sie greifen ohne Authentifizierung über Magic Links auf Umfragen zu.

Listet Befragte auf, optional gefiltert.

Parameter Typ Erforderlich Standard Beschreibung
source_system string Nein — Nach Quelle filtern (z. B. "crm", "panel_provider")
project_id string Nein — Nach Projekt filtern
name string Nein — Teilzeichenfolgen-Suche ohne Berücksichtigung der Groß- und Kleinschreibung
limit integer Nein 100 Maximale Anzahl an Ergebnissen

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


Ruft eine befragte Person anhand ihrer ID ab.

Parameter Typ Erforderlich Standard Beschreibung
respondent_id string Ja — UUID der befragten Person

Rückgabe: Objekt der befragten Person oder { error }.


Legt eine einzelne befragte Person mit demografischen Attributen an.

Parameter Typ Erforderlich Standard Beschreibung
name string Ja — Anzeigename
project_id string Nein — Projekt-ID
email string Nein — E-Mail-Adresse für Einladungen
external_id string Nein — ID aus einem externen System (CRM, Panel)
source_system string Nein — Name des Quellsystems (z. B. "crm")
age integer Nein — Alter
gender string Nein — Geschlecht
location string Nein — Ort
preferred_language string Nein — Bevorzugte Sprache (en, es, fr, de oder hu) oder null für keine. Bestimmt die Sprache der Einladung und die auf der ersten Seite der Umfrage vorausgewählte Sprache, sofern die Kampagne sie anbietet; die befragte Person kann trotzdem eine andere wählen
custom_attributes object Nein {} Benutzerdefinierte Schlüssel-Wert-Paare für die Zielgruppenauswahl

Rückgabe: Das angelegte Objekt der befragten Person.

Für Befragte gibt es folgende demografische Felder für den Abgleich mit Stichprobenstrategien und die Auswertung von Umfragen:

Attribut Typ Verwendet von
age integer Altersbasierte Stichprobenfaktoren, Persona-Gewichtung von mass_fill_surveys
gender string Geschlechtsbasierte Stichprobenfaktoren
location string Geografische Stichprobenfaktoren
custom_attributes object Benutzerdefinierte Zielgruppenauswahl und Segmentierung

Aktualisiert die Angaben zu einer befragten Person (partielle Aktualisierung – nur die übergebenen Felder ändern sich).

Parameter Typ Erforderlich Standard Beschreibung
respondent_id string Ja — UUID der befragten Person
name string Nein — Neuer Name
email string Nein — Neue E-Mail-Adresse
age integer Nein — Neues Alter
gender string Nein — Neues Geschlecht
location string Nein — Neuer Ort
external_id string Nein — Neue externe ID
source_system string Nein — Neues Quellsystem
preferred_language string Nein — Neue bevorzugte Sprache; weglassen, um den gespeicherten Wert zu behalten, null senden, um ihn zu löschen
custom_attributes object Nein — Neue benutzerdefinierte Attribute (ersetzen die vorhandenen)

Rückgabe: Das aktualisierte Objekt der befragten Person. Werden keine Änderungen erkannt: { message: "No changes detected", respondent: {...} }.


Entfernt eine befragte Person.

Parameter Typ Erforderlich Standard Beschreibung
respondent_id string Ja — UUID der befragten Person

Rückgabe: { deleted: true, respondent_id, respondent_info: { name, email, external_id, source_system } }


Legt mehrere Befragte mit realistischen, erfundenen demografischen Daten an. Nur für Testdaten – nicht für Produktivdaten verwenden.

Parameter Typ Erforderlich Standard Beschreibung
count integer Ja — Anzahl der anzulegenden Befragten (1–100)
project_id string Nein — Projekt-ID
name_prefix string Nein "Test" Präfix für die erzeugten Namen
source_system string Nein "bulk_generate" Name des Quellsystems
generate_demographics boolean Nein true Realistische demografische Daten mit Faker erzeugen
preferred_language string Nein — Eine bevorzugte Sprache für alle angelegten Befragten

Rückgabe:

{
"created": 50,
"project_id": "...",
"source_system": "bulk_generate",
"respondents": [
{"id": "...", "name": "John Smith", "email": "[email protected]", "project_id": "..."}
]
}

Ist generate_demographics true (Standard), erzeugt Faker:

Feld Erzeugungsmethode
name faker.name()
email faker.email()
age Zufällige Ganzzahl 18–75
gender Zufällig: "male", "female" oder "other"
location "{city}, {country}"
external_id "bulk-{random_hex}"

Ist generate_demographics false, werden fortlaufende Namen ("Test Respondent 1") und E-Mail-Adressen ohne demografische Daten erzeugt.


Erzeugt ein Magic-Link-Token, mit dem eine befragte Person ohne Authentifizierung auf ihre Umfrage zugreift.

Parameter Typ Erforderlich Standard Beschreibung
survey_id string Ja — UUID der Umfrage
respondent_id string Ja — UUID der befragten Person (muss zur befragten Person der Umfrage passen)
expiration_hours integer Nein 168 Stunden bis zum Ablauf des Tokens (Standard: 7 Tage)

Rückgabe:

{
"token": "...",
"survey_url": "https://sirway.dev.askalot.io/s/{token}",
"survey_id": "...",
"respondent_id": "...",
"expiration_hours": 168
}

Bietet die Kampagne der Umfrage den KI-Assistenten an, enthält das Ergebnis zusätzlich connector_url, die Adresse des Connectors für Befragte (https://portor.<tenant>.askalot.io/respond/mcp), sodass eine Einladung, die Sie von Hand weitergeben, beide Zugangswege nennen kann. Der Kopplungscode selbst wird hier nie zurückgegeben: Die befragte Person erhält ihn auf ihrer eigenen Umfrageseite. Siehe KI-gestütztes Selbstinterview.


Sendet einer befragten Person eine Einladungs-E-Mail zur Umfrage mit einem Magic Link. Versendet eine echte E-Mail.

Parameter Typ Erforderlich Standard Beschreibung
survey_id string Ja — UUID der Umfrage
respondent_id string Ja — UUID der befragten Person (muss zur befragten Person der Umfrage passen)
expiration_hours integer Nein 168 Stunden bis zum Ablauf des Links (Standard: 7 Tage)
subject string Nein — Eigener E-Mail-Betreff. Standard: "You're invited to complete: {questionnaire_name}"
body_template string Nein — Eigener Text mit Platzhaltern: {name}, {url}, {expiration}, {questionnaire}

Rückgabe:

{
"status": "sent",
"survey_id": "...",
"respondent_id": "...",
"email": "[email protected]",
"survey_url": "https://sirway.dev.askalot.io/s/{token}",
"message_id": "...",
"message_bus_used": true
}

Die E-Mail wird in der Sprache der Umfrage verfasst: in der bereits gewählten, sonst in der bevorzugten Sprache der befragten Person, sofern die Kampagne darin eine vollständige Übersetzung anbietet, sonst in der Quellsprache des Fragebogens. Ein eigener subject und ein eigenes body_template werden so versendet, wie sie geschrieben sind.

Bietet die Kampagne der Umfrage den KI-Assistenten an, enthält die E-Mail einen zusätzlichen Absatz, der der befragten Person mitteilt, dass sie den Link öffnen und die Umfrage mit ihrem eigenen KI-Assistenten beantworten kann; das Ergebnis enthält dann außerdem connector_url.


Löscht mehrere Befragte anhand von Filterkriterien. Verwendet einen zweistufigen Ablauf: Rufen Sie das Tool zuerst mit dry_run=true auf, um eine Vorschau der zu löschenden Einträge zu erhalten, und dann erneut mit dry_run=false, um die Löschung auszuführen.

Mindestens ein Filter muss angegeben werden, um eine versehentliche Massenlöschung zu verhindern.

Parameter Typ Erforderlich Standard Beschreibung
source_system string Nein — Nach Quellsystem filtern (z. B. "bulk_generate", "mcp_review")
project_id string Nein — Nach Projekt-ID filtern
orphans_only boolean Nein false Nur Befragte ohne Projekt erfassen (kombinierbar mit anderen Filtern)
dry_run boolean Nein true Vorschaumodus – liefert Anzahl und Beispiele, ohne zu löschen

Rückgabe des Probelaufs:

{
"dry_run": true,
"count": 50,
"sample": [{"id": "...", "name": "...", "source_system": "bulk_generate", "project_id": null}],
"message": "Would delete 50 respondents. Call again with dry_run=False to execute."
}

Rückgabe der Ausführung: { dry_run: false, deleted: 50 }


Situation Antwort
Befragte Person nicht gefunden {"error": "Respondent {id} not found"}
Umfrage nicht gefunden {"error": "Survey {id} not found"}
Befragte Person passt nicht {"error": "Respondent is not the respondent for this survey"}
Keine E-Mail-Adresse {"error": "Respondent has no email address"}
Abgemeldet {"error": "Respondent has opted out of notifications"}
E-Mail-Versand fehlgeschlagen {"error": "Failed to send email: {details}"}
Situation Antwort
Anzahl über 100 {"error": "Maximum 100 respondents per request"}
Anzahl unter 1 {"error": "Count must be at least 1"}