تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
توضّح هذه الصفحة كيفية ربط تطبيق Google Chat بخدمة أو أداة خارج Google Chat. على الرغم من أنّ تطبيقات Chat فعّالة بذاتها، إلا أنّها غالبًا ما تعمل بالتزامن مع أنظمة أخرى وتتطلّب تطبيقات مصاحبة لربط الحسابات أو منح إذن الوصول إلى البيانات أو عرض بيانات إضافية أو ضبط الإعدادات المفضّلة للمستخدم.
المتطلبات الأساسية
تطبيق Google Chat تم إعداده لتلقّي أحداث التفاعل والردّ عليها. لإنشاء تطبيق تفاعلي على Chat، أكمل أحد أدلة البدء السريع التالية استنادًا إلى بنية التطبيق التي تريد استخدامها:
إذا كان إكمال الطلب يتطلّب إعدادات إضافية لا يمكن إكمالها مباشرةً في تطبيق Chat، يمكنك عرض عنوان URL للإعدادات للمستخدم كجزء من رد عادي، أو عرضه بشكل خاص، وذلك على النحو التالي:
يطلب هذا الرمز من Google Chat عرض طلب خاص للمستخدم، حيث يمثّل
CONFIGURATION_URL رابطًا
يمكن للمستخدم الانتقال إليه لإجراء مصادقة أو تفويض أو
إعدادات إضافية. لا يمكن أن يتضمّن الرد REQUEST_CONFIG رسالة رد عادية. ويتم تجاهل أي نص أو بطاقات أو سمات أخرى.
إكمال طلب الإعداد
يتضمّن كل
حدث تفاعلي في MESSAGE وADDED_TO_SPACE وAPP_COMMAND
يتلقّاه تطبيق Chat أيضًا الحقل
configCompleteRedirectUrl. يجب ترميز عنوان URL هذا في عنوان URL الخاص بالإعداد لاستخدامه عند اكتمال العملية. يشير التوجيه إلى عنوان URL هذا إلى أنّ طلب الإعداد قد تم تنفيذه في Google Chat.
عندما يبدأ تطبيق Chat، يعتمد مسار العمل على الرسالة المحدّدة التي تم تلقّيها. استجابةً لرسالة مثل @app help، يجب أن يستجيب تطبيق المحادثة برسالة بدون الحاجة إلى إعدادات إضافية.
عندما تتم إعادة توجيه المستخدم بنجاح إلى configCompleteRedirectUrl
المقدَّم في الرسالة الأصلية، يتّخذ Google Chat الخطوات التالية:
محو الطلب الذي تم عرضه على المستخدم الذي بدأ المحادثة
تحويل الرسالة الأصلية إلى رسالة عامة، ما يجعلها مرئية للأعضاء الآخرين في المساحة
أرسِل الرسالة الأصلية إلى تطبيق Chat نفسه
مرة ثانية.
لا يؤثر الانتقال إلى configCompleteRedirectUrl إلا في رسالة مستخدم واحدة.
إذا حاول مستخدم إرسال رسالة إلى تطبيق Chat عدة مرات وتلقّى نتيجة لذلك عدة طلبات، سيؤدي النقر على طلب معيّن وإكمال عملية المصادقة والإعداد إلى التأثير في تلك الرسالة المحدّدة فقط. لا يتم تغيير الرسائل الأخرى.
عند إعادة إرسال حدث تفاعل من النوع MESSAGE بهذه الطريقة، يجب أن يكون مطابقًا للحدث الأصلي، ولكن هناك بعض الحالات التي يمكن أن تختلف فيها أحداث التفاعل من النوع MESSAGE. على سبيل المثال، عندما تشير رسالة إلى كل من تطبيق Chat أ وتطبيق Chat ب، يمكن للمستخدم تعديل الرسالة إذا ردّ تطبيق Chat أ برسالة عادية قبل المصادقة باستخدام تطبيق Chat ب. في هذه الحالة، يتلقّى تطبيق المراسلة (ب) نص الرسالة المعدَّلة بعد أن يكمل المستخدم عملية المصادقة والإعداد.
مصادقة مستخدم Chat خارج Chat
في بعض الحالات، مثل طلب تفويض OAuth لواجهة برمجة تطبيقات، يحتاج تطبيقك إلى الربط بعنوان URL خارج Chat مع الحفاظ على هوية المستخدم. وأفضل طريقة لتحديد هوية المستخدم في هذه الحالات هي حماية التطبيق الوجهة باستخدام تسجيل الدخول باستخدام حساب Google.
استخدِم الرمز المميز للهوية الذي تم إصداره أثناء تسجيل الدخول للحصول على رقم تعريف المستخدم. يتضمّن طلب sub المعرّف الفريد للمستخدم ويمكن ربطه بمعرّف المستخدم من Google Chat.
على الرغم من أنّ المعرّفَين ليسا متطابقَين تمامًا، يمكن إجبارهما على التطابق. لفرض قيمة المطالبة sub على users/{user} في Google Chat، أضِف users/ قبل القيمة. على سبيل المثال، تكون قيمة المطالبة 123 مكافئة لاسم المستخدم users/123 في الرسائل إلى تطبيق Chat.
تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eGoogle Chat apps can connect with external services for enhanced functionality, such as account linking and data access.\u003c/p\u003e\n"],["\u003cp\u003eTo enable external connections, Chat apps use a configuration URL that prompts users to complete setup outside of Chat.\u003c/p\u003e\n"],["\u003cp\u003eUpon successful configuration, the original message in Chat becomes public and is resent to the app for processing.\u003c/p\u003e\n"],["\u003cp\u003eGoogle Sign-in is recommended for authenticating Chat users in external systems by using the identity token's \u003ccode\u003esub\u003c/code\u003e claim.\u003c/p\u003e\n"],["\u003cp\u003eEnsure the identity token's integrity is validated before using the user ID for any operations.\u003c/p\u003e\n"]]],["To connect a Google Chat app with external services, use a configuration URL returned in a `REQUEST_CONFIG` response, prompting users for authentication or configuration. This URL should include the `configCompleteRedirectUrl` provided by Chat, redirecting users back upon completion. Successful redirection erases the prompt, makes the original message public, and resends the original message to the Chat app. To maintain user identity outside Chat, use Google Sign-in and validate the integrity of the `sub` token.\n"],null,["# Connect a Chat app with other services and tools\n\n| **Note:** This guide explains how to build an interactive Chat app\n| using *Chat API interaction events* . You can also build your\n| Chat app as a Google Workspace add-on. To learn about which framework\n| to use, see [Build an interactive\n| Google Chat app](/workspace/chat/interact-users-overview).\n\n\u003cbr /\u003e\n\nThis page describes how to connect a Google Chat app with a service\nor tool that is outside of Google Chat. While Chat apps are\npowerful on their own, they often work in concert with other systems and require\ncompanion applications to connect accounts, authorize data access, display\nadditional data, or configure user preferences.\n\nPrerequisites\n-------------\n\n\u003cbr /\u003e\n\nA Google Chat app that's configured to receive and respond to [interaction events](/workspace/chat/receive-respond-interactions). To create an interactive Chat app, complete one of the following quickstarts based on the [app architecture](/workspace/chat/structure) that you want to use:\n\n- [HTTP service](/workspace/chat/quickstart/gcf-app) with Google Cloud Functions\n- [Google Apps Script](/workspace/chat/quickstart/apps-script-app)\n- [Google Cloud Dialogflow CX](/workspace/chat/build-dialogflow-chat-app-natural-language)\n- [Google Cloud Pub/Sub](/workspace/chat/quickstart/pub-sub)\n\nRequest Chat app configuration from a user\n------------------------------------------\n\nIf completing a request requires additional configuration that can't be\ncompleted directly in the Chat app, return a\nconfiguration URL to the user as part of a normal reply, or present it privately,\nin the following form: \n\n```\n{\n \"actionResponse\": {\n \"type\": \"REQUEST_CONFIG\",\n \"url\": \"CONFIGURATION_URL\"\n }\n}\n```\n\nThis tells Google Chat to present the user with a private prompt, where\n\u003cvar translate=\"no\"\u003eCONFIGURATION_URL\u003c/var\u003e is a link\nfor the user to visit for additional authentication, authorization, or\nconfiguration. A `REQUEST_CONFIG` response is mutually exclusive with a regular\nresponse message. Any text, cards, or other attributes are ignored.\n\nComplete the configuration request\n----------------------------------\n\nEvery\n[`MESSAGE`, `ADDED_TO_SPACE`, and `APP_COMMAND` interaction event](/workspace/chat/api/reference/rest/v1/EventType)\nthat your Chat app receives also includes the field\n`configCompleteRedirectUrl`. You must encode this URL in your\nconfiguration URL to be used on completion of the process. Redirecting to this\nURL signals to Google Chat that the configuration request was fulfilled.\n\nWhen your Chat app starts, the flow depends on the\nspecific message received. In response to a message like `@app help`, a\nChat app should respond with a message without\nrequiring additional configuration.\n\nWhen a user is successfully redirected to the `configCompleteRedirectUrl`\nprovided in the original message, Google Chat performs the following steps:\n\n1. Erase the prompt that was displayed to the initiating user.\n2. Convert the original message to public, making it visible to other members of the space.\n3. Send the original message to the same Chat app a second time.\n\nVisiting a `configCompleteRedirectUrl` only affects a single user message.\nIf a user has tried to message a Chat app multiple\ntimes and as a result received multiple prompts, clicking through a particular\nprompt and completing the authentication and configuration process only affects\nthat particular message. Other messages aren't changed.\n\nWhen a `MESSAGE` interaction event is resent in this way, it should be identical\nto the original event; however, there are some situations where `MESSAGE`\ninteraction events can differ. For example, when a message mentions both\nChat app A and Chat app B,\nthe user is able to edit the message if Chat app A\nresponds with a regular message before authenticating with\nChat app B. In this case,\nChat app B receives the edited message text after the\nuser completes authentication and configuration.\n\nAuthenticate the Chat user outside of Chat\n------------------------------------------\n\nIn some cases, such as requesting OAuth authorization for an API, your app needs\nto link to a URL outside of Chat while maintaining the user\nidentity. The best way to identify the user in these cases is to guard the\ndestination app with [Google Sign-in](/identity).\n\nUse the\n[identity token](/identity/sign-in/web/backend-auth)\nissued during sign-in to get the user ID. The `sub` claim contains the user's\nunique ID and can be correlated with the user ID from Google Chat.\n| **Caution:** Always [validate the integrity](/identity/sign-in/web/backend-auth#verify-the-integrity-of-the-id-token) of the token before accepting the asserted user ID.\n\nWhile the two IDs aren't exactly identical, they can be coerced. To\ncoerce the value of the `sub` claim to a Google Chat `users/{user}`, prepend\nthe value with `users/`. For example, the claim value of `123` is equivalent\nto the username `users/123` in messages to your\nChat app.\n\nRelated topics\n--------------\n\n- [Receive and respond to user interaction](/workspace/chat/receive-respond-interactions#receive)\n- The [MyProfile app example](https://github.com/googleworkspace/google-chat-samples/tree/main/python/auth-app) uses the identity token from the Google Sign-in response to identify the user."]]
