إرسال رسالة باستخدام بطاقة

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

بالإضافة إلى الرسائل النصية، يمكن لتطبيقات Chat إرسال رسائل البطاقات في مساحات العمل وإلى المستخدمين. وتدعم البطاقات التصميم المحدّد وعناصر واجهة المستخدم التفاعلية مثل الأزرار والوسائط المتعددة التفاعلية، مثل الصور.

يمكنك استخدام رسائل البطاقة لإجراء ما يلي:

  • تقديم معلومات مفصّلة
  • جمع المعلومات من المستخدمين
  • توجيه المستخدمين إلى اتخاذ الخطوة التالية

يصف هذا الدليل كيفية إرسال رسائل البطاقة بشكلٍ متزامن (ردّ في الوقت الفعلي على حدث Chat، مثل تلقّي رسالة من مستخدم أو إضافتها إلى مساحة) وبشكل غير متزامن (إرسال رسالة من التطبيق إلى مساحة أو مستخدم بدون طلب استخدام واجهة برمجة تطبيقات REST Chat).

المتطلبات الأساسية

لإرسال رسائل البطاقات في هذا الدليل، ستحتاج إلى ما يلي:

Node.js

لغة Python

برمجة تطبيقات

بنية رسالة البطاقة

تكون كل بطاقة، سواء كانت مربّع حوار أو رسالة، كائن JSON على مورد spaces.messages في واجهة برمجة تطبيقات Chat.

يتكون كائن JSON للبطاقة مما يلي:

  1. مصفوفة باسم cardsV2[] تحتوي على عنصر CardWithId واحد أو أكثر.
  2. تُستخدَم السمة cardId لتحديد البطاقة، وتحديد نطاقها ضمن رسالة معيّنة. (يمكن أن يكون للبطاقات في الرسائل المختلفة رقم التعريف نفسه.)
  3. عنصر card، ويتألف من ما يلي:

    • عنصر header يحدّد عناصر، مثل عنوان وعنوان فرعي وصورة ذات نمط رمزي.
    • عنصر أو أكثر من عناصر section يحتوي كل منها على أداة واحدة على الأقل.
    • عنصر widget واحد أو أكثر. كل أداة هي عبارة عن كائن مركّب يمكنه تمثيل النص والصور والأزرار وأنواع العناصر الأخرى.

      تتوفّر الأدوات التالية في رسائل البطاقات ومربعات الحوار:

      • TextParagraph: تعرض فقرة نصية بتنسيق HTML بسيط اختياري.
      • Image: تعرض صورة ثابتة أو قابلة للنقر .PNG أو .JPG تتم استضافتها على عنوان URL يستخدم HTTPS.
      • DecoratedText: تعرض نصًا مع ميزات تنسيق ووظائف اختيارية، مثل الرموز والأزرار.
      • ButtonList: تعرض مجموعة من الأزرار.

      تتوفّر الأدوات التالية في مربّعات الحوار (ستتوفّر قريبًا رسائل البطاقات):

      • TextInput: حقل يمكن للمستخدمين إدخال نص فيه.
      • SelectionInput: تقدم مجموعة من العناصر القابلة للاختيار، مثل قائمة بمربّعات الاختيار أو أزرار الاختيار أو مفاتيح التبديل أو القائمة المنسدلة.

      • Divider: تعرض خطًا أفقيًا يمتد لعرض البطاقة بين الأدوات المكدّسة، التي تعمل كفاصل مرئي.

      • Grid–يقدّم مجموعة من العناصر في شبكة بسيطة.

      وستتوفّر قريبًا إمكانية استخدام الأداة التالية:

      • DateTimePicker: تتيح للمستخدمين تحديد تاريخ أو وقت أو كليهما.

كمثال، عليك مراقبة العناصر header وsection وwidget في رسالة البطاقة التالية:

تطبيق Chat يجري استطلاع رأي في مساحة Chat باستخدام رسالة بطاقة

يمثل الرمز التالي رمز JSON لعنوان البطاقة:

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": "sasha@example.com",
                }
              },
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "PERSON",
                  },
                  "text": "<font color=\"#80e27e\">Online</font>",
                },
              },
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "PHONE",
                  },
                  "text": "+1 (555) 555-1234",
                }
              },
              {
                "buttonList": {
                  "buttons": [
                    {
                      "text": "Share",
                      "onClick": {
                        "openLink": {
                          "url": "https://example.com/share",
                        }
                      }
                    },
                    {
                      "text": "Edit",
                      "onClick": {
                        "action": {
                          "function": "goToView",
                          "parameters": [
                            {
                              "key": "viewType",
                              "value": "EDIT",
                            }
                          ],
                        }
                      }
                    },
                  ],
                }
              },
            ],
          },
        ],
      },
    }
  ],
}

إرسال رسالة متزامنة

في هذا المثال، يرسل أحد المستخدمين رسالة إلى تطبيق Chat في Google Chat ويستجيب التطبيق من خلال إرسال رسالة بطاقة متزامنة بسيطة تعرض اسم المُرسِل والصورة الرمزية:

تطبيق Chat يتفاعل مع بطاقة تتضمّن الاسم المعروض للمُرسِل وصورة رمزية

في نماذج الرموز التالية، تتم استضافة تطبيقَي Node.js وPython على Google Cloud Functions. تتم استضافة مثال "برمجة التطبيقات" في برمجة تطبيقات Google.

للحصول على التعليمات الكاملة التي توضّح كيفية إنشاء تطبيق Chat ونشره، يُرجى الاطِّلاع على إنشاء تطبيق Chat.

Node.js

/**
  * 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.
  */
exports.helloChat = function helloChat(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send('Hello! This function must be called from Google Chat.');
  }

  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': imageURL},
  };

  const avatarSection = {
    'widgets': [
      avatarWidget,
      avatarImageWidget,
    ],
  };

  return {
    'cards': [{
      'name': 'Avatar Card',
      'header': cardHeader,
      'sections': [avatarSection],
    }],
  };
}

لغة Python

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 = {'cards': [{'name': 'Avatar Card',
                      'header': header, 'sections': [avatar_section]}]}

  return cards  

برمجة تطبيقات

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

إرسال رسالة بطاقة غير متزامنة باستخدام واجهة برمجة التطبيقات Chat

ينشئ هذا المثال رسالة بشكل غير متزامن باستخدام Chat API ويرسلها إلى مساحة تتم إضافة تطبيق Chat إليها، مثل المساحة التي تظهر أدناه:

رسالة تم إنشاؤها باستخدام واجهة برمجة تطبيقات Chat REST
الشكل 1: رسالة بطاقة تم إنشاؤها باستخدام واجهة برمجة تطبيقات REST Chat
.

لغة Python

  1. في دليل العمل، يمكنك إنشاء ملف باسم chat_create_card_message.py.
  2. أدرِج الرمز التالي في chat_create_card_message.py:

    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=
        {
          'cards_v2': [{
            'card_id': '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. في الرمز، استبدل SPACE باسم مساحة عمل، يمكنك الحصول عليه من طريقة spaces.list() في Chat API، أو من عنوان URL لمساحة عمل.

  4. في دليل العمل، يمكنك إنشاء النموذج وتشغيله:

    python3 chat_create_card_message.py
    

للتعرُّف على مزيد من المعلومات حول التعامل مع الرسائل في واجهة برمجة تطبيقات Chat REST، يُرجى الاطِّلاع على إنشاء الرسائل وقراءتها وتحديثها وحذفها.

فتح مربّع حوار

مربّعات الحوار عبارة عن واجهات مستنِدة إلى البطاقات تفتحها تطبيقات Chat للتفاعل مع المستخدمين. لمساعدة المستخدمين في إتمام عمليات متعددة الخطوات، يمكن للتطبيقات فتح مربّعات حوار تسلسلية. يمكن للتطبيقات فتح مربّعات الحوار استجابةً لنقرة على الزر على رسالة بطاقة أو استجابةً لأمر شرطة مائلة.

تُعد مربّعات الحوار مفيدة للعديد من أنواع تفاعلات المستخدم، بما في ذلك:

  • جمع المعلومات من المستخدمين
  • مصادقة المستخدمين باستخدام خدمات الويب
  • ضبط إعدادات تطبيق Chat

في هذا المثال، يفتح تطبيق Chat مربع حوار لمساعدة المستخدم في إنشاء جهة اتصال جديدة لدفتر العناوين:

مربع حوار يتضمن مجموعة متنوعة من الأدوات المختلفة.

لتنفيذ مربعات الحوار، راجِع فتح مربّعات الحوار.

تنسيق البطاقة

تنسيق نص البطاقة

في البطاقات الداخلية، تتيح معظم حقول النصوص تنسيق النص الأساسي من خلال مجموعة فرعية صغيرة من علامات HTML. يتم عرض العلامات المتوافقة والغرض منها في الجدول أدناه:

غامق <b> مائل <i>
تسطير <> يتوسطه خط <Strike>
لون الخط <font color=""> رابط تشعّبي <a href="">
فاصل سطر <br>

تجدر الإشارة إلى أنه يتم تحليل نص الرسالة الأساسية باستخدام بنية ترميز مختلفة محسّنة للمستخدمين. لمعرفة التفاصيل، يُرجى الاطّلاع على إرسال رسالة نصية.

الرموز المدمجة

تتيح أداتا DecoratedText وButtonList العنصر icon الذي تم استخدامه لتحديد أحد الرموز المضمنة المتوفرة في Google Chat:

{ . . "knownIcon": "TRAIN" . . }

يسرد الجدول التالي الرموز المضمّنة المتاحة لرسائل البطاقات:

الطائرة إشارة مرجعية
حافلة السيارة
الساعة تأكيدATION_NUMBER_ICON
الوصف الدولار
البريد الإلكتروني EVENT_SEAT
تغادر في الساعة الرحلة الجوية
الفندق HOTEL_ROOM_TYPE
دعوة MAP_PIN
الاشتراك مستخدمون متعددون
الشخص الهاتف
RESTAURANT_ICON SHOPPING_CART
STAR المتجر
التذكرة القطار
VIDEO_CAMERA VIDEO_PLAY

الرموز المخصصة

يتيح لك أداؤك DecoratedText وButtonList استخدام الرموز المضمنة أعلاه، أو تحديد رموزك المخصصة. لتحديد رمز مخصّص، استخدِم العنصر iconUrl كما هو موضّح أدناه:

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

الحدود والاعتبارات

عند الاستعداد لإرسال رسائل البطاقات، يُرجى مراعاة هذه الحدود والاعتبارات.

  • لا تتوافق رسائل البطاقات مع الأدوات التالية، ولكن سيتوفّر الدعم قريبًا:

    • TextInput، وهو حقل يمكن للمستخدمين إدخال نص فيه.
    • SelectionInput، والذي يوفّر مجموعة من العناصر القابلة للاختيار، مثل قائمة بمربّعات الاختيار أو أزرار الاختيار أو مفاتيح التبديل أو القائمة المنسدلة.
    • DateTimePicker، ما يتيح للمستخدمين تحديد تاريخ أو وقت أو كليهما.
    • Grid، والذي يضع مجموعة من العناصر في شبكة بسيطة.