پیام‌های چت Google را ارسال کنید

این صفحه توضیح می‌دهد که چگونه برنامه‌های چت گوگل می‌توانند برای پاسخ به تعاملات کاربر، پیام ارسال کنند.

  • فرم تماس از دستور اسلش.
    شکل ۱. یک برنامه چت به یک دستور اسلش با یک پیام متنی و یک دکمه پاسخ می‌دهد.
  • فرم تماس در یک کادر محاوره‌ای.
    شکل ۲. یک برنامه چت، پنجره‌ای را باز می‌کند که کاربران می‌توانند در آن اطلاعات را وارد کنند.
  • پیام کارت با ابزارک‌های ورودی فرم.
    شکل ۵. یک برنامه چت، پیامی حاوی متن و یک کارت تعاملی ارسال می‌کند.

پیش‌نیازها

اچ‌تی‌پی

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

اسکریپت برنامه‌ها

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

طراحی پیام

برنامه‌های چت می‌توانند هر یک از موارد زیر را در یک پیام بگنجانند:

  • متنی که حاوی هایپرلینک، @mention و ایموجی باشد.
  • یک یا چند کارت، که می‌توانند در یک پیام ظاهر شوند یا در یک پنجره جدید به عنوان یک کادر محاوره‌ای باز شوند.
  • یک یا چند ویجت جانبی، که دکمه‌هایی هستند که بعد از هر متن یا کارتی در یک پیام ظاهر می‌شوند.

برای آشنایی با طراحی پیام‌ها، به مستندات Google Chat API زیر مراجعه کنید:

با پیام پاسخ دهید

برنامه‌های چت می‌توانند با ارسال پیام به هر یک از محرک‌ها یا تعاملات زیر پاسخ دهند:

  • محرک‌های پیام ، مانند زمانی که کاربران یک برنامه چت را منشن یا دایرکت می‌کنند.
  • محرک‌های اضافه شده به فضا ، مانند زمانی که کاربران برنامه چت را از Google Workspace Marketplace نصب می‌کنند یا آن را به یک فضا اضافه می‌کنند.
  • کلیک‌های دکمه از کارت‌ها در پیام‌ها یا پنجره‌های محاوره‌ای. به عنوان مثال، وقتی کاربران اطلاعات را وارد می‌کنند و روی ارسال کلیک می‌کنند.

در غیر این صورت، برنامه‌های چت می‌توانند با فراخوانی Google Chat API پیام‌ها را به صورت پیشگیرانه ارسال کنند.

برای پاسخ دادن با یک پیام، اکشن DataActions به همراه یک شیء CreateMessageAction برگردانید:

{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
  "message": MESSAGE
}}}

MESSAGE با یک منبع Message از Chat API جایگزین کنید. برای کسب اطلاعات بیشتر در مورد نحوه عملکرد اکشن‌ها، به Chat actions مراجعه کنید.

در مثال زیر، یک برنامه چت هر زمان که به یک فاصله اضافه شود، یک پیام متنی ایجاد و ارسال می‌کند. برای ارسال پیام متنی هنگامی که کاربر برنامه چت شما را به یک فاصله اضافه می‌کند، برنامه چت شما با بازگرداندن اکشن DataActions به تریگر Added to space پاسخ می‌دهد:

نود جی اس

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The request object from Google Workspace add-on.
 * @param {Object} res The response object from the Chat app.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  const chatEvent = req.body.chat;
  // Send an onboarding message when added to a Chat space
  if (chatEvent.addedToSpacePayload) {
    res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      text: 'Hi, Cymbal at your service. I help you manage your calendar' +
        'from Google Chat. Take a look at your schedule today by typing' +
        '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
        'To learn what else I can do, type `/help`.'
    }}}}});
  }
};

پایتون

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  chat_event = request.get_json()["chat"]
  if "addedToSpacePayload" in chat_event:
    return json.jsonify({ "hostAppDataAction": { "chatDataAction": {
      "createMessageAction": { "message": {
        "text": 'Hi, Cymbal at your service. I help you manage your calendar' +
        'from Google Chat. Take a look at your schedule today by typing' +
        '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
        'To learn what else I can do, type `/help`.'
      }}
    }}})

جاوا

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    JsonNode chatEvent = event.at("/chat");
    if(!chatEvent.at("/addedToSpacePayload").isEmpty()) {
      return new GenericJson() { {
        put("hostAppDataAction", new GenericJson() { {
          put("chatDataAction", new GenericJson() { {
            put("createMessageAction", new GenericJson() { {
              put("message", new Message().setText(
                "Hi, Cymbal at your service. I help you manage your calendar" +
                "from Google Chat. Take a look at your schedule today by typing" +
                "`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. " +
                "To learn what else I can do, type `/help`."
              ));
            } });
          } });
        } });
      } };
    }
  }
}

اسکریپت برنامه‌ها

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onAddedToSpace(event) {
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: 'Hi, Cymbal at your service. I help you manage your calendar' +
          'from Google Chat. Take a look at your schedule today by typing' +
          '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
          'To learn what else I can do, type `/help`.'
  }}}}};
}

نمونه کد، پیام متنی زیر را برمی‌گرداند:

نمونه پیام شروع به کار.

برای مثال‌های بیشتر در مورد نحوه پاسخ دادن به یک پیام، به راهنماهای زیر مراجعه کنید:

به‌روزرسانی یک پیام

برنامه‌های چت همچنین می‌توانند پیام‌هایی را که ارسال می‌کنند به‌روزرسانی کنند. برای مثال، برای به‌روزرسانی یک پیام پس از اینکه کاربر یک کادر محاوره‌ای ارسال کرد یا روی یک دکمه یا یک پیام کلیک کرد.

برای به‌روزرسانی پیام برنامه چت، اکشن DataActions را به همراه UpdateMessageAction برگردانید، همانطور که در مثال زیر نشان داده شده است:

{ "hostAppDataAction": { "chatDataAction": { "updateMessageAction": {
  "message": MESSAGE
}}}}

MESSAGE با یک منبع Message از Chat API جایگزین کنید.

برای کسب اطلاعات بیشتر در مورد نحوه عملکرد اکشن‌ها، به اکشن‌های چت مراجعه کنید.

برنامه‌های چت همچنین می‌توانند پیام دریافتی از کاربر را به‌روزرسانی کنند تا پیش‌نمایشی از لینکی که ارسال کرده است را برگردانند. برای جزئیات بیشتر، به پیش‌نمایش لینک‌ها در پیام‌های چت گوگل مراجعه کنید.

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

به جای برگرداندن یک عمل افزونه، برنامه‌های چت ممکن است نیاز داشته باشند از Google Chat API برای پاسخ به یک تعامل استفاده کنند. برای مثال، برنامه‌های چت باید Google Chat API را برای انجام هر یک از موارد زیر فراخوانی کنند:

  • ارسال پیام‌ها طبق برنامه یا در مورد تغییرات در منابع خارجی. به عنوان مثال، اعلان‌ها در مورد یک مسئله یا پرونده جدید.
  • بیش از ۳۰ ثانیه پس از تعامل پاسخ دهید. به عنوان مثال، برای پاسخ دادن با یک پیام پس از انجام یک کار طولانی مدت.
  • پیامی را به خارج از فضایی که تعامل در آن رخ داده است، ارسال کنید.
  • ارسال پیام از طرف یک کاربر چت.

برای ارسال پیام با استفاده از Chat API، باید احراز هویت را تنظیم کرده و متد create() را در منبع Message فراخوانی کنید. برای مراحل، به Send a message using the Google Chat API مراجعه کنید.