A REST API

Minden, amit az Antimatter-alkalmazások végeznek, ugyanazon HTTP API-n keresztül történik, így a szkriptjeid is ugyanígy használhatják. Ez az oldal elmagyarázza, hogyan hitelesítsd a kéréseidet, melyek a leggyakrabban használt erőforrások, hogyan néznek ki a válaszok és a hibák, valamint hogyan követheted az eseményeket élőben a WebSocket-en keresztül.

Alapok

• Alap URL: https://chat.example.com/api/v4. Az alábbi végpontok mind ehhez viszonyítva vannak megadva.
• Formátum: bemenet és kimenet is JSON, kivéve a fájlfeltöltéseket (multipart). Küldd a Content-Type: application/json fejlécet.
• Azonosítók: minden objektum rendelkezik egy 26 karakteres id-val. Az idők a Unix-epoch óta eltelt milliszekundumokban vannak megadva (create_at, update_at, delete_at; a 0 azt jelenti, hogy „nem törölve”).
• A közösségek csapatok: az API teams néven hivatkozik rájuk, team_id azonosítóval.
• Önmagad: bárhová, ahol a útvonal egy user_id-t vár, a me a bejelentkezett felhasználót jelenti, ahogy a GET /users/me példában is.

A végpontok teljes listája a szerver kódjában található: az útvonalakat a server/channels/api4/*.go mappában, a típusokat pedig a server/public/model mappában deklarálják. A repozitóriumban az api/v4/source mappában található OpenAPI-leírás a Mattermosttól örökölt végpontokat, valamint az Antimatter néhány kiegészítését (üzenetszálak áthelyezése, modellkapcsolatok és üzenetműveletek) is lefedi. A többi végpont csak a kódban érhető el.

Hitelesítés

Minden kéréshez, a bejelentkezéssel és néhány nyilvános végponttal kivéve, token szükséges az Authorization fejlécben:

curl -H "Authorization: Bearer $TOKEN" https://chat.example.com/api/v4/users/me

Háromféle token fogadott el itt: személyes hozzáférési tokenek, munkamenet-tokenek és OAuth-hozzáférési tokenek. Az Authorization: Token … formátum is elfogadott. A lekérdezési paraméterben (?access_token=) megadott tokenek csak OAuth-hozzáférési tokenek esetén érvényesek.

Személyes hozzáférési tokenek (ajánlott szkriptekhez)

A személyes hozzáférési token a neked cselekszik, nem jár le, hacsak nem adsz meg lejárati dátumot, és bármikor visszavonható. A személyes hozzáférési tokenek alapértelmezés szerint le vannak tiltva:

1. Egy rendszeradminisztrátor engedélyezi a Személyes hozzáférési tokenek engedélyezése beállítást a Rendszerkonzol › Integrációk › Integrációkezelés menüben (ServiceSettings.EnableUserAccessTokens, AM_SERVICESETTINGS_ENABLEUSERACCESSTOKENS).
2. Minden olyan felhasználó számára, aki tokeneket hozhat létre, a rendszeradminisztrátor megnyitja a Rendszerkonzol › Felhasználókezelés › Felhasználók menüpontot, a felhasználó menüjében kiválasztja a Szerepkörök kezelése lehetőséget, és bejelöli az Engedélyezze, hogy ez a fiók személyes hozzáférési tokeneket generáljon opciót. A rendszeradminisztrátorok mindig létrehozhatnak tokeneket.
3. A felhasználó megnyitja a profilját a jobb felső sarokban, majd a Profil és beállítások › Biztonság menüpontot. A Személyes hozzáférési tokenek alatt leírja, mire használja a tokenet, és kiválasztja a Token létrehozása gombot. A token csak egyszer jelenik meg: másolja le.

API-n keresztül: POST /users/{user_id}/tokens a következő testtel: {"description": "backup script", "expires_at": 0} (az expires_at milliszekundumban van megadva; 0 esetén nincs lejárati idő). A válasz token mezője a titok; a id mezővel lehet visszavonni (POST /users/tokens/revoke a {"token_id": "…"} testtel). Parancssorból: amctl token generate <user> <description>.

A rendszeradminisztrátor korlátozhatja a tokenek élettartamát a Személyes hozzáférési token maximális élettartama (nap) beállítással a Rendszerkonzol ugyanazon az oldalon.

Munkamenet-tokenek

A jelszóval történő bejelentkezés egy munkamenet-tokent ad vissza a Token válaszfejlécben, ugyanolyan típusú munkamenetet, amelyet az alkalmazások is használnak:

curl -i -X POST https://chat.example.com/api/v4/users/login \
  -H 'Content-Type: application/json' \
  -d '{"login_id": "maya", "password": "…"}'

Többfaktoros hitelesítéssel rendelkező fiókhoz adjon meg "token": "123456" értéket. A munkamenetek a szerver munkamenet-beállításai szerint járnak le, a bejelentkezési végpont pedig sebességkorlátozott (5 kérés per másodperc). A POST /users/logout lezárja a munkamenetet.

OAuth 2.0 alkalmazások

Ha azt szeretné, hogy a felhasználók Antimatter-fiókjukkal jelentkezzenek be az Ön alkalmazásába, regisztráljon egy OAuth 2.0 alkalmazást. Ekkor az Antimatter lesz az OAuth-szolgáltató:

1. Az OAuth 2.0 szolgáltató engedélyezése beállításnak bekapcsolva kell lennie (Rendszerkonzol › Integrációk › Integrációkezelés, ServiceSettings.EnableOAuthServiceProvider, alapértelmezetten bekapcsolva).
2. Aki jogosultsággal rendelkezik az OAuth-alkalmazások kezeléséhez (alapértelmezetten a rendszeradminisztrátorok), megnyitja a profilját, majd a Integrációk › OAuth 2.0 alkalmazások menüpontot, és hozzáadja az alkalmazást a visszahívási URL-jeivel. Ilyen módon kap egy kliensazonosítót (client ID) és egy kliens titkot (client secret).
3. Az alkalmazásod a felhasználókat a https://chat.example.com/oauth/authorize címre irányítja, a response_type=code, client_id, redirect_uri és state paraméterekkel. A code_challenge_method=S256 értékű PKCE támogatott.
4. A kódot a POST https://chat.example.com/oauth/access_token végponton cseréli be (először grant_type=authorization_code, majd refresh_token megújításához), és a Authorization: Bearer <access token> fejléccel hívja meg a API-t.

A felhasználók a Profil és beállítások › Biztonság › Engedélyezett alkalmazások menüben láthatják az engedélyezett alkalmazásaikat.

Fő erőforrások

Üzenet küldése

curl -X POST https://chat.example.com/api/v4/posts \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"channel_id": "'$CHANNEL_ID'", "message": "Backup finished: **42 GB** in 3 min"}'

Az üzenetek Markdown formátumúak. Üzenetszálban való válaszhoz add meg a "root_id" (a szál első bejegyzése) értékét, fájlokhoz a "file_ids", csatolmányokhoz és egyéb kiegészítőkhöz a "props" mezőt (lásd: Csatolmányok).

Csatorna-azonosító keresése

curl -H "Authorization: Bearer $TOKEN" \
  https://chat.example.com/api/v4/teams/name/lumen-labs/channels/name/ops-alerts

A nevek a csatorna hivatkozásában szereplők: /lumen-labs/channels/ops-alerts.

Lapozás

A listázó végpontok a page (0-tól) és per_page (alapértelmezés szerint 60, maximum 200) paramétereket fogadják el. Kérdezd tovább a következő lapokat, amíg egy lap rövidebb nem lesz, mint a per_page értéke.

A csatorna üzenetei (GET /channels/{channel_id}/posts) szintén elfogadnak since (időpont: minden, ami azóta változott), vagy before és after (bejegyzés-azonosító) paramétert. Válaszként bejegyzéslistát kapunk: {"order": [IDs, newest first], "posts": {ID: post}, "next_post_id", "prev_post_id"}.

Hibák

A hibák a szokásos HTTP-státuszkódokat használják (400 hibás bemenet, 401 nem bejelentkezve, 403 nem engedélyezett, 404 nem található, 501 funkció kikapcsolva), JSON-testtel:

{
  "id": "api.context.permissions.app_error",
  "message": "You do not have the appropriate permissions.",
  "detailed_error": "",
  "request_id": "jz8zm5nunpbt8f3gpqsz5dq6so",
  "status_code": 403
}

A kódban a id értékét használd: a message a felhasználó nyelvén van lefordítva. A detailed_error csak akkor nem üres, ha a szerver fejlesztői módban fut (ServiceSettings.EnableDeveloper). A szerver adminisztrátorának idézd a request_id értékét: ez szerepel a naplóban.

Kérésekre vonatkozó korlátok

A sebességkorlátozás alapértelmezetten kikapcsolva van. Amikor a rendszeradminisztrátor bekapcsolja (Rendszerkonzol › Környezet › Sebességkorlátozás), minden kliens alapértelmezetten másodpercenként 10 kérést kap, 100-as burst-tel, IP-cím vagy felhasználó alapján számolva. A válaszok tartalmazzák az X-RateLimit-Limit, X-RateLimit-Remaining és X-RateLimit-Reset fejléceket; a limit túllépése esetén a szerver 429 státuszkóddal válaszol, másodpercben megadott Retry-After fejlécet tartalmazva. Egyes végpontok, például a bejelentkezés, saját limittel rendelkeznek, függetlenül a beállításoktól.

Írj olyan szkripteket, amelyek 429 esetén várakoznak és újrapróbálkoznak, és kerüljük a pollinget: a WebSocketet kövesd.

A WebSocket-eseményfolyam

Csatlakozz a wss://chat.example.com/api/v4/websocket címre. A hitelesítés vagy a Authorization: Bearer fejléc használatával történik a csatlakozási kérésben, vagy az első üzenetként küldd el ezt:

{"seq": 1, "action": "authentication_challenge", "data": {"token": "…"}}

A szerver egy hello eseményt küld, majd mindenhez, amit látni engedélyeztek, egy-egy eseményt:

{
  "event": "posted",
  "data": {"channel_id": "…", "channel_type": "O", "post": "{\"id\":\"…\",\"message\":\"Hello\",…}"},
  "broadcast": {"channel_id": "…", "team_id": "", "user_id": "", "omit_users": null},
  "seq": 4
}

Megjegyzés: a data.post a bejegyzés JSON-sztringként. Gyakori események: posted, post_edited, post_deleted, reaction_added, reaction_removed, typing, status_change, user_added, direct_added. Az alkalmazások saját eseményeket küldenek, custom_<app id>_<event> néven.

Akkciókat is küldhetsz, mindegyik növekvő seq értékkel: user_typing {"channel_id", "parent_id"} paraméterekkel, vagy get_statuses. Ha a kapcsolat megszakad, csatlakozz újra, és a since paraméterrel (lásd Lapozás) szerezd be, amit elhagytál.

Az Antimatter hozzáadja az alábbi eseményeket: community_attributes_updated, member_timeouts_updated, post_put_on_top, post_removed_from_top, server_categories_updated, channel_overrides_updated és category_overrides_updated.

Klienskönyvtárak

• Mehet: a model.Client4 a server/public/model mappában (import: github.com/mattermost/mattermost/server/public/model). Először a model.NewAPIv4Client(url), majd a client.SetToken(token); a model.NewWebSocketClient4(wsURL, token) követi az eseményeket. Az Antimatter saját másolata módszereket ad hozzá a saját végpontjaihoz, például UpdateMessageRequest, PutPostOnTop és ExportChannel.
• TypeScript: a @mattermost/client Client4 osztálya a webapp/platform/client könyvtárban, a típusok a webapp/platform/types könyvtárban. Az Antimatter repozitóriumban lévő másolat tartalmazza az Antimatter végpontjait; a Mattermost által npm-en publikált csomag nem.

package main

import (
	"context"
	"log"

	"github.com/mattermost/mattermost/server/public/model"
)

func main() {
	client := model.NewAPIv4Client("https://chat.example.com")
	client.SetToken("…")
	post, _, err := client.CreatePost(context.Background(), &model.Post{
		ChannelId: "…",
		Message:   "Hello from Go",
	})
	if err != nil {
		log.Fatal(err)
	}
	log.Println("posted", post.Id)
}

Az Antimatter által a API-hoz hozzáadott elemek

Ezek a végpontok és mezők nem léteznek egy Mattermost szerveren. Mindegyikükhöz munkamenet szükséges.

Új mezők

• Közösségek (Team, és PUT /teams/{team_id}/patch): all_channels_membership (mindenki tagja minden csatornának, amelyet láthat), default_channel_id (ahová az újonnan csatlakozók kerülnek; ha üres, akkor a General csatorna), kind (community vagy workplace: workplace esetén a csatorna-adminisztrátorok archíválhatják a saját csatornáikat is; az új közösségek a szerver TeamSettings.DefaultCommunityKind értékét kapják, alapértelmezetten community), member_list_view (hogy a taglista hogyan csoportosítja a tagokat: choice, az alapértelmezés, lehetővé teszi, hogy minden tag maga válassza; roles vagy teams rögzíti a csoportosítást), hide_role_colors, require_team_badges, onboarding és autolinks (mindkettő JSON-sztring).
• Új közösség alapértelmezett csatornája a general (General), nem a town-square. A 0.9.0-s frissítés átnevezi minden közösség town-square csatornáját general-ra, megtartva annak azonosítóját, hacsak a közösségnek már nincs general nevű csatornája. A régi nevek továbbra is működnek: a GET /teams/{team_id}/channels/name/town-square, a GET /teams/name/{team}/channels/name/town-square és a bejövő webhook channel mezője a közösség alapértelmezett csatornáját adja vissza, ha nincs ilyen nevű csatorna. Az új kódban használja a default_channel_id-t, vagy a general nevet.
• Csatorna-hivatkozások: a #channel-name hivatkozás egy csatornát jelöl, ahogy a ~channel-name is. A bejegyzés channel_mentions tulajdonsága felsorolja mindkét módon hivatkozott csatornákat; a #word, amely nem nevez meg csatornát, hashtag marad. Az Antimatter webes felülete és mobilalkalmazása a #name formátumot használja.
• Archivált csatornák még mindig felvehetnek új tagokat (POST /channels/{channel_id}/members), akik olvashatják a korábbi üzeneteket. Senki nem közzéteszhet, nem reagálhat, nem tűzhet ki, nem emelhet üzenetet a tetejére, nem nevezheti át a csatornát, és nem módosíthatja a tagok szerepkörét.
• Belső válaszok: egy bejegyzés, amelynek "props": {"reply_to": "<post id>"} értéke, idézi a csatorna másik üzenetét. A "reply_to_mention": false hozzáadása esetén a szerző nem kap értesítést. A szerver kitölti a metadata.reply_to mezőt a hivatkozott üzenet rövid leírásával.
• Spoilerek: a "props": {"spoiler": true} elrejteti a bejegyzés szövegét és fájljait, amíg az olvasó nem dönt úgy, hogy megtekinti őket.
• Mellőzés és blokkolás beállítások: user_block kategória, a másik személy azonosítója szerint elnevezve, ignore vagy block értékkel. Hogy egy közvetlen üzenet kérésként vár-e, a csatorna-tagod notify_props.dm_request mezőjében látható (pending, accepted vagy dismissed).
• Üzenet-csatolmányok tartalmazhatnak stages és chart elemeket: lásd Kártyák.

Üzenetszál áthelyezése

A POST /posts/{post_id}/move_to_channel egy másik, ugyanahhoz a közösséghez tartozó csatornába mozgatja az üzenetszalat, annak első üzenetét és minden válaszát. A post_id lehet az első üzenet vagy bármelyik válasz.

curl -X POST https://chat.example.com/api/v4/posts/$POST_ID/move_to_channel \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"channel_id": "'$TARGET_CHANNEL_ID'", "flatten": false}'

• channel_id (kötelező): a csatorna, ahová az üzenetszál átköltözik.
• flatten (alapérték: false): ha true, a válaszok nem szálként, hanem a célcsatorna közvetlen üzenetei lesznek. A Fusion Make it a channel funkciója használja ezt.

Az üzenetek megtartják szerzőiket, időbélyeget, reakcióikat és csatolmányaikat. A másolatok a silent_notification tulajdonságot viselik, így nem küldenek értesítést senkinek. Az eredeti üzenetek törlődnek. A válasz a mozgatott első üzenet, az új azonosítóval.

Ki mozgathat üzenetszalat

• Olvashatod az üzenetszalat, és közzéteshetsz a célcsatornában.
• A csatorna adminisztrátorai, a közösség adminisztrátorai, a csatornában Üzenetek kezelése (delete_others_posts) jogosultsággal rendelkezők, valamint a rendszeradminisztrátorok bármelyik üzenetszalat mozgatják.
• Az üzenetszál szerzője akkor mozgatja, ha mindkét csatorna nyilvános, vagy ha a szál minden üzenete az őtől származik. Egyébként a válasz 403, az api.post.move_thread.private_needs_moderator.app_error azonosítóval.
• Mindkét csatornának ugyanahhoz a közösséghez kell tartoznia (közvetlen és csoportos üzenetek nem jöhetnek szóba), különbözőeknek kell lenniük, és nem lehetnek archiválva. Rendszerüzenetek és az olvasáskor törlődő üzenetek nem mozgatók.
• A WranglerSettings.MoveThreadMaxCount üzenetnél hosszabb szál (alapértelmezés szerint 100; 0 esetén nincs korlát) nem mozgatható.

A mutató és a megjegyzés

A mozgatás két system_wrangler típusú rendszerüzenetet hagy maga után: egy mutatót a régi csatornában („Egy 13 üzenetes szál átköltözött a #target csatornába”) és egy megjegyzést a célcsatornában („Ez a szál átköltözött a #source csatornából”), a mozgatott szál alatt, vagy a flatten esetén az üzenetek után. Az üzenetszöveg mellett a tulajdonságaik lehetővé teszik, hogy a kliens a csatorna nevét hivatkozásként jelenítse meg:

• A mutató: MovedThreadPermalink, NumMessages, MovedThreadChannelId, MovedThreadTeamName, MovedThreadPostId, valamint, ha a cél nyílt csatorna, MovedThreadChannelName és MovedThreadChannelDisplayName.
• A megjegyzés: MovedFromChannelId, MovedFromTeamName, MovedFromPostId (a mutató), MovedFromPermalink, valamint, ha a forrás nyílt csatorna, MovedFromChannelName és MovedFromChannelDisplayName.

Mindkettő rendelkezik TranslationID-vel. A privát csatorna neve elmarad: az olvasók „másik csatorna” feliratot látnak. A Mattermost saját POST /posts/{post_id}/move végpontja az Antimatterben nem érhető el; ehelyett ezt a végpontot használd.

Modellkapcsolatok

A modellkapcsolat egy MI-szolgáltató címe és kulcsa, amelyet egy adminisztrátor állít be. A szerver MI-funkciói és az MI-szolgáltatást hívó alkalmazások használják ezeket. A rendszeradminisztrátorok a szerver-szintű kapcsolatokat kezelik (manage_ai_connections); a közösségek adminisztrátorai a saját közösségük kapcsolatait (manage_team_ai_connections). A kulcsok csak írási módúak: egyetlen válasz sem tartalmazza őket, csak a api_key_set és a api_key_last4 mezők.

Az új kapcsolat testje:

{
  "name": "Local models",
  "scope": "server",
  "provider": "openai_compatible",
  "base_url": "http://llm.internal:8000/v1",
  "api_key": "…",
  "extra_headers": {},
  "models": {"chat": "qwen3-32b", "embeddings": "", "transcription": "", "decisions": ""},
  "limits": {"requests_per_minute": 0, "monthly_token_budget": 0, "per_user_requests_per_minute": 0, "per_user_monthly_token_budget": 0},
  "sharing": {"all_teams": true, "team_ids": []},
  "audience": {"everyone": true, "group_ids": [], "roles": [], "allow_guests": false}
}

A provider értéke openai_compatible vagy anthropic. A scope alapértelmezett értéke server; ha egy közösség azonosítója szerepel, akkor az adott közösséghez tartozó kapcsolat lesz. A limits szekcióban a 0 azt jelenti, hogy nincs korlát; a perces kérésszámot szerverenként, a token-kvótákat pedig a teljes klaszterre vonatkozóan, naptári hónap (UTC) szerint számoljuk. A sharing mező megadja, mely közösségek használhatják a szerver-szintű kapcsolatot (a közvetlen és csoportos üzenetekhez all_teams szükséges), a audience pedig azt, hogy ki férhet hozzá; vendégek csak akkor, ha be van kapcsolva a allow_guests. A módosítások a naplóba kerülnek. A beállítások részletes leírását lásd az adminisztrátori útmutatóban: AI.