الرسائل

أرسل الرسائل واقرأ حالتها.

كل ما ترسله يمر عبر نقطة واحدة هي POST /messages. تختار type، وتضع المحتوى تحت مفتاح بالاسم نفسه، ثم تتابع ما يحدث عبر أحداث message.*.

كيف يعمل: إرسال الرسائلنافذة الـ24 ساعة · النص · الوسائط · الأزرار والقوائم والروابط · الموقع وبطاقات الاتصال والتفاعلات · الردود وإشعارات القراءة والكتابة · ما يحدث بعد الإرسال · إنستغرام وماسنجر · أي رقم يُرسل

نافذة الـ24 ساعة#

يحدد واتساب ما يمكنك إرساله بقاعدة واحدة:

خلال 24 ساعة من آخر رسالة للعميل تكون المحادثة مفتوحة: أرسل أي نوع وبنص حر.
في غير ذلك لا يُسلَّم إلا قالب معتمد. أي نوع آخر يُرفض بالخطأ window_closed قبل أن يصل إلى واتساب، فلا تُحاسب أبدًا على رسالة لم يكن بالإمكان تسليمها.

إذا رد العميل على قالب تُفتح النافذة من جديد. ويخبرك GET /conversations/{id} متى تُغلق (reply_window_expires_at).

النص#

JSON

{ "to": "+966501234567", "type": "text", "text": { "body": "أهلًا سارة! طلبك جاهز 🎉", "preview_url": true } }

حتى 4096 حرفًا. يعرض preview_url معاينة لأول رابط في النص.

الوسائط#

الصور والفيديو والصوت والمستندات والملصقات تأتي من رابط https:// عام يحمّله واتساب، أو من ملف رفعته مرة واحدة عبر POST /media:

JSON

{ "to": "+966501234567", "type": "document", "document": { "media_id": "med_381", "filename": "invoice-10482.pdf", "caption": "فاتورتك" } }

النوع	الصيغ	الحد الأقصى	تعليق
`image`	JPEG وPNG	5 ميجابايت	نعم
`video`	MP4 و3GPP	16 ميجابايت	نعم
`audio`	AAC وMP4 وMPEG وAMR وOGG/Opus	16 ميجابايت	لا
`document`	أي ملف	100 ميجابايت	نعم، مع `filename`
`sticker`	WebP بمقاس 512×512	100 كيلوبايت (500 للمتحرك)	لا

يُفحص الملف المرفوع وفق هذه الحدود عند رفعه، فلا يصل ملف سيرفضه واتساب إلى مرحلة الإرسال أصلًا.

الأزرار والقوائم والروابط#

يجيب العميل عن رسائل interactive بلمسة. يعود اختياره إليك كحدث message.received من نوع interactive يحمل id الذي حددته، فاعتمد عليه في منطقك.

JSON

{
  "to": "+966501234567",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": "هل تؤكد موعدك غدًا الساعة 4 عصرًا؟",
    "buttons": [
      { "id": "confirm_10482", "title": "تأكيد" },
      { "id": "reschedule_10482", "title": "تغيير الموعد" }
    ]
  }
}

`interactive.type`	ما يراه العميل	الحدود
`button`	حتى 3 أزرار رد	العنوان 20 حرفًا، والمعرّف 256
`list`	زر يفتح حتى 10 خيارات موزعة على أقسام	10 صفوف إجمالًا، عنوان الصف 24 حرفًا والوصف 72
`cta_url`	زر واحد يفتح رابطًا	العنوان 20 حرفًا، و`https://` فقط
`location_request`	زر لمشاركة موقعه	النص فقط

كل الأنواع تأخذ body، وكلها عدا location_request تقبل footer وheader اختياريين (نصًا، أو في cta_url رابط صورة أو فيديو أو مستند).

الموقع وبطاقات الاتصال والتفاعلات#

location: القيمتان latitude وlongitude، واختياريًا name وaddress.
contacts: قائمة بطاقات، تحتاج كل منها إلى name.formatted_name، والرقم الذي يحمل wa_id يُظهر زر "مراسلة".
reaction: القيمة {"message_id": "imsg_…", "emoji": "👍"} تتفاعل مع رسالة، وemoji الفارغ يزيل التفاعل. التفاعلات مجانية ولا تُحتسب كرسائل.

الردود وإشعارات القراءة والكتابة#

أرسل reply_to (معرّف msg_… أو imsg_… أو معرّف واتساب) لتقتبس رسالة العميل في ردك.
يُظهر POST /messages/{id}/read للعميل علامتي القراءة الزرقاوين. أضف "typing_indicator": true لتظهر له عبارة "يكتب…" بينما تجهّز الرد (حتى 25 ثانية أو حتى ترد).

ما يحدث بعد الإرسال#

تعود الاستجابة فور قبول واتساب للرسالة بحالة status: accepted، ثم تتوالى الأحداث:

الحدث	المعنى
`message.sent`	أرسلها واتساب
`message.delivered`	وصلت إلى هاتف العميل
`message.read`	فتحها العميل (إن كان يشارك إشعارات القراءة)
`message.failed`	تعذّر تسليمها، ويوضح `error.code` سبب واتساب

ضع معرّفك الخاص في reference (رقم طلب أو رقم تذكرة): يعود في الاستجابة وفي كل حدث، فلا تحتاج إلى جدول ربط.

النقطة نفسها ترد على إنستغرام وماسنجر: حدّد channel وأرسل to بمعرّف العميل من حقل from في رسالته. تقبل هاتان القناتان النص والصورة والفيديو والصوت والمستند، خلال 24 ساعة من آخر رسالة للعميل فقط، ولا قوالب فيهما: بعد إغلاق النافذة لا يمكنك الكتابة إلا بعد أن يكتب العميل.

JSON

{ "channel": "instagram", "to": "17841400000000000", "type": "text", "text": { "body": "شكرًا لتواصلك! المقاس متوفر ✨" } }

أي رقم يُرسل#

إن لم ترسل from تخرج الرسالة من الرقم الذي راسله العميل آخر مرة، وإلا من رقمك الافتراضي. للاختيار أرسل from بمعرّف رقم من GET /numbers، الذي يوضح أيضًا هل يستطيع كل رقم الإرسال الآن.

نقاط الواجهة

getعرض الرسائل المرسلة عبر الواجهة/messages
postإرسال رسالة/messages
getجلب رسالة/messages/{id}
postتعليم رسالة العميل كمقروءة/messages/{id}/read

عرض الرسائل المرسلة عبر الواجهة

gethttps://api.saei.automize.sa/v1/messages

الصلاحية: messages:read
يعمل في وضع الاختبار

الأحدث أولًا. مفاتيح التشغيل تعرض الرسائل المرسلة عبر الواجهة، ومفاتيح الاختبار تعرض رسائل وضع الاختبار (المرسلة والواردة المحاكاة).

معاملات الاستعلام

limitintegerاختياري
عدد العناصر المطلوبة، من 1 إلى 100.
cursorstringاختياري
قيمة next_cursor من الصفحة السابقة.
referencestringاختياري
فقط الرسائل التي أرسلتها بهذا reference.
tostringاختياري
فقط الرسائل المرسلة إلى هذا الرقم (E.164).

حقول الاستجابة200· صفحة من الرسائل.

object"list"مطلوب
dataarray<Message>مطلوب
الحقول الفرعية (28)
- idstringمطلوب
  معرّف فريد. عامله كنص معتم وخزّنه كنص حتى 64 حرفًا.
- object"message"مطلوب
- livemodebooleanمطلوب
- directionstringمطلوب
  outbound للرسائل التي ترسلها، وinbound لرسائل العملاء.
  إحدى القيمoutboundinbound
- channelstringمطلوب
  إحدى القيمwhatsappinstagrammessenger
- fromstring | nullاختياري
  المُرسِل، بصيغة E.164 في واتساب.
- tostring | nullاختياري
  المُستلِم، بصيغة E.164 في واتساب.
- typestringمطلوب
  نوع محتوى الرسالة.
- textobjectاختياري
  الحقول الفرعية (1)
  bodystringاختياري
- templateobjectاختياري
  الحقول الفرعية (4)
  namestringاختياري
  languagestringاختياري
  variablesobjectاختياري
  bodystringاختياري
- imageobjectاختياري
  رسائل الوسائط تحمل link (أو media_id) وcaption وfilename وmime_type عند توفرها.
- videoobjectاختياري
- audioobjectاختياري
- documentobjectاختياري
- stickerobjectاختياري
- locationobjectاختياري
- contactsarrayاختياري
- interactiveobjectاختياري
  ما أرسلته (type وbody وbuttons…)، أو عند ضغط العميل: reply: {id, title}.
- reactionobjectاختياري
- statusstringمطلوب
  accepted ← sent ← delivered ← read، أو failed. رسائل العملاء حالتها received. تصلك تغيّرات الحالة كأحداث ويب هوك.
  إحدى القيمacceptedsentdeliveredreadfailedreceived
- errorobject | nullاختياري
  سبب فشل التسليم، عندما تكون status هي failed.
  الحقول الفرعية (3)
  codestring | nullاختياري
  titlestring | nullاختياري
  messagestring | nullاختياري
- referencestring | nullاختياري
  مرجعك الخاص، يُعاد كما أرسلته في طلب الإرسال وفي كل حدث.
- conversation_idstring | nullاختياري
- provider_message_idstring | nullاختياري
  معرّف الرسالة لدى واتساب (wamid).
- contactobject | nullاختياري
  الحقول الفرعية (1)
  namestring | nullاختياري
- contextobject | nullاختياري
  في الرد، الرسالة التي يُرَد عليها.
  الحقول الفرعية (1)
  provider_message_idstringاختياري
- created_atstring | nullمطلوب
- updated_atstring | nullاختياري
has_morebooleanمطلوب
next_cursorstring | nullمطلوب

الأخطاء المحتملة2

422parameter_invalidحقل غير صالح
429rate_limitedطلبات كثيرة

جرّبها

curl -X GET https://api.saei.automize.sa/v1/messages \
  -H "Authorization: Bearer $API_KEY"

الاستجابة

صفحة من الرسائل.

{
  "object": "list",
  "data": [
    {
      "id": "msg_48213",
      "object": "message",
      "livemode": false,
      "direction": "outbound",
      "channel": "whatsapp",
      "from": "+966112345678",
      "to": "+966501234567",
      "type": "text",
      "text": {
        "body": "string"
      },
      "template": {
        "name": "string",
        "language": "string",
        "variables": {},
        "body": "string"
      },
      "image": {},
      "video": {},
      "audio": {},
      "document": {},
      "sticker": {},
      "location": {},
      "contacts": [],
      "interactive": {},
      "reaction": {},
      "status": "accepted",
      "error": {
        "code": "string",
        "title": "string",
        "message": "string"
      },
      "reference": "string",
      "conversation_id": "string",
      "provider_message_id": "string",
      "contact": {
        "name": "string"
      },
      "context": {
        "provider_message_id": "string"
      },
      "created_at": "2026-10-01T09:30:00Z",
      "updated_at": "2026-10-01T09:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "string"
}

إرسال رسالة

posthttps://api.saei.automize.sa/v1/messages

الصلاحية: messages:send
محاكاة في وضع الاختبار
يقبل Idempotency-Key

نقطة واحدة لكل أنواع الرسائل: حدّد type وضع المحتوى تحت مفتاح بنفس الاسم: text أو template أو image أو video أو audio أو document أو sticker أو location أو contacts أو interactive (أزرار رد، قوائم، أزرار روابط، طلب موقع) أو reaction.

خلال 24 ساعة من آخر رسالة أرسلها العميل يمكنك إرسال أي نوع.
خارج هذه النافذة (أو لبدء محادثة) لا يُسلَّم إلا template معتمد. أي نوع آخر يُرجع window_closed.
إنستغرام وماسنجر (channel) للردود فقط: نص ووسائط خلال الـ24 ساعة.

تصلك الاستجابة فور قبول القناة للرسالة (status: accepted). أما تحديثات التسليم والقراءة فتصلك كأحداث ويب هوك message.*. مع مفتاح اختبار تكون الرسالة محاكاة ولا تصل إلى واتساب أبدًا.

الترويسات

Idempotency-Keystringاختياري
أي نص فريد (يُفضّل UUID). إعادة الطلب بنفس المفتاح ونفس الجسم تُرجع الاستجابة الأولى بدل التنفيذ مرتين. يُحفظ لمدة 24 ساعة.

جسم الطلب

نوع الرسالة

على هاتف العميلشكل تقريبي

نشاطك التجاريحساب أعمال

اليوم

أهلًا سارة! طلبك جاهز للاستلام 🎉

9:41

ثم تصلك أحداث الويب هوك هذه

أُرسلتmessage.sent
وصلتmessage.delivered
قُرئتmessage.read

رسالة نصية عادية. فقط خلال نافذة الـ24 ساعة بعد آخر رسالة للعميل.

channelstringاختياري
القناة المرسَل عبرها. إنستغرام وماسنجر للردود فقط (نص، صورة، فيديو، صوت، مستند) خلال 24 ساعة من آخر رسالة للعميل، ويكون to حينها معرّف العميل من حقل from في رسالته.
إحدى القيمwhatsappinstagrammessenger
tostringمطلوب
رقم هاتف العميل بصيغة E.164، مثل +966501234567. في إنستغرام وماسنجر معرّف العميل من رسالته.
fromstringاختياري
أي أرقامك يرسلها: معرّف رقم (num_…) أو الرقم بصيغة E.164. الافتراضي: الرقم الذي راسله العميل آخر مرة، وإلا رقمك الافتراضي.
reply_tostringاختياري
أرسلها ردًّا على هذه الرسالة (معرّف msg_… أو imsg_… أو wamid من واتساب).
referencestringاختياري
معرّفك الخاص لهذه الرسالة (رقم طلب، رقم تذكرة). يُعاد في الاستجابة وفي كل حدث ويب هوك يخصها.
type"text"مطلوب
textobjectمطلوب
الحقول الفرعية (2)
- bodystringمطلوب
  نص الرسالة. حتى 4096 حرفًا، والعربية والرموز التعبيرية مدعومة.
- preview_urlbooleanاختياري
  اعرض معاينة لأول رابط في النص.

قالب واتساب معتمد. الطريقة الوحيدة لبدء محادثة أو المراسلة بعد نافذة الـ24 ساعة.

channelstringاختياري
القناة المرسَل عبرها. إنستغرام وماسنجر للردود فقط (نص، صورة، فيديو، صوت، مستند) خلال 24 ساعة من آخر رسالة للعميل، ويكون to حينها معرّف العميل من حقل from في رسالته.
إحدى القيمwhatsappinstagrammessenger
tostringمطلوب
رقم هاتف العميل بصيغة E.164، مثل +966501234567. في إنستغرام وماسنجر معرّف العميل من رسالته.
fromstringاختياري
أي أرقامك يرسلها: معرّف رقم (num_…) أو الرقم بصيغة E.164. الافتراضي: الرقم الذي راسله العميل آخر مرة، وإلا رقمك الافتراضي.
reply_tostringاختياري
أرسلها ردًّا على هذه الرسالة (معرّف msg_… أو imsg_… أو wamid من واتساب).
referencestringاختياري
معرّفك الخاص لهذه الرسالة (رقم طلب، رقم تذكرة). يُعاد في الاستجابة وفي كل حدث ويب هوك يخصها.
type"template"مطلوب
templateobjectمطلوب
الحقول الفرعية (4)
- namestringاختياري
  اسم القالب كما اعتمده واتساب.
- languagestringاختياري
  رمز اللغة مثل ar أو en_US. مطلوب إذا كان الاسم موجودًا بأكثر من لغة.
- idstringاختياري
  معرّف القالب (tpl_…) بدلًا من الاسم واللغة.
- variablesobjectاختياري
  قيم المتغيرات: body (بالترتيب: {{1}}، {{2}}…)، وheader_text، وheader_media_link، وbuttons حسب ترتيب الزر (url_suffix، coupon_code، payload).
  الحقول الفرعية (4)
  bodyarray<string>اختياري
  header_textstringاختياري
  header_media_linkstringاختياري
  buttonsobjectاختياري
consent_confirmedbooleanاختياري
يجب أن تكون true لإرسال قالب غير قوالب التحقق إلى جهة اتصال لم توافق على استقبال رسائل الأعمال. تُسجَّل كل موافقة في سجل التدقيق.

بطاقة اتصال أو أكثر يحفظها العميل بلمسة واحدة.

channelstringاختياري
القناة المرسَل عبرها. إنستغرام وماسنجر للردود فقط (نص، صورة، فيديو، صوت، مستند) خلال 24 ساعة من آخر رسالة للعميل، ويكون to حينها معرّف العميل من حقل from في رسالته.
إحدى القيمwhatsappinstagrammessenger
tostringمطلوب
رقم هاتف العميل بصيغة E.164، مثل +966501234567. في إنستغرام وماسنجر معرّف العميل من رسالته.
fromstringاختياري
أي أرقامك يرسلها: معرّف رقم (num_…) أو الرقم بصيغة E.164. الافتراضي: الرقم الذي راسله العميل آخر مرة، وإلا رقمك الافتراضي.
reply_tostringاختياري
أرسلها ردًّا على هذه الرسالة (معرّف msg_… أو imsg_… أو wamid من واتساب).
referencestringاختياري
معرّفك الخاص لهذه الرسالة (رقم طلب، رقم تذكرة). يُعاد في الاستجابة وفي كل حدث ويب هوك يخصها.
type"contacts"مطلوب
contactsarray<object>مطلوب
الحقول الفرعية (6)
- nameobjectمطلوب
  الحقول الفرعية (3)
  formatted_namestringمطلوب
  first_namestringاختياري
  last_namestringاختياري
- phonesarray<object>اختياري
  الحقول الفرعية (3)
  phonestringمطلوب
  typestringاختياري
  إحدى القيمCELLMAINIPHONEHOMEWORK
  wa_idstringاختياري
  معرّف الرقم في واتساب (أرقام فقط). يضيف زر "مراسلة" إلى البطاقة.
- emailsarray<object>اختياري
  الحقول الفرعية (2)
  emailstringمطلوب
  typestringاختياري
  إحدى القيمHOMEWORK
- orgobjectاختياري
  الحقول الفرعية (3)
  companystringاختياري
  departmentstringاختياري
  titlestringاختياري
- urlsarray<object>اختياري
  الحقول الفرعية (2)
  urlstringمطلوب
  typestringاختياري
  إحدى القيمHOMEWORK
- birthdaystringاختياري

رسائل يجيب عنها العميل بلمسة: حتى 3 أزرار رد button، أو قائمة list حتى 10 خيارات، أو زر رابط cta_url، أو طلب موقع location_request. تصلك كل لمسة كحدث message.received من نوع interactive يحمل id الذي اخترته.

channelstringاختياري
القناة المرسَل عبرها. إنستغرام وماسنجر للردود فقط (نص، صورة، فيديو، صوت، مستند) خلال 24 ساعة من آخر رسالة للعميل، ويكون to حينها معرّف العميل من حقل from في رسالته.
إحدى القيمwhatsappinstagrammessenger
tostringمطلوب
رقم هاتف العميل بصيغة E.164، مثل +966501234567. في إنستغرام وماسنجر معرّف العميل من رسالته.
fromstringاختياري
أي أرقامك يرسلها: معرّف رقم (num_…) أو الرقم بصيغة E.164. الافتراضي: الرقم الذي راسله العميل آخر مرة، وإلا رقمك الافتراضي.
reply_tostringاختياري
أرسلها ردًّا على هذه الرسالة (معرّف msg_… أو imsg_… أو wamid من واتساب).
referencestringاختياري
معرّفك الخاص لهذه الرسالة (رقم طلب، رقم تذكرة). يُعاد في الاستجابة وفي كل حدث ويب هوك يخصها.
type"interactive"مطلوب
interactiveobjectمطلوب
الحقول الفرعية (9)
- typestringمطلوب
  إحدى القيمbuttonlistcta_urllocation_request
- headerobjectاختياري
  اختياري. أزرار الرد والقوائم تقبل ترويسة text، وزر الرابط يقبل أيضًا image أو video أو document من link.
  الحقول الفرعية (3)
  typestringمطلوب
  إحدى القيمtextimagevideodocument
  textstringاختياري
  linkstringاختياري
- bodystringمطلوب
  نص الرسالة. حتى 1024 حرفًا (4096 للقائمة).
- footerstringاختياري
- buttonsarray<object>اختياري
  لنوع button: من 1 إلى 3 أزرار. يعود إليك id (حتى 256 حرفًا) عند الضغط، وtitle (حتى 20 حرفًا) هو ما يراه العميل.
  الحقول الفرعية (2)
  idstringمطلوب
  titlestringمطلوب
- buttonstringاختياري
  لنوع list: عنوان الزر الذي يفتح القائمة.
- sectionsarray<object>اختياري
  لنوع list: من 1 إلى 10 أقسام، و10 صفوف كحد أقصى إجمالًا. عند وجود أكثر من قسم يحتاج كل قسم إلى title.
  الحقول الفرعية (2)
  titlestringاختياري
  rowsarray<object>مطلوب
  الحقول الفرعية (3)
  idstringمطلوب
  titlestringمطلوب
  descriptionstringاختياري
- display_textstringاختياري
  لنوع cta_url: عنوان الزر.
- urlstringاختياري
  لنوع cta_url: صفحة https:// التي يفتحها الزر.

حقول الاستجابة202· قبلها واتساب (أو المحاكي في وضع الاختبار).

idstringمطلوب
معرّف فريد. عامله كنص معتم وخزّنه كنص حتى 64 حرفًا.
object"message"مطلوب
livemodebooleanمطلوب
directionstringمطلوب
outbound للرسائل التي ترسلها، وinbound لرسائل العملاء.
إحدى القيمoutboundinbound
channelstringمطلوب
إحدى القيمwhatsappinstagrammessenger
fromstring | nullاختياري
المُرسِل، بصيغة E.164 في واتساب.
tostring | nullاختياري
المُستلِم، بصيغة E.164 في واتساب.
typestringمطلوب
نوع محتوى الرسالة.
textobjectاختياري
الحقول الفرعية (1)
- bodystringاختياري
templateobjectاختياري
الحقول الفرعية (4)
- namestringاختياري
- languagestringاختياري
- variablesobjectاختياري
- bodystringاختياري
imageobjectاختياري
رسائل الوسائط تحمل link (أو media_id) وcaption وfilename وmime_type عند توفرها.
videoobjectاختياري
audioobjectاختياري
documentobjectاختياري
stickerobjectاختياري
locationobjectاختياري
contactsarrayاختياري
interactiveobjectاختياري
ما أرسلته (type وbody وbuttons…)، أو عند ضغط العميل: reply: {id, title}.
reactionobjectاختياري
statusstringمطلوب
accepted ← sent ← delivered ← read، أو failed. رسائل العملاء حالتها received. تصلك تغيّرات الحالة كأحداث ويب هوك.
إحدى القيمacceptedsentdeliveredreadfailedreceived
errorobject | nullاختياري
سبب فشل التسليم، عندما تكون status هي failed.
الحقول الفرعية (3)
- codestring | nullاختياري
- titlestring | nullاختياري
- messagestring | nullاختياري
referencestring | nullاختياري
مرجعك الخاص، يُعاد كما أرسلته في طلب الإرسال وفي كل حدث.
conversation_idstring | nullاختياري
provider_message_idstring | nullاختياري
معرّف الرسالة لدى واتساب (wamid).
contactobject | nullاختياري
الحقول الفرعية (1)
- namestring | nullاختياري
contextobject | nullاختياري
في الرد، الرسالة التي يُرَد عليها.
الحقول الفرعية (1)
- provider_message_idstringاختياري
created_atstring | nullمطلوب
updated_atstring | nullاختياري

الأخطاء المحتملة21

402subscription_inactiveالاشتراك غير نشط
402quota_exceededنفد الرصيد المتاح
403api_access_not_in_planالواجهة غير مشمولة في الباقة
403test_mode_unsupportedغير متاح في وضع الاختبار
422parameter_missingحقل مفقود
422parameter_invalidحقل غير صالح
404resource_missingغير موجود
422idempotency_key_reusedتكرار Idempotency-Key
409idempotency_in_progressالطلب نفسه ما زال قيد التنفيذ
422window_closedنافذة الـ24 ساعة مغلقة
422template_not_foundالقالب غير موجود
422template_not_approvedالقالب غير معتمد
422template_variables_mismatchمتغيرات القالب غير مطابقة
409recipient_not_consentedالمستلِم لم يوافق
422sender_not_configuredلا يوجد رقم مُرسِل
422sender_not_sendableالرقم لا يستطيع الإرسال
422channel_errorرفض واتساب الرسالة
409send_outcome_unknownربما أُرسلت المحاولة السابقة
422channel_not_connectedالقناة غير متصلة
429rate_limitedطلبات كثيرة
503platform_pausedالإرسال متوقف مؤقتًا

جرّبها

مثال

curl -X POST https://api.saei.automize.sa/v1/messages \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+966501234567",
  "type": "text",
  "text": {
    "body": "أهلًا سارة! طلبك جاهز للاستلام 🎉"
  },
  "reference": "order-10482"
}'

الاستجابة

قبلها واتساب (أو المحاكي في وضع الاختبار).

{
  "id": "msg_48213",
  "object": "message",
  "livemode": true,
  "direction": "outbound",
  "channel": "whatsapp",
  "from": "+966112345678",
  "to": "+966501234567",
  "type": "text",
  "text": {
    "body": "أهلًا سارة! طلبك جاهز للاستلام 🎉"
  },
  "status": "accepted",
  "error": null,
  "reference": "order-10482",
  "conversation_id": "conv_311",
  "provider_message_id": "wamid.HBgMOTY2NTAxMjM0NTY3FQIAERgSMEM4",
  "created_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z"
}

جلب رسالة

gethttps://api.saei.automize.sa/v1/messages/{id}

الصلاحية: messages:read
يعمل في وضع الاختبار

الرسالة وحالتها الحالية. يعمل مع الرسائل التي أرسلتها (msg_…) ورسائل العملاء الواردة في أحداث الويب هوك (imsg_…).

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

idstringمطلوب
معرّف العنصر.

حقول الاستجابة200· الرسالة.

idstringمطلوب
معرّف فريد. عامله كنص معتم وخزّنه كنص حتى 64 حرفًا.
object"message"مطلوب
livemodebooleanمطلوب
directionstringمطلوب
outbound للرسائل التي ترسلها، وinbound لرسائل العملاء.
إحدى القيمoutboundinbound
channelstringمطلوب
إحدى القيمwhatsappinstagrammessenger
fromstring | nullاختياري
المُرسِل، بصيغة E.164 في واتساب.
tostring | nullاختياري
المُستلِم، بصيغة E.164 في واتساب.
typestringمطلوب
نوع محتوى الرسالة.
textobjectاختياري
الحقول الفرعية (1)
- bodystringاختياري
templateobjectاختياري
الحقول الفرعية (4)
- namestringاختياري
- languagestringاختياري
- variablesobjectاختياري
- bodystringاختياري
imageobjectاختياري
رسائل الوسائط تحمل link (أو media_id) وcaption وfilename وmime_type عند توفرها.
videoobjectاختياري
audioobjectاختياري
documentobjectاختياري
stickerobjectاختياري
locationobjectاختياري
contactsarrayاختياري
interactiveobjectاختياري
ما أرسلته (type وbody وbuttons…)، أو عند ضغط العميل: reply: {id, title}.
reactionobjectاختياري
statusstringمطلوب
accepted ← sent ← delivered ← read، أو failed. رسائل العملاء حالتها received. تصلك تغيّرات الحالة كأحداث ويب هوك.
إحدى القيمacceptedsentdeliveredreadfailedreceived
errorobject | nullاختياري
سبب فشل التسليم، عندما تكون status هي failed.
الحقول الفرعية (3)
- codestring | nullاختياري
- titlestring | nullاختياري
- messagestring | nullاختياري
referencestring | nullاختياري
مرجعك الخاص، يُعاد كما أرسلته في طلب الإرسال وفي كل حدث.
conversation_idstring | nullاختياري
provider_message_idstring | nullاختياري
معرّف الرسالة لدى واتساب (wamid).
contactobject | nullاختياري
الحقول الفرعية (1)
- namestring | nullاختياري
contextobject | nullاختياري
في الرد، الرسالة التي يُرَد عليها.
الحقول الفرعية (1)
- provider_message_idstringاختياري
created_atstring | nullمطلوب
updated_atstring | nullاختياري

الأخطاء المحتملة2

404resource_missingغير موجود
429rate_limitedطلبات كثيرة

جرّبها

curl -X GET https://api.saei.automize.sa/v1/messages/msg_48213 \
  -H "Authorization: Bearer $API_KEY"

الاستجابة

الرسالة.

{
  "id": "msg_48213",
  "object": "message",
  "livemode": false,
  "direction": "outbound",
  "channel": "whatsapp",
  "from": "+966112345678",
  "to": "+966501234567",
  "type": "text",
  "text": {
    "body": "string"
  },
  "template": {
    "name": "string",
    "language": "string",
    "variables": {},
    "body": "string"
  },
  "image": {},
  "video": {},
  "audio": {},
  "document": {},
  "sticker": {},
  "location": {},
  "contacts": [],
  "interactive": {},
  "reaction": {},
  "status": "accepted",
  "error": {
    "code": "string",
    "title": "string",
    "message": "string"
  },
  "reference": "string",
  "conversation_id": "string",
  "provider_message_id": "string",
  "contact": {
    "name": "string"
  },
  "context": {
    "provider_message_id": "string"
  },
  "created_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z"
}

تعليم رسالة العميل كمقروءة

posthttps://api.saei.automize.sa/v1/messages/{id}/read

الصلاحية: messages:send
محاكاة في وضع الاختبار

تظهر للعميل علامتا القراءة الزرقاوان على رسالته (وعلى كل ما أرسله قبلها). أضف typing_indicator: true لتظهر له أيضًا عبارة "يكتب…" بينما تجهّز الرد، وتستمر حتى 25 ثانية أو حتى ترد.

تعمل على رسائل واتساب التي استقبلتها (imsg_… من أحداث message.received).

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

idstringمطلوب
معرّف العنصر.

جسم الطلب

typing_indicatorbooleanاختياري
أظهر للعميل أيضًا "يكتب…".

حقول الاستجابة200· يرى العميل الآن رسالته مقروءة.

object"read_receipt"مطلوب
message_idstringمطلوب
livemodebooleanمطلوب
typing_indicatorbooleanاختياري

الأخطاء المحتملة4

404resource_missingغير موجود
422sender_not_configuredلا يوجد رقم مُرسِل
422channel_errorرفض واتساب الرسالة
429rate_limitedطلبات كثيرة

جرّبها

curl -X POST https://api.saei.automize.sa/v1/messages/msg_48213/read \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "typing_indicator": true
}'

الاستجابة

يرى العميل الآن رسالته مقروءة.

{
  "object": "read_receipt",
  "message_id": "imsg_88213",
  "livemode": true,
  "typing_indicator": true
}

نافذة الـ24 ساعة#

النص#

الوسائط#

الأزرار والقوائم والروابط#

الموقع وبطاقات الاتصال والتفاعلات#

الردود وإشعارات القراءة والكتابة#

ما يحدث بعد الإرسال#

إنستغرام وماسنجر#

أي رقم يُرسل#

نقاط الواجهة

عرض الرسائل المرسلة عبر الواجهة#

معاملات الاستعلام

إرسال رسالة#

الترويسات

جسم الطلب

جلب رسالة#

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

تعليم رسالة العميل كمقروءة#

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

جسم الطلب

عرض الرسائل المرسلة عبر الواجهة

إرسال رسالة

جلب رسالة

تعليم رسالة العميل كمقروءة