Method: spaces.messages.create

ينشئ رسالة في مساحة Chat في Google Chat. للاطّلاع على مثال، يُرجى مراجعة إرسال رسالة.

يتيح الأنواع التالية من المصادقة:

  • مصادقة التطبيق باستخدام نطاق التفويض:
    • https://www.googleapis.com/auth/chat.bot
  • مصادقة المستخدم باستخدام أحد نطاقات التفويض التالية:
    • https://www.googleapis.com/auth/chat.messages.create
    • https://www.googleapis.com/auth/chat.messages
    • https://www.googleapis.com/auth/chat.import (مساحات وضع الاستيراد فقط)

ينسب Chat مُرسِل الرسالة بشكل مختلف استنادًا إلى نوع المصادقة التي تستخدمها في طلبك.

تعرض الصورة التالية كيفية تحديد Chat لمصدر الرسالة عند استخدام مصادقة التطبيق. يعرض Chat تطبيق Chat كمُرسِل الرسالة. يمكن أن يتضمّن محتوى الرسالة نصًا (text) وبطاقات (cardsV2) وتطبيقات مصغّرة ملحقة (accessoryWidgets).

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

تعرض الصورة التالية كيفية تحديد Chat لمرسِل الرسالة عند استخدام مصادقة المستخدم. يعرض Chat المستخدم كمُرسِل الرسالة وينسب تطبيق Chat إلى الرسالة من خلال عرض اسمه. يمكن أن يحتوي محتوى الرسالة على نص فقط (text).

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

الحد الأقصى لحجم الرسالة، بما في ذلك محتوى الرسالة، هو 32,000 بايت.

بالنسبة إلى طلبات webhook، لا يحتوي الردّ على الرسالة الكاملة. يملأ الردّ الحقلَين name وthread.name فقط بالإضافة إلى المعلومات التي كانت في الطلب.

طلب HTTP

POST https://chat.googleapis.com/v1/{parent=spaces/*}/messages

يستخدم عنوان URL بنية تحويل الترميز إلى gRPC.

مَعلمات المسار

المعلمات
parent

string

الحقل مطلوب. اسم المورد للمساحة التي سيتم إنشاء رسالة فيها

التنسيق: spaces/{space}

مَعلمات طلب البحث

المعلمات
threadKey
(deprecated)

string

اختيارية: تم إيقاف هذه السياسة نهائيًا، لذا يُرجى استخدام سياسة thread.thread_key بدلاً منها. رقم تعريف سلسلة المحادثات يمكن إدخال ما يصل إلى 4,000 حرف. لبدء سلسلة محادثات أو الإضافة إليها، أنشئ رسالة وحدِّد threadKey أو thread.name. للاطّلاع على مثال على الاستخدام، يُرجى مراجعة بدء سلسلة رسائل أو الردّ عليها.

requestId

string

اختيارية: معرّف فريد لهذا الطلب ننصح باستخدام معرّف UUID عشوائي. يؤدي تحديد معرّف الطلب إلى جعل الطلب متكررًا، ما يضمن أنّ الطلبات المتعددة المتطابقة التي تحمل معرّف الطلب نفسه تؤدي إلى إنشاء رسالة واحدة فقط. وتؤدي الطلبات اللاحقة التي تتضمّن معرّف الطلب نفسه إلى عرض الرسالة الحالية ولا تعدّلها، حتى إذا كانت التفاصيل المطلوبة تختلف عن الحالة الحالية.

لاستخدام هذا الحقل بفعالية:

  • تأكَّد من أنّ الطلبات اللاحقة متطابقة وتستخدم بيانات اعتماد المصادقة نفسها المستخدَمة في الطلب الأصلي.
  • إذا سبق أن تم إنشاء رسالة باستخدام معرّف الطلب المقدَّم، سيعرض الطلب هذه الرسالة. يُرجى العِلم أنّ الرسالة المعروضة قد لا تكون مكتملة، إذ تعرض واجهة برمجة التطبيقات الرسالة في طلبك مع أسماء الموارد التي يحدّدها النظام. لاسترداد أحدث البيانات الوصفية للرسالة، يمكنك طلب messages.get.
  • تؤدي إعادة استخدام معرّف طلب حالي مع مستخدم مختلف تمّت مصادقته إلى حدوث خطأ.
messageReplyOption

enum (MessageReplyOption)

اختيارية: تحدّد ما إذا كانت الرسالة تبدأ سلسلة محادثات أو تردّ على رسالة أخرى. لا تتوفّر هذه الميزة إلا في المساحات المُسمّاة.

عند الردّ على تفاعلات المستخدمين، يتم تجاهل هذا الحقل. بالنسبة إلى التفاعلات ضمن سلسلة محادثات، يتم إنشاء الردّ في سلسلة المحادثات نفسها. وإلا، سيتم إنشاء الرد كسلسلة محادثات جديدة.

messageId

string

اختيارية: معرّف مخصّص لرسالة يتيح لتطبيقات Chat الحصول على رسالة أو تعديلها أو حذفها بدون الحاجة إلى تخزين المعرّف الذي يحدّده النظام في اسم مورد الرسالة (الممثّل في حقل name للرسالة).

يجب أن تستوفي قيمة هذا الحقل المتطلبات التالية:

  • يبدأ بـ "client-". على سبيل المثال، client-custom-name هو معرّف مخصّص صالح، ولكن custom-name ليس كذلك.
  • يحتوي على ما يصل إلى 63 حرفًا وأحرف صغيرة وأرقام وواصلات فقط.
  • أن يكون فريدًا داخل مساحة معيّنة لا يمكن لتطبيق Chat استخدام المعرّف المخصّص نفسه لرسائل مختلفة.

لمعرفة التفاصيل، يُرجى الاطّلاع على تسمية رسالة.

createMessageNotificationOptions

object (CreateMessageNotificationOptions)

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

نص الطلب

يحتوي نص الطلب على مثال Message.

نص الاستجابة

إذا كانت الاستجابة ناجحة، سيحتوي نصها على مثال Message تم إنشاؤه حديثًا.

نطاقات الأذونات

يتطلب أحد نطاقات OAuth التالية:

  • https://www.googleapis.com/auth/chat.bot
  • https://www.googleapis.com/auth/chat.import
  • https://www.googleapis.com/auth/chat.messages
  • https://www.googleapis.com/auth/chat.messages.create

لمزيد من المعلومات، يُرجى الاطّلاع على دليل التفويض.

MessageReplyOption

تحدّد هذه السمة كيفية الردّ على رسالة. وقد تتم إضافة المزيد من الولايات في المستقبل.

عمليات التعداد
MESSAGE_REPLY_OPTION_UNSPECIFIED تلقائي: لبدء سلسلة محادثات جديدة يؤدي استخدام هذا الخيار إلى تجاهل أي thread ID أو threadKey مضمّن.
REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD يتم إنشاء الرسالة كردّ على سلسلة المحادثات المحدّدة من خلال thread ID أو threadKey. وفي حال تعذّر ذلك، تبدأ الرسالة سلسلة محادثات جديدة بدلاً من ذلك.
REPLY_MESSAGE_OR_FAIL يتم إنشاء الرسالة كردّ على سلسلة المحادثات المحدّدة من خلال thread ID أو threadKey. إذا تم استخدام threadKey جديد، يتم إنشاء سلسلة محادثات جديدة. إذا تعذّر إنشاء الرسالة، سيتم عرض الخطأ NOT_FOUND بدلاً من ذلك.

CreateMessageNotificationOptions

خيارات سلوك الإشعار عند نشر الرسالة

تمثيل JSON
{
  "notificationType": enum (NotificationType)
}
الحقول
notificationType

enum (NotificationType)

نوع الإشعار للرسالة

NotificationType

خيارات أنواع الإشعارات للرسالة

عمليات التعداد
NOTIFICATION_TYPE_NONE الإعداد التلقائي يشبه سلوك الإشعارات ما يحدث عندما يرسل المستخدم البشري الرسالة باستخدام واجهة مستخدم Chat: لا يتم إرسال أي إشعار إلى المُرسِل البشري.
NOTIFICATION_TYPE_INCLUDE_HUMAN_CREATOR

يتم إرسال إشعار (إشعارات فورية أو إشعارات عبر البريد الإلكتروني أو غير ذلك) إلى منشئ الرسالة (على سبيل المثال، المستخدم الذي تم استخدام مصادقته لإنشاء الرسالة) ويتم وضع علامة على الرسالة كغير مقروءة.

لن يؤدي هذا الإجراء إلى إلغاء إعدادات إشعارات المستخدمين الحالية في المساحة. على سبيل المثال، إذا اختار المستخدم عدم تلقّي إشعارات بشأن مساحة معيّنة، لن يتم إرسال إشعارات إليه حتى إذا تم ضبط هذا الخيار.

يتطلب ذلك مصادقة المستخدم.

NOTIFICATION_TYPE_FORCE_NOTIFY

فرض إرسال إشعار إلى المستلِمين يؤدي ذلك إلى تجاوز إعدادات إشعارات المساحة لدى المستخدمين وإعدادات "عدم الإزعاج" في Chat. لا يتجاوز هذا الخيار إعدادات "عدم الإزعاج" على مستوى الجهاز.

يتطلّب ذلك مصادقة التطبيق.

NOTIFICATION_TYPE_SILENT

لا يتم إشعار المستلِمين، ولا يتم وضع علامة "غير مقروءة" على الرسالة. ويشبه هذا الإجراء كتم صوت المحادثة أو تفعيل ميزة عدم الإزعاج في Chat.

يتطلّب ذلك مصادقة التطبيق.