رسانه برنامه‌نویسی REST

همه‌ی کارهایی که برنامه‌های Antimatter انجام می‌دهند از طریق همین رسانه برنامه‌نویسی HTTP صورت می‌گیرد، بنابراین اسکریپت‌های شما هم می‌توانند همین کار را انجام دهند. این صفحه روش احراز هویت، منابعی که بیشترین استفاده را دارید، ساختار پاسخ‌ها و خطاها، و همچنین روش دنبال‌کردن رویدادها به‌صورت زنده از طریق WebSocket را توضیح می‌دهد.

مبانی

• آدرس پایه: https://chat.example.com/api/v4. همه‌ی نقاط پایانی زیر نسبت به این آدرس هستند.
• قالب: ورودی و خروجی به‌صورت JSON است، به‌جز بارگذاری فایل‌ها (multipart). Content-Type: application/json را ارسال کنید.
• شناسه‌ها: هر شیء یک id با ۲۶ کاراکتر دارد. زمان‌ها به‌صورت میلی‌ثانیه از مبدأ Unix هستند (create_at، update_at، delete_at؛ مقدار 0 به معنای «حذف‌نشده» است).
• جوامع همان تیم‌ها هستند: رسانه برنامه‌نویسی به آن‌ها teams می‌گوید و برای هر کدام یک team_id وجود دارد.
• خودتان: هر جا که در مسیر یک user_id لازم باشد، me به کاربر واردشده اشاره دارد، همان‌طور که در GET /users/me می‌بینید.

فهرست کامل نقاط پایانی در کد سرور قرار دارد: مسیرها در server/channels/api4/*.go و انواع داده در server/public/model تعریف شده‌اند. توضیحات OpenAPI در پوشه api/v4/source مخزن، نقاط پایانی ارث‌بری شده از Mattermost و برخی از افزوده‌های Antimatter را پوشش می‌دهد: انتقال رشته‌ها، اتصالات مدل، عامل‌ها، قوانین جامعه، حالت تمرکز و اقدامات پیام. سایر نقاط پایانی فقط در کد موجود هستند.

احراز هویت

هر درخواست، به‌جز ورود و چند نقطه پایانی عمومی، به یک توکن در هدر Authorization نیاز دارد:

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

سه نوع توکن در آنجا پذیرفته می‌شود: توکن‌های دسترسی شخصی، توکن‌های نشست و توکن‌های دسترسی OAuth. Authorization: Token … هم پذیرفته می‌شود. توکن‌ها در رشته پرس (query string) (?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 در پاسخ، راز (secret) است؛ 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" را اضافه کنید. نشست‌ها طبق تنظیمات نشست سرور منقضی می‌شوند و نقطه ورود (login endpoint) محدودیت نرخ دارد (۵ درخواست بر ثانیه). POST /users/logout نشست را پایان می‌دهد.

برنامه‌های OAuth 2.0

برای اینکه افراد بتوانند با حساب Antimatter خود به برنامه شما وارد شوند، یک برنامه OAuth 2.0 ثبت کنید. در این صورت Antimatter به عنوان ارائه‌دهنده OAuth عمل می‌کند:

1. گزینه فعال کردن OAuth 2.0 Service Provider باید فعال باشد (کنسول سیستم › ادغام ها › مدیریت یکپارچه سازی، ServiceSettings.EnableOAuthServiceProvider، به صورت پیش‌فرض فعال است).
2. شخصی که حق مدیریت برنامه‌های OAuth را دارد (به طور پیش‌فرض مدیران سیستم)، ادغام ها › برنامه‌های OAuth 2.0 (منوی جامعه › تنظیمات تیم › ادغام ها) را باز می‌کند و برنامه را همراه با URLهای بازگشتی آن اضافه می‌کند. سپس یک شناسه مشتری و یک رمز مشتری دریافت می‌کند.
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 برای تمدید) تبدیل می‌کند و با Authorization: Bearer <access token> به API دسترسی پیدا می‌کند.

کاربران می‌توانند برنامه‌هایی که به آن‌ها مجوز داده‌اند را در بخش مشخصات و تنظیمات › امنیت › برنامه‌هایی که به آن‌ها مجوز داده‌اید مشاهده کنند.

منابع اصلی

ارسال پیام

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" (به پیوست‌ها مراجعه کنید).

یافتن شناسه کانال

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 (یک شناسه پیام). پاسخ به‌صورت یک فهرست پیام برمی‌گردد: {"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 را به مدیر سرور ذکر کنید: این شناسه در لاگ‌ها موجود است.

محدودیت نرخ

محدود کردن نرخ به صورت پیش‌فرض غیرفعال است. وقتی یک مدیر سیستم آن را فعال می‌کند (کنسول سیستم › محیط › محدود کردن نرخ)، هر کلاینت به صورت پیش‌فرض ۱۰ درخواست در ثانیه با امکان افزایش تا ۱۰۰ درخواست (burst) مجاز است؛ این شمارش بر اساس آدرس IP یا کاربر انجام می‌شود. پاسخ‌ها هدرهای X-RateLimit-Limit، X-RateLimit-Remaining و X-RateLimit-Reset را همراه دارند؛ در صورت عبور از حد مجاز، سرور با کد 429 و هدر Retry-After (به ثانیه) پاسخ می‌دهد. برخی از نقاط پایانی (endpoints)، مانند ورود به سیستم، صرف‌نظر از تنظیمات، محدودیت اختصاصی خود را دارند.

اسکریپتی بنویسید که در صورت دریافت 429 صبر کند و دوباره تلاش کند، و از پُلینگ (polling) خودداری کنید: به جای آن از 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> مشخص می‌شوند.

شما همچنین می‌توانید عملیات (actions) ارسال کنید، هر کدام با یک 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) را به همه آن‌ها ارسال می‌کند.

کتابخانه‌های کلاینت

• برو: model.Client4 در مسیر server/public/model (با import کردن github.com/mattermost/mattermost/server/public/model). ابتدا model.NewAPIv4Client(url) را صدا بزنید، سپس client.SetToken(token) را؛ model.NewWebSocketClient4(wsURL, token) رویدادها را دنبال می‌کند. نسخه Antimatter روش‌هایی برای نقاط پایانی اختصاصی خود، مانند UpdateMessageRequest، PutPostOnTop و ExportChannel اضافه کرده است.
• TypeScript: کلاس Client4 از بسته @mattermost/client در مسیر webapp/platform/client، با تایپ‌های آن در 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 وجود ندارند. همه آن‌ها به یک نشست (session) نیاز دارند.

فیلدهای جدید

• جوامع (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 (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 یک وب‌هوکِ ورودی، در صورتی که کانالی با آن نام وجود نداشته باشد، کانال پیش‌فرض جامعه را برمی‌گردانند. در کدهای جدید از 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، نام‌گذاری‌شده بر اساس شناسه شخص دیگر، با مقدار 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 (شناسه پیش‌تنظیم مطابقت‌دار یا خالی برای تنظیمات سفارشی) وجود دارد. برای انجمن‌ها، am_forum_view (topics یا imageboard) نیز وجود دارد. نبود am_type در یک بارگذاری (payload) به این معناست که مقدار آن پر نشده است، نه اینکه کانال از نوع متنی است. پیام‌های مستقیم و گروهی هیچ‌کدام از این مقادیر را ندارند. به انواع کانال مراجعه کنید.

انواع کانال

یک کانال جامعه از نوع text، voice یا forum است (نوع آن هنگام ایجاد تعیین می‌شود و قابل تغییر نیست)، در یکی از حالت‌های آن نوع، با تنظیمات اضافه. یک پیش‌تنظیم (Preset) یک بسته نام‌دار از حالت و تنظیمات است که کلاینت آن را به عنوان یک گزینه واحد ارائه می‌دهد؛ پیش‌تنظیم‌ها ذخیره نمی‌شوند، بنابراین پیش‌تنظیم یک کانال (am_preset) از تنظیمات آن مشتق می‌شود و اگر با هیچ پیش‌تنظیمی مطابقت نداشته باشد، مقدار "" را برمی‌گرداند (که به معنای «سفارشی» است).

ایجاد و تغییر نوع کانال

POST /channels ابتدا props.am_preset را (پس از بسط دادن) و سپس props.am_type، am_mode، am_root_posts و am_forum_view را به‌عنوان تنظیمات فردی روی آن اعمال می‌کند؛ هر am_ دیگری نادیده گرفته می‌شود. ایجاد کانال صوتی زمانی که اپلیکیشن کانال‌های صوتی فعال نیست، رد می‌شود (400 api.channel.type.voice_unavailable.app_error)؛ همچنین ایجاد پیام مستقیم یا پیام گروهی با ویژگی‌های نوع کانال رد می‌شود (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"?, "mode"?, "root_posts"?, "view"?}، که پیش‌تنظیم ابتدا همانند زمان ایجاد باز می‌شود. این عمل نیازمند مجوز 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. خط کانالی که این فیلدها را نداشته باشد، به عنوان یک کانال چت متنی ساده وارد می‌شود، همانند قبل از وجود انواع کانال.

چه کسی مکالمات را شروع می‌کند یا موضوعات را باز می‌کند

برای ارسال پیام اصلی (در مقابل پاسخ) به مجوز create_root_post نیاز است که در ویرایشگر لغوها به صورت شروع گفتگوها (متن، صوتی) یا باز کردن موضوعات (انجمن‌ها) نمایش داده می‌شود. هیچ نقشی این مجوز را به صورت پیش‌فرض ندارد: قبل از اعمال لغوها، همه کسانی که اجازه ارسال دارند، در کانال‌هایی که مقدار 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 برای رد کردن با اولویت بالاتر. این بررسی برای API استراحتی، ربات‌ها، وب‌هوک‌های ورودی و خروجی (برای ایجادکننده وب‌هوک) و پاسخ‌های دستور اسلش انجام می‌شود؛ اما برای پست‌های ارسال‌شده توسط برنامه‌ها (از طریق API افزونه) و کپی‌های یک رشته منتقل‌شده انجام نمی‌شود (در عوض، فرد منتقل‌کننده رشته بررسی می‌شود). وارد کردن انبوه نیز از این بررسی صرف‌نظر می‌کند.

فروم‌ها فقط موضوع را می‌پذیرند

در یک فروم، پست ریشه‌ای نیاز به props.am_thread_title (عنوان موضوع آن) دارد که باید بدون فاصله‌های اضافی (trimmed)، بین ۱ تا ۱۰۰ کاراکتر باشد و از هر منبعی (شامل برنامه‌ها و رشته‌های منتقل‌شده) ارسال شود. اگر عنوان وجود نداشته باشد، خطای 400 app.post.forum.title_required.app_error و اگر طول آن بیش از حد باشد، خطای app.post.forum.title_too_long.app_error رخ می‌دهد. پاسخ‌ها به عنوان نیاز ندارند و هر عنوانی که همراه با پاسخ ارسال شود، نادیده گرفته می‌شود. ویرایش پست ریشه‌ای یک موضوع بدون عنوان یا با عنوان خالی، عنوان موجود آن را حفظ می‌کند؛ اما عنوان غیرخالی باعث تغییر نام آن می‌شود. انتقال یک رشته به داخل یک فروم (در ادامه) نیز نیاز به عنوان دارد، که از درخواست یا از خود رشته گرفته می‌شود.

پاسخ پذیرفته‌شده برای یک موضوع پرسش و پاسخ (am_accepted_answer، که شناسه یک پاسخ است) و وضعیت یک موضوع ایده (am_topic_status، همراه با am_topic_status_by و am_topic_status_at) تنها از طریق PATCH /posts/{post_id}/topic نوشته می‌شوند. اگر هر یک از این سه فیلد هنگام ایجاد، به‌روزرسانی یا پچ (patch) توسط یک کلاینت یا برنامه ارسال شود، نادیده گرفته می‌شود و مقدار ذخیره‌شده حفظ می‌گردد.

فهرست کردن موضوعات یک فروم

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

نیاز به حق خواندن کانال دارد. پارامترهای پرسش (Query parameters):

• sort: activity (پیش‌فرض)، newest، votes، unanswered (فقط برای پرسش و پاسخ) یا status (فقط برای ایده‌ها).
• answered (true/false، برای پرسش و پاسخ) و status (یکی از open، planned، in_progress، done، declined، برای ایده‌ها): برای فیلتر کردن بر اساس این موارد استفاده کنید. استفاده از هر یک خارج از حالت مربوطه منجر به خطای 400 می‌شود.
• mine=true: فقط موضوعاتی که شما شروع کرده‌اید. following=true: فقط موضوعاتی که آن‌ها را دنبال می‌کنید.
• q: با عنوان یا متن اولین پست مطابقت دارد، تا حداکثر ۲۰۰ کاراکتر.
• before: مقدار next_cursor صفحه‌ی قبلی. per_page: به‌طور پیش‌فرض ۲۵، حداکثر ۱۰۰. replies: ۰ تا ۵ پاسخ آخر هر موضوع، برای نمای تابلوی اعلانات.

پاسخ: {"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 (شناسه‌ی یک پاسخ، یا "" برای لغو آن) نیازمند یک انجمن پرسش و پاسخ است؛ 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 پیام (به‌طور پیش‌فرض ۱۰۰؛ ۰ برای بدون محدودیت) بیشتر باشد، رد می‌شود.

اشاره و یادداشت

جابه‌جایی دو پیام سیستمی از نوع system_wrangler باقی می‌گذارد: یک اشاره در کانال مبدأ ("رشته‌ای با ۱۳ پیام به #target جابه‌جا شده است") و یک یادداشت در مقصد ("این رشته از #source جابه‌جا شده است")، زیر رشته جابه‌جا شده یا، با flatten، بعد از پیام‌های آن. علاوه بر متن پیام، ویژگی‌های (props) آن‌ها به کلاینت اجازه می‌دهند نام کانال را به‌صورت پیوند نمایش دهد:

• اشاره: MovedThreadPermalink، NumMessages، MovedThreadChannelId، MovedThreadTeamName، MovedThreadPostId و، برای مقصد عمومی، MovedThreadChannelName و MovedThreadChannelDisplayName.
• یادداشت: MovedFromChannelId، MovedFromTeamName، MovedFromPostId (اشاره)، MovedFromPermalink و، برای مبدأ عمومی، MovedFromChannelName و MovedFromChannelDisplayName.

هر دو همچنین دارای TranslationID هستند. نام کانال خصوصی حذف می‌شود: خوانندگان «یک کانال دیگر» را می‌بینند. POST /posts/{post_id}/move خود Mattermost در Antimatter غیرفعال است؛ از این نقطه پایانی (endpoint) استفاده کنید.

قوانین انجمن

مدیران یک جامعه می‌توانند اعضا را ملزم کنند که قبل از ارسال پیام در کانال‌های آن، با قوانین موافقت کنند. تا زمانی که قوانین فعال هستند، عضوی که با نسخه فعلی موافقت نکرده است، نمی‌تواند پیامی ارسال کند، پاسخی بدهد، فایلی بفرستد، پیامی را زمان‌بندی کند، پیامی را ویرایش یا بازگرداند، یا دستوری را اجرا کند که منجر به ارسال پیام در کانال‌های جامعه شود؛ در این حالت سرور با کد 403 و شناسه api.post.community_rules_not_accepted پاسخ می‌دهد و پیام زمان‌بندی‌شده‌ای که در آن زمان باید ارسال می‌شد، با کد خطای community_rules_not_accepted شکست می‌خورد. خواندن پیام‌ها، واکنش‌ها، پیام‌های مستقیم و گروهی محدود نمی‌شوند؛ همچنین ربات‌ها، وب‌هوک‌های ورودی، پیام‌های سیستمی و مدیران جامعه (با مجوز manage_team که مدیران سیستم نیز دارند) از این محدودیت معاف هستند.

رویداد community_rules_updated به جامعه ارسال می‌شود زمانی که یک مدیر قوانین را ذخیره می‌کند (team_id، enabled، version)، و رویداد community_rules_accepted به کسی که موافقت کرده است، در تمام جلساتش ارسال می‌شود (team_id، version).

حالت تمرکز

حالت تمرکز همان «مزاحم نشوید» با یک زمان پایان است: اعلان‌ها بی‌صدا می‌شوند (هیچ اعلان push، ایمیل، دسکتاپ یا ماندگاری، از جمله پیام‌های فوری، ارسال نمی‌شود)، دلیل به عنوان وضعیت سفارشی با ایموجی 🎯 (dart) تنظیم می‌شود که در زمان پایان منقضی می‌شود، و اپلیکیشن‌های Antimatter نشان‌های خوانده‌نشده خودِ فرد را پنهان می‌کنند. فقط خودِ فرد می‌تواند از این نقاط پایانی استفاده کند (me یا شناسه خودش)؛ هیچ کس دیگر، از جمله مدیران سیستم، اجازه ندارد حالت تمرکز یا خلاصه آن را برای کسی شروع، پایان یا خوانده شود.

در حین تمرکز یک کاربر، کاربر او دارای ویژگی focus_until (میلی‌ثانیه) است که کلاینت‌ها از آن برای نمایش وضعیت تمرکز استفاده می‌کنند؛ این مقدار از طریق پروفایل قابل تغییر نیست. تمرکز زمانی پایان می‌یابد که کاربر آن را پایان دهد، زمان آن فرا برسد (در عرض یک دقیقه)، یا کاربر خودش وضعیتی را انتخاب کند که در آن صورت همان وضعیت باقی می‌ماند. در غیر این صورت، وضعیت و وضعیت سفارشی قبلی بازگردانده می‌شوند. سپس تمام جلسات کاربر رویداد focus_ended را با start_at، end_at و ended_by (user، timer یا status) دریافت می‌کنند.

اتصالات مدل

اتصال مدل، آدرس و کلید ارائه‌دهنده هوش مصنوعی است که توسط مدیر تنظیم می‌شود. قابلیت‌های هوش مصنوعی سرور و برنامه‌هایی که از سرویس هوش مصنوعی استفاده می‌کنند، از آن‌ها بهره می‌برند. مدیران سیستم اتصالات سراسری سرور را مدیریت می‌کنند (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 به معنای عدم وجود محدودیت است؛ درخواست‌ها در دقیقه برای هر سرور به‌شمار می‌روند و بودجه توکن‌ها برای کل خوشه بر اساس ماه تقویمی (UTC) محاسبه می‌شود. sharing مشخص می‌کند کدام جوامع می‌توانند از اتصال کل سرور استفاده کنند (برای پیام‌های مستقیم و گروهی، all_teams لازم است) و audience مشخص می‌کند چه کسانی می‌توانند از آن استفاده کنند؛ مهمان‌ها فقط در صورت فعال بودن allow_guests. تغییرات در گزارش ممیزی ثبت می‌شوند. راهنمای مدیران این تنظیمات را توضیح می‌دهد: هوش مصنوعی را ببینید.

عامل‌ها

یک عامل، حساب رباتی از نوع agent است (با is_agent روی کاربر آن)، همراه با تنظیماتش: دامنه آن (server، یا شناسه یک جامعه)، داخلی یا external، و برای یک عامل داخلی، اتصال مدل، مدل، پرامپت سیستمی و استدلال آن. مدیران سیستم، عامل‌های سطح سرور را مدیریت می‌کنند (manage_system)، و مدیران یک جامعه، عامل‌های جامعه خود را (manage_team)؛ علاوه بر این، manage_own_agent برای عاملی که خودشان ساخته‌اند و manage_others_agent برای سایرین. شناسه عامل در این مسیرها، شناسه کاربری آن است. اجرای یک عامل خارجی و نحوه تعیین وضعیت یک عامل داخلی در ربات‌ها توضیح داده شده است؛ 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 لیست عامل‌هایی که می‌توانید با آن‌ها صحبت کنید را به همان شکلی که اپلیکیشن چت هوش مصنوعی آن‌ها را می‌خواند، ارائه می‌دهد.