أنواع أحداث التفاعل مع تطبيق Google Chat

توضّح هذه الصفحة أنواع أحداث التفاعل التي يمكن لتطبيق Google Chat تلقّيها من Google Chat.

لإعداد تطبيق Chat لتلقّي أحداث التفاعل، يمكنك الاطّلاع على مقالة تلقّي التفاعلات والردّ عليها من خلال تطبيق Chat.

تنسيقات أحداث التفاعل

يمكن للمستخدمين التفاعل مع تطبيقات Chat بعدة طرق. لكل نوع من أنواع التفاعل، يرسل Google Chat نوعًا مختلفًا من أحداث التفاعل:

• الرسالة: يرسل المستخدم رسالة إلى تطبيق Chat أو يستدعي تطبيق Chat في مساحة.
• إضافة إلى المساحة: يضيف مستخدم تطبيق Chat إلى مساحة.
• تمت الإزالة من المساحة: يزيل المستخدم تطبيق Chat من مساحة.
• النقر على البطاقة: ينقر المستخدم على بطاقة تفاعلية أو مربّع حوار مُرسَل من تطبيق Chat.

في كل مرة يتفاعل فيها المستخدم مع تطبيق Chat، يرسِل Google Chat حدث تفاعل مع نص الطلب، وهو حمولة JSON تمثِّل التفاعل. تحتوي حمولة الحدث هذه على عناصر شائعة في جميع أنواع أحداث التفاعل، بالإضافة إلى العناصر الخاصة بنوع الحدث.

لمعرفة المزيد من المعلومات عن الحقول في حدث التفاعل، راجِع المستندات المرجعية Event الخاصة بواجهة Google Chat API.

الحقول المشتركة

يتم دائمًا توفير الحقول التالية في حمولة حدث التفاعل:

الحقل	الوصف
type	نوع الحدث الذي يتلقّاه تطبيق Chat، مثل MESSAGE أو ADDED_TO_SPACE.
eventTime	الطابع الزمني الذي يشير إلى وقت إرسال الحدث.
common	تمثل هذه السمة معلومات عن عميل المستخدم، مثل اللغة أو المنصة.

الحقول حسب نوع حدث التفاعل

استنادًا إلى نوع الحدث، قد تحتوي الحمولة على الحقول الإضافية التالية:

الحقل	الوصف	نوع الفعالية
message	الرسالة ذات الصلة بالحدث.	MESSAGE، ADDED_TO_SPACE، CARD_CLICKED.
space	المساحة ذات الصلة بالفعالية	MESSAGE، ADDED_TO_SPACE، REMOVED_FROM_SPACE، CARD_CLICKED.
user	المستخدِم المرتبط بالحدث. يكون المستخدم دائمًا شخصًا (وليس تطبيق Chat).	MESSAGE، ADDED_TO_SPACE، REMOVED_FROM_SPACE، CARD_CLICKED.
action	الدالة التي يشغّلها المستخدم عند النقر على بطاقة أو مربّع حوار تفاعلي.	CARD_CLICKED.

أمثلة على حمولات الأحداث

يصف هذا القسم ما يؤدي إلى تشغيل حدث التفاعل ويقدّم مثالاً لحمولة JSON لكل نوع من أنواع الأحداث التالية:

• رسالة (MESSAGE)
• تمت الإضافة إلى المساحة (ADDED_TO_SPACE)
• تمت الإزالة من المساحة (REMOVED_FROM_SPACE)
• تم النقر على البطاقة (CARD_CLICKED)

الرسالة

يمثّل حدث التفاعل هذا الوقت الذي يُرسِل فيه مستخدِم رسالة إلى تطبيق Chat، مثل:

• أي رسالة في مساحة رسالة مباشرة (DM) باستخدام تطبيق Chat.
• رسالة في مساحة متعددة المستخدمين حيث يشير المستخدم باستخدام الرمز @إلى تطبيق Chat، أو يستخدم أحد الأوامر التي تبدأ بشرطة مائلة.
• في حال أعددت معاينات الروابط لتطبيق 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"
  }
}

تمت الإضافة إلى المساحة.

يشير حدث التفاعل هذا إلى أنه تمت إضافة تطبيق Chat إلى مساحة. تردّ التطبيقات عادةً على حدث التفاعل هذا من خلال نشر نوع من رسائل الترحيب في سلسلة محادثات جديدة في المساحة.

يعرض مثال JSON التالي نص الطلب لحدث تفاعل ADDED_TO_SPACE عندما يضيف مستخدم تطبيق Chat إلى مساحة:

{
  "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 قد ثبَّت تطبيق Chat لمستخدم في مؤسسته.

ولا يمكن للمشرفين تثبيت تطبيق Chat إلا للرسائل المباشرة بين تطبيق Chat والمستخدم. يظهر التطبيق المثبَّت في لوحة الرسائل المباشرة للمستخدمين. عندما يثبّت المشرفون تطبيقات Chat، لا يمكن للمستخدمين إلغاء تثبيتها. للتعرُّف على تطبيقات Chat التي ثبَّتها المشرفون، يمكنك الاطّلاع على مستندات مساعدة المشرف في Google Workspace، تثبيت تطبيقات Marketplace في نطاقك.

يعرض مثال JSON التالي نص الطلب لحدث تفاعل ADDED_TO_SPACE عندما يثبّت مشرف Google Workspace تطبيق Chat لمستخدم. بما أنّ أحد المشرفين ثبَّت تطبيق 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"
  }
}

تمت الإزالة من المساحة

يشير حدث التفاعل هذا إلى أنّه تمت إزالة تطبيق Chat من مساحة عمل. لا ترسِل تطبيقات Chat رسائل إلى هذا الحدث لأنّه تمت إزالتها من قبل.

يعرض مثال JSON التالي نص الطلب لحدث تفاعل REMOVED_FROM_SPACE عندما يزيل المستخدم تطبيق Chat من مساحة:

{
  "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 مثبّتًا للمستخدم. في هذه الحالة، بما أنّ تطبيق 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. على سبيل المثال، لا يتلقّى تطبيق 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. في هذا المثال، نقر المستخدم على زر في مربع حوار يرسل معلومات إلى تطبيق Chat:

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

مواضيع ذات صلة

لمعرفة كيفية معالجة حمولات أحداث التفاعل وعرض استجابة، يُرجى الاطّلاع على الأدلة التالية:

• إنشاء رسالة بطاقة
• إنشاء رسالة نصية
• فتح مربّعات الحوار التفاعلية
• معاينة الروابط
• قراءة بيانات النموذج التي يُدخلها المستخدمون على البطاقات
• إعداد الأوامر التي تبدأ بشرطة مائلة