REST-API'et

Alt, hvad Antimatter-appene gør, sker gennem samme HTTP-API, så dine scripts kan også gøre det. Denne side forklarer, hvordan du autentificerer, hvilke ressourcer du oftest vil bruge, hvordan svar og fejl ser ud, og hvordan du følger hændelser live via WebSocket.

Grundlæggende

• Grund-URL: https://chat.example.com/api/v4. Alle endpoints nedenfor er relative hertil.
• Format: JSON ind og ud, undtagen filuploads (multipart). Send Content-Type: application/json.
• IDs: hvert objekt har en 26 tegn lang id. Tider er millisekunder siden Unix-epochen (create_at, update_at, delete_at; 0 betyder "ikke slettet").
• Fællesskaber er teams: API'et kalder dem teams, med et team_id.
• Dig selv: hvor en sti tager et user_id, betyder me den indloggede bruger, som i GET /users/me.

Den fulde liste over slutpunkter findes i serverens kode: ruterne er deklareret i server/channels/api4/*.go og typerne i server/public/model. OpenAPI-beskrivelsen i lagerets mappe api/v4/source dækker de slutpunkter, der er arvet fra Mattermost, samt nogle af Antimatters tilføjelser: flytning af tråde, modeltilslutninger, agenter, fællesskabsregler, fokustilstand og beskedhandlinger. De øvrige findes kun i koden.

Autentificering

Alle anmodninger, undtagen indlogning og et par offentlige endpoints, kræver et token i Authorization-headeren:

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

Tre typer tokens accepteres der: personlige adgangstokens, sessionstokens og OAuth-adgangstokens. Authorization: Token … accepteres også. Tokens i query-strengen (?access_token=) accepteres kun for OAuth-adgangstokens.

Personlige adgangstokens (anbefalet til scripts)

Et personligt adgangstoken handler som dig, udløber ikke, medmindre du giver det en udløbsdato, og kan til enhver tid tilbagekaldes. Personlige adgangstokens er deaktiveret som standard:

1. En systemadministrator aktiverer Aktivér personlige adgangstokens i Systemkonsol › Integrationer › Integrationshåndtering (ServiceSettings.EnableUserAccessTokens, AM_SERVICESETTINGS_ENABLEUSERACCESSTOKENS).
2. For hver person, der kan oprette tokens, åbner en systemadministrator Systemkonsol › Brugerstyring › Brugere, vælger Administrer roller i personens menu og markerer Tillad denne konto at generere personlige adgangstokens. Systemadministratorer kan altid oprette dem.
3. Personen åbner deres avatar øverst til højre og derefter Profil & indstillinger › Sikkerhed. Under Personlige adgangstokens beskriver de, hvad tokenet skal bruges til, og vælger Opret token. Tokenet vises kun é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). Svarfeltet token er hemmeligheden, og id er det, du bruger til at ophæve det (POST /users/tokens/revoke med {"token_id": "…"}). Fra kommandolinjen: amctl token generate <user> <description>.

En systemadministrator kan begrænse tokens levetid med Maksimal levetid for personlige adgangstokens (dage) på samme side i Systemkonsolen.

Sessionstokens

Når man logger ind med en adgangskode, returneres et sessionstoken i Token-responsheaderen, samme type session som appene bruger:

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

Tilføj "token": "123456" for en konto med multifaktorautentificering. Sessions udløber, som serverens sessionindstillinger angiver, og login-endpointen er ratebegrænset (5 anmodninger pr. sekund). POST /users/logout afslutter sessionen.

OAuth 2.0-apps

For at lade folk logge ind på din applikation med deres Antimatter-konto, registrerer du en OAuth 2.0-app. Antimatter er derefter OAuth-udbyderen:

1. Aktivér OAuth 2.0-tjenesteudbyder skal være slået til (Systemkonsol › Integrationer › Integrationshåndtering, ServiceSettings.EnableOAuthServiceProvider, slået til som standard).
2. En person med rettigheder til at administrere OAuth-apps (som standard systemadministratorer) åbner Integrationer › OAuth 2.0-apps (fællesskabsmenu › Teamindstillinger › Integrationer) og tilføjer appen med dens callback-URL'er. De modtager et klient-ID og en klienthemmelighed.
3. Din applikation sender brugere til https://chat.example.com/oauth/authorize med response_type=code, client_id, redirect_uri og state. PKCE med code_challenge_method=S256 understøttes.
4. Den bytter koden ud ved POST https://chat.example.com/oauth/access_token (grant_type=authorization_code, derefter refresh_token for fornyelse) og kalder API'et med Authorization: Bearer <access token>.

Brugere kan se de applikationer, de har godkendt, under Profil & indstillinger › Sikkerhed › Apps, du har godkendt.

Hovedressourcer

Send en besked

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

Beskeder er Markdown. Tilføj "root_id" (den første besked i en tråd) for at svare i en tråd, "file_ids" for filer og "props" for vedhæftninger og andre ekstraudgaver (se Vedhæftninger).

Find en kanals ID

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

Navnene er dem i kanalens link: /lumen-labs/channels/ops-alerts.

Paginering

Liste-endpoints tager page (fra 0) og per_page (60 som standard, højst 200). Fortsæt med at anmode om den næste side, indtil en side kommer tilbage, der er kortere end per_page.

En kanals beskeder (GET /channels/{channel_id}/posts) kan også tage since (et tidspunkt: alt, der er ændret siden da), eller before og after (et indlægs-ID). De returneres som en liste over indlæg: {"order": [IDs, newest first], "posts": {ID: post}, "next_post_id", "prev_post_id"}.

Fejl

Fejl bruger de almindelige HTTP-statuskoder (400 ugyldig input, 401 ikke logget ind, 403 ikke tilladt, 404 ikke fundet, 501 funktion slået fra) og en JSON-krop:

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

Brug id i din kode: message oversættes til brugerens sprog. detailed_error er tom, medmindre serveren kører i udvikler-tilstand (ServiceSettings.EnableDeveloper). Angiv request_id til serverens administrator: den findes i logfilerne.

Begrænsning af haster

Begrænsning af haster er slået fra som standard. Når en systemadministrator slår den til (Systemkonsol › Miljø › Begrænsning af haster), får hver klient 10 anmodninger pr. sekund med bursts på 100 som standard, talt pr. IP-adresse eller pr. bruger. Svar indeholder X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-Reset; over grænsen svarer serveren med 429 og et Retry-After-header i sekunder. Nogle endpoints, f.eks. logind, har deres egen grænse uanset indstillingen.

Skriv scripts, der venter og prøver igen ved 429, og undgå polling: følg i stedet WebSocket.

WebSocket-hændelsesstrømmen

Forbind til wss://chat.example.com/api/v4/websocket. Autentificér enten med Authorization: Bearer-headeren i forbindelsesanmodningen, eller ved at sende dette som den første besked:

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

Serveren sender en hello-hændelse, derefter en hændelse for alt, du har tilladelse til at 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
}

Bemærk, at data.post er posten som en JSON-streng. Almindelige hændelser: posted, post_edited, post_deleted, reaction_added, reaction_removed, typing, status_change, user_added, direct_added. Apps sender deres egne hændelser, navngivet custom_<app id>_<event>.

Du kan også sende handlinger, hver med en stigende seq: user_typing med {"channel_id", "parent_id"}, eller get_statuses. Forbind igen, når forbindelsen afbrydes, og hente det, du manglede, med since (se Paginering).

Antimatter tilføjer disse begivenheder: agent_activity_changed og agent_post_stream (se Agenter), ai_tools_changed (se Agenter), community_rules_updated og community_rules_accepted (se Fællesskabsregler), focus_ended (se Fokustilstand), community_attributes_updated, member_timeouts_updated, post_put_on_top, post_removed_from_top, server_categories_updated, channel_overrides_updated og category_overrides_updated. En ny login til din egen konto sender session_created til dine andre sessioner (session_id, create_at, platform, os, browser, mobile; aldrig et token), og håndtering af advarslen sender session_revoked eller session_acknowledged (session_id) til alle dem.

Klientbiblioteker

• Go: model.Client4 i server/public/model (importér github.com/mattermost/mattermost/server/public/model). model.NewAPIv4Client(url), derefter client.SetToken(token); model.NewWebSocketClient4(wsURL, token) følger begivenhederne. Antimatters kopi tilføjer metoder til dets egne endpoints, såsom UpdateMessageRequest, PutPostOnTop og ExportChannel.
• TypeScript: Client4-klassen fra @mattermost/client, i webapp/platform/client, med typerne i webapp/platform/types. Kopien i Antimatters repository inkluderer Antimatters endpoints; pakken, der udgives på npm af Mattermost, gø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)
}

Hvad Antimatter tilføjer til API'et

Disse endpoints og felter findes ikke på en Mattermost-server. Alle kræver en session.

Nye felter

• Fællesskaber (Team og PUT /teams/{team_id}/patch): all_channels_membership (alle er med i alle kanaler, de kan se), default_channel_id (hvor nye brugere lander), welcome_channel_id (hvor beskeder om deltagelse og afgang sendes, tom hvis ingen), kind (community eller workplace, vist i grænsefladen som Guild og Workspace: en guild slår også all_channels_membership til; nye fællesskaber får serverens TeamSettings.DefaultCommunityKind, som som standard er community/Guild), member_list_view (hvordan medlemslisten grupperer medlemmer: choice, som er standarden, lader hvert medlem vælge; roles eller teams låser valget), hide_role_colors, require_team_badges, name_display (hvordan fællesskabet viser personer: tom for serverens standard), onboarding og autolinks (begge JSON-strenge).
• Standardkanalen i et nyt fællesskab er general (Generel), ikke town-square. Opgraderingen til 0.9.0 omdøber hvert fællesskabs town-square til general og bevarer ID'et, medmindre fællesskabet allerede har en general-kanal. Gamle navne virker stadig: GET /teams/{team_id}/channels/name/town-square, GET /teams/name/{team}/channels/name/town-square og en indgående webhooks channel returnerer fællesskabets standardkanal, når ingen kanal har det pågældende navn. Brug default_channel_id eller navnet general i ny kode.
• Kanallinks: #channel-name linker en kanal, ligesom ~channel-name gør. Postens channel_mentions-prop lister de kanaler, der er linket på den ene eller anden måde; et #word, der ikke navngiver en kanal, forbliver et hashtag. Antimatters webgrænseflade og mobilapp skriver #name.
• Arkiverede kanaler kan stadig få nye medlemmer (POST /channels/{channel_id}/members), som kan læse deres historik. Ingen kan poste, reagere, fastgøre, sætte en besked øverst, omdøbe kanalen eller ændre medlemmernes roller der.
• Inline-svar: Et indlæg med "props": {"reply_to": "<post id>"} citerer den pågældende besked fra samme kanal. Tilføj "reply_to_mention": false for ikke at underrette forfatteren. Serveren udfylder metadata.reply_to med en kort beskrivelse af den citerede besked.
• Spoilers: "props": {"spoiler": true} skjuler et indlægs tekst og filer, indtil læseren vælger at se dem.
• Ignorering og blokering er præferencer: kategori user_block, navngivet efter den andres ID, med værdien ignore eller block. Om en direkte besked venter som en anmodning fremgår af din kanalmembers notify_props.dm_request (pending, accepted eller dismissed).
• Beskedvedhæftninger kan indeholde stages og en chart: se Cards.
• Kanaler (Channel): props for enhver fællesskabskanal indeholder altid am_type (text, voice eller forum), am_mode, am_root_posts (members eller moderators) og am_preset (den tilsvarende forudindstillingens ID, eller tom for brugerdefinerede indstillinger), og for fora am_forum_view (topics eller imageboard). En payload uden am_type betyder, at feltet ikke er udfyldt, aldrig at kanalen er tekst. Direkte beskeder og gruppebeskeder indeholder ingen af disse. Se Kanaltyper.

Kanaltyper

En fællesskabskanal er text, voice eller forum (dens type, fastlagt ved oprettelsen), i en af dens types tilstande, med indstillinger ovenpå. En forudindstilling er en navngivet samling af en tilstand og indstillinger, som en klient tilbyder som ét valg; forudindstillinger gemmes ikke, så en kanals forudindstilling (am_preset) udledes fra dens indstillinger, og læser "", når de ikke matcher nogen forudindstilling ("Brugerdefineret").

Oprettelse og ændring af en kanals type

POST /channels læser props.am_preset (udvides først), derefter de enkelte props.am_type, am_mode, am_root_posts og am_forum_view ovenpå denne; alle andre am_-egenskaber fjernes. Oprettelse af en lydkanal, når Lydkanaler-appen ikke er aktiv, afvises (400 api.channel.type.voice_unavailable.app_error); oprettelse af en direkte besked eller gruppebesked med typeegenskaber afvises (api.channel.type.direct.app_error).

curl -X POST https://chat.example.com/api/v4/channels \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"team_id": "'$TEAM_ID'", "name": "help-desk", "display_name": "Help desk", "type": "O",
       "props": {"am_preset": "forum_qa"}}'

PUT /channels/{channel_id}/type ændrer forudindstillingen eller indstillingerne for en eksisterende kanal: {"preset"?, "mode"?, "root_posts"?, "view"?}, hvor forudindstillingen udvides først som ved oprettelse. Det kræver manage_public_channel_properties eller manage_private_channel_properties i kanalen (revisionshændelse updateChannelType), og svarer med den udfyldte kanal. En body, der navngiver en anden type, afvises (api.channel.type.fixed.app_error): selve typen ændres aldrig. Andre fejl: api.channel.type.invalid.app_error (en ukendt værdi, en tilstand, der ikke er af kanalens type, eller en visning på en ikke-forum).

Masseimport og -eksport (amctl import bulk) bærer de samme fire felter på en kanals linje: am_type, am_mode, am_root_posts, am_forum_view. En kanallinje uden disse importeres som en almindelig tekstbaseret Chat-kanal, som før kanalentyper.

Hvem starter samtaler eller åbner emner

At sende et rodindlæg (i modsætning til et svar) kræver tilladelsen create_root_post, som vises i tilsidesættelseseditoren som Start samtaler (tekst, lyd) eller Åbn emner (fora). Ingen rolle indeholder den: før tilsidesættelser har alle, der må sende beskeder, den, hvor root_posts er members, og kun kanalens moderatorer (systemadministratorer, communityadministratorer, kanaladministratorer og alle med Administrer beskeder der), hvor den er moderators. En rolle- eller personlig tilsidesættelse af create_root_post anvendes derefter ovenpå, som for enhver anden tilladelse. Et svar (root_id angivet) kræver kun den almindelige ret til at sende beskeder.

Et rodindlæg, der ikke opfylder dette, giver 403: app.post.root_posts.moderators_only.app_error, når root_posts er sat til moderators, og afsenderen ikke modererer kanalen, eller app.post.root_posts.denied.app_error ved en overstyrende nægtelse. Dette kontrolleres for REST API, bots, indgående og udgående webhooks (på hookets opretter) og svar på skråstregskommandoer; indlæg fra apps (plugin-API'en) og kopier af flyttede tråde kontrolleres ikke (her kontrolleres i stedet personen, der flytter tråden). Masseimport springer også denne kontrol over.

Forumer accepterer kun emner

I en forum skal et rodindlæg have props.am_thread_title (titlen på dets emne), uden mellemrum i starten eller slutningen, 1 til 100 tegn, fra alle kilder, inklusive apps og flyttede tråde: Manglende titel giver 400 app.post.forum.title_required.app_error, for lang titel giver app.post.forum.title_too_long.app_error. Svar kræver ingen titel, og eventuelle titler sendt med et svar ignoreres. Redigering af et emnes rodindlæg uden titel, eller med en tom titel, beholder den eksisterende titel; en ikke-tom titel omdøber emnet. Flytning af en tråd til et forum (nedenfor) kræver også en titel, enten fra anmodningen eller fra trådens egen.

Det accepterede svar på et Q&A-emne (am_accepted_answer, ID'et på et svar) og statussen for et Ideer-emne (am_topic_status, sammen med am_topic_status_by og am_topic_status_at) kan kun ændres via PATCH /posts/{post_id}/topic; hvis nogen af disse tre felter sendes ved oprettelse, opdatering eller patch, uanset om det kommer fra en klient eller en app, ignoreres de, og den gemte værdi bevares.

Vis en liste over forumets emner

GET /channels/{channel_id}/topics?sort=votes&per_page=25

Kræver rettigheden til at læse kanalen. Forespørgselsparametre:

• sort: activity (standard), newest, votes, unanswered (kun Q&A) eller status (kun Ideer).
• answered (true/false, Q&A) og status (en af open, planned, in_progress, done, declined, Ideer): filtrer efter disse. Brug af disse uden for den relevante tilstand giver 400.
• mine=true: kun de emner, du har oprettet. following=true: kun de emner, du følger.
• q: matcher titlen eller teksten i det første indlæg, op til 200 tegn.
• before: next_cursor fra den forrige side. per_page: 25 som standard, maksimalt 100. replies: 0 til 5 af de seneste svar til hvert emne, for en visning som et opslagstavle.

Svar: {"topics": [{"post", "reply_count", "last_reply_at", "participant_ids", "votes", "accepted_answer_id", "status", "on_top", "replies": [post, …]}], "next_cursor"}. Stemmer er 👍-reaktioner (+1 og thumbsup tæller sammen), fratrukket emnets egen forfatter; accepted_answer_id angives kun i Q&A-forumer, status kun i Ideer-forumer. Emner, der er fastgjort øverst i kanalen, kommer først.

Accepter et svar, eller angiv status for et emne

curl -X PATCH https://chat.example.com/api/v4/posts/$POST_ID/topic \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"accepted_answer_id": "'$REPLY_ID'"}'

post_id skal være rodindlægget for et forumemne, ellers 400 app.topic.not_a_topic.app_error. accepted_answer_id (et svar-ID, eller "" for at trække det tilbage) kræver et Q&A-forum; status kræver et Ideer-forum; forkert tilstand giver 400 app.topic.mode.app_error.

• Accept af svar: kun emnets spørger (så længe de stadig kan skrive der) eller en kanaladministrator; ellers 403 app.topic.accept.not_allowed.app_error. Svaret skal være et aktivt, ikke-systemsvar til det pågældende emne, ellers 400 app.topic.accept.not_a_reply.app_error. Slettes det accepterede svar, fjernes svaret.
• Angivelse af status: kun kanaladministratorer, ellers 403 app.topic.status.not_allowed.app_error; en ukendt værdi giver 400 app.topic.status.invalid.app_error.

Hver ændring opretter et systemvar i emnet (som fortæller dets følgere) og svarer med emnets rodindlæg, som det ser ud nu. I et Ideer-forum gør afstemning på et emne dig også til følger af det.

Flyt en tråd

POST /posts/{post_id}/move_to_channel flytter en tråd, dens første besked og alle dens svar, til en anden kanal i samme fællesskab. post_id kan være den første besked 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): den kanal, tråden flyttes til.
• flatten (standard false): true gør svarene til beskeder i målkanalen i stedet for i en tråd. Fusion's Gør til kanal bruger denne indstilling. Afvist, når målet er et forum (400 app.post.move_thread.forum_flatten.app_error): svarene ville blive til emner uden titler.
• title: emnets titel, når målet er et forum. Uden denne beholdes trådens egen titel, hvis den har en; mangler begge, giver det 400 app.post.move_thread.forum_title_required.app_error. Ignoreres, hvis målet ikke er et forum.

Beskederne beholder deres forfattere, tidspunkter, reaktioner og filer. Kopierne bærer silent_notification-egenskaben, så de ikke giver notifikationer til nogen. De oprindelige beskeder slettes. Svarret er den flyttede første besked med dens nye ID.

Hvem kan flytte en tråd

• Du skal kunne læse tråden og skrive i målkanalen.
• Kanalens administratorer, fællesskabets administratorer, personer med Administrer beskeder (delete_others_posts) i kanalen og systemadministratorer kan flytte enhver tråd.
• Trådens forfatter kan flytte den, når begge kanaler er offentlige, eller når alle beskeder i tråden er skrevet af forfatteren. I andre tilfælde er svaret 403 med ID'et api.post.move_thread.private_needs_moderator.app_error.
• Begge kanaler skal være i samme fællesskab (ingen direkte eller gruppebeskeder), være forskellige og ikke være arkiveret. Systembeskeder og beskeder, der brændes ved læsning, kan ikke flyttes.
• En tråd, der er længere end WranglerSettings.MoveThreadMaxCount beskeder (100 som standard; 0 for ingen grænse), afvises.

Pegeren og noten

Flytningen efterlader to systembeskeder af typen system_wrangler: en peger i den gamle kanal ("En tråd med 13 beskeder er blevet flyttet til #target") og en note i målkanalen ("Denne tråd blev flyttet fra #source"), under den flyttede tråd eller, med flatten, efter dens beskeder. Ud over beskedteksten giver deres egenskaber en klient mulighed for at tegne kanalnavnet som et link:

• Pegeren: MovedThreadPermalink, NumMessages, MovedThreadChannelId, MovedThreadTeamName, MovedThreadPostId og, for en offentlig målkanal, MovedThreadChannelName og MovedThreadChannelDisplayName.
• Noten: MovedFromChannelId, MovedFromTeamName, MovedFromPostId (pegeren), MovedFromPermalink og, for en offentlig kildekanal, MovedFromChannelName og MovedFromChannelDisplayName.

Begge har også en TranslationID. Et privat kanals navn udelades: læserne ser "en anden kanal". Mattermosts egen POST /posts/{post_id}/move er slået fra i Antimatter; brug denne endepunkt i stedet.

Fællesskabsregler

Administratorerne for et samfund kan kræve, at dets medlemmer accepterer samfundets regler, før de skriver i kanalerne. Når reglerne er aktiveret, kan et medlem, der ikke har accepteret den nuværende version, ikke skrive, svare, sende filer, planlægge, redigere eller gendanne en besked eller køre en kommando, der skriver i samfundets kanaler: Serveren svarer 403 med ID'et api.post.community_rules_not_accepted, og en planlagt besked, der skal sendes på det tidspunkt, fejler med fejlcode community_rules_not_accepted. Læsning, reaktioner samt direkte beskeder og gruppebeskeder begrænses ikke. Det samme gælder bots, indgående webhooks, systembeskeder og samfundets administratorer (manage_team, som systemadministratorer også har).

Hændelsen community_rules_updated sendes til fællesskabet, når en administrator gemmer reglerne (team_id, enabled, version), og community_rules_accepted sendes til den, der accepterede dem, på alle deres sessioner (team_id, version).

Fokustilstand

Fokustilstand er Forstyr ikke med et sluttidspunkt: Notifikationer er sat til lyd af (ingen push-, e-mail-, skrivebords- eller vedvarende notifikationer, inklusive hastige beskeder), årsagen bliver til den brugerdefinerede status med 🎯-emoji (dart), som udløber ved slutningen, og Antimatters apps skjuler personens egne ulæste badges. Kun personen selv kan bruge disse slutpunkter (me eller deres eget ID): Ingen andre, inklusive systemadministratorer, må starte, afslutte eller læse nogens fokus eller dets resumé.

Mens en person er i fokus, har deres bruger egenskaben focus_until (millisekunder), som klienterne bruger til at vise fokusstatus. Den kan ikke ændres gennem profilen. Fokus slutter, når personen selv afslutter det, når tiden er inde (inden for et minut), eller når de vælger en status selv, som derefter bliver stående. Ellers kommer status og tilpasset status fra før tilbage. Alle deres sessioner modtager derefter hændelsen focus_ended med start_at, end_at og ended_by (user, timer eller status).

Modelforbindelser

En modelforbindelse er en AI-udbyders adresse og nøgle, der oprettes af en administrator. Serverens AI-funktioner og de apps, der kalder AI-tjenesten, bruger dem. Systemadministratorer administrerer serverens forbindelser (manage_ai_connections), mens en fællesskabs administratorer administrerer deres fællesskabs egne (manage_team_ai_connections). Nøgler er skrivealene: intet svar indeholder en nøgle, kun api_key_set og api_key_last4.

Bodyen for en ny forbindelse:

{
  "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 er standard server; et fællesskabs ID gør det til det fællesskabs forbindelse. I limits betyder 0 ingen grænse; anmodninger pr. minut tæller på hver server, token-budgetter pr. kalendermåned (UTC) for hele clusteret. sharing angiver, hvilke fællesskaber der må bruge en serverbred forbindelse (direkte og gruppebeskeder kræver all_teams), og audience hvem der må bruge den; gæster kun med allow_guests. Ændringer skrives til auditloggen. Administrationsguiden forklarer indstillingerne: se AI.

Agenter

En agent er en bot-konto af typen agent (is_agent på dens bruger) med dens indstillinger: dens omfang (server eller et arbejdsområdes ID), om den er indbygget eller external, og for en indbygget agent dens modelforbindelse, model, systemprompt og ræsonnement. Systemadministratorer administrerer serverdækkende agenter (manage_system), mens arbejdsområdets administratorer administrerer deres arbejdsområdes agenter (manage_team). Derudover kan manage_own_agent administrere en agent, de selv har oprettet, og manage_others_agent administrere de øvrige. Agentens ID i disse stier er dens bruger-ID. Kørsel af en ekstern agent, og hvordan status for en indbygget agent sættes, forklares i Bots. PUT /users/{user_id}/status og endpoints for brugerdefineret status afviser ID'et for en indbygget agent, også for systemadministratorer (403, api.status.agent.app_error).

Indholdet af en ny agent:

{
  "username": "researcher",
  "display_name": "Researcher",
  "description": "Answers with sources",
  "scope": "server",
  "external": false,
  "connection_id": "…",
  "model": "",
  "system_prompt": "You research questions and answer with sources.",
  "reasoning": {"enabled": false, "effort": "", "budget_tokens": 0},
  "max_tool_turns": 0,
  "access": {"everyone": true, "team_ids": [], "channel_ids": [], "roles": [], "user_ids": [], "allow_guests": false}
}

En tom model bruger forbindelsens chatmodel. access.channel_ids betyder medlemmerne af disse kanaler. En ekstern agent har ingen forbindelse, model eller systemprompt. GET /agents viser en liste over de agenter, du kan tale med, som AI-chatappen læser dem.