> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# إرسال مجدول

> إرسال أي رسالة في وقت لاحق، مرة أو على تكرار يومي أو أسبوعي أو شهري، وإدارة الجداول الزمنية من خلال / إرسال / جداول.

![نظرة عامة على جدولة الرسائل في GOWA](https://mintcdn.com/gowa-docs/G0gUpNl3gUGyehVX/images/GOWA-Message-Scheduler-Overview.png?fit=max\&auto=format\&n=G0gUpNl3gUGyehVX\&q=85\&s=663bfdbb9e1c0bb451c0fa782380b139)

يمكن جدولة أي طلب إرسال بدلاً من إرساله فوراً. إضافة `scheduled_at` و `timezone`؛ تقوم GOWA بتخزين الطلب ويقوم عامل خلفية بإرساله في ذلك الوقت. الجداول الزمنية تبقى على قيد الحياة لإعادة التشغيل وانتظر جهاز غير متصل.

أنواع الرسائل القابلة للجدول: النصوص، الصورة، الملف، الفيديو، الصوت، الملصق، جهة الاتصال، الرابط، الموقع، الاستطلاع والمرسل (`/message/{id}/forward`). لا يمكن جدولة الحضور والمؤشرات المكتوبة والنقطة النهائية التجريبية `/send/interactive`.

## جدولة الحقول

| الحقل | مطلوب | الوصف |
| - | - | - |
| `scheduled_at` | نعم | RFC 3339 مرة من أول إرسال في المستقبل، مثل `2026-11-01T09:00:00+07:00`. أول إرسال يحدث دائما في هذا الوقت. |
| `timezone` | نعم | منطقة زمنية وفق IANA (مثل `Asia/Jakarta`) تُستخدم لحساب التكرار، بحيث تظل عبارة "09:00 كل يوم" تعني الساعة 09:00 حتى مع تغيّر التوقيت الصيفي. |
| `recurrence` | لا | `once` (الافتراضي)، أو `daily`، أو `weekly`، أو `monthly`. |
| `weekdays` | أسبوعياً | أيام إرسال `0` = الأحد … `6` = السبت، على سبيل المثال `[1, 3, 5]`. |
| `day_of_month` | شهريا | من `1` إلى `31`؛ وتُضبط القيمة على آخر يوم في الشهر إذا كان الشهر أقصر. |
| `end_at` | لا | متكررة فقط. لا يتم الإرسال بعد هذا الوقت. |
| `occurrence_limit` | لا | التكرار فقط. توقف بعد إرسال العديد من هذه العناصر. |

بدون `scheduled_at`، يُرسل الطلب فورًا كالمعتاد.

## أمثلة

```bash theme={null}
# once, tomorrow morning
curl -u admin:changeme -X POST http://localhost:3000/send/message \
  -H "Content-Type: application/json" -H "X-Device-Id: my-device" \
  -d '{
    "phone": "628123456789",
    "message": "Reminder: meeting at 10:00",
    "scheduled_at": "2026-11-01T09:00:00+07:00",
    "timezone": "Asia/Jakarta"
  }'
```

```json theme={null}
{
  "code": "SUCCESS",
  "message": "Success",
  "results": {
    "schedule_id": "0b5c3a8e-7f5d-4d6f-9d1e-2f8c1a7b9e10",
    "scheduled_at": "2026-11-01T02:00:00Z",
    "next_run_at": "2026-11-01T02:00:00Z"
  }
}
```

الردود المجدولة لها `schedule_id` بدلا من `message_id`.

```bash theme={null}
# every Monday, Wednesday and Friday at 08:30, 12 times
curl -u admin:changeme -X POST http://localhost:3000/send/message \
  -H "Content-Type: application/json" -H "X-Device-Id: my-device" \
  -d '{
    "phone": "120363025246125486@g.us",
    "message": "Standup in 30 minutes",
    "scheduled_at": "2026-11-02T08:30:00+07:00",
    "timezone": "Asia/Jakarta",
    "recurrence": "weekly",
    "weekdays": [1, 3, 5],
    "occurrence_limit": 12
  }'
```

```bash theme={null}
# monthly invoice on the 1st, with an uploaded file (multipart: repeat weekdays as separate fields if used)
curl -u admin:changeme -X POST http://localhost:3000/send/file \
  -H "X-Device-Id: my-device" \
  -F phone=628123456789 \
  -F file=@invoice.pdf \
  -F scheduled_at=2026-12-01T09:00:00+07:00 \
  -F timezone=Asia/Jakarta \
  -F recurrence=monthly \
  -F day_of_month=1 \
  -F end_at=2027-12-31T23:59:59+07:00
```

تُحتفظ بالملفات المرفوعة على الخادم حتى انتهاء الجدول. في أجسام الطلبات متعددة الأجزاء، أرسل `weekdays` كحقول متكررة (`-F weekdays=1 -F weekdays=3`).

## إدارة الجداول الزمنية

الجداول تنتمي إلى جهاز؛ أرسل نفس `X-Device-Id`.

| اجراء | طلب |
| - | - |
| قائمة | `GET /send/schedules` مع `status`، `search` (المتلقي أو النص)، `message_type`، `limit`، `offset` اختيارياً\` |
| احصل على واحد | `GET /send/schedules/{schedule_id}` |
| إيقاف | `POST /send/schedules/{schedule_id}/pause` |
| استئناف | `POST /send/schedules/{schedule_id}/resume` |
| إلغاء | `POST /send/schedules/{schedule_id}/cancel` |

```bash theme={null}
curl -u admin:changeme -H "X-Device-Id: my-device" \
  "http://localhost:3000/send/schedules?status=active&limit=25"
```

ترجع القائمة `results.data` و`results.pagination` (`limit`، الافتراضي 25؛ `offset`؛ `total`).

### Statuses

| الحالة | المعنى |
| - | - |
| `active` | في انتظار تشغيله القادم. |
| `running` | طالب به العامل والمرسل |
| `paused` | استمر حتى استؤنف. |
| `completed` | لم يتبق أي جروح. |
| `failed` | وصول بعد إعادة المحاولة، أو الطلب المخزن غير صالح. |
| `cancelled` | ألغيت من قبلك. |

## سلوك التسليم

* ويقوم العامل بالتحقق من الجداول الزمنية الواجبة كل 5 ثوان.
* **الجهاز غير متصل أو غير مسجل الدخول:** التشغيل ينتظر و يعيد المحاولة كل 30 ثانية. الانتظار لا يعتبر محاولة فاشلة، لذا فإن الجدول ينجو من حالات انقطاع طويلة.
* **أخطاء الإرسال:** تُعاد المحاولة بفترات انتظار متزايدة تبدأ من 15 ثانية ولا تتجاوز 5 دقائق، بحد أقصى 10 محاولات لكل موعد تنفيذ. ينتقل الجدول المتكرر بعد ذلك إلى موعده التالي؛ أما الجدول الذي يُنفَّذ مرة واحدة فتتغير حالته إلى `failed`.
* **طلب غير صالح** (على سبيل المثال مستلم سيئ): فشل فورا دون إعادة المحاولة.
* **التشغيل المتأخر:** لم يتم إرسال الحدث المتأخر الماضي `end_at`.
* **الأعطال وإعادة التشغيل:** إيقاف التشغيل لا يؤدي إلى إجهاض إرسال بالفعل في الرحلة. قبل المحاولة الأولى، تحافظ GOWA على معرف رسالة WhatsApp للحدث. وبعد انتهاء مدة مطالبتها التي تبلغ دقيقتين، يتكرر حدوث توقف بذات الهوية ويحسب في ميزانية المحاولة. وتحتفظ استطلاعات الرأي أيضا بسرية التشفير عبر المحاولات. وهذا يحافظ على هوية الرسالة بعد إقرار غامض، ولكنه لا يضمن التسليم مرة واحدة تماما.
* **محاولات انقطاع قديمة:** محاولات الإرث التي لم تعرف نتيجتها تحتفظ باستعادة محافظة. يتخطى العامل هذا الحدث لجدول زمني متكرر أو يفشل جدولاً لمرة واحدة بدلاً من تعيينه هوية رسالة جديدة.

## أكثر من MCP

أداة MCP `whatsapp_send` تقبل نفس حقول الجدول، وقوائم `whatsapp_schedule` و تحصل على إيقاف مؤقت و تستأنف و تلغي الجداول. انظر [MCP server](https://gowa-docs.mintlify.site/ar/integrations/mcp.md).

> [!NOTE]
>
> تحقق من `GET /app/info`: `results.scheduled_sends` هو `true` عندما يقبل الخادم حقول الجدول ويكشف `/send/schedules`.


## Related topics

- [إيقاف إرسال مجدول](https://gowa-docs.mintlify.site/ar/api-reference/send/إيقاف-إرسال-مجدول.md)
- [إلغاء إرسال مجدول](https://gowa-docs.mintlify.site/ar/api-reference/send/إلغاء-إرسال-مجدول.md)
- [الحصول على إرسال مجدول](https://gowa-docs.mintlify.site/ar/api-reference/send/الحصول-على-إرسال-مجدول.md)
- [GOWA: واجهة WhatsApp REST API](https://gowa-docs.mintlify.site/ar/index.md)
- [اختيار الأجهزة المتعددة و الأجهزة](https://gowa-docs.mintlify.site/ar/concepts/multidevice.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.