Tovább a tartalomhoz
Tudástár

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.

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 }


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 }.


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.

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

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: {...} }.


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


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": [
{"id": "...", "name": "John Smith", "email": "[email protected]", "project_id": "..."}
]
}

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.


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.


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": "...",
"email": "[email protected]",
"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.


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 }


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