# تحديث

`POST` `https://api.pushwoosh.com/messaging/v2/update`

يستبدل رسالة تم إنشاؤها مسبقًا، محددة بواسطة `message_code` الخاص بها، بتعريف جديد. الاستبدال هو **استبدال كامل، وليس تصحيحًا**: يتم تطبيق التعريف الجديد تمامًا كما تم إرساله، ولا يتغير `message_code`.

التحديث متاح فقط عندما تكون الرسالة لا تزال **معلقة** — أي مجدولة للإرسال في المستقبل ولم يتم التقاطها بعد للمعالجة أو التسليم.

<Aside type="caution" title="هام">

- حقل `request` هو تعريف [`Notify`](/ar/developer/api-reference/messaging-api-v2/notify/) كامل. الحقول التي تحذفها **لا** يتم نقلها من الرسالة الأصلية — بل يتم إعادة تعيينها. أرسل الرسالة الكاملة التي تريدها، وليس فقط الأجزاء التي تم تغييرها.

- إذا كانت الرسالة قيد المعالجة بالفعل، أو تم تسليمها، أو تم إلغاؤها، أو تم حذفها، فإن واجهة برمجة التطبيقات (API) تُرجع `400`. هذا الاستدعاء ليس متطابقًا. تحقق من حالة الرسالة قبل التحديث.
</Aside>

للتحقق مما إذا كانت الرسالة لا تزال في حالة قابلة للتحديث، انظر [التحقق من حالة الرسالة](#checking-message-status).

## الطلب

قم بالمصادقة باستخدام [رمز Server API token](/ar/developer/api-reference/api-access-token/#server-api-token) الخاص بك في ترويسة `Authorization: Token <API_TOKEN>`.

| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
| `message_code` | string | نعم | [رمز الرسالة (Message code)](/ar/developer/api-reference/api-identifiers/#message-code) للرسالة التي سيتم تحديثها، كما تم إرجاعه بواسطة [`Notify`](/ar/developer/api-reference/messaging-api-v2/notify/) في `result.message_code`. |
| `request` | object | نعم | التعريف الجديد الكامل للرسالة. له نفس شكل نص طلب [`Notify`](/ar/developer/api-reference/messaging-api-v2/notify/) — كائن `segment` أو `transactional`. يتم التحقق من صحته تمامًا مثل `Notify`. |

### مثال على الطلب

إعادة جدولة رسالة segment وتغيير محتواها:

```bash
curl -X POST https://api.pushwoosh.com/messaging/v2/update \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message_code": "XXXX-XXXXXXXX-XXXXXXXX",
    "request": {
      "segment": {
        "application": "XXXXX-XXXXX",
        "platforms": ["IOS", "ANDROID"],
        "code": "active_users",
        "payload": {
          "content": {
            "localized_content": {
              "en": {
                "ios":     { "body": "Updated message" },
                "android": { "body": "Updated message" }
              }
            }
          }
        },
        "schedule": { "at": "2026-05-02T12:00:00Z" },
        "message_type": "MESSAGE_TYPE_MARKETING"
      }
    }
  }'
```

## الاستجابة

عند النجاح، تُرجع HTTP 200 مع نتيجة الرسالة المحدثة. يبقى `message_code` دون تغيير.

```json
{
  "result": {
    "message_code": "XXXX-XXXXXXXX-XXXXXXXX",
    "unknown_identifiers": []
  }
}
```

- `message_code` (string): نفس الرمز الذي تم تمريره في الطلب.
- `unknown_identifiers` (array of string): المعرفات في التعريف الجديد التي لم يتم العثور عليها، عند الاقتضاء (انظر [`Notify`](/ar/developer/api-reference/messaging-api-v2/notify/)).

## الأخطاء

تستخدم الأخطاء غلاف الخطأ القياسي لـ gRPC-Gateway: `{ "code": ..., "message": ..., "details": [...] }`.

| حالة HTTP | الشرط |
|---|---|
| `400` | `message_code` مفقود. |
| `400` | تعريف `request` الجديد مفقود أو غير صالح (يتم التحقق من صحته تمامًا مثل [`Notify`](/ar/developer/api-reference/messaging-api-v2/notify/)). |
| `400` | الرسالة ليست في حالة قابلة للتحديث (لم تعد `pending`). |
| `403` | الرسالة تنتمي إلى حساب آخر. |
| `404` | لا توجد رسالة لـ `message_code` المحدد. |
| `500` | حدث خطأ داخلي أثناء تحميل الرسالة أو تطبيق التحديث. أعد محاولة الطلب. |


**مثال**

تحديث رسالة لم تعد موجودة يُرجع HTTP `404`:

```json
{
  "code": 5,
  "message": "message not found",
  "details": []
}
```

## التحقق من حالة الرسالة

قبل التحديث، يمكنك التحقق مما إذا كانت الرسالة لا تزال في حالة قابلة للتحديث. بالإضافة إلى قراءة عمود **الحالة (Status)** في جدول الرسائل في لوحة التحكم ([**الحملات → رسائل لمرة واحدة (Campaigns → One-time messages)**](/ar/product/statistics-and-analytics/message-history/))، يمكنك الاستعلام عن الحالة برمجيًا باستخدام [`messages:list`](/ar/developer/api-reference/statistics-api/message-statistics-api/#messageslist):

- مرر `message_code` في مصفوفة `filters.messages_codes` (بجانب `filters.application` المطلوب).
- اقرأ حقل `status` للإدخال المطابق في `items[]`.

<Aside type="note">
`messages:list` هو جزء من Statistics API ويستخدم ترويسة مصادقة مختلفة عن هذه النقطة النهائية: `Authorization: Api <Server Key>`.
</Aside>

## مواضيع ذات صلة

<CardGrid>
  <LinkCard title="Notify" href="/developer/api-reference/messaging-api-v2/notify/" />
  <LinkCard title="Cancel" href="/developer/api-reference/messaging-api-v2/cancel/" />
  <LinkCard title="إحصائيات الرسائل" href="/developer/api-reference/statistics-api/message-statistics-api/#messageslist" />
  <LinkCard title="نظرة عامة على Messaging API v2" href="/developer/api-reference/messaging-api-v2/" />
  <LinkCard title="الترحيل من v1" href="/developer/api-reference/messaging-api-v2/migration-from-v1/" />
</CardGrid>