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.
list_respondents
Abschnitt betitelt „list_respondents“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 }
get_respondent
Abschnitt betitelt „get_respondent“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 }.
create_respondent
Abschnitt betitelt „create_respondent“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.
Demografische Attribute
Abschnitt betitelt „Demografische Attribute“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 |
update_respondent
Abschnitt betitelt „update_respondent“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: {...} }.
delete_respondent
Abschnitt betitelt „delete_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 } }
bulk_create_respondents
Abschnitt betitelt „bulk_create_respondents“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": [ ]}Erzeugte demografische Daten
Abschnitt betitelt „Erzeugte demografische Daten“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.
generate_survey_access_token
Abschnitt betitelt „generate_survey_access_token“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.
send_survey_invitation
Abschnitt betitelt „send_survey_invitation“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": "...", "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.
bulk_delete_respondents
Abschnitt betitelt „bulk_delete_respondents“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 }
Fehlerbehandlung
Abschnitt betitelt „Fehlerbehandlung“Häufige Fehler
Abschnitt betitelt „Häufige Fehler“| 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}"} |
Grenzen der Massenanlage
Abschnitt betitelt „Grenzen der Massenanlage“| Situation | Antwort |
|---|---|
| Anzahl über 100 | {"error": "Maximum 100 respondents per request"} |
| Anzahl unter 1 | {"error": "Count must be at least 1"} |