Mergado Chat – WS konzole

Připojení

REST API Mergado ID Mergado token (PAT)

Session token WebSocket URL

Typy zpráv (protokol)

Každý rámec ze serveru má type, rostoucí seq a ts (ISO UTC). Výjimka: unauthorized jde bez seq/ts a spojení se hned zavře kódem 4401. Jedno odeslání = jeden turn_id.

Klient → server

→ user_message

Dotaz. message_id je volitelné, vrátí se v turn_start.reply_to.

{
  "type": "user_message",
  "content": "Kolik mám projektů?",
  "message_id": "c1"
}

→ stop

Přeruší běžící generování. Jinak přijde error s kódem not_generating.

{ "type": "stop" }

→ reset

Smaže historii. Během generování přijde error busy.

{ "type": "reset" }

→ ping

Keep-alive. Odpověď je pong.

{ "type": "ping" }

Server → klient

← connected

Hned po handshake. mcp.error je string, když katalog nástrojů spadl (connected: false).

{
  "type": "connected",
  "seq": 1,
  "ts": "2026-08-31T14:12:00+00:00",
  "protocol_version": "1.0",
  "session_id": "…",
  "mergado_user_id": 12345,
  "name": "Jan Novák",
  "model": "gemma4:26b[262k]",
  "expires_at": "2026-08-31T01:12:00+00:00",
  "format": "markdown",
  "mcp": {
    "url": "https://mcp.mergado.com",
    "connected": true,
    "tools": ["list_apps", "chart_create"],
    "error": null
  }
}

← turn_start

Začátek výměny. reply_to = tvoje message_id (nebo null).

{
  "type": "turn_start",
  "seq": 2,
  "ts": "…",
  "turn_id": "turn_a1b2c3d4e5f6",
  "reply_to": "c1"
}

← status

state: generating · calling_tools (+ tools[]) · retrying_tool (+ tools[]) · tools_unavailable (+ message).

{
  "type": "status",
  "seq": 3,
  "ts": "…",
  "turn_id": "turn_…",
  "state": "calling_tools",
  "tools": ["list_apps"]
}

← thinking_delta / thinking_end

Uvažování modelu (jen thinking varianty). Append text, na thinking_end blok zavři.

{ "type": "thinking_delta", "seq": 4, "ts": "…", "turn_id": "turn_…", "text": "Nejdřív zjistím…" }

{ "type": "thinking_end", "seq": 5, "ts": "…", "turn_id": "turn_…" }

← message_start

Založ prázdnou bublinu podle message_id. role je vždy assistant, format markdown.

{
  "type": "message_start",
  "seq": 6,
  "ts": "…",
  "turn_id": "turn_…",
  "message_id": "msg_…",
  "role": "assistant",
  "format": "markdown"
}

← delta

Připoj text na konec bubliny message_id. Chunky jsou markdown, jak jdou z modelu.

{
  "type": "delta",
  "seq": 7,
  "ts": "…",
  "turn_id": "turn_…",
  "message_id": "msg_…",
  "text": "Máš **"
}

← message_end

Přepiš bublinu kanonickým content a vyrenderuj markdown. finish_reason: stop · tool_calls · stopped.

{
  "type": "message_end",
  "seq": 8,
  "ts": "…",
  "turn_id": "turn_…",
  "message_id": "msg_…",
  "content": "Máš **12** projektů.",
  "finish_reason": "stop"
}

← tool_call

Model volá nástroj. arguments je objekt (prázdný {}, když JSON nešel naparsovat).

{
  "type": "tool_call",
  "seq": 9,
  "ts": "…",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "list_apps",
  "arguments": { "limit": 20 }
}

← tool_result

status: ok · error. preview je zkrácený výstup. U grafu je v artifacts jen odkaz {kind, title, message_id}, data jsou v graph_data.

{
  "type": "tool_result",
  "seq": 10,
  "ts": "…",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "list_apps",
  "status": "ok",
  "duration_ms": 142,
  "preview": "[{…}]",
  "truncated": false,
  "artifacts": []
}

← artifact · image

Screenshot. Relativní url je vůči WS službě. Vykresli url jako obrázek.

{
  "type": "artifact",
  "seq": 11,
  "ts": "…",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "web_screenshot",
  "artifact": {
    "kind": "image",
    "title": "Screenshot https://www.mergado.cz",
    "url": "/files/u20667-…/www.mergado.cz.png",
    "mime": "image/png",
    "name": "www.mergado.cz.png",
    "size": 265421
  }
}

← artifact · file

Soubor ke stažení. Nabídni odkaz url s name a size.

{
  "type": "artifact",
  "seq": 12,
  "ts": "…",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "file_create_text",
  "artifact": {
    "kind": "file",
    "title": "Export produktů",
    "url": "/files/u20667-…/export.csv",
    "mime": "text/csv",
    "name": "export.csv",
    "size": 4096
  }
}

← graph_data

Vlastní blok s message_id — zařaď ho mezi textové bubliny. graph.type: pie · bar · line. Vykreslení (D3) je věc frontendu.

{
  "type": "graph_data",
  "seq": 13,
  "ts": "…",
  "turn_id": "turn_…",
  "message_id": "msg_a5af39483f84",
  "call_id": "call_1",
  "name": "chart_create",
  "title": "Podíl objednávek",
  "graph": {
    "type": "pie",
    "title": "Podíl objednávek",
    "x_label": "",
    "y_label": "",
    "unit": "ks",
    "series": [{
      "name": "Objednávky",
      "points": [
        { "label": "Heureka", "value": 120 },
        { "label": "Zboží.cz", "value": 80 }
      ]
    }]
  }
}

← turn_end

Odemkni vstup. finish_reason: stop · stopped · error · max_iterations. usage je jen při normálním doběhnutí.

{
  "type": "turn_end",
  "seq": 14,
  "ts": "…",
  "turn_id": "turn_…",
  "finish_reason": "stop",
  "usage": {
    "prompt_tokens": 41200,
    "completion_tokens": 180,
    "total_tokens": 41380
  }
}

← error

Kódy: unauthorized · mergado_token_invalid · bad_payload · empty_message · busy · not_generating · unknown_type · llm_error (+ turn_id) · max_iterations (+ turn_id).

{
  "type": "error",
  "seq": 15,
  "ts": "…",
  "code": "busy",
  "message": "Předchozí odpověď ještě běží"
}

← pong / history_cleared

Odpověď na ping / reset. Po history_cleared vymaž konverzaci.

{ "type": "pong", "seq": 16, "ts": "…" }

{ "type": "history_cleared", "seq": 17, "ts": "…" }

Typický turn: turn_start → status(generating) → message_start → delta × N → message_end → tool_call → artifact|graph_data → tool_result → nová bublina → turn_end.

Lokální nástroje (ne MCP)

Stejná dvojice tool_call / tool_result jako u MCP. Některé navíc pošlou artifact nebo graph_data ještě před tool_result.

← mergado_help_search

Hledání v dokumentaci Mergado Help. Žádný artefakt, jen text v preview.

{
  "type": "tool_call",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "mergado_help_search",
  "arguments": { "query": "Jak nastavit Heureka feed?" }
}

{
  "type": "tool_result",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "mergado_help_search",
  "status": "ok",
  "duration_ms": 80,
  "preview": "Nalezeno 3 výsledků v Mergado Help k „Jak nastavit Heureka feed?“:\n\n1. https://help.mergado.com/cs/… (skóre 0.68)\nJak vám Mergado pomůže s inzercí na Heurece? …",
  "truncated": true,
  "artifacts": []
}

← ares_find_company_by_name

Najde firmy v ARES podle názvu. Pak se IČO dohledá přes ares_get_company_by_ico.

{
  "type": "tool_call",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "ares_find_company_by_name",
  "arguments": { "company_name": "Mergado", "limit": 25 }
}

{
  "type": "tool_result",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "ares_find_company_by_name",
  "status": "ok",
  "duration_ms": 210,
  "preview": "[{\"ico\": \"12345678\", \"obchodniJmeno\": \"MERGADO technologies s.r.o.\", \"sidlo\": \"…\"}]",
  "truncated": false,
  "artifacts": []
}

← ares_get_company_by_ico

Detail firmy z ARES. ico je osmimístné číslo.

{
  "type": "tool_call",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "ares_get_company_by_ico",
  "arguments": { "ico": "27074358" }
}

{
  "type": "tool_result",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "ares_get_company_by_ico",
  "status": "ok",
  "duration_ms": 180,
  "preview": "{\"ico\": \"27074358\", \"obchodniJmeno\": \"…\", \"sidlo\": {…}}",
  "truncated": false,
  "artifacts": []
}

← web_read_page

Otevře stránku v Chromiu a vrátí text. max_chars výchozí 20000.

{
  "type": "tool_call",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "web_read_page",
  "arguments": { "url": "https://www.mergado.cz", "max_chars": 20000 }
}

{
  "type": "tool_result",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "web_read_page",
  "status": "ok",
  "duration_ms": 1400,
  "preview": "Mergado – automatizace inzerce…",
  "truncated": true,
  "artifacts": []
}

← web_screenshot

Screenshot v prohlížeči. Před tool_result přijde artifact s kind: "image". device např. iPhone 13 Pro; bez něj desktop 1280×720.

{
  "type": "tool_call",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "web_screenshot",
  "arguments": { "url": "https://www.mergado.cz", "device": "iPhone 13 Pro", "full_page": true }
}

{
  "type": "artifact",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "web_screenshot",
  "artifact": {
    "kind": "image",
    "title": "Screenshot https://www.mergado.cz (iPhone 13 Pro)",
    "url": "/files/u20667-…/www.mergado.cz.png",
    "mime": "image/png",
    "name": "www.mergado.cz.png",
    "size": 265421
  }
}

{
  "type": "tool_result",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "web_screenshot",
  "status": "ok",
  "duration_ms": 2100,
  "preview": "Screenshot pořízen a zobrazen uživateli (259 kB, celá stránka, iPhone 13 Pro).",
  "truncated": false,
  "artifacts": [{
    "kind": "image",
    "title": "Screenshot https://www.mergado.cz (iPhone 13 Pro)",
    "url": "/files/u20667-…/www.mergado.cz.png",
    "mime": "image/png",
    "name": "www.mergado.cz.png",
    "size": 265421
  }]
}

← date_now

Aktuální datum a čas. Výchozí zóna Europe/Prague.

{
  "type": "tool_call",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "date_now",
  "arguments": { "timezone": "Europe/Prague" }
}

{
  "type": "tool_result",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "date_now",
  "status": "ok",
  "duration_ms": 2,
  "preview": "2026-08-31T18:40:00+02:00 (Europe/Prague)\nčesky: pondělí 31. srpna 2026, 18:40",
  "truncated": false,
  "artifacts": []
}

← date_shift

Posun data. Bez base počítá od teď. Kladné do budoucna, záporné do minulosti.

{
  "type": "tool_call",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "date_shift",
  "arguments": { "days": 4, "timezone": "Europe/Prague" }
}

{
  "type": "tool_result",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "date_shift",
  "status": "ok",
  "duration_ms": 2,
  "preview": "výchozí: 2026-08-31T18:40:00+02:00\nvýsledek:\n2026-09-04T18:40:00+02:00 …",
  "truncated": false,
  "artifacts": []
}

← date_diff

Rozdíl mezi dvěma daty – kalendářní i pracovní dny.

{
  "type": "tool_call",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "date_diff",
  "arguments": { "start": "2026-01-01", "end": "2026-12-24", "timezone": "Europe/Prague" }
}

{
  "type": "tool_result",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "date_diff",
  "status": "ok",
  "duration_ms": 3,
  "preview": "od 2026-01-01T00:00:00+01:00 do 2026-12-24T00:00:00+01:00\nkalendářních dnů: 357, pracovních dnů: 255",
  "truncated": false,
  "artifacts": []
}

← date_parse

Rozpozná volný zápis data. output_format: iso · cs · date_only.

{
  "type": "tool_call",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "date_parse",
  "arguments": { "text": "24. prosince 2026 18:30", "timezone": "Europe/Prague", "output_format": "iso" }
}

{
  "type": "tool_result",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "date_parse",
  "status": "ok",
  "duration_ms": 2,
  "preview": "2026-12-24T18:30:00+01:00 (Europe/Prague)\nčesky: čtvrtek 24. prosince 2026, 18:30",
  "truncated": false,
  "artifacts": []
}

← file_create_text

Soubor ke stažení. format: md · txt · csv. Před výsledkem přijde artifact s kind: "file".

{
  "type": "tool_call",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "file_create_text",
  "arguments": {
    "filename": "export-projektu",
    "format": "csv",
    "content": "id,name\n1,Shop",
    "title": "Export produktů"
  }
}

{
  "type": "artifact",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "file_create_text",
  "artifact": {
    "kind": "file",
    "title": "Export produktů",
    "url": "/files/u20667-…/export-projektu.csv",
    "mime": "text/csv; charset=utf-8",
    "name": "export-projektu.csv",
    "size": 18
  }
}

{
  "type": "tool_result",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "file_create_text",
  "status": "ok",
  "duration_ms": 12,
  "preview": "Soubor export-projektu.csv (18 B) je připravený ke stažení…",
  "truncated": false,
  "artifacts": [{
    "kind": "file",
    "title": "Export produktů",
    "url": "/files/u20667-…/export-projektu.csv",
    "mime": "text/csv; charset=utf-8",
    "name": "export-projektu.csv",
    "size": 18
  }]
}

← chart_create

Data pro graf. type: pie · bar · line. Před výsledkem přijde graph_data s vlastním message_id. Koláč = 1 řada, bez záporných hodnot.

{
  "type": "tool_call",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "chart_create",
  "arguments": {
    "type": "pie",
    "title": "Podíl objednávek",
    "unit": "ks",
    "series": [{
      "name": "Objednávky",
      "points": [
        { "label": "Heureka", "value": 120 },
        { "label": "Zboží.cz", "value": 80 }
      ]
    }]
  }
}

{
  "type": "graph_data",
  "turn_id": "turn_…",
  "message_id": "msg_a5af39483f84",
  "call_id": "call_1",
  "name": "chart_create",
  "title": "Podíl objednávek",
  "graph": {
    "type": "pie",
    "title": "Podíl objednávek",
    "x_label": "",
    "y_label": "",
    "unit": "ks",
    "series": [{
      "name": "Objednávky",
      "points": [
        { "label": "Heureka", "value": 120 },
        { "label": "Zboží.cz", "value": 80 }
      ]
    }]
  }
}

{
  "type": "tool_result",
  "turn_id": "turn_…",
  "call_id": "call_1",
  "name": "chart_create",
  "status": "ok",
  "duration_ms": 4,
  "preview": "Graf „Podíl objednávek“ (pie, 1 řad, 2 bodů) se uživateli vykreslil.",
  "truncated": false,
  "artifacts": [{ "kind": "chart", "title": "Podíl objednávek", "message_id": "msg_a5af39483f84" }]
}

Mergado Chat – WS konzole

Připojení

Konverzace

Síťová komunikace

Připojení

Konverzace manual auto reset ping

Síťová komunikace kopírovat smazat

Konverzace

Síťová komunikace