انواع رویدادهای تعامل برنامه چت Google

این صفحه انواع رویدادهای تعاملی را که برنامه Google Chat شما می‌تواند از Google Chat دریافت کند، توضیح می‌دهد.

برای پیکربندی برنامه چت برای دریافت رویدادهای تعامل، به دریافت و پاسخ به تعاملات با برنامه چت خود مراجعه کنید.

قالب‌های رویدادهای تعاملی

کاربران می توانند به طرق مختلف با برنامه های چت تعامل داشته باشند. برای هر نوع تعامل، Google Chat نوع متفاوتی از رویداد تعاملی را ارسال می‌کند:

  • پیام: یک کاربر به برنامه چت شما پیامی ارسال می کند یا برنامه چت شما را در یک فاصله فراخوانی می کند.
  • به فضا اضافه شد: کاربر برنامه چت شما را به یک فضا اضافه می کند.
  • حذف شده از فضا: یک کاربر برنامه چت شما را از یک فضا حذف می کند.
  • کارت کلیک شده: کاربر روی کارت تعاملی یا گفتگوی ارسال شده توسط برنامه چت شما کلیک می کند.
  • پیام صفحه اصلی برنامه : کاربر یک پیام مستقیم را با یک برنامه چت باز می کند و یک پیام اصلی برنامه چت را دریافت می کند.
  • فرم ارسال : کاربر اطلاعات فرم را از طریق پیام اصلی برنامه چت ارسال می کند

هر بار که کاربر با برنامه چت شما تعامل می کند، Google Chat یک رویداد تعاملی را با یک بدنه درخواست ارسال می کند که یک بار JSON است که تعامل را نشان می دهد. این بار رویداد حاوی عناصری است که برای همه انواع رویدادهای تعامل مشترک هستند و همچنین عناصری که مختص نوع رویداد هستند.

برای کسب اطلاعات بیشتر در مورد فیلدها در یک رویداد تعاملی، به مستندات مرجع Event Google Chat API مراجعه کنید.

زمینه های مشترک

فیلدهای زیر همیشه در محموله یک رویداد تعاملی ارائه می شوند:

رشته شرح
type نوع رویدادی که برنامه گپ دریافت می‌کند، مانند MESSAGE یا ADDED_TO_SPACE .
eventTime مهر زمانی که نشان دهنده زمان ارسال رویداد است.
common نشان دهنده اطلاعات مربوط به مشتری کاربر، مانند محل یا پلت فرم است.

فیلدها بر اساس نوع رویداد تعامل

بسته به نوع رویداد، payload ممکن است حاوی فیلدهای اضافی زیر باشد:

رشته شرح نوع رویداد
message پیام مربوط به مراسم MESSAGE ، ADDED_TO_SPACE ، CARD_CLICKED .
space فضای مربوط به رویداد. MESSAGE ، ADDED_TO_SPACE ، REMOVED_FROM_SPACE ، CARD_CLICKED .
user کاربر مرتبط با رویداد. کاربر همیشه یک شخص است (نه یک برنامه چت). MESSAGE ، ADDED_TO_SPACE ، REMOVED_FROM_SPACE ، CARD_CLICKED .
action عملکردی که کاربر هنگام کلیک کردن روی کارت تعاملی یا گفتگو فعال می کند. CARD_CLICKED .

نمونه بارهای رویداد

این بخش آنچه را که یک رویداد تعاملی را راه‌اندازی می‌کند توضیح می‌دهد و یک نمونه بارگیری JSON برای هر یک از انواع رویداد زیر ارائه می‌کند:

پیام

این رویداد تعامل نشان دهنده زمانی است که شخصی پیامی را به برنامه چت ارسال می کند، مانند:

  • هر پیامی در فضای پیام مستقیم (DM) با برنامه چت.
  • پیامی در فضای چند نفره که در آن شخصی @ از برنامه Chat نام می‌برد یا از یکی از دستورات اسلش آن استفاده می‌کند.
  • اگر پیش نمایش پیوندها را برای برنامه چت خود پیکربندی کرده باشید، کاربر پیامی را ارسال می کند که حاوی پیوندی است که با الگوی URL پیکربندی شده مطابقت دارد.

مثال JSON زیر یک رویداد تعاملی MESSAGE را نشان می‌دهد که در آن کاربر @ از یک برنامه Chat در فضایی با چند نفر نام می‌برد:

{
  "type": "MESSAGE",
  "eventTime": {
      "seconds": 1691187414,
      "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "SPACE"
  },
  "message": {
    "name": "spaces/AAAAAAAAAAA/messages/CCCCCCCCCCC",
    "sender": {
      "name": "users/12345678901234567890",
      "displayName": "Izumi",
      "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
      "email": "izumi@example.com"
    },
    "createTime": {
      "seconds": 1691187386,
      "nanos": 954319000
    },
    "text": "@TestBot Create ticket.",
    "argumentText": " Create ticket.",
    "thread": {
      "name": "spaces/AAAAAAAAAAA/threads/BBBBBBBBBBB",
      "threadKey": "custom-thread-ID"
    },
    "annotations": [
      {
        "length": 8,
        "startIndex": 0,
        "userMention": {
          "type": "MENTION",
          "user": {
            "avatarUrl": "https://.../avatar.png",
            "displayName": "TestBot",
            "name": "users/1234567890987654321",
            "type": "BOT"
          }
        },
        "type": "USER_MENTION"
      }
    ],
    "attachment": [
      {
        "name": "spaces/5o6pDgAAAAE/messages/Ohu1LlUVcS8.Ohu1LlUVcS8/attachments/AATUf-Iz7d8kySEdRRZd-dznqBk3",
        "content_name": "solar.png",
        "content_type": "image/png",
        "drive_data_ref": {
          "drive_file_id": "H1HqaqRuH2Pfd_TOa1fF2_ltwDlV_yKRrr"
        },
        "source": "DRIVE_FILE"
      }
    ]
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

به فضا اضافه شد

این رویداد تعاملی نشان می‌دهد که برنامه چت شما به یک فضا اضافه شده است. برنامه ها معمولاً با ارسال نوعی پیام خوش آمدگویی در یک رشته جدید در فضا به این رویداد تعامل پاسخ می دهند.

مثال JSON زیر بدنه درخواست یک رویداد تعاملی ADDED_TO_SPACE را هنگامی که کاربر یک برنامه چت را به یک فضا اضافه می‌کند نشان می‌دهد:

{
  "type": "ADDED_TO_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "SPACE",
    "adminInstalled": "false"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

توسط سرپرستان Google Workspace نصب شده است

رویداد تعامل ADDED_TO_SPACE همچنین می‌تواند نشان دهد که یک سرپرست Google Workspace برنامه چت شما را برای کاربری در سازمان خود نصب کرده است.

مدیران فقط می‌توانند یک برنامه چت را برای پیام‌های مستقیم بین برنامه چت و کاربر نصب کنند. برنامه نصب شده در پنل پیام مستقیم کاربران ظاهر می شود. وقتی سرپرستان برنامه‌های چت را نصب می‌کنند، کاربران نمی‌توانند آن‌ها را حذف نصب کنند. برای آشنایی با برنامه‌های گپ نصب‌شده توسط سرپرستان، به اسناد راهنمای Google Workspace Admin مراجعه کنید، برنامه‌های Marketplace را در دامنه خود نصب کنید .

مثال JSON زیر بدنه درخواست یک رویداد تعاملی ADDED_TO_SPACE را هنگامی که یک سرپرست Google Workspace یک برنامه چت را برای یک کاربر نصب می‌کند، نشان می‌دهد. از آنجایی که یک سرپرست برنامه Chat را نصب کرده است، adminInstalled روی true تنظیم شده است:

{
  "type": "ADDED_TO_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "DIRECT_MESSAGE",
    "adminInstalled": "true"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

از فضا حذف شد

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

مثال JSON زیر بدنه درخواست یک رویداد تعاملی REMOVED_FROM_SPACE را هنگامی که کاربر یک برنامه چت را از یک فضا حذف می‌کند نشان می‌دهد:

{
  "type": "REMOVED_FROM_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "spaceType": "SPACE",
    "adminInstalled": "false"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

توسط سرپرستان Google Workspace حذف نصب شد

رویداد تعامل REMOVED_FROM_SPACE همچنین می‌تواند نشان دهد که یک سرپرست Google Workspace برنامه چت شما را برای کاربری در سازمانش حذف نصب کرده است. با حذف نصب، برنامه چت دیگر در پانل پیام مستقیم کاربر ظاهر نمی شود.

اگر کاربری برنامه Chat شما را قبل از سرپرست نصب کرده باشد، برنامه Chat همچنان برای کاربر نصب شده است. در این حالت، از آنجایی که برنامه Chat هنوز نصب است، برنامه Chat رویداد تعاملی REMOVED_FROM_SPACE را دریافت نمی کند.

مثال JSON زیر بدنه درخواست را برای یک رویداد تعاملی REMOVED_FROM_SPACE نشان می‌دهد که سرپرست Google Workspace یک برنامه Chat را برای یک کاربر حذف نصب می‌کند. از آنجایی که برنامه Chat توسط یک سرپرست حذف نصب شده است، adminInstalled روی true تنظیم شده است:

{
  "type": "REMOVED_FROM_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "spaceType": "DIRECT_MESSAGE",
    "adminInstalled": "true"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

کارت کلیک شد

این رویداد تعاملی نشان می‌دهد که کاربر روی یک دکمه در پیام کارت یا گفتگو کلیک کرده است.

برای دریافت یک رویداد تعاملی، دکمه باید تعامل دیگری با برنامه چت ایجاد کند. برای مثال، اگر کاربر روی دکمه‌ای کلیک کند که پیوندی به یک وب‌سایت باز می‌کند، برنامه Chat رویداد تعاملی CARD_CLICKED را دریافت نمی‌کند، اما رویدادهای تعامل را در مثال‌های زیر دریافت می‌کند:

  • کاربر روی دکمه Send feedback روی کارت کلیک می کند، که یک گفتگو برای کاربر برای وارد کردن اطلاعات باز می شود.
  • کاربر پس از وارد کردن اطلاعات در کارت یا گفتگو، روی دکمه Submit کلیک می کند.

مثال JSON زیر بدنه درخواست یک رویداد تعاملی CARD_CLICKED را نشان می‌دهد که کاربر روی دکمه‌ای در پیام کارت کلیک می‌کند که یک بلیط پشتیبانی دریافتی را به او اختصاص می‌دهد:

{
  "type": "CARD_CLICKED",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "common": {
    "userLocale": "en",
    "hostApp": "CHAT",
    "invokedFunction": "doAssignTicket",
    "timeZone": {
      "offset": -25200000,
      "id": "America/Los_Angeles"
    }
  },
  "action": {
    "actionMethodName": "doAssignTicket"
  },
  "message": {
    "cards": [
      {
        "header": {
          "title": "Incoming support ticket."
        },
        "sections": [
          {
            "widgets": [
              {
                "textParagraph": {
                  "text": "Incoming support ticket #12345 is unassigned and needs your attention."
                }
              },
              {
                "buttons": [
                  {
                    "textButton": {
                      "onClick": {
                        "action": {
                          "actionMethodName": "doAssignTicket"
                        }
                      },
                      "text": "Assign to me"
                    }
                  }
                ]
              }
            ]
          }
        ]
      }
    ],
    "sender": {
      "avatarUrl": "https://www.example.com/images/chat-app-icon.png",
      "displayName": "Support Chat app",
      "name": "users/98765432109876543210",
      "type": "BOT"
    },
    "createTime": {
      "seconds": 1691187386,
      "nanos": 954319000
    },
    "retentionSettings": {
      "state": "PERMANENT"
    },
    "name": "spaces/AAAAAAAAAAA/messages/CCCCCCCCCCC",
    "thread": {
      "retentionSettings": {
        "state": "PERMANENT"
      },
      "name": "spaces/AAAAAAAAAAA/threads/BBBBBBBBBBB"
    },
    "messageHistoryState": "HISTORY_ON",
    "space": {
      "spaceThreadingState": "GROUPED_MESSAGES",
      "spaceType": "SPACE",
      "displayName": "Customer Support Superstars",
      "name": "spaces/AAAAAAAAAAA",
      "spaceHistoryState": "HISTORY_ON",
      "type": "ROOM",
      "threaded": true
    }
  },
  "user": {
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "displayName": "Izumi",
    "name": "users/12345678901234567890",
    "type": "HUMAN",
    "email": "izumi@example.com",
    "domainId": "ABCDEFG"
  },
  "space": {
    "spaceThreadingState": "GROUPED_MESSAGES",
    "spaceType": "SPACE",
    "displayName": "Customer Support Superstars",
    "name": "spaces/AAAAAAAAAAA",
    "spaceHistoryState": "HISTORY_ON",
    "type": "ROOM",
    "threaded": true
  }
}

کلیک کارت برای گفتگوها

هنگامی که کاربر با یک گفتگو تعامل می کند، بارگذاری برای رویداد تعامل CARD_CLICKED شامل فیلدهای اضافی زیر است:

  • isDialogEvent : برای رویدادهای تعاملی که شامل دیالوگ ها می شوند، روی true تنظیم کنید.
  • DialogEventType : نوع تعامل با دیالوگ، از جمله اگر کاربر یک گفتگو را باز کند، ارسال کند یا لغو کند.

مثال JSON زیر بخشی از بدنه درخواست را برای یک رویداد تعاملی CARD_CLICKED نشان می‌دهد. در این مثال، کاربر روی دکمه ای در یک گفتگو کلیک کرده است که اطلاعات را به برنامه چت ارسال می کند:

{
  "type": "CARD_CLICKED",
  ...
  "isDialogEvent": true,
  "dialogEventType": "SUBMIT_DIALOG",
}

پیام خانه برنامه

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

مثال JSON زیر بدنه درخواست یک رویداد تعاملی APP_HOME را نشان می‌دهد:

{
  "chat": {
    "type": "APP_HOME",
    "user": {
      "name": "users/12345678901234567890",
      "type": "HUMAN",
      "email": "izumi@example.com",
      "domainId": "ABCDEFG"
    },
    "space": {
      "name": "spaces/AAAAAAAAAAA",
      "singleUserBotDm": true,
      "spaceType": "DIRECT_MESSAGE"
    }
  },
  "commonEventObject": {
    "invokedFunction": "onAppHome",
    "userLocale": "en",
    "hostApp": "CHAT"
  }
}

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

این رویداد تعاملی نشان می‌دهد که کاربر اطلاعات فرم را از طریق پیام اصلی برنامه چت ارسال کرده است.

مثال JSON زیر بدنه درخواست یک رویداد تعاملی SUBMIT_FORM را نشان می دهد:

{
  "commonEventObject": {
    "userLocale": "en",
    "invokedFunction": "onSubmitFunction",
    "formInputs": {
      "username": {
        "": {
          "stringInputs": {
            "value": [
              "Ira"
            ]
          }
        }
      }
    },
    "hostApp": "CHAT"
  },
  "chat": {
    "type": "SUBMIT_FORM",
    "space": {
      "name": "spaces/AAAAAAAAAAA",
      "spaceType": "DIRECT_MESSAGE",
      "singleUserBotDm": true
    },
    "user": {
      "type": "HUMAN",
      "name": "123456789"
    }
  }
}

برای یادگیری نحوه پردازش محموله های رویدادهای تعامل و بازگرداندن پاسخ، به راهنماهای زیر مراجعه کنید: