API پیام رسانی در زمان واقعی

API پیام رسانی میراث واقعی یک API مبتنی بر WebSocket است که به شما امکان می دهد رویدادهایی را از Slack در زمان واقعی دریافت کنید و به عنوان کاربران از جمله کاربران BOT پیام ارسال کنید. گاهی اوقات به عنوان "RTM API" گفته می شود.

این زمانی مبنای کلیه مشتری های Slack بود و زمانی که معمولاً با کاربران BOT استفاده می شد تا ربات های یاور را برای فضای کاری شما ایجاد کنند.

توصیه می کنیم به جای آن ، با استفاده از API رویدادهای مبتنی بر HTTP ، رویدادهایی را به سمت شما سوق دهید. بیشتر انواع رویداد پشتیبانی شده RTM API نیز توسط API رویدادها پشتیبانی می شود. اگر واقعاً WebSockets را دوست دارید ، حالت سوکت برای برنامه ها به جای آن اشتراک های رویداد را از طریق WebSockets ارائه می دهد.

بسیاری از مدیران فضای کاری به دلیل داشتن مجوزهای مجوز بیش از حد مجاز برای عملکرد خود ، برنامه ها و ادغام ها را با استفاده از RTM API مجاز نمی کنند. برنامه های Slack مدرن به شما امکان می دهد تا در رویدادها مشترک شوید و فقط برای داده هایی که برنامه شما واقعاً برای کار کردن نیاز دارد ، مجوزها را درخواست کنید.

اعلامیه ها

این API باستانی است و راه های دسترسی به آن با گذشت زمان محدودتر شده است. لطفاً این لقب هشدارها را ببخشید و به اقدامات زیر مراجعه کنید.

این پلتفرم نزدیک به یک دهه تکامل یافته است و ما به دنبال تحکیم برخی از قدیمی ترین راه های خود برای ادغام و گسترش Slack هستیم.

برنامه های جدید Slack ممکن است از هیچ روش API پیام رسانی در زمان واقعی استفاده نکنند. یک برنامه کلاسیک ایجاد کنید و از جریان V1 OAuth برای استفاده از RTM استفاده کنید.

برای اکثر برنامه ها ، حالت سوکت راهی بهتر برای برقراری ارتباط با Slack است.

اصول اولیه

برای شروع جلسه RTM ، یک تماس معتبر به روش API RTM. Coect انجام دهید. این یک مجموعه اولیه از ابرداده فضای کاری و URL WebSocket Server Server Server را فراهم می کند. پس از اتصال به سرور پیام ، جریان رویدادهایی از جمله پیام و به روزرسانی به وضعیت فعلی فضای کاری ارائه می شود. این به مشتری اجازه می دهد تا به راحتی یک کپی محلی هماهنگ از کلیه داده ها و پیام های فضای کاری را حفظ کند.

URL های WebSocket ارائه شده توسط RTM. Coect یکبار مصرف هستند و فقط برای 30 ثانیه معتبر هستند ، بنابراین حتماً به سرعت متصل شوید. اگر با موفقیت وصل شوید ، اولین رویداد دریافت شده سلام خواهد بود:

این اتفاق می افتد با هر رویدادی که بین تماس با RTM. Coect و اتصال به سرور پیام رخ داده است. اگر بعد از یک مشکل شبکه دوباره به هم وصل می شوید ، این مجموعه اولیه از رویدادها ممکن است شامل پاسخی به آخرین پیام ارسال شده در اتصال قبلی (با پاسخ_ت) باشد تا مشتری بتواند تأیید کند که پیام دریافت شده است.

اگر مشکلی برای اتصال یک خطا وجود داشته باشد ، از جمله پیام خطای توصیفی:

مناسبت ها

تقریباً هر اتفاقی که در Slack رخ می دهد منجر به ارسال یک رویداد به کلیه مشتری های متصل خواهد شد. ساده ترین رویداد پیامی است که از یک کاربر ارسال می شود:

هر رویدادی دارای یک ویژگی نوع است که نوع رویداد را توصیف می کند. سرورهای ما در حال حاضر انواع رویداد زیر را ارسال می کنند:

لیست حساب هایی که کاربر امضا کرده است تغییر کرده است

کاربر روی برنامه برنامه شما کلیک کرد

فقط در رویدادهای پیام که برنامه یا ربات شما را ذکر می کنند مشترک شوید

نشان می دهد اشتراک های رویداد برنامه شما محدود است

کاربر درخواست برنامه کرد

برنامه Slack شما حذف نشده است.

یک کاربر ربات اضافه شد

یک کاربر ربات تغییر یافت

یک تماس رد شد

یک کانال بایگانی شد

یک کانال ایجاد شد

یک کانال حذف شد

به روزرسانی های فله به تاریخچه کانال ساخته شد

شناسه کانال تغییر کرد

شما به یک کانال پیوستید

نشانگر خواندن کانال شما به روز شد

یک کانال تغییر نام داد

یک کانال با یک فضای کاری خارجی به اشتراک گذاشته شده است

یک کانال بدون مجوز بود

یک کانال با یک فضای کاری خارجی بی نظیر بوده است

یک دستور slash اضافه شده یا تغییر یافته است

تنظیمات را برای کاربر فعلی تغییر ندهید

تنظیمات را برای یک عضو تغییر ندهید

دامنه ایمیل فضای کاری تغییر کرده است

یک ایموجی سفارشی اضافه شده یا تغییر یافته است

مهاجرت شبکه سازمانی در فضای کاری خارجی به پایان رسیده است.

مهاجرت شبکه سازمانی در فضای کاری خارجی آغاز شده است.

یک نظر پرونده اضافه شد

یک نظر پرونده حذف شد

یک نظر فایل ویرایش شد

پرونده ای علنی شد

یک پرونده بی نظیر بود

سرور قصد دارد به زودی اتصال را ببندد.

مهاجرت شبکه سازمانی در این فضای کاری به پایان رسیده است.

مهاجرت شبکه سازمانی در این فضای کاری آغاز شده است.

یک کانال خصوصی بایگانی شد

شما یک کانال خصوصی را بستید

یک کانال خصوصی حذف شد

به روزرسانی های فله به تاریخچه کانال خصوصی ساخته شد

شما به یک کانال خصوصی پیوستید

شما یک کانال خصوصی را ترک کردید

یک نشانگر خواندن کانال خصوصی به روز شد

شما یک گروه DM ایجاد کردید

یک کانال خصوصی تغییر نام داد

یک کانال خصوصی بدون مجوز بود

مشتری با موفقیت به سرور متصل شده است

به روزرسانی های فله به تاریخ DM ساخته شد

یک نشانگر خواندن پیام مستقیم به روز شد

کاربر درخواست دعوت کرد

پیامی ارسال شده است که شامل یک یا چند لینک مربوط به برنامه شما است

شما به طور دستی حضور خود را به روز کردید

یک کاربر به یک کانال عمومی ، کانال خصوصی یا MPDM پیوست.

یک کاربر یک کانال عمومی یا خصوصی را ترک کرد

یک پیام به یک کانال ارسال شد

کاربر پیامی را به برنامه Slack شما ارسال کرد

یک پیام به یک کانال ارسال شد

پیامی به یک کانال خصوصی ارسال شد

یک پیام در یک کانال پیام مستقیم ارسال شد

یک پیام در یک کانال پیام مستقیم چند منظوره ارسال شد

ابرداده پیام حذف شد

ابرداده پیام ارسال شد

ابرداده پیام به روز شد

یک پین به یک کانال اضافه شد

یک پین از یک کانال برداشته شد

ترجیحات خود را به روز کرده اید

حضور یک عضو تغییر کرد

وضعیت حضور فعلی را برای لیستی از کاربران تعیین کنید

برای کاربران مشخص در رویدادهای حضور مشترک مشترک شوید

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

یک عضو واکنش ایموجی را حذف کرد

دسترسی به مجموعه ای از منابع برای برنامه شما اعطا شد

دسترسی به مجموعه ای از منابع برای برنامه شما حذف شد

Oauth Scopes به برنامه شما رد شد

Oauth Scopes به برنامه شما اعطا شد

یک دعوت کانال مشترک پذیرفته شد

یک دعوت کانال مشترک تصویب شد

یک دعوت کانال مشترک رد شد

یک دعوت کانال مشترک به کاربر Slack ارسال شد

یک عضو یک مورد را بازی کرده است

یک عضو یک ستاره را حذف کرد

یک گروه کاربر به فضای کاری اضافه شده است

عضویت در یک گروه کاربر موجود تغییر کرده است

شما به یک گروه کاربر اضافه شده اید

شما از یک گروه کاربر حذف شده اید

یک گروه کاربر موجود به روز شده است یا اعضای آن تغییر کرده اند

دسترسی به مجموعه ای از تیم ها به برنامه ORG شما اعطا شد

دسترسی به مجموعه ای از تیم ها از برنامه ORG شما ابطال شد

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

یک عضو جدید پیوسته است

فضای کاری بین سرورها مهاجرت می شود

برنامه صورتحساب حساب تغییر کرده است

اولویت به روز شده است

قسمتهای پروفایل فضای کاری به روز شده اند

زمینه های مشخصات فضای کاری حذف شده اند

زمینه های مشخصات فضای کاری دوباره مرتب شده اند

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

نشانه های API برای برنامه شما لغو شد.

مالکیت یک URL درخواست API رویدادها را تأیید می کند

داده های یک عضو تغییر کرده است

وضعیت هدر کاربر تغییر کرده است

داده های پروفایل کاربر تغییر کرده است

منبع کاربر به برنامه شما رد شد

منبع کاربر به برنامه شما اعطا شد

منبع کاربر از برنامه شما حذف شد

وضعیت کاربر تغییر کرده است

یک عضو کانال در حال تایپ پیام است

گردش کاری که شامل گامی است که توسط برنامه شما پشتیبانی می شود حذف شد

گردش کاری که شامل گامی است که توسط برنامه شما پشتیبانی می شود منتشر شد

یک مرحله کار پشتیبانی شده توسط برنامه شما از یک گردش کار حذف شد

یک مرحله کار پشتیبانی شده توسط برنامه شما باید اجرا شود

گردش کاری که شامل گامی است که توسط برنامه شما پشتیبانی می شود منتشر نشده است

در آینده انواع رویداد جدید اضافه می شود ، مشتریان باید بتوانند انواع رویدادهای غیر منتظره را کنترل کنند.

ارسال پیام

با ارسال JSON از طریق اتصال WebSocket می توانید پیامی را به Slack ارسال کنید.

هر رویدادی باید یک شناسه عدد صحیح مثبت (برای آن اتصال) داشته باشد. تمام پاسخ های مربوط به آن پیام شامل این شناسه است که به مشتری اجازه می دهد تا پاسخ ها را با پیام های ارسال شده در ارتباط باشد. پاسخ ها به دلیل ماهیت ناهمزمان سرورهای پیام ممکن است "خارج از نظم" باشد.

همچنین ، مانند رویدادهای ارسال شده از سرور ، هر رویداد ارسال شده توسط مشتری دارای نوع رشته ای است که پیام را مشخص می کند - پیام های گپ از نوع پیام هستند.

انتخاب کانال

بنابراین برای ارسال متن "سلام جهان" به یک کانال ، می توانید این JSON را ارسال کنید:

می توانید به همان روش به یک گروه خصوصی یا کانال پیام مستقیم پیام ارسال کنید ، اما با استفاده از شناسه گروهی (C024BE91L) یا شناسه کانال پیام مستقیم (D024BE91L).

برای ارسال پیامی هم به عنوان و هم به کاربر تأیید کننده ، از شناسه کانال پیام مستقیم مستقیم برای آن کاربر استفاده کنید. شناسه پیام مستقیم را می توان به عنوان بخشی از پاسخ به RTM. Coect یا با مشاوره در مورد مکالمات. لیست یافت.

قالب بندی پیام ها

RTM API فقط از ارسال پیام های ساده فرمت شده با استفاده از حالت قالب بندی پیام پیش فرض ما پشتیبانی می کند. این از پیوست ها یا سایر حالت های قالب بندی پیام پشتیبانی نمی کند. برای ارسال یک پیام پیچیده تر به عنوان یک مشتری کاربر می تواند با روش API Web. postmessage با AS_USER تنظیم شود.

ذکر کاربر از طریق RTM باید از نحو مبتنی بر شناسه استفاده کند:

پاسخهای

پس از ارسال JSON به سرور بصری ، مشتری های بصری باید بلافاصله متن را در کانال نمایش دهند ، خاکستری شده یا در غیر این صورت مشخص شده اند تا نشان دهند که "در انتظار" است. در بعضی از مواقع ، معمولاً چند میلی ثانیه بعد ، سرور تأیید می کند که پیام دریافت شده است:

پاسخ به پیام های ارسال شده توسط مشتری ها همیشه حاوی دو ویژگی خواهد بود: یک OK Boolean که نشان می دهد آنها موفق شده اند و یک عدد صحیح پاسخ داده شده است که نشان می دهد در پاسخ به کدام پیام است.

در صورت پاسخ به پیام گپ ، در صورت موفقیت ، پاسخ شامل زمان بندی ضبط شده متعارف پیام خواهد بود. تمام پیام های موجود در یک کانال واحد تضمین شده است که دارای یک جدول زمانی منحصر به فرد است که ASCII قابل مرتب سازی است. با توجه به دقت زمان بندی ، مشتری ها باید با این جدول زمانی به عنوان رشته ها رفتار کنند ، نه شناورها/دونفره. پس از بازگشت پاسخ موفقیت آمیز ، پیام موجود در گپ دیگر نباید از خاکستری خارج شود - اکنون تحویل داده شده است.

پاسخ پیام چت همچنین حاوی متن پیام است که ممکن است به دلیل تشخیص URL از پیام ارسال شده متفاوت باشد.

خطاها

در صورت وجود خطایی در حال پردازش یک رویداد ، سرور پیام با خطا پاسخ می دهد. مثلا:

نشانگرهای تایپ کردن

مشتریان می توانند یک نشانگر تایپ را ارسال کنند تا نشان دهد کاربر در حال حاضر در حال نوشتن پیام برای ارسال به یک کانال است:

این می تواند در هر مطبوعات کلیدی در ورودی چت ارسال شود مگر اینکه یکی در سه ثانیه آخر ارسال شده باشد. مگر اینکه خطایی رخ دهد که سرور پاسخی ارسال نمی کند ، اما یک رویداد "user_typing" را به همه اعضای فضای کاری در کانال ارسال می کند.

حضور

کاربر و حضور کاربر ربات در API RTM به اندازه کافی پیچیده است تا یک سند کامل را تضمین کند. همه چیز را در مورد اشتراک های حضور و رویدادهای حضور دسته ای در اینجا بیاموزید.

حضور RTM API اکنون فقط از طریق اشتراک در دسترس است. از ژانویه سال 2018 ، رویدادهای requend_change بدون اشتراک های حضور با حضور_ sub اعزام نمی شوند. به همین ترتیب ، وضعیت حضور کاربر فعلی دیگر در RTM. Start ابلاغ نمی شود. بیشتر بدانید.

پینگ و پنگ

مشتریان باید سعی کنند قطع ارتباطات را حتی در دوره های بیکار تشخیص دهند تا کاربران بتوانند به راحتی تفاوت بین قطع ارتباط و ساکت بودن را بیان کنند. همه مرورگرهای وب از مشخصات پینگ WebSocket پشتیبانی نمی کنند ، بنابراین پروتکل RTM همچنین از پیام های پینگ/pong پشتیبانی می کند. هنگامی که هیچ فعالیت دیگری وجود ندارد ، مشتری ها باید هر چند ثانیه پینگ را ارسال کنند. برای ارسال پینگ ، JSON زیر را ارسال کنید:

شما می توانید هر تعداد آرگومان اضافی "مسطح" را تهیه کنید (یعنی: فقط مقادیر مقیاس ، بدون آرایه یا اشیاء). اینها در پیام PONG که ارسال می شود گنجانده می شود. به عنوان مثال ، یک مشتری می تواند یک جدول زمانی محلی را در پیام پینگ درج کند تا بتواند تأخیر سفر دور را محاسبه کند:

این در پاسخ از سرور گنجانده شده است:

محدودیت

سرور پیام هر مشتری را که بیش از 16 کیلوبایت پیام ارسال می کند ، قطع می کند. این شامل تمام قسمت های پیام ، از جمله نحو JSON ، نه فقط متن پیام است. مشتریان باید پیام های ارسال شده به کانال ها را به 4000 کاراکتر محدود کنند ، که همیشه زیر 16K بایت حتی با پیامی که فقط از شخصیت های غیر BMP Unicode در هر 4 بایت تشکیل شده است ، قرار می گیرند. اگر پیام طولانی تر است ، مشتری باید پیام را به چندین پیام تقسیم کند ، یک قطعه ایجاد کند یا یک پست ایجاد کند.

مانند همه API های Slack ، API RTM در معرض محدودیت نرخ است. مشتریان نباید بیش از یک پیام در هر ثانیه پایدار ارسال کنند. اگر انجام دهید ممکن است یک پیام خطا دریافت کنید یا قطع شوید.

WebSocket چیست؟

WebSockets یک روش استاندارد برای باز کردن یک کانال ارتباطی دو جهته با یک سرور بیش از TCP است. این پروتکل مورد استفاده در هنگام اتصال به API RTM ما است. بسیاری از کمک های جامعه ما از جزئیات اتصال به Slack از طریق WebSocket پشتیبانی می کند.

اتصال با rtm. coect در مقابل rtm. start

در حال حاضر دو راه برای رزرو اتصالات WebSocket وجود دارد.

RTM. Coect فقط با اتصال برنامه شما به RTM API نگران است و فقط شامل اطلاعات محدودی در مورد کاربر اتصال دهنده و فضای کاری مسکن است.

RTM. Start نه تنها یک سینک آشپزخانه کامل بلکه کل آشپزخانه پر از اطلاعاتی در مورد کاربر ، فضای کاری آن ، کانال های آن ، وضعیت فعلی آن در جهان را شامل می شود. RTM. Start به طور طبیعی استفاده از شبکه سازمانی و سایر مناطق بزرگ کار دشوارتر است.

ما اکیداً توصیه می کنیم از RTM. Coect برای رزرو اتصالات WebSocket خود استفاده کنید و از API وب به طور هم زمان استفاده کنید تا تمام اطلاعات دولتی را که برنامه شما نیاز دارد جمع آوری کنید.

رویدادهای API در مقابل RTM API

هر دو API به دلایل مختلف مفید هستند ، با وجود این که هر دو به یک نوع داده ارائه می دهند. دریابید که چرا یک یا دیگری (یا هر دو!) را در API FAQ رویدادها انتخاب کنید.

یک برنامه کلاسیک Slack ایجاد کنید

از آنجا که برنامه های جدید Slack به RTM. Coect وصل نمی شوند ، برای شروع کار باید یک برنامه کلاسیک Slack داشته باشید. اگر هنوز یکی از آنها را ایجاد نکرده اید ، اینجا را کلیک کنید تا یکی از آنها را تهیه کنید: