Kart mesajı gönder

Chat uygulamaları, kısa mesajlara ek olarak alanlarda ve kullanıcılara kart mesajları gönderebilir. Kartlar tanımlı bir düzeni, düğmeler gibi etkileşimli kullanıcı arayüzü öğelerini ve resimler gibi rich media'yı destekler.

Kart mesajlarını kullanarak:

• Ayrıntılı bilgi verin
• Kullanıcılardan bilgi toplama
• Kullanıcıları bir sonraki adıma geçmeye yönlendirin

Bu kılavuzda, kart mesajlarının eşzamanlı olarak (bir Chat etkinliğine gerçek zamanlı yanıt verme (ör. kullanıcıdan mesaj alma veya alana eklenme)) ve eşzamansız olarak (Chat REST API kullanılarak istem olmadan uygulamadan alana veya kullanıcıya mesaj gönderilmesi) nasıl gönderileceği açıklanmaktadır.

Ön koşullar

Bu kılavuzdaki kart mesajlarını göndermek için aşağıdakilere ihtiyacınız vardır:

Node.js

• Google Chat'e erişimi olan bir Google Workspace hesabı.
• Bir Chat uygulaması. Chat uygulaması oluşturmak için bu hızlı başlangıç kılavuzunu takip edin.

Not: Bu kılavuzdaki Node.js kod örnekleri Google Cloud Functions işlevi olarak çalışacak şekilde yazılmıştır.

Python

• Google Chat'e erişimi olan bir Google Workspace hesabı.
• Bir Chat uygulaması. Chat uygulaması oluşturmak için bu hızlı başlangıç kılavuzunu takip edin.

Not: Bu kılavuzdaki Python kod örnekleri, Python 3.9 kullanılarak Google Cloud Functions işlevi olarak çalışacak şekilde yazılmıştır.

Apps Komut Dosyası

• Google Chat'e erişimi olan bir Google Workspace hesabı.
• Bir Chat uygulaması. Chat uygulaması oluşturmak için bu hızlı başlangıç kılavuzunu takip edin.

Bir kart mesajının anatomisi

İster kart ister mesaj olsun, her kart Chat API'deki spaces.messages kaynağında bir JSON nesnesidir.

Kart JSON nesnesi aşağıdakilerden oluşur:

1. Bir veya daha fazla CardWithId nesnesi içeren cardsV2[] adlı bir dizi.
2. Kartı tanımlamak için kullanılan ve belirli bir mesaj kapsamındaki kapsam cardId. (Farklı mesajlardaki kartlar aynı kimliğe sahip olabilir.)

3. Aşağıdakilerden oluşan bir card nesnesi:

   • Başlık, alt başlık ve avatar stili resim gibi öğeleri belirten bir header nesnesi.
   • Her biri en az bir widget içeren bir veya daha fazla section nesnesi.

   • Bir veya daha fazla widget nesnesi. Her widget; metin, resim, düğme ve diğer nesne türlerini temsil edebilen birleşik bir nesnedir.

     Kart widget'larında ve iletişim kutularında aşağıdaki widget'lar desteklenir:

     • TextParagraph: İsteğe bağlı basit HTML biçimlendirmesiyle bir metin paragrafı görüntüler.
     • Image: HTTPS URL'sinde barındırılan tıklanabilir veya statik .PNG veya .JPG resmi gösterir.
     • DecoratedText: Simgeler ve düğmeler gibi isteğe bağlı düzen ve işlev özelliklerine sahip metinleri görüntüler.
     • ButtonList: Bir dizi düğmeyi görüntüler.

     Aşağıdaki widget'lar iletişim kutularında desteklenir (yakında kart mesajları için destek sunulacaktır):

     • TextInput: Kullanıcıların metin girebileceği alan.

     • SelectionInput: Onay kutuları, radyo düğmeleri, anahtarlar veya açılır menü gibi bir dizi seçilebilir öğe sağlar.

     • Divider: Yığılmış widget'lar arasında, kart genişliğini yatay ayırıcı olarak gören yatay bir çizgi görüntüler.

     • Grid: Bir öğe grubunu basit bir ızgaraya yerleştirir.

     Aşağıdaki widget yakında desteklenecektir:

     • DateTimePicker: Kullanıcıların bir tarih, saat veya her ikisini birden belirtmesine olanak tanır.

Örneğin, aşağıdaki kart mesajında header, section ve widget nesnelerini inceleyin:

Aşağıdaki kod, kart mesajının JSON'unu temsil eder:

JSON

{
  "cardsV2": [
    {
      "cardId": "unique-card-id",
      "card": {
        "header": {
          "title": "Sasha",
          "subtitle": "Software Engineer",
          "imageUrl":
          "https://developers.google.com/chat/images/quickstart-app-avatar.png",
          "imageType": "CIRCLE",
          "imageAltText": "Avatar for Sasha",
        },
        "sections": [
          {
            "header": "Contact Info",
            "collapsible": true,
            "uncollapsibleWidgetsCount": 1,
            "widgets": [
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "EMAIL",
                  },
                  "text": "[e-mail]",
                }
              },
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "PERSON",
                  },
                  "text": "<font color=\"#80e27e\">Online</font>",
                },
              },
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "PHONE",
                  },
                  "text": "[phone]",
                }
              },
              {
                "buttonList": {
                  "buttons": [
                    {
                      "text": "Share",
                      "onClick": {
                        "openLink": {
                          "url": "https://example.com/share",
                        }
                      }
                    },
                    {
                      "text": "Edit",
                      "onClick": {
                        "action": {
                          "function": "goToView",
                          "parameters": [
                            {
                              "key": "viewType",
                              "value": "EDIT",
                            }
                          ],
                        }
                      }
                    },
                  ],
                }
              },
            ],
          },
        ],
      },
    }
  ],
}

Eşzamanlı kart mesajı gönderme

Bu örnekte, kullanıcı Chat uygulamasına Google Chat'te bir mesaj gönderir. Uygulama da gönderenin adını ve avatar resmini gösteren basit bir eşzamanlı kart mesajı göndererek yanıt verir:

Aşağıdaki kod örneklerinde Node.js ve Python uygulamaları Google Cloud Functions'da barındırılır. Apps Komut Dosyası örneği Google Apps Komut Dosyası'nda barındırılır.

Chat uygulaması oluşturma ve dağıtmayla ilgili tüm talimatlar için Chat uygulaması oluşturma başlıklı makaleyi inceleyin.

Node.js

düğüm/avatar-bot/index.js

GitHub'da göster

/**
 * Google Cloud Function that responds to messages sent from a
 * Hangouts Chat room.
 *
 * @param {Object} req Request sent from Hangouts Chat room
 * @param {Object} res Response to send back
 */
exports.helloHangoutsChat = function helloHangoutsChat(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send('Hello! This function is meant to be used in a Hangouts 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 {
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Python

python/avatar-bot/main.py

GitHub'da göster

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):
    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 = {
        "cardsV2": [
            {
                "cardId": "avatarCard",
                "card": {
                    "name": "Avatar Card",
                    "header": header,
                    "sections": [avatar_section],
                },
            }
        ]
    }

    return cards

Apps Komut Dosyası

apps-script/avatar-bot/hello-chat.gs

GitHub'da göster

/**
 * 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 {
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Chat API ile eşzamansız bir kart mesajı gönderin

Bu örnek, eşzamansız olarak Chat API ile mesaj oluşturur ve bu mesajı, Chat uygulamasının eklendiği bir alana gönderir (ör. aşağıda gösterilen):

Şekil 1: Chat REST API ile oluşturulan bir kart mesajı.

Python

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

2. chat_create_card_message.py uygulamasına aşağıdaki 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(
       'service_account.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 Chat REST 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 yerine Chat API'sindeki spaces.list() yöntemini veya bir alanın URL'sini kullanarak bir alan adı girin.

4. Çalışma dizininizde örneği oluşturun ve çalıştırın:

   python3 chat_create_card_message.py
   

Chat REST API'de mesajlarla çalışma hakkında daha fazla bilgi edinmek için Mesaj oluşturma, okuma, güncelleme, silme başlıklı makaleyi inceleyin.

İletişim kutusu açma

İletişim kutuları, Chat uygulamalarının kullanıcılarla etkileşimde bulunmak için açtığı pencereli, kart tabanlı arayüzlerdir. Kullanıcıların çok adımlı işlemleri tamamlamasına yardımcı olmak için uygulamalar sıralı iletişim kutuları açabilir. Uygulamalar, bir kart mesajına yapılan düğmeye veya bir eğiklik komutuna yanıt olarak iletişim kutularını açabilir.

İletişim kutuları, aşağıdakiler de dahil olmak üzere birçok kullanıcı etkileşimi türü için yararlıdır:

• Kullanıcılardan bilgi toplama
• Web hizmetleriyle kullanıcı kimliklerini doğrulama
• Chat uygulaması ayarlarını yapılandırma

Bu örnekte Chat uygulaması, kullanıcının adres defteri için yeni bir kişi oluşturmasına yardımcı olmak amacıyla bir iletişim kutusu açmaktadır:

İletişim kutularını uygulamak için İletişim kutularını açma konusuna bakın.

Kart biçimlendirmesi

Kart metni biçimlendirmesi

Kartların içindeki çoğu metin alanı, HTML etiketlerinin küçük bir alt kümesi üzerinden temel metin biçimlendirmesini destekler. Desteklenen etiketler ve amaçları aşağıdaki tabloda gösterilir:

Kalın	<b>		İtalik	<i>
Altını çiz	<>		Üstü Çizili	<ihtar>
Yazı Tipi Rengi	<font color="">		Köprü	<a href="">
Satır Sonu	<br>

Temel mesajın metin gövdesi, insan kullanıcılar için optimize edilmiş farklı bir işaretleme söz dizimi kullanılarak ayrıştırılır. Ayrıntılar için Kısa mesaj gönderme başlıklı makaleyi inceleyin.

Yerleşik simgeler

DecoratedText ve ButtonList widget'ları, Google Chat'te bulunan yerleşik simgelerden birini belirtmek için kullanılan icon öğesini destekler:

{ . . . "knownIcon": "EĞİTİM", . . . }

Aşağıdaki tabloda, kart mesajlarıyla kullanılabilen yerleşik simgeler listelenmiştir:

	UÇAK		YER İŞARETİ
	OTOBÜS		ARA
	SAAT		ONAY_NUMBER_SİMGESİ
	AÇIKLAMA		LİSANS
	E-POSTA GÖNDERİN		ETKİNLİK_SEAT
	UÇUŞ_SAYISI		UÇ_KATILIMCI
	OTEL		OTEL_ODA_TÜRÜ
	DAVET ET		MAP_PIN
	ÜYELİK		ÇOKTAN_KİŞİLER
	KİŞİ		TELEFON
	RESTAURANT_SİMGE		ALIŞVERİŞ_KART
	Yıldız		MAĞAZA
	BİLET		TREN
	VİDEO_KAMERA		VİDEO_OYNATMA

Özel simgeler

DecoratedText ve ButtonList widget'ları, yukarıda listelenen yerleşik simgeleri kullanmanıza veya kendi özel simgelerinizi tanımlamanıza olanak tanır. Özel bir simge belirtmek için burada gösterildiği gibi iconUrl öğesini kullanın:

{ . . . "iconUrl": "https://developers.google.com/chat/images/quickstart-app-avatar.png". . . }

Sınırlar ve dikkat edilmesi gereken noktalar

Kart mesajı göndermeye hazırlanırken bu sınırları ve dikkat edilmesi gereken noktaları göz önünde bulundurun.

• Aşağıdaki widget'lar kart mesajları tarafından desteklenmez ancak yakında desteklenecektir:

  • Kullanıcıların metin girebileceği bir alan olan TextInput.
  • Onay kutuları, radyo düğmeleri, anahtarlar veya açılır menü gibi bir dizi seçilebilir öğe sağlayan SelectionInput.
  • DateTimePicker (kullanıcıların tarih, saat veya her ikisini birden belirtmesini sağlar).
  • Grid, bir öğe grubunu basit bir ızgarada yerleştirir.