یک برنامه چت را با سرویس ها و ابزارهای دیگر متصل کنید
با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
این صفحه نحوه اتصال یک برنامه Google Chat را با سرویس یا ابزاری که خارج از Google Chat است توضیح می دهد. در حالی که برنامه‌های چت به تنهایی قدرتمند هستند، اغلب با سیستم‌های دیگر کار می‌کنند و به برنامه‌های همراه برای اتصال حساب‌ها، مجوز دسترسی به داده‌ها، نمایش داده‌های اضافی یا پیکربندی تنظیمات برگزیده کاربر نیاز دارند.
پیش نیازها
یک برنامه Google Chat که برای دریافت و پاسخگویی به رویدادهای تعامل پیکربندی شده است. برای ایجاد یک برنامه چت تعاملی، یکی از شروع سریع زیر را بر اساس معماری برنامه ای که می خواهید استفاده کنید، انجام دهید:
اگر تکمیل یک درخواست به پیکربندی اضافی نیاز دارد که نمی‌توان آن را مستقیماً در برنامه چت تکمیل کرد، یک URL پیکربندی را به عنوان بخشی از یک پاسخ معمولی به کاربر برگردانید، یا آن را به صورت خصوصی در فرم زیر ارائه دهید:
این به Google Chat می‌گوید که یک درخواست خصوصی به کاربر ارائه دهد، که در آن CONFIGURATION_URL پیوندی است که کاربر باید برای احراز هویت، مجوز، یا پیکربندی بیشتر از آن بازدید کند. یک پاسخ REQUEST_CONFIG با یک پیام پاسخ معمولی متقابل است. هر متن، کارت یا سایر ویژگی‌ها نادیده گرفته می‌شوند.
درخواست پیکربندی را تکمیل کنید
هر رویداد تعاملی MESSAGE ، ADDED_TO_SPACE ، و APP_COMMAND که برنامه چت شما دریافت می‌کند، شامل فیلد configCompleteRedirectUrl نیز می‌شود. شما باید این URL را در URL پیکربندی خود رمزگذاری کنید تا در تکمیل فرآیند مورد استفاده قرار گیرد. هدایت مجدد به این URL نشان می دهد که درخواست پیکربندی به Google Chat انجام شده است.
وقتی برنامه چت شما شروع می شود، جریان به پیام دریافتی خاص بستگی دارد. در پاسخ به پیامی مانند @app help ، یک برنامه چت باید بدون نیاز به پیکربندی اضافی با پیامی پاسخ دهد.
هنگامی که کاربر با موفقیت به configCompleteRedirectUrl ارائه شده در پیام اصلی هدایت می شود، Google Chat مراحل زیر را انجام می دهد:
درخواستی را که به کاربر آغازگر نمایش داده شده است پاک کنید.
پیام اصلی را به عمومی تبدیل کنید تا برای سایر اعضای فضا قابل مشاهده باشد.
پیام اصلی را برای بار دوم به همان برنامه چت ارسال کنید.
بازدید از configCompleteRedirectUrl تنها بر یک پیام کاربر تأثیر می گذارد. اگر کاربر چندین بار سعی کرده است به یک برنامه چت پیام ارسال کند و در نتیجه چندین درخواست دریافت کرده است، کلیک کردن روی یک درخواست خاص و تکمیل فرآیند تأیید هویت و پیکربندی تنها بر آن پیام خاص تأثیر می‌گذارد. سایر پیام ها تغییر نمی کنند
هنگامی که یک رویداد تعاملی MESSAGE به این روش ارسال می شود، باید با رویداد اصلی یکسان باشد. با این حال، شرایطی وجود دارد که رویدادهای تعامل MESSAGE ممکن است متفاوت باشد. به عنوان مثال، وقتی پیامی به برنامه Chat A و Chat B اشاره می‌کند، اگر برنامه Chat A قبل از احراز هویت با برنامه Chat B با یک پیام معمولی پاسخ دهد، کاربر می‌تواند پیام را ویرایش کند. در این حالت، برنامه Chat B متن پیام ویرایش‌شده را پس از تکمیل احراز هویت و پیکربندی توسط کاربر دریافت می‌کند.
کاربر چت را خارج از چت احراز هویت کنید
در برخی موارد، مانند درخواست مجوز OAuth برای یک API، برنامه شما باید با حفظ هویت کاربر، به URL خارج از Chat پیوند دهد. بهترین راه برای شناسایی کاربر در این موارد، محافظت از برنامه مقصد با Google Sign-in است.
برای دریافت شناسه کاربری از کد هویت صادر شده در هنگام ورود به سیستم استفاده کنید. ادعای sub حاوی شناسه منحصر به فرد کاربر است و می تواند با شناسه کاربر از چت Google مرتبط باشد.
در حالی که این دو شناسه دقیقاً یکسان نیستند، اما می توان آنها را اجبار کرد. برای وادار کردن ارزش ادعای sub به users/{user} Google Chat، مقدار را به users/ اضافه کنید. برای مثال، مقدار ادعای 123 معادل نام کاربری users/123 در پیام‌های برنامه چت شما است.
تاریخ آخرین بهروزرسانی 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."]]
