REST API

Kaikki, mitä Antimatterin sovellukset tekevät, kulkee saman HTTP API:n kautta, joten skriptit voivat tehdä sen samaan tapaan. Tässä sivussa kerrotaan, miten tunnistaututaan, mitkä resurssit ovat yleisimmin käytössä, miten vastaukset ja virheet näyttävät ja miten tapahtumia voi seurata reaaliajassa WebSocketin kautta.

Perusasiat

• Perus-URL: https://chat.example.com/api/v4. Kaikki alla olevat loput ovat suhteessa tähän.
• Muoto: JSON sisäänpäin ja ulospäin, paitsi tiedostolähetykset (multipart). Lähetä Content-Type: application/json.
• Tunnistekoodit: jokaisella objektilla on 26 merkin id. Aikaleimat ovat millisekunteja Unix-epokista (create_at, update_at, delete_at; 0 tarkoittaa "ei poistettu").
• Yhteisöt ovat tiimejä: API kutsuu niitä teams-resursseiksi, joilla on team_id.
• Sinä: missä tahansa polussa, joka ottaa user_id-parametrin, me tarkoittaa kirjautunutta käyttäjää, kuten GET /users/me.

Täydellinen luettelo päätepisteistä on palvelimen koodissa: reitit on määritelty tiedostoissa server/channels/api4/*.go ja tyypit hakemistossa server/public/model. Tietovaraston api/v4/source-hakemistossa oleva OpenAPI-kuvaus kattaa Mattermostista perityt päätepisteet sekä osan Antimatterin lisäyksistä: ketjujen siirtäminen, malliyhteydet, agentit, tiimin säännöt, keskittymistila ja viestitoiminnot. Muut ovat vain koodissa.

Tunnistautuminen

Jokainen pyyntö, paitsi kirjautuminen ja muutama julkinen loppu, vaatii tunnuksen Authorization-otsakkeessa:

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

Siellä hyväksytään kolme tyyppiä tunnusta: henkilökohtaiset pääsytunnukset, istuntotunnukset ja OAuth-pääsytunnukset. Myös Authorization: Token … hyväksytään. Tunnukset kyselymerkkijonossa (?access_token=) hyväksytään vain OAuth-pääsytunnuksille.

Henkilökohtaiset pääsytunnukset (suositellaan skripteille)

Henkilökohtainen pääsytunnus toimii puolestasi, ei vanhene, ellei sinä aseta sille vanhenemispäivää, ja se voi peruutua milloin tahansa. Henkilökohtaiset pääsytunnukset ovat oletusarvoisesti poissa käytöstä:

1. Järjestelmän ylläpitäjä ottaa Ota henkilökohtaiset pääsytunnustiedot käyttöön-asetuksen käyttöön kohdassa Järjestelmäkonsoli › Integraatiot › Integraatioiden hallinta (ServiceSettings.EnableUserAccessTokens, AM_SERVICESETTINGS_ENABLEUSERACCESSTOKENS).
2. Jokaiselle käyttäjälle, joka voi luoda avaimia, järjestelmän ylläpitäjä avaa Järjestelmäkonsoli › Käyttäjien hallinta › Käyttäjät, valitsee Hallitse rooleja käyttäjän valikosta ja valitsee Salli tämän tilin luoda henkilökohtaisia API-avaimia. Järjestelmän ylläpitäjät voivat aina luoda avaimia.
3. Käyttäjä avaa profiilinsa yläoikeasta kulmasta ja siirtyy kohtaan Profiili ja asetukset › Turva. Kohdassa Henkilökohtaiset pääsytunnisteet hän kuvaa, mihin tunnistetta tarvitaan, ja valitsee Luo tunnus. Tunnus näytetään vain kerran: kopioi se.

API:lla: POST /users/{user_id}/tokens parametrina {"description": "backup script", "expires_at": 0} (expires_at millisekunteina; 0, jos ei eräpäivää). Vastauksen token-kenttä on avain; sen id käytetään avaimen peruuttamiseen (POST /users/tokens/revoke parametrina {"token_id": "…"}). Komentoriviltä: amctl token generate <user> <description>.

Järjestelmän ylläpitäjä voi asettaa pääsytunnisteen enimmäiskäyttöajan päivinä samassa Järjestelmäkonsolin sivulla, kohdassa Henkilökohtaisen pääsytunnisteen enimmäiskäyttöaika (päivää).

Istuntoavaimet

Kirjautuminen salasanalla palauttaa istuntoavaimen Token-vastausotsakkeessa. Istunto on sama tyyppi, jota sovellukset käyttävät:

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

Lisää "token": "123456" tilille, jolla on monitahoinen tunnistautuminen. Istunnot erääntyvät palvelimen istuntoasetusten mukaan, ja kirjautumispisteellä on nopeusrajoitus (5 pyyntöä sekunnissa). POST /users/logout päättää istunnon.

OAuth 2.0 -sovellukset

Jotta käyttäjät voivat kirjautua sovellukseesi Antimatter-tilillään, rekisteröi OAuth 2.0 -sovellus. Antimatter toimii silloin OAuth-palveluntarjoajana:

1. Ota OAuth 2.0 -palveluntarjoaja käyttöön on oltava päällä (Järjestelmäkonsoli › Integraatiot › Integraatioiden hallinta, ServiceSettings.EnableOAuthServiceProvider, oletuksena päällä).
2. Käyttäjä, jolla on oikeus hallita OAuth-sovelluksia (oletuksena järjestelmän ylläpitäjät), avaa Integraatiot › OAuth 2.0 -sovellukset (tiimivalikko › Tiimin asetukset › Integraatiot) ja lisää sovelluksen sen takaisinkutsuosoitteineen. Hän saa asiakas-ID:n ja asiakassalaisuuden.
3. Sovellus ohjaa käyttäjät osoitteeseen https://chat.example.com/oauth/authorize parametreilla response_type=code, client_id, redirect_uri ja state. PKCE-tuki code_challenge_method=S256 -menetelmällä on käytettävissä.
4. Koodi vaihdetaan osoitteessa POST https://chat.example.com/oauth/access_token (grant_type=authorization_code, sen jälkeen refresh_token uudistamiseksi), ja API:ta kutsutaan otsakkeella Authorization: Bearer <access token>.

Käyttäjät näkevät valtuuttamansa sovellukset kohdassa Profiili ja asetukset › Tietoturva › Valtuuttamasi sovellukset.

Pääresurssit

Viestin julkaiseminen

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

Viestit ovat Markdown-muodossa. Lisää "root_id" (ketjun ensimmäinen viesti) vastaamaan ketjussa, "file_ids" tiedostoille ja "props" liitteille ja muille lisäyksille (katso Liitteet).

Kanavan ID:n etsiminen

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

Nimet ovat kanavan linkissä: /lumen-labs/channels/ops-alerts.

Sivutus

Listaloppupisteet ottavat vastaan page (alkaen 0) ja per_page (oletus 60, enintään 200). Pyydä seuraavaa sivua, kunnes palautettu sivu on lyhyempi kuin per_page.

Kanavan viestit (GET /channels/{channel_id}/posts) ottavat myös since (aika: kaikki siitä lähtien muuttuneet) tai before ja after (viestin tunniste). Vastaus on viestilista: {"order": [IDs, newest first], "posts": {ID: post}, "next_post_id", "prev_post_id"}.

Virheet

Virheet käyttävät tavallisia HTTP-tilakoodia (400 virheellinen syöte, 401 ei kirjautunut, 403 ei sallittu, 404 ei löytynyt, 501 ominaisuus poistettu käytöstä) ja JSON-viestin:

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

Käytä id:tä koodissasi: message käännetään käyttäjän kielelle. detailed_error on tyhjä, ellei palvelin aja kehittäjätilassa (ServiceSettings.EnableDeveloper). Mainitse request_id palvelimen ylläpitäjälle: se näkyy lokitiedostoissa.

Nopeusrajoitukset

Käyttörajoitukset ovat oletusarvona poistettu käytöstä. Kun järjestelmän ylläpitäjä ottaa ne käyttöön (Järjestelmäkonsoli › Ympäristö › Käyttörajoitukset), jokainen asiakas saa oletusarvona 10 pyyntöä sekunnissa ja 100:n pyynnön räjähdyksen. Laskenta perustuu IP-osoitteeseen tai käyttäjään. Vastaukset sisältävät X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset-otsakkeet. Rajoituksen ylittyessä palvelin vastaa 429-koodilla ja Retry-After-otsakkeella, joka ilmaisee sekunteina, milloin uutta pyyntöä voi yrittää. Joillakin liitospisteillä, kuten kirjautumisella, on omat rajoituksensa riippumatta asetuksista.

Kirjoita skriptejä, jotka odottavat ja yrittävät uudelleen 429-virheen kohdalla, ja vältä kyselyitä: seuraa WebSocket-yhteyttä sen sijaan.

WebSocket-tapahtumavirta

Yhdistä osoitteeseen wss://chat.example.com/api/v4/websocket. Todennä itsesi joko Authorization: Bearer-otsakkeella yhteydenpyynnössä tai lähettämällä tämä ensimmäisenä viestinä:

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

Palvelin lähettää hello-tapahtuman, sitten tapahtuman kaikesta, mitä sinulla on oikeus nähdä:

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

Huomaa, että data.post on viesti JSON-muotoisena merkkijonona. Yleisiä tapahtumia ovat: posted, post_edited, post_deleted, reaction_added, reaction_removed, typing, status_change, user_added, direct_added. Sovut lähettävät omia tapahtumiaan, nimettyinä custom_<app id>_<event>.

Voit myös lähettää toimintoja, joista jokaisella on kasvava seq: user_typing arvolla {"channel_id", "parent_id"} tai get_statuses. Yhdistä uudelleen, jos yhteys katkeaa, ja hae puuttuvat tiedot since-parametrilla (ks. Sivutus).

Antimatter lisää seuraavat tapahtumat: agent_activity_changed ja agent_post_stream (katso Agentit), ai_tools_changed (katso Agentit), community_rules_updated ja community_rules_accepted (katso Tiimin säännöt), focus_ended (katso Keskittymistila), community_attributes_updated, member_timeouts_updated, post_put_on_top, post_removed_from_top, server_categories_updated, channel_overrides_updated ja category_overrides_updated. Uusi kirjautuminen omaan tiliin lähettää tapahtuman session_created muihin istuntoihisi (session_id, create_at, platform, os, browser, mobile; ei koskaan tokenia), ja varoituksen käsitteleminen lähettää tapahtuman session_revoked tai session_acknowledged (session_id) kaikkiin niihin.

Asiakasohjelmistokirjastot

• Siirry: model.Client4 -luokka sijaitsee hakemistossa server/public/model (tuonti: github.com/mattermost/mattermost/server/public/model). Luo asiakas model.NewAPIv4Client(url)-metodilla ja aseta tunnus client.SetToken(token)-metodilla. model.NewWebSocketClient4(wsURL, token) seuraa tapahtumia. Antimatterin kopio lisää metodeja omille liitospisteilleen, kuten UpdateMessageRequest, PutPostOnTop ja ExportChannel.
• TypeScript: Client4 -luokka @mattermost/client -paketista, joka sijaitsee hakemistossa webapp/platform/client, ja tyyppimääritykset hakemistossa webapp/platform/types. Antimatterin varastossa oleva kopio sisältää Antimatterin päätepisteet; Mattermostin npm:ssä julkaisema paketti ei sisällä niitä.

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

Mikä Antimatter lisää API:hin

Nämä päätepisteet ja kentät eivät ole olemassa Mattermost-palvelimella. Kaikki ne vaativat istunnon.

Uudet kentät

• Yhteisöt (Team ja PUT /teams/{team_id}/patch): all_channels_membership (kaikki ovat kaikissa kanavissa, jotka näkevät), default_channel_id (mihin uudet käyttäjät ohjautuvat), welcome_channel_id (mihin liittymis- ja poistumisviestit lähetetään, tyhjä jos ei mihinkään), kind (community tai workplace, näkyy käyttöliittymässä nimillä Guild ja Työtila: guild myös ottaa all_channels_membership-asetuksen käyttöön; uudet yhteisöt saavat palvelimen TeamSettings.DefaultCommunityKind-arvon, oletuksena community/Guild), member_list_view (miten jäsenlista ryhmittelee jäsenet: choice, oletus, antaa jokaisen jäsenen valita; roles tai teams määrää sen), hide_role_colors, require_team_badges, name_display (miten yhteisö näyttää nimet: tyhjä palvelimen oletuksena), onboarding ja autolinks (molemmat JSON-merkkijonoja).
• Uuden yhteisön oletuskanava on general (Yleinen), ei town-square. 0.9.0-päivitys nimetää jokaisen yhteisön town-square-kanavan uudelleen general-kanavaksi, säilyttäen sen ID:n, ellei yhteisössä ole jo general-kanavaa. Vanhat nimet toimivat yhä: GET /teams/{team_id}/channels/name/town-square, GET /teams/name/{team}/channels/name/town-square ja webhooken channel-kenttä palauttavat yhteisön oletuskanavan, jos kanavalla ei ole kyseistä nimeä. Käytä uuteen koodiin default_channel_id-kenttää tai nimeä general.
• Kanavalinkit: #channel-name linkkaa kanavan, kuten ~channel-name. Viestin channel_mentions-ominaisuus listaa kanavat, jotka on linkattu kummallakin tavalla; #word, joka ei nimeä kanavaa, jää hashtagiksi. Antimatterin verkkokeskus ja mobiilisovitus kirjoittavat #name.
• Arkistoidut kanavat ottavat yhä uusia jäseniä (POST /channels/{channel_id}/members), jotka voivat lukea niiden historian. Kukaan ei voi kirjoittaa, reagoida, kiinnittää, siirtää viestiä yläreunaan, nimetä kanavaa uudelleen tai muuttaa jäsenten rooleja siellä.
• Sisäiset vastaukset: viesti, jossa on "props": {"reply_to": "<post id>"}, lainaa kyseisen kanavan viestin. Lisää "reply_to_mention": false, jotta viestin kirjoittajaa ei ilmoiteta. Palvelin täyttää metadata.reply_to -kentän lainatun viestin lyhyellä kuvauksella.
• Spoilerit: "props": {"spoiler": true} piilottaa viestin tekstin ja liitetiedostot, kunnes lukija valitsee nähdä ne.
• Ignoroiminen ja estäminen ovat asetuksia: kategoria user_block, nimetty toisen henkilun ID:n mukaan, arvo ignore tai block. Suoran viestin odottaminen pyyntönä näkyy kanavan jäsenen notify_props.dm_request -kentässä (pending, accepted tai dismissed).
• Viestiliitteet voivat sisältää stages- ja chart-kentät: katso Kortit.
• Kanavat (Channel): jokaisen yhteisökanavan props sisältää aina am_type (text, voice tai forum), am_mode, am_root_posts (members tai moderators) ja am_preset (vastaavan esiasetuksen ID tai tyhjä mukautettujen asetusten tapauksessa), ja foorumeilla lisäksi am_forum_view (topics tai imageboard). Jos am_type puuttuu payloadista, se tarkoittaa, että kenttää ei ole täytetty, ei sitä, että kanava olisi tekstikanava. Suorat ja ryhmäviestit eivät sisällä näitä tietoja. Katso Kanavatyyppiä.

Kanavatyyppiä

Yhteisökanava on text, voice tai forum (sen tyyppi, joka määräytyy kanavan luomisen yhteydessä), yhtenä sen tyypin tiloista, ja siihen päälle asetukset. Esiasetus on nimetty paketti tilasta ja asetuksista, jonka asiakas tarjoaa yhtenä valintana; esiasetuksia ei tallenneta, joten kanavan esiasetus (am_preset) johdetaan sen asetuksista, ja se palauttaa arvon "", jos ne eivät vastaa mitään esiasetusta ("Mukautettu").

Kanavan tyypin luominen ja muuttaminen

POST /channels lukee ensin props.am_presetarvon (joka laajennetaan), ja sen jälkeen yksittäiset props.am_type-, am_mode-, am_root_posts- ja am_forum_view-arvot päällekkäin sen kanssa; muut am_-alkuiset ominaisuudet hylätään. Äänikanavan luominen hylätään, jos Äänikanavat-sovellus ei ole aktiivinen (400 api.channel.type.voice_unavailable.app_error). Suoran viestin tai ryhmäviestin luominen tyyppiominaisuuksilla hylätään (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 muuttaa olemassa olevan kanavan esiasetusta tai asetuksia: {"preset"?, "mode"?, "root_posts"?, "view"?}. Esiasetus laajennetaan ensin samalla tavalla kuin luomisen yhteydessä. Pyyntö edellyttää kanavassa oikeutta manage_public_channel_properties tai manage_private_channel_properties (tarkastustapahtuma updateChannelType), ja vastauksena palautetaan täydennetty kanava. Ruumis, joka määrittää toisen type-arvon, hylätään (api.channel.type.fixed.app_error): tyyppiä ei voi koskaan muuttaa. Muita virheitä: api.channel.type.invalid.app_error (tuntematon arvo, tila, joka ei kuulu kanavan tyyppiin, tai näkymä muulle kuin foorumikanavalle).

Eräviennissä ja -tuonnissa (amctl import bulk) kanavan rivillä on samat neljä kenttää: am_type, am_mode, am_root_posts ja am_forum_view. Jos kanavan riviltä puuttuvat nämä kentät, kanava tuodaan tavallisena tekstimuotoisena Chat-kanavana, kuten kanavatyypit olivat ennen.

Kuka aloittaa keskustelut tai avaa aiheita

Juurviestin lähettäminen (ei vastauksena oleva viesti) edellyttää oikeutta create_root_post, joka näkyy ohituseditorissa nimillä Aloita keskustelut (teksti- ja äänikanavat) tai Avaa aiheet (foorumit). Mikään rooli ei sisällä tätä oikeutta oletuksena: ennen ohituksia kaikilla, joilla on oikeus lähettää viestejä, on tämä oikeus, jos root_posts on members, ja vain kanavan moderaattoreilla (järjestelmän ylläpitäjät, yhteisön ylläpitäjät, kanavan ylläpitäjät sekä kaikki, joilla on kanavassa oikeus Hallitse viestejä) jos arvo on moderators. Rooli- tai henkilökohtainen ohitus oikeudelle create_root_post otetaan huomioon tämän jälkeen, kuten muidenkin oikeuksien kohdalla. Vastauksen (root_id asetettu) lähettämiseen riittää tavallinen oikeus lähettää viestejä.

Jos juuriviesti ei täytä tätä ehtoa, palautetaan 403: app.post.root_posts.moderators_only.app_error, kun root_posts on moderators eikä lähettäjä ole kanavan moderaattori, tai app.post.root_posts.denied.app_error, jos kyseessä on ohituskielto. Tarkistus tehdään REST API:lle, boteille, saapuville ja lähteville webhook-kutsuille (kutsun luoja tarkistetaan) sekä kauttaviivakomentojen vastauksille. Sovellusten lähettämät viestit (laajennosrajapinta) ja siirretyn ketjun kopiot eivät tarkisteta (siirtäjä tarkistetaan sen sijaan). Erätuonti ohittaa tarkistuksen.

Foorumit hyväksyvät vain aiheita

Foorumilla juuriviestissä on oltava props.am_thread_title (aiheen otsikko), tyhjät merkit poistettuina, 1–100 merkkiä, riippumatta lähteestä, mukaan lukien sovellukset ja siirretyt ketjut: puuttuva otsikko aiheuttaa virheen 400 app.post.forum.title_required.app_error, liian pitkä otsikko virheen app.post.forum.title_too_long.app_error. Vastauksissa ei tarvita otsikkoa, ja vastauksen mukana lähetetty otsikko hylätään. Jos aiheen juuriviestiä muokataan ilman otsikkoa tai tyhjällä otsikolla, nykyinen otsikko säilyy; ei-tyhjä otsikko nimeää aiheen uudelleen. Ketjun siirtäminen foorumille (alla) vaatii myös otsikon, joko pyynnöstä tai ketjun omasta otsikosta.

Kysymys- ja vastaus-aiheen hyväksytty vastaus (am_accepted_answer, vastauksen ID) ja Ideat-aiheen tila (am_topic_status, sekä am_topic_status_by ja am_topic_status_at) kirjoitetaan vain pyynnöllä PATCH /posts/{post_id}/topic. Jos näitä kolmea kenttää lähetetään luomisen, päivityksen tai osittaisen päivityksen yhteydessä, asiakkaan tai sovelluksen toimesta, ne hylätään ja tallennettu arvo säilytetään.

Listaa foorumin aiheet

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

Vaatii oikeuden lukea kanavaa. Kyselyparametrit:

• sort: activity (oletus), newest, votes, unanswered (vain Kysymys ja vastaus) tai status (vain Ideat).
• answered (true/false, Kysymys ja vastaus) ja status (jokin seuraavista: open, planned, in_progress, done, declined, Ideat): suodata näillä parametreilla. Jos parametria käytetään väärässä tilassa, palautetaan 400.
• mine=true: vain sinun aloittamasi aiheet. following=true: vain seuraamasi aiheet.
• q: hakee otsikosta tai ensimmäisen viestin tekstistä, enintään 200 merkkiä.
• before: edellisen sivun next_cursor. per_page: oletuksena 25, enintään 100. replies: 0–5 uusinta vastausta kullekin ketjulle kuvataulunäkymää varten.

Vastaus: {"topics": [{"post", "reply_count", "last_reply_at", "participant_ids", "votes", "accepted_answer_id", "status", "on_top", "replies": [post, …]}], "next_cursor"}. Äänet ovat 👍-reaktioita (+1 ja thumbsup lasketaan yhteen), joista vähennetään ketjun oma tekijä. accepted_answer_id annetaan vain Q&A-foorumeilla, status vain Ideat-foorumeilla. Kanavan kärjessä olevat ketjut tulevat ensin.

Hyväksy vastaus tai aseta ketjun tila

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:n on oltava foorumiketjun juurviesti, muuten 400 app.topic.not_a_topic.app_error. accepted_answer_id (vastauksen tunnus tai "" peruuttamista varten) vaatii Q&A-foorumin; status vaatii Ideat-foorumin. Väärässä tilassa oleva parametri aiheuttaa virheen 400 app.topic.mode.app_error.

• Vastauksen hyväksyminen: ketjun kysyjä (jos hän voi vielä kirjoittaa siellä) tai kanavan moderaattori; muuten 403 app.topic.accept.not_allowed.app_error. Vastauksen on oltava kyseisen ketjun aktiivinen, ei-järjestelmäviesti, muuten 400 app.topic.accept.not_a_reply.app_error. Hyväksytyn vastauksen poistaminen tyhjentää vastauksen.
• Tilan asettaminen: vain kanavan moderaattorit, muuten 403 app.topic.status.not_allowed.app_error; tuntematon arvo aiheuttaa virheen 400 app.topic.status.invalid.app_error.

Jokainen muutos lisää järjestelmävastauksen ketjuun (kertoen sen seuraajille) ja palauttaa ketjun juurviestin sellaisena kuin se nyt on. Ideat-foorumilla ketjun äänestäminen tekee siitä myös seuraamasi.

Siirrä ketju

POST /posts/{post_id}/move_to_channel siirtää ketjun, sen ensimmäisen viestin ja kaikki vastaukset toiseen kanavaan samassa yhteisössä. post_id voi olla ensimmäinen viesti tai mikä tahansa vastaus.

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 (pakollinen): kanava, johon ketju siirretään.
• flatten (oletus false): true tekee vastauksista kohdekanavan viestejä ketjun sijaan. Fusionin Tee kanavasta käyttää tätä. Hylätään, jos kohde on foorumi (400 app.post.move_thread.forum_flatten.app_error): vastauksista tulisi otsikottomia ketjuja.
• title: ketjun otsikko, kun kohde on foorumi. Jos sitä ei anneta, ketjun oma otsikko säilytetään, jos sellainen on; puuttuminen jommassakummassa tapauksessa aiheuttaa virheen 400 app.post.move_thread.forum_title_required.app_error. Ohitetaan, jos kohde ei ole foorumi.

Viestit säilyttävät kirjoittajansa, aikaleimansa, reaktiot ja tiedostot. Niiden kopiot kantavat silent_notification-ominaisuuden, joten ne eivät ilmoita kenellekään. Alkuperäiset viestit poistetaan. Vastaus on siirretty ensimmäinen viesti, jossa on sen uusi ID.

Kuka voi siirtää ketjua

• Sinun on pystyttävä lukemaan ketju ja kirjoittamaan kohdekanavaan.
• Kanavan ylläpitäjät, yhteisön ylläpitäjät, henkilöt, joilla on Hallitse viestejä (delete_others_posts) -oikeus kanavassa, ja järjestelmän ylläpitäjät voivat siirtää mitä tahansa ketjua.
• Ketjun kirjoittaja voi siirtää sen, jos molemmat kanavat ovat julkisia, tai jos ketjun kaikki viestit ovat hänen. Muussa tapauksessa vastaus on 403 ja ID api.post.move_thread.private_needs_moderator.app_error.
• Molempien kanavien on oltava samassa yhteisössä (ei suoria tai ryhmäviestejä), eri kanavia ja arkistoimattomia. Järjestelmäviestejä ja luetuissa poltettavia viestejä ei voi siirtää.
• Ketju, jossa on enemmän kuin WranglerSettings.MoveThreadMaxCount viestiä (oletusarvo 100; 0 ilman rajaa), hylätään.

Viite ja muistiinpano

Siirto luo kaksi system_wrangler-tyypin järjestelmäviestiä: viitteen vanhaan kanavaan ("Ketju, jossa on 13 viestiä, on siirretty kanavaan #target") ja muistiinpanon kohdekanavaan ("Tämä ketju on siirretty kanavasta #source"), siirretyn ketjun alle tai, flatten-valinnalla, sen viestien jälkeen. Viestien tekstin lisäksi niiden ominaisuudet mahdollistavat kanavan nimen piirtämisen linkkinä asiakkaassa:

• Viite: MovedThreadPermalink, NumMessages, MovedThreadChannelId, MovedThreadTeamName, MovedThreadPostId ja, jos kohde on julkinen kanava, MovedThreadChannelName ja MovedThreadChannelDisplayName.
• Muistiinpano: MovedFromChannelId, MovedFromTeamName, MovedFromPostId (viite), MovedFromPermalink ja, jos lähde on julkinen kanava, MovedFromChannelName ja MovedFromChannelDisplayName.

Molemmilla on myös TranslationID. Yksityisen kanavan nimi jätetään pois: lukijat näkevät tekstin "toinen kanava". Mattermostin oma POST /posts/{post_id}/move-pääte on poistettu käytöstä Antimatterissa; käytä tätä päatetta.

Yhteisön säännöt

Yhteisön ylläpitäjät voivat vaatia, että jäsenet hyväksyvät yhteisön säännöt ennen kuin he voivat lähettää viestejä kanavilla. Kun säännöt ovat käytössä, jäsen, joka ei ole hyväksynyt nykyistä versiota, ei voi lähettää, vastata, lähettää tiedostoja, ajoittaa, muokata tai palauttaa viestiä eikä suorittaa komentoja, jotka lähettävät viestejä yhteisön kanaville: palvelin vastaa tilakoodilla 403 ja virhekoodilla api.post.community_rules_not_accepted, ja ajoitetun viestin lähettäminen epäonnistuu virhekoodilla community_rules_not_accepted. Lukeminen, reaktiot sekä suorat ja ryhmäviestit eivät ole rajoitettuja. Myöskään botit, saapuvat webhookit, järjestelmäviestit tai yhteisön ylläpitäjät (manage_team, jonka järjestelmän ylläpitäjillä on myös) eivät ole rajoitettuja.

Tapahtuma community_rules_updated lähetetään yhteisölle, kun ylläpitäjä tallentaa säännöt (team_id, enabled, version), ja tapahtuma community_rules_accepted lähetetään hyväksyneelle jäsenelle kaikissa hänen istunnoissaan (team_id, version).

Keskittymistila

Keskittymistila on Älä häiritse -tila, jolla on lopetusaika: ilmoitukset mykistetään (ei push-, sähköposti-, työpöytä- tai pysyviä ilmoituksia, mukaan lukien kiireelliset viestit), syystä tulee mukautettu tila 🎯-emojilla (dart), joka vanhenee lopetusaikana, ja Antimatterin sovellukset piilottavat käyttäjän omat lukemattomat merkkien määrät. Vain henkilö itse voi käyttää näitä päätepisteitä (me tai hänen oma ID:nsä): kukaan muu, mukaan lukien järjestelmän ylläpitäjät, ei voi aloittaa, lopettaa tai lukea kenenkään keskittymistilaa tai sen yhteenvetoa.

Kun henkilö keskittyy, hänen käyttäjänsä omaisuutena on focus_until (millisekunteina), jota asiakasohjelmat käyttävät keskittymistilan näyttämiseen; sitä ei voi muuttaa profiilin kautta. Keskittyminen päättyy, kun henkilö lopettaa sen, kun ajankohta koittaa (minuutin sisällä) tai kun henkilö asettaa tilan itse, jolloin tila säilyy. Muutoin palautetaan aiempi tila ja mukautettu tila. Kaikki hänen istuntonsa saavat tällöin focus_ended-tapahtuman, jossa on start_at, end_at ja ended_by (user, timer tai status).

Malliyhteydet

Malli-yhteys on tekoälyn palveluntarjoattajan osoite ja avain, jonka ylläpitäjä määrittää. Palvelimen tekoälyominaisuudet ja tekoälypalvelua käyttävät sovellukset käyttävät näitä. Järjestelmän ylläpitäjät hallinnoivat palvelimenlaajuisia yhteyksiä (manage_ai_connections); yhteisön ylläpitäjät hallinnoivat yhteisönsä omia (manage_team_ai_connections). Avaimet ovat vain kirjoitettavia: vastaukset eivät sisällä avainta, vaan vain api_key_set ja api_key_last4.

Uuden yhteyden ruumis:

{
  "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 on openai_compatible tai anthropic. scope on oletuksena server; yhteisön ID tekee siitä kyseisen yhteisön yhteyden. limits-osassa arvo 0 tarkoittaa, ettei rajaa ole; pyyntöjä minuutissa lasketaan jokaisella palvelimella, ja token-budjetteja kalenterikuukaudessa (UTC) koko klusterille. sharing määrittää, mitkä yhteisöt voivat käyttää palvelimenlaajuista yhteyttä (suoriin viesteihin ja ryhmäviesteihin tarvitaan all_teams), ja audience määrittää, ketkä voivat käyttää sitä; vieraat vain, jos allow_guests on asetettu. Muutokset kirjataan tilintarkastuslokiin. Ylläpitäjän opas selittää asetukset: katso AI.

Agentit

Agentti on agent-tyyppinen bottitili (käyttäjän omaisuutena is_agent), jolla on asetukset: sen kattavuus (server tai yhteisön ID), sisäänrakennettu vai external, ja sisäänrakennetun agentin osalta malliyhteys, malli, järjestelmäkehote ja päättely. Järjestelmän ylläpitäjät hallitsevat palvelinkohtaisia agentteja (manage_system), yhteisön ylläpitäjät oman yhteisönsä agentteja (manage_team); lisäksi manage_own_agent heidän itse luomalleen agentille ja manage_others_agent muille agentteille. Agentin ID näissä poluissa on sen käyttäjä-ID. Ulkoisen agentin suorittaminen ja sisäänrakennetun agentin tilan asettaminen on selitetty osiossa Botit; PUT /users/{user_id}/status ja mukautettuja tiloja koskevat päätepisteet hylkäävät sisäänrakennetun agentin ID:n myös järjestelmän ylläpitäjiltä (403, api.status.agent.app_error).

Uuden agentin runko:

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

Tyhjä model käyttää yhteyden chat-mallia. access.channel_ids tarkoittaa kyseisten kanavien jäseniä. Ulkoisella agentilla ei ole yhteyttä, mallia eikä järjestelmäkehote. GET /agents palauttaa listan agentteja, joiden kanssa voit keskustella, sellaisina kuin tekoälykeskustelusovellus heidät näkee.