> ## 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.

# تلقي الرسائل

> عالج الرسائل الواردة باستخدام webhooks، أو اقرأ المحادثات والرسائل المحفوظة من مخزن المحادثات في GOWA.

يوفر GOWA طريقتين لاستقبال الرسائل:

| الطريقة | استخدمه لـ |
| - | - |
| **Webhooks** (مستحسن) | رد الفعل للأحداث في الوقت الحقيقي. تقوم GOWA بدفع كل حدث إلى عنوان URL الخاص بك. |
| **وحدة تخزين الدردشة API** | قراءة التاريخ، اللحاق بعد التعطل، بناء مشاهدة صندوق الوارد. |

## الوب

بدء تشغيل GOWA مع رابط ويب هوك وسرّ:

```bash theme={null}
./whatsapp rest --basic-auth=admin:changeme \
  --webhook=https://example.com/wa-hook \
  --webhook-secret=change-me \
  --webhook-events=message,message.ack
```

تصل رسالة نصية كما يلي:

```json theme={null}
{
  "event": "message",
  "device_id": "628123456789@s.whatsapp.net",
  "session_id": "my-device",
  "payload": {
    "id": "3EB0C127D7BACC83D6A1",
    "chat_id": "628987654321@s.whatsapp.net",
    "from": "628987654321@s.whatsapp.net",
    "from_name": "John Doe",
    "sender_display_name": "John Doe",
    "timestamp": "2026-10-15T10:30:00Z",
    "is_from_me": false,
    "body": "Hello, how are you?"
  }
}
```

في المجموعة، `chat_id` هي مجموعة JID (`...@g.us`) و `from` هو العضو الذي أرسلها.

### مثال: بوت الرد التلقائي

التحقق من التوقيع، الاعتراف، ثم الرد من خلال API بنفس الجهاز:

```javascript theme={null}
const express = require("express");
const crypto = require("crypto");

const GOWA = "http://localhost:3000";
const AUTH = "Basic " + Buffer.from("admin:changeme").toString("base64");
const SECRET = "change-me";

const app = express();
app.post("/wa-hook", express.raw({ type: "application/json" }), async (req, res) => {
  const sig = crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const received = req.get("X-Hub-Signature-256") || "";
  const expected = `sha256=${sig}`;
  if (!/^sha256=[0-9a-f]{64}$/.test(received) ||
      received.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const evt = JSON.parse(req.body);
  res.sendStatus(200);
  if (evt.event !== "message" || evt.payload.is_from_me) return;
  if (!evt.session_id) return;
  if (!/^hi\b/i.test(evt.payload.body || "")) return;

  const response = await fetch(`${GOWA}/send/message`, {
    method: "POST",
    headers: {
      Authorization: AUTH,
      "Content-Type": "application/json",
      "X-Device-Id": evt.session_id,          // reply from the slot that received it
    },
    body: JSON.stringify({
      phone: evt.payload.chat_id,
      message: "Hello! How can we help?",
      reply_message_id: evt.payload.id,
    }),
  });
  if (!response.ok) console.error("GOWA reply failed", response.status);
});
app.listen(8080);
```

ويعترف هذا المثال الأدنى قبل إرسال الرد. للإنتاج ، قم بإنتظار الحدث الذي تم التحقق منه بشكل دائم قبل الاعتراف به ، وإزالة التكرار بواسطة الجهاز والدردشة ومعرّف الرسالة ، وفشل إعادة المحاولة في إرسال العامل الخاص بك. تخطي الأحداث بدون `session_id` أو حل الجهاز الصحيح صراحة.

لإرسال رد ثابت على كل رسالة، يتيح `WHATSAPP_AUTO_REPLY="We'll get back to you soon"` ذلك دون كتابة أي شيفرة.

راجع [خطافات الويب](https://gowa-docs.mintlify.site/ar/concepts/webhooks.md) للاطلاع على جميع أنواع الأحداث وحقول الوسائط وإعادات المحاولة وعناوين URL الخاصة بكل جهاز.

### التعامل مع أشكال الأحداث الجديدة

ترويسة الألبوم هي حدث `message` يتضمن `payload.album` دون متن نصي. تتبعها كل صورة أو مقطع فيديو في حدث وسائط منفصل يتضمن `payload.album_id`. اجمع الوسائط بحسب هذا المعرّف بدلًا من التعامل مع الترويسة بوصفها رسالة مفقودة.

يتضمن `newsletter.message` تحديثات عدادات القناة ولا يضمن تضمين متن منشور جديد. تستخدم تحديثات اتصال جهات الاتصال وانقطاع اتصالها `presence`، وتتطلب `POST /user/presence/subscribe`، كما تتطلب بقاء عميلك متاحًا. تستخدم تغييرات اسم المجموعة `group.info`.

اشترك في `device.logged_out`، و `device.temporary_ban`، و `device.reachout_timelock` لتمييز قيود الحساب من قطع الاتصال العادية. هذه الأحداث تحدد دائماً الخانة مع `session_id`. انظر [Webhooks](https://gowa-docs.mintlify.site/ar/concepts/webhooks.md) للحقول وتكوين الوجود.

## وحدة تخزين الدردشة API

يسجل GOWA المحادثة والرسائل لكل فتحة في وحدة تخزين المحادثة المحلية. استفسر عنه لكل جهاز:

```bash theme={null}
# list chats (filters: search, has_media, archived; paging: limit, offset)
curl -u admin:changeme -H "X-Device-Id: my-device" \
  "http://localhost:3000/chats?limit=20"

# messages in one chat (filters: start_time, end_time, media_only, is_from_me, search)
curl -u admin:changeme -H "X-Device-Id: my-device" \
  "http://localhost:3000/chat/628987654321@s.whatsapp.net/messages?limit=50"
```

فقط الرسائل التي شاهدها GOWA (تم تلقيها أثناء الاتصال، أو تسليمها بواسطة مزامنة تاريخ WhatsApp) متوفرة. لسؤال الهاتف عن التاريخ القديم في محادثة، اتصل بـ `POST /chat/{chat_jid}/history` مع `{"count": 50}`؛ تصل الرسائل في وقت واحد.

التصويت مناسب لمشاهدة اللحاق بركب البريد الوارد. للبوتات والأتمتة ، استخدم الويب.

## تنزيل الوسائط

مع التحميل التلقائي على (الافتراضي)، يعطي ويبهوك مسارا تحت `statics/media/`، يخدم في `http://localhost:3000/statics/media/<file>`. وإلا أحضرت الوسائط بناء على الطلب:

```bash theme={null}
curl -u admin:changeme -H "X-Device-Id: my-device" \
  "http://localhost:3000/message/3EB0C127D7BACC83D6A3/download?phone=628987654321@s.whatsapp.net"
```

انظر [الوسائط الواردة](https://gowa-docs.mintlify.site/ar/examples/media-handling.md#%D8%A7%D9%84%D9%88%D8%B3%D8%A7%D8%A6%D8%B7-%D8%A7%D9%84%D9%88%D8%A7%D8%B1%D8%AF%D8%A9) للشروط التي يمكن في إطارها لGOWA استرداد ملف انتهت صلاحيته.

## إيصالات القراءة

ضع علامة على رسالة مقروءة (الدقائق الزرقاء) مع `POST /message/{message_id}/read` و `{"phone": "<chat_jid>"}`، أو تعيين `WHATSAPP_AUTO_MARK_READ=true` لوضع علامة على كل رسالة واردة مقروءة تلقائياً.


## Related topics

- [البداية السريعة](https://gowa-docs.mintlify.site/ar/quickstart.md)
- [الوب](https://gowa-docs.mintlify.site/ar/concepts/webhooks.md)
- [إرسال الرسائل](https://gowa-docs.mintlify.site/ar/examples/sending-messages.md)
- [تعيين مؤقت الرسائل المختفية](https://gowa-docs.mintlify.site/ar/api-reference/chat/تعيين-مؤقت-الرسائل-المختفية.md)
- [الحصول على عدادات الرسائل الإخبارية](https://gowa-docs.mintlify.site/ar/api-reference/newsletter/الحصول-على-عدادات-الرسائل-الإخبارية.md)


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