وب‌هوک سازوکاری برای ارسال خودکار داده‌ها میان سایت‌ها و برنامه‌ها هنگام رویدادهای مشخص است. داده‌ها با درخواست HTTP منتقل می‌شوند: یک برنامه آن‌ها را از طریق اینترنت به نشانی از پیش تعیین‌شدهٔ برنامهٔ دیگر می‌فرستد.
قابلیت‌های وب‌هوک‌ها
در FLOWIN، وب‌هوک‌ها با انتقال‌ها کار می‌کنند. ممکن است هنگام ایجاد، ویرایش، حذف یا سنجاق شدن پیام در گفتگوی اصلی (مبدأ) و همچنین هنگام کلیک روی دکمه در گفتگویی که پیام‌ها به آن منتقل می‌شوند (مقصد) فعال شوند.
به این ترتیب می‌توانید FLOWIN را به شبکه‌های اجتماعی، صرافی‌ها، جدول‌ها و CRM (سیستم‌های مدیریت ارتباط با مشتریان) متصل کنید. چنین ارتباطی یکپارچه‌سازی نام دارد و این امکان‌ها را فراهم می‌کند:
- افزودن خودکار درخواست‌ها از Telegram به CRM.
- ارسال سیگنال‌های معاملاتی از Telegram به صرافی برای دنبال کردن خودکار، یعنی انجام خودکار معامله‌ها بر اساس این سیگنال‌ها.
- انتقال پیام‌ها از Telegram به شبکه‌های اجتماعی دیگر.
- کپی پست‌ها و پیام‌ها در Google Sheets.
- راه‌اندازی پاسخ‌گوی خودکار در ربات.
برای هر کاربرد، باید دریافت داده‌ها و عمل موردنظر را در سمت سایت یا برنامه تنظیم کنید.
ایجاد وب‌هوک
وب‌هوک را در سایت webhook.site امتحان می‌کنیم؛ این سایت نشانی دریافت داده می‌دهد و درخواست‌های دریافتی را نشان می‌دهد. متن پیام جدیدی از Telegram را به آن می‌فرستیم.
برای این کار به یک انتقال تنظیم‌شده و فعال در FLOWIN نیاز دارید.
برای اولین آزمایش
از گفتگوی آزمایشی جداگانه و درخواست ساختگی استفاده کنید. برای بررسی، فرستادن متن بدون نام، شماره تلفن و دیگر داده‌های شخصی کافی است.
ربات @flow_in_bot را باز کنید، فرمان
/startرا بفرستید و روی «پنل مدیریت» بزنید.
ورود به پنل مدیریت از طریق @flow_in_bot. سایت webhook.site را در زبانه‌ای جداگانه باز کنید. نشانی دریافت درخواست‌ها را از فیلد «Your unique URL» کپی کنید.
نشانی دریافت درخواست آزمایشی. در پنل FLOWIN، «منو» ← «وب‌هوک‌ها» را باز کنید و «ایجاد» را بزنید.
بخش «وب‌هوک‌ها» در منوی FLOWIN. 
ایجاد اولین وب‌هوک. نشانی کپی‌شده را در فیلد بالایی جای‌گذاری کنید. در فیلد «بدنه درخواست»،
{"message":"<message-text>"}را وارد کنید و «ایجاد» را بزنید. این الگوی داده‌های ارسالی است: FLOWIN به‌جای<message-text>متن پیام را قرار می‌دهد و گیرنده آن را در فیلدmessageمی‌بیند.
نشانی و بدنهٔ درخواست آزمایشی. کنار وب‌هوک ایجادشده، «اعمال» را بزنید. انتقال موردنظر را علامت بزنید و «ذخیره» را بزنید.
اتصال وب‌هوک به انتقال. 
انتخاب انتقال برای وب‌هوک. یک پیام آزمایشی به گفتگوی مبدأ بفرستید؛ برای مثال «درخواست شمارهٔ 1042: کاتالوگ مبلمان لازم دارم.». به webhook.site برگردید: اولین درخواست دریافتی خودکار باز می‌شود. در بخش «Request Content»، متن درخواست در فیلد
messageظاهر می‌شود. اکنون FLOWIN متن هر پیام جدید را پیش از انتقال آن به گفتگوی مقصد، خودکار به نشانی تعیین‌شده می‌فرستد.
درخواست آزمایشی در گفتگوی مبدأ. 
متن درخواست دریافت‌شده در webhook.site.
تنظیمات وب‌هوک‌ها
تنظیمات را با وب‌هوک ایجادشده بررسی می‌کنیم: چگونه آن‌ها را تغییر دهیم و هر فیلد چه معنایی دارد.
تنظیمات را از کجا بگیریم
برای اتصال سایت یا برنامه‌ای دیگر، از مستندات آن استفاده کنید. معمولاً قواعد دریافت داده در بخش API قرار دارند که ارتباط با برنامه‌های دیگر را توضیح می‌دهد. نشانی، روش HTTP و قالب داده برای پر کردن فیلدهای زیر در آن مشخص شده‌اند.
چگونه تنظیمات وب‌هوک را تغییر دهیم
در فهرست «وب‌هوک‌ها»، کنار وب‌هوک موردنظر «تغییر» را بزنید.
باز کردن تنظیمات وب‌هوک. فیلدهای موردنظر را تغییر دهید و «ذخیره» را بزنید.
ذخیرهٔ تنظیمات تغییرکرده. 
توضیح در تنظیمات وب‌هوک ذخیره شده است.
روش HTTP
روش HTTP، عمل درخواست را مشخص می‌کند: POST داده‌ها را برای پردازش می‌فرستد، GET داده‌ها را درخواست می‌کند و PUT آن‌ها را جایگزین می‌کند. POST به‌صورت پیش‌فرض انتخاب شده و برای آزمایش ما مناسب است. برای سایت یا برنامه‌ای دیگر، روشی را انتخاب کنید که در مستندات آن آمده است.
نشانی URL
URL یعنی نشانی در اینترنت. در این قسمت، نشانی دریافت داده را وارد می‌کنید که از سایت یا برنامهٔ مورداتصال گرفته‌اید. در مثال ما، webhook.site آن را داده است.
بدنه درخواست
بدنهٔ درخواست، داده‌های ارسالی را در قالب JSON نگه می‌دارد: جفت‌های «نام فیلد: مقدار». مجموعهٔ فیلدها به الزامات سایت یا برنامهٔ مورداتصال بستگی دارد.
متاتگ‌ها نشانه‌هایی هستند که FLOWIN داده‌های پیام را جای آن‌ها قرار می‌دهد. برای مثال، <message-text> با متن و <author-name> با نام نویسنده جایگزین می‌شود. فهرست متاتگ‌ها با لینک «متاتگ‌ها» در زیر فیلد نیز باز می‌شود.
شماره‌های کاربران، پیام‌ها، گفتگوها و موضوع‌ها در فهرست زیر، همان شناسه‌های (ID) آن‌ها در Telegram هستند.
پیام و نویسنده
- متن پیام:
<message-text>. - تاریخ پیام:
<message-date>. - زمان پیام:
<message-time>. - شناسهٔ نویسنده:
<author-id>. - نام نویسنده:
<author-name>. - نام نویسنده در لینک HTML به پروفایل او:
<author-name-link>. - نام نویسنده به‌صورت هشتگ:
<author-name-tag>. - نام کاربری نویسنده:
<author-username>.
مبدأ
- متن پیام:
<src-message-text>. - شناسهٔ پیام:
<src-message-id>. - لینک پیام:
<src-message-link>. - شناسهٔ گفتگو:
<src-chat-id>. - نام گفتگو:
<src-chat-name>. - نام کاربری گفتگو:
<src-chat-username>. - شناسهٔ موضوع:
<src-topic-id>. - نام موضوع:
<src-topic-name>.
مقصد
- متن پیام:
<dst-message-text>. - شناسهٔ پیام:
<dst-message-id>. - لینک پیام:
<dst-message-link>. - شناسهٔ گفتگو:
<dst-chat-id>. - نام گفتگو:
<dst-chat-name>. - نام کاربری گفتگو:
<dst-chat-username>. - شناسهٔ موضوع:
<dst-topic-id>. - نام موضوع:
<dst-topic-name>.
شناسه و لینک پیام در مقصد، پس از انتقال در دسترس قرار می‌گیرند. برای فرستادن آن‌ها، در فیلد «تریگر درخواست» گزینهٔ «پس از ارسال» را انتخاب کنید.
کلیک روی دکمه
- شناسهٔ کاربرِ کلیک‌کننده:
<clicker-id>. - نام کاربرِ کلیک‌کننده:
<clicker-name>. - داده‌های دکمه:
<clicker-data>. - تاریخ کلیک:
<click-date>. - زمان کلیک:
<click-time>.
انتخاب متن
- عبارت منظم، قاعدهٔ جستجوی متن را تعیین می‌کند. برای مثال،
<regexp>(short|sell)</regexp>اولین تطبیق پیداشده باshortیاsellرا قرار می‌دهد. - متن تصادفی
<random>1|2|3|4|5</random>یکی از پنج گزینه را قرار می‌دهد. می‌توانید گزینه‌های خود را میان تگ‌ها بنویسید و آن‌ها را با نویسهٔ|از هم جدا کنید.
هدرهای درخواست
«هدرهای درخواست»، اطلاعات جانبی برای گیرنده را نگه می‌دارند. برای مثال، کلید دسترسی امکان بررسی فرستندهٔ درخواست را می‌دهد. هدرها در قالب JSON تعیین می‌شوند. معمولاً نیازی به تغییر این فیلد نیست؛ مقدارهای لازم را از مستندات سایت یا برنامهٔ مورداتصال می‌گیرید.
تریگر درخواست
«تریگر درخواست»، رویداد و زمانی را تعیین می‌کند که وب‌هوک باید درخواست را به نشانی مشخص‌شده بفرستد. می‌توانید این رویدادها را انتخاب کنید:
- «ارسال» به‌صورت پیش‌فرض انتخاب شده است. وب‌هوک هنگام انتقال پیام جدید فعال می‌شود.
- «ویرایش» هنگام پردازش تغییر پیام در مبدأ فعال می‌شود.
- «سنجاق» هنگام پردازش سنجاق شدن پیام در مبدأ فعال می‌شود.
- «حذف» هنگام پردازش حذف پیام در مبدأ فعال می‌شود.
- «کلیک روی دکمه» برای دکمه‌های کال‌بک در گفتگوی مقصد فعال می‌شود. چنین دکمه‌ای ربات را از کلیک باخبر می‌کند و داده‌های تعیین‌شده برای آن را می‌فرستد. دکمهٔ معمولی دارای لینک، این وب‌هوک را فعال نمی‌کند.
زمان ارسال تعیین می‌کند درخواست در کدام مرحلهٔ انتقال فرستاده شود:
- «پیش از پردازش»: درخواست پیش از ترجمه و پردازش پیام با هوش مصنوعی فرستاده می‌شود.
- «پس از پردازش»: درخواست پس از ترجمه و پردازش هوش مصنوعی فرستاده می‌شود.
- «پس از ارسال»: درخواست زمانی فرستاده می‌شود که پیام با موفقیت به گفتگوی مقصد ارسال یا در آن ویرایش شده باشد.
زمان‌های ارسال در دسترس
هر سه گزینه برای رویدادهای «ارسال» و «ویرایش» در دسترس هستند. برای «سنجاق»، «حذف» و «کلیک روی دکمه»، از «پیش از پردازش» استفاده می‌شود و انتخاب زمان دیگری ممکن نیست.
توضیحات
«توضیحات»، یادداشتی برای راحتی شماست و بر عملکرد وب‌هوک تأثیری ندارد. می‌توانید فیلد را خالی بگذارید.
کارهای قابل انجام با وب‌هوک
می‌توانید وب‌هوک‌های ایجادشده را از فهرست «وب‌هوک‌ها» مدیریت کنید:
- «تغییر»، تنظیمات اصلی وب‌هوک را باز می‌کند.
- «تکثیر» در منوی «بیشتر»، کپی تنظیمات وب‌هوک را می‌سازد.
- «انتخاب پروژه» در منوی «بیشتر»، وب‌هوک را به پروژه اضافه می‌کند.
- «حذف» در منوی «بیشتر»، وب‌هوک را حذف می‌کند.
همچنین هر وب‌هوک دکمهٔ «انتقال‌ها [N]» دارد که انتخاب انتقال‌های متصل به آن را باز می‌کند. N تعداد انتقال‌های انتخاب‌شده را نشان می‌دهد. اگر هنوز انتقالی انتخاب نشده باشد، به‌جای آن دکمهٔ «اعمال» نمایش داده می‌شود.
پرسش‌های متداول
وب‌هوک به زبان ساده چیست؟
روشی برای فرستادن خودکار داده به برنامه‌ای دیگر هنگام رویدادی مشخص است. برای مثال، هنگام انتقال پیام جدید، FLOWIN متن آن را با درخواست HTTP به نشانی تعیین‌شدهٔ شما می‌فرستد. اینجا FLOWIN درخواست را می‌فرستد؛ روش setWebhook در Telegram، جهت دیگری را تنظیم می‌کند: رساندن به‌روزرسانی‌ها از Telegram به برنامه‌ای که ربات را اداره می‌کند.
آیا وارد کردن نشانی CRM کافی است؟
خیر. به نشانی دریافت داده از مستندات CRM و روش HTTP، فیلدهای JSON و هدرهای مناسب، اگر برای دسترسی لازم باشند، نیاز دارید. نشانی معمولی سایت CRM برای این کار مناسب نیست. FLOWIN درخواست را می‌فرستد و ثبت درخواست یا انجام عمل دیگر به نحوهٔ پردازش داده‌های دریافتی در CRM بستگی دارد. مقدارهای فیلدها در بخش «تنظیمات وب‌هوک‌ها» توضیح داده شده‌اند.
چرا لینک پیام در مقصد خالی است؟
پیش از ارسال موفق پیام جدید، FLOWIN هنوز شناسه و لینک آن را در مقصد ندارد. برای فرستادن <dst-message-id> و <dst-message-link> رویداد «ارسال» یا «ویرایش» و زمان «پس از ارسال» را در فیلد «تریگر درخواست» انتخاب کنید. لینک برای کانال‌ها و سوپرگروه‌ها ساخته می‌شود. برای گفتگوی خصوصی یا گروه معمولی، <dst-message-link> حتی پس از ارسال هم خالی می‌ماند.
آیا می‌توان وب‌هوک را با کلیک روی دکمهٔ معمولی URL فعال کرد؟
خیر. دکمهٔ معمولی URL، لینک را باز می‌کند. برای رویداد «کلیک روی دکمه»، دکمهٔ کال‌بک در گفتگوی مقصد لازم است: این دکمه داده‌های کلیک را به ربات می‌فرستد. این تفاوت در بخش «تریگر درخواست» توضیح داده شده است.
چگونه بررسی کنیم که سرویس خارجی داده‌ها را گرفته است؟
پیامی ساختگی بفرستید و درخواست دریافتی را در سمت سرویس بررسی کنید. در مثال webhook.site متن درخواست در بخش «Request Content» ظاهر می‌شود. انتقال موفق در Telegram به‌تنهایی تأیید نمی‌کند که سرویس خارجی داده‌ها را پذیرفته یا عمل موردنظر را انجام داده است. برای بررسی، متن بدون نام، شماره تلفن و دیگر داده‌های شخصی کافی است.