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.
list_campaigns
Szekció neve “list_campaigns”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 }
get_campaign
Szekció neve “get_campaign”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.
create_campaign
Szekció neve “create_campaign”Ú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.
add_interviewers_to_campaign
Szekció neve “add_interviewers_to_campaign”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".
remove_interviewers_from_campaign
Szekció neve “remove_interviewers_from_campaign”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}update_campaign_questionnaire
Szekció neve “update_campaign_questionnaire”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"}assign_respondents_to_interviewer
Szekció neve “assign_respondents_to_interviewer”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"]}unassign_respondents_from_interviewer
Szekció neve “unassign_respondents_from_interviewer”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"]}get_interviewer_workload
Szekció neve “get_interviewer_workload”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 }}get_unassigned_respondents
Szekció neve “get_unassigned_respondents”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"} ]}assign_pool_to_campaign
Szekció neve “assign_pool_to_campaign”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}get_campaign_pool
Szekció neve “get_campaign_pool”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: "..." }
send_campaign_invitations
Szekció neve “send_campaign_invitations”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.
Láncolt eszközök
Szekció neve “Láncolt eszközök”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.
prepare_campaign_fielding
Szekció neve “prepare_campaign_fielding”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.
simulate_campaign_responses
Szekció neve “simulate_campaign_responses”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.
Hibakezelés
Szekció neve “Hibakezelés”Gyakori hibák
Szekció neve “Gyakori hibák”| 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"} |
Kötegelt műveleti minta
Szekció neve “Kötegelt műveleti minta”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.