این راهنما روش های مختلفی را توضیح می دهد که برنامه های چت Google می توانند پیام ارسال کنند:
- با پاسخ به تعامل کاربر، پیامهای متنی و کارتی را در زمان واقعی ارسال کنید.
- با فراخوانی متد
create
در منبعMessage
، پیام های متنی و کارت را به صورت ناهمزمان ارسال کنید. - یک رشته پیام را شروع کنید یا به آن پاسخ دهید.
- پیام بفرستید و نام ببرید.
منبع Message
یک پیام متنی یا کارتی را در Google Chat نشان می دهد. میتوانید با فراخوانی روشهای مربوطه، پیامی را در Google Chat API create
، get
، update
یا delete
. برای کسب اطلاعات بیشتر درباره پیامهای نوشتاری و کارتی، به نمای کلی پیامهای گپ Google مراجعه کنید.
حداکثر اندازه پیام (شامل هر متن یا کارت) 32000 بایت است. اگر اندازه پیام بیشتر از این باشد، برنامه Chat شما میتواند در عوض چندین پیام ارسال کند.
به جای فراخوانی روش create
در منبع Message
Google Chat API برای ارسال پیام متنی یا کارتی به صورت ناهمزمان، برنامههای چت Google همچنین میتوانند پیامهایی برای پاسخگویی به تعاملات کاربر در زمان واقعی ایجاد کنند. پاسخها به تعاملات کاربر نیازی به احراز هویت ندارند و از انواع دیگر پیامها از جمله گفتگوهای تعاملی و پیشنمایش پیوندها پشتیبانی میکنند. برای جزئیات، به دریافت و پاسخ به تعاملات با برنامه Google Chat خود مراجعه کنید.
پیش نیازها
Node.js
- یک حساب Google Workspace با دسترسی به Google Chat .
- یک پروژه Google Cloud با Google Chat API فعال و پیکربندی شده است. برای مراحل، به ساخت برنامه گپ Google مراجعه کنید.
- مجوز برای برنامه Chat برای ارسال پیامهای ناهمزمان پیکربندی شده است. هیچ پیکربندی مجوز برای ارسال پیام در زمان واقعی مورد نیاز نیست.
- ارسال پیام متنی از هر دو روش مجوز زیر پشتیبانی می کند:
- احراز هویت کاربر با محدوده مجوز
chat.messages.create
یاchat.messages
. - احراز هویت برنامه با محدوده مجوز
chat.bot
.
- احراز هویت کاربر با محدوده مجوز
- ارسال پیام کارت نیاز به احراز هویت برنامه با محدوده مجوز
chat.bot
دارد.
- ارسال پیام متنی از هر دو روش مجوز زیر پشتیبانی می کند:
پایتون
- یک حساب Google Workspace با دسترسی به Google Chat .
- پایتون 3.6 یا بالاتر
- ابزار مدیریت بسته پیپ
جدیدترین کتابخانه های مشتری گوگل برای پایتون. برای نصب یا به روز رسانی آنها، دستور زیر را در رابط خط فرمان خود اجرا کنید:
pip3 install --upgrade google-api-python-client google-auth
- یک پروژه Google Cloud با Google Chat API فعال و پیکربندی شده است. برای مراحل، به ساخت برنامه گپ Google مراجعه کنید.
مجوز برای برنامه Chat برای ارسال پیامهای ناهمزمان پیکربندی شده است. هیچ پیکربندی مجوز برای ارسال پیام در زمان واقعی مورد نیاز نیست.
- ارسال پیام متنی از هر دو روش مجوز زیر پشتیبانی می کند:
- احراز هویت کاربر با محدوده مجوز
chat.messages.create
یاchat.messages
. - احراز هویت برنامه با محدوده مجوز
chat.bot
.
- احراز هویت کاربر با محدوده مجوز
- ارسال پیام کارت نیاز به احراز هویت برنامه با محدوده مجوز
chat.bot
دارد.
- ارسال پیام متنی از هر دو روش مجوز زیر پشتیبانی می کند:
اسکریپت برنامه ها
- یک حساب Google Workspace با دسترسی به Google Chat .
- یک برنامه چت منتشر شده. برای ایجاد یک برنامه چت، این شروع سریع را دنبال کنید.
- مجوز برای برنامه Chat برای ارسال پیامهای ناهمزمان پیکربندی شده است. هیچ پیکربندی مجوز برای ارسال پیام در زمان واقعی مورد نیاز نیست.
- ارسال پیام متنی از هر دو روش مجوز زیر پشتیبانی می کند:
- احراز هویت کاربر با محدوده مجوز
chat.messages.create
یاchat.messages
. - احراز هویت برنامه با محدوده مجوز
chat.bot
.
- احراز هویت کاربر با محدوده مجوز
- ارسال پیام کارت نیاز به احراز هویت برنامه با محدوده مجوز
chat.bot
دارد.
- ارسال پیام متنی از هر دو روش مجوز زیر پشتیبانی می کند:
پیامک ارسال کنید
در این بخش نحوه ارسال پیامک به دو روش زیر توضیح داده شده است:
- با پاسخ دادن به تعامل کاربر، یک پیام متنی در زمان واقعی ارسال کنید.
- با تماس ناهمزمان با 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
فراخوانی کنید.
یک پیام متنی با احراز هویت برنامه ارسال کنید
در اینجا نحوه ارسال پیام متنی با تأیید اعتبار برنامه آمده است:
پایتون
- در فهرست کاری خود، یک فایل با نام
chat_create_text_message_app.py
ایجاد کنید. کد زیر را در
chat_create_text_message_app.py
قرار دهید:from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # 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)
در کد،
SPACE
با یک نام فضایی جایگزین کنید، که می توانید آن را از متدspaces.list()
در Chat API یا از URL یک فضا دریافت کنید.در پوشه کاری خود، نمونه را بسازید و اجرا کنید:
python3 chat_create_text_message_app.py
Chat API نمونهای از Message
را برمیگرداند که جزئیات پیام ارسال شده را نشان میدهد.
یک پیام متنی با احراز هویت کاربر ارسال کنید
در اینجا نحوه ارسال پیام متنی با احراز هویت کاربر آورده شده است:
پایتون
- در پوشه کاری خود، یک فایل با نام
chat_create_text_message_user.py
ایجاد کنید. کد زیر را در
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 message. print(result) if __name__ == '__main__': main()
در کد،
SPACE
با یک نام فضایی جایگزین کنید، که می توانید آن را از متدspaces.list()
در Chat API یا از URL یک فضا دریافت کنید.در پوشه کاری خود، نمونه را بسازید و اجرا کنید:
python3 chat_create_text_message_user.py
Chat API نمونهای از Message
را برمیگرداند که جزئیات پیام ارسال شده را نشان میدهد.
ارسال پیام کارت
این بخش نحوه ارسال پیام های کارت را به دو روش زیر شرح می دهد:
- با پاسخ به تعامل کاربر، پیام کارت را در زمان واقعی ارسال کنید.
- با تماس ناهمزمان با Google Chat API یک پیام کارتی ارسال کنید.
ارسال پیام کارت در زمان واقعی
برنامههای چت میتوانند پیامهای کارتی ایجاد کنند تا به تعامل کاربر پاسخ دهند، مانند زمانی که کاربر برای برنامه چت پیامی ارسال میکند یا برنامه چت را به یک فضا اضافه میکند. برای کسب اطلاعات بیشتر درباره پاسخ به تعاملات کاربر، به رویدادهای تعامل برنامه گپ دریافت و پاسخ دهید .
در این مثال، یک کاربر پیامی را به یک برنامه چت ارسال می کند و برنامه چت با ارسال یک پیام کارتی که نام و تصویر آواتار کاربر را نمایش می دهد، پاسخ می دهد:
Node.js
پایتون
اسکریپت برنامه ها
این مثال با برگرداندن کارت JSON یک پیام کارت ارسال می کند. همچنین میتوانید از سرویس کارت برنامههای اسکریپت استفاده کنید.
ارسال پیام کارت به صورت ناهمزمان
برای ارسال پیام کارت ، موارد زیر را در درخواست خود وارد کنید:
- با احراز هویت برنامه، محدوده مجوز
chat.bot
را مشخص کنید. با احراز هویت کاربر نمی توانید پیام کارتی ارسال کنید. - متد
create
را در منبعMessage
فراخوانی کنید.
نمونه زیر یک پیام کارت است:
در اینجا نحوه ارسال پیام کارت با تأیید اعتبار برنامه آمده است:
پایتون
- در پوشه کاری خود، یک فایل با نام
chat_create_card_message.py
ایجاد کنید. کد زیر را در
chat_create_card_message.py
قرار دهید:from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # 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)
در کد،
SPACE
با یک نام فاصله جایگزین کنید، که می توانید آن را از روشspaces.list
در Chat API یا از URL یک فضا دریافت کنید.در پوشه کاری خود، نمونه را بسازید و اجرا کنید:
python3 chat_create_card_message.py
یک رشته پیام را شروع کنید یا به آن پاسخ دهید
برای شروع یک رشته پیام، یک پیام ارسال کنید و thread.name
خالی بگذارید. Google Chat هنگام ایجاد رشته آن را پر می کند. در صورت تمایل، برای سفارشی کردن نام رشته، فیلد thread.threadKey
را مشخص کنید.
برای پاسخ دادن به رشته پیام، پیامی ارسال کنید که threadKey
یا name
رشته را مشخص کند. اگر رشته توسط شخص یا برنامه چت دیگری ایجاد شده است، باید از قسمت thread.name
استفاده کنید.
اگر رشته منطبقی پیدا نشد، می توانید با تنظیم فیلد messageReplyOption
تعیین کنید که آیا یک پیام باید یک رشته جدید شروع شود یا ارسال نشود.
اگر messageReplyOption
تنظیم شده است، باید thread.name
یا thread.threadKey
را نیز تنظیم کنید.
در اینجا نحوه شروع یا پاسخ دادن به یک رشته با فیلد threadKey
تعریف شده به عنوان nameOfThread
آمده است:
پایتون
- در پوشه کاری خود، فایلی با نام
chat_create_message_thread.py
ایجاد کنید. کد زیر را در
chat_create_message_thread.py
قرار دهید:from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # 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)
در کد،
SPACE
با یک نام فاصله جایگزین کنید، که می توانید آن را از روشspaces.list
در Chat API یا از URL یک فضا دریافت کنید.در پوشه کاری خود، نمونه را بسازید و اجرا کنید:
python3 chat_create_message_thread.py
Chat API نمونهای از Message
را برمیگرداند که جزئیات پیام ارسال شده را نشان میدهد.
یک پیام را نام ببرید
این بخش نحوه نامگذاری پیام را با تنظیم یک شناسه سفارشی برای پیام توضیح می دهد. میتوانید از شناسههای سفارشی برای دریافت، بهروزرسانی یا حذف پیامها استفاده کنید. شناسههای سفارشی به شما امکان میدهند پیامی را بدون نیاز به ذخیره شناسه اختصاص داده شده به سیستم از نام منبع پیام (که در قسمت name
نشان داده شده است) مشخص کنید. هنگام ایجاد پیام، نام منبع در بدنه پاسخ ایجاد می شود.
به عنوان مثال، برای بازیابی یک پیام با استفاده از متد get()
، از نام منبع استفاده می کنید تا مشخص کنید کدام پیام را بازیابی کنید. نام منبع به صورت spaces/{space}/messages/{message}
قالببندی میشود، جایی که {message}
شناسه اختصاص داده شده به سیستم را نشان میدهد. اگر پیام را نامگذاری کرده اید، می توانید مقدار {message}
را با شناسه سفارشی جایگزین کنید.
برای نامگذاری پیام، هنگام ایجاد پیام، یک شناسه سفارشی را در قسمت messageId
تعیین کنید. فیلد messageId
مقدار فیلد clientAssignedMessageId
منبع Message
را تعیین می کند.
زمانی که پیام را ایجاد میکنید، فقط میتوانید پیامی را نام ببرید. نمیتوانید یک شناسه سفارشی برای پیامهای موجود نامگذاری یا تغییر دهید. شناسه سفارشی باید شرایط زیر را داشته باشد:
- با
client-
شروع می شود- . برای مثال،client-custom-name
یک شناسه سفارشی معتبر است، اماcustom-name
نیست. - دارای حداکثر 63 کاراکتر و فقط حروف کوچک، اعداد و خط فاصله است.
- در یک فضا منحصر به فرد است. برنامه چت نمیتواند از یک شناسه سفارشی برای پیامهای مختلف استفاده کند.
در اینجا نحوه ارسال پیام با شناسه سفارشی آمده است:
پایتون
- در پوشه کاری خود، یک فایل با نام
chat_create_named_message.py
ایجاد کنید. کد زیر را در
chat_create_named_message.py
قرار دهید:from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # 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-NAME', # The message to create. body={'text': 'Hello, world!'} ).execute() print(result)
در کد زیر را جایگزین کنید:
-
SPACE
: شناسه فضایی که میخواهید پیام را در آن پست کنید، که میتوانید از روشspaces.list
در Chat API یا از URL یک فضا دریافت کنید. -
NAME
: نام سفارشی پیام.
-
در پوشه کاری خود، نمونه را بسازید و اجرا کنید:
python3 chat_create_named_message.py
Chat API نمونهای از Message
برمیگرداند.
ویجت های تعاملی را در پایین پیام اضافه کنید
به صورت اختیاری، میتوانید پیامها را با ویجتهای جانبی اضافه کنید. ویجت های لوازم جانبی بعد از هر متن یا کارتی در پیام ظاهر می شوند. شما می توانید از این ویجت ها برای ترغیب کاربران به تعامل با پیام شما به طرق مختلف استفاده کنید، از جمله موارد زیر:
- دقت یا رضایت یک پیام را ارزیابی کنید.
- مشکل پیام یا برنامه چت را گزارش کنید.
- پیوندی به محتوای مرتبط، مانند اسناد، باز کنید.
- رد یا به تعویق انداختن پیامهای مشابه از برنامه چت برای یک دوره زمانی خاص.
برای افزودن ویجتهای جانبی، شیء accessoryWidgets[]
را در پیام وارد کنید و یک یا چند AccessoryWidgets
را که میخواهید اضافه کنید، مشخص کنید. پیام باید برای همه افراد موجود در فضا قابل مشاهده باشد (شما نمی توانید ویجت های جانبی را به پیام های خصوصی اضافه کنید).
تصویر زیر یک برنامه چت را نشان می دهد که یک پیام متنی را با ویجت های جانبی اضافه می کند تا کاربران بتوانند تجربه خود را با برنامه چت رتبه بندی کنند.
نمونه کد زیر JSON را برای این پیام نشان می دهد. وقتی کاربر یکی از دکمهها را کلیک میکند، این تعامل عملکرد مربوطه (مانند doUpvote
) را فعال میکند که رتبهبندی را پردازش میکند.
"text": "Rate your experience with this Chat app.",
"accessoryWidgets": [
{
"buttonList": {
"buttons": [
{
"icon": {
"material_icon": {
"name": "thumb_up"
}
},
"color": {
"red": 0,
"blue": 255,
"green": 0
},
"onClick": {
"action": {
"function": "doUpvote",
}
}
},
{
"icon": {
"material_icon": {
"name": "thumb_down"
}
},
"color": {
"red": 0,
"blue": 255,
"green": 0
},
"onClick": {
"action": {
"function": "doDownvote",
}
}
}
]
}
}
]
به صورت خصوصی پیام بفرستید
برنامه های چت می توانند پیام های متنی و کارتی را به صورت خصوصی ارسال کنند تا پیام فقط برای یک کاربر در فضا قابل مشاهده باشد. برای ارسال یک پیام به صورت خصوصی، فیلد privateMessageViewer
را در پیام مشخص کنید. فقط برنامه های چت می توانند پیام خصوصی ارسال کنند. برای ارسال پیام خصوصی به صورت ناهمزمان، باید از احراز هویت برنامه استفاده کنید.
برای جزئیات، به ارسال پیام خصوصی به کاربران گپ Google مراجعه کنید.
عیب یابی
وقتی یک برنامه یا کارت Google Chat خطایی را برمیگرداند، رابط Chat پیامی را نشان میدهد که میگوید «مشکلی پیش آمده است». یا "نمی توان به درخواست شما رسیدگی کرد." گاهی اوقات Chat UI هیچ پیام خطایی را نمایش نمی دهد، اما برنامه یا کارت Chat نتیجه غیرمنتظره ای ایجاد می کند. برای مثال، ممکن است پیام کارت ظاهر نشود.
اگرچه ممکن است پیام خطا در رابط کاربری گپ نمایش داده نشود، پیامهای خطای توصیفی و دادههای گزارش در دسترس هستند تا به شما کمک کنند هنگام فعال بودن ثبت خطا برای برنامههای گپ، خطاها را برطرف کنید. برای راهنمایی برای مشاهده، اشکالزدایی و رفع خطاها، به عیبیابی و رفع خطاهای Google Chat مراجعه کنید.
مطالب مرتبط
- یک پیام را قالب بندی کنید .
- دریافت جزئیات در مورد یک پیام
- لیست پیام ها در یک فاصله
- یک پیام را به روز کنید .
- یک پیام را حذف کنید .
- شناسایی کاربران در پیامهای گپ Google .
- با وب هوک های ورودی به چت Google پیام ارسال کنید .