أنواع أحداث التفاعل مع تطبيق 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 لكل نوع من أنواع الأحداث التالية:

الرسالة

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

  • أي رسالة في مساحة رسائل مباشرة باستخدام تطبيق 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",
}

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