Válaszadói eszközök – MCP-eszközreferencia
A válaszadói eszközök a kérdőívek célszemélyeit kezelik – válaszadók létrehozása, módosítása és törlése, tömeges előállítás teszteléshez, valamint kérdőív-meghívók küldése. A válaszadók nem platformfelhasználók; hitelesítés nélkül, belépési linkkel érik el a kérdőíveket.
list_respondents
Szekció neve “list_respondents”Válaszadók listázása opcionális szűrőkkel.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
source_system |
string |
Nem | — | Szűrés forrás szerint (pl. "crm", "panel_provider") |
project_id |
string |
Nem | — | Szűrés projekt szerint |
name |
string |
Nem | — | Kis- és nagybetűt nem megkülönböztető részszöveg-egyezés |
limit |
integer |
Nem | 100 |
A visszaadott találatok legnagyobb száma |
Visszatérési érték: { items: [...], count, limit }
get_respondent
Szekció neve “get_respondent”Válaszadó lekérdezése azonosító alapján.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
respondent_id |
string |
Igen | — | A válaszadó UUID-ja |
Visszatérési érték: a válaszadóobjektum vagy { error }.
create_respondent
Szekció neve “create_respondent”Egyetlen válaszadó létrehozása demográfiai jellemzőkkel.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
name |
string |
Igen | — | Megjelenített név |
project_id |
string |
Nem | — | Projektazonosító |
email |
string |
Nem | — | E-mail-cím a meghívókhoz |
external_id |
string |
Nem | — | Azonosító egy külső rendszerből (CRM, panel) |
source_system |
string |
Nem | — | A forrásrendszer neve (pl. "crm") |
age |
integer |
Nem | — | Életkor |
gender |
string |
Nem | — | Nem |
location |
string |
Nem | — | Lakóhely |
preferred_language |
string |
Nem | — | Preferált nyelv (en, es, fr, de vagy hu), illetve null, ha nincs. Ez határozza meg a meghívó nyelvét és a kérdőív első oldalán előre kiválasztott nyelvet, ha a kampány kínálja; a válaszadó ettől még választhat másikat |
custom_attributes |
object |
Nem | {} |
Egyéni kulcs–érték párok a célzáshoz |
Visszatérési érték: a létrehozott válaszadóobjektum.
Demográfiai jellemzők
Szekció neve “Demográfiai jellemzők”A válaszadókhoz az alábbi demográfiai mezők adhatók meg; ezeket a mintavételi stratégiák illesztése és a kérdőíves elemzés használja:
| Jellemző | Típus | Felhasználja |
|---|---|---|
age |
integer | Életkor alapú mintavételi tényezők, a mass_fill_surveys perszónasúlyozása |
gender |
string | Nem alapú mintavételi tényezők |
location |
string | Földrajzi mintavételi tényezők |
custom_attributes |
object | Egyéni célzás és szegmentálás |
update_respondent
Szekció neve “update_respondent”A válaszadó adatainak módosítása (részleges módosítás – csak a megadott mezők változnak).
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
respondent_id |
string |
Igen | — | A válaszadó UUID-ja |
name |
string |
Nem | — | Új név |
email |
string |
Nem | — | Új e-mail-cím |
age |
integer |
Nem | — | Új életkor |
gender |
string |
Nem | — | Új nem |
location |
string |
Nem | — | Új lakóhely |
external_id |
string |
Nem | — | Új külső azonosító |
source_system |
string |
Nem | — | Új forrásrendszer |
preferred_language |
string |
Nem | — | Új preferált nyelv; hagyja el a tárolt érték megtartásához, küldjön null értéket a törléséhez |
custom_attributes |
object |
Nem | — | Új egyéni attribútumok (a meglévőket lecseréli) |
Visszatérési érték: a módosított válaszadóobjektum. Ha nem történt változás: { message: "No changes detected", respondent: {...} }.
delete_respondent
Szekció neve “delete_respondent”Válaszadó eltávolítása.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
respondent_id |
string |
Igen | — | A válaszadó UUID-ja |
Visszatérési érték: { deleted: true, respondent_id, respondent_info: { name, email, external_id, source_system } }
bulk_create_respondents
Szekció neve “bulk_create_respondents”Több válaszadó létrehozása valószerű, kitalált demográfiai adatokkal. Csak tesztadatokhoz – éles adatokhoz ne használja.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
count |
integer |
Igen | — | A létrehozandó válaszadók száma (1–100) |
project_id |
string |
Nem | — | Projektazonosító |
name_prefix |
string |
Nem | "Test" |
Az előállított nevek előtagja |
source_system |
string |
Nem | "bulk_generate" |
A forrásrendszer neve |
generate_demographics |
boolean |
Nem | true |
Valószerű demográfiai adatok előállítása a Faker segítségével |
preferred_language |
string |
Nem | — | Egyetlen preferált nyelv minden létrehozott válaszadónak |
Visszatérési érték:
{ "created": 50, "project_id": "...", "source_system": "bulk_generate", "respondents": [ ]}Előállított demográfiai adatok
Szekció neve “Előállított demográfiai adatok”Ha a generate_demographics értéke true (alapértelmezés), a Faker a következőket állítja elő:
| Mező | Előállítás módja |
|---|---|
name |
faker.name() |
email |
faker.email() |
age |
Véletlen egész szám 18 és 75 között |
gender |
Véletlenszerűen: "male", "female" vagy "other" |
location |
"{city}, {country}" |
external_id |
"bulk-{random_hex}" |
Ha a generate_demographics értéke false, az eszköz sorszámozott neveket ("Test Respondent 1") és e-mail-címeket állít elő, demográfiai adatok nélkül.
generate_survey_access_token
Szekció neve “generate_survey_access_token”Belépésilink-token előállítása, amellyel a válaszadó hitelesítés nélkül érheti el a kérdőívét.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
survey_id |
string |
Igen | — | A kitöltés UUID-ja |
respondent_id |
string |
Igen | — | A válaszadó UUID-ja (egyeznie kell a kitöltés válaszadójával) |
expiration_hours |
integer |
Nem | 168 |
A token lejáratáig hátralévő órák száma (alapértelmezés: 7 nap) |
Visszatérési érték:
{ "token": "...", "survey_url": "https://sirway.dev.askalot.io/s/{token}", "survey_id": "...", "respondent_id": "...", "expiration_hours": 168}Ha a kitöltés kampánya kínálja az MI-asszisztenst, az eredmény a connector_url mezőt is tartalmazza, a válaszadói összekötő címét (https://portor.<tenant>.askalot.io/respond/mcp), így egy kézzel továbbított meghívó mindkét belépési módot megnevezheti. Magát a párosítókódot ez az eszköz soha nem adja vissza: a válaszadó a saját kérdőívoldaláról kapja meg. Lásd: MI-támogatott önkitöltés.
send_survey_invitation
Szekció neve “send_survey_invitation”Belépési linket tartalmazó kérdőív-meghívó e-mail küldése egy válaszadónak. Valódi e-mailt küld.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
survey_id |
string |
Igen | — | A kitöltés UUID-ja |
respondent_id |
string |
Igen | — | A válaszadó UUID-ja (egyeznie kell a kitöltés válaszadójával) |
expiration_hours |
integer |
Nem | 168 |
A link lejáratáig hátralévő órák száma (alapértelmezés: 7 nap) |
subject |
string |
Nem | — | Egyéni e-mail-tárgy. Alapértelmezés: "You're invited to complete: {questionnaire_name}" |
body_template |
string |
Nem | — | Egyéni levéltörzs a következő helyőrzőkkel: {name}, {url}, {expiration}, {questionnaire} |
Visszatérési érték:
{ "status": "sent", "survey_id": "...", "respondent_id": "...", "survey_url": "https://sirway.dev.askalot.io/s/{token}", "message_id": "...", "message_bus_used": true}Az e-mail a kitöltés nyelvén készül: a már kiválasztott nyelven, ennek hiányában a válaszadó preferált nyelvén, ha a kampány teljes fordítást kínál rajta, különben a kérdőív forrásnyelvén. Az egyéni subject és body_template szövegét a rendszer változtatás nélkül küldi el.
Ha a kitöltés kampánya kínálja az MI-asszisztenst, az e-mail egy bekezdéssel bővül, amely közli a válaszadóval, hogy megnyithatja a linket, és választhatja, hogy a kérdőívet a saját MI-asszisztensével tölti ki; az eredmény ilyenkor a connector_url mezőt is tartalmazza.
bulk_delete_respondents
Szekció neve “bulk_delete_respondents”Több válaszadó törlése szűrési feltételek alapján. Kétlépéses munkafolyamatot használ: először hívja meg dry_run=true értékkel a törlendők előnézetéhez, majd hívja meg újra dry_run=false értékkel a végrehajtáshoz.
A véletlen tömeges törlés megelőzésére legalább egy szűrőt meg kell adni.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
source_system |
string |
Nem | — | Szűrés forrásrendszer szerint (pl. "bulk_generate", "mcp_review") |
project_id |
string |
Nem | — | Szűrés projektazonosító szerint |
orphans_only |
boolean |
Nem | false |
Csak a projekt nélküli válaszadókat célozza (más szűrőkkel kombinálható) |
dry_run |
boolean |
Nem | true |
Előnézeti mód – törlés nélkül visszaadja a darabszámot és egy mintát |
Próbafuttatás válasza:
{ "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."}Végrehajtás válasza: { dry_run: false, deleted: 50 }
Hibakezelés
Szekció neve “Hibakezelés”Gyakori hibák
Szekció neve “Gyakori hibák”| Helyzet | Válasz |
|---|---|
| A válaszadó nem található | {"error": "Respondent {id} not found"} |
| A kitöltés nem található | {"error": "Survey {id} not found"} |
| Eltérő válaszadó | {"error": "Respondent is not the respondent for this survey"} |
| Nincs e-mail-cím | {"error": "Respondent has no email address"} |
| Leiratkozott | {"error": "Respondent has opted out of notifications"} |
| Sikertelen e-mail-küldés | {"error": "Failed to send email: {details}"} |
A tömeges létrehozás korlátai
Szekció neve “A tömeges létrehozás korlátai”| Helyzet | Válasz |
|---|---|
| A darabszám meghaladja a 100-at | {"error": "Maximum 100 respondents per request"} |
| A darabszám 1-nél kisebb | {"error": "Count must be at least 1"} |