Bu rehberde, Google Chat uygulamalarının mesaj gönderebileceği farklı yollar açıklanmaktadır:
- Kullanıcı etkileşimine yanıt vererek metin ve kart mesajlarını gerçek zamanlı olarak gönderin.
Message
kaynağındacreate
yöntemini çağırarak kısa mesajları ve kart mesajlarını eşzamansız olarak gönderin.- Bir mesaj dizisi başlatın veya bir mesaj dizisini yanıtlayın.
- Mesaj gönderme ve mesaj gönderme.
Message
kaynağı, Google Chat'te bir metin veya kart mesajı temsil eder. İlgili yöntemleri çağırarak Google Chat API'de bir mesajı create
, get
, update
veya delete
yapabilirsiniz. Kısa mesajlar ve kart mesajlar hakkında daha fazla bilgi edinmek için Google Chat mesajlarına genel bakış başlıklı makaleyi inceleyin.
Maksimum ileti boyutu (metinler veya kartlar dahil) 32.000 bayttır. Bir mesaj bu boyutu aşarsa Chat uygulamanız bunun yerine birden fazla mesaj gönderebilir.
Google Chat uygulamaları, bir kısa mesajı veya kart mesajını eşzamansız olarak göndermek için Google Chat API'nin Message
kaynağında create
yöntemini çağırmak yerine kullanıcı etkileşimlerine gerçek zamanlı yanıt vermek için mesajlar da oluşturabilir. Kullanıcı etkileşimlerine verilen yanıtlar kimlik doğrulama gerektirmez ve etkileşimli iletişim kutuları ve bağlantı önizlemeleri gibi diğer mesaj türlerini destekler. Ayrıntılı bilgi için Google Chat uygulamanızla etkileşimleri alma ve yanıtlama başlıklı makaleyi inceleyin.
Ön koşullar
Node.js
- Google Chat'e erişimi olan bir Google Workspace hesabı.
- Google Chat API'nin etkin ve yapılandırılmış olduğu bir Google Cloud projesi. Adımlar için Google Chat uygulaması oluşturma başlıklı makaleye göz atın.
- Chat uygulamasının eşzamansız mesajlar göndermesi için yapılandırılmış yetkilendirme. İletileri gerçek zamanlı olarak göndermek için yetkilendirme yapılandırması gerekmez.
- Kısa mesaj göndermek aşağıdaki yetkilendirme yöntemlerinin her ikisini de destekler:
chat.messages.create
veyachat.messages
yetkilendirme kapsamıyla kullanıcı kimlik doğrulaması.chat.bot
yetkilendirme kapsamıyla uygulama kimlik doğrulaması.
- Kart mesajı göndermek için
chat.bot
yetkilendirme kapsamıyla uygulama kimlik doğrulaması gerekir.
- Kısa mesaj göndermek aşağıdaki yetkilendirme yöntemlerinin her ikisini de destekler:
Python
- Google Chat'e erişimi olan bir Google Workspace hesabı.
- Python 3.6 veya sonraki sürümler
- pip paket yönetimi aracı
Python için en yeni Google istemci kitaplıkları. Bunları yüklemek veya güncellemek için komut satırı arayüzünüzde aşağıdaki komutu çalıştırın:
pip3 install --upgrade google-api-python-client google-auth
- Google Chat API'nin etkin ve yapılandırılmış olduğu bir Google Cloud projesi. Adımlar için Google Chat uygulaması oluşturma başlıklı makaleye göz atın.
Chat uygulamasının eşzamansız mesajlar göndermesi için yapılandırılmış yetkilendirme. İletileri gerçek zamanlı olarak göndermek için yetkilendirme yapılandırması gerekmez.
- Kısa mesaj göndermek aşağıdaki yetkilendirme yöntemlerinin her ikisini de destekler:
chat.messages.create
veyachat.messages
yetkilendirme kapsamıyla kullanıcı kimlik doğrulaması.chat.bot
yetkilendirme kapsamıyla uygulama kimlik doğrulaması.
- Kart mesajı gönderebilmek için
chat.bot
yetkilendirme kapsamıyla uygulama kimlik doğrulaması gerekir.
- Kısa mesaj göndermek aşağıdaki yetkilendirme yöntemlerinin her ikisini de destekler:
Apps Komut Dosyası
- Google Chat'e erişimi olan bir Google Workspace hesabı.
- Yayınlanmış bir Chat uygulamasıdır. Chat uygulaması oluşturmak için bu quickstart takip edin.
- Chat uygulamasının eşzamansız mesajlar göndermesi için yapılandırılmış yetkilendirme. İletileri gerçek zamanlı olarak göndermek için yetkilendirme yapılandırması gerekmez.
- Kısa mesaj göndermek aşağıdaki yetkilendirme yöntemlerinin her ikisini de destekler:
chat.messages.create
veyachat.messages
yetkilendirme kapsamıyla kullanıcı kimlik doğrulaması.chat.bot
yetkilendirme kapsamıyla uygulama kimlik doğrulaması.
- Kart mesajı gönderebilmek için
chat.bot
yetkilendirme kapsamıyla uygulama kimlik doğrulaması gerekir.
- Kısa mesaj göndermek aşağıdaki yetkilendirme yöntemlerinin her ikisini de destekler:
Kısa mesaj gönderme
Bu bölümde, kısa mesajların aşağıdaki iki yöntemle nasıl gönderileceği açıklanmaktadır:
- Bir kullanıcı etkileşimine yanıt vererek gerçek zamanlı bir kısa mesaj gönderin.
- Google Chat API'yi eşzamansız olarak çağırarak kısa mesaj gönderin.
Gerçek zamanlı olarak kısa mesaj gönderin
Bu örnekte, Chat uygulamanız bir alana her eklendiğinde kısa mesaj oluşturup gönderir. Kullanıcıların ilk katılımıyla ilgili en iyi uygulamalar hakkında bilgi edinmek için Kullanıcıların ve alanların faydalı ilk katılım özellikleriyle başlamasını sağlama başlıklı makaleyi inceleyin.
Kullanıcı Chat uygulamanızı bir alana eklediğinde kısa mesaj göndermek için Chat uygulamanız ADDED_TO_SPACE
etkileşim etkinliğine yanıt verir. ADDED_TO_SPACE
etkileşim etkinliklerine kısa mesajla yanıt vermek için aşağıdaki kodu kullanın:
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`.'
});
}
};
Apps Komut Dosyası
/**
* 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`.'
}
}
Kod örneği şu kısa mesajı döndürür:
Eşzamansız olarak kısa mesaj gönderme
Aşağıdaki bölümde, uygulama kimlik doğrulaması ve kullanıcı kimlik doğrulamasıyla eşzamansız olarak kısa mesajın nasıl gönderileceği açıklanmaktadır.
Kısa mesaj göndermek için isteğinizde aşağıdakileri iletin:
- Uygulama kimlik doğrulamasıyla
chat.bot
yetkilendirme kapsamını belirtin. Kullanıcı kimlik doğrulamasıylachat.messages.create
yetkilendirme kapsamını belirtin. Message
kaynağındacreate
yöntemini çağırın.
Uygulama kimlik doğrulamasıyla kısa mesaj gönder
Uygulama kimlik doğrulaması ile nasıl kısa mesaj göndereceğiniz aşağıda açıklanmıştır:
Python
- Çalışma dizininizde
chat_create_text_message_app.py
adında bir dosya oluşturun. chat_create_text_message_app.py
içine şu kodu ekleyin: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)
Kodda,
SPACE
değerini Chat API'dekispaces.list()
yönteminden veya alanın URL'sinden alabileceğiniz bir alan adıyla değiştirin.Çalışma dizininizde örneği derleyip çalıştırın:
python3 chat_create_text_message_app.py
Chat API, gönderilen mesajla ilgili ayrıntıları içeren bir Message
örneği döndürür.
Kullanıcı kimlik doğrulamalı kısa mesaj gönderme
Kullanıcı kimlik doğrulaması ile kısa mesaj göndermek için yapmanız gerekenler aşağıda açıklanmıştır:
Python
- Çalışma dizininizde
chat_create_text_message_user.py
adında bir dosya oluşturun. chat_create_text_message_user.py
içine şu kodu ekleyin: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()
Kodda,
SPACE
değerini Chat API'dekispaces.list()
yönteminden veya alanın URL'sinden alabileceğiniz bir alan adıyla değiştirin.Çalışma dizininizde örneği derleyip çalıştırın:
python3 chat_create_text_message_user.py
Chat API, gönderilen mesajla ilgili ayrıntıları içeren bir Message
örneği döndürür.
Kart mesajları gönder
Bu bölümde, kart mesajlarının aşağıdaki iki yöntemle nasıl gönderileceği açıklanmıştır:
- Kullanıcı etkileşimine yanıt vererek gerçek zamanlı olarak kart mesajı gönderin.
- Google Chat API'yi eşzamansız olarak çağırarak kart mesajı gönderin.
Gerçek zamanlı olarak kart mesajı gönderin
Chat uygulamaları, kullanıcının Chat uygulamasına mesaj göndermesi veya Chat uygulamasını bir alana eklemesi gibi kullanıcı etkileşimlerine yanıt vermek için kart mesajları oluşturabilir. Kullanıcı etkileşimlerine yanıt verme hakkında daha fazla bilgi edinmek için Chat uygulaması etkileşim etkinliklerini alma ve yanıtlama başlıklı makaleyi inceleyin.
Bu örnekte, kullanıcı bir Chat uygulamasına mesaj gönderir ve Chat uygulaması da kullanıcının adını ve avatar resmini gösteren bir kart mesajı göndererek yanıt verir:
Node.js
Python
Apps Komut Dosyası
Bu örnekte, kart JSON hatası döndürerek bir kart mesajı gönderilmektedir. Apps Komut Dosyası kart hizmetini de kullanabilirsiniz.
Kart mesajını eşzamansız olarak gönder
Kart mesajı göndermek için isteğinizde aşağıdakileri belirtin:
- Uygulama kimlik doğrulamasıyla
chat.bot
yetkilendirme kapsamını belirtin. Kullanıcı kimlik doğrulamasıyla kart mesajı gönderemezsiniz. Message
kaynağındacreate
yöntemini çağırın.
Aşağıda, bir kart mesajı örneği verilmiştir:
Uygulama kimlik doğrulamasıyla kart mesajı göndermek için aşağıdaki adımları uygulayın:
Python
- Çalışma dizininizde
chat_create_card_message.py
adında bir dosya oluşturun. chat_create_card_message.py
içine şu kodu ekleyin: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)
Kodda,
SPACE
değerini Chat API'dekispaces.list
yönteminden veya alanın URL'sinden alabileceğiniz bir alan adıyla değiştirin.Çalışma dizininizde örneği derleyip çalıştırın:
python3 chat_create_card_message.py
Bir mesaj dizisi başlatma veya bir mesaj dizisini yanıtlama
Bir mesaj dizisi başlatmak için mesaj gönderin ve thread.name
alanını boş bırakın. Google Chat, mesaj dizisini oluştururken bu alanı doldurur. İsteğe bağlı olarak, iş parçacığının adını özelleştirmek için thread.threadKey
alanını belirtin.
Bir mesaj dizisine yanıt vermek için ileti dizisinin threadKey
veya name
alanını belirten bir mesaj gönderin. İleti dizisi bir kişi veya başka bir Chat uygulaması tarafından oluşturulduysa thread.name
alanını kullanmanız gerekir.
Eşleşen bir ileti dizisi bulunmazsa bir mesajın yeni bir ileti dizisi başlatması veya yayınlanmaması gerektiğini messageReplyOption
alanını ayarlayarak belirtebilirsiniz.
messageReplyOption
ayarlandıysa thread.name
veya thread.threadKey
ayarlarını da yapmanız gerekir.
threadKey
alanı nameOfThread
olarak tanımlanmış bir ileti dizisini şu şekilde başlatabilir veya yanıtlayabilirsiniz:
Python
- Çalışma dizininizde
chat_create_message_thread.py
adında bir dosya oluşturun. chat_create_message_thread.py
içine şu kodu ekleyin: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)
Kodda,
SPACE
değerini Chat API'dekispaces.list
yönteminden veya alanın URL'sinden alabileceğiniz bir alan adıyla değiştirin.Çalışma dizininizde örneği derleyip çalıştırın:
python3 chat_create_message_thread.py
Chat API, gönderilen mesajla ilgili ayrıntıları içeren bir Message
örneği döndürür.
Mesaja bir ad verme
Bu bölümde, mesaj için özel bir kimlik ayarlayarak bir mesajı nasıl adlandıracağınız açıklanmaktadır. Mesajları almak, güncellemek veya silmek için özel kimlikleri kullanabilirsiniz. Özel kimlikler, mesajın kaynak adındaki (name
alanında temsil edilir) sistem tarafından atanan kimliği depolamanıza gerek kalmadan mesaj belirtmenizi sağlar. Kaynak adı, mesajı oluşturduğunuzda yanıt gövdesinde oluşturulur.
Örneğin, get()
yöntemini kullanarak bir mesaj almak için hangi mesajın alınacağını belirtmek üzere kaynak adını kullanırsınız. Kaynak adı spaces/{space}/messages/{message}
olarak biçimlendirilir. Burada {message}
, sistem tarafından atanan kimliği temsil eder. Mesajı adlandırdıysanız {message}
değerini özel kimlikle değiştirebilirsiniz.
Bir mesajı adlandırmak için mesajı oluştururken messageId
alanında özel bir kimlik belirtin. messageId
alanı, Message
kaynağının clientAssignedMessageId
alanının değerini ayarlar.
Mesajları yalnızca mesajı oluştururken adlandırabilirsiniz. Mevcut mesajlar için özel bir kimliği adlandıramaz veya değiştiremezsiniz. Özel kimlik aşağıdaki gereksinimleri karşılamalıdır:
- Şununla başlar:
client-
. Örneğin,client-custom-name
geçerli bir özel kimliktir, ancakcustom-name
geçerli bir özel kimlik değildir. - En fazla 63 karakter ve yalnızca küçük harf, sayı ve kısa çizgi içerebilir.
- Bir alan içinde benzersizdir. Bir Chat uygulaması farklı mesajlar için aynı özel kimliği kullanamaz.
Özel kimlikle ileti göndermek için aşağıdaki adımları uygulayın:
Python
- Çalışma dizininizde
chat_create_named_message.py
adında bir dosya oluşturun. chat_create_named_message.py
içine şu kodu ekleyin: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)
Kodda aşağıdakileri değiştirin:
SPACE
: Mesajı yayınlamak istediğiniz alanın kimliği. Bu kimliği, Chat API'dekispaces.list
yönteminden veya bir alanın URL'sinden edinebilirsiniz.NAME
: İletinin özel adı.
Çalışma dizininizde örneği derleyip çalıştırın:
python3 chat_create_named_message.py
Chat API, Message
öğesinin bir örneğini döndürür.
İletinin alt kısmına etkileşimli widget'lar ekleme
İsteğe bağlı olarak, aksesuar widget'larını kullanarak ileti ekleyebilirsiniz. Aksesuar widget'ları, iletideki herhangi bir metinden veya karttan sonra görünür. Bu widget'ları, kullanıcılardan iletinizle etkileşimde bulunmalarını istemek için kullanabilirsiniz. Bunlardan bazıları:
- Bir mesajın doğruluğunu veya memnuniyetini derecelendirin.
- Mesajla veya Chat uygulamasıyla ilgili sorun bildirin.
- Dokümanlar gibi ilgili içeriğin bağlantısını açın.
- Chat uygulamasından benzer mesajları belirli bir süre için kapatabilir veya erteleyebilirsiniz.
Aksesuar widget'ları eklemek için iletiye accessoryWidgets[]
nesnesini ekleyin ve dahil etmek istediğiniz en az bir AccessoryWidgets
öğesini belirtin. Mesaj, alandaki herkese görünür olmalıdır (Özel mesajlara aksesuar widget'ları ekleyemezsiniz).
Aşağıdaki resimde, kullanıcıların Chat uygulamasındaki deneyimlerini değerlendirebilmeleri için aksesuar widget'ları içeren bir kısa mesaja sahip bir Chat uygulaması gösterilmektedir.
Aşağıdaki kod örneğinde, bu iletinin JSON'u gösterilmektedir. Kullanıcı düğmelerden birini tıkladığında, etkileşim ilgili derecelendirmeyi işleyen ilgili işlevi (doUpvote
gibi) tetikler.
"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",
}
}
}
]
}
}
]
Mesajları gizli olarak gönderme
Chat uygulamaları, kısa mesajları ve kart mesajlarını gizli olarak gönderebilir. Böylece mesaj, alandaki yalnızca bir kullanıcı tarafından görülebilir. İletiyi gizli olarak göndermek için iletide privateMessageViewer
alanını belirtirsiniz. Yalnızca Chat uygulamaları özel mesaj gönderebilir. Bir özel mesajı eşzamansız olarak göndermek için uygulama kimlik doğrulamasını kullanmanız gerekir.
Ayrıntılı bilgi için Google Chat kullanıcılarına özel mesaj gönderme başlıklı makaleyi inceleyin.
Sorun giderme
Bir Google Chat uygulaması veya kartı hata döndürdüğünde Chat arayüzünde "Bir hata oluştu" mesajı gösterilir. veya "İsteğiniz işlenemiyor". Bazen Chat kullanıcı arayüzünde hata mesajı gösterilmez ancak Chat uygulaması veya kartı beklenmedik bir sonuç üretir. Örneğin, kart mesajı görünmeyebilir.
Chat kullanıcı arayüzünde bir hata mesajı gösterilmese de, Chat uygulamaları için hata günlük kaydı etkinken hataları düzeltmenize yardımcı olacak açıklayıcı hata mesajları ve günlük verileri mevcuttur. Hataları görüntüleme, hata ayıklama ve düzeltme konusunda yardım için Google Chat hatalarını giderme ve düzeltme bölümünü inceleyin.
İlgili konular
- Mesajı biçimlendirme.
- Bir mesajla ilgili ayrıntıları alma.
- Alandaki mesajları listeleyin.
- Mesajları güncelleme.
- Mesajı silebilirsiniz.
- Google Chat mesajlarında kullanıcıları belirleyin.
- Gelen webhook'ları kullanarak Google Chat'e mesaj gönderin.