A teljes MCP-eszközkatalógus, a paraméterekkel és visszatérési értékekkel.
Az MCP szerver 29 eszközt biztosít. Az alábbiak mind az élő tool schemákból generálódnak server/mcp-tools.ts — ami az egyetlen hiteles forrás — a npm run gen:mcp-docs. Egy CI-ellenőrzés elbuktatja a buildet, ha egy eszköz megváltozik, és ez az oldal nincs újragenerálva, így nem térhet el a valóságtól.
| Eszköz | Mit csinál |
|---|---|
| whoami | Megmutatja, melyik OptiMonk fiókként működik ez a kapcsolat, és mit engedélyez számára. Ezt hívd meg elsőként, ha egy eszköz not-found vagy scope hibát ad vissza — ugyanúgy néz ki, függetlenül attól, hogy a hitelesítő adat rossz fiókra mutat, vagy az objektum valóban hiányzik. |
| build_popup | Elindít egy popup buildet egy nyilvánosan elérhető referenciakép URL alapján. Egy runId-t ad vissza, amely egyben érvényes jobId is: hívd meg a watch_job eszközt, hogy megvárd, amíg a job terminal állapotba kerül, vagy használd a get_job-ot egyszeri lekéréshez, illetve amikor a kliens nem tud nyitva tartani egy kérést. |
| get_popup_html | Lekéri egy elkészült build HTML-jét. Előtte várj a watch_job segítségével (a runId egyben érvényes jobId is); használd a get_job-ot egyszeri lekéréshez, vagy amikor a kliens nem tud nyitva tartani egy kérést. |
| get_popup_preview | MEGNÉZHETED egy elkészült build eredményét: szerveroldalon renderelt képernyőképek valódi böngésző-arányokban — desktop (1440×900) és mobil (390×844) —, image content blokkokként visszaadva. A get_popup_html a markupot adja vissza; ez pedig a képet. |
| edit_popup | Természetes nyelvű szerkesztést alkalmaz egy elkészült buildre. queued állapotot ad vissza egy jobId-vel; hívd meg a watch_job-ot ezzel a jobId-vel, majd a get_popup_html-t. Használd a get_job-ot egyszeri lekéréshez, vagy amikor a kliens nem tud nyitva tartani egy kérést. |
| upload_reference_image | Feltölt egy base64 kódolású képet nyilvános tárhelyre; a visszaadott publicUrl-t használd a build_popup referenceUrl paramétereként. |
| get_design_thread | Beolvas egy design threadet: a sorba rendezett eseménynaplót, a levezetett állapotot (designing / variant_picked / campaign_live) és az aktuális koncepciókártyákat az előnézeti képeikkel együtt. A campaign_live azt jelenti, hogy létezik egy kampány (inaktívan jön létre); a state.published pedig azt mutatja, hogy publikálva és bekapcsolva lett-e. Egyszeri lekérés; a folyamat megvárásához használd a watch_design_thread-et, sose pollozz ciklusban. Ahhoz, hogy megjelenítsd a kártyákat a felhasználó számára választásra, használd a get_concept_board-ot. |
| get_concept_board | MEGNÉZHETED egy design thread koncepciókártyáit: ez az eredmény CSATOLJA a képeket — egy 2×2-es táblát, amelyre rá van rendezve minden kártya betűje és neve, plusz egy-egy miniatűrt minden kártyához, tábla-sorrendben. Mutasd meg a felhasználónak a csatolt tábla-képet (vagy a csatolt miniatűröket) pontosan úgy, ahogy visszaérkeztek; sose hotlinkeld az imageUrl/mockupUrl-t HTML-en, widgeteken vagy artifactokon belül (a sandboxok blokkolják a cross-origin képeket, és a felhasználó törött csempéket lát) — ezek az URL-ek csak böngészőben megnyitásra szolgálnak. A kép alatt sorold fel minden betűt a nevével, majd tegyél fel EGY kérdést: melyik betűt választja? A select_variant-ot csak azután hívd meg, hogy a felhasználó választott. A get_design_thread ugyanazokat a kártyákat adja vissza adatként. |
| start_design_thread | Megnyit egy új design threadet egy brief alapján (például: „egy welcome popup az earfun.hu számára 10%-os kedvezménnyel”). Visszaadja a session id-t; az agent ezután felderítő kérdéseket tesz fel, és koncepciókat generál — hívd meg a watch_design_thread-et, hogy megvárd a következő kérdést vagy a koncepciókártyákat (sose alkalmazz sleep-et vagy pollozást), és a send_design_message-t a válaszadáshoz. |
| get_coupon | Beolvassa a build által kiosztott kupont: hogy a popupnak van-e egyáltalán coupon eleme, a tárolt specifikációt, és minden jelenleg benne lévő fixed kódot. Ezt hívd meg, mielőtt kupont javasolnál — egy üres codes lista azt jelenti, hogy a popup egy üres kuponmezőt publikálna. |
| list_campaigns | Felsorolja a fiókhoz tartozó kampányokat (a legújabbal kezdve). |
| get_campaign | Lekér egy kampányt runId és/vagy campaignId alapján (legalább egy megadása kötelező). |
| create_campaign | Létrehoz egy Piszkozat kampányt egy elkészült buildből (nincs publikálás). Design-session által támogatott buildet igényel: a start_design_thread létrehoz ilyet, míg egy önálló build_popup futás nem. A 'livePreview' mezőt adja vissza (egy megosztható nyilvános előnézeti linket és egy bejelentkezett app linket) — mindkettőt add meg a felhasználónak a záró üzenetedben, a 'summary'-ből származó targeting összefoglalóval együtt. |
| set_campaign_name | Átnevez egy kampányt. |
| publish_campaign | Publikál egy kampányt az OptiMonkba, és aktiválja azt. A 'livePreview' mezőt adja vissza (egy megosztható nyilvános előnézeti linket és egy bejelentkezett app linket) — mindkettőt add meg a felhasználónak a záró üzenetedben, egy targeting összefoglalóval együtt. |
| get_campaign_settings | Beolvassa egy build jelenlegi megjelenítési beállításait (triggerek, targeting, gyakoriság, overlay) és egy ember által is olvasható összefoglalót róluk. |
| set_campaign_settings | Elmenti egy build megjelenítési beállításait (triggerek, targeting, gyakoriság, overlay) egy egységként; ha még nem létezik kampány, létrehozza a kampány beállítási piszkozatát. |
| prepare_animated_background | Elindítja egy design animált hátterének generálását, még mielőtt megkérdeznék a kereskedőt, hogy szeretné-e. Kb. 40 másodpercet vesz igénybe. Biztonságosan hívható újra: ha egy második hívás történik, míg egy már fut, vagy egy olyan designon, amelynek már van válasza, nem indít el semmit, és megmondja, melyik eset áll fenn. Sok design szándékosan nem jogosult — egy egyszínű háttérnek nincs mit animálni —, és ez egy normális válasz, nem hiba. Add meg a wait paramétert, hogy a végleges eredményt kapd meg, ne pedig a feladás pillanatában térjen vissza. |
| set_animated_background | Rögzíti, hogy ez a design az animált hátterét használja-e, vagy statikus marad. Az animated választásához szükséges, hogy a designhoz valóban tartozzon egy klip — a prepare_animated_background készít egyet, és sok design szándékosan nem jogosult rá. A válasz egy újratöltés után is megmarad. Megjegyzés: a buildek jelenleg statikusak — a design journey már nem kínál animációt, és az elkészült popup nem hordozza a klipet; a rögzített válasz egy későbbi kampányoldal-funkció számára marad megőrizve. |
| set_coupon | Rögzíti a kupont egy buildben, UTÁNA, hogy a kereskedő elfogadta: megírja a specifikációt, átírja a fixed kódot a popupban, és rögzíti a megállapodást a design threaden. Előbb javasold a kupont a beszélgetésben — ez az eszköz a jóváhagyást végzi, nem a javaslattételt. |
| get_job | Beolvassa egy hosszan futó job státuszát a jobId alapján — legyen az egy build, vagy egy sorba állított design thread-módosítás. A terminal megmondja, hogy fog-e még önmagától történni valami. Egy selected státuszú build job egy olyan design, amit kiválasztottak, de sosem építettek meg: semmi nem fut, és a select_variant indítja el a buildet. Amíg várakozol, inkább a watch_job-ot használd; ezt egyszeri lekéréshez használd, vagy amikor a kliens nem tud nyitva tartani egy kérést. |
| watch_job | Megvárja, hogy egy hosszan futó job befejeződjön, pollozás helyett. Futás közben progress értesítéseket küld (ha a klienstől érkezik egy progressToken), és visszaadja a végleges státuszt. Azonnal visszatér, ha a job már befejeződött. Timeout esetén timedOut státusszal tér vissza, az eddigi állapottal együtt — hívd meg újra, hogy tovább várj. progressToken nélkül a hívás csendben marad, amíg vissza nem tér, ezért tartsd a timeoutSeconds értékét a kliensed tool call-okra vonatkozó idle timeout-ja alatt (ez gyakran 300 s); az alapérték már ennek megfelel. |
| set_plan_coupon | Rögzíti a kupont a PLAN-en, még mielőtt bármilyen popup elkészült volna — ez a kampánylétrehozási folyamat kupon lépése. Ezt akkor használd, amikor a kereskedő még a designt választja; ha már létezik popup, a set_coupon magába a buildbe ír. Előbb javasold a kupont a beszélgetésben: ez az eszköz a megállapodást rögzíti, nem a javaslattételt végzi. |
| regenerate_animated_background | Megváltoztatja, hogyan MOZOG egy elkészült popup animált háttere („lassabban”, „a gőz balra sodródjon”, „álljon meg a víz mozgása”). Egy olyan elkészült popup szükséges, amelynek MÁR VAN animált háttere — a klipet regenerálja, nem tud újat hozzáadni. Kb. egy percet vesz igénybe: rögtön válaszol egy jobId-vel, kövesd figyelemmel a watch_job-bal, és olvasd ki a result.body-ból az új klip url-jét és mozgását. Az új klip mentésig piszkozat marad. |
| patch_popup | Szerkeszt egy elkészült popupot a változás szöveges leírásával ("legyen nagyobb a headline", "cseréld ki a gomb színét"). Rögtön válaszol egy jobId-vel; kövesd figyelemmel a watch_job-bal, majd olvasd ki a szerkesztett html-t a befejezett job eredményéből (result.body.html). Hagyd ki a html paramétert, ha a popup jelenlegi dokumentumát szeretnéd szerkeszteni. Ehelyett használd az edit_popup-ot egy beszélgetés alapú áttervezéshez a design threaden keresztül. |
| send_design_message | Elküld egy üzenetet egy design threadnek. Amíg a thread még a scoping fázisban van, ez VÁLASZOL az agent felderítő kérdésére; ha már léteznek kártyák, finomítja a koncepciótáblát; select_variant után pedig a kiválasztott popupot szerkeszti. Állítsd be a newVariant paramétert, ha inkább egy újabb koncepciókört akarsz indítani; a newVariantFrom opcionálisan egy kiválasztott futáshoz kötheti azt. Egyébként a szerver a thread állapota alapján irányítja tovább. Ezután várj a watch_design_thread-del, ha az üzenet a táblára került (routedTo: board), vagy a watch_job-bal a visszaadott jobId-n, ha egy futásra került — sose alkalmazz sleep-et vagy pollozást a get_design_thread-del a hívások között. (A variáns kiválasztása nem üzenettel történik — használd a select_variant-ot.) |
| restore_revision | Visszaállít egy korábbi verziót a popupból egy design threaden. A verziót nevezd meg revisionId-vel, vagy kérj stepsBack-et (1 = az előző verzió). A visszaállítás sorba állított design-módosításként fut, és egy figyelendő jobId-vel válaszol; az élő kampány nem változik, amíg nem publikálod újra. |
| select_variant | Kiválaszt egy vagy több koncepciókártyát, és popupokká ÉPÍTI azokat — ez az agent Build it funkciója. Ez A döntés, amely leszűkíti a threadet: ezután a send_design_message a kiválasztott popupot szerkeszti, nem a táblát. A build a háttérben indul el, és a draft kampány rögtön létrejön: figyeld a visszaadott jobId-t a watch_job-bal, majd egyezz meg a targetingről a get_campaign_settings / set_campaign_settings segítségével, és publikálj a publish_campaign-nel. Ez a hívás kb. 40 másodpercen belül válaszol, még akkor is, ha a build még csak most indul — a 'pending: true' egy null campaignId-vel pontosan ezt jelenti, ezért figyeld a jobId-t, és röviddel utána olvasd ki a kampányt a get_design_thread-ből; sose válassz újra csak azért, mert egy hívás lassúnak tűnt, és ha egyszer mégis timeout lép fel, ismételd meg ugyanazokkal az id-kkal, ne válassz újra, mivel egy ismétlés ugyanazokat a futásokat adja vissza, és soha nem épít kétszer. Adj meg több id-t egy A/B páros esetén — mindig a TELJES kiválasztást ugyanabban a sorrendben, mivel egy olyan hívás, amely hozzáad egy korábbi választáshoz, újra átveszi az ismételt kártyákat, helyette nem használja fel újra a futásaikat. |
| watch_design_thread | Megvárja, hogy egy design threadnek szüksége legyen rád, pollozás helyett: visszatér, amikor az agent felderítő kérdést tesz fel, amikor a koncepciókártyák és a mockupjaik mind elkészültek, amikor a thread véget ér, vagy timeout esetén (ekkor hívd meg újra). Azonnal visszatér, ha ezek közül már valamelyik fennáll. Sose alkalmazz sleep-et vagy pollozást a get_design_thread-del a hívások között. |
Eszközök részletei
Paraméterek, alapértékek, enumok és visszatérési mezők minden eszközhöz:
whoami
0 paraméter
Megmutatja, melyik OptiMonk fiókként működik ez a kapcsolat, és mit engedélyez számára. Ezt hívd meg elsőként, ha egy eszköz not-found vagy scope hibát ad vissza — ugyanúgy néz ki, függetlenül attól, hogy a hitelesítő adat rossz fiókra mutat, vagy az objektum valóban hiányzik.
Visszatérési érték accountId loginId via credential scopes canPublish
build_popup
5 paraméter
Elindít egy popup buildet egy nyilvánosan elérhető referenciakép URL alapján. Egy runId-t ad vissza, amely egyben érvényes jobId is: hívd meg a watch_job eszközt, hogy megvárd, amíg a job terminal állapotba kerül, vagy használd a get_job-ot egyszeri lekéréshez, illetve amikor a kliens nem tud nyitva tartani egy kérést.
referenceUrl string, kötelező
A popup nyilvánosan lekérhető PNG/JPG/WEBP képe, amelyet újra kell alkotni
domain string, kötelező
A célbolt hostneve, például shop.com
userPrompt string, opcionális
formatHint enum, opcionális
card fullscreen
idempotencyKey string, opcionális
Adj meg egy állandó id-t, hogy az újrapróbálkozások biztonságosak legyenek: egy második hívás ugyanazzal a kulccsal az első hívás runId-jét adja vissza, helyette nem indít el (és nem számláz fel) egy másik buildet.
Visszatérési érték runId shortId status replayed note
get_popup_html
2 paraméter
Lekéri egy elkészült build HTML-jét. Előtte várj a watch_job segítségével (a runId egyben érvényes jobId is); használd a get_job-ot egyszeri lekéréshez, vagy amikor a kliens nem tud nyitva tartani egy kérést.
runId string, kötelező
viewport enum, opcionális, alapérték: desktop
desktop mobile
Visszatérési érték html viewport
get_popup_preview
2 paraméter
MEGNÉZHETED egy elkészült build eredményét: szerveroldalon renderelt képernyőképek valódi böngésző-arányokban — desktop (1440×900) és mobil (390×844) —, image content blokkokként visszaadva. A get_popup_html a markupot adja vissza; ez pedig a képet.
runId string, kötelező
viewport enum, opcionális, alapérték: both
both desktop mobile
Mely viewport(ok)ról készüljön kép. Mindegyik saját image blokként érkezik vissza.
Visszatérési érték runId images missing
edit_popup
4 paraméter
Természetes nyelvű szerkesztést alkalmaz egy elkészült buildre. queued állapotot ad vissza egy jobId-vel; hívd meg a watch_job-ot ezzel a jobId-vel, majd a get_popup_html-t. Használd a get_job-ot egyszeri lekéréshez, vagy amikor a kliens nem tud nyitva tartani egy kérést.
runId string, kötelező
message string, kötelező
Mit kell megváltoztatni, például: 'legyen piros a headline' (legfeljebb 2000 karakter)
viewport enum, opcionális, alapérték: desktop
desktop mobile
imageUrls array, opcionális
Legfeljebb 8 nyilvános referenciakép URL
Visszatérési érték runId jobId status note
upload_reference_image
2 paraméter
Feltölt egy base64 kódolású képet nyilvános tárhelyre; a visszaadott publicUrl-t használd a build_popup referenceUrl paramétereként.
imageBase64 string, kötelező
Base64 kódolású kép bájtok (data: prefix nélkül)
contentType enum, kötelező
image/png image/jpeg image/webp
Visszatérési érték publicUrl storageKey
get_design_thread
1 paraméter
Beolvas egy design threadet: a sorba rendezett eseménynaplót, a levezetett állapotot (designing / variant_picked / campaign_live) és az aktuális koncepciókártyákat az előnézeti képeikkel együtt. A campaign_live azt jelenti, hogy létezik egy kampány (inaktívan jön létre); a state.published pedig azt mutatja, hogy publikálva és bekapcsolva lett-e. Egyszeri lekérés; a folyamat megvárásához használd a watch_design_thread-et, sose pollozz ciklusban. Ahhoz, hogy megjelenítsd a kártyákat a felhasználó számára választásra, használd a get_concept_board-ot.
sessionId string, kötelező
Design session id
Visszatérési érték sessionId domain status state legacy events concepts
get_concept_board
1 paraméter
MEGNÉZHETED egy design thread koncepciókártyáit: ez az eredmény CSATOLJA a képeket — egy 2×2-es táblát, amelyre rá van rendezve minden kártya betűje és neve, plusz egy-egy miniatűrt minden kártyához, tábla-sorrendben.
Mutasd meg a felhasználónak a csatolt tábla-képet (vagy a csatolt miniatűröket) pontosan úgy, ahogy visszaérkeztek; sose hotlinkeld az imageUrl/mockupUrl-t HTML-en, widgeteken vagy artifactokon belül (a sandboxok blokkolják a cross-origin képeket, és a felhasználó törött csempéket lát) — ezek az URL-ek csak böngészőben megnyitásra szolgálnak. A kép alatt sorold fel minden betűt a nevével, majd tegyél fel EGY kérdést: melyik betűt választja?
A select_variant-ot csak azután hívd meg, hogy a felhasználó választott. A get_design_thread ugyanazokat a kártyákat adja vissza adatként.
sessionId string, kötelező
Design session id
Visszatérési érték sessionId cells next
start_design_thread
1 paraméter
Megnyit egy új design threadet egy brief alapján (például: „egy welcome popup az earfun.hu számára 10%-os kedvezménnyel”). Visszaadja a session id-t; az agent ezután felderítő kérdéseket tesz fel, és koncepciókat generál — hívd meg a watch_design_thread-et, hogy megvárd a következő kérdést vagy a koncepciókártyákat (sose alkalmazz sleep-et vagy pollozást), és a send_design_message-t a válaszadáshoz.
text string, kötelező
A brief: milyen popup szükséges, melyik boltnak
Visszatérési érték sessionId shortId next
get_coupon
1 paraméter
Beolvassa a build által kiosztott kupont: hogy a popupnak van-e egyáltalán coupon eleme, a tárolt specifikációt, és minden jelenleg benne lévő fixed kódot. Ezt hívd meg, mielőtt kupont javasolnál — egy üres codes lista azt jelenti, hogy a popup egy üres kuponmezőt publikálna.
runId string, kötelező
A build runId-je
Visszatérési érték runId hasCouponElement spec summary codes emptyCodeSlots contractIssues
list_campaigns
1 paraméter
Felsorolja a fiókhoz tartozó kampányokat (a legújabbal kezdve).
limit number, opcionális, alapérték: 20
Visszatérési érték campaigns nextCursor
get_campaign
2 paraméter
Lekér egy kampányt runId és/vagy campaignId alapján (legalább egy megadása kötelező).
runId string, opcionális
campaignId string, opcionális
Visszatérési érték id name status domain v3RunId omCampaignId livePreview next
create_campaign
2 paraméter
Létrehoz egy Piszkozat kampányt egy elkészült buildből (nincs publikálás). Design-session által támogatott buildet igényel: a start_design_thread létrehoz ilyet, míg egy önálló build_popup futás nem. A 'livePreview' mezőt adja vissza (egy megosztható nyilvános előnézeti linket és egy bejelentkezett app linket) — mindkettőt add meg a felhasználónak a záró üzenetedben, a 'summary'-ből származó targeting összefoglalóval együtt.
runId string, kötelező
Egy elkészült build runId-je
domain string, opcionális
Csak egy domain_not_on_account elutasítás után: a kereskedő saját domainje, amely alá a kampányt be kell sorolni, az elutasításban megnevezett listából
Visszatérési érték id name status campaign summary livePreview next
set_campaign_name
2 paraméter
Átnevez egy kampányt.
campaignId string, kötelező
name string, kötelező
Visszatérési érték name
publish_campaign
1 paraméter
Publikál egy kampányt az OptiMonkba, és aktiválja azt. A 'livePreview' mezőt adja vissza (egy megosztható nyilvános előnézeti linket és egy bejelentkezett app linket) — mindkettőt add meg a felhasználónak a záró üzenetedben, egy targeting összefoglalóval együtt.
campaignId string, kötelező
A publikálandó kampány, id alapján
Visszatérési érték campaignId omCampaignId omVariantId databaseId propagating ssrPreviewUrl activation redirect livePreview next
get_campaign_settings
2 paraméter
Beolvassa egy build jelenlegi megjelenítési beállításait (triggerek, targeting, gyakoriság, overlay) és egy ember által is olvasható összefoglalót róluk.
runId string, opcionális
Az a build, amelynek beállításait olvasni szeretnéd (ezt VAGY a campaignId-t add meg)
campaignId string, opcionális
Az a kampány, amelynek beállításait olvasni szeretnéd (ezt VAGY a runId-t add meg)
Visszatérési érték campaignId settings summary livePreview next
set_campaign_settings
12 paraméter
Elmenti egy build megjelenítési beállításait (triggerek, targeting, gyakoriság, overlay) egy egységként; ha még nem létezik kampány, létrehozza a kampány beállítási piszkozatát.
runId string, opcionális
Az a build, amelynek beállításait el akarod menteni (ezt VAGY a campaignId-t add meg)
campaignId string, opcionális
Az a kampány, amelynek beállításait el akarod menteni (ezt VAGY a runId-t add meg)
trigger enum, kötelező
timed exitIntent scrollDown inactivity click javascriptEvent omPassthrough
Mi nyitja meg a popupot — az alábbi delay/scroll mezők ehhez a választáshoz kapcsolódnak
timedDelaySec number, opcionális
Hány másodpercet kell várni, csak timed vagy inactivity trigger esetén (alapérték: 5)
scrollPercent number, opcionális
Milyen mértékben lefelé az oldalon, csak scrollDown trigger esetén (alapérték: 50)
where enum, kötelező
all homepage urlContains
Mely oldalakon jelenhet meg a popup
urlContains string, opcionális
Az egyeztetendő URL-részlet, csak where: "urlContains" esetén (alapérték: "")
triggers array, opcionális
targeting array, opcionális
frequency object, opcionális
overlay object, opcionális
meta object, opcionális
Visszatérési érték campaignId settings summary livePreview next
prepare_animated_background
3 paraméter
Elindítja egy design animált hátterének generálását, még mielőtt megkérdeznék a kereskedőt, hogy szeretné-e. Kb. 40 másodpercet vesz igénybe. Biztonságosan hívható újra: ha egy második hívás történik, míg egy már fut, vagy egy olyan designon, amelynek már van válasza, nem indít el semmit, és megmondja, melyik eset áll fenn. Sok design szándékosan nem jogosult — egy egyszínű háttérnek nincs mit animálni —, és ez egy normális válasz, nem hiba. Add meg a wait paramétert, hogy a végleges eredményt kapd meg, ne pedig a feladás pillanatában térjen vissza.
sessionId string, kötelező
Az a design thread, amelyhez a koncepció tartozik
conceptId string, kötelező
Az a design, amelynek hátterét animálni kell
wait boolean, opcionális
Tartsd nyitva a hívást, amíg a klip véglegesül (kb. 40 másodperc), helyette ne térjen vissza rögtön, amint a munka lefoglalásra kerül
Visszatérési érték sessionId conceptId outcome pending
set_animated_background
4 paraméter
Rögzíti, hogy ez a design az animált hátterét használja-e, vagy statikus marad. Az animated választásához szükséges, hogy a designhoz valóban tartozzon egy klip — a prepare_animated_background készít egyet, és sok design szándékosan nem jogosult rá. A válasz egy újratöltés után is megmarad. Megjegyzés: a buildek jelenleg statikusak — a design journey már nem kínál animációt, és az elkészült popup nem hordozza a klipet; a rögzített válasz egy későbbi kampányoldal-funkció számára marad megőrizve.
sessionId string, kötelező
Az a design thread, amelyhez a koncepció tartozik
conceptId string, kötelező
Az a design, amelyre a válasz vonatkozik
choice enum, kötelező
static animated
animated = a generált klip legyen a háttér · static = maradjon az álló kép
version number, opcionális
A mockup verzió, amelyre ez a válasz vonatkozik. Hagyd ki, hacsak nem verziókat követsz nyomon; egy eltérés esetén a rendszer elutasítja, nem tárolja el a rossz képhez rendelve.
Visszatérési érték sessionId conceptId choice
set_coupon
9 paraméter
Rögzíti a kupont egy buildben, UTÁNA, hogy a kereskedő elfogadta: megírja a specifikációt, átírja a fixed kódot a popupban, és rögzíti a megállapodást a design threaden. Előbb javasold a kupont a beszélgetésben — ez az eszköz a jóváhagyást végzi, nem a javaslattételt.
runId string, kötelező
A build runId-je
type enum, kötelező
fixed unique shopify_automatic
fixed = egy kód, amelyet mindenki lát (a fixedCode szükséges hozzá) · unique = kódok a kampányhoz feltöltött készletből · shopify_automatic = a Shopify generál kódot minden látogatóhoz (az automatic szükséges hozzá)
fallbackAction enum, opcionális
hide text
unique/shopify_automatic esetén: mi történjen, ha nincs elérhető kód. Alapértelmezett: hide.
fallbackCoupon string, opcionális
A megjelenő szöveg, ha a fallbackAction értéke text
autoRedeem boolean, opcionális
Shopify boltok esetén: a kód automatikus alkalmazása a checkoutnál
automatic object, opcionális
Kötelező shopify_automatic esetén
fixedCode string, opcionális
A megjelenítendő kód, type=fixed esetén. Kötelező, kivéve ha a popup már rendelkezik eggyel.
couponIndex number, opcionális
Írj EGY kuponhelyre (a get_coupon codes listájának indexe). Hagyd ki, ha minden helyet be akarsz állítani.
fixedCodeChanges array, opcionális
Több kuponhelyet ír egyszerre: egy {couponIndex, code} páros minden helyhez. A fixedCode/couponIndex helyett használd, sose azokkal együtt.
Visszatérési érték runId ok draft summary codes omPublished omPublishError contractIssues savedCodes
get_job
1 paraméter
Beolvassa egy hosszan futó job státuszát a jobId alapján — legyen az egy build, vagy egy sorba állított design thread-módosítás. A terminal megmondja, hogy fog-e még önmagától történni valami. Egy selected státuszú build job egy olyan design, amit kiválasztottak, de sosem építettek meg: semmi nem fut, és a select_variant indítja el a buildet. Amíg várakozol, inkább a watch_job-ot használd; ezt egyszeri lekéréshez használd, vagy amikor a kliens nem tud nyitva tartani egy kérést.
jobId string, kötelező
A hosszú munkát elindító parancs jobId-je (vagy egy önálló runId a build_popup-ból)
Visszatérési érték jobId kind status terminal sourceStatus error runId threadId hasHtml result
watch_job
2 paraméter
Megvárja, hogy egy hosszan futó job befejeződjön, pollozás helyett. Futás közben progress értesítéseket küld (ha a klienstől érkezik egy progressToken), és visszaadja a végleges státuszt. Azonnal visszatér, ha a job már befejeződött. Timeout esetén timedOut státusszal tér vissza, az eddigi állapottal együtt — hívd meg újra, hogy tovább várj. progressToken nélkül a hívás csendben marad, amíg vissza nem tér, ezért tartsd a timeoutSeconds értékét a kliensed tool call-okra vonatkozó idle timeout-ja alatt (ez gyakran 300 s); az alapérték már ennek megfelel.
jobId string, kötelező
A hosszú munkát elindító parancs jobId-je (vagy egy önálló runId a build_popup-ból)
timeoutSeconds number, opcionális
Mennyi ideig várjon, mielőtt feladja, és jelenti az eddigi státuszt (alapérték: 240, max: 900).
Visszatérési érték jobId kind status terminal sourceStatus error runId threadId hasHtml result timedOut
set_plan_coupon
7 paraméter
Rögzíti a kupont a PLAN-en, még mielőtt bármilyen popup elkészült volna — ez a kampánylétrehozási folyamat kupon lépése. Ezt akkor használd, amikor a kereskedő még a designt választja; ha már létezik popup, a set_coupon magába a buildbe ír. Előbb javasold a kupont a beszélgetésben: ez az eszköz a megállapodást rögzíti, nem a javaslattételt végzi.
sessionId string, kötelező
Az a design thread, amelynek a plan-jéhez a kupon tartozik
type enum, kötelező
fixed unique shopify_automatic
fixed = egy kód, amelyet mindenki lát (a fixedCode szükséges hozzá) · unique = kódok a kampányhoz feltöltött készletből · shopify_automatic = a Shopify generál kódot minden látogatóhoz (az automatic szükséges hozzá)
fallbackAction enum, opcionális
hide text
unique/shopify_automatic esetén: mi történjen, ha nincs elérhető kód. Alapértelmezett: hide.
fallbackCoupon string, opcionális
A megjelenő szöveg, ha a fallbackAction értéke text
autoRedeem boolean, opcionális
Shopify boltok esetén: a kód automatikus alkalmazása a checkoutnál
automatic object, opcionális
Kötelező shopify_automatic esetén
fixedCode string, opcionális
A megjelenítendő kód, type=fixed esetén
Visszatérési érték sessionId coupon fixedCode agreedBy at
regenerate_animated_background
2 paraméter
Megváltoztatja, hogyan MOZOG egy elkészült popup animált háttere („lassabban”, „a gőz balra sodródjon”, „álljon meg a víz mozgása”). Egy olyan elkészült popup szükséges, amelynek MÁR VAN animált háttere — a klipet regenerálja, nem tud újat hozzáadni. Kb. egy percet vesz igénybe: rögtön válaszol egy jobId-vel, kövesd figyelemmel a watch_job-bal, és olvasd ki a result.body-ból az új klip url-jét és mozgását. Az új klip mentésig piszkozat marad.
runId string, kötelező
A build (run) id, amelynek animált hátterét regenerálni kell
instruction string, kötelező
Mi mozogjon másképp, egyszerű szavakkal leírva
Visszatérési érték runId jobId
patch_popup
12 paraméter
Szerkeszt egy elkészült popupot a változás szöveges leírásával ("legyen nagyobb a headline", "cseréld ki a gomb színét"). Rögtön válaszol egy jobId-vel; kövesd figyelemmel a watch_job-bal, majd olvasd ki a szerkesztett html-t a befejezett job eredményéből (result.body.html). Hagyd ki a html paramétert, ha a popup jelenlegi dokumentumát szeretnéd szerkeszteni. Ehelyett használd az edit_popup-ot egy beszélgetés alapú áttervezéshez a design threaden keresztül.
viewport enum, kötelező
desktop mobile
Melyik dokumentumot kell szerkeszteni: desktop vagy mobile
html string, opcionális
A szerkesztendő dokumentum. Hagyd ki, ha a futás jelenlegi html-jét szeretnéd szerkeszteni az adott viewporthoz
instruction string, kötelező
Mit kell megváltoztatni, egyszerű szavakkal leírva
selectedIds array, opcionális
Opcionális data-v3id azonosítók, amelyek meghatározott elemekre korlátozzák a szerkesztést
overlaySelected boolean, opcionális
Igaz, ha a hívó a kampány overlay/backdrop elemét választotta ki, nem pedig egy elemet
mode enum, opcionális
fast full
fast (alapértelmezett) egy célzott javításhoz, full a dokumentum teljes újraépítéséhez
omStep number, opcionális
Több oldalas popupok esetén: az 1-től induló oldalszám, amelyre az utasítás vonatkozik
history array, opcionális
A popupról szóló legutóbbi felhasználó/agent üzenetváltások, a legrégebbivel kezdve, hogy egy követő kérés feloldható legyen
skipSettingsGate boolean, opcionális
Kihagyja a campaign-settings szándékellenőrzést (egy már jóváhagyott utasítás újraküldéséhez)
measuredFeedback string, opcionális
Mit mért egy korábbi próbálkozás a kéréshez viszonyítva, egy méretre vonatkozó második próbálkozáshoz
runId string, kötelező
A build (run) id, amelynek popupját szerkeszteni kell
requestId string, opcionális
Opcionális idempotencia-kulcs: ugyanaz a kulcs ugyanazon a futáson ugyanazt a jobot adja vissza
Visszatérési érték runId jobId replayed
send_design_message
7 paraméter
Elküld egy üzenetet egy design threadnek. Amíg a thread még a scoping fázisban van, ez VÁLASZOL az agent felderítő kérdésére; ha már léteznek kártyák, finomítja a koncepciótáblát; select_variant után pedig a kiválasztott popupot szerkeszti. Állítsd be a newVariant paramétert, ha inkább egy újabb koncepciókört akarsz indítani; a newVariantFrom opcionálisan egy kiválasztott futáshoz kötheti azt. Egyébként a szerver a thread állapota alapján irányítja tovább.
Ezután várj a watch_design_thread-del, ha az üzenet a táblára került (routedTo: board), vagy a watch_job-bal a visszaadott jobId-n, ha egy futásra került — sose alkalmazz sleep-et vagy pollozást a get_design_thread-del a hívások között. (A variáns kiválasztása nem üzenettel történik — használd a select_variant-ot.)
sessionId string, kötelező
Design session id
message string, kötelező
Mit kell megváltoztatni, egyszerű nyelven leírva
imageUrls array, opcionális
Opcionális referenciaképek ehhez az üzenethez (nyilvános URL-ek vagy app-relatív referenciák), legfeljebb 8
viewport enum, opcionális
desktop mobile
Melyik viewportra vonatkozik a változás, ha már ki van választva egy variáns
answers object, opcionális
Opcionális, strukturált válaszok egy clarify kártyára: kérdés id (a get_design_thread-ben található agent_message questions payloadból) → a választott válasz. A 'message' mezőben lévő szöveg önmagában is beolvasásra kerül, de csak akkor, ha pontosan megnevezi az egyik felkínált opciót; minden más esetben a kártya válasz nélkül marad.
newVariant boolean, opcionális
Egy új koncepciókört indít el a kiválasztott popup szerkesztése helyett
newVariantFrom string, opcionális
Opcionális, kiválasztott futás, amelyet az új variáns horgonyaként lehet használni
Visszatérési érték sessionId jobId routedTo runId state
restore_revision
3 paraméter
Visszaállít egy korábbi verziót a popupból egy design threaden. A verziót nevezd meg revisionId-vel, vagy kérj stepsBack-et (1 = az előző verzió). A visszaállítás sorba állított design-módosításként fut, és egy figyelendő jobId-vel válaszol; az élő kampány nem változik, amíg nem publikálod újra.
sessionId string, kötelező
A design thread id
revisionId string, opcionális
Egy revisionId egy korábbi edit_applied eseményből vagy egy verziólistából
stepsBack number, opcionális
Hány verziót kell visszalépni a jelenlegihez képest; 1 = az előző verzió
Visszatérési érték sessionId runId jobId targetRevisionId targetRevisionNumber
select_variant
3 paraméter
Kiválaszt egy vagy több koncepciókártyát, és popupokká ÉPÍTI azokat — ez az agent Build it funkciója. Ez A döntés, amely leszűkíti a threadet: ezután a send_design_message a kiválasztott popupot szerkeszti, nem a táblát. A build a háttérben indul el, és a draft kampány rögtön létrejön: figyeld a visszaadott jobId-t a watch_job-bal, majd egyezz meg a targetingről a get_campaign_settings / set_campaign_settings segítségével, és publikálj a publish_campaign-nel.
Ez a hívás kb. 40 másodpercen belül válaszol, még akkor is, ha a build még csak most indul — a 'pending: true' egy null campaignId-vel pontosan ezt jelenti, ezért figyeld a jobId-t, és röviddel utána olvasd ki a kampányt a get_design_thread-ből; sose válassz újra csak azért, mert egy hívás lassúnak tűnt, és ha egyszer mégis timeout lép fel, ismételd meg ugyanazokkal az id-kkal, ne válassz újra, mivel egy ismétlés ugyanazokat a futásokat adja vissza, és soha nem épít kétszer.
Adj meg több id-t egy A/B páros esetén — mindig a TELJES kiválasztást ugyanabban a sorrendben, mivel egy olyan hívás, amely hozzáad egy korábbi választáshoz, újra átveszi az ismételt kártyákat, helyette nem használja fel újra a futásaikat.
sessionId string, kötelező
Design session id
conceptIds array, kötelező
A koncepciókártya id-k teljes kiválasztása a get_design_thread-ből; egynél több elem A/B tesztet indít
domain string, opcionális
Csak egy domain_not_on_account elutasítás után: a kereskedő saját domainje, amely alá a kampányt be kell sorolni, az elutasításban megnevezett listából
Visszatérési érték sessionId runId runIds campaignId jobId pending state next
watch_design_thread
2 paraméter
Megvárja, hogy egy design threadnek szüksége legyen rád, pollozás helyett: visszatér, amikor az agent felderítő kérdést tesz fel, amikor a koncepciókártyák és a mockupjaik mind elkészültek, amikor a thread véget ér, vagy timeout esetén (ekkor hívd meg újra). Azonnal visszatér, ha ezek közül már valamelyik fennáll. Sose alkalmazz sleep-et vagy pollozást a get_design_thread-del a hívások között.
sessionId string, kötelező
Design session id, a start_design_thread-ből
timeoutSeconds number, opcionális
Mennyi ideig várjon, mielőtt "timeout" okkal visszatér (alapérték: 240, max: 900).
Visszatérési érték sessionId status state reason question concepts timedOut next