ارسال یک پیام

این راهنما روش های مختلفی را توضیح می دهد که برنامه های چت Google می توانند پیام ارسال کنند:

  • با پاسخ به تعامل کاربر، پیام‌های متنی و کارتی را در زمان واقعی ارسال کنید.
  • با فراخوانی متد create در منبع Message ، پیام های متنی و کارت را به صورت ناهمزمان ارسال کنید.
  • یک رشته پیام را شروع کنید یا به آن پاسخ دهید.
  • پیام بفرستید و نام ببرید.

منبع Message یک پیام متنی یا کارتی را در Google Chat نشان می دهد. می‌توانید با فراخوانی روش‌های مربوطه، پیامی را در Google Chat API create ، get ، update یا delete . برای کسب اطلاعات بیشتر درباره پیام‌های نوشتاری و کارتی، به نمای کلی پیام‌های گپ Google مراجعه کنید.

به جای فراخوانی روش create در منبع Message Google Chat API برای ارسال پیام متنی یا کارتی به صورت ناهمزمان، برنامه‌های چت Google همچنین می‌توانند پیام‌هایی برای پاسخگویی به تعاملات کاربر در زمان واقعی ایجاد کنند. پاسخ‌ها به تعاملات کاربر نیازی به احراز هویت ندارند و از انواع دیگر پیام‌ها از جمله گفتگوهای تعاملی و پیش‌نمایش پیوندها پشتیبانی می‌کنند. برای جزئیات، به دریافت و پاسخ به تعاملات با برنامه Google Chat خود مراجعه کنید.

پیش نیازها

Node.js

پایتون

  • پایتون 3.6 یا بالاتر
  • ابزار مدیریت بسته پیپ
  • جدیدترین کتابخانه های مشتری گوگل برای پایتون. برای نصب یا به روز رسانی آنها، دستور زیر را در رابط خط فرمان خود اجرا کنید:

    pip3 install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib oauth2client
    
  • یک برنامه چت منتشر شده. برای ایجاد و انتشار یک برنامه چت، به ساخت برنامه گپ Google مراجعه کنید.

  • مجوز برای برنامه Chat برای ارسال پیام‌های ناهمزمان پیکربندی شده است. هیچ پیکربندی مجوز برای ارسال پیام در زمان واقعی مورد نیاز نیست.

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

پیامک ارسال کنید

در این بخش نحوه ارسال پیامک به دو روش زیر توضیح داده شده است:

  • با پاسخ دادن به تعامل کاربر، یک پیام متنی در زمان واقعی ارسال کنید.
  • با تماس ناهمزمان با Google Chat API یک پیام متنی ارسال کنید.

در زمان واقعی پیامک ارسال کنید

در این مثال، برنامه چت شما هر زمان که به فضایی اضافه شود پیام متنی ایجاد کرده و ارسال می کند. برای آشنایی با بهترین شیوه‌ها برای کاربران حضوری، به شروع کار افراد و فضاها با ورود مفید مراجعه کنید.

برای ارسال پیام نوشتاری هنگامی که کاربر برنامه چت شما را به یک فضا اضافه می‌کند، برنامه چت شما به یک رویداد تعاملی ADDED_TO_SPACE پاسخ می‌دهد. برای پاسخ دادن به رویدادهای تعامل ADDED_TO_SPACE با یک پیام متنی، از کد زیر استفاده کنید:

Node.js

/**
 * 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. An onboarding message that
 * introduces the app and helps people get started with it.
 */
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat space.');
  }

  // Send an onboarding message when added to a Chat space
  if(req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      '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`.'
    });
  }
};

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

/**
 * 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. An onboarding message that
 * introduces the app and helps people get started with it.
 */
function onAddToSpace(event) {

  return {
    '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`.'
  }
}

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

نمونه پیام ورود.

ارسال پیام متنی به صورت ناهمزمان

بخش زیر نحوه ارسال پیام متنی به صورت ناهمزمان با احراز هویت برنامه و تأیید هویت کاربر را توضیح می دهد.

برای ارسال پیامک موارد زیر را در درخواست خود وارد کنید:

  • با احراز هویت برنامه، محدوده مجوز chat.bot را مشخص کنید. با احراز هویت کاربر، محدوده مجوز chat.messages.create را مشخص کنید.
  • متد create را در منبع Message فراخوانی کنید.

یک پیام متنی با احراز هویت برنامه ارسال کنید

در اینجا نحوه ارسال پیام متنی با تأیید اعتبار برنامه آمده است:

پایتون

  1. در فهرست کاری خود، یک فایل با نام chat_create_text_message_app.py ایجاد کنید.
  2. کد زیر را در chat_create_text_message_app.py قرار دهید:

    from httplib2 import Http
    from oauth2client.service_account import ServiceAccountCredentials
    from apiclient.discovery import build
    
    # Specify required scopes.
    SCOPES = ['https://www.googleapis.com/auth/chat.bot']
    
    # Specify service account details.
    CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
        'credentials.json', SCOPES)
    
    # Build the URI and authenticate with the service account.
    chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))
    
    # Create a Chat message.
    result = chat.spaces().messages().create(
    
        # The space to create the message in.
        #
        # Replace SPACE with a space name.
        # Obtain the space name from the spaces resource of Chat API,
        # or from a space's URL.
        parent='spaces/SPACE',
    
        # The message to create.
        body={'text': 'Hello, world!'}
    
    ).execute()
    
    print(result)
    
  3. در کد، SPACE با یک نام فضایی جایگزین کنید، که می توانید آن را از متد spaces.list() در Chat API یا از URL یک فضا دریافت کنید.

  4. در پوشه کاری خود، نمونه را بسازید و اجرا کنید:

    python3 chat_create_text_message_app.py
    

Chat API نمونه‌ای از Message را برمی‌گرداند که جزئیات پیام ارسال شده را نشان می‌دهد.

یک پیام متنی با احراز هویت کاربر ارسال کنید

در اینجا نحوه ارسال پیام متنی با احراز هویت کاربر آورده شده است:

پایتون

  1. در پوشه کاری خود، یک فایل با نام chat_create_text_message_user.py ایجاد کنید.
  2. کد زیر را در chat_create_text_message_user.py قرار دهید:

    import os.path
    
    from google.auth.transport.requests import Request
    from google.oauth2.credentials import Credentials
    from google_auth_oauthlib.flow import InstalledAppFlow
    from googleapiclient.discovery import build
    from googleapiclient.errors import HttpError
    
    # Define your app's authorization scopes.
    # When modifying these scopes, delete the file token.json, if it exists.
    SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"]
    
    def main():
        '''
        Authenticates with Chat API via user credentials,
        then creates a text message in a Chat space.
        '''
    
        # Start with no credentials.
        creds = None
    
        # Authenticate with Google Workspace
        # and get user authorization.
        flow = InstalledAppFlow.from_client_secrets_file(
                        'client_secrets.json', SCOPES)
        creds = flow.run_local_server()
    
        # Build a service endpoint for Chat API.
        chat = build('chat', 'v1', credentials=creds)
    
        # Use the service endpoint to call Chat API.
        result = chat.spaces().messages().create(
    
            # The space to create the message in.
            #
            # Replace SPACE with a space name.
            # Obtain the space name from the spaces resource of Chat API,
            # or from a space's URL.
            parent='spaces/SPACE',
    
            # The message to create.
            body={'text': 'Hello, world!'}
    
        ).execute()
    
        # Prints details about the created membership.
        print(result)
    
    if __name__ == '__main__':
        main()
    
  3. در کد، SPACE با یک نام فضایی جایگزین کنید، که می توانید آن را از متد spaces.list() در Chat API یا از URL یک فضا دریافت کنید.

  4. در پوشه کاری خود، نمونه را بسازید و اجرا کنید:

    python3 chat_create_text_message_user.py
    

Chat API نمونه‌ای از Message را برمی‌گرداند که جزئیات پیام ارسال شده را نشان می‌دهد.

ارسال پیام کارت

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

  • با پاسخ به تعامل کاربر، پیام کارت را در زمان واقعی ارسال کنید.
  • با تماس ناهمزمان با Google Chat API یک پیام کارتی ارسال کنید.

ارسال پیام کارت در زمان واقعی

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

در این مثال، یک کاربر پیامی را به یک برنامه چت ارسال می کند و برنامه چت با ارسال یک پیام کارتی که نام و تصویر آواتار کاربر را نمایش می دهد، پاسخ می دهد:

یک برنامه چت که با کارتی حاوی نام نمایشی فرستنده و تصویر آواتار پاسخ می‌دهد.

Node.js

node/avatar-app/index.js
/**
 * Google Cloud Function that responds to messages sent from a
 * Google Chat room.
 *
 * @param {Object} req Request sent from Google Chat room
 * @param {Object} res Response to send back
 */
exports.helloChat = function helloChat(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send('Hello! This function is meant to be used in a Google Chat ' +
      'Room.');
  }

  const sender = req.body.message.sender.displayName;
  const image = req.body.message.sender.avatarUrl;

  const data = createMessage(sender, image);

  res.send(data);
};

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} imageUrl the URL for the sender's avatar
 * @return {Object} a card with the user's avatar.
 */
function createMessage(displayName, imageUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`,
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '},
  };

  const avatarImageWidget = {
    image: {imageUrl},
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget,
    ],
  };

  return {
    text: 'Here\'s your avatar',
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

پایتون

python/avatar-app/main.py
from typing import Any, Mapping

import flask
import functions_framework


# Google Cloud Function that responds to messages sent in
# Google Chat.
#
# @param {Object} req Request sent from Google Chat.
# @param {Object} res Response to send back.
@functions_framework.http
def hello_chat(req: flask.Request) -> Mapping[str, Any]:
  if req.method == "GET":
    return "Hello! This function must be called from Google Chat."

  request_json = req.get_json(silent=True)

  display_name = request_json["message"]["sender"]["displayName"]
  avatar = request_json["message"]["sender"]["avatarUrl"]

  response = create_message(name=display_name, image_url=avatar)

  return response


# Creates a card with two widgets.
# @param {string} name the sender's display name.
# @param {string} image_url the URL for the sender's avatar.
# @return {Object} a card with the user's avatar.
def create_message(name: str, image_url: str) -> Mapping[str, Any]:
  avatar_image_widget = {"image": {"imageUrl": image_url}}
  avatar_text_widget = {"textParagraph": {"text": "Your avatar picture:"}}
  avatar_section = {"widgets": [avatar_text_widget, avatar_image_widget]}

  header = {"title": f"Hello {name}!"}

  cards = {
      "text": "Here's your avatar",
      "cardsV2": [
          {
              "cardId": "avatarCard",
              "card": {
                  "name": "Avatar Card",
                  "header": header,
                  "sections": [avatar_section],
              },
          }
      ]
  }

  return cards

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

apps-script/avatar-app/hello-chat.gs
/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
  const displayName = event.message.sender.displayName;
  const avatarUrl = event.message.sender.avatarUrl;

  return createMessage(displayName, avatarUrl);
}

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} avatarUrl the URL for the sender's avatar
 * @return {Object} a card with the sender's avatar.
 */
function createMessage(displayName, avatarUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '}
  };

  const avatarImageWidget = {
    image: {imageUrl: avatarUrl}
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget
    ],
  };

  return {
    text: 'Here\'s your avatar',
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

ارسال پیام کارت به صورت ناهمزمان

برای ارسال پیام کارت ، موارد زیر را در درخواست خود وارد کنید:

  • با احراز هویت برنامه، محدوده مجوز chat.bot را مشخص کنید. با احراز هویت کاربر نمی توانید پیام کارتی ارسال کنید.
  • متد create را در منبع Message فراخوانی کنید.

نمونه زیر یک پیام کارت است:

یک پیام کارت ارسال شده با Chat API.

در اینجا نحوه ارسال پیام کارت با تأیید اعتبار برنامه آمده است:

پایتون

  1. در پوشه کاری خود، یک فایل با نام chat_create_card_message.py ایجاد کنید.
  2. کد زیر را در chat_create_card_message.py قرار دهید:

    from httplib2 import Http
    from oauth2client.service_account import ServiceAccountCredentials
    from apiclient.discovery import build
    
    # Specify required scopes.
    SCOPES = ['https://www.googleapis.com/auth/chat.bot']
    
    # Specify service account details.
    CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
        'credentials.json', SCOPES)
    
    # Build the URI and authenticate with the service account.
    chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))
    
    # Create a Chat message.
    result = chat.spaces().messages().create(
    
        # The space to create the message in.
        #
        # Replace SPACE with a space name.
        # Obtain the space name from the spaces resource of Chat API,
        # or from a space's URL.
        parent='spaces/SPACE',
    
        # The message to create.
        body=
        {
          'cardsV2': [{
            'cardId': 'createCardMessage',
            'card': {
              'header': {
                'title': 'A card message!',
                'subtitle': 'Created with the Chat API',
                'imageUrl': 'https://developers.google.com/chat/images/chat-product-icon.png',
                'imageType': 'CIRCLE'
              },
              'sections': [
                {
                  'widgets': [
                    {
                      'buttonList': {
                        'buttons': [
                          {
                            'text': 'Read the docs!',
                            'onClick': {
                              'openLink': {
                                'url': 'https://developers.google.com/chat'
                              }
                            }
                          }
                        ]
                      }
                    }
                  ]
                }
              ]
            }
          }]
        }
    
    ).execute()
    
    print(result)
    
  3. در کد، SPACE با یک نام فاصله جایگزین کنید، که می توانید آن را از روش spaces.list در Chat API یا از URL یک فضا دریافت کنید.

  4. در پوشه کاری خود، نمونه را بسازید و اجرا کنید:

    python3 chat_create_card_message.py
    

یک رشته پیام را شروع کنید یا به آن پاسخ دهید

برای شروع یک رشته پیام، یک پیام ارسال کنید و thread.name خالی بگذارید. Google Chat هنگام ایجاد رشته آن را پر می کند. در صورت تمایل، برای سفارشی کردن نام رشته، فیلد thread.threadKey را مشخص کنید.

برای پاسخ دادن به رشته پیام، پیامی ارسال کنید که فیلد threadKey یا name رشته را مشخص کند. اگر رشته توسط شخص یا برنامه چت دیگری ایجاد شده است، باید از قسمت thread.name استفاده کنید.

اگر رشته منطبقی پیدا نشد، می توانید با تنظیم فیلد messageReplyOption تعیین کنید که آیا یک پیام باید یک رشته جدید شروع شود یا ارسال نشود.

در اینجا نحوه شروع یا پاسخ دادن به یک رشته با فیلد threadKey تعریف شده به عنوان nameOfThread آمده است:

پایتون

  1. در پوشه کاری خود، فایلی با نام chat_create_message_thread.py ایجاد کنید.
  2. کد زیر را در chat_create_message_thread.py قرار دهید:

    from httplib2 import Http
    from oauth2client.service_account import ServiceAccountCredentials
    from apiclient.discovery import build
    
    # Specify required scopes.
    SCOPES = ['https://www.googleapis.com/auth/chat.bot']
    
    # Specify service account details.
    CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
        'credentials.json', SCOPES)
    
    # Build the URI and authenticate with the service account.
    chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))
    
    # Create a Chat message.
    result = chat.spaces().messages().create(
    
        # The space to create the message in.
        #
        # Replace SPACE with a space name.
        # Obtain the space name from the spaces resource of Chat API,
        # or from a space's URL.
        parent='spaces/SPACE',
    
        # Whether to start a thread or reply to an existing one.
        #
        # Required when threading is enabled in a space unless starting a
        # thread.  Ignored in other space types. Threading is enabled when
        # space.spaceThreadingState is THREADED_MESSAGES.
        #
        # REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD replies to an existing thread
        # if one exists, otherwise it starts a new one.
        messageReplyOption='REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD',
    
        # The message body.
        body={
    
            # The message to create.
            'text': 'Start or reply to another message in a thread!',
    
            # The thread to start or reply to.
            'thread': {
                'threadKey': 'nameOfThread'
            }
        }
    
    ).execute()
    
    print(result)
    
  3. در کد، SPACE با یک نام فاصله جایگزین کنید، که می توانید آن را از روش spaces.list در Chat API یا از URL یک فضا دریافت کنید.

  4. در پوشه کاری خود، نمونه را بسازید و اجرا کنید:

    python3 chat_create_message_thread.py
    

Chat API نمونه‌ای از Message را برمی‌گرداند که جزئیات پیام ارسال شده را نشان می‌دهد.

پیام بفرستید و نام ببرید

این بخش نحوه ارسال پیام با نام سفارشی را توضیح می دهد. شما از نام پیام ها برای دریافت ، به روز رسانی یا حذف پیام ها استفاده می کنید. تخصیص یک نام سفارشی همچنین به یک برنامه چت اجازه می دهد پیام را بدون ذخیره name پیام از بدنه پاسخی که هنگام ارسال پیام بازگردانده شده است، فراخوانی کند.

اختصاص یک نام سفارشی جایگزین فیلد name ایجاد شده، نام منبع پیام نمی شود. در عوض، نام سفارشی را به‌عنوان فیلد clientAssignedMessageId تنظیم می‌کند که می‌توانید هنگام پردازش عملیات بعدی، مانند به‌روزرسانی یا حذف پیام، به آن ارجاع دهید.

نام های سفارشی دارای شرایط زیر هستند:

  • با client- شروع کنید- . برای مثال، client-custom-name یک نام سفارشی معتبر است، اما custom-name اینطور نیست.
  • فقط شامل حروف کوچک، اعداد و خط فاصله باشد.
  • از 63 کاراکتر بیشتر نباشد.
  • تعیین یک نام سفارشی استفاده شده در حین ارسال یک پیام، یک خطا برمی گرداند، اما روش های دیگر مانند update و delete مطابق انتظار عمل می کنند.

در اینجا نحوه ارسال و نامگذاری پیام آمده است:

پایتون

  1. در پوشه کاری خود، یک فایل با نام chat_create_named_message.py ایجاد کنید.
  2. کد زیر را در chat_create_named_message.py قرار دهید:

    from httplib2 import Http
    from oauth2client.service_account import ServiceAccountCredentials
    from apiclient.discovery import build
    
    # Specify required scopes.
    SCOPES = ['https://www.googleapis.com/auth/chat.bot']
    
    # Specify service account details.
    CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
        'credentials.json', SCOPES)
    
    # Build the URI and authenticate with the service account.
    chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))
    
    # Create a Chat message with a custom name.
    result = chat.spaces().messages().create(
    
        # The space to create the message in.
        #
        # Replace SPACE with a space name.
        # Obtain the space name from the spaces resource of Chat API,
        # or from a space's URL.
        parent='spaces/SPACE',
    
        # Custom name for the message used to facilitate later operations.
        messageId='client-custom-name',
    
        # The message to create.
        body={'text': 'Hello, world!'}
    
    ).execute()
    
    print(result)
    
  3. در کد، SPACE با یک نام فاصله جایگزین کنید، که می توانید آن را از روش spaces.list در Chat API یا از URL یک فضا دریافت کنید.

  4. در پوشه کاری خود، نمونه را بسازید و اجرا کنید:

    python3 chat_create_named_message.py
    

Chat API نمونه‌ای از Message را برمی‌گرداند که جزئیات پیام ارسال شده را نشان می‌دهد.

عیب یابی

وقتی یک برنامه یا کارت Google Chat خطایی را برمی‌گرداند، رابط Chat پیامی را نشان می‌دهد که می‌گوید «مشکلی پیش آمده است». یا "نمی توان به درخواست شما رسیدگی کرد." گاهی اوقات Chat UI هیچ پیام خطایی را نمایش نمی دهد، اما برنامه یا کارت Chat نتیجه غیرمنتظره ای ایجاد می کند. برای مثال، ممکن است پیام کارت ظاهر نشود.

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