# MCP-eszközök referenciája az OptiMonk szerverhez

Canonical URL: https://support.optimonk.com/hu/articles/mcp-tool-reference

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`