Mesaj gönder

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ğında create 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.

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

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.

Apps Komut Dosyası

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:

Örnek ilk katılım mesajı.

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ıyla chat.messages.create yetkilendirme kapsamını belirtin.
  • Message kaynağında create 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

  1. Çalışma dizininizde chat_create_text_message_app.py adında bir dosya oluşturun.
  2. 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)
    
  3. Kodda, SPACE değerini Chat API'deki spaces.list() yönteminden veya alanın URL'sinden alabileceğiniz bir alan adıyla değiştirin.

  4. Ç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

  1. Çalışma dizininizde chat_create_text_message_user.py adında bir dosya oluşturun.
  2. 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 membership.
        print(result)
    
    if __name__ == '__main__':
        main()
    
  3. Kodda, SPACE değerini Chat API'deki spaces.list() yönteminden veya alanın URL'sinden alabileceğiniz bir alan adıyla değiştirin.

  4. Ç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.


Kart Oluşturucu ile kartları tasarlayın ve önizleyin.

Card Builder'ı açın

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:

Bir Chat uygulaması, gönderenin görünen adını ve avatar resmini içeren bir kartla yanıt veriyor.

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

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 Komut Dosyası

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],
      }
    }],
  };
}

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ğında create yöntemini çağırın.

Aşağıda, bir kart mesajı örneği verilmiştir:

Chat API ile gönderilen bir kart mesajı.

Uygulama kimlik doğrulamasıyla kart mesajı göndermek için aşağıdaki adımları uygulayın:

Python

  1. Çalışma dizininizde chat_create_card_message.py adında bir dosya oluşturun.
  2. 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)
    
  3. Kodda, SPACE değerini Chat API'deki spaces.list yönteminden veya alanın URL'sinden alabileceğiniz bir alan adıyla değiştirin.

  4. Ç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.

threadKey alanı nameOfThread olarak tanımlanmış bir ileti dizisini şu şekilde başlatabilir veya yanıtlayabilirsiniz:

Python

  1. Çalışma dizininizde chat_create_message_thread.py adında bir dosya oluşturun.
  2. 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)
    
  3. Kodda, SPACE değerini Chat API'deki spaces.list yönteminden veya alanın URL'sinden alabileceğiniz bir alan adıyla değiştirin.

  4. Ç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, ancak custom-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

  1. Çalışma dizininizde chat_create_named_message.py adında bir dosya oluşturun.
  2. 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)
    
  3. Kodda aşağıdakileri değiştirin:

    • SPACE: Mesajı yayınlamak istediğiniz alanın kimliği. Bu kimliği, Chat API'deki spaces.list yönteminden veya bir alanın URL'sinden edinebilirsiniz.
    • NAME: İletinin özel adı.
  4. Ç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.

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 sorun oluştu." veya "İsteğiniz işleme alınamıyor" mesajı gösterilir. 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 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 başlıklı makaleyi inceleyin.