قالب‌بندی پیام‌ها

این صفحه توضیح می‌دهد که برنامه‌های Google Chat چگونه می‌توانند نوشتار را قالب‌بندی کنند تا پیام‌هایی ارسال کنند که حاوی هریک از موارد زیر باشد:

• نوشتار غنی‌شده‌ای که حاوی اَبَرپیوند یا نام‌بردن با @از یک یا همه کاربران در فضای Chat است.
• نوشتاری که در میانای کارت نشان داده می‌شود، ازجمله نوشتار پاراگراف یا نوشتار میانای کاربری که در کنار نماد، مثلاً دکمه، نمایش داده می‌شود.

قالب‌بندی پیامک

Chat به شما امکان می‌دهد قالب‌بندی پایه را به پیام نوشتاری اضافه کنید، ازجمله پررنگ، ایتالیک، و خط‌خورده. قالب‌بندی نوشتار در پیام‌های نوشتاری با پیام‌های کارتی متفاوت است زیرا پیام‌های نوشتاری با همان نحوی قالب‌بندی می‌شوند که کاربران Chat استفاده می‌کنند.

برای پیام‌های ارسال‌شده یا بازیابی‌شده بااستفاده از Chat API، می‌توانید از نحو Markdown استاندارد (MARKUP_SYNTAX_MARKDOWN) یا نحو نشانه‌گذاری Chat (MARKUP_SYNTAX_CHAT) استفاده کنید. می‌توانید نحو نشانه‌گذاری پیش‌فرض Markup syntax را در سطح برنامه در کنسول Google Cloud پیکربندی کنید (به پیکربندی Google Chat API مراجعه کنید):

• Markdown: نحو استاندارد Markdown (MARKUP_SYNTAX_MARKDOWN)، براساس مشخصات CommonMark با افزونه‌های اضافی. برنامه‌های Chat که به‌تازگی ایجاد شده‌اند به‌طور پیش‌فرض روی Markdown تنظیم شده‌اند.
• Chat: نحو نشانه‌گذاری Chat (MARKUP_SYNTAX_CHAT). برنامه‌های Chat موجود برای حفظ سازگاری با نسخه‌های قدیمی به‌طور پیش‌فرض روی Chat تنظیم شده‌اند.

همچنین می‌توانید markup_syntax را در درخواست‌های تکی Chat API مشخص کنید تا پیش‌فرض سطح برنامه را لغو کنید. وقتی markup_syntax در درخواست API مشخص نشده باشد، نشان‌گذاری براساس نحوه فراخوانی Chat API تنظیم می‌شود:

• برنامه‌های Chat پیکربندی‌شده: از نحو نشانه‌گذاری ذخیره‌شده در صفحه «پیکربندی Chat API» استفاده می‌کند.
• پروژه‌های Cloud پیکربندی‌نشده (بدون پیکربندی): اگر پروژه Cloud شما Chat API را بدون پیکربندی ذخیره‌شده برنامه Chat فراخوانی کند، درخواست‌ها به‌طور پیش‌فرض به MARKUP_SYNTAX_MARKDOWN می‌روند.
• وب‌قلاب‌های ورودی: به‌طور پیش‌فرض روی MARKUP_SYNTAX_CHAT تنظیم شده است. ارسال پیام بااستفاده از وب‌قلاب‌های ورودی را ببینید.

برای قالب‌بندی پیام‌های نوشتاری، از نحو زیر استفاده کنید:

برای مثال، JSON زیر را درنظر بگیرید:

    {
      "text": "Your pizza delivery *has arrived*!\nThank you for using _Cymbal Pizza!_"
    }

این پیام نوشتاری قالب‌بندی‌شده موارد زیر را در فضای Chat نمایش می‌دهد:

مشاهده قالب‌بندی نوشتار ارسال‌شده در پیام

وقتی کاربری پیامی ارسال می‌کند، بدنه نوشتار ساده پیام در فیلد text قرار می‌گیرد. برخی‌از قالب‌بندی‌هایی که بااستفاده از نحو Markdown روی پیام نوشتاری اعمال شده است در فیلد text قرار دارد. قالب‌بندی اضافی در فیلد فقط خروجی formattedText است، ازجمله موارد زیر:

• نحو Markdown اضافی برای نوشتار
• نام بردن‌ها از کاربر
• اَبَرپیوندهای سفارشی
• صورتک سفارشی

برای مثال، نوشتار زیر را که توسط کاربر ارسال شده است درنظر بگیرید:

اگر پیام بااستفاده از منو قالب در رابط کاربری Chat قالب‌بندی شده باشد، فیلد text فقط حاوی نوشتار است، درحالی‌که فیلد formattedText حاوی نشانه‌گذاری‌ها، نوشتار، و اَبَرپیوند است. مثال زیر پیش‌نویس پیام نوشتاری را با یک واژه اَبَرپیوندشده، موارد موجود در فهرست، و یک واژه پررنگ‌شده نشان می‌دهد:

پیام در قالب زیر دریافت می‌شود:

    {
      "text": "I can meet there at:\nNoon\n3 pm\n5 pm\nWhat time works for you?",
      "formattedText": "I can meet <http://example.com|there> at:\n* Noon\n* 3 pm\n* 5 pm\nWhat time works for *you*?",
    }

پیوندهای قالب

اگر نشانی وب پیوند ساده‌ای را در نوشتار پیامتان اضافه کنید، مثلاً http://www.example.com/، Google Chat از آن به‌عنوان نوشتار پیوند استفاده می‌کند و به‌طور خودکار آن نوشتار را به نشانی وب مشخص‌شده پیوند می‌دهد.

برای ارائه نوشتار پیوند جایگزین برای پیوندتان، از نحو زیر استفاده کنید:

• برای پیام‌های API پیکربندی‌شده با Markdown، از نحو پیوند Markdown استاندارد استفاده کنید:

  نحو نمونه	نوشتار نمایش‌داده‌شده در Google Chat
  [Example website](https://example.com)	Example website

• برای پیام‌های نوشتار ساده استاندارد، از نحو لوله استفاده کنید:

  نحو نمونه	نوشتار نمایش‌داده‌شده در Google Chat
  <https://example.com|Example website>	Example website

  خط عمودی و نوشتار پیوند اختیاری هستند، بنابراین <https://example.com> و https://example.com معادل هستند.

استفاده از اموجی سفارشی در پیامک

برنامه‌های Chat می‌توانند پیام‌های نوشتاری با اموجی سفارشی ارسال کنند تا پیام‌ها را شخصی‌سازی کنند. اموجی‌های سفارشی فقط برای سازمان‌های Google Workspace دردسترس است و سرپرست باید اموجی‌های سفارشی را برای سازمان روشن کند. برای اطلاعات بیشتر، به آشنایی با اموجی‌های سفارشی در Google Chat و مدیریت اجازه‌های اموجی سفارشی مراجعه کنید.

برای ایجاد پیام با اموجی‌های سفارشی، برنامه‌تان باید از اصالت‌سنجی کاربر استفاده کند. اموجی‌های سفارشی در پیام‌های ایجادشده به‌عنوان وب‌قلاب یا در پیام‌های ایجادشده با اصالت‌سنجی برنامه پشتیبانی نمی‌شوند.

برای افزودن اموجی سفارشی به نوشتار پیام، name یا emoji_name منبع customEmoji را مشخص کنید:

{
    "text": "Hello <customEmojis/CUSTOM_EMOJI_ID>."
}

برای استفاده از این نمونه، CUSTOM_EMOJI_ID را با شناسه اموجی سفارشی جایگزین کنید. می‌توانید این شناسه را در فیلد name یا emoji_name منبع customEmoji پیدا کنید.

اگر برنامه‌تان پیام‌ها را بااستفاده از نحو Markdown ارسال می‌کند، می‌توانید بااستفاده از شناسه اموجی سفارشی، اموجی‌های سفارشی را در قالب برچسب HTML مشخص کنید:

{
  "text": "Hello <chat-emoji data-custom-emoji=\"customEmojis/CUSTOM_EMOJI_ID\">."
}

یا می‌توانید نام اموجی سفارشی را مشخص کنید:

{
  "text": "Hello <chat-emoji data-emoji-name=\"CUSTOM_EMOJI_NAME\">."
}

برای استفاده از این نمونه‌ها، CUSTOM_EMOJI_ID را با شناسه اموجی سفارشی و CUSTOM_EMOJI_NAME را با نام کد کوتاه اموجی سفارشی جایگزین کنید.

نام بردن از کاربران در پیامک

برنامه‌های Chat می‌توانند پیام‌های نوشتاری ارسال کنند که یک یا همه کاربران را در فضای Chat با @نام می‌برد. برنامه‌های Chat همچنین می‌توانند از کاربرانی که به فضا نپیوسته‌اند یا عضو فضایی هستند که در حالت وارد کردن است نام ببرند.

پیام‌های بی‌صدا از نام بردن کاربران پشتیبانی نمی‌کنند. اگر در پیام بی‌صدا از کسی نام برده شود، خطا برگردانده می‌شود.

@نامبردن از کاربران خاص

برای @نامبری کاربر خاصی، <users/{user}> را به پیام نوشتاری اضافه کنید که در آن {user} شناسه کاربر است. برای مثال، پیامک زیر را درنظر بگیرید که در آن 123456789012345678901 نشان‌دهنده شناسه کاربر «ماهان س.» است:

{
    "text": "A customer has reported an issue. Assigning ticket #942 to <users/123456789012345678901>."
}

اگر برنامه‌تان پیام‌ها را بااستفاده از نحو Markdown ارسال می‌کند، از قالب برچسب HTML chat-user برای مشخص کردن شناسه کاربر استفاده کنید:

{
  "text": "Assigning ticket #942 to <chat-user data-user=\"users/123456789012345678901\">."
}

یا ازطریق ایمیل مشخص کنید:

{
  "text": "Assigning ticket #942 to <chat-user data-email=\"mahan@example.com\">."
}

پیامک به‌صورت زیر نمایش داده می‌شود:

می‌توانید مقدار users/{user} را به روش‌های زیر مشخص کنید:

• اگر برنامه Google Chat شما به پیامی که کاربر ارسال کرده است پاسخ می‌دهد، می‌توانید از فیلد message.sender.name رویداد تعامل MESSAGE استفاده کنید.

• اگر برنامه Google Chat شما درحال ایجاد پیام نوشتاری ناهمگام است، می‌توانید مقدار users/{user} را به روش‌های زیر مشخص کنید:

  • از فیلد name منبع Google Chat User، مثل users/123456789012345678901، استفاده کنید.
  • از نشانی ایمیل کاربر به‌عنوان نام مستعار برای مقدار {user} استفاده کنید. برای مثال، اگر نشانی ایمیل mahan@example.com باشد، می‌توانید کاربر را به‌صورت users/mahan@example.com مشخص کنید. برای استفاده از ایمیل مستعار، برنامه Google Chat شما باید به‌عنوان کاربر اصالت‌سنجی شود.

• اگر از People API استفاده می‌کنید، می‌توانید از روش people.get برای شناسایی شناسه کاربر استفاده کنید.

@نامبردن از همه کاربران

برای ایجاد پیام نوشتاری که از همه افراد در فضا @نام می‌برد، {user} را با all جایگزین کنید. نمونه JSON زیر از همه کاربران در پیام نام می‌برد:

{
    "text": "Important message for <users/all>: Code freeze starts at midnight tonight!"
}

اگر برنامه‌تان پیام‌ها را بااستفاده از نحو Markdown ارسال می‌کند، نامبری را بااستفاده از قالب تگ HTML chat-user مشخص کنید:

{
  "text": "Important message for <chat-user data-user=\"users/all\">: Code freeze starts at midnight tonight!"
}

افزودن استناد به پیامک

برنامه‌های Chat می‌توانند برای ارائه اطلاعات دقیق منبع به کاربران، در پیام‌های نوشتاری استناد اضافه کنند. به دو روش می‌توانید منبع ارائه دهید:

• نقل‌قول‌های درون‌خطی: کارت‌های تعاملی اضافه کنید که وقتی کاربران نشانگر را روی بخش‌های خاصی از نوشتار پیام شما نگه می‌دارند، ظاهر می‌شوند.
• منابع پانویس: فهرستی از منابع را در پایین پیام به‌عنوان پیوندهای پانویس نمایش می‌دهد.

استنادها فقط زمانی پشتیبانی می‌شوند که markupSyntax پیام روی MARKUP_SYNTAX_MARKDOWN تنظیم شده باشد. این ویژگی فقط ازطریق ایجاد پیام ناهمگام بااستفاده از Chat API پشتیبانی می‌شود.

برای افزودن نقل‌قول‌های درون‌خطی به پیام:

1. منابع را در فهرست citations پیام elements ارائه دهید و به هر شیء Citation یک id یکتا اختصاص دهید.
2. در نوشتار پیام، نوشتاری را که می‌خواهید نقل‌قول کنید بااستفاده از قالب برچسب HTML chat-citation بپیچید: <chat-citation data-id="{id}">{text}</chat-citation>. مطمئن شوید {id} با شناسه‌ای که در elements تعریف کرده‌اید مطابقت داشته باشد. نقل‌قول‌های بدون مرجع (آن‌هایی که برچسب منطبق ندارند) نادیده گرفته می‌شوند.

{
  "text": "This is a <chat-citation data-id=\"cite_1\">cited</chat-citation> text.",
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "elements": {
    "citations": [
      {
        "id": "cite_1",
        "citedSources": [
          {
            "title": "Example Source",
            "uri": "https://example.com"
          }
        ]
      }
    ]
  }
}

برای افزودن منابع پانویس به پیام، منابع را در فهرست citedSources پیام elements ارائه دهید. هر منبعی که اینجا ارائه شود به‌طور خودکار به‌عنوان پیوند پانویس در زیر پیام نشان داده می‌شود و به هیچ برچسب درون‌خطی‌ای در نوشتار پیام نیاز ندارد.

{
  "text": "This is a message with a footer source.",
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "elements": {
    "citedSources": [
      {
        "title": "Example Source",
        "uri": "https://example.com"
      }
    ]
  }
}

قالب‌بندی نوشتاری که در کارت‌ها نشان داده می‌شود

در داخل کارت‌ها، اکثر فیلدهای نوشتاری از قالب‌بندی نوشتار پایه بااستفاده از زیرمجموعه کوچکی از برچسب‌های HTML پشتیبانی می‌کنند. قالب‌بندی نوشتار در پیام‌های کارتی با پیام‌های نوشتاری متفاوت است زیرا پیام‌های نوشتاری با همان نحوی قالب‌بندی می‌شوند که کاربران Chat استفاده می‌کنند.

از «کارت‌ساز» برای طراحی و پیش‌نمایش پیام‌رسانی و میاناهای کاربر برای برنامه‌های Chat استفاده کنید:

قالب‌بندی نوشتار پاراگراف

برچسب‌های پشتیبانی‌شده و هدف آن‌ها در جدول زیر نشان داده شده است:

برای تعریف فهرست‌ها و بلوک‌های کد، از برچسب‌های زیر استفاده کنید:

This is a code block.

Markdown

وقتی نحو Markdown روشن باشد، می‌توانید از نحو زیر استفاده کنید:

افزودن نماد به نوشتار

برای نمایش نمادها در کنار نوشتار در کارت، می‌توانید از ابزاره‌های DecoratedText و ButtonList استفاده کنید.

بخش‌های زیر نحوه استفاده از نمادهای داخلی، نمادهای Google Material، یا نمادهای سفارشی را در نوشتار یا دکمه‌های تزئین‌شده توضیح می‌دهد.

استفاده از نمادهای Chat

برای استفاده از نمادهای داخلی موجود در Chat، یکی از موارد زیر را مشخص کنید:

جدول زیر نمادهای داخلی را که برای پیام‌های کارتی دردسترس است فهرست می‌کند:

در زیر نمونه‌ای از کارت با نماد ایمیل ارائه شده است:

استفاده از نمادهای Google Material

می‌توانید از نمادهای Google Material استفاده کنید تا از بین بیش‌از ۲۵۰۰ گزینه نماد انتخاب کنید و وزن، رنگ، و درجه نمادها را سفارشی‌سازی کنید.

در زیر نمونه‌ای از کارت با نماد Google Material ارائه شده است:

استفاده از نمادهای سفارشی

برای افزودن نماد سفارشی، فیلد iconUrl را اضافه کنید و نشانی وب مربوط به نماد را مشخص کنید.

در زیر نمونه‌ای از نماد سفارشی آورده شده است: