Skip to navigation
مرجع

مرجع رویدادهای وب‌هوک

نسخه پیش‌انتشار v1، منتشرشده در 2026-09-14. این صفحه به شکل API متعهد است، نه به تاریخ مشخصی. دقیقاً همان چیزی را می‌سازیم که اینجا مستند شده است. شکل API تا 2026-10-14 هنوز ممکن است تغییر کند؛ پس از آن، تغییرات از نسخه‌بندی و پایداری پیروی می‌کنند.

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

همه رویدادهای زیر در API Reference هم آمده‌اند، در بخش Webhook events؛ آنجا هر حالت را می‌توانید از فهرست کشویی کنار محتوای رویداد انتخاب کنید.

تحویل، تأیید امضا و تلاش دوباره: رویدادهای وب‌هوک.

همه رویدادها پوشش یکسانی دارند؛ فقط data فرق می‌کند.

message

پوشش رویداد در همه کانال‌ها یکسان است. تفاوت در داخل data است: اینستاگرام یک source و یک sender اینستاگرامی دارد، و تلگرام شناسه کاربر تلگرام دارد و source ندارد.

{
  "schema_version": "1.0.0",
  "event": "message",
  "delivery_id": "dlv_9fK2mQ",
  "occurred_at": "2026-09-20T11:09:02Z",
  "robot_id": "rbt_8fK2mQ",
  "external_id": "shop_10422",
  "channel_id": "chn_3pQ7xL",
  "data": {
    "conversation_id": "cnv_4dR8nW",
    "message_id": "msg_1aB2cD",
    "external_id": "cli_msg_1",
    "source": "direct",
    "role": "client",
    "type": "text",
    "text": "Hi, do you have these roses in stock?",
    "markdown_content": null,
    "reply_to_id": null,
    "form_data": null,
    "attachments": [],
    "is_edited": false,
    "sender": { "id": "iguser_88213", "username": "sara.k" },
    "created_at": "2026-09-20T11:09:02Z"
  }
}
فیلدتوضیح
roleclient، ai یا operator. برای ai و operator مقدار sender برابر null است
typetext · voice · image · video · multimedia · document · poll · form · template
sourceفقط اینستاگرام: direct · comment · story_reply · story_mention · reel
external_idکلید idempotency شما
reply_to_idmessage_id پیامی که این پیام به آن پاسخ می‌دهد، یا null
markdown_contentنسخه با قالب‌بندی غنی؛ text ساده می‌ماند. هر کدام ممکن است null باشد
form_dataوقتی type برابر form است وجود دارد

آغازشده با کامنت، همراه با پیوست

{
  "schema_version": "1.0.0",
  "event": "message",
  "delivery_id": "dlv_2xK8pL",
  "occurred_at": "2026-09-20T11:14:20Z",
  "robot_id": "rbt_8fK2mQ",
  "external_id": "shop_10422",
  "channel_id": "chn_3pQ7xL",
  "data": {
    "conversation_id": "cnv_7mN2qS",
    "message_id": "msg_5eF6gH",
    "source": "comment",
    "media_id": "17895695668004550",
    "role": "client",
    "type": "image",
    "text": "",
    "attachments": [
      { "type": "image", "url": "https://cdn.parstechai.com/m/9fK2mQ.jpg", "mime": "image/jpeg" }
    ],
    "sender": { "id": "iguser_44190", "username": "ali.m" },
    "created_at": "2026-09-20T11:14:20Z"
  }
}

media_id فقط وقتی می‌آید که رویداد از یک پست یا ریل آغاز شده باشد.

یک پیام صوتی

پیوست‌ها به صورت رویدادهای عادی message با type غیرمتنی می‌رسند، هرگز به صورت رویداد جداگانه. text خالی است و محتوا در attachments قرار دارد.

{
  "schema_version": "1.0.0",
  "event": "message",
  "delivery_id": "dlv_6vB3nK",
  "occurred_at": "2026-09-20T11:31:12Z",
  "robot_id": "rbt_8fK2mQ",
  "external_id": "shop_10422",
  "channel_id": "chn_3pQ7xL",
  "data": {
    "conversation_id": "cnv_4dR8nW",
    "message_id": "msg_2vC5xN",
    "source": "direct",
    "role": "client",
    "type": "voice",
    "text": "",
    "attachments": [
      {
        "type": "voice",
        "url": "https://cdn.parstechai.com/m/2vC5xN.ogg",
        "mime": "audio/ogg",
        "duration_seconds": 14
      }
    ],
    "sender": { "id": "iguser_88213", "username": "sara.k" },
    "created_at": "2026-09-20T11:31:12Z"
  }
}

آدرس پیوست‌ها مدت اعتبار محدودی دارد. به جای ذخیره آدرس و دریافت فایل در زمانی دیگر، فایل را همان وقتی که رویداد می‌رسد دانلود کنید.

ارسال فرم

{
  "schema_version": "1.0.0",
  "event": "message",
  "delivery_id": "dlv_4jH7sV",
  "occurred_at": "2026-09-20T11:40:00Z",
  "robot_id": "rbt_8fK2mQ",
  "external_id": "shop_10422",
  "channel_id": "chn_3pQ7xL",
  "data": {
    "conversation_id": "cnv_4dR8nW",
    "message_id": "msg_8kP1rT",
    "role": "client",
    "type": "form",
    "text": null,
    "form_data": [
      { "type": "text", "situation": "question", "key": "Your name", "value": "Sara" },
      { "type": "single_select", "situation": "rate", "key": "Service rating", "value": "excellent" }
    ],
    "attachments": [],
    "created_at": "2026-09-20T11:40:00Z"
  }
}

message.generating

هوش مصنوعی نوشتن پاسخ را شروع کرده است. نشانگر «در حال نوشتن» را نمایش دهید.

{
  "schema_version": "1.0.0",
  "event": "message.generating",
  "delivery_id": "dlv_5kL3nP",
  "occurred_at": "2026-09-20T11:09:03Z",
  "robot_id": "rbt_8fK2mQ",
  "external_id": "shop_10422",
  "channel_id": "chn_3pQ7xL",
  "data": { "conversation_id": "cnv_4dR8nW" }
}

وقتی message متناظر رسید، نشانگر را پنهان کنید. رویداد صریحی برای «متوقف شد» وجود ندارد. تولید پاسخی که شکست بخورد هیچ پیامی نمی‌سازد، پس پس از چند ثانیه آن را timeout در نظر بگیرید.

chat

وضعیت یک گفتگو تغییر کرد. status یکی از answered، operator_attention، not_answered، closed یا pending است، و previous_status وضعیت قبلی آن است.

هر کدام برای سمت شما معنای متفاوتی دارد، پس به جای ذخیره صرف این رشته، هر کدام را جداگانه مدیریت کنید.

هوش مصنوعی یا یک اپراتور پاسخ داد. چیزی منتظر کسی نیست.

{
  "schema_version": "1.0.0",
  "event": "chat",
  "delivery_id": "dlv_6hJ4kM",
  "occurred_at": "2026-09-20T11:09:08Z",
  "robot_id": "rbt_8fK2mQ",
  "external_id": "shop_10422",
  "channel_id": "chn_3pQ7xL",
  "data": {
    "conversation_id": "cnv_4dR8nW",
    "status": "answered",
    "previous_status": "not_answered",
    "changed_at": "2026-09-20T11:09:08Z"
  }
}

بستن گفتگو، زمینه را از نو شروع می‌کند

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

context_reset پرچم حذف نیست. چیزی حذف نمی‌شود. پیام‌ها باقی می‌مانند و فقط دیگر در زمینه گفتگوی بعدی بازپخش نمی‌شوند. شریکی که این را دستور حذف تلقی کند، رونوشتی را دور می‌ریزد که ما هنوز نگه داشته‌ایم.

رونوشتی که ذخیره کرده‌ایدتغییری نمی‌کند. نگهش دارید
خواندن گفتگو پس از بسته شدنهمچنان کار می‌کند
گفتگوی بعدی با همان کاربربدون زمینه قبلی شروع می‌شود

reaction

کسی واکنشی را روی یک پیام اضافه یا حذف کرد. action می‌گوید کدام، پس یک پردازشگر هر دو حالت را پوشش می‌دهد: با added اعمالش کنید و با removed برش گردانید.

{
  "schema_version": "1.0.0",
  "event": "reaction",
  "delivery_id": "dlv_3pQ9rT",
  "occurred_at": "2026-09-20T11:22:05Z",
  "robot_id": "rbt_8fK2mQ",
  "external_id": "shop_10422",
  "channel_id": "chn_3pQ7xL",
  "data": {
    "conversation_id": "cnv_4dR8nW",
    "message_id": "msg_1aB2cD",
    "action": "added",
    "emoji": "❤️",
    "by": { "id": "iguser_88213", "username": "sara.k" }
  }
}

is_typing

یک انسان شروع به نوشتن کرد یا متوقف شد. این با message.generating که مربوط به هوش مصنوعی است فرق دارد. شاید بخواهید آن‌ها را متفاوت نمایش دهید: «سارا در حال نوشتن است» در برابر «در حال تولید پاسخ».

{
  "schema_version": "1.0.0",
  "event": "is_typing",
  "delivery_id": "dlv_7rS2tU",
  "occurred_at": "2026-09-20T11:25:10Z",
  "robot_id": "rbt_8fK2mQ",
  "external_id": "shop_10422",
  "channel_id": "chn_3pQ7xL",
  "data": {
    "conversation_id": "cnv_4dR8nW",
    "is_typing": true,
    "by": { "id": "iguser_88213", "username": "sara.k", "role": "client" }
  }
}

ارسال رویداد توقف تضمینی نیست. ممکن است اتصال در میانه تایپ قطع شود، پس به جای انتظار برای is_typing: false، خودتان نشانگر را پس از چند ثانیه منقضی کنید.