الرسائل

أرسل نصوصًا وصورًا ومستندات وملفات صوتية، واعرض سجل رسائل الجهاز.

إرسال رسالة

POST /v1/devices/{id}/messages

{id} هو الجهاز الذي يرسل الرسالة، ويجب أن يكون connected.

حقل المحتوى	مطلوب	المعنى
`to`	نعم	رقم المستلم مع رمز الدولة، أرقامًا فقط: `9665XXXXXXXX` (بدون `+` أو مسافات أو صفر في البداية).
`type`	نعم	`text` أو `image` أو `document` أو `audio`.
`text`	لـ `text`	نص الرسالة.
`media_url`	لـ `image` و`document` و`audio`	رابط عام `http` أو `https` للملف. ننزّله مرة واحدة عند الإرسال.
`caption`	لا	نص يظهر تحت الصورة أو المستند.

curl -X POST https://api.wa.goupdev.net/v1/devices/7/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "9665XXXXXXXX", "type": "text", "text": "تم شحن طلبك."}'

الرد 201:

{ "id": 1042, "status": "queued" }

queued تعني أننا قبلنا الرسالة. تُرسل رسائل الجهاز الواحد واحدة تلو الأخرى بفارق بضع ثوانٍ، لذا تأخذ القائمة الطويلة وقتًا. لمتابعة رسالة احتفظ بـ id: يصل إلى الويب هوك الحدث message.status_changed عندما تصل وعندما تُقرأ.

الملفات

الصور: حتى 5 ميغابايت. المستندات والصوت: حتى 16 ميغابايت.
يجب أن يكون الرابط متاحًا من الإنترنت. نرفض روابط الشبكات الخاصة (مثل localhost أو 192.168.x.x).

الأخطاء

الخطأ	السبب
`400 {"error": "to and type are required"}`	الحقل `to` أو `type` مفقود.
`400 {"error": "text is required for type=text"}`	رسالة نصية بدون `text`.
`400 {"error": "media_url is required for media types"}`	رسالة ملف بدون `media_url`.
`400 {"error": "Unsupported type: video"}`	قيمة `type` ليست أحد الأنواع الأربعة.
`400 {"error": "Failed to download media: 404"}`	تعذّر تنزيل الملف (النص يوضح السبب).
`402 {"error": "No active Subscription"}`	لا يوجد اشتراك فعّال لمؤسستك.
`404 {"error": "Device not found"}`	لا يوجد جهاز بهذا المعرّف في مؤسستك.
`409 {"error": "Device is not connected"}`	الجهاز ليس `connected`. اربطه من جديد.
`413 {"error": "Media exceeds 5242880 byte limit for type image"}`	الملف أكبر من المسموح.
`429 {"error": "Monthly Message Quota reached"}`	انتهى حد الرسائل الشهري في باقتك.
`429 {"error": "Rate limit exceeded (hourly cap: 60)"}`	بلغ الجهاز أحد حدود الإرسال. حاول لاحقًا.

كلا ردَّي 429 يعني "ليس الآن" لسببين مختلفين، فميّز بينهما بنص error.

عرض رسائل جهاز

GET /v1/devices/{id}/messages?limit=50

limit من 1 إلى 200 (الافتراضي 50). الرد 200: الرسائل التي أرسلها الجهاز، الأحدث أولًا. الرسائل الواردة لا تُحفظ، وتصلك فقط عبر الويب هوك (message.received).

[
  {
    "id": 1042,
    "direction": "out",
    "to_number": "9665XXXXXXXX",
    "from_number": null,
    "type": "text",
    "content": "تم شحن طلبك.",
    "status": "read",
    "error": null,
    "created_at": "2026-10-08T09:40:00.000Z"
  }
]

الحقل	المعنى
`direction`	`out` (أرسلها الجهاز).
`status`	`queued` أو `sent` أو `delivered` أو `read` أو `failed`. راجع الحالات.
`content`	النص، أو رابط الملف للملفات التي أرسلتها.
`error`	سبب الفشل، للرسائل `failed`.

إرسال رسالةنسخ رابط العنوان

الملفاتنسخ رابط العنوان

الأخطاءنسخ رابط العنوان

عرض رسائل جهازنسخ رابط العنوان

في هذه الصفحة

إرسال رسالة

الملفات

الأخطاء

عرض رسائل جهاز