Το REST API

Ό,τι κάνουν οι εφαρμογές Antimatter περνάει από το ίδιο HTTP API, οπότε μπορούν να το κάνουν και τα σενάρια σας. Αυτή η σελίδα εξηγεί τον τρόπο ελέγχου ταυτότητας, τους πόρους που θα χρησιμοποιήσετε περισσότερο, τη μορφή των απαντήσεων και των σφαλμάτων, και τον τρόπο παρακολούθησης των γεγονότων σε πραγματικό χρόνο μέσω WebSocket.

Βασικά

• Βασική διεύθυνση URL: https://chat.example.com/api/v4. Όλα τα τελικά σημεία (endpoints) που ακολουθούν είναι σχετικά με αυτήν.
• Μορφή: JSON στην είσοδο και στην έξοδο, εκτός από τα ανέβασματα αρχείων (multipart). Στείλτε Content-Type: application/json.
• Αναγνωριστικά (IDs): κάθε αντικείμενο έχει ένα id 26 χαρακτήρων. Οι χρόνοι είναι σε χιλιοστά του δευτερολέπτου από την εποχή Unix (create_at, update_at, delete_at· 0 σημαίνει «δεν έχει διαγραφεί»).
• Οι κοινότητες είναι ομάδες: το API τα αποκαλεί teams, με team_id.
• Εσάς: όπου μια διαδρομή απαιτεί user_id, το me σημαίνει τον συνδεδεμένο χρήστη, όπως στο GET /users/me.

Η πλήρης λίστα των endpoints βρίσκεται στον κώδικα του διακομιστή: οι διαδρομές δηλώνονται στα server/channels/api4/*.go και οι τύποι στα server/public/model. Η περιγραφή OpenAPI στον φάκελο api/v4/source του repository καλύπτει τα endpoints που κληρονομήθηκαν από το Mattermost, καθώς και μερικές από τις προσθήκες του Antimatter: μετακίνηση νημάτων, συνδέσεις μοντέλων, πράκτορες, κανόνες κοινότητας, λειτουργία εστίασης και ενέργειες μηνυμάτων. Τα υπόλοιπα υπάρχουν μόνο στον κώδικα.

Ελέγχος ταυτότητας

Κάθε αίτημα, εκτός από την σύνδεση και μερικά δημόσια τελικά σημεία, απαιτεί διακριτικό (token) στο πεδίο Authorization:

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

Δεχόμαστε τρεις τύπους διακριτικών: προσωπικά διακριτικά πρόσβασης, διακριτικά συνεδρίας και διακριτικά πρόσβασης OAuth. Δεχόμαστε επίσης τη μορφή Authorization: Token …. Τα διακριτικά στην συμβολοσειρά ερωτήματος (?access_token=) δέχονται μόνο για διακριτικά πρόσβασης OAuth.

Προσωπικά διακριτικά πρόσβασης (συμβουλεύονται για σενάρια)

Ένα προσωπικό διακριτικό πρόσβασης δρα ως εσείς, δεν λήγει εκτός αν του ορίσετε ημερομηνία λήξης, και μπορεί να ανακληθεί ανά πάσα στιγμή. Τα προσωπικά διακριτικά πρόσβασης είναι απενεργοποιημένα από προεπιλογή:

1. Ένας διαχειριστής συστήματος ενεργοποιεί την επιλογή Ενεργοποίηση προσωπικών διαπιστευτηρίων πρόσβασης στη Κονσόλα συστήματος › Ολοκληρώσεις › Διαχείριση ολοκληρώσεων (ServiceSettings.EnableUserAccessTokens, AM_SERVICESETTINGS_ENABLEUSERACCESSTOKENS).
2. Για κάθε χρήστη που μπορεί να δημιουργήσει tokens, ένας διαχειριστής συστήματος ανοίγει το Κονσόλα συστήματος › Διαχείριση χρηστών › Χρήστες, επιλέγει Διαχείριση ρόλων από το μενού του χρήστη και επιλέγει Επιτρέπεται σε αυτόν τον λογαριασμό να δημιουργεί tokens πρόσβασης. Οι διαχειριστές συστήματος μπορούν πάντα να δημιουργούν tokens.
3. Ο χρήστης ανοίγει το avatar του στην πάνω δεξιά γωνία και στη συνέχεια πηγαίνει στις Ρυθμίσεις προφίλ › Ασφάλεια. Κάτω από Προσωπικά Tokens Πρόσβασης, περιγράφει τη χρήση του token και επιλέγει Δημιουργία token. Το token εμφανίζεται μία φορά: αντιγράψτε το.

Μέσω της API: POST /users/{user_id}/tokens με {"description": "backup script", "expires_at": 0} (expires_at σε χιλιοστά του δευτερολέπτου· 0 για κανένα). Το πεδίο token στην απάντηση είναι το μυστικό· το id χρησιμοποιείται για την ακύρωσή του (POST /users/tokens/revoke με {"token_id": "…"}). Από τη γραμμή εντολών: amctl token generate <user> <description>.

Ένας διαχειριστής συστήματος μπορεί να ορίσει ένα όριο στη διάρκεια ζωής των tokens χρησιμοποιώντας την επιλογή Μέγιστη διάρκεια ζωής προσωπικού token πρόσβασης (ημέρες) στη σελίδα της Κονσόλας συστήματος.

Tokens συνεδρίας

Η σύνδεση με κωδικό επιστρέφει ένα token συνεδρίας στο πεδίο Token της κεφαλίδας της απάντησης, του ίδιου τύπου με τις συνεδρίες που χρησιμοποιούν οι εφαρμογές:

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

Προσθέστε "token": "123456" για λογαριασμούς με πολυπαραγοντική ελέγχου. Οι συνεδρίες λήγουν σύμφωνα με τις ρυθμίσεις συνεδρίας του server, και το endpoint σύνδεσης έχει περιορισμό ρυθμού (5 αιτήματα ανά δευτερόλεπτο). Το POST /users/logout τερματίζει τη συνεδρία.

Εφαρμογές OAuth 2.0

Για να επιτρέψετε στους χρήστες να συνδέονται στην εφαρμογή σας με τον λογαριασμό Antimatter, καταχωρίστε μια εφαρμογή OAuth 2.0. Το Antimatter γίνεται τότε πάροχος OAuth:

1. Η επιλογή Ενεργοποίηση παρόχου υπηρεσιών OAuth 2.0 πρέπει να είναι ενεργοποιημένη (Κονσόλα συστήματος › Ολοκληρώσεις › Διαχείριση ολοκληρώσεων, ServiceSettings.EnableOAuthServiceProvider, ενεργοποιημένη από προεπιλογή).
2. Ένα άτομο με δικαίωμα διαχείρισης εφαρμογών OAuth (από προεπιλογή οι διαχειριστές συστήματος) ανοίγει Ολοκληρώσεις › Εφαρμογές OAuth 2.0 (μενού ομάδας › Ρυθμίσεις ομάδας › Ολοκληρώσεις) και προσθέτει την εφαρμογή με τα URLs callback της. Λαμβάνει ένα αναγνωριστικό πελάτη (client ID) και ένα μυστικό πελάτη (client secret).
3. Η εφαρμογή σας στέλνει τους χρήστες στο https://chat.example.com/oauth/authorize με response_type=code, client_id, redirect_uri και state. Υποστηρίζεται PKCE με code_challenge_method=S256.
4. Εκτελεί την ανταλλαγή του κωδικού στο POST https://chat.example.com/oauth/access_token (grant_type=authorization_code, και στη συνέχεια refresh_token για ανανέωση) και καλεί το API με Authorization: Bearer <access token>.

Οι χρήστες βλέπουν τις εφαρμογές που έχουν εξουσιοδοτήσει στο Προφίλ & ρυθμίσεις › Ασφάλεια › Εφαρμογές που εξουσιοδοτήσατε.

Βασικοί πόροι

Δημοσίευση μηνύματος

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

Τα μηνύματα είναι σε Markdown. Προσθέστε "root_id" (την πρώτη δημοσίευση ενός νήματος) για να απαντήσετε σε ένα νήμα, "file_ids" για αρχεία και "props" για συνημμένα και άλλα πρόσθετα (βλ. Συνημμένα).

Εύρεση του αναγνωριστικού (ID) ενός καναλιού

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

Οι ονομασίες είναι αυτές που βρίσκονται στο σύνδεσμο του καναλιού: /lumen-labs/channels/ops-alerts.

Σελιδοποίηση

Τα τελικά σημεία που επιστρέφουν λίστες δέχονται page (από 0) και per_page (60 από προεπιλογή, έως 200). Συνεχίστε να ζητάτε την επόμενη σελίδα μέχρι να επιστραφεί μια σελίδα με λιγότερα στοιχεία από το per_page.

Τα μηνύματα ενός καναλιού (GET /channels/{channel_id}/posts) δέχονται επίσης since (χρονική στιγμή: όλα όσα άλλαξαν από τότε) ή before και after (ID μηνύματος). Επιστρέφονται ως λίστα μηνυμάτων: {"order": [IDs, newest first], "posts": {ID: post}, "next_post_id", "prev_post_id"}.

Σφάλματα

Τα σφάλματα χρησιμοποιούν τους συνηθισμένους κωδικούς κατάστασης HTTP (400 λανθασμένη είσοδος, 401 χωρίς σύνδεση, 403 μη επιτρεπόμενο, 404 μη βρεθέν, 501 λειτουργία απενεργοποιημένη) και ένα JSON σώμα:

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

Χρησιμοποιήστε id στον κώδικά σας: το message μεταφράζεται στη γλώσσα του χρήστη. Το detailed_error είναι κενό εκτός αν ο διακομιστής εκτελεί σε λειτουργία προγραμματιστή (ServiceSettings.EnableDeveloper). Αναφέρετε το request_id στον διαχειριστή του διακομιστή: βρίσκεται στα αρχεία καταγραφής.

Περιορισμοί ρυθμού

Ο περιορισμός ρυθμού είναι απενεργοποιημένος από προεπιλογή. Όταν ένας διαχειριστής συστήματος τον ενεργοποιεί (Κονσόλα συστήματος › Περιβάλλον › Περιορισμός ρυθμού), κάθε client λαμβάνει 10 αιτήματα ανά δευτερόλεπτο με bursts των 100 από προεπιλογή, μετρώντας ανά διεύθυνση IP ή ανά χρήστη. Οι απαντήσεις περιέχουν τα X-RateLimit-Limit, X-RateLimit-Remaining και X-RateLimit-Reset. Αν ξεπεραστεί το όριο, ο server απαντά με 429 και ένα header Retry-After σε δευτερόλεπτα. Ορισμένα endpoints, όπως η σύνδεση, έχουν το δικό τους όριο ανεξάρτητα από τις ρυθμίσεις.

Γράψτε σενάρια που περιμένουν και επαναλαμβάνουν σε 429, και αποφύγετε την ερωτηματική αναζήτηση: ακολουθήστε το WebSocket.

Η ροή γεγονότων WebSocket

Συνδεθείτε στο wss://chat.example.com/api/v4/websocket. Επαληθεύστε είτε με την κεφαλίδα Authorization: Bearer στο αίτημα σύνδεσης, είτε στέλνοντας αυτό ως πρώτο μήνυμα:

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

Ο διακομιστής στέλνει ένα γεγονός hello, και στη συνέχεια ένα γεγονός για όλα όσα έχετε άδεια να δείτε:

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

Σημειώστε ότι το data.post είναι το μήνυμα ως JSON string. Συνηθισμένα γεγονότα: posted, post_edited, post_deleted, reaction_added, reaction_removed, typing, status_change, user_added, direct_added. Οι εφαρμογές στέλνουν τα δικά τους γεγονότα, με ονομασία custom_<app id>_<event>.

Μπορείτε επίσης να στέλνετε ενέργειες, καθεμία με αυξανόμενο seq: user_typing με {"channel_id", "parent_id"}, ή get_statuses. Επανασυνδεθείτε όταν η σύνδεση χαθεί, και ανακτήστε ό,τι χάσατε με since (βλ. Σελιδοποίηση).

Το Antimatter προσθέτει τα παρακάτω γεγονότα: agent_activity_changed και agent_post_stream (δείτε Πράκτορες), ai_tools_changed (δείτε Πράκτορες), community_rules_updated και community_rules_accepted (δείτε Κανόνες κοινότητας), focus_ended (δείτε Λειτουργία εστίασης), community_attributes_updated, member_timeouts_updated, post_put_on_top, post_removed_from_top, server_categories_updated, channel_overrides_updated και category_overrides_updated. Μια νέα σύνδεση στον λογαριασμό σας στέλνει το session_created στις άλλες σας συνόδους (session_id, create_at, platform, os, browser, mobile· ποτέ δεν στέλνει διακριτικό), και η διαχείριση της προειδοποίησής του στέλνει session_revoked ή session_acknowledged (session_id) σε όλες αυτές.

Βιβλιοθήκες πελάτη

• Go: model.Client4 στο server/public/model (import github.com/mattermost/mattermost/server/public/model). model.NewAPIv4Client(url), στη συνέχεια client.SetToken(token). Το model.NewWebSocketClient4(wsURL, token) παρακολουθεί τα συμβάντα. Η έκδοση του Antimatter προσθέτει μεθόδους για τα δικά του endpoints, όπως UpdateMessageRequest, PutPostOnTop και ExportChannel.
• TypeScript: η κλάση Client4 του @mattermost/client, στο webapp/platform/client, με τους τύπους της στο webapp/platform/types. Το αντίγραφο στο αποθετήριο του Antimatter περιλαμβάνει τα τελεία του Antimatter· το πακέτο που δημοσιεύεται στο npm από το Mattermost δεν τα περιλαμβάνει.

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

Τι προσθέτει το Antimatter στο API

Τα τελεία και τα πεδία αυτά δεν υπάρχουν σε έναν διακομιστή Mattermost. Όλα απαιτούν συνεδρία.

Νέα πεδία

• Κοινότητες (Team και PUT /teams/{team_id}/patch): all_channels_membership (όλοι μετέχουν σε κάθε κανάλι που μπορούν να δουν), default_channel_id (το κανάλι όπου καταλήγουν οι νέοι χρήστες), welcome_channel_id (το κανάλι όπου αποστέλλονται τα μηνύματα συμμετοχής και αποχώρησης, κενό για καμία αποστολή), kind (community ή workplace, εμφανίζεται στη διεπαφή ως Guild και Workspace: ένα guild ενεργοποιεί επίσης το all_channels_membership, οι νέες κοινότητες λαμβάνουν την τιμή TeamSettings.DefaultCommunityKind του διακομιστή, με προεπιλογή community/Guild), member_list_view (πώς ομαδοποιείται η λίστα μελών: choice, η προεπιλογή, επιτρέπει σε κάθε μέλος να επιλέξει, roles ή teams την καθορίζει σταθερά), hide_role_colors, require_team_badges, name_display (πώς εμφανίζει η κοινότητα τα άτομα, κενό για την προεπιλογή του διακομιστή), onboarding και autolinks (και τα δύο συμβολοσειρές JSON).
• Το προεπιλεγμένο κανάλι μιας νέας κοινότητας είναι το general (Γενικά), και όχι το town-square. Η αναβάθμιση στην έκδοση 0.9.0 μετονομάζει το town-square κάθε κοινότητας σε general, διατηρώντας το αναγνωριστικό του, εκτός εάν η κοινότητα διαθέτει ήδη κανάλι με όνομα general. Οι παλιές ονομασίες συνεχίζουν να λειτουργούν: τα GET /teams/{team_id}/channels/name/town-square, GET /teams/name/{team}/channels/name/town-square και το πεδίο channel ενός εισερχόμενου webhook επιστρέφουν το προεπιλεγμένο κανάλι της κοινότητας όταν δεν υπάρχει κανάλι με αυτό το όνομα. Χρησιμοποιήστε το default_channel_id ή το όνομα general στον νέο κώδικα.
• Σύνδεσμοι καναλιών: Οι σύνδεσμοι #channel-name παραπέμπουν σε ένα κανάλι, όπως και οι σύνδεσμοι ~channel-name. Η ιδιότητα channel_mentions της ανάρτησης περιλαμβάνει τα κανάλια που συνδέονται με οποιοδήποτε από τους δύο τρόπους. Μια λέξη #word που δεν αντιστοιχεί σε όνομα καναλιού παραμένει hashtag. Η διεπαφή web και η εφαρμογή για κινητά του Antimatter γράφουν #name.
• Αρχειοθετημένα κανάλια εξακολουθούν να δέχονται νέα μέλη (POST /channels/{channel_id}/members), τα οποία μπορούν να διαβάσουν το ιστορικό τους. Κανείς δεν μπορεί να αναρτήσει, να αντιδράσει, να καρφιτσώσει, να θέσει μήνυμα στην κορυφή, να μετονομάσει το κανάλι ή να αλλάξει τους ρόλους των μελών του.
• Ενσωματωμένες απαντήσεις: μια ανάρτηση με "props": {"reply_to": "<post id>"} παραθέτει το μήνυμα του ίδιου καναλιού. Προσθέστε "reply_to_mention": false για να μην ειδοποιηθεί ο δημιουργός του. Ο διακομιστής γεμίζει το metadata.reply_to με μια σύντομη περιγραφή του παρατιθέμενου μηνύματος.
• Σποίλερ: "props": {"spoiler": true} κρύβει το κείμενο και τα αρχεία μιας αναρτησης μέχρι ο αναγνώστης να επιλέξει να τα δει.
• Αγνόηση και αποκλεισμός είναι προτιμήσεις: κατηγορία user_block, με το όνομα του ID του άλλου ατόμου, και τιμή ignore ή block. Αν ένα άμεσο μήνυμα περιμένει ως αίτημα, αυτό καθορίζεται στο notify_props.dm_request του μέλους του καναλιού σας (pending, accepted ή dismissed).
• Συνημμένα μηνυμάτων μπορούν να φέρουν stages και chart: δείτε Κάρτες.
• Κανάλια (Channel): Τα props κάθε καναλιού κοινότητας περιλαμβάνουν πάντα τα am_type (text, voice ή forum), am_mode, am_root_posts (members ή moderators) και am_preset (το αναγνωριστικό του αντίστοιχου preset ή κενό για προσαρμοσμένες ρυθμίσεις), καθώς και, για τα φόρουμ, το am_forum_view (topics ή imageboard). Ένα payload χωρίς am_type σημαίνει ότι το πεδίο δεν έχει συμπληρωθεί, ποτέ ότι το κανάλι είναι κειμένου. Τα άμεσα και ομαδικά μηνύματα δεν περιλαμβάνουν κανένα από αυτά. Δείτε Τύπους καναλιών.

Τύποι καναλιών

Ένα κανάλι κοινότητας είναι text, voice ή forum (ο τύπος του, που καθορίζεται οριστικά κατά τη δημιουργία του), σε μία από τις λειτουργίες του τύπου του, με ρυθμίσεις από πάνω. Ένα preset είναι μια ονομαστική δέσμη λειτουργίας και ρυθμίσεων που μια εφαρμογή πελάτη προσφέρει ως μία επιλογή. Τα presets δεν αποθηκεύονται, επομένως το preset ενός καναλιού (am_preset) προκύπτει από τις ρυθμίσεις του και εμφανίζει "" όταν αυτές δεν ταιριάζουν με κανένα preset ("Προσαρμοσμένο").

Δημιουργία και αλλαγή του τύπου ενός καναλιού

Το POST /channels διαβάζει το props.am_preset (το οποίο επεκτείνεται πρώτο) και στη συνέχεια τα επιμέρους props.am_type, am_mode, am_root_posts και am_forum_view πάνω σε αυτό. Οποιοδήποτε άλλο prop με πρόθεμα am_ αγνοείται. Η δημιουργία φωνητικού καναλιού όταν η εφαρμογή Φωνητικά κανάλια δεν είναι ενεργή απορρίπτεται (400 api.channel.type.voice_unavailable.app_error). Η δημιουργία άμεσου ή ομαδικού μηνύματος με props τύπου απορρίπτεται (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 αλλάζει το preset ή τις ρυθμίσεις ενός υπάρχοντος καναλιού: {"preset"?, "mode"?, "root_posts"?, "view"?}, με το preset να επεκτείνεται πρώτο όπως κατά τη δημιουργία. Απαιτεί τη δικαιολογία manage_public_channel_properties ή manage_private_channel_properties στο κανάλι (γεγονός ελέγχου updateChannelType) και επιστρέφει το συμπληρωμένο κανάλι. Ένα σώμα αιτήματος που ορίζει άλλο type απορρίπτεται (api.channel.type.fixed.app_error): ο τύπος ο ίδιος δεν αλλάζει ποτέ. Άλλα σφάλματα: api.channel.type.invalid.app_error (άγνωστη τιμή, λειτουργία που δεν ανήκει στον τύπο του καναλιού ή προβολή σε μη-φόρουμ).

Η μαζική εισαγωγή και εξαγωγή (amctl import bulk) μεταφέρει τα ίδια τέσσερα πεδία στη γραμμή ενός καναλιού: am_type, am_mode, am_root_posts, am_forum_view. Μια γραμμή καναλιού χωρίς αυτά εισάγεται ως απλό κανάλι κειμένου Chat, όπως πριν τους τύπους καναλιών.

Ποιος ξεκινά συνομιλίες ή ανοίγει θέματα

Η ανάρτηση ριζικού μηνύματος (σε αντίθεση με μια απάντηση) απαιτεί τη δικαιολογία create_root_post, η οποία εμφανίζεται στον επεξεργαστή παρακάμπτησης ως Start conversations (κείμενο, φωνή) ή Open topics (φόρουμ). Κανένας ρόλος δεν τη διαθέτει: πριν τις παρακάμπτησεις, την έχουν όλοι όσοι μπορούν να αναρτούν όπου το root_posts είναι members, και μόνο οι συντονιστές του καναλιού (διαχειριστές συστήματος, διαχειριστές κοινότητας, διαχειριστές καναλιών και οποιοσδήποτε έχει Διαχείριση μηνυμάτων εκεί) όπου είναι moderators. Μια παρακάμπτηση ρόλου ή ατόμου στο create_root_post εφαρμόζεται στη συνέχεια από πάνω, όπως για οποιαδήποτε δικαιολογία. Μια απάντηση (με ορισμένο root_id) απαιτεί μόνο το συνηθισμένο δικαίωμα ανάρτησης.

Μια ανάρτηση ρίζας που δεν πληροί αυτήν τη προϋπόθεση λαμβάνει 403: app.post.root_posts.moderators_only.app_error όταν το root_posts είναι moderators και ο συντάκτης δεν είναι συντονιστής του καναλιού, ή app.post.root_posts.denied.app_error για μια παράκαμψη άρνησης. Ο έλεγχος αυτός ισχύει για το REST API, τα bots, τα εισερχόμενα και εξερχόμενα webhooks (στον δημιουργό του webhook) και τις απαντήσεις εντολών καθέτου. Οι αναρτήσεις από εφαρμογές (το plugin API) και τα αντίγραφα ενός μετακινούμενου νήματος δεν ελέγχονται (ο έλεγχος γίνεται στον χρήστη που μετακινεί το νήμα). Η μαζική εισαγωγή παραλείπει επίσης αυτόν τον έλεγχο.

Οι φόρουμ δέχονται μόνο θέματα

Σε ένα φόρουμ, μια ανάρτηση ρίζας απαιτεί το props.am_thread_title (τον τίτλο του θέματος), κομμένο στα άκρα, με μήκος από 1 έως 100 χαρακτήρες, από οποιαδήποτε πηγή, συμπεριλαμβανομένων των εφαρμογών και των μετακινούμενων νημάτων: η έλλειψη του τίτλου οδηγεί σε σφάλμα 400 app.post.forum.title_required.app_error, ενώ η υπερβαίνηση του ορίου σε app.post.forum.title_too_long.app_error. Οι απαντήσεις δεν απαιτούν τίτλο και οποιοσδήποτε τίτλος σταλεί σε απάντηση αγνοείται. Η επεξεργασία της ρίζας ενός θέματος χωρίς τίτλο ή με κενό τίτλο διατηρεί τον υπάρχοντα τίτλο· ένας μη κενός τίτλος το μετονομάζει. Η μετακίνηση ενός νήματος σε φόρουμ (παρακάτω) απαιτεί επίσης τίτλο, είτε από το αίτημα είτε από το ίδιο το νήμα.

Η αποδεκτή απάντηση ενός θέματος Q&A (am_accepted_answer, το ID μιας απάντησης) και η κατάσταση ενός θέματος Ιδεών (am_topic_status, μαζί με τα am_topic_status_by και am_topic_status_at) καταγράφονται μόνο μέσω του PATCH /posts/{post_id}/topic. Οποιοδήποτε από αυτά τα τρία πεδία σταλεί κατά τη δημιουργία, ενημέρωση ή τροποποίηση, από έναν πελάτη ή μια εφαρμογή, αγνοείται και διατηρείται η αποθηκευμένη τιμή.

Λίστα των θεμάτων ενός φόρουμ

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

Απαιτείται το δικαίωμα ανάγνωσης του καναλιού. Παράμετροι αιτήματος:

• sort: activity (προεπιλογή), newest, votes, unanswered (μόνο για Q&A) ή status (μόνο για Ιδέες).
• answered (true/false, για Q&A) και status (μία από τις τιμές open, planned, in_progress, done, declined, για Ιδέες): φιλτράρετε με βάση αυτές. Η χρήση οποιασδήποτε από αυτές εκτός της αντίστοιχης λειτουργίας οδηγεί σε σφάλμα 400.
• mine=true: μόνο τα θέματα που ξεκινήσατε εσείς. following=true: μόνο αυτά που παρακολουθείτε.
• q: ταιριάζει με τον τίτλο ή το κείμενο της πρώτης ανάρτησης, έως 200 χαρακτήρες.
• before: το next_cursor της προηγούμενης σελίδας. per_page: 25 από προεπιλογή, έως 100. replies: 0 έως 5 από τις πιο πρόσφατες απαντήσεις κάθε θέματος, για προβολή τύπου πίνακα εικόνων.

Απάντηση: {"topics": [{"post", "reply_count", "last_reply_at", "participant_ids", "votes", "accepted_answer_id", "status", "on_top", "replies": [post, …]}], "next_cursor"}. Οι ψήφοι είναι αντιδράσεις 👍 (οι +1 και thumbsup υπολογίζονται μαζί), μείον ο ίδιος ο συγγραφέας του θέματος. Το accepted_answer_id εμφανίζεται μόνο σε φόρουμ τύπου Ε&Α, ενώ το status μόνο σε φόρουμ Ιδεών. Τα θέματα που είναι καρφιτσωμένα στην κορυφή του καναλιού εμφανίζονται πρώτα.

Αποδοχή απάντησης ή ορισμός κατάστασης θέματος

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 πρέπει να είναι η ρίζα ενός θέματος φόρουμ, αλλιώς 400 app.topic.not_a_topic.app_error. Το accepted_answer_id (το ID μιας απάντησης ή "" για ανάκληση) απαιτεί φόρουμ τύπου Ε&Α. Το status απαιτεί φόρουμ Ιδεών. Η χρήση σε λάθος λειτουργία οδηγεί σε 400 app.topic.mode.app_error.

• Αποδοχή απάντησης: Επιτρέπεται μόνο στον ερωτών του θέματος (όσο μπορεί ακόμα να δημοσιεύει εκεί) ή σε έναν συντονιστή καναλιού. Διαφορετικά, 403 app.topic.accept.not_allowed.app_error. Η απάντηση πρέπει να είναι μια ενεργή, μη-συστημική απάντηση του συγκεκριμένου θέματος, αλλιώς 400 app.topic.accept.not_a_reply.app_error. Η διαγραφή της αποδεκτής απάντησης καθαρίζει την απάντηση.
• Ορισμός κατάστασης: Μόνο συντονιστές καναλιού, αλλιώς 403 app.topic.status.not_allowed.app_error. Μια άγνωστη τιμή οδηγεί σε 400 app.topic.status.invalid.app_error.

Κάθε αλλαγή δημοσιεύει μια συστηματική απάντηση στο θέμα (ενημερώνοντας τους ακόλουθους) και απαντά με τη ρίζα του θέματος, όπως διαμορφώνεται τώρα. Σε ένα φόρουμ Ιδεών, η ψήφος σε ένα θέμα σας κάνει επίσης να το ακολουθείτε.

Μετακίνηση νήματος

Το POST /posts/{post_id}/move_to_channel μετακινεί ένα νήμα, το πρώτο του μήνυμα και όλες τις απαντήσεις του, σε άλλο κανάλι της ίδιας κοινότητας. Το post_id μπορεί να είναι το πρώτο μήνυμα ή οποιαδήποτε απάντηση.

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 (απαιτούμενο): Το κανάλι στο οποίο μετακινείται το νήμα.
• flatten (προεπιλογή false): Η τιμή true κάνει τις απαντήσεις μηνύματα του καναλιού προορισμού αντί για νήμα. Η λειτουργία Δημιουργία καναλιού του Fusion το χρησιμοποιεί. Απορρίπτεται όταν ο προορισμός είναι φόρουμ (400 app.post.move_thread.forum_flatten.app_error), καθώς οι απαντήσεις θα γίνονταν θέματα χωρίς τίτλους.
• title: ο τίτλος του θέματος, όταν ο προορισμός είναι φόρουμ. Χωρίς αυτόν, διατηρείται ο τίτλος του ίδιου του νήματος, εάν υπάρχει. Η έλλειψη και των δύο προκαλεί σφάλμα 400 app.post.move_thread.forum_title_required.app_error. Αγνοείται όταν ο προορισμός δεν είναι φόρουμ.

Τα μηνύματα διατηρούν τους συγγραφείς, τις ώρες, τις αντιδράσεις και τα αρχεία τους. Τα αντίγραφα φέρουν την ιδιότητα silent_notification, ώστε να μην ειδοποιούν κανέναν. Τα αρχικά μηνύματα διαγράφονται. Η απάντηση είναι το πρώτα μετακινούμενο μήνυμα, με το νέο του αναγνωριστικό.

Ποιοι μπορούν να μετακινήσουν ένα νήμα

• Πρέπει να μπορείτε να διαβάζετε το νήμα και να δημοσιεύετε στο κανάλι προορισμού.
• Οι διαχειριστές του καναλιού, οι διαχειριστές της κοινότητας, τα άτομα με δικαίωμα Διαχείριση μηνυμάτων (delete_others_posts) στο κανάλι και οι διαχειριστές συστήματος μπορούν να μετακινήσουν οποιοδήποτε νήμα.
• Ο συγγραφέας του νήματος μπορεί να το μετακινήσει όταν και τα δύο κανάλια είναι δημόσια, ή όταν όλα τα μηνύματα του νήματος είναι δικά του. Διαφορετικά, η απάντηση είναι 403 με το αναγνωριστικό api.post.move_thread.private_needs_moderator.app_error.
• Και τα δύο κανάλια πρέπει να βρίσκονται στην ίδια κοινότητα (όχι άμεσα ή ομαδικά μηνύματα), να είναι διαφορετικά και να μην έχουν αρχειοθετηθεί. Τα μηνύματα συστήματος και τα μηνύματα που διαγράφονται μετά την ανάγνωση δεν μπορούν να μετακινηθούν.
• Ένα νήμα με περισσότερα μηνύματα από το όριο WranglerSettings.MoveThreadMaxCount (100 από προεπιλογή· 0 για απεριόριστο αριθμό) απορρίπτεται.

Ο δείκτης και η σημείωση

Η μετακίνηση αφήνει δύο μηνύματα συστήματος τύπου system_wrangler: έναν δείκτη στο παλιό κανάλι («Μετακινήθηκε ένα νήμα με 13 μηνύματα στο #target») και μια σημείωση στον προορισμό («Αυτό το νήμα μετακινήθηκε από το #source»), κάτω από το μετακινούμενο νήμα ή, με flatten, μετά τα μηνύματά του. Εκτός από το κείμενο του μηνύματος, οι ιδιότητές τους επιτρέπουν σε έναν πελάτη να σχεδιάζει το όνομα του καναλιού ως σύνδεσμο:

• Ο δείκτης: MovedThreadPermalink, NumMessages, MovedThreadChannelId, MovedThreadTeamName, MovedThreadPostId και, για δημόσιο προορισμό, MovedThreadChannelName και MovedThreadChannelDisplayName.
• Η σημείωση: MovedFromChannelId, MovedFromTeamName, MovedFromPostId (ο δείκτης), MovedFromPermalink και, για δημόσια πηγή, MovedFromChannelName και MovedFromChannelDisplayName.

Και τα δύο έχουν επίσης ένα TranslationID. Το όνομα ενός ιδιωτικού καναλιού παραλείπεται: οι αναγνώστες βλέπουν «άλλο κανάλι». Το δικό της POST /posts/{post_id}/move του Mattermost δεν είναι ενεργό στο Antimatter· χρησιμοποιήστε αυτό το σημείο σύνδεσης.

Κανόνες κοινότητας

Οι διαχειριστές μιας κοινότητας μπορούν να απαιτήσουν από τα μέλη να συμφωνήσουν με τους κανόνες πριν αναρτήσουν σε κανάλια. Ενώ οι κανόνες είναι ενεργοί, ένα μέλος που δεν έχει συμφωνήσει με την τρέχουσα έκδοση δεν μπορεί να αναρτήσει, να απαντήσει, να στείλει αρχεία, να προγραμματίσει, να επεξεργαστεί ή να ανακτήσει ένα μήνυμα, ούτε να εκτελέσει μια εντολή που αναρτά σε κανάλια της κοινότητας: ο διακομιστής απαντά 403 με το αναγνωριστικό api.post.community_rules_not_accepted, και ένα προγραμματισμένο μήνυμα που λήγει τότε αποτυγχάνει με τον κωδικό σφάλματος community_rules_not_accepted. Η ανάγνωση, οι αντιδράσεις και τα άμεσα και ομαδικά μηνύματα δεν εμποδίζονται. Το ίδιο ισχύει για τα bots, τα εισερχόμενα webhooks, τα μηνύματα συστήματος και τους διαχειριστές της κοινότητας (manage_team, το οποίο έχουν επίσης οι διαχειριστές συστήματος).

Το γεγονός community_rules_updated αποστέλλεται στην κοινότητα όταν ένας διαχειριστής αποθηκεύει τους κανόνες (team_id, enabled, version), και το community_rules_accepted αποστέλλεται σε αυτόν που συμφώνησε, σε όλες τις συνεδρίες του (team_id, version).

Λειτουργία συγκέντρωσης

Η λειτουργία συγκέντρωσης είναι η λειτουργία «Μην ενοχλείτε» με χρόνο λήξης: οι ειδοποιήσεις τίθενται σε σίγαση (χωρίς push, email, ειδοποιήσεις στην επιφάνεια εργασίας ή μόνιμες ειδοποιήσεις, συμπεριλαμβανομένων των επείγοντων μηνυμάτων), ο λόγος γίνεται η προσαρμοσμένη κατάσταση με το emoji 🎯 (dart), λήγοντας στο τέλος, και οι εφαρμογές του Antimatter αποκρύπτουν τα δικά του μη αναγνωσμένα σήματα. Μόνο το ίδιο το άτομο μπορεί να χρησιμοποιήσει αυτά τα endpoints (me ή το δικό του αναγνωριστικό): κανείς άλλος, συμπεριλαμβανομένων των διαχειριστών συστήματος, δεν μπορεί να ξεκινήσει, να τελειώσει ή να διαβάσει τη λειτουργία συγκέντρωσης κάποιου ή τη περίληψή της.

Ενώ κάποιος συγκεντρώνεται, ο χρήστης έχει την ιδιότητα focus_until (σε χιλιοστά του δευτερολέπτου), την οποία οι πελάτες χρησιμοποιούν για να εμφανίσουν την κατάσταση συγκέντρωσης. Δεν μπορεί να αλλάξει μέσω του προφίλ. Η συγκέντρωση τελειώνει όταν το άτομο τη τερματίσει, όταν έρθει η ώρα της (μέσα σε ένα λεπτό) ή όταν επιλέξει μόνο του μια κατάσταση, η οποία τότε παραμένει. Διαφορετικά, επανέρχονται η προηγούμενη κατάσταση και η προσαρμοσμένη κατάσταση. Όλες οι συνεδρίες του λαμβάνουν τότε το γεγονός focus_ended, με start_at, end_at και ended_by (user, timer ή status).

Συνδέσεις μοντέλων

Μια σύνδεση μοντέλου είναι η διεύθυνση και το κλειδί ενός παρόχου AI, που ρυθμίζεται από έναν διαχειριστή. Τις χρησιμοποιούν οι λειτουργίες AI του διακομιστή και οι εφαρμογές που καλούν την υπηρεσία AI. Οι διαχειριστές συστήματος διαχειρίζονται τις συνδέσεις σε επίπεδο διακομιστή (manage_ai_connections). Οι διαχειριστές μιας κοινότητας διαχειρίζονται τις δικές τους (manage_team_ai_connections). Τα κλειδιά είναι μόνο για εγγραφή: καμία απάντηση δεν μεταφέρει κλειδί, μόνο api_key_set και api_key_last4.

Το σώμα μιας νέας σύνδεσης:

{
  "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 είναι openai_compatible ή anthropic. Η παράμετρος scope έχει προεπιλογή server. Ένα αναγνωριστικό κοινότητας καθιστά τη σύνδεση σύνδεση αυτής της κοινότητας. Στο πεδίο limits, το 0 σημαίνει χωρίς όριο. Τα αιτήματα ανά λεπτό μετρώνται σε κάθε διακομιστή, ενώ τα budgets tokens ανά ημερολογιακό μήνα (UTC) ισχύουν για ολόκληρη την ομάδα διακομιστών (cluster). Η παράμετρος sharing καθορίζει ποιες κοινότητες μπορούν να χρησιμοποιήσουν μια σύνδεση σε επίπεδο διακομιστή (τα άμεσα και ομαδικά μηνύματα απαιτούν all_teams), ενώ η παράμετρος audience καθορίζει ποιοι μπορούν να τη χρησιμοποιήσουν. Οι επισκέπτες μπορούν να τη χρησιμοποιήσουν μόνο με allow_guests. Οι αλλαγές καταγράφονται στο αρχείο ελέγχου (audit log). Ο οδηγός διαχειριστών εξηγεί τις ρυθμίσεις: δείτε AI.

Πράκτορες

Ένας πράκτορας είναι ένας λογαριασμός Bot τύπου agent (is_agent στον χρήστη του), με τις ρυθμίσεις του: το πεδίο εφαρμογής (server ή το αναγνωριστικό μιας κοινότητας), αν είναι ενσωματωμένος ή external, και για έναν ενσωματωμένο πράκτορα, η σύνδεση μοντέλου, το μοντέλο, το σύστημα προτροπής (system prompt) και η λογική (reasoning). Οι διαχειριστές συστήματος διαχειρίζονται τους πράκτορες σε επίπεδο διακομιστή (manage_system), ενώ οι διαχειριστές μιας κοινότητας διαχειρίζονται τους δικούς της (manage_team). Επιπλέον, υπάρχει η δυνατότητα manage_own_agent για πράκτορες που δημιούργησαν οι ίδιοι και manage_others_agent για τους υπόλοιπους. Το αναγνωριστικό του πράκτορα σε αυτές τις διαδρομές είναι το αναγνωριστικό χρήστη (user ID). Η εκτέλεση εξωτερικού πράκτορα και ο τρόπος καθορισμού της κατάστασης ενός ενσωματωμένου πράκτορα εξηγούνται στο Bots. Τα σημεία σύνδεσης PUT /users/{user_id}/status και τα σημεία σύνδεσης για προσαρμοσμένη κατάσταση απορρίπτουν το αναγνωριστικό ενός ενσωματωμένου πράκτορα, ακόμη και για τους διαχειριστές συστήματος (403, api.status.agent.app_error).

Το σώμα ενός νέου πράκτορα:

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

Ένα κενό πεδίο model χρησιμοποιεί το μοντέλο συνομιλίας της σύνδεσης. Η παράμετρος access.channel_ids σημαίνει τα μέλη αυτών των καναλιών. Ένας εξωτερικός πράκτορας δεν έχει σύνδεση, μοντέλο ή προτροπή συστήματος. Η εντολή GET /agents καταγράφει τους πράκτορες με τους οποίους μπορείτε να συνομιλήσετε, όπως τους διαβάζει η εφαρμογή συνομιλίας AI.