دریافت رویدادها در لحظه

برای مطلع شدن در لحظه از اتفاقاتی که در دیوار رخ می‌دهد می‌توانید از این سرویس استفاده کنید. دقت کنید که سرویس، نسخه‌ی آزمایشی هست و ممکن است در آینده دچار تغییرات Backward incompatible شود.

برای مطلع شدن از یک رویداد، ابتدا باید درخواستی برای گوش دادن به آن ارسال کنید. در صورت موفق بودن این درخواست، تا زمان معتبر بودن دسترسی شما به آن رویداد، هر زمانی که آن رویداد رخ دهد، کنار برنامه‌ی شما را از طریق یک درخواست HTTP (Webhook) مطلع می‌کند.

دقت کنید که برای دریافت رویدادها باید برای برنامه‌ی خود یک آدرس دریافت رویداد‌های معتبر ست کنید.

درخواست گوش دادن به یک رویداد

برای ارسال این درخواست برنامه‌ی شما باید دسترسی EVENTS_REGISTER_SUBSCRIPTION را داشته باشد. دقت کنید که این یک دسترسی OAuth نیست، بلکه این دسترسی بر روی کلید API شما تعریف می‌شود.

همچنین برای گوش دادن به هر نوع رویداد، دسترسی Oauth متناظر با آن نیز باید در توکن همراه درخواست گوش دادن به آن وجود داشته باشد.

در صورت موفق بودن این درخواست، شما تا زمان معتبر بودن توکن تان از رویداد‌های درخواستی مطلع خواهید شد. در صورتی که نیاز به refresh کردن توکن دارید، باید پس از دریافت توکن جدید، درخواستی برای ساختن مجدد subscription تان بزنید.

انواع رویداد‌ها

نوع رویداد	دسترسی Oauth متناظر	توضیحات
NEW_MESSAGE_ON_POST	CHAT_POST_CONVERSATIONS_READ.{{post_token}}	مطلع شدن از پیام‌های جدید بر روی چت یک آگهی. فقط برای آگهی گذار
NEW_MESSAGE_ON_POST	CHAT_SUPPLIER_ALL_CONVERSATIONS_READ	مطلع شدن از پیام‌های جدید بر روی تمام چت‌های تمام آگهی‌های یک فرد. فقط برای چت های مربوط به آگهی گذار
NEW_CHATBOT_MESSAGE	-	مطلع شدن از پیام جدید کاربران به چت بات
USER_ACCESS_REVOCATION	NOTIFICATION_ACCESS_REVOCATION و USER_ID	مطلع شدن از حذف شدن دسترسی‌های برنامه توسط کاربر
POST_UPDATE	USER_POSTS_GET	مطلع شدن از تغییرات آگهی‌ منتشر شده و آگهی در جریان

درخواست

پارامتر	نوع	توضیحات
event_type	string	یک نوع رویداد معتبر. برای مثال NEW_MESSAGE_ON_POST
event_resource_id	string	شناسهٔ چیزی که می خواهید از رویداد آن باخبر شوید و نوعش رو در بالا گفتید. اگر ارسال نشود همهٔ موارد در نظر گرفته می شود. مثلاً می توانید با ارسال توکن آگهی پیام های جدید یک آگهی را دریافت کنید و بدون ارسال آن پیام های جدید همهٔ آگهی را دریافت می کنید.

POST https://api.divar.ir/v1/open-platform/events/subscriptions
Content-Type: application/json
x-api-key: {{apikey}}
x-access-token: {{access_token}}

{
    "event_type": "NEW_MESSAGE_ON_POST",
    "event_resource_id": "gZd7omnS",
    "metadata": {
        "key": "value"
    }
}

درخواست ارسالی از سمت کنار دیوار

پس از هر رویدادی که برنامه‌ی شما به آن گوش‌ می‌دهد، درخواستی از سمت کنار دیوار برای برنامه‌ی شما به آدرس دریافت رویدادی‌های جدید که در پنل کنار ست کردید، فرستاده می‌شود. شما باید ابتدا با چک کردن هدر Authorization اصالت این درخواست را بررسی کنید. مقدار این هدر برابر با همان مقداری است که برای هدر شناسایی ریکوئست‌های دیوار در پنل ست کرده‌اید.

POST https://{{new_events_url}}
Authorization: {{identification_key}}
Content-Type: application/json

{
    "type": "NEW_MESSAGE",
    "metadata": {
        "key": "value"
    },
    "new_message": {
        "id": "e7a08a2c-8ee4-11ef-af85-4e9e9bfa3c12",
        "conversation": {
            "id": "edbb9499-cccc-4d35-b21f-621fa95f2b3e",
            "type": "POST",
            "post_token": "gZd7omnS"
        },
        "sender": {
            "side": "SELLER",
            "type": "BOT"
        },
        "type": "TEXT",
        "sent_at": 1729429926140000,
        "text": "Hello!"
    } 
}

درخواست رویداد جدید (ارسالی از سمت دیوار)

پارامتر	نوع	توضیحات
type	EventType	نوع رویداد، برای مثال NEW_MESSAGE
new_message	Optional[ChatMessage]	پیام جدید. در صورتی که نوع رویداد NEW_MESSAGE باشد
new_chatbot_message	Optional[ChatMessage]	پیام جدید. در صورتی که نوع رویداد NEW_CHATBOT_MESSAGE باشد
user_access_revocation	Optional[UserAccessRevocation]	حذف دسترسی برنامه توسط کاربر. در صورتی که نوع رویداد USER_ACCESS_REVOCATION باشد
post_update	Optional[PostUpdate]	تغییر آگهی منتشر شده یا در جریان. در صورتی که نوع رویداد POST_UPDATE باشد
metadata	Optional[Object]	دیتای دلخواه از سمت برنامه‌ی شما.

رویدادها

رویداد	توضیحات
NEW_MESSAGE	پیام جدید در چت
NEW_CHATBOT_MESSAGE	پیام جدید در چت بات
USER_ACCESS_REVOCATION	حذف دسترسی برنامه توسط کاربر
POST_UPDATE	تغییر آگهی