ماژول وب هوک
دریافت رویدادها از دیالوگها Hotline به شکل POST-درخواستها در قالب JSON برای پردازش بیشتر به یک اسکریپت خارجی.
در ربات نصب @hotlinetg_bot از طریق پارامتر اتصال @WEBHOOKS@ میتوانید یک یا چند آدرس برای پردازش خروجی تنظیم کنید POST-درخواستهای خارجی Hotline درباره وقایع در دیالوگها.
هشدار: این صفحه حاوی قطعات با ترجمه خودکار است. اگر درک این اطلاعات برای شما دشوار است، سعی کنید زبان را به انگلیسی یا روسی تغییر دهید و از سیستم ترجمه وب سایت مورد اعتماد خود استفاده کنید.
درخواستهای خروجی از سمت Hotline به آدرسهای مشخصشده با انواع رویدادهای مشخصشده، شامل تمام اطلاعات اولیه در مورد موضوع و/یا کاربر مربوطه برای پردازشهای بعدی، و همچنین فیلد api_key اتصال مربوطه برای تأیید فرستنده. در صورت لزوم، میتوانید با استفاده از آدرس IP سرور پروکسی ما، تأیید فرستنده اضافی را در سمت خود پیکربندی کنید.
مثال JSON برای پیکربندی پارامتر @WEBHOOKS@:
{
"https://someapiserver.com/webhooks/test-hook1": [
"dialog_created",
"dialog_reopened",
"dialog_closed",
"message_received",
"message_sent",
"message_intercepted"
],
"https://someapiserver.com/webhooks/test-hook2": [
"/mark", "/info",
"/invoice", "/client"
]
}شما میتوانید دو نوع درخواست از Hotline دریافت کنید:
رویدادهای سیستم – درباره باز کردن، بستن یا بازگشایی دیالوگها، دریافت پیامهای ورودی یا ارسالی توسط اپراتورها یا از جلسات موازی. این رویدادها برای سیستمهای تحلیلی یا برای ذخیرهسازی پیامهای اضافی در پایگاه داده شما (از جمله برای دستیاران هوش مصنوعی) مناسب هستند.
دستورات سفارشی - گزارشهایی در مورد استفاده از دستورات مشخص شده توسط اپراتورهایی که با نماد شروع میشوند / (اسلش). میتواند به عنوان دستورات استاندارد سیستم (به عنوان مثال) نظارت شود /mark یا /close) و همچنین هرگونه دستور سفارشی، به عنوان مثال /invoice (ایجاد فاکتور)، /client (اطلاعات مربوط به مشتری را از طریق او دریافت کنید) user_id в Telegram). رویدادهای نوع دوم میتوانند پاسخی را برگردانند که در تاپیک با کادر محاورهای مربوطه نمایش داده میشود. این رویدادها برای پیادهسازی دستورات سفارشی که میتوانند عملکرد Hotline را به طور قابل توجهی گسترش دهند یا کار اپراتور را سرعت بخشند، مناسب هستند.
رویدادهای سیستم – درباره باز کردن، بستن یا بازگشایی دیالوگها، دریافت پیامهای ورودی یا ارسالی توسط اپراتورها یا از جلسات موازی. این رویدادها برای سیستمهای تحلیلی یا برای ذخیرهسازی پیامهای اضافی در پایگاه داده شما (از جمله برای دستیاران هوش مصنوعی) مناسب هستند.
دستورات سفارشی - گزارشهایی در مورد استفاده از دستورات مشخص شده توسط اپراتورهایی که با نماد شروع میشوند / (اسلش). میتواند به عنوان دستورات استاندارد سیستم (به عنوان مثال) نظارت شود /mark یا /close) و همچنین هرگونه دستور سفارشی، به عنوان مثال /invoice (ایجاد فاکتور)، /client (اطلاعات مربوط به مشتری را از طریق او دریافت کنید) user_id в Telegram). رویدادهای نوع دوم میتوانند پاسخی را برگردانند که در تاپیک با کادر محاورهای مربوطه نمایش داده میشود. این رویدادها برای پیادهسازی دستورات سفارشی که میتوانند عملکرد Hotline را به طور قابل توجهی گسترش دهند یا کار اپراتور را سرعت بخشند، مناسب هستند.
وبهوکها فقط برای کاربران پولی سیستم در دسترس هستند.
برای خرید اشتراک پولی یا اتصال به یک دوره آزمایشی چند روزه برای آزمایش عملکرد، لطفاً با ما تماس بگیرید @hotlinetg_support
نوع ۱: رویدادهای سیستم
رویدادهای سیستم از مجموعهای ثابت از مقادیر تعریف میشوند. رویدادهای سیستم بدون بازگشت هیچ نتیجهای به موضوع گفتگوی مربوطه ارسال میشوند.
در حال حاضر انواع رویدادهای زیر در دسترس هستند: dialog_created, dialog_reopened, dialog_closed, message_دریافت شد, message_ارسال شد, message_رهگیری شده.
نمونههایی از استفاده از رویدادهای سیستم در دیالوگها:
- ارسال پیامهای اضافی به کاربر پس از شروع گفتگو (برای مثال، پس از اتمام مهلت زمانی)
- نظارت بیشتر بر پیامهای ورودی و خروجی بر اساس کلمات کلیدی یا معنای پیامها برای تخلفات اپراتورها
- کنترل زمان پاسخگویی اپراتور به درخواستهای دریافتی
- جمعآوری دادهها برای تجزیه و تحلیل گفتگوها و/یا اپراتورها در یک سیستم خارجی
- ضبط پیامها در یک سیستم خارجی برای آموزش ماژول هوش مصنوعی
مثالی از درخواست خروجی برای بازگشایی یک پنجره گفتگو:
{
"event_type": "dialog_reopened",
"timestamp": "2025-10-09 00:24:55",
"instance_id": "13209946874612345",
"data": {
"chat_id": -1002146012345,
"thread_id": 5602541568,
"topic_id": 5343,
"topic_link": "https://t.me/c/2146012345/5343",
"user_id": 5339212345,
"frontend_chat_id": 5339212345,
"frontend_topic_id": null,
"frontend_topic_link": null,
"frontend_user_id": 6406751371,
"chat_type": "private",
"title": "Some User Name",
"department": "default"
},
"api_key": "pQTngMZLh0NmAh"
}مثالی از درخواست خروجی برای پیام ارسالی:
{
"event_type": "message_sent",
"timestamp": "2025-10-09 00:21:57",
"instance_id": "132099468746812345",
"data": {
"backend_chat_id": -1002146012345,
"backend_thread_id": 5602541568,
"backend_message_id": 6171918336,
"sender_user_id": 5339212345,
"frontend_user_id": 640675123,
"frontend_message_id": 3260022784,
"text": "test message",
"content_type": "messageText",
"department": "default",
"backend_reply_message_id": 0
},
"api_key": "pQTngMZLh0NmAh"
}نوع ۲: دستورات سفارشی
هر دستوری که با نماد شروع شود / (اسلش) میتواند به عنوان یک مقدار برای دریافت رویدادهای مربوط به آن و اطلاعات مربوط به کادر محاورهای مربوطه مشخص شود.
شما میتوانید هر دو دستور استاندارد سیستم موجود (/info, /mark, /close و غیره)، و همچنین موارد سفارشی، منطق اقداماتی که اسکریپت شما مسئول آن خواهد بود و در صورت لزوم، نتیجه را به صورت موضوع به موضوع بازمیگرداند JSON یا یک پیام متنی (نشانهگذاری در قالب مجاز است) Markdown v2).
نمونههایی از استفاده از وبهوکها با دستورات سفارشی:
- بسط فرمان استاندارد /info اطلاعات تکمیلی در مورد کاربر
- ثبت تغییرات در وضعیتهای دیالوگ توسط اپراتورها از طریق یک دستور /mark
- ثبت وقایع مربوط به بسته شدن درخواستها توسط دستور /close
- برای مثال، دستورات خودتان را اضافه کنید /invoice, /client یا هر مورد دیگری که به اطلاعاتی در مورد موضوع مکالمه و دادههای کاربر یا چت نیاز دارد.
مثالی از درخواست فراخوانی فرمان /mark deal اپراتور معامله:
{
"event_type": "/mark",
"timestamp": "2025-10-08 20:41:20",
"instance_id": "132099468746812345",
"data": {
"command_data": "deal",
"chat_id": -1002146012345,
"topic_id": 5,
"topic_link": "https://t.me/c/2146012345/5",
"message_id": 5850,
"reply_message_id": null,
"sender_user_id": 123456,
"user_id": 7890123,
"frontend_chat_id": 7890123,
"frontend_thread_id": null
},
"api_key": "pQTngMZLh0NmAh"
}برای نمایش نتیجه یک دستور در یک تاپیک، پاسخ سرور شما باید یا به صورت متن ساده یا به شکل زیر باشد: JSONکه گرهای با نام دارد message یا error (سایر گرهها نادیده گرفته میشوند).
نمونهای از پاسخ موفقیتآمیز از سرور شما در قالب JSON با پیامی که در تاپیک مربوط به دیالوگ نشان داده خواهد شد:
{
"message": "Deal created: http://internal.domain.com/crm/deals/76238",
"status": "ok"
}نمونهای از پاسخ سرور شما به همراه متن خطا در قالب JSONکه در تاپیک با دیالوگ نشان داده خواهد شد:
{
"error": "User 12345678 not found in our database"
}برای سوالات مربوط به وبهوکها، یا فعالسازی اشتراک پولی یا نسخه آزمایشی، لطفاً با پشتیبانی تماس بگیرید. @hotlinetg_support.