REST API

Antimatter ऐप्स जो कुछ भी करते हैं, वह सब इसी HTTP API के माध्यम से होता है, इसलिए आपकी स्क्रिप्ट भी ऐसा कर सकती हैं। यह पेज बताता है कि प्रमाणीकरण कैसे करें, आप सबसे अधिक कौन से संसाधन इस्तेमाल करेंगे, रिस्पॉन्स और त्रुटियाँ कैसी दिखती हैं, और WebSocket के माध्यम से इवेंट्स लाइव कैसे फॉलो करें।

मूल बातें

• बेस URL: https://chat.example.com/api/v4। नीचे दिए गए सभी एंडपॉइंट्स इसके सापेक्ष हैं।
• प्रारूप: इन और आउट दोनों में JSON, सिवाय फ़ाइल अपलोड (मल्टीपार्ट) के। Content-Type: application/json भेजें।
• ID: हर ऑब्जेक्ट की एक 26-अक्षरों की id होती है। समय Unix epoch से मिलीसेकंड में होता है (create_at, update_at, delete_at; 0 का अर्थ है "हटाया नहीं गया")।
• समुदाय टीमें हैं: API इन्हें teams कहता है, जिनके साथ team_id होता है।
• आप स्वयं: जहाँ भी पाथ में user_id लिया जाता है, me का अर्थ है साइन-इन किया हुआ यूज़र, जैसे GET /users/me में।

एंडपॉइंट्स की पूरी सूची सर्वर के कोड में है: राउट्स server/channels/api4/*.go में घोषित हैं और टाइप्स server/public/model में हैं। रिपॉज़िटरी के api/v4/source फोल्डर में मौजूद OpenAPI विवरण Mattermost से वारसा प्राप्त एंडपॉइंट्स और Antimatter के कुछ जोड़ों (जैसे थ्रेड हटाना, मॉडल कनेक्शन और मैसेज एक्शन) को कवर करता है। बाकी सब केवल कोड में हैं।

प्रमाणीकरण

हर अनुरोध, सिवाय साइन-इन करने और कुछ सार्वजनिक एंडपॉइंट्स के, 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. हर उस व्यक्ति के लिए जो टोकन बना सकता है, एक सिस्टम एडमिन सिस्टम कंसोल › यूज़र प्रबंधन › उपयोगकर्ता खोलता है, उस व्यक्ति के मेन्यू में भूमिकाओं का प्रबंधन करें चुनता है और इस अकाउंट को व्यक्तिगत एक्सेस टोकन जनरेट करने की अनुमति दें पर टिक लगाता है। सिस्टम एडमिन हमेशा उन्हें बना सकते हैं।
3. व्यक्ति ऊपर दाईं ओर अपने अवतार पर क्लिक करता है, फिर प्रोफ़ाइल और सेटिंग्स › सुरक्षा खोलता है। पर्सनल एक्सेस टोकन के नीचे, वह टोकन किसके लिए है, इसका विवरण देता है और टोकन बनाएं चुनता है। टोकन केवल एक बार दिखाया जाता है: इसे कॉपी करें।

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>।

एक सिस्टम एडमिन उसी सिस्टम कंसोल पेज पर अधिकतम व्यक्तिगत एक्सेस टोकन वैधता (दिन) से टोकन की वैधता की सीमा लगा सकता है।

सेशन टोकन

पासवर्ड के साथ साइन इन करने पर 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" जोड़ें। सेशन सर्वर के सेशन सेटिंग्स के अनुसार समाप्त हो जाते हैं, और लॉगिन एंडपॉइंट रेट लिमिटेड है (5 अनुरोध प्रति सेकंड)। POST /users/logout सेशन समाप्त करता है।

OAuth 2.0 ऐप्स

अपने एप्लिकेशन में लोगों को उनके Antimatter अकाउंट के साथ साइन इन करने देने के लिए, एक OAuth 2.0 ऐप पंजीकृत करें। Antimatter तब OAuth प्रोवाइडर होता है:

1. OAuth 2.0 सर्विस प्रोवाइडर सक्षम करें चालू होना चाहिए (सिस्टम कंसोल › इंटीग्रेशन › इंटीग्रेशन प्रबंधन, ServiceSettings.EnableOAuthServiceProvider, डिफ़ॉल्ट रूप से चालू)।
2. OAuth ऐप्स को मैनेज करने का अधिकार रखने वाला कोई व्यक्ति (डिफ़ॉल्ट रूप से सिस्टम एडमिन) अपने अवतार पर क्लिक करता है, फिर इंटीग्रेशन › OAuth 2.0 ऐप्स खोलता है, और ऐप को उसके कॉलबैक URL के साथ जोड़ता है। उन्हें एक क्लाइंट ID और एक क्लाइंट सीक्रेट मिलता है।
3. आपका एप्लिकेशन लोगों को https://chat.example.com/oauth/authorize पर भेजता है, जिसमें response_type=code, client_id, redirect_uri और state शामिल होते हैं। code_challenge_method=S256 के साथ PKCE का समर्थन उपलब्ध है।
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 को सर्वर के एडमिन को उद्धृत करें: यह लॉग्स में उपलब्ध है।

रेट लिमिट्स

रेट लिमिटिंग डिफ़ॉल्ट रूप से बंद है। जब एक सिस्टम एडमिन इसे चालू करता है (सिस्टम कंसोल › पर्यावरण › रेट लिमिटिंग), तो डिफ़ॉल्ट रूप से हर क्लाइंट को 100 की बर्स्ट के साथ प्रति सेकंड 10 अनुरोध मिलते हैं, जिन्हें IP पता या उपयोगकर्ता के आधार पर गिना जाता है। प्रतिसाव X-RateLimit-Limit, X-RateLimit-Remaining और X-RateLimit-Reset ले जाते हैं; सीमा से ऊपर, सर्वर Retry-After हेडर (सेकंड में) के साथ 429 का जवाब देता है। कुछ एंडपॉइंट, जैसे साइन इन, किसी भी सेटिंग के बावजूद अपनी अलग सीमा रखते हैं।

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 स्ट्रिंग के रूप में पोस्ट है। सामान्य इवेंट्स: 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 के साथ जो आपने मिस किया है उसे प्राप्त करें (देखें Pagination)।

Antimatter इन इवेंट्स को जोडता है: community_attributes_updated, member_timeouts_updated, post_put_on_top, post_removed_from_top, server_categories_updated, channel_overrides_updated और category_overrides_updated.

क्लाइंट लाइब्रेरी

• जाना: server/public/model में model.Client4 (import github.com/mattermost/mattermost/server/public/model)। model.NewAPIv4Client(url), फिर client.SetToken(token); model.NewWebSocketClient4(wsURL, token) इवेंट्स को फॉलो करता है। Antimatter की कॉपी अपने एंडपॉइंट्स के लिए विधियाँ जोड़ती है, जैसे UpdateMessageRequest, PutPostOnTop और ExportChannel।
• TypeScript: webapp/platform/client में @mattermost/client की Client4 क्लास, जिसके टाइप्स webapp/platform/types में हैं। Antimatter के रिपॉज़िटरी में मौजूद कॉपी Antimatter के एंडपॉइंट्स को शामिल करती है; Mattermost द्वारा npm पर प्रकाशित पैकेज में वे नहीं हैं।

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 (जहाँ नए सदस्य आते हैं; खाली होने का मतलब General है), kind (community या workplace: एक वर्कप्लेस में, चैनल एडमिन अपने चैनलों को भी अर्काइव कर सकते हैं; नए समुदाय सर्वर के TeamSettings.DefaultCommunityKind को प्राप्त करते हैं, डिफ़ॉल्ट रूप से community), member_list_view (सदस्य सूची सदस्यों को कैसे समूहबद्ध करती है: choice, डिफ़ॉल्ट, हर सदस्य को चुनने देती है; roles या teams इसे फिक्स करती है), hide_role_colors, require_team_badges, onboarding और autolinks (दोनों JSON स्ट्रिंग्स हैं)।
• नई कम्युनिटी कया डिफ़ॉल्ट चैनल general (General) हय, न कि town-square। 0.9.0 अपग्रेड हर कम्युनिटी कया town-square कय नाम general कर दता हय, उसकय ID बरकरार रहता हय, जब तक कि कम्युनिटी कय पहले से ही general चैनल न हो। पुराने नाम काम करतय रहतय: GET /teams/{team_id}/channels/name/town-square, GET /teams/name/{team}/channels/name/town-square आ इनकमिंग वेबहुक कय channel तब कम्युनिटी कय डिफ़ॉल्ट चैनल देतय जब कसि चैनल कय उतना नाम न हो। नया कोड में default_channel_id या नाम general कय उपयोग करें।
• चैनल लिंक: #channel-name कसि चैनल कय लिंक करता हय, जस ~channel-name करता हय। पोस्ट कय channel_mentions प्रॉप में उतने चैनल कय लिस्ट हय जिनकय लिंक या तरीकय से किये गयय हय; #word जो कसि चैनल कय नाम न हो, हेशटैग रहता हय। 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 ले जा सकते हैं: कार्ड्स देखें।

थ्रेड कय स्थान बदलें

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 कय Make it a channel इसकय उपयोग करता हय।

संदेश अपन लेखक, समय, प्रतिक्रियाएँ आ फाइलें बरकरार रखतय हैं। उनकय कॉपी silent_notification प्रॉप कय साथ आतय हैं, ताकि कसि न सूचना पावे। मूल संदेश हटा दिये जातय हैं। जवाब में स्थानांतरित पहला संदेश, उसकय नया ID कय साथ, आतय हय।

कसि थ्रेड कय स्थान बदल सकेतय हय

• आपकय थ्रेड पढ़न आ लक्ष्य चैनल में पोस्ट करन कय अधिकार होना जरूरी हय।
• चैनल कय एडमिन, कम्युनिटी कय एडमिन, चैनल में संदेशों कय प्रबंधन करें (delete_others_posts) कय अधिकार रखने वाले लोग, आ सिस्टम एडमिन कसि भी थ्रेड कय स्थान बदल सकेतय हैं।
• थ्रेड कय लेखक तब तक उसकय स्थान बदल सकेतय हय जब तक कि दोनों चैनल सार्वजनिक न हो, या जब तक कि थ्रेड कय सारे संदेश उसकय अपन न हो। अन्यथा जवाब 403 आतय हय, ID api.post.move_thread.private_needs_moderator.app_error कय साथ।
• दोनों चैनल एक ही कम्युनिटी में होने चाहिए (डायरेक्ट या समूह संदेश नहीं), अलग-अलग होने चाहिए, और अरकाइव न किए गए होने चाहिए। सिस्टम संदेश और burn-on-read संदेश को नहीं हटाया जा सकता।
• WranglerSettings.MoveThreadMaxCount संदेशों (डिफ़ॉल्ट रूप से 100; कोई सीमा न रखने के लिए 0) से लंबा थ्रेड अस्वीकार कर दिया जाता है।

पॉइंटर और नोट

इस स्थानांतरण से system_wrangler प्रकार के दो सिस्टम संदेश बनते हैं: पुराने चैनल में एक पॉइंटर ("13 संदेशों वाला थ्रेड #target में स्थानांतरित कर दिया गया") और लक्ष्य में एक नोट ("यह थ्रेड #source से स्थानांतरित किया गया"), जो स्थानांतरित किए गए थ्रेड के नीचे या, flatten के साथ, उसके संदेशों के बाद आता है। संदेश के टेक्स्ट के अलावा, उनके प्रॉप्स एक क्लाइंट को चैनल का नाम एक लिंक के रूप में दिखाने की अनुमति देते हैं:

• पॉइंटर: MovedThreadPermalink, NumMessages, MovedThreadChannelId, MovedThreadTeamName, MovedThreadPostId, और, एक सार्वजनिक लक्ष्य के लिए, MovedThreadChannelName और MovedThreadChannelDisplayName।
• नोट: MovedFromChannelId, MovedFromTeamName, MovedFromPostId (पॉइंटर), MovedFromPermalink, और, एक सार्वजनिक स्रोत के लिए, MovedFromChannelName और MovedFromChannelDisplayName।

दोनों में TranslationID भी होता है। निजी चैनल का नाम छोड़ दिया जाता है: पाठक "एक अन्य चैनल" देखते हैं। Antimatter में Mattermost का अपना POST /posts/{post_id}/move बंद रहता है; इस एंडपॉइंट का उपयोग करें।

मॉडल कनेक्शन

मॉडल कनेक्शन एक AI प्रोवाइडर का पता और कुंजी है, जिसे एक एडमिन सेट अप करता है। सर्वर के AI फीचर और AI सर्विस को कॉल करने वाले ऐप्स इनका उपयोग करते हैं। सिस्टम एडमिन सर्वर-व्यापी कनेक्शन (manage_ai_connections) प्रबंधित करते हैं; एक कम्युनिटी के एडमिन अपनी कम्युनिटी के अपने (manage_team_ai_connections) प्रबंधित करते हैं। कुंजियाँ write-only हैं: कोई जवाब एक कुंजी नहीं ले जाता, केवल 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 होता है; किसी कम्युनिटी का ID इसे उस कम्युनिटी का कनेक्शन बना देता है। limits में, 0 का अर्थ है कोई सीमा नहीं; प्रति मिनट अनुरोध प्रत्येक सर्वर पर गिने जाते हैं, और टोकन बजट पूरे क्लस्टर के लिए कैलेंडर महीने (UTC) के आधार पर होते हैं। sharing बताता है कि कौन सी कम्युनिटी सर्वर-वाइड कनेक्शन का उपयोग कर सकती हैं (डायरेक्ट मैसेज और समूह संदेश के लिए all_teams आवश्यक है), और audience बताता है कि कौन उपयोग कर सकता है; अतिथि केवल allow_guests के साथ। परिवर्तन ऑडिट लॉग में लिखे जाते हैं। एडमिन गाइड सेटिंग्स की व्याख्या करता है: देखें AI।