Mesaj gönder

Bu rehberde, Google Chat uygulamalarının mesaj gönderebileceği farklı yöntemler açıklanmaktadır:

  • Bir kullanıcı etkileşimine yanıt vererek kısa mesajları 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 adlandırma

Message kaynağı, Google Chat'te bir metin veya kart mesajını temsil eder. İlgili yöntemleri çağırarak Google Chat API'de mesaj create, get, update veya delete gönderebilirsiniz. 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ı, kısa mesajları veya kart mesajları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

  • 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-httplib2 google-auth-oauthlib oauth2client

  • Yayınlanmış bir Chat uygulaması. Chat uygulaması oluşturmak ve yayınlamak için Google Chat uygulaması oluşturma başlıklı makaleyi inceleyin.

  • Chat uygulamasının eşzamansız mesajlar göndermesi için yetkilendirme yapılandırıldı. Mesajları 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, aşağıdaki iki şekilde kısa mesajların nasıl gönderileceği açıklanmaktadır:

  • Kullanıcı etkileşimine yanıt vererek gerçek zamanlı olarak 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 bir kısa mesaj oluşturur ve gönderir. Kullanıcıların ilk katılım sürecini gerçekleştirmeyle ilgili en iyi uygulamalar hakkında bilgi edinmek için Kullanıcıların ve alanların faydalı ilk katılımla 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 bir 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ı.

Zaman uyumsuz şekilde 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ı ile 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önderme

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 adlı bir dosya oluşturun.

  2. chat_create_text_message_app.py içine şu kodu ekleyin:

    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. Koddaki SPACE kısmını, 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 derleyin ve ç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ı bir kısa mesaj gönder

Kullanıcı 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_user.py adlı 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. Koddaki SPACE kısmını, 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 derleyin ve ç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 şekilde nasıl gönderileceği açıklanmaktadır:

  • Kullanıcı etkileşimine yanıt vererek gerçek zamanlı olarak bir 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:

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

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 mesajlarını eşzamansız olarak gönderme

Kart mesajı göndermek için isteğinizde aşağıdakileri iletin:

  • Uygulama kimlik doğrulaması ile chat.bot yetkilendirme kapsamını belirtin. Kullanıcı kimlik doğrulamalı 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 nasıl kart mesajı göndereceğiniz aşağıda açıklanmıştır:

Python

  1. Çalışma dizininizde chat_create_card_message.py adlı bir dosya oluşturun.

  2. chat_create_card_message.py içine şu kodu ekleyin:

    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. Koddaki SPACE kısmını, 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 derleyin ve çalıştırın:

    python3 chat_create_card_message.py

Bir mesaj dizisi başlatın veya bir mesaj dizisini yanıtlayın

Bir mesaj dizisi başlatmak için bir 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, ileti dizisinin adını özelleştirmek için thread.threadKey alanını belirtin.

Bir mesaj dizisini yanıtlamak 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 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 mesaj dizisini nasıl başlatacağınız veya yanıtlayacağınız aşağıda açıklanmıştır:

Python

  1. Çalışma dizininizde chat_create_message_thread.py adlı bir dosya oluşturun.

  2. chat_create_message_thread.py içine şu kodu ekleyin:

    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. Koddaki SPACE kısmını, 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 derleyin ve ç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.

Mesaj gönderme ve adlandırma

Bu bölümde, özel adla nasıl ileti gönderebileceğiniz açıklanmaktadır. Mesaj adlarını mesajları almak, güncellemek veya silmek için kullanırsınız. Özel bir ad atamak, Chat uygulamasının mesaj gönderilirken döndürülen yanıt gövdesinden name mesajını kaydetmeden mesajı geri çağırmasına da olanak tanır.

Özel bir ad atamak, oluşturulan name alanının (mesajın kaynak adının) yerini almaz. Bunun yerine, özel adı clientAssignedMessageId alanı olarak ayarlar. Bu alana, mesajı güncelleme veya silme gibi sonraki işlemleri işlerken başvurabilirsiniz.

Özel adlar aşağıdaki koşullara sahiptir:

  • client- ile başlayın. Örneğin, client-custom-name geçerli bir özel addır, ancak custom-name geçerli bir özel ad değildir.
  • Yalnızca küçük harf, rakam ve kısa çizgi içermelidir.
  • En fazla 63 karakter uzunluğunda olmalıdır.
  • Mesaj gönderirken kullanılmış bir özel ad belirtmek hata döndürür, ancak update ve delete gibi diğer yöntemler beklendiği gibi çalışır.

Mesaj göndermek ve adlandırmak için:

Python

  1. Çalışma dizininizde chat_create_named_message.py adlı bir dosya oluşturun.

  2. chat_create_named_message.py içine şu kodu ekleyin:

    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. Koddaki SPACE kısmını, 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 derleyin ve çalıştırın:

    python3 chat_create_named_message.py

Chat API, gönderilen mesajla ilgili ayrıntıları içeren bir Message örneği döndürür.

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, bir 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ı olmak üzere açıklayıcı hata mesajları ve günlük verileri kullanılabilir. Hataları görüntüleme, hata ayıklama ve düzeltme konusunda yardım almak için Google Chat hatalarını giderme ve düzeltme başlıklı makaleyi inceleyin.