REST-API-et

Alt som Antimatter-appene gjør, går gjennom samme HTTP-API, så skriptene dine kan gjøre det samme. Denne siden forklarer hvordan du autentiserer, de ressursene du vil bruke mest, hvordan svar og feil ser ut, og hvordan du kan følge hendelser i sanntid via WebSocket.

Grunnleggende

• Grunn-URL: https://chat.example.com/api/v4. Alle endepunktene nedenfor er relative til denne.
• Format: JSON inn og ut, bortsett fra filopplasting (multipart). Send Content-Type: application/json.
• ID-er: hver objekt har en 26 tegn lang id. Tider er millisekunder siden Unix-epoken (create_at, update_at, delete_at; 0 betyr «ikke slettet»).
• Samfunn er team: API-et kaller dem teams, med en team_id.
• deg selv: der en sti tar en user_id, betyr me den innloggte brukeren, som i GET /users/me.

Den komplette listen over endepunkter finnes i serverens kode: rutene er deklarert i server/channels/api4/*.go, og typene i server/public/model. OpenAPI-beskrivelsen i mappene api/v4/source i repositoriet dekker endepunktene arvet fra Mattermost, samt noen av Antimatters tillegg: flytting av tråder, modellkoblinger og meldingshandlinger. De øvrige finnes bare i koden.

Autentisering

Hver forespørsel, bortsett fra innlogging og noen offentlige endepunkter, krever en token i Authorization-hodet:

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

Tre typer token aksepteres der: personlige tilgangstokens, sesjonstokens og OAuth-tilgangstokens. Authorization: Token … aksepteres også. Tokens i spørringsstrengen (?access_token=) aksepteres bare for OAuth-tilgangstokens.

Personlige tilgangstokens (anbefales for skript)

En personlig tilgangstoken handler som deg, utløper ikke med mindre du gir den en utløpsdato, og kan revokes når som helst. Personlige tilgangstokens er av per standard:

1. En systemadministrator aktiverer Aktiver personlige tilgangstokens i Systemkonsoll › Integrasjoner › Integrasjonsadministrasjon (ServiceSettings.EnableUserAccessTokens, AM_SERVICESETTINGS_ENABLEUSERACCESSTOKENS).
2. For hver person som kan opprette tokens, åpner en systemadministrator Systemkonsoll › Brukeradministrasjon › Brukere, velger Administrer roller i personens meny og avkrysser Tillat denne kontoen å generere personlige tilgangstokens. Systemadministratorer kan alltid opprette dem.
3. Personen åpner avataren sin øverst til høyre, deretter Profil & innstillinger › Sikkerhet. Under Personlige tilgangstokens beskriver de hva tokenet skal brukes til og velger Opprett token. Tokenet vises bare én gang: kopier det.

Med API-et: POST /users/{user_id}/tokens med {"description": "backup script", "expires_at": 0} (expires_at i millisekunder; 0 for ingen). token-feltet i svaret er hemmeligheten; id-en er det du bruker for å oppheve det (POST /users/tokens/revoke med {"token_id": "…"}). Fra kommandolinjen: amctl token generate <user> <description>.

En systemadministrator kan sette en øvre grense for levetiden til tokens med Maksimal levetid for personlige tilgangstoken (dager) på samme side i Systemkonsoll.

Sesjonstoken

Innlogging med passord returnerer et sesjonstoken i Token-responsen, samme type sesjon som appene bruker:

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

Legg til "token": "123456" for en konto med multifaktorautentisering. Sesjoner utløper som serverens sesjonsinnstillinger sier, og innloggingsendepunktet har hastighetsbegrensning (5 forespørsler per sekund). POST /users/logout avslutter sesjonen.

OAuth 2.0-apps

For å la folk logge inn i din applikasjon med deres Antimatter-konto, registrerer du en OAuth 2.0-app. Antimatter er da OAuth-leverandøren:

1. Aktiver OAuth 2.0-tjeneste-tilbyder må være på (Systemkonsoll › Integrasjoner › Integrasjonsadministrasjon, ServiceSettings.EnableOAuthServiceProvider, på som standard).
2. Noen med rett til å administrere OAuth-apper (systemadministratorer som standard) åpner avataren sin, deretter Integrasjoner › OAuth 2.0-apper, og legger til appen med callback-URL-ene. De får en klient-ID og en klienthemmelighet.
3. Programmet ditt sender brukere til https://chat.example.com/oauth/authorize med response_type=code, client_id, redirect_uri og state. PKCE med code_challenge_method=S256 støttes.
4. Det bytter ut koden ved POST https://chat.example.com/oauth/access_token (grant_type=authorization_code, deretter refresh_token for å fornye), og kaller API-et med Authorization: Bearer <access token>.

Brukere ser appene de har godkjent i Profil & innstillinger › Sikkerhet › Apper du har godkjent.

Hovedressurser

Sende en melding

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"}'

Meldinger er Markdown. Legg til "root_id" (det første innlegget i en tråd) for å svare i en tråd, "file_ids" for filer og "props" for vedlegg og andre ekstrautgaver (se Vedlegg).

Finne en kanals ID

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

Navnene er de som står i kanallinket: /lumen-labs/channels/ops-alerts.

Paginering

Liste-endepunkter tar page (fra 0) og per_page (60 som standard, maks 200). Fortsett å be om neste side inntil en side kommer tilbake som er kortere enn per_page.

Meldingene i en kanal (GET /channels/{channel_id}/posts) tar også since (et tidspunkt: alt som har endret seg siden da), eller before og after (et innlegg-ID). De returneres som en liste over innlegg: {"order": [IDs, newest first], "posts": {ID: post}, "next_post_id", "prev_post_id"}.

Feil

Feil bruker vanlige HTTP-statuskoder (400 ugyldig inndata, 401 ikke pålogget, 403 ikke tillatt, 404 ikke funnet, 501 funksjon slått av) og en JSON-kropp:

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

Bruk id i koden din: message blir oversatt til brukerens språk. detailed_error er tom med mindre serveren kjører i utviklermodus (ServiceSettings.EnableDeveloper). Angi request_id til serverens administrator: den finnes i loggene.

Hastighetsbegrensninger

Hastighetsbegrensning er slått av som standard. Når en systemadministrator slår den på (Systemkonsoll › Miljø › Hastighetsbegrensning), får hver klient 10 forespørsler per sekund med utbrudd på 100 som standard, tellt per IP-adresse eller per bruker. Svarene bærer X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-Reset; over grensen svarer serveren med 429 og en Retry-After-header i sekunder. Noen endepunkter, som pålogging, har egne grenser uavhengig av innstillingen.

Skriv skripter som venter og prøver på nytt ved 429, og unngå polling: følg WebSocket i stedet.

WebSocket-hendelsesstrømmen

Koble til wss://chat.example.com/api/v4/websocket. Autentiser enten med Authorization: Bearer-headeren i kobleforespørselen, eller ved å sende dette som den første meldingen:

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

Serveren sender en hello-hendelse, deretter en hendelse for alt du har tillatelse til å se:

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

Merk at data.post er meldingen som en JSON-streng. Vanlige hendelser: posted, post_edited, post_deleted, reaction_added, reaction_removed, typing, status_change, user_added, direct_added. Apper sender egne hendelser, navngitt custom_<app id>_<event>.

Du kan også sende handlinger, hver med en økende seq: user_typing med {"channel_id", "parent_id"}, eller get_statuses. Koble på nytt når forbindelsen brytes, og hent det du gikk glipp av med since (se Paginering).

Antimatter legger til disse hendelsene: community_attributes_updated, member_timeouts_updated, post_put_on_top, post_removed_from_top, server_categories_updated, channel_overrides_updated og category_overrides_updated.

Klientbiblioteker

• Gå: model.Client4 i server/public/model (importer github.com/mattermost/mattermost/server/public/model). model.NewAPIv4Client(url), deretter client.SetToken(token); model.NewWebSocketClient4(wsURL, token) følger hendelsene. Antimatters kopi legger til metoder for sine egne endepunkter, som UpdateMessageRequest, PutPostOnTop og ExportChannel.
• TypeScript: Client4-klassen i @mattermost/client, i webapp/platform/client, med typene i webapp/platform/types. Kopien i Antimatters repotorium inneholder Antimatters endepunkter; pakkene som Mattermost publiserer på npm, gjør det ikke.

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)
}

Det Antimatter legger til i API-et

Disse endepunktene og feltene finnes ikke på en Mattermost-server. Alle krever en økt.

Nye felter

• Team (Team, og PUT /teams/{team_id}/patch): all_channels_membership (alle er med i alle kanaler de kan se), default_channel_id (hvor nye brukere havner; tom verdi betyr General), kind (community eller workplace: i en workplace kan kanaladministratorer også arkivere sine kanaler; nye team får serverens TeamSettings.DefaultCommunityKind, community som standard), member_list_view (hvordan medlemslisten grupperer medlemmer: choice, standarden, lar hvert medlem velge; roles eller teams fastsetter det), hide_role_colors, require_team_badges, onboarding og autolinks (begge JSON-strenger).
• Den standardkanalen i et nytt samfunn er general (Generelt), ikke town-square. Oppgraderingen til 0.9.0 endrer navnet på town-square i hvert samfunn til general og beholder ID-en, med mindre samfunnet allerede har en general-kanal. Gamle navn fungerer fortsatt: GET /teams/{team_id}/channels/name/town-square, GET /teams/name/{team}/channels/name/town-square og en innkommende webhooks channel gir samfunnets standardkanal når ingen kanal har det navnet. Bruk default_channel_id eller navnet general i ny kode.
• Kanallinker: #channel-name linker en kanal, slik ~channel-name også gjør. Egenskapen channel_mentions i innlegget lister kanalene som er lenket på denne måten; en #word som ikke nevner en kanal forblir et hashtag. Antimatters webgrensesnitt og mobilapp skriver #name.
• Arkiverte kanaler kan fortsatt få nye medlemmer (POST /channels/{channel_id}/members), som kan lese historikken. Ingen kan legge inn meldinger, reagere, feste, sette en melding øverst, endre kanalens navn eller endre rollene til medlemmene der.
• Inline-svar: en melding med "props": {"reply_to": "<post id>"} siterer den meldingen i samme kanal. Legg til "reply_to_mention": false for ikke å varsle forfatteren. Serveren fyller metadata.reply_to med en kort beskrivelse av den siterte meldingen.
• Spoilere: "props": {"spoiler": true} skjuler meldingens tekst og filer inntil leseren velger å se dem.
• Ignorering og blokkering er preferanser: kategori user_block, navngitt etter den andres ID, med verdien ignore eller block. Om en direktemelding venter som en forespørsel, står det i din kanalmedlems notify_props.dm_request (pending, accepted eller dismissed).
• Meldingsvedlegg kan bære stages og en chart: se Cards.

Flytte en tråd

POST /posts/{post_id}/move_to_channel flytter en tråd, den første meldingen og alle svarene, til en annen kanal i samme samfunn. post_id kan være den første meldingen eller et hvilket som helst svar.

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 (obligatorisk): kanalen tråden flyttes til.
• flatten (standard false): true gjør at svarene blir meldinger i målkanalet i stedet for en tråd. Fusion bruker Gjør det til en kanal.

Meldingene beholder forfatterne, tidspunktene, reaksjonene og filene. Kopiene deres har egenskapen silent_notification, slik at de ikke varsler noen. De opprinnelige meldingene slettes. Svaret er den flyttede første meldingen, med den nye ID-en.

Hvem kan flytte en tråd

• Du må kunne lese tråden og legge inn meldinger i målkanalet.
• Kanalens administratorer, samfunnets administratorer, personer med Administrer meldinger (delete_others_posts) i kanalen og systemadministratorer kan flytte enhver tråd.
• Forfatteren av tråden kan flytte den når begge kanalene er offentlige, eller når alle meldinger i tråden er forfattet av vedkommende. Ellers er svaret 403 med ID-en api.post.move_thread.private_needs_moderator.app_error.
• Begge kanaler må være i samme community (ikke direktemeldinger eller gruppemeldinger), være ulike og ikke arkivert. Systemmeldinger og meldinger som brennes ut ved lesing kan ikke flyttes.
• En tråd med mer enn WranglerSettings.MoveThreadMaxCount meldinger (100 som standard; 0 for ingen grense) blir avvist.

Pekeren og notatet

Flyttingen etterlater to systemmeldinger av typen system_wrangler: en peker i den gamle kanalen («En tråd med 13 meldinger har blitt flyttet til #target») og et notat i målet («Denne tråden ble flyttet fra #source»), under den flyttede tråden eller, med flatten, etter meldingene. Bortsett fra meldingsteksten, lar egenskapene deres en klient tegne kanalnavnet som en lenke:

• Pekeren: MovedThreadPermalink, NumMessages, MovedThreadChannelId, MovedThreadTeamName, MovedThreadPostId og, for et offentlig mål, MovedThreadChannelName og MovedThreadChannelDisplayName.
• Notatet: MovedFromChannelId, MovedFromTeamName, MovedFromPostId (pekeren), MovedFromPermalink og, for en offentlig kilde, MovedFromChannelName og MovedFromChannelDisplayName.

Begge har også en TranslationID. Navnet på en privat kanal utelates: leserne ser «en annen kanal». Mattermosts egen POST /posts/{post_id}/move er slått av i Antimatter; bruk denne endepunktet.

Modelltilkoblinger

En modelltilkobling er en AI-leverandørs adresse og nøkkel, satt opp av en administrator. Serverens AI-funksjoner og appene som kaller AI-tjenesten bruker dem. Systemadministratorer administrerer serveromfattende tilkoblinger (manage_ai_connections); en communities administratorer administrerer deres communitys egne (manage_team_ai_connections). Nøkkeler er skrivebare: ingen svar inneholder en, bare api_key_set og api_key_last4.

Innholdet i en ny tilknytning:

{
  "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}
}

provider er openai_compatible eller anthropic. scope har server som standardverdi; en fellesskaps-ID gjør det til tilknytningsen for det fellesskapet. I limits betyr 0 ingen grense; forespørsler per minutt telles på hver server, mens token-budsjettene gjelder per kalendermåned (UTC) for hele klusteret. sharing angir hvilke fellesskap som kan bruke en serveromfattende tilknytning (direktemeldinger og gruppemeldinger krever all_teams), og audience hvem som kan bruke den; gjester kun med allow_guests. Endringer skrives til revisjonsloggen. Administratørguiden forklarer innstillingene: se AI.