الرد على التقييمات، ثم تعديل رد أو أرشفته

ابحث عن التقييمات التي تقبل ردًا من المالك، وانشر ردًا، وتأكد من وصوله إلى منصة النشر، ثم صحّح صياغته أو أرشفه.

يُنشر رد المالك على منصة النشر نيابةً عنك. تقبله الواجهة البرمجية فورًا وتوصله بشكل غير متزامن، ويكون التسلسل كما يلي: اختر تقييمًا يمكن الرد عليه، وانشر الرد، ثم تأكد من وصوله بإعادة القراءة.

1. اختر التقييمات التي يمكن الرد عليها

اعرض قائمة تقييمات الموقع واحتفظ بالتقييمات التي تكون فيها قيمة canRespond هي true وقيمة responded هي false. يجري عامل التصفية responseStatus=["PENDING"] التحقق الثاني على الخادم؛ ويجب ترميز قيمة JSON بترميز URL، وهو ما يتولاه --data-urlencode.

curl -G "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'responseStatus=["PENDING"]' \--data-urlencode 'first=25'

{  "node": {    "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",    "source": "maps.google.com",    "rating": 5,    "content": "nice place for family together",    "responded": false,    "responseCount": 0,    "canRespond": true  }}

تكون قيمة canRespond هي false للمصادر التي لا تقبل ردود المالك عبر الواجهة البرمجية. تجاوز هذه التقييمات؛ فلن تصل محاولة الرد إلى منصة النشر. عند صياغة الرد، يوضح لك عرض قائمة عبارات التقييمات أكثر ما يذكره العملاء، حتى يتمكن الرد من تناوله.

2. انشر ردًا

يأخذ POST /locations/reviews/respond الحقول مباشرةً في جسم الطلب، دون تغليفها داخل input. interactionId هو id الخاص بالتقييم. الحقل respondedWith اختياري ويحدد اسم قالب الرد إذا استخدمت قالبًا.

curl -X POST https://listingsapi.com/api/v4/locations/reviews/respond \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "interactionId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",  "responseContent": "Thank you for visiting Jenny Home: we are glad you enjoyed your experience!"}'

{  "data": {    "respondToInteraction": {      "interaction": {        "id": "2090753a-ece6-4837-8336-8494ad308523",        "interactionId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",        "content": "Thank you for visiting Jenny Home: we are glad you enjoyed your experience!",        "interactionStatus": "CREATED",        "editedResponse": false      },      "errors": null    }  }}

احتفظ بـ interaction.id: فهو responseId الذي تحتاج إليه لتعديل الرد أو أرشفته لاحقًا. عند رفض الرد، تعود الاستجابة على هيئة 200 مع تعبئة errors داخل data.respondToInteraction، لذا اقرأ جسم الاستجابة. تثير حزم SDK الاستثناء ValidationError في هذه الحالة.

3. تأكد من وصوله إلى منصة النشر

تكون قيمة interactionStatus هي CREATED في البداية وتتقدم دون استدعاءات إضافية. أعد قراءة التقييم باستخدام معرّفه بعد انتظار قصير، وتحقق من responded وresponseCount وحالة الرد داخل responses[].

curl -G "https://listingsapi.com/api/v4/reviewDetails" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'interactionIds=["9e26d2a8-a6ed-42ea-8454-47d1c92ea841"]'

{  "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",  "responded": true,  "responseCount": 1,  "responses": [    {      "id": "2090753a-ece6-4837-8336-8494ad308523",      "content": "Thank you for visiting Jenny Home: we are glad you enjoyed your experience!",      "interactionStatus": "CONFIRMED",      "editedResponse": false    }  ]}

تشير responded: true مع رد حالته CONFIRMED أو COMPLETED إلى أن العميل يمكنه رؤيته. إذا رأيت FAILED، فاقرأ remarks في الاستجابة لمعرفة سبب منصة النشر قبل المحاولة مجددًا.

4. عدّل ردًا

يحتاج POST /locations/reviews/respond/edit إلى كلا المعرّفين: reviewId هو معرّف التقييم، وresponseId هو معرّف الرد من الخطوة 2. يُعاد إرسال التعديل، لذا تعود قيمة interactionStatus للرد إلى CREATED وتصبح قيمة editedResponse هي true بمجرد وصوله.

curl -X POST https://listingsapi.com/api/v4/locations/reviews/respond/edit \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "reviewId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",  "responseId": "2090753a-ece6-4837-8336-8494ad308523",  "responseContent": "Thank you again: we have updated our reply to include our new store hours."}'

{  "data": {    "editResponse": {      "status": "true",      "reviewId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",      "responseId": "2090753a-ece6-4837-8336-8494ad308523"    }  }}

تكون قيمة status هي السلسلة النصية "true" عند قبول التعديل. تأكد من الصياغة الجديدة بالطريقة نفسها المتبعة في الخطوة 3.

5. أرشف ردًا

يأخذ POST /locations/reviews/respond/archive الحقل responseId فقط. تزيل الأرشفة الرد من responses الخاص بالتفاعل في Listings API. وهي لا تسحب ردًا منشورًا بالفعل على Google أو Facebook، لذا استخدمها لإزالة مسودة فشل نشرها أو استُبدلت بمسودة أخرى، واستخدم التعديل لأي رد منشور.

curl -X POST https://listingsapi.com/api/v4/locations/reviews/respond/archive \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "responseId": "2090753a-ece6-4837-8336-8494ad308523" }'

{  "data": {    "archiveResponse": {      "status": "true"    }  }}

بعد الأرشفة، تنخفض قيمة responseCount للتقييم ويعكس responded الردود المتبقية.

6. استقبل أحداث الردود عبر webhook

يُطلَق حدث interaction.response عند نشر رد أو تعديله أو أرشفته. تكون حمولة البيانات ضمن data.interaction، مع type: "Response"، وparent_id مضبوطًا على معرّف التقييم، حتى تتمكن من مطابقتها مع سجلك دون استدعاء آخر. وكما هو الحال مع interaction.review، لا يكون location_id الخاص به موحّد الصيغة وقد تكون قيمته null. ترد تعليمات الإعداد في الاستجابة للأحداث باستخدام webhooks.

الخطوات التالية

• جلب التقييمات: أنشئ قائمة انتظار للتقييمات المعلّقة على مستوى الحساب.
• تحليلات التقييمات: تتبّع review-response-rate أثناء معالجة التقييمات في قائمة الانتظار.
• المرجع: الرد على تفاعل، تعديل رد، أرشفة رد، سمات التفاعل.
• حزم SDK: التقييمات في Python، التقييمات في Node.