API REST

Semua yang dilakukan oleh aplikasi Antimatter melalui API HTTP yang sama, jadi skrip anda juga boleh melakukannya. Halaman ini menerangkan cara pengesahan, sumber yang paling kerap digunakan, rupa respons dan ralat, serta cara mengikuti peristiwa secara langsung melalui WebSocket.

Asas

• URL Asas: https://chat.example.com/api/v4. Semua titik akhir di bawah adalah relatif kepadanya.
• Format: JSON masuk dan keluar, kecuali muat naik fail (multipart). Hantar Content-Type: application/json.
• ID: setiap objek mempunyai id 26 aksara. Masa adalah milisaat sejak epoch Unix (create_at, update_at, delete_at; 0 bermaksud "tidak dipadam").
• Komuniti adalah pasukan: API memanggilnya teams, dengan team_id.
• diri anda: di mana-mana laluan yang mengambil user_id, me bermaksud pengguna yang log masuk, seperti dalam GET /users/me.

Senarai penuh titik akhir terdapat dalam kod pelayan: laluan diisytiharkan dalam server/channels/api4/*.go dan jenis dalam server/public/model. Penerangan OpenAPI dalam folder api/v4/source repositori merangkumi titik akhir yang diwarisi daripada Mattermost, serta beberapa penambahan Antimatter: memindahkan bebenang, sambungan model dan tindakan mesej. Yang lain hanya terdapat dalam kod.

Pengesahan

Setiap permintaan, kecuali log masuk dan beberapa titik akhir awam, memerlukan token dalam pengepala Authorization:

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

Tiga jenis token diterima di sana: token akses peribadi, token sesi dan token akses OAuth. Authorization: Token … juga diterima. Token dalam strung pertanyaan (?access_token=) hanya diterima untuk token akses OAuth.

Token akses peribadi (disyorkan untuk skrip)

Token akses peribadi bertindak sebagai anda, tidak tamat melainkan anda memberikan tarikh tamat, dan boleh dicabut pada bila-bila masa. Token akses peribadi adalah luar oleh lalai:

1. Pentadbir sistem mengaktifkan Dayakan Token Akses Peribadi dalam Konsol Sistem › Integrasi › Pengurusan Integrasi (ServiceSettings.EnableUserAccessTokens, AM_SERVICESETTINGS_ENABLEUSERACCESSTOKENS).
2. Untuk setiap individu yang boleh mencipta token, seorang pentadbir sistem membuka Konsol Sistem › Pengurusan Pengguna › Pengguna, memilih Urus peranan dalam menu individu tersebut dan menanda Benarkan akaun ini menjana token akses peribadi. Pentadbir sistem sentiasa boleh mencipta token ini.
3. Individu tersebut membuka avatar mereka di bahagian kanan atas, kemudian Profil & tetapan › Keselamatan. Di bawah Token akses peribadi, mereka menerangkan tujuan token tersebut dan memilih Cipta token. Token tersebut hanya dipaparkan sekali: salinnya.

Melalui API: POST /users/{user_id}/tokens dengan {"description": "backup script", "expires_at": 0} (expires_at dalam milisaat; 0 untuk tiada). Medan token dalam respons adalah rahsia; id yang digunakan untuk membatalkannya (POST /users/tokens/revoke dengan {"token_id": "…"}). Dari baris arahan: amctl token generate <user> <description>.

Pentadbir sistem boleh menetapkan had tempoh hayat token dengan Tempoh Hayat Maksimum Token Akses Peribadi (hari) pada halaman Konsol Sistem yang sama.

Token sesi

Log masuk dengan kata laluan akan mengembalikan token sesi dalam pengepala respons Token, sejenis sesi yang sama yang digunakan oleh aplikasi:

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

Tambah "token": "123456" untuk akaun dengan pengesahan dua faktor. Sesi tamat tempoh mengikut tetapan sesi pelayan, dan titik akhir log masuk had kadar (5 permintaan setiap saat). POST /users/logout menamatkan sesi.

Aplikasi OAuth 2.0

Untuk membolehkan orang lain log masuk ke aplikasi anda dengan akaun Antimatter mereka, daftar aplikasi OAuth 2.0. Antimatter kemudian menjadi penderia OAuth:

1. Aktifkan Pempamer Perkhidmatan OAuth 2.0 mesti dihidupkan (Konsol Sistem › Integrasi › Pengurusan Integrasi, ServiceSettings.EnableOAuthServiceProvider, dihidupkan secara lalai).
2. Seseorang yang mempunyai hak untuk mengurus aplikasi OAuth (pentadbir sistem secara lalai) membuka avatar mereka, kemudian Integrasi › Aplikasi OAuth 2.0, dan menambah aplikasi dengan URL panggil balik. Mereka akan mendapat ID klien dan rahsia klien.
3. Aplikasi anda menghantar pengguna ke https://chat.example.com/oauth/authorize dengan response_type=code, client_id, redirect_uri dan state. PKCE dengan code_challenge_method=S256 disokong.
4. Ia menukar kod di POST https://chat.example.com/oauth/access_token (grant_type=authorization_code, kemudian refresh_token untuk memperbaharui), dan memanggil API dengan Authorization: Bearer <access token>.

Pengguna boleh melihat aplikasi yang mereka benarkan dalam Profil & tetapan › Keselamatan › Aplikasi yang anda benarkan.

Sumber utama

Hantar mesej

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

Mesej menggunakan Markdown. Tambahkan "root_id" (hantaran pertama dalam benang) untuk balas dalam benang, "file_ids" untuk fail dan "props" untuk lampiran dan tambahan lain (lihat Lampiran).

Cari ID saluran

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

Nama tersebut ialah nama dalam pautan saluran: /lumen-labs/channels/ops-alerts.

Pembahagian halaman

Titik akhir senarai menerima page (mula dari 0) dan per_page (60 secara lalai, maksimum 200). Terus minta halaman seterusnya sehingga halaman yang dikembalikan lebih pendek daripada per_page.

Mesej dalam saluran (GET /channels/{channel_id}/posts) juga mengambil since (masa: semua yang berubah sejak itu), atau before dan after (ID mesej). Ia dikembalikan sebagai senarai mesej: {"order": [IDs, newest first], "posts": {ID: post}, "next_post_id", "prev_post_id"}.

Ralat

Ralat menggunakan kod status HTTP biasa (400 input tidak sah, 401 tidak log masuk, 403 tidak dibenarkan, 404 tidak dijumpai, 501 ciri dimatikan) dan badan JSON:

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

Gunakan id dalam kod anda: message diterjemahkan ke dalam bahasa pengguna. detailed_error kosong melainkan pelayan berjalan dalam mod pembangun (ServiceSettings.EnableDeveloper). Quotekan request_id kepada pentadbir pelayan: ia terdapat dalam log.

Had kadar

Had kadar dimatikan secara lalai. Apabila pentadbir sistem menghidupkannya (Konsol Sistem › Persekitaran › Had Kadar), setiap klien mendapat 10 permintaan per saat dengan pecutan 100 secara lalai, dikira mengikut alamat IP atau pengguna. Respons membawa X-RateLimit-Limit, X-RateLimit-Remaining dan X-RateLimit-Reset; melebihi had, pelayan menjawab 429 dengan pengepala Retry-After dalam saat. Sesetengah hujung, seperti log masuk, mempunyai had mereka sendiri tanpa mengira tetapan.

Tulis skrip yang menunggu dan cuba semula pada 429, dan elakkan pengimbasan: ikuti WebSocket sebaliknya.

Aliran peristiwa WebSocket

Sambungkan ke wss://chat.example.com/api/v4/websocket. Autentikasi sama ada dengan pengepala Authorization: Bearer pada permintaan sambungan, atau dengan menghantar ini sebagai mesej pertama:

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

Pelayan menghantar peristiwa hello, kemudian peristiwa untuk semua yang anda dibenarkan melihat:

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

Perhatikan bahawa data.post ialah mesej sebagai strung JSON. Peristiwa biasa: posted, post_edited, post_deleted, reaction_added, reaction_removed, typing, status_change, user_added, direct_added. Aplikasi menghantar peristiwa mereka sendiri, dinamakan custom_<app id>_<event>.

Anda juga boleh menghantar tindakan, setiap satu dengan seq yang meningkat: user_typing dengan {"channel_id", "parent_id"}, atau get_statuses. Sambung semula apabila sambungan terputus, dan dapatkan apa yang terlepas dengan since (lihat Pembahagian).

Antimatter menambah peristiwa ini: community_attributes_updated, member_timeouts_updated, post_put_on_top, post_removed_from_top, server_categories_updated, channel_overrides_updated dan category_overrides_updated.

Pustaka klien

• Pergi: model.Client4 dalam server/public/model (import github.com/mattermost/mattermost/server/public/model). model.NewAPIv4Client(url), kemudian client.SetToken(token); model.NewWebSocketClient4(wsURL, token) mengikut peristiwa. Salinan Antimatter menambah kaedah untuk pintunya sendiri, seperti UpdateMessageRequest, PutPostOnTop dan ExportChannel.
• TypeScript: kelas Client4 daripada @mattermost/client, dalam webapp/platform/client, dengan jenisnya dalam webapp/platform/types. Salinan dalam repositori Antimatter merangkumi pintu Antimatter; pakej yang diterbitkan oleh Mattermost pada npm tidak merangkuminya.

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

Apa yang Antimatter tambah kepada API

Pintu dan medan ini tidak wujud pada pelayan Mattermost. Kesemuanya memerlukan sesi.

Medan baharu

• Komuniti (Team, dan PUT /teams/{team_id}/patch): all_channels_membership (semua orang berada dalam setiap saluran yang boleh mereka lihat), default_channel_id (tempat pendaratan orang baharu; kosong bermaksud Am), kind (community atau workplace: dalam tempat kerja, pentadbir saluran juga boleh mengarkibkan saluran mereka; komuniti baharu mendapat TeamSettings.DefaultCommunityKind pelayan, community secara lalai), member_list_view (cara senarai ahli mengumpul ahli: choice, lalai, membolehkan setiap ahli memilih; roles atau teams memastikannya), hide_role_colors, require_team_badges, onboarding dan autolinks (keduanya rentetan JSON).
• Saluran lalai bagi komuniti baharu ialah general (General), bukan town-square. Kemas kini 0.9.0 menamakan semula town-square setiap komuniti kepada general, mengekalkan ID-nya, melainkan komuniti tersebut sudah mempunyai saluran general. Nama lama masih berfungsi: GET /teams/{team_id}/channels/name/town-square, GET /teams/name/{team}/channels/name/town-square dan channel webhook masuk memberikan saluran lalai komuniti tersebut apabila tiada saluran dengan nama itu. Gunakan default_channel_id, atau nama general, dalam kod baharu.
• Pautan saluran: #channel-name memautkan saluran, sama seperti ~channel-name. Prop channel_mentions hantaran senaraikan saluran yang dipautkan dengan mana-mana cara; #word yang tidak menamakan sebarang saluran kekal sebagai tag. Antarmuka web dan aplikasi mudah alih Antimatter menulis #name.
• Saluran diarkibkan masih menerima ahli baharu (POST /channels/{channel_id}/members), yang boleh membaca sejarah mereka. Tiada siapa yang boleh menghantar, memberi reaksi, semat, meletakkan mesej di bahagian atas, menamakan semula saluran atau mengubah peranan ahli di sana.
• Balas dalaman: hantaran dengan "props": {"reply_to": "<post id>"} mengutip mesej tersebut dari saluran yang sama. Tambah "reply_to_mention": false untuk tidak memaklumkan pengarangnya. Pelayan mengisi metadata.reply_to dengan penerangan ringkas tentang mesej yang dikutip.
• Spoiler: "props": {"spoiler": true} menyembunyikan teks dan fail hantaran sehingga pembaca memilih untuk melihatnya.
• Abai dan halang adalah tetapan: kategori user_block, dinamakan mengikut ID orang lain, dengan nilai ignore atau block. Sama ada mesej terus menunggu sebagai permintaan terdapat dalam notify_props.dm_request ahli saluran anda (pending, accepted atau dismissed).
• Lampiran mesej boleh membawa stages dan chart: lihat Kad.

Alihkan bebenang

POST /posts/{post_id}/move_to_channel mengalihkan bebenang, mesej pertamanya dan semua balasannya, ke saluran lain dalam komuniti yang sama. post_id boleh menjadi mesej pertama atau mana-mana balasan.

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 (diperlukan): saluran yang bebenang dialihkan ke sana.
• flatten (lalai false): true menjadikan balasan sebagai mesej saluran sasaran, bukan bebenang. Jadikan saluran Fusion menggunakannya.

Mesej-mesej ini mengekalkan pengarang, masa, reaksi dan fail. Salinannya membawa prop silent_notification, jadi ia tidak memberi pemberitahuan kepada sesiapa. Mesej asal akan dipadam. Jawapannya ialah mesej pertama yang dialihkan, dengan ID baharunya.

Siapa yang boleh mengalihkan bebenang

• Anda mesti boleh membaca bebenang dan menghantar dalam saluran sasaran.
• Pentadbir saluran, pentadbir komuniti, orang yang mempunyai Urus mesej (delete_others_posts) dalam saluran, dan pentadbir sistem boleh mengalihkan mana-mana bebenang.
• Pengarang bebenang boleh mengalihkannya apabila kedua-dua saluran adalah awam, atau apabila semua mesej dalam bebenang adalah miliknya. Jika tidak, jawapannya ialah 403 dengan ID api.post.move_thread.private_needs_moderator.app_error.
• Kedua-dua saluran mesti berada dalam komuniti yang sama (tiada mesej terus atau kumpulan), berbeza, dan tidak diarkibkan. Mesej sistem dan mesej yang dibakar selepas dibaca tidak boleh dipindahkan.
• Bebenang yang lebih panjang daripada WranglerSettings.MoveThreadMaxCount mesej (100 secara lalai; 0 untuk tiada had) akan ditolak.

Penuding dan nota

Pemindahan ini meninggalkan dua mesej sistem jenis system_wrangler: penuding dalam saluran lama ("Bebenang dengan 13 mesej telah dipindahkan ke #target") dan nota dalam sasaran ("Bebenang ini dipindahkan dari #source"), di bawah bebenang yang dipindahkan atau, dengan flatten, selepas mesej-mesejnya. Selain teks mesej, properti mereka membolehkan klien melukis nama saluran sebagai pautan:

• Penuding: MovedThreadPermalink, NumMessages, MovedThreadChannelId, MovedThreadTeamName, MovedThreadPostId, dan, untuk sasaran awam, MovedThreadChannelName dan MovedThreadChannelDisplayName.
• Nota: MovedFromChannelId, MovedFromTeamName, MovedFromPostId (penuding), MovedFromPermalink, dan, untuk sumber awam, MovedFromChannelName dan MovedFromChannelDisplayName.

Keduanya juga mempunyai TranslationID. Nama saluran peribadi ditinggalkan: pembaca melihat "saluran lain". POST /posts/{post_id}/move milik Mattermost sendiri kekal dimatikan dalam Antimatter; gunakan titik akhir ini.

Sambungan model

Sambungan model ialah alamat dan kunci pembekal AI, diset oleh pentadbir. Ciri-ciri AI pelayan dan aplikasi yang memanggil perkhidmatan AI menggunakannya. Pentadbir sistem mengurus sambungan peringkat pelayan (manage_ai_connections); pentadbir komuniti mengurus sambungan komuniti mereka sendiri (manage_team_ai_connections). Kunci adalah tulis sahaja: tiada jawapan membawa satu, hanya api_key_set dan api_key_last4.

Isi badan sambungan baharu:

{
  "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 ialah openai_compatible atau anthropic. scope secara lalai ialah server; ID komuniti menjadikannya sambungan komuniti tersebut. Dalam limits, 0 bermaksud tiada had; permintaan per minit dikira pada setiap server, bajet token per bulan kalendar (UTC) untuk keseluruhan kluster. sharing menyatakan komuniti mana yang boleh menggunakan sambungan seluruh server (Mesej Terus dan Mesej Kumpulan memerlukan all_teams), dan audience menyatakan sesiapa yang boleh menggunakannya; Tetamu hanya dengan allow_guests. Perubahan ditulis ke dalam log audit. Panduan pentadbir menerangkan tetapan: lihat AI.