ساختن صفحه اصلی برای برنامه Google Chat

این صفحه توضیح می‌دهد چگونه برای پیام‌های مستقیم با برنامه Google Chat خود صفحه اصلی بسازید. صفحه اصلی که در Google Chat API به‌عنوان صفحه اصلی برنامه نامیده می‌شود، یک رابط کارت قابل‌سفارشی‌سازی است که در برگه صفحه اصلی فضاهای پیام مستقیم ۱:۱ بین کاربر و برنامه Chat ظاهر می‌شود.

شکل ۱: نمونه‌ای از صفحه اصلی که در پیام‌های مستقیم با برنامه Chat ظاهر می‌شود.

برخلاف دیگر برنامه‌های میزبان Google Workspace، افزونه‌هایی که Chat را گسترش می‌دهند صفحه اصلی را در پانل دسترسی سریع سمت چپ نمایش نمی‌دهند و از addOns.common.homepageTrigger در مانیفست استفاده نمی‌کنند. درعوض، Chat صفحه اصلی شما را به‌عنوان کارتی در برگه صفحه اصلی پیام مستقیم ۱:۱ با برنامه Chat نمایش می‌دهد و در کنسول Google Cloud پیکربندی می‌شود.

می‌توانید از «صفحه اصلی برنامه» برای هم‌رسانی نکته‌هایی درباره تعامل با برنامه Chat، نمایش داشبورد کاربر شخصی‌سازی‌شده، یا اجازه دادن به کاربران برای دسترسی و پیکربندی سرویس یا ابزار خارجی از Chat استفاده کنید.

---

از «کارت‌ساز» برای طراحی و پیش‌نمایش پیام‌رسانی و واسط‌های کاربر برای برنامه‌های Chat استفاده کنید:

باز کردن «سازنده کارت»

---

پیش‌نیازها

HTTP

برنامه Google Chat که تعاملات کاربر را دریافت و به آن‌ها پاسخ می‌دهد. برای ساختن آن، شروع سریع HTTP را تکمیل کنید.

توجه: نمونه‌های کد در این راهنما برای اجرا به‌عنوان تابع Google Cloud Run برای Node.js نوشته شده‌اند.

Apps Script

برنامه Google Chat که تعاملات کاربر را دریافت و به آن‌ها پاسخ می‌دهد. برای ساختن یکی از آن‌ها، راه‌اندازی سریع Apps Script را تکمیل کنید.

پیکربندی «صفحه اصلی برنامه» برای برنامه Chat

برای پشتیبانی از «صفحه اصلی برنامه»، پشتیبانی از صفحه اصلی برنامه را فعال کنید و راه‌انداز صفحه اصلی برنامه را در کنسول Google Cloud پیکربندی کنید. برنامه Chat شما هرگاه کاربری زبانه صفحه اصلی را در پیام مستقیم دونفره با برنامه Chat باز می‌کند، رویداد راه‌انداز صفحه اصلی برنامه دریافت می‌کند.

برای پیکربندی «صفحه اصلی برنامه» در «کنسول Google Cloud»:

1. در کنسول Google Cloud، به منو > میاناهای برنامه‌سازی کاربردی و سرویس‌ها > میاناهای برنامه‌سازی کاربردی و سرویس‌های فعال > میانای برنامه‌سازی کاربردی Google Chat > پیکربندی بروید.

   رفتن به پیکربندی Chat API

2. در بخش ویژگی‌های تعاملی، مطمئن شوید که فعال کردن ویژگی‌های تعاملی روشن است، و سپس در بخش عملکرد، چارگوش پشتیبانی از صفحه اصلی برنامه را انتخاب کنید.

3. در بخش تنظیمات اتصال > محرک‌ها، کنترل‌کننده «صفحه اصلی برنامه» را در فیلد صفحه اصلی برنامه براساس معماری برنامه Chat خودتان مشخص کنید:

   • HTTP: نشانی وب نقطه پایان HTTPS را که درخواست‌های «صفحه اصلی برنامه» را مدیریت می‌کند وارد کنید (یا استفاده از نشانی وب نقطه پایان HTTP مشترک برای همه راه‌اندازها را انتخاب کنید تا نشانی وب نقطه پایان HTTP مشترک شما همه رویدادها را دریافت کند).
   • Google Apps Script: نام تابع تماس برگشتی Google Apps Script را که کارت صفحه اصلی شما را می‌سازد و برمی‌گرداند وارد کنید (به‌طور پیش‌فرض روی onAppHome تنظیم شده است).

4. روی ذخیره کلیک کنید.

پردازش کردن شیء رویداد «صفحه اصلی برنامه»

وقتی کاربری برگه صفحه اصلی پیام مستقیم یک‌به‌یک با برنامه Chat شما را باز می‌کند، Chat یک شیء رویداد به نقطه پایانی «صفحه اصلی برنامه» یا تابع برگشت تماس شما ارسال می‌کند.

برخلاف رویدادهای تعامل پیام یا فضا، شیء رویداد «صفحه اصلی برنامه» اولیه شامل بار تعامل اتحادی (مثل messagePayload) نمی‌شود. این شیء شامل فیلدهای زیر است:

• commonEventObject: شامل clientPlatform، hostApp ("CHAT")، userLocale، و userTimezone.
• chat.user: کاربر Chat که برگه صفحه اصلی را باز کرده است.
• ‫chat.eventTime: مُهر زمان وقتی کاربر زبانه صفحه اصلی را باز کرد.

ساختن کارت «صفحه اصلی برنامه»

وقتی کاربری زبانه صفحه اصلی را باز می‌کند، رویداد راه‌انداز صفحه اصلی برنامه را با برگرداندن شیء RenderActions با pushCardکنش پیمایش و Card مدیریت کنید. برای ایجاد تجربه‌ای تعاملی، کارت می‌تواند حاوی ابزارک‌های تعاملی مثل دکمه‌ها یا ورودی‌های نوشتاری باشد.

HTTP

{
  "action": {
    "navigations": [
      {
        "pushCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Manage your settings and view your dashboard here."
                  }
                },
                {
                  "buttonList": {
                    "buttons": [
                      {
                        "text": "Refresh",
                        "onClick": {
                          "action": {
                            "function": "https://example.com/updateAppHome"
                          }
                        }
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Apps Script

/**
 * Builds and returns the App Home card when a user opens the Home tab.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {ActionResponse} The RenderActions response pushing the homepage card.
 */
function onAppHome(event) {
  const card = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection()
              .addWidget(
                  CardService.newTextParagraph().setText(
                      'Manage your settings and view your dashboard here.'))
              .addWidget(
                  CardService.newButtonSet().addButton(
                      CardService.newTextButton()
                          .setText('Refresh')
                          .setOnClickAction(
                              CardService.newAction().setFunctionName(
                                  'updateAppHome')))))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().pushCard(card))
      .build();
}

پاسخ دادن به تعاملات «صفحه اصلی برنامه»

اگر کارت «صفحه اصلی برنامه» شما حاوی ابزارک‌های تعاملی، مثل دکمه‌ها یا ورودی‌های فرم، باشد، کلیک کردن روی دکمه یک شیء رویداد حاوی chat.buttonClickedPayload (همراه با commonEventObject.parameters و commonEventObject.formInputs) به تابع کنش پیکربندی‌شده دکمه یا نقطه پایانی ارسال می‌کند.

برای به‌روز کردن کارت «صفحه اصلی برنامه» در پاسخ به تعامل کاربر، RenderActions شیئی با کنش updateCard پیمایش برگردانید. برای کسب اطلاعات بیشتر درباره خواندن ورودی‌های فرم از ابزارک‌های تعاملی، به خواندن ورودی داده‌های فرم توسط کاربران در کارت‌ها مراجعه کنید.

HTTP

{
  "action": {
    "navigations": [
      {
        "updateCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Last updated: 2026-10-02T23:00:00Z"
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Apps Script

/**
 * Updates the App Home card when a user clicks the Refresh button.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {ActionResponse} The RenderActions response updating the homepage card.
 */
function updateAppHome(event) {
  const updatedCard = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection().addWidget(
              CardService.newTextParagraph().setText(
                  'Last updated: ' + new Date().toTimeString())))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().updateCard(updatedCard))
      .build();
}

باز کردن کادرهای گفتگو از «صفحه اصلی برنامه»

برنامه Chat شما همچنین می‌تواند با باز کردن کادرهای گفتگو به تعاملات در «صفحه اصلی برنامه» پاسخ دهد.

شکل ۲: کادر گفتگویی که از کاربر می‌خواهد مخاطبی اضافه کند.

برای آشنایی با نحوه باز کردن، به‌روز کردن، و بستن کادرهای گفتگو بااستفاده از RenderActions (pushCard، updateCard، و endNavigation: "CLOSE_DIALOG")، به باز کردن کادرهای گفتگوی تعاملی مراجعه کنید.

موضوعات مرتبط

• دریافت و پاسخ به تعاملات کاربر
• باز کردن کادرهای گفتگوی تعاملی
• خواندن داده‌های فرم واردشده توسط کاربران در کارت‌ها
• مشاهده نمونه‌های برنامه Chat

برنامه‌های Chat که برافزا نیستند: ساختن صفحه اصلی برای برنامه Chat

اگر برنامه Chat را که برافزای Google Workspace نیست حفظ کنید، Chat وقتی کاربر زبانه صفحه اصلی را باز می‌کند، APP_HOME رویداد تعامل ارسال می‌کند و وقتی کاربر با ابزاره‌های کارت «صفحه اصلی برنامه» تعامل برقرار می‌کند، رویدادهای تعامل CARD_CLICKED یا SUBMIT_FORM ارسال می‌کند.

برای ارتقا دادن برنامه Chat که برافزا نیست به چارچوب برافزاهای Google Workspace، به تبدیل برنامه Google Chat به برافزای Google Workspace مراجعه کنید.

ساختن کارت «صفحه اصلی برنامه» در برنامه Chat که برافزا نیست

در برنامه Chat که برافزا نیست، رویداد تعامل APP_HOME را با برگرداندن پاسخی که حاوی فیلد سطح بالای renderActions با پیمایش pushCard است مدیریت کنید:

Node.js

node/app-home/index.js

مشاهده در GitHub

app.post('/', async (req, res) => {
  let event = req.body.chat;

  let body = {};
  if (event.type === 'APP_HOME') {
    // App home is requested
    body = { action: { navigations: [{
      pushCard: getHomeCard()
    }]}}
  } else if (event.type === 'SUBMIT_FORM') {
    // The update button from app home is clicked
    commonEvent = req.body.commonEventObject;
    if (commonEvent && commonEvent.invokedFunction === 'updateAppHome') {
      body = updateAppHome()
    }
  }

  return res.json(body);
});

// Create the app home card
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

Python

python/app-home/main.py

مشاهده در GitHub

@app.route('/', methods=['POST'])
def post() -> Mapping[str, Any]:
  """Handle requests from Google Chat

  Returns:
      Mapping[str, Any]: the response
  """
  event = request.get_json()
  match event['chat'].get('type'):

    case 'APP_HOME':
      # App home is requested
      body = { "action": { "navigations": [{
        "pushCard": get_home_card()
      }]}}

    case 'SUBMIT_FORM':
      # The update button from app home is clicked
      event_object = event.get('commonEventObject')
      if event_object is not None:
        if 'update_app_home' == event_object.get('invokedFunction'):
          body = update_app_home()

    case _:
      # Other response types are not supported
      body = {}

  return json.jsonify(body)


def get_home_card() -> Mapping[str, Any]:
  """Create the app home card

  Returns:
      Mapping[str, Any]: the card
  """
  return { "sections": [{ "widgets": [
    { "textParagraph": {
      "text": "Here is the app home 🏠 It's " +
        datetime.datetime.now().isoformat()
    }},
    { "buttonList": { "buttons": [{
      "text": "Update app home",
      "onClick": { "action": {
        "function": "update_app_home"
      }}
    }]}}
  ]}]}

جاوا

java/app-home/src/main/java/com/google/chat/app/home/App.java

مشاهده در GitHub

// Process Google Chat events
@PostMapping("/")
@ResponseBody
public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
  switch (event.at("/chat/type").asText()) {
    case "APP_HOME":
      // App home is requested
      GenericJson navigation = new GenericJson();
      navigation.set("pushCard", getHomeCard());

      GenericJson action = new GenericJson();
      action.set("navigations", List.of(navigation));

      GenericJson response = new GenericJson();
      response.set("action", action);
      return response;
    case "SUBMIT_FORM":
      // The update button from app home is clicked
      if (event.at("/commonEventObject/invokedFunction").asText().equals("updateAppHome")) {
        return updateAppHome();
      }
  }

  return new GenericJson();
}

// Create the app home card
GoogleAppsCardV1Card getHomeCard() {
  return new GoogleAppsCardV1Card()
    .setSections(List.of(new GoogleAppsCardV1Section()
      .setWidgets(List.of(
        new GoogleAppsCardV1Widget()
          .setTextParagraph(new GoogleAppsCardV1TextParagraph()
            .setText("Here is the app home 🏠 It's " + new Date())),
        new GoogleAppsCardV1Widget()
          .setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
            .setText("Update app home")
            .setOnClick(new GoogleAppsCardV1OnClick()
              .setAction(new GoogleAppsCardV1Action()
                .setFunction("updateAppHome"))))))))));
}

Apps Script

این مثال با برگرداندن JSON کارت، پیام کارت ارسال می‌کند. همچنین می‌توانید از خدمات کارت Apps Script استفاده کنید.

apps-script/app-home/app-home.gs

مشاهده در GitHub

/**
 * Responds to a APP_HOME event in Google Chat.
 */
function onAppHome() {
  return { action: { navigations: [{
    pushCard: getHomeCard()
  }]}};
}

/**
 * Returns the app home card.
 */
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

پاسخ دادن به تعاملات «صفحه اصلی برنامه» در برنامه Chat که برافزا نیست

در برنامه Chat که برافزا نیست، رویدادهای تعاملی CARD_CLICKED یا SUBMIT_FORM را از کارت «صفحه اصلی برنامه» با برگرداندن پاسخی که حاوی فیلد renderActions سطح بالا با updateCard پیمایش است مدیریت کنید:

Node.js

node/app-home/index.js

مشاهده در GitHub

// Update the app home
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}}
};

Python

python/app-home/main.py

مشاهده در GitHub

def update_app_home() -> Mapping[str, Any]:
  """Update the app home

  Returns:
      Mapping[str, Any]: the update card render action
  """
  return { "renderActions": { "action": { "navigations": [{
    "updateCard": get_home_card()
  }]}}}

جاوا

java/app-home/src/main/java/com/google/chat/app/home/App.java

مشاهده در GitHub

// Update the app home
GenericJson updateAppHome() {
  GenericJson navigation = new GenericJson();
  navigation.set("updateCard", getHomeCard());

  GenericJson action = new GenericJson();
  action.set("navigations", List.of(navigation));

  GenericJson renderActions = new GenericJson();
  renderActions.set("action", action);

  GenericJson response = new GenericJson();
  response.set("renderActions", renderActions);
  return response;
}

Apps Script

این مثال با برگرداندن JSON کارت، پیام کارت ارسال می‌کند. همچنین می‌توانید از خدمات کارت Apps Script استفاده کنید.

apps-script/app-home/app-home.gs

مشاهده در GitHub

/**
 * Updates the home app.
 */
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}};
}