Tovább a tartalomhoz
Tudástár

Kampányeszközök – MCP-eszközreferencia

A kampányeszközök a kérdőíves kampányok életciklusát kezelik: kampányok létrehozása, kérdezők és válaszadói körök hozzárendelése, a munkaterhelés elosztása és a meghívók kiküldése. Sok művelet kötegelt válaszmintát használ added/skipped/reasons mezőkkel.

Az összes kampány listázása, igény szerint projekt, név vagy állapot szerint szűrve.

Paraméter Típus Kötelező Alapértelmezés Leírás
project_id string Nem — Szűrés projektazonosító szerint
name string Nem — Szűrés kampánynév szerint
status string Nem — Szűrés állapot szerint
limit integer Nem 100 A visszaadott találatok legnagyobb száma

Visszatérési érték: { items: [...], count, limit }


Kampány lekérése azonosító alapján.

Paraméter Típus Kötelező Alapértelmezés Leírás
campaign_id string Igen — A kampány UUID-ja

Visszatérési érték: kampányobjektum vagy { error }. Tartalmazza az offered_languages mezőt: azokat a nyelveket, amelyek közül a válaszadók választhatnak – elsőként a kérdőív forrásnyelvét, majd a rögzített verzió minden teljes fordítását, mindegyiket { locale, name, human_edited } formában. A rögzített verzió nélküli kampány csak a forrásnyelvet kínálja.


Új kampány létrehozása. A kampány módja automatikusan dől el aszerint, hogy rendeltek-e hozzá kérdezőket.

Paraméter Típus Kötelező Alapértelmezés Leírás
name string Igen — A kampány megjelenített neve
project_id string Igen — A szülőprojekt azonosítója
questionnaire_id string Igen — A használandó kérdőív
status string Nem "draft" Kezdeti állapot: draft, active vagy scheduled. Minden más értéket elutasít
admits_volunteers boolean Igen — Részt vehetnek-e olyanok, akik a húzáskor nem kerültek be a kampány válaszadói körébe (a magától jelentkező önkéntesek, a nyitott link). Nincs alapértéke: adja meg.
offers_ai_channel boolean Igen — Kitölthetik-e a válaszadók a kérdőívet a saját MI-asszisztensükben is. Nincs alapértéke: adja meg.
intro_text string Ha az offers_ai_channel értéke true — Ki gyűjti az adatokat és miért; szó szerint jelenik meg az első kérdés előtt
consent_text string Ha az offers_ai_channel értéke true — Mibe egyezik bele a válaszadó; szó szerint jelenik meg, és mindig egy rögzített bekezdés követi az MI-szolgáltatóról

Visszatérési érték: a létrehozott kampányobjektum.

Az update_campaign a status értékét csak a kampány életciklusa mentén változtatja: draft → active vagy scheduled; scheduled → active vagy draft; active → paused, completed vagy aborted; paused → active, completed vagy aborted; completed vagy aborted → draft. Minden más átmenetet, illetve ismeretlen állapotot elutasít, és semmit sem változtat.

Az update_campaign az offers_ai_channel, az intro_text és a consent_text értéket is fogadja; mindegyik opcionális, és ha elhagyja, a tárolt kampány értéke marad érvényben. A szövegeket a módosítás utáni állapoton ellenőrzi: ha olyan kampánynál kapcsolja be az asszisztenst, amely már mindkét szöveget tartalmazza, nem kell újra megadnia őket, ha viszont kiüríti valamelyik szöveget, miközben a kampány felkínálja az asszisztenst, a rendszer elutasítja a kérést. Az asszisztens kikapcsolása minden még fel nem használt párosítókódot érvénytelenít; a már csatlakozott válaszadók befejezhetik a kitöltést.


Kérdezők (kérdező szerepkörű felhasználók) felvétele egy kampányba. A kötegelt válaszmintát használja.

Paraméter Típus Kötelező Alapértelmezés Leírás
campaign_id string Igen — A kampány UUID-ja
user_ids string[] Igen — A kérdezőként felveendő felhasználók azonosítóinak listája

Visszatérési érték:

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

Kihagyási okok: "User not found", "No interviewer role".


Kérdezők eltávolítása egy kampányból.

Paraméter Típus Kötelező Alapértelmezés Leírás
campaign_id string Igen — A kampány UUID-ja
user_ids string[] Igen — Az eltávolítandó felhasználók azonosítóinak listája

Visszatérési érték:

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

A kampányhoz rendelt kérdőív módosítása.

Paraméter Típus Kötelező Alapértelmezés Leírás
campaign_id string Igen — A kampány UUID-ja
questionnaire_id string Igen — Az új kérdőív UUID-ja

Visszatérési érték:

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

Adott válaszadók hozzárendelése egy adott kérdezőhöz egy kampányon belül, a munkaterhelés elosztása céljából.

Paraméter Típus Kötelező Alapértelmezés Leírás
campaign_id string Igen — A kampány UUID-ja
interviewer_id string Igen — A kérdező felhasználó UUID-ja
respondent_ids string[] Igen — A hozzárendelendő válaszadók azonosítóinak listája

Visszatérési érték:

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

Válaszadók eltávolítása egy kérdező hozzárendelései közül. A válaszadók a kampány válaszadói körében maradnak, de már nem tartoznak kérdezőhöz.

Paraméter Típus Kötelező Alapértelmezés Leírás
campaign_id string Igen — A kampány UUID-ja
interviewer_id string Igen — A kérdező felhasználó UUID-ja
respondent_ids string[] Igen — A hozzárendelésből eltávolítandó válaszadók azonosítóinak listája

Visszatérési érték:

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

Egy adott kérdező munkaterhelésének lekérése egy kampányban – a hozzárendelt válaszadók és a kitöltések állapota.

Paraméter Típus Kötelező Alapértelmezés Leírás
campaign_id string Igen — A kampány UUID-ja
interviewer_id string Igen — A kérdező felhasználó UUID-ja

Visszatérési érték:

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

Egy kampány azon válaszadóinak lekérése, akiket még egyetlen kérdezőhöz sem rendeltek hozzá.

Paraméter Típus Kötelező Alapértelmezés Leírás
campaign_id string Igen — A kampány UUID-ja

Visszatérési érték:

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

Válaszadói kör hozzárendelése egy kampányhoz. Összekapcsolja a válaszadói kört a kampánnyal, hogy a bulk_create_surveys a válaszadói kör minden válaszadójához kitöltést hozhasson létre.

Paraméter Típus Kötelező Alapértelmezés Leírás
campaign_id string Igen — A kampány UUID-ja
pool_id string Igen — A válaszadói kör UUID-ja

Visszatérési érték:

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

A kampányhoz rendelt válaszadói kör lekérése.

Paraméter Típus Kötelező Alapértelmezés Leírás
campaign_id string Igen — A kampány UUID-ja

Visszatérési érték (van hozzárendelt válaszadói kör):

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

Visszatérési érték (nincs válaszadói kör): { campaign_id, pool_id: null, has_pool: false, message: "..." }


Kérdőíves meghívó e-mailek küldése a kampány válaszadóinak. Valódi e-maileket küld belépési linkkel.

Paraméter Típus Kötelező Alapértelmezés Leírás
campaign_id string Igen — A kampány UUID-ja
respondent_ids string[] Nem — A meghívandó konkrét válaszadók
send_to_all_uninvited boolean Nem false Küldés minden még meg nem hívott válaszadónak

Minden meghívó a címzettje nyelvén készül: a válaszadó preferált nyelvén, ha a kampány azon a nyelven teljes fordítást kínál, egyébként a kérdőív forrásnyelvén.

Visszatérési érték:

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

Ha a kampány felkínálja az MI-asszisztenst, minden meghívó e-mail kiegészül egy bekezdéssel, amely a válaszadót a kérdőívoldalán található MI-lehetőségre irányítja, és minden sent bejegyzés tartalmazza a connector_url mezőt is, a válaszadói összekötő címét.

A meghívhatóság feltételei válaszadónként:

  • Rendelkeznie kell e-mail-címmel
  • A notification_preference értéke nem lehet "none"
  • A kitöltés nem lehet már befejezett vagy folyamatban lévő
  • A kampánynak be kell fogadnia. Olyan személyt, aki a húzáskor nem került be a válaszadói körébe, a kampány csak akkor hívhat meg, ha fogad önkénteseket, és éppen adatot gyűjt – ugyanez a kapu vonatkozik a magától jelentkező önkéntesekre is. A rendszer a kitöltésüket ekkor önkéntesként, nem pedig a mintába húzott esetként rögzíti, így az adatkészletben továbbra is megkülönböztethető a kettő.

Kihagyási okok: "Respondent not found", "No email address", "Opted out of notifications", "Survey already completed", "Survey already in_progress", valamint egy elutasítás, amely megnevezi, hogy a befogadási kapu melyik fele mondott nemet – a kampány nem fogad önkénteseket, vagy éppen nem gyűjt adatot.


A fenti lépéssorok közül kettő egyetlen hívásként is elérhető. Ezek nem rövidítések, amelyek bármit is átugranának: minden lépés ugyanaz az ezen az oldalon dokumentált eszköz, így ugyanazokat a rekordokat írja, ugyanazok az auditesemények keletkeznek, és minden elutasítás, amelyet egy nyers eszköz adna, itt is változatlanul megjelenik – kiegészítve a stopped_at_step mezővel, amely megnevezi, melyik lépésnél állt le a lánc. A rendszer semmit sem von vissza, így a félúton megálló lánc megtartja, amit a korábbi lépések felépítettek, és Ön az egyes eszközökkel folytathatja.

A lánc minden lépéshez ellenőrzi a jogosultságát, mielőtt bármit felépítene. Ha az előfizetése egy későbbi lépést nem fed le, már az elején elutasítást kap, nem pedig egy félig felépített terepmunkát.

Egy kampány teljes terepmunka-láncának futtatása: a mintavételi stratégia létrehozása, a válaszadói kör generálása, a válaszadói kör hozzárendelése a kampányhoz, a kampány által használt kérdőívverzió közzététele (és rögzítése), valamint a kitöltések létrehozása.

Paraméter Típus Kötelező Alapértelmezés Leírás
campaign_id string Igen — Az előkészítendő kampány. Már meg kell neveznie azt a kérdőívet, amellyel a terepmunkát végezni kívánja
admits_volunteers boolean Igen nincs Ennek a terepmunkának az önkéntes-befogadási szabálya, kifejezetten megadva. Nincs alapértéke, és egyeznie kell a kampány saját beállításával – ha az hibás, előbb módosítsa az update_campaign eszközzel
strategy_name string Igen — Az e futás által létrehozott mintavételi stratégia neve
target_size integer Igen — A válaszadóikör-húzás kért mérete: a húzandó válaszadók száma túlmintavételezés előtt (> 0). A húzás requested_size értékként kapja meg, és a rendszer a válaszadói körrel együtt tárolja
factors object[] Nem [] Azok a demográfiai megoszlási tényezők, amelyekhez a stratégia az illeszkedést méri
selection_algorithm string Nem "greedy" A válaszadóikör-húzás kiválasztási algoritmusa ("greedy" vagy "random_constrained")
oversample_factor number Nem 1.0 A válaszadóikör-húzás túlmintavételezési szorzója (≥ 1)
quality_metric string Nem "rmse" Az a mérőszám, amellyel a stratégia az illeszkedést értékeli: "rmse", "mae", "chi_square" vagy "max_deviation". Minden más értéket elutasít, mielőtt bármi elkészülne
require_email boolean Nem false A válaszadóikör-húzás csak e-mail-címmel rendelkező válaszadókat fogad be
pool_name string Nem — A generált válaszadói kör neve; alapértelmezés szerint a stratégia nevéből képzett címke

Az e futás által létrehozott stratégia csak a factors és a quality_metric értéket tartalmazza. A húzási beállítások (target_size, oversample_factor, selection_algorithm, require_email) a válaszadói kört létrehozó lépés kapja meg, és a rendszer a válaszadói körrel együtt tárolja őket, pontosan úgy, ahogy egy közvetlen generate_pool_from_strategy hívás is tenné.

Visszatérési érték: ready_to_invite, a strategy_id, a pool_id, a pool_respondent_count, a qml_version_id, az adott verzióhoz a válaszadók által választható offered_languages (mint a get_campaign esetén), valamint az általa létrehozott surveys_created / surveys_skipped, továbbá a next_step. Leállás esetén: stopped_at_step az elutasító lépés saját error és detail értékével, valamint mindaz, amit a korábbi lépések már felépítettek.

Miért fontos a közzétételi lépés. Egy kézzel összerakott lánc gyakran kihagyja a közzétételt, a rögzítés nélküli kampány pedig olvasáskor a kérdőív legfrissebb változatát veszi alapul – így egy terepmunka közben végzett szerkesztés észrevétlenül megváltoztatja a mérőeszközt azoknak a válaszadóknak a feje fölött, akik már válaszoltak.

Az újrafuttatás újra húz. Minden futás új stratégiát és válaszadói kört hoz létre, és a kampányt ehhez köti át (egy válaszadói kör egyszer használatos), majd az új válaszadói körön végighaladva kihagyja azokat a válaszadókat, akiknek már van kitöltésük ebben a kampányban. Egy target_size értéknél nagyobb névsor esetén a második futás ezért újonnan húzott válaszadókat ad hozzá, nem pedig bárkit lecserél.


A kampány kitöltéseinek létrehozása, majd szintetikus válaszok generálása hozzájuk. Az egyes megoszlási módok és perszónaprofilok működését a mass_fill_surveys leírása ismerteti.

Paraméter Típus Kötelező Alapértelmezés Leírás
campaign_id string Igen — Az a kampány, amelynek a kitöltéseit az eszköz létrehozza, majd válaszokkal feltölti
distribution string Nem "realistic" "realistic", "random" vagy "llm"
max_surveys integer Nem — A kampány legfeljebb ennyi kitöltését tölti fel válaszokkal
profiles string[] Nem ["random"] A válaszadók között körforgásban kiosztott perszónanevek
concurrency integer Nem 1 A kitöltés belső ciklusának párhuzamossága

Visszatérési érték: surveys_created / surveys_skipped, valamint a kitöltési feladat task_id azonosítója status: "pending" értékkel. Pontosan úgy kérdezze le a get_task_status eszközzel, mint egy mass_fill_surveys futást. Leállás esetén: stopped_at_step az elutasító lépés error és detail értékével, valamint task_id: null.


Helyzet Válasz
A kampány nem található {"error": "Campaign {id} not found"}
A kérdező nincs a kampányban {"error": "Interviewer {id} is not assigned to this campaign"}
Nincs kérdőív/válaszadói kör {"error": "Campaign has no questionnaire assigned"}

A legtöbb azonosítólistát fogadó kampányeszköz strukturált eredményt ad vissza, és nem hiúsul meg egy-egy elem miatt:

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

Ez a minta a következőkre vonatkozik: add_interviewers_to_campaign, remove_interviewers_from_campaign, assign_respondents_to_interviewer, unassign_respondents_from_interviewer és send_campaign_invitations.

Minden kihagyott vagy sikertelen elem tartalmaz egy reason mezőt, amely megmagyarázza, miért maradt ki a műveletből.