تنسيق الرسائل

توضّح هذه الصفحة كيف يمكن لتطبيقات Google Chat تنسيق النص لإرسال رسائل تحتوي على أي مما يلي:

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

تنسيق رسالة نصية

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

بالنسبة إلى الرسائل المُرسَلة أو التي تم استردادها باستخدام Chat API، يمكنك استخدام بنية Markdown العادية (MARKUP_SYNTAX_MARKDOWN) أو بنية ترميز Chat (MARKUP_SYNTAX_CHAT). يمكنك ضبط بنية الترميز التلقائية على مستوى التطبيق في Google Cloud Console (يُرجى الاطّلاع على ضبط Google Chat API):

• Markdown: صيغة Markdown العادية (MARKUP_SYNTAX_MARKDOWN)، استنادًا إلى مواصفات CommonMark مع إضافات أخرى تستخدم تطبيقات Chat التي تم إنشاؤها حديثًا تنسيق Markdown تلقائيًا.
• ‫Chat: صيغة ترميز Chat (MARKUP_SYNTAX_CHAT). تستخدم تطبيقات Chat الحالية Chat تلقائيًا للحفاظ على التوافق مع الأنظمة القديمة.

يمكنك أيضًا تحديد markup_syntax في طلبات بيانات من واجهة برمجة التطبيقات الفردية في Chat لتجاوز الإعداد التلقائي على مستوى التطبيق. عندما لا يتم تحديد markup_syntax في طلب بيانات من واجهة برمجة التطبيقات، يتم ضبط الترميز استنادًا إلى كيفية استدعاء Chat API:

• تطبيقات Chat التي تم ضبطها: تستخدم بنية الترميز المحفوظة في صفحة "إعدادات Chat API".
• مشاريع على السحابة الإلكترونية غير المضبوطة (بدون ضبط): إذا كان مشروعك على السحابة الإلكترونية يرسل طلبات إلى 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*?",
    }

تنسيق الروابط

إذا أدرجت عنوان URL لرابط عادي في نص رسالتك، مثل http://www.example.com/، سيستخدم Google Chat هذا النص كنص الرابط وسيربط هذا النص تلقائيًا بعنوان URL المحدّد.

لتقديم نص رابط بديل للرابط، استخدِم البنية التالية:

• بالنسبة إلى رسائل واجهة برمجة التطبيقات التي تم ضبطها باستخدام 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، مع تخصيص id فريد لكل عنصر Citation.
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.

استخدِم Card Builder لتصميم ومعاينة واجهات المستخدم والرسائل لتطبيقات Chat:

تنسيق نص الفقرة

يتم عرض العلامات المتوافقة والغرض منها في الجدول التالي:

لتحديد القوائم ومجموعات الرموز، استخدِم العلامات التالية:

This is a code block.

Markdown

عند تفعيل بنية Markdown، يمكنك استخدام البنية التالية:

إضافة رموز إلى النص

لعرض الرموز بجانب النص في بطاقة، يمكنك استخدام التطبيقَين المصغّرَين DecoratedText وButtonList.

توضّح الأقسام التالية كيفية استخدام الرموز المضمّنة أو رموز Google Material أو الرموز المخصّصة في النصوص أو الأزرار المزخرفة.

استخدام الرموز من Chat

لاستخدام الرموز المضمّنة المتاحة في Chat، يُرجى تحديد أحد الخيارات التالية:

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

فيما يلي مثال على بطاقة بها رمز بريد إلكتروني:

استخدام رموز Google Material

يمكنك استخدام رموز متوافقة مع إرشادات التصميم المتعدّد الأبعاد من Google للاختيار من بين أكثر من 2,500 رمز وتخصيص سمك الرموز وتعبئتها ودرجتها.

في ما يلي مثال على بطاقة تتضمّن رمز Google Material:

استخدام رموز مخصّصة

لإضافة رمز مخصّص، أدرِج الحقل iconUrl وحدِّد عنوان URL المقابل للرمز.

في ما يلي مثال على رمز مخصّص: