{
  "api_base": "",
  "endpoints": [
    {
      "path": "/v2/start",
      "methods": [
        "GET"
      ],
      "category": "General",
      "isArticle": true,
      "title": "Get Started",
      "description": "Learn how to use our interactive developer platform to test, integrate, and master Wawp API in minutes.",
      "extraInfo": "\n# Getting Started: The Interactive Developer Experience\n\nWelcome to the Wawp API platform. This guide is designed to help you navigate our documentation and use the specialized tools we've built to speed up your development process. Our docs aren't just a manual—they are a lived, interactive environment where you can test real requests against your own WhatsApp instances.\n\n---\n\n## 🚀 1. The Interactive API Tester (Postman-Style)\n\nEvery endpoint in our documentation comes with a built-in interactive tester. This allows you to execute real API calls without leaving your browser or opening external tools like Postman or Insomnia.\n\n### How to use it:\n1. **Method Selector**: At the top left of the tester, you can see the HTTP method (POST, GET, etc.). If an endpoint supports multiple methods, you can switch between them using the dropdown.\n2. **URL Bar**: Displays the final URL that will be called. You can click to copy it directly.\n3. **Parameter Tabs**:\n    - **Params**: Configure Query parameters or Body fields.\n    - **Headers**: View or set required headers like `Authorization`.\n4. **The \"Send\" Button**: Click the **Send** button (or the Flask icon) to execute the request.\n\n![Placeholder: Screenshot of the Postman Tester highlighting the Send button and Parameter tabs.](IMAGE_POSTMAN_TESTER_PLACEHOLDER)\n\n---\n\n## 🧪 2. The API Sandbox & Global Variables\n\nTo make testing easier, we've implemented a \"Live Sandbox\" feature. Instead of typing your `instance_id` and `access_token` for every single endpoint, you can set them globally.\n\n### Setting your credentials:\n1. Look for the **API Sandbox** panel (usually in the sidebar or top of the page).\n2. Enter your **Instance ID**, **Access Token**, and a **Test Number** (the target phone number you want to send messages to).\n3. Once saved, these values will automatically populate the input fields in *every* tester across all pages.\n4. **Live Indicators**: You'll see a green \"Live\" pulse next to fields in the parameter tables that are using your sandbox values.\n\n![Placeholder: Image of the API Sandbox sidebar with fields for Instance ID and Token highlighted.](IMAGE_SANDBOX_SIDEBAR_PLACEHOLDER)\n\n---\n\n## 📖 3. Additional Context: Beyond the Basics\n\nMost documentation just tells you *what* a parameter is. We tell you *why* it matters. Under the main description of an endpoint, you'll find the **Additional Context** (or \"Narrative Power\") section.\n\n### What's inside:\n- **Architectural Deep Dives**: Explanation of the underlying logic (e.g., how we handle message queuing).\n- **Optimization Tips**: Specific advice on how to achieve 99.9% uptime.\n- **Strategic Patterns**: High-level designs like \"The Auto-Heal Pattern\" or \"Optimistic UI Updates.\"\n\n![Placeholder: Image showing the 'Additional Context' section expanded with a rich Markdown article.](IMAGE_CONTEXT_SECTION_PLACEHOLDER)\n\n---\n\n## 💻 4. Request Samples: Code for Humans\n\nOn the right side of the page (or below the parameters), you'll find the **Request Samples** section. This is your one-stop shop for implementation.\n\n### Features:\n- **Language Selection**: Switch between JavaScript, PHP, Python, Go, C#, and more.\n- **Library Variants**: For each language, we provide multiple methods (e.g., for JavaScript, you can choose between `fetch`, `axios`, or `jQuery`).\n- **One-Click Copy**: Use the copy button to grab the code and paste it directly into your IDE.\n- **Dynamic Content**: The sample code updates in real-time as you type into the interactive tester.\n\n![Placeholder: Image of the Code Samples section showing the language switcher and copy button.](IMAGE_CODE_SAMPLES_PLACEHOLDER)\n\n---\n\n## 📥 5. Expected Responses: Success & Failure\n\nUnderstanding what the server returns is crucial for error handling.\n\n### How to read them:\n1. **Status Codes**: 200 for Success, 400 for Client Errors (missing params), 401 for Auth issues, and 500 for Upstream errors.\n2. **Schema & Examples**: Each status code shows a JSON example of exactly what the API will return.\n3. **Filtered View**: Use the search and filter bar to quickly find specific error codes like \"400\".\n\n![Placeholder: Image of the Response Section highlighting a 200 Success and a 400 Error example.](IMAGE_RESPONSES_SECTION_PLACEHOLDER)\n\n---\n\n## 💡 Pro Tips for Fast Integration:\n- **Sync with Webhooks**: Always use the Webhooks category to learn how to receive real-time updates (like message delivery statuses).\n- **Use the Search**: Press `Ctrl+K` (or `Cmd+K`) to instantly find any endpoint or guide.\n- **Dark Mode**: Toggle the theme in the top right—our docs are designed for high-contrast late-night coding sessions.\n\n*Need more help? Our engineering team is available 24/7 via the \"Talk to Us\" button in the navbar.*\n",
      "args": {},
      "tips": [
        {
          "type": "positive",
          "title": "Global Sandbox",
          "content": "Fill out your Instance ID and Token once in the Sidebar to use them across all interactive testers."
        },
        {
          "type": "info",
          "title": "Code Samples",
          "content": "Our code samples use your real sandbox values, making them perfect for \"Copy-Paste\" testing in your local environment."
        }
      ],
      "recommendations": [
        "Start with the [/v2/session/create](/v2/session/create) guide to set up your first instance.",
        "Always check the 'Expected Responses' for 4xx errors to build robust error handling.",
        "Use the 'Copy AI Description' button (Icon) to get a full Markdown summary of any endpoint for your AI assistant."
      ],
      "responses": [],
      "translations": {
        "ar": {
          "title": "ابدأ الآن",
          "description": "تعرف على كيفية استخدام منصتنا التفاعلية لاختبار ودمج وإتقان Wawp API في دقائق معدودة.",
          "extraInfo": "\n# البداية: تجربة المطور التفاعلية\n\nمرحباً بك في منصة Wawp API. تم تصميم هذا الدليل لمساعدتك في التنقل في توثيقنا واستخدام الأدوات المتخصصة التي بنيناها لتسريع عملية التطوير الخاصة بك. التوثيق لدينا ليس مجرد دليل مستخدم—إنه بيئة تفاعلية حقيقية حيث يمكنك اختبار الطلبات الفعلية مقابل مثيلات واتساب الخاصة بك.\n\n---\n\n## 🚀 1. مختبر API التفاعلي (نمط Postman)\n\nتأتي كل نقطة نهاية (Endpoint) في توثيقنا مع مختبر تفاعلي مدمج. يسمح لك هذا بتنفيذ طلبات API حقيقية دون مغادرة متصفحك أو فتح أدوات خارجية مثل Postman.\n\n### كيفية استخدامه:\n1. **مبدل الطريقة (Method Selector)**: في أعلى يسار المختبر، يمكنك رؤية طريقة HTTP (POST, GET، إلخ). إذا كانت نقطة النهاية تدعم طرقاً متعددة، يمكنك التبديل بينها.\n2. **شريط الرابط (URL Bar)**: يعرض الرابط النهائي الذي سيتم استدعاؤه. يمكنك النقر لنسخه مباشرة.\n3. **تبويبات المعاملات**:\n    - **Params**: لتهيئة معاملات الاستعلام (Query) أو حقول الجسم (Body).\n    - **Headers**: لعرض أو ضبط الترويسات المطلوبة مثل `Authorization`.\n4. **زر \"إرسال\" (Send)**: انقر فوق زر **Send** لتنفيذ الطلب.\n\n![وصف: لقطة شاشة لمختبر Postman تبرز زر الإرسال وتبويبات المعاملات.](IMAGE_POSTMAN_TESTER_PLACEHOLDER)\n\n---\n\n## 🧪 2. الـ Sandbox والمتغيرات العالمية\n\nلجعل الاختبار أسهل، قمنا بتنفيذ ميزة \"Live Sandbox\". بدلاً من كتابة `instance_id` و `access_token` لكل نقطة نهاية بشكل منفصل، يمكنك ضبطها عالمياً.\n\n### ضبط بياناتك:\n1. ابحث عن لوحة **API Sandbox** (عادةً في القائمة الجانبية أو أعلى الصفحة).\n2. أدخل **Instance ID**، **Access Token**، و **رقم الاختبار** (رقم الهاتف المستهدف الذي تريد إرسال الرسائل إليه).\n3. بمجرد الحفظ، سيتم ملء هذه القيم تلقائياً في حقول الإدخال في *كل* مختبر عبر جميع الصفحات.\n4. **مؤشرات الحداثة**: ستلاحظ نبضاً أخضر بكلمة \"Live\" بجوار الحقول التي تستخدم قيم Sandbox الخاصة بك.\n\n![وصف: صورة لقائمة API Sandbox الجانبية مع إبراز حقول معرف المثيلة والرمز.](IMAGE_SANDBOX_SIDEBAR_PLACEHOLDER)\n\n---\n\n## 📖 3. معلومات إضافية: ما وراء الأساسيات\n\nمعظم التوثيقات تخبرك فقط *ما هو* المعامل، نحن نخبرك *لماذا* هو مهم. تحت الوصف الرئيسي لكل نقطة نهاية، ستجد قسم **معلومات إضافية** (Additional Context).\n\n### ماذا يوجد بالداخل:\n- **تحليلات هندسية عميقة**: شرح للمنطق الكامن وراء العمليات (مثل كيفية معالجة طوابير الرسائل).\n- **نصائح التحسين**: نصائح محددة حول كيفية تحقيق استمرارية عمل بنسبة 99.9%.\n- **أنماط استراتيجية**: تصميمات عالية المستوى مثل \"نمط الإصلاح الذاتي\" أو \"تحديثات واجهة المستخدم المتفائلة\".\n\n![وصف: صورة تظهر قسم 'معلومات إضافية' موسعاً مع مقال Markdown غني.](IMAGE_CONTEXT_SECTION_PLACEHOLDER)\n\n---\n\n## 💻 4. عينات الكود: مخصصة للمطورين\n\nفي جانب الصفحة (أو تحت المعاملات)، ستجد قسم **عينات الكود** (Request Samples). هذا هو مكانك الأمثل للتنفيذ البرمجي.\n\n### الميزات:\n- **اختيار اللغة**: بدّل بين JavaScript و PHP و Python و Go و C# وغيرها الكثير.\n- **مكتبات متنوعة**: لكل لغة، نوفر طرقاً متعددة (مثلاً لـ JavaScript، يمكنك الاختيار بين `fetch` أو `axios`).\n- **نسخ بنقرة واحدة**: استخدم زر النسخ لأخذ الكود ولصقه مباشرة في بيئة التطوير الخاصة بك.\n- **محتوى ديناميكي**: يتم تحديث كود العينة في الوقت الفعلي أثناء كتابتك في المختبر التفاعلي.\n\n![وصف: صورة لقسم عينات الكود تظهر مبدل اللغات وزر النسخ.](IMAGE_CODE_SAMPLES_PLACEHOLDER)\n\n---\n\n## 📥 5. الردود المتوقعة: النجاح والفشل\n\nفهم ما يعيده الخادم أمر بالغ الأهمية لمعالجة الأخطاء.\n\n### كيفية قراءتها:\n1. **أكواد الحالة**: 200 للنجاح، 400 للأخطاء من جانب العميل، 401 لمشاكل المصادقة، و 500 للأخطاء الداخلية.\n2. **المخطط والأمثلة**: يعرض كل كود حالة مثال JSON لما سيعيده الـ API بالضبط.\n3. **عرض مفلتر**: استخدم شريط البحث والفلترة للعثور بسرعة على أكواد خطأ محددة.\n\n![وصف: صورة لقسم الردود تبرز مثالاً للنجاح (200) وآخر للخطأ (400).](IMAGE_RESPONSES_SECTION_PLACEHOLDER)\n\n---\n\n## 💡 نصائح احترافية للدمج السريع:\n- **مزامنة الويب هوك**: استخدم دائماً قسم الويب هوك لتعلم كيفية استقبال التحديثات في الوقت الفعلي (مثل حالات تسليم الرسائل).\n- **استخدم البحث**: اضغط على `Ctrl+K` (أو `Cmd+K`) للعثور فوراً على أي نقطة نهاية أو دليل.\n- **الوضع الليلي**: بدّل المظهر في أعلى اليمين—تم تصميم توثيقنا ليكون مريحاً للعين أثناء جلسات البرمجة الليلية.\n\n*هل تحتاج لمزيد من المساعدة؟ فريقنا الهندسي متاح دائماً عبر زر \"تحدث معنا\" في شريط التنقل.*\n",
          "args": {},
          "tips": [
            {
              "title": "الـ Sandbox العالمي",
              "content": "قم بتعبئة معرف المثيلة والرمز مرة واحدة في القائمة الجانبية لاستخدامهما في جميع المختبرات التفاعلية."
            },
            {
              "title": "عينات الكود",
              "content": "تستخدم عينات الكود الخاصة بنا قيم Sandbox الحقيقية الخاصة بك، مما يجعلها مثالية لتجربة 'النسخ واللصق'."
            }
          ],
          "recommendations": [
            "ابدأ بدليل [/v2/session/create](/v2/session/create) لإعداد أول مثيلة لك.",
            "تحقق دائماً من 'الردود المتوقعة' لبناء معالجة قوية للأخطاء.",
            "استخدم زر 'نسخ وصف الذكاء الاصطناعي' للحصول على ملخص شامل لأي نقطة نهاية لمساعدك الذكي."
          ]
        }
      }
    },
    {
      "path": "/mcp-ready",
      "methods": [
        "GET"
      ],
      "isArticle": true,
      "title": "AI & MCP Integration",
      "category": "AI & Tools",
      "description": "Connect Wawp API Documentation directly to your AI tools like Cursor, Windsurf, or Claude Desktop.",
      "extraInfo": "\n# 🤖 Wawp AI-Ready Documentation (MCP)\n\nAt Wawp, we believe that documentation should be as smart as the code it describes. That's why we've implemented the **Model Context Protocol (MCP)**, allowing you to connect our entire API documentation directly to your favorite AI development tools.\n\n---\n\n## 🚀 What is MCP?\n\nThe **[Model Context Protocol](https://modelcontextprotocol.io/)** (MCP) is an open standard that enables AI models (like Claude, GPT-4, or those inside Cursor) to securely and reliably access external data sources. Instead of copying and pasting documentation, the AI can \"ask\" our server for the exact information it needs.\n\n## 🛠️ How to use the Wawp MCP Server\n\nYou can run the Wawp MCP server locally to give your AI full context of our WhatsApp API.\n\n### 1. Prerequisites\n- **Node.js (LTS Version):** Required to run the MCP server. Download it from [nodejs.org](https://nodejs.org/).\n- **AI Client:** An AI client that supports MCP (like **Cursor**, **Windsurf**, or **Claude Desktop**).\n\n> [!IMPORTANT]\n> If you see an error like `executable file not found in %path%`, it means Node.js is not installed or your terminal needs a restart after installation.\n\n### 2. Connect Your Favorite AI Tools\n\nFollow these simple steps for your platform:\n\n#### 🖱️ Cursor\nGo to **Settings > Cursor Settings > Models > MCP** and add a new tool:\n- **Name:** `wawp-api`\n- **Type:** `command`\n- **Command:** \n```bash\nnpx -y @wawp/mcp-server@latest\n```\n\n#### 🌊 Windsurf\nGo to **Windsurf Settings (Cmd+,)** > **MCP** > **Add Server**:\n- **Name:** `wawp-api`\n- **Type:** `command`\n- **Command:** \n```bash\nnpx -y @wawp/mcp-server@latest\n```\n\n#### 🤖 Claude Desktop\nOpen your `claude_desktop_config.json` and add:\n```json\n{\n  \"mcpServers\": {\n    \"wawp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@wawp/mcp-server@latest\"]\n    }\n  }\n}\n```\n\n#### 🚀 AI Agents (Antigravity / Cortex / etc.)\nIf you are using a command-line agent or a custom AI, use this command to start the MCP server:\n```bash\nnpx -y @wawp/mcp-server@latest\n```\n\n---\n\n## ⚡ Boost Your AI Agent\n\nGive your AI deep knowledge of Wawp's WhatsApp API by installing our **Agent Rules** and **API Integration Skill** directly into your project. Simply tell your AI agent:\n\n> \"Use the **install_agent_config** tool to set up my project with Wawp standards.\"\n\nThis will automatically create:\n1.  **.cursorrules**: Strict rules for secure credential management, correct `chatId` formats, error handling, and anti-spam rate limiting.\n2.  **.agent/skills/wawp-api-integration**: A complete technical guide covering all endpoints, webhook handling, interactive messages, and Node.js code patterns.\n\n---\n\n## Supported operations\n\nWawp's MCP server exposes the following operations:\n\n1.  **`search_docs`**: Find endpoints for specific tasks (e.g., \"How do I send a PDF?\").\n2.  **`list_endpoints`**: See all available categories and actions.\n3.  **`get_endpoint_details`**: Get exact JSON schemas, required parameters, and response examples for any endpoint.\n4.  **`set_config`**: Configure your `instance_id`, `access_token`, and `test_number` for the current session.\n5.  **`execute_request`**: Perform real API calls directly from your AI conversation (Logged as **MCP**).\n6.  **`get_session_health`**: Instantly check if your WhatsApp instance is connected.\n7.  **`send_local_file`**: Send a file (image, PDF, etc.) directly from your local computer.\n8.  **`generate_starter_code`**: Get a fully working script for any task.\n9.  **`install_agent_config`**: Setup Wawp premium agent rules in one click.\n\n---\n\n## 🔑 How to Provide Your Credentials\n\nTo make the AI capable of executing real requests, you need to tell it your API details. You can do this by simply telling the AI:\n\n> \"Set my Wawp configuration: Access Token is **YOUR_TOKEN**, Instance ID is **YOUR_INSTANCE**, and Test Number is **YOUR_NUMBER**.\"\n\nThe AI will then use the `set_config` tool to remember these details for the rest of your conversation. You can find your **Access Token** and **Instance ID** in the Wawp Dashboard.\n\n### 📄 Automatic Setup (.env)\nYou can also create a `.env` file in your project root to load credentials automatically:\n```env\nWAWP_ACCESS_TOKEN=your_token_here\nWAWP_INSTANCE_ID=your_instance_id\nWAWP_TEST_NUMBER=recipient_number\n```\n\n---\n\n## 🗺️ Your First AI-Powered WhatsApp Task\n\nIf you've never written code before, don't worry. Here is how you can start:\n\n1.  **Connect the MCP**: Follow the steps in section 2.\n2.  **Provide context**: Tell the AI: *\"I want to send a welcome message to my customers. Use my Wawp credentials.\"*\n3.  **Generate & Run**: Tell the AI: *\"Use the generate_starter_code tool to write a Node.js script that sends 'Hello' to my test number.\"*\n4.  **Execute**: The AI will give you the code. Just copy, paste, and run it!\n\n---\n\n## 💡 Why use this?\n\n- **Zero Guesswork**: The AI will always use the correct parameters and types.\n- **Save Time**: No more switching between your editor and the documentation website.\n- **Auto-pilot**: Leverage the design system skills to build UI that matches Wawp perfectly.\n\n---\n\n## 💾 Export & Downloads\n\nNeed the full API specification for your own tools? Visit our [Export Data](/docs/export) page to download Wawp API in **OpenAPI**, **Markdown**, or **HTML** formats.\n",
      "args": {},
      "modifiedAt": "2026-03-02",
      "translations": {
        "ar": {
          "title": "الربط مع الذكاء الاصطناعي (MCP)",
          "category": "الذكاء الاصطناعي والأدوات",
          "description": "اربط توثيق Wawp API مباشرة بأدواتك المفضلة مثل Cursor و Windsurf و Claude Desktop.",
          "extraInfo": "\n# 🤖 توثيق Wawp الجاهز للذكاء الاصطناعي (MCP)\n\nفي Wawp، نؤمن بأن التوثيق يجب أن يكون ذكياً بقدر الكود الذي يصفه. لهذا السبب، قمنا بتنفيذ بروتوكول **Model Context Protocol (MCP)**، الذي يتيح لك ربط توثيقنا الكامل مباشرة بأدوات تطوير البرمجيات المدعومة بالذكاء الاصطناعي.\n\n---\n\n## 🚀 ما هو MCP؟\n\nبروتوكول سياق النموذج (MCP) هو معيار مفتوح يتيح لنماذج الذكاء الاصطناعي (مثل Claude أو GPT-4 أو تلك الموجودة داخل Cursor) الوصول بشكل آمن وموثوق إلى مصادر البيانات الخارجية. بدلاً من نسخ ولصق التوثيق، يمكن للذكاء الاصطناعي \"سؤال\" خادمنا عن المعلومات الدقيقة التي يحتاجها.\n\n## 🛠️ كيفية استخدام سيرفر Wawp MCP\n\nيمكنك تشغيل سيرفر Wawp MCP محلياً لمنح الذكاء الاصطناعي الخاص بك السياق الكامل لـ WhatsApp API الخاص بنا.\n\n### 1. المتطلبات الأساسية\n- **Node.js (نسخة LTS):** ضروري لتشغيل السيرفر. يمكنك تحميله من [nodejs.org](https://nodejs.org/).\n- **برنامج يدعم MCP:** (مثل **Cursor** أو **Windsurf** أو **Claude Desktop**).\n\n> [!IMPORTANT]\n> إذا واجهت خطأ مثل `executable file not found in %path%` فهذا يعني أن Node.js غير مثبت، أو أنك بحاجة لإعادة تشغيل البرنامج بعد التثبيت.\n\n### 2. ربط سيرفر Wawp بأدواتك المفضلة\n\nاتبع هذه الخطوات البسيطة حسب البرنامج الذي تستخدمه:\n\n#### 🖱️ تطبيق Cursor\nانتقل إلى **Settings > Cursor Settings > Models > MCP** وأضف أداة جديدة:\n- **الاسم:** `wawp-api`\n- **النوع:** `command`\n- **الأمر:** \n```bash\nnpx -y @wawp/mcp-server@latest\n```\n\n#### 🌊 تطبيق Windsurf\nانتقل إلى **Windsurf Settings (Cmd+,)** > **MCP** > **Add Server**:\n- **الاسم:** `wawp-api`\n- **النوع:** `command`\n- **الأمر:** \n```bash\nnpx -y @wawp/mcp-server@latest\n```\n\n#### 🤖 تطبيق Claude Desktop\nافتح ملف `claude_desktop_config.json` وأضف الكود التالي:\n```json\n{\n  \"mcpServers\": {\n    \"wawp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@wawp/mcp-server@latest\"]\n    }\n  }\n}\n```\n\n#### 🚀 وكلاء الذكاء الاصطناعي (Antigravity / Cortex / إلخ)\nإذا كنت تستخدم وكيلاً يعمل عبر سطر الأوامر أو نظام AI مخصص، استخدم هذا الأمر لتشغيل السيرفر:\n```bash\nnpx -y @wawp/mcp-server@latest\n```\n\n---\n\n## ⚡ تعزيز قدرات الذكاء الاصطناعي (وكيل API)\n\nامنح ذكاءك الاصطناعي معرفة متعمقة بـ Wawp WhatsApp API عبر تثبيت **قواعد الوكيل** و **مهارة التكامل مع الـ API** مباشرةً في مشروعك. فقط قل للذكاء الاصطناعي:\n\n> \"استخدم أداة **install_agent_config** لتجهيز مشروعي وفق معايير Wawp.\"\n\nسيقوم هذا الإجراء بإنشاء:\n1.  **.cursorrules**: قواعد صارمة لإدارة الاعتمادات بأمان، تنسيق `chatId` الصحيح، معالجة الأخطاء، ومنع الرسائل المزعجة.\n2.  **.agent/skills/wawp-api-integration**: دليل تقني شامل يغطي جميع نقاط النهاية، معالجة Webhooks، الرسائل التفاعلية، وأمثلة كود Node.js.\n\n---\n\n## 🔍 الأدوات المتاحة\n\nبمجرد الاتصال، سيكون لدى الذكاء الاصطناعي إمكانية الوصول إلى:\n\n1.  **`search_docs`**: البحث عن نقاط النهاية لمهام محددة (مثل \"كيف أرسل ملف PDF؟\").\n2.  **`list_endpoints`**: رؤية كافة التصنيفات والإجراءات المتاحة.\n3.  **`get_endpoint_details`**: الحصول على مسودات JSON الدقيقة، والبارامترات المطلوبة، وأمثلة الاستجابة لأي نقطة نهاية.\n4.  **`set_config`**: تهيئة رقم المثيل (`instance_id`)، ورمز الوصول، ورقم الاختبار للجلسة الحالية.\n5.  **`execute_request`**: تنفيذ طلبات برمجية حقيقية مباشرة من محادثة الذكاء الاصطناعي (يتم تسجيلها في السجل باسم **MCP**).\n6.  **`get_session_health`**: فحص حالة اتصال مثيل واتساب الخاص بك فورياً.\n7.  **`send_local_file`**: إرسال ملف (صورة، PDF، إلخ) مباشرة من جهاز الكمبيوتر المحلي الخاص بك.\n8.  **`generate_starter_code`**: الحصول على كود برمجي جاهز للعمل لأي مهمة تطلبها.\n9.  **`install_agent_config`**: تثبيت إعدادات Wawp الاحترافية في مشروعك بضغطة واحدة.\n\n---\n\n## 🔑 كيفية إدخال بيانات الاعتماد الخاصة بك\n\n لتمكين الذكاء الاصطناعي من تنفيذ طلبات حقيقية، يجب عليك تزويده بتفاصيل الـ API الخاصة بك. يمكنك القيام بذلك ببساطة عن طريق إخبار الذكاء الاصطناعي:\n\n> \"قم بإعداد تهيئة Wawp الخاصة بي: رمز الوصول هو **YOUR_TOKEN**، ومعرف المثيل هو **YOUR_INSTANCE**، ورقم الاختبار هو **YOUR_NUMBER**.\"\n\nسيرفع الذكاء الاصطناعي هذه البيانات باستخدام أداة `set_config` ليحفظها طوال مدة المحادثة. يمكنك العثور على **رمز الوصول** و**معرف المثيل** في لوحة تحكم Wawp.\n\n### 📄 الإعداد التلقائي (ملف .env)\nيمكنك أيضاً إنشاء ملف `.env` في مجلد مشروعك لتحميل بيانات الاعتماد تلقائياً:\n```env\nWAWP_ACCESS_TOKEN=your_token_here\nWAWP_INSTANCE_ID=your_instance_id\nWAWP_TEST_NUMBER=recipient_number\n```\n\n---\n\n## 🗺️ مهمتك الأولى باستخدام الذكاء الاصطناعي\n\nإذا لم تكن قد كتبت كوداً من قبل، فلا تقلق. إليك كيف تبدأ:\n\n1.  **ربط الـ MCP**: اتبع الخطوات الموضحة في القسم الثاني.\n2.  **أعطِ السياق**: قل للذكاء الاصطناعي: *\"أريد إرسال رسالة ترحيب لعملائي. استخدم بيانات Wawp الخاصة بي.\"*\n3.  **توليد الكود**: قل للذكاء الاصطناعي: *\"استخدم أداة generate_starter_code لكتابة كود Node.js يرسل كلمة 'أهلاً' لرقم الاختبار الخاص بي.\"*\n4.  **التنفيذ**: سيعطيك الذكاء الاصطناعي الكود كاملاً. فقط قم بنسخه وتشغيله!\n\n---\n\n## 💡 لماذا تستخدم هذا؟\n\n- **بدون تخمين**: سيستخدم الذكاء الاصطناعي دائماً البارامترات والأنواع الصحيحة.\n- **توفير الوقت**: لا داعي للتنقل بين محرر الكود وموقع التوثيق.\n- **القيادة الذاتية**: استفد من مهارات نظام التصميم لبناء واجهات تطابق Wawp تماماً.\n\n---\n\n## 💾 التصدير والتحميل\n\nهل تحتاج إلى مواصفات الـ API الكاملة لأدواتك الخاصة؟ قم بزيارة صفحة [تصدير البيانات](/docs/export) لتحميل Wawp API بتنسيقات **OpenAPI** أو **Markdown** أو **HTML**.\n            "
        }
      }
    },
    {
      "path": "/export",
      "methods": [
        "GET"
      ],
      "isArticle": true,
      "title": "Export & Downloads",
      "category": "AI & Tools",
      "description": "Download Wawp API in your preferred format (OpenAPI, Markdown, HTML).",
      "extraInfo": "This article is a placeholder to link to the export page.",
      "args": {},
      "modifiedAt": "2024-02-16",
      "translations": {
        "ar": {
          "title": "التصدير والتحميل",
          "description": "تحميل Wawp API بالتنسيق المفضل لديك (OpenAPI, Markdown, HTML)."
        }
      }
    },
    {
      "path": "/v2/lifecycle-overview",
      "methods": [
        "GET"
      ],
      "category": "Session Management",
      "isArticle": true,
      "title": "Session Lifecycle",
      "description": "Documentation on Wawp's Session Lifecycle — how to provision, start, and maintain reliable WhatsApp instances.",
      "extraInfo": "\n# The Lifecycle of a Session: Architectural Mastery\n\nWawp’s session API is not just a collection of endpoints; it is a sophisticated orchestration layer designed to make WhatsApp automation reliable, secure, and infinitely scalable. In this guide, we deep-dive into the \"Operational Philosophy\" behind instance management and how to build production-grade workflows.\n\n---\n\n## 🏗️ Operational Philosophy: The \"Lazy & Warm\" Approach\n\nTo maintain **99.9% uptime** and provide a premium user experience, we recommend a lifecycle strategy we call \"Lazy Provisioning & Warm Booting.\"\n\n### 1. Lazy Provisioning (Creation)\nDon't create sessions in bulk for users who might never use the service. Provision an `instance_id` using the [`create`](/v2/session/create) endpoint only at the moment a user decides to connect. This keeps your database clean and ensures your quota is allocated to active customers.\n\n### 2. Warm Booting (Starting)\nStarting a session boots a dedicated engine. If your application detects a user has logged into your dashboard, verify their session status via [`info`](/v2/session/info). If they are `STOPPED`, trigger a [`start`](/v2/session/start) call in the background. By the time they navigate to the \"WhatsApp QR\" page, the engine is already \"warm,\" reducing wait times by up to 15 seconds.\n\n---\n\n## 🔄 Status Transitions: Decoding the State Machine\n\nUnderstanding the movement between states is critical for building a responsive UI.\n\n| Status | Technical Context | Recommended UI Action |\n| :--- | :--- | :--- |\n| **STOPPED** | The engine is not running. No resources are consumed. | Show a \"Power On\" or \"Start\" button. |\n| **STARTING** | The engine is booting and connecting to the WhatsApp bridge. | Show a \"Connecting...\" spinner or progress bar. |\n| **SCAN_QR_CODE** | The engine is active but unauthenticated. | Display the QR Code or a Pairing Code input. |\n| **WORKING** | Authenticated and ready for all operations. | Show \"Connected\" status and enable messaging features. |\n| **FAILED** | An unrecoverable internal error occurred. | Show a \"Troubleshoot\" or \"Restart\" button. |\n\n---\n\n## 🌐 Reliability Engineering with Webhooks\n\nWhile polling the [`info`](/v2/session/info) endpoint is useful for simple scripts, production environments **must** use webhooks. \n\n### Why Webhooks?\n- **Instant Response**: Receive a `SCAN_QR_CODE` event the millisecond a session is disconnected or requires re-authentication.\n- **Resource Efficiency**: Eliminates the need for aggressive polling loops that waste network bandwidth.\n- **Audit Trails**: Log status changes in your own database to analyze session stability over time.\n\n---\n\n## 🛠️ Advanced Orchestration Patterns\n\n### The \"Auto-Heal\" Pattern\nIf a status webhook returns `FAILED`, your system should wait 30 seconds and then automatically call [`/v2/session/restart`](/v2/session/restart). Most failures are transient (network drops, port collisions) and can be resolved by a clean restart without user intervention.\n\n### The \"Identity Verification\" Pattern\nOnce a status hits `WORKING`, your automation should immediately call [`/v2/session/me`](/v2/session/me). Compare the returned WhatsApp JID with the record in your database. If a user scans their personal phone instead of their business phone, you can detect this instantly and notify them of the mistake.\n\n---\n\n## 🛡️ Security & Performance Best Practices\n\n- **Token Rotation**: Treat your `access_token` like a password. If a developer leaves or a key is leaked, use our security portal to rotate it immediately.\n- **Rate Limiting Intelligence**: Wawp handles internal rate limits for you, but calling `/session/start` for the same instance many times in a few seconds will result in a `429` error. Implement an exponential backoff strategy in your code.\n- **Scheduled Maintenance**: For sessions that stay active for months, a weekly [`restart`](/v2/session/restart) during low-traffic hours can help clear memory and maintain peak performance.\n\n---\n\n## Troubleshooting Guide\n\n### Why is my session stuck in \"STARTING\"?\nThis usually happens if the underlying high-performance node is under heavy load or if there's a delay in the WhatsApp handshake. If it lasts longer than 60 seconds, trigger a manual [`restart`](/v2/session/restart).\n\n### My session returns \"LOGOUT\" via Webhook\nThe user has likely used their mobile device's \"Linked Devices\" settings to manually disconnect the session. You should clear their connection state in your database and redirect them to scan the QR code again.\n\n---\n\n## Summary of Operations:\n- **create**: Allocate instance resources.\n- **start**: Power on the engine.\n- **stop**: Hibernate the engine to save resources.\n- **info**: Real-time health monitoring.\n- **me**: Profile and identity verification.\n- **logout**: Cleanly unpair the device.\n- **restart**: Troubleshooting and maintenance.\n- **delete**: Complete data destruction.\n            ",
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "Safe Restarts",
          "content": "If a session is in FAILED state, always try a Restart before a full Logout/Start cycle."
        },
        {
          "type": "warning",
          "title": "QR Freshness",
          "content": "QR codes in WhatsApp expire quickly. Always fetch the most recent code when the status is SCAN_QR_CODE."
        },
        {
          "type": "positive",
          "title": "Pairing Code UX",
          "content": "Use Pairing Codes for users who can't easily scan a QR code. It provides a more accessible onboarding flow."
        }
      ],
      "recommendations": [
        "Use webhooks for real-time status updates instead of aggressive polling.",
        "Implement a 'Retry' button in your UI that triggers the [/v2/session/restart](/v2/session/restart) endpoint.",
        "Monitor the 'STARTING' state duration; if it persists beyond 60s, trigger a manual restart.",
        "Store the 'instance_id' and 'server_name' in your database for faster troubleshooting.",
        "Automatically trigger a [/v2/session/start](/v2/session/start) if you detect a user trying to send a message while the status is STOPPED.",
        "Ensure your application handles the 'FAILED' status gracefully by notifying the administrator."
      ],
      "responses": [],
      "translations": {
        "ar": {
          "title": "دليل إدارة الجلسات",
          "description": "تعرف على كيفية إدارة دورة حياة جلسة واتساب من الإنشاء إلى الإيقاف.",
          "category": "إدارة الجلسات",
          "extraInfo": "\n# الدليل الشامل لإدارة دورة حياة الجلسات في Wawp\n\nتعد إدارة الجلسات (Sessions) العمود الفقري لمنصة Wawp، وهي العملية التي يتم من خلالها ربط حساب واتساب حقيقي بنظامنا لتمكين الأتمتة وإرسال الرسائل. فهم دورة حياة الجلسة بشكل عميق هو ما يفرق بين نظام هش وخدمة احترافية تضمن استمرارية العمل بنسبة 99.9%.\n\n---\n\n## المفهوم الجوهري للجلسات\nفي Wawp، لا نتعامل مع أرقام الهاتف بشكل مجرد، بل نتعامل مع \"مثيلات\" (Instances) أو جلسات معزولة. كل جلسة تعمل في بيئة تقنية مستقلة تماماً، مما يضمن أن نشاطك في جلسة واحدة لا يؤثر على الأخرى. هذا التصميم يمنح المطورين القدرة على إدارة مئات الحسابات بشكل متوازٍ وبأعلى معايير الأمان.\n\n### لماذا يعتبر نظام الجلسات الخاص بنا متفوقاً؟\n1. **العزل التام**: كل جلسة تمتلك ملفات تعريف واتساب الخاصة بها ومخزن بيانات مستقل.\n2. **الاسترداد الآلي**: يقوم نظامنا بمراقبة حالة الجلسات وإعادة تشغيل المحركات المعطلة تلقائياً في حالة حدوث خلل برمجي بسيط.\n3. **الشفافية**: نوفر لك نقاط نهاية (Endpoints) تمنحك رؤية كاملة لما يحدث داخل المحرك في كل ثانية.\n\n---\n\n## الحالات الكاملة للجلسة (Deep Dive into Statuses)\n\nفهم الحالات ليس مجرد معرفة الاسم، بل معرفة \"المنطق\" وراء كل انتقال:\n\n### 1. **STOPPED (المحرك متوقف)**\nهذه هي حالة \"السكون\". الجلسة موجودة في قاعدة بياناتنا ولكن المحرك البرمجي المسؤول عن الاتصال بواتساب غير مفعل.\n*   **متى تحدث؟**: بعد إنشاء الجلسة مباشرة، أو بعد استدعاء أمر `/stop` يدوياً، أو في حالات نادرة عند حدوث فشل حرج متكرر.\n*   **الإجراء**: يجب استدعاء `/v2/session/start` لإيقاظ المحرك.\n\n### 2. **STARTING (قيد التشغيل)**\nهذه حالة انتقالية قصيرة (عادة 5-15 ثانية). في هذه المرحلة، نقوم بتجهيز الحاوية (Container)، تحميل ملفات التعريف، وبدء مصافحة الشبكة مع خوادم واتساب.\n*   **نصيحة**: لا تكرر استدعاء `start` في هذه المرحلة. انتظر حتى تتغير الحالة.\n\n### 3. **SCAN_QR_CODE (انتظار المصادقة)**\nالمحرك يعمل ولكنه غير مرتبط بحساب واتساب. هو الآن يبث \"تحدي\" (Challenge) يحتاج لهاتفك لفك شفرته.\n*   **الخيارات**: يمكنك جلب رمز QR أو طلب رمز اقتران (Pairing Code) للهواتف التي تواجه مشاكل في الكاميرا.\n\n### 4. **WORKING (فعال وجاهز)**\nهذه هي حالة الهدف. الجلسة الآن متصلة بخوادم واتساب، تم تحميل جهات الاتصال، وهي جاهزة لاستقبال وإرسال أي نوع من الوسائط.\n*   **الاستمرارية**: طالما أن الهاتف متصل بالإنترنت ولم يقم المستخدم بتسجيل الخروج يدوياً، ستبقى الجلسة في هذه الحالة.\n\n### 5. **FAILED (فشل الاتصال)**\nحالة تحذيرية تعني أن المحرك واجه عقبة لا يمكنه تجاوزها تلقائياً (مثل انقطاع مفاجئ في خدمات واتساب العالمية أو خلل في ملفات التعريف المحلية).\n*   **الإجراء التقني**: يفضل استدعاء `/v2/session/restart` بدلاً من البدء من الصفر.\n\n---\n\n## هندسة التدفق المثالي (The Golden Flow)\n\nلضمان أفضل تجربة لمستخدميك، اتبع هذا التسلسل الهندسي:\n\n### المرحلة الأولى: التخصيص (Provisioning)\nابدأ بإنشاء الجلسة وحفظ `instance_id` و `server_name` في قاعدة بياناتك. **لا تترك هذه البيانات للصدفة**؛ فهي مفتاحك للتحكم في الجلسة مستقبلاً.\n\n### المرحلة الثانية: الإحماء والربط\nعندما يفتح المستخدم لوحة التحكم الخاصة بك:\n1. تحقق من الحالة عبر `/v2/session/info`.\n2. إذا كانت `STOPPED`، استدعِ `start` فوراً في الخلفية.\n3. اعرض مؤشر تحميل (Loading) جذاب بينما تنتقل الجلسة من `STARTING` إلى `SCAN_QR_CODE`.\n\n### المرحلة الثالثة: المراقبة المستمرة\nبمجرد وصول الجلسة لحالة `WORKING`، لا تتوقف عن المتابعة. نوصي بشدة باستخدام الويب هوك (Webhooks). الاستماع لحدث `session.status` يجعلك تستجيب لحظياً إذا قام العميل بفصل هاتفه، مما يتيح لك إرسال إشعار فوري له: \"عذراً، جلسة واتساب الخاصة بك انقطعت، يرجى إعادة المسح\".\n\n---\n\n## استراتيجيات التشغيل المتقدمة\n\n### الاستجابة للأعطال (Fault Tolerance)\nإذا كنت تبني نظاماً لارسال التنبيهات الحساسة (مثل OTP)، لا تعتمد على جلسة واحدة. ابنِ نظام \"تبديل الفشل\" (Failover) بحيث إذا انتقلت جلسة لحالة `FAILED`، يقوم النظام تلقائياً بتوجيه الرسالة عبر جلسة بديلة.\n\n### توفير الموارد (Resource Optimization)\nإذا كان لديك آلاف الجلسات لعملاء مختلفين، وبعضهم لا يستخدم النظام إلا مرة في الأسبوع، استخدم \"إيقاف الخمول\" (Idle Stop). إذا لم يتم إرسال أو استقبال رسالة خلال 24 ساعة، استدعِ `/v2/session/stop`. هذا يقلل الضغط على خوادمك ويضمن سرعة استجابة هائلة للجلسات النشطة.\n\n---\n\n## الأسئلة الشائعة والأخطاء البرمجية\n\n### لماذا تظل الجلسة في حالة STARTING للأبد؟\nهذا يحدث عادة بسبب محاولة تشغيل نفس الجلسة من مكانين مختلفين، أو بسبب وجود عملية صيانة على العقدة (Node) المستضيفة. انتظر 60 ثانية، ثم جرب `/restart`.\n\n### هل يؤثر إيقاف الجلسة على الرسائل الواردة؟\nنعم، عندما تكون الحالة `STOPPED` أو `FAILED`، لا يمكن لـ Wawp استقبال الرسائل وتوجيهها للويب هوك الخاص بك. بمجرد العودة لحالة `WORKING`، سيقوم واتساب بمزامنة الرسائل التي وصلت أثناء الانقطاع، وسنقوم بمعالجتها.\n\n### متى يجب علي استخدام تسجيل الخروج (Logout)؟\nاستخدمه فقط إذا كنت ترغب في ربط رقم هاتف مختلف تماماً بنفس الجلسة، أو إذا كانت ملفات التعريف تعاني من تلف لا يمكن إصلاحه عبر إعادة التشغيل.\n",
          "tips": [
            {
              "title": "إعادة تشغيل آمنة",
              "content": "إذا كانت الجلسة في حالة FAILED، حاول دائماً إعادة التشغيل قبل تسجيل الخروج والبدء من جديد."
            },
            {
              "title": "حداثة QR",
              "content": "تنتهي صلاحية رموز QR بسرعة. اجلب دائماً أحدث رمز."
            }
          ],
          "recommendations": [
            "استخدم الويب هوك لتحديثات الحالة في الوقت الفعلي بدلاً من الاستجواب المكثف.",
            "قم بتنفيذ زر 'إعادة المحاولة' في واجهتك يقوم باستدعاء نقطة النهاية [/v2/session/restart](/v2/session/restart).",
            "راقب مدة الحالة 'STARTING'؛ إذا استمرت لأكثر من 60 ثانية، ابدأ إعادة تشغيل يدوية.",
            "خزن 'instance_id' و 'server_name' في قاعدة بياناتك لاستكشاف الأخطاء وإصلاحها بشكل أسرع.",
            "ابدأ تلقائياً [/v2/session/start](/v2/session/start) إذا اكتشفت أن مستخدماً يحاول إرسال رسالة بينما الحالة STOPPED.",
            "تأكد من أن تطبيقك يتعامل مع حالة 'FAILED' بمرونة عن طريق إخطار المسؤول."
          ]
        }
      }
    },
    {
      "path": "/v2/session/create",
      "methods": [
        "POST"
      ],
      "title": "Create Session",
      "category": "Session Management",
      "description": "Provisions a fresh Wawp instance and returns metadata such as instance_id and session_name.",
      "extraInfo": "\n# Provisioning Your Digital Infrastructure: The Create Session Endpoint\n\nThe `/v2/session/create` endpoint is the specialized \"Factory\" for Wawp instances. While it may seem like a simple registration step, it handles a sophisticated backend process of resource allocation, container provisioning, and server assignment. Understanding how to use this factory efficiently is the foundation of a scalable WhatsApp integration.\n\n---\n\n## 🛠️ The Provisioning Architecture\n\nWhen you call `create`, Wawp does not just create a record in a database; it orchestrates the following:\n1. **Node Selection**: Our balancer identifies the high-performance node with the lowest latency and highest availability for your region.\n2. **Instance Isolation**: A dedicated, isolated environment is carved out for your session, ensuring that your data and encryption keys never mingle with other users.\n3. **Identifier Assignment**: You are issued a unique `instance_id`, which serves as your permanent handle for all future interactions with that specific WhatsApp account.\n\n---\n\n## 🛡️ Strategic Best Practices\n\n### 1. Data Integrity and Persistence\nAlways save the returned `instance_id` and `server_name` in your local database immediately. \n- **The \"Context Store\"**: Associate this ID with your internal User IDs or Business IDs. \n- **Troubleshooting**: If you ever need to contact support, providing the `server_name` allows our engineers to pinpoint the exact infrastructure node hosting your session, reducing resolution time from hours to minutes.\n\n### 2. Idempotency and Deduplication\nBefore calling `create`, always check your own system state. \n- **The Trap**: Re-creating instances every time a user refreshes their settings page will quickly exhaust your quota.\n- **The Solution**: Implement a \"Check-then-Create\" logic. Only call this endpoint if your database shows that the user has no existing `instance_id` or if they have explicitly requested to \"Delete and Start New.\"\n\n### 3. \"Lazy\" Provisioning\nDon't create sessions in bulk. Provision an instance only when a user is actively \"Onboarding.\" This maintains a clean environment and ensures that your allocated resources are being used by active, paying, or engaged customers.\n\n---\n\n## 💡 Industry-Standard Use Cases\n\n### A. Customer Relationship Management (CRM)\nAutomatically provision a unique WhatsApp instance for every new high-value account. This allows your sales team to have dedicated communication channels that are fully logged and auditable within your CRM.\n\n### B. Automated Appointment Reminders\nFor medical or service industries, use this endpoint to spin up \"Notification Engines.\" By separating \"Notifications\" from \"Customer Support\" across different instances, you reduce the risk of account flagging and ensure high delivery rates.\n\n### C. Multi-Tenant SaaS Platforms\nIf you build software for other businesses, you can use this endpoint to offer \"WhatsApp-as-a-Service\" to your clients. Each of your clients gets their own `instance_id`, giving them a private, secure connection to their own customers.\n\n---\n\n## ⚠️ Common Pitfalls and Troubleshooting\n\n### \"quota_reached\" (403 Forbidden)\nThis is the most common error for growing applications. It means you have used all the \"slots\" provided by your current plan.\n- **Fix**: Either upgrade your plan or use the [`/v2/session/delete`](/v2/session/delete) endpoint to remove stagnant or unused sessions.\n\n### \"missing_param\" (400 Bad Request)\nThe \"Factory\" cannot verify your identity without the `access_token`. \n- **Fix**: Ensure your token is included in the request body (POST). Double-check for trailing spaces or hidden characters if copying from a dashboard.\n\n---\n\n## 🚀 The Next Step: \"The Warm Boot\"\nCreating a session is like \"registering a car.\" You now have the keys, but the engine isn't running yet. Your newly created session will be in the **STOPPED** state. To actually start the authentication process and generate a QR code, you **must** call the [`/v2/session/start`](/v2/session/start) endpoint immediately after success.\n    ",
      "args": {
        "access_token": {
          "type": "string",
          "required": true,
          "description": "Your API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        }
      },
      "tips": [
        {
          "type": "info",
          "title": "Metadata Storage",
          "content": "Always store the 'server_name' alongside the 'instance_id'. It helps our support team resolve issues faster."
        },
        {
          "type": "warning",
          "title": "Quota Limits",
          "content": "If you receive a 'quota_reached' error, you must either delete an unused instance or upgrade your plan."
        }
      ],
      "recommendations": [
        "Provision sessions 'On-Demand' to keep your dashboard clean and maximize your quota usage.",
        "Always follow a Create call with a Start call to initiate the QR code generation process.",
        "Ensure your database schema can handle 12-character alphanumeric strings for the 'instance_id'."
      ],
      "responses": [
        {
          "status": 201,
          "description": "Success - Session Created",
          "contentType": "application/json",
          "example": {
            "instance_id": "3EB0BCB2E3D4",
            "session_name": "wawp-84729105",
            "status": "STARTING",
            "server_name": "wawp-api-prod-50",
            "config": {}
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Token",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: access_token",
            "details": {
              "missing": [
                "access_token"
              ],
              "recommendation": "Ensure you are sending the 'access_token' in your request."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 403,
          "description": "Forbidden - Quota or Limit Reached",
          "contentType": "application/json",
          "example": {
            "code": "quota_reached",
            "message": "You have reached your maximum instances limit.",
            "details": {
              "recommendation": "Upgrade your plan or delete unused instances to create new ones."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "إنشاء جلسة",
          "description": "حجز معرف جلسة جديد في النظام.",
          "tips": [
            {
              "title": "أمان الجلسة",
              "content": "حافظ على سرية معرف الجلسة session_id ولا تشاركه علنًا أبدًا."
            },
            {
              "title": "حالة الجلسة",
              "content": "تحقق من حالة الجلسة بانتظام أو استخدم Webhooks للتحديثات."
            }
          ],
          "args": {
            "instance_id": {
              "description": "المعرف المراد استخدامه"
            },
            "access_token": {
              "description": "مفتاح الوصول"
            }
          },
          "extraInfo": "\n# إنشاء جلسة Wawp: الخطوة الأولى في رحلة الأتمتة\n\nتعد نقطة النهاية `/v2/session/create` بمثابة \"بوابة الدخول\" إلى كامل منظومة Wawp. هي ليست مجرد أمر برمجي، بل هي عملية هندسية معقدة تتم خلف الكواليس لتخصيص موارد سحابية معزولة وضمان جاهزية المحرك لربط حساب واتساب خاص بك.\n\n---\n\n## كيف يعمل \"مصنع الجلسات\"؟\nعندما تُرسل طلباً لإنشاء جلسة، يقوم نظامنا بعدة عمليات متسلسلة في أجزاء من الثانية:\n1. **التحقق من الهوية والقواعد**: نتأكد من أن `access_token` الخاص بك صالح وأنك لم تتجاوز الحصة المسموح بها (Quota) في خطتك الحالية.\n2. **اختيار العقدة (Node Selection)**: نختار أفضل خادم حالي متاح من حيث الموارد والقرب الجغرافي لضمان أقل زمن استجابة (Latency).\n3. **توليد الهوية الفريدة**: يتم إنشاء `instance_id` فريد تماماً، وهو المعرف الذي سيرافقك في كافة العمليات البرمجية القادمة.\n4. **تجهيز البيئة المعزولة**: يتم إنشاء حاوية (Container) مخصصة لهذه الجلسة فقط، لضمان عدم تداخل البيانات بين حساباتك المختلفة.\n\n---\n\n## الاستخدام الذكي: متى وكيف تُنشيء الجلسات؟\n\n### استراتيجية \"الإنشاء عند الطلب\" (Just-In-Time Provisioning)\nمن الأخطاء الشائعة بين المطورين المبتدئين إنشاء مئات الجلسات مسبقاً قبل الحاجة الفعلية إليها. هذا يؤدي إلى استهلاك غير مبرر لحصتك المتاحة. \n**الطريقة الاحترافية**: أنشئ الجلسة فقط عندما يقوم المستخدم بالنقر على زر \"ربط واتساب\" في واجهة تطبيقك. هذا يضمن أن كل جلسة في حسابك هي جلسة نشطة ومستهدفة.\n\n### تكامل قاعدة البيانات\nعند نجاح عملية الإنشاء، تعيد لك API كلاً من `instance_id` و `server_name`. \n> [!IMPORTANT]\n> يجب عليك حفظ هذين المعطيين فوراً في قاعدة بياناتك وربطهما بمعرف المستخدم (User ID) في نظامك. بدون تسجيلهما، ستفقد القدرة على التحكم في الجلسة برمجياً.\n\n---\n\n## أفضل الممارسات الأمنية والتقنية\n\n### 1. حماية الـ Access Token\nتذكر أن كلاً من `access_token` و `instance_id` يمنحان السيطرة الكاملة على الجلسة. لا تقم أبداً بتمرير هذه القيم في مسار الرابط (URL Parameters) أو عرضها في سجلات المتصفح الأمامية. اجعل كافة الطلبات تتم عبر خادمك الخلفي (Backend) لإبقاء مفاتيحك آمنة.\n\n### 2. التعامل مع الحصص (Quota Management)\nإذا تلقيت استجابة `403 Forbidden` مع رسالة \"Quota Reached\"، فهذا يعني أنك بلغت الحد الأقصى للجلسات المسموح بها في خطتك. \n*   **الحل البرمجي**: ابحث في قاعدة بياناتك عن الجلسات القديمة التي لم تعد تُستخدم وقم بحذفها عبر `/v2/session/delete` لتحرير مكان لجلسة جديدة، أو قم بترقية خطتك.\n\n### 3. ثبات الخادم (Server Stability)\nحقل `server_name` الذي نرسله لك يساعد فريق الدعم الفني لدينا في تحديد مكان جلستك بدقة إذا واجهت أي مشاكل. ننصح بعرضه في \"معلومات النظام\" داخل لوحة تحكم تطبيقك لتسهيل التواصل مع الدعم.\n\n---\n\n## حالات استخدام عملية\n\n### أ- منصات خدمة العملاء (CRM)\nعندما يقوم عميل جديد بالتسجيل في منصتك، يمكنك تلقائياً استدعاء `create` لتجهيز بيئة الواتساب الخاصة به، مما يجعل عملية الإعداد (Onboarding) سريعة وسلسة.\n\n### ب- أنظمة إخطارات المتجر الإلكتروني\nبدلاً من استخدام رقم واحد لكل الإخطارات، يمكنك إنشاء جلسات منفصلة (بأرقام واتساب مختلفة) لكل قسم: \"المبيعات\"، \"الدعم الفني\"، \"تأكيد الطلبات\". هذا يوزع ضغط الرسائل ويقلل احتمالية حظر الرقم من قِبل واتساب.\n\n---\n\n## استكشاف الأخطاء وإصلاحها (Troubleshooting)\n\n### الخطأ: \"Instance ID already exists\"\nعلى الرغم من أننا نولد المعرفات تلقائياً في معظم الأحيان، إلا أنك إذا كنت توفر معرفاً خاصاً، فتأكد من أنه فريد. يفضل ترك النظام يولد المعرف لضمان عدم التصادم.\n\n### الخطأ: \"Invalid Access Token\"\nتحقق من أنك تنسخ الرمز بالكامل وبدون مسافات زائدة. تذكر أن الرمز حساس لحالة الأحرف.\n\n---\n\n## الخطوات القادمة بعد الإنشاء\nإنشاء الجلسة هو مجرد \"حجز مكان\". هي الآن في حالة `STOPPED`. لتفعيلها فعلياً، يجب عليك دائماً اتباع عملية `create` باستدعاء فوري لنقطة النهاية `/v2/session/start`. لا تتوقع الحصول على رمز QR أو إرسال رسائل قبل إتمام خطوة \"البدء\".\n",
          "recommendations": [
            "قم بإنشاء الجلسات 'عند الطلب' للحفاظ على نظافة لوحة التحكم وتعظيم استخدام حصتك.",
            "أتبع دائماً استدعاء الإنشاء باستدعاء البدء (Start) لبدء عملية توليد رمز QR.",
            "تأكد من أن مخطط قاعدة البيانات لديك يمكنه التعامل مع سلاسل أبجدية رقمية مكونة من 12 حرفاً لـ 'instance_id'."
          ]
        }
      }
    },
    {
      "path": "/v2/session/start",
      "methods": [
        "POST",
        "GET"
      ],
      "title": "Start Session",
      "category": "Session Management",
      "description": "Boots up the WhatsApp engine for a specific instance. This is the trigger that transitions a session from 'STOPPED' to 'STARTING'.",
      "extraInfo": "\n# Starting the Engine: The Deep Dive into /v2/session/start\n\nIf creating a session is like \"registering a car,\" then calling `/v2/session/start` is the act of \"turning the ignition.\" Without this step, your session is merely a passive record in our database, incapable of communicating with the WhatsApp network. This endpoint is the primary catalyst for the entire automation lifecycle.\n\n---\n\n## 🏗️ What Happens Technically During \"Start\"?\n\nWhen you trigger a start request, Wawp orchestrates several high-concurrency operations:\n1. **Container Awakening**: The isolated environment dedicated to your instance is powered on.\n2. **Library Initialization**: The underlying WhatsApp libraries (Baileys/WAWebJS) are loaded into memory and configured with your instance's specific security parameters.\n3. **Network Handshake**: The engine attempts to establish a secure WebSocket bridge between our high-performance nodes and WhatsApp's official servers.\n4. **Credential Fetching**: If previous authentication exists, the engine attempts to \"resume\" the session. If not, it transitions to a state where it can generate a fresh QR code.\n\n---\n\n## 🛡️ Strategic Best Practices\n\n### 1. The \"State Check\" Prerequisite\nNever call `start` blindly. Always check the current status via [`/v2/session/info`](/v2/session/info) first.\n- **The Ideal Condition**: Only call `start` if the status is **STOPPED**.\n- **The Risk**: Calling `start` on a session that is already **WORKING** can cause a protocol conflict, potentially leading to a temporary disconnection or a \"Session conflict\" notice on the user's mobile device.\n\n### 2. Handling the \"Async\" Nature\nThe `start` command is non-blocking. It will return a success response (200 OK) almost immediately, but the engine may still be \"warming up\" for several seconds.\n- **Developer Action**: Do not poll for a QR code immediately. Implement a 5-10 second \"settle time\" before your application starts aggressively checking for status changes.\n\n### 3. \"Warm Booting\" for Better UX\nIn a production dashboard, don't wait for the user to click \"Connect.\" \n- **The Optimization**: If you detect a user has logged into your CRM and their WhatsApp status is `STOPPED`, call `start` in the background. By the time they click on the WhatsApp integration tab, the engine will be ready to display a QR code, making the experience feel instantaneous.\n\n---\n\n## 💡 Industry-Standard Use Cases\n\n### A. Automated Re-connection Workers\nBuild a background \"Watcher\" service that runs every hour. If it finds a session that should be online (e.g., a \"Gold Tier\" customer) but has a status of **STOPPED**, it should trigger a `start` command automatically.\n\n### B. \"Morning Boot\" Scheduling\nIf your business only operates during specific hours, you can call [`/v2/session/stop`](/v2/session/stop) at night to save system resources and call `start` 30 minutes before your agents start their shift.\n\n---\n\n## ⚠️ Common Errors and Troubleshooting\n\n### \"Instance Not Found\" (404 Not Found)\nThis occurs if the `instance_id` provided is incorrect or has been permanently deleted from our servers. Double-check your database persistence layer.\n\n### Stuck in \"STARTING\"\nOn very rare occasions, a session may hang in the \"STARTING\" state due to a network timeout at the WhatsApp bridge level.\n- **Fix**: If the status remains `STARTING` for more than 45 seconds, we recommend calling the [`/v2/session/restart`](/v2/session/restart) endpoint to force a clean environment reset.\n\n---\n\n## Summary of Responsibilities:\n- Power on the isolated WhatsApp engine.\n- Initiate the connection protocol with WhatsApp servers.\n- Transition the instance state from **STOPPED** to **STARTING** or **WORKING**.\n- Prepare the environment for QR code or Pairing code generation.\n            ",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "The 12-character ID of the instance",
          "example": "Your_Instance_ID"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        }
      },
      "tips": [
        {
          "type": "info",
          "title": "Async Operation",
          "content": "This endpoint returns 'STARTING' immediately. The actual connection happens asynchronously in the background."
        }
      ],
      "recommendations": [
        "Use the /v2/status endpoint to fetch the QR code once the state transitions to 'SCAN_QR_CODE'.",
        "If you receive a 404 error, the 'instance_id' is likely incorrect or the instance was deleted."
      ],
      "responses": [
        {
          "status": 200,
          "description": "Success - Boot Initiated",
          "contentType": "application/json",
          "example": {
            "name": "wawp-84729105",
            "status": "STARTING",
            "config": {
              "webhooks": [],
              "proxy": null
            }
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "بدء الجلسة",
          "description": "تشغيل جلسة واتساب وتجهيزها للاتصال.",
          "tips": [
            {
              "title": "أمان الجلسة",
              "content": "حافظ على سرية معرف الجلسة session_id ولا تشاركه علنًا أبدًا."
            },
            {
              "title": "حالة الجلسة",
              "content": "تحقق من حالة الجلسة بانتظام أو استخدم Webhooks للتحديثات."
            }
          ],
          "args": {
            "instance_id": {
              "description": "معرف النسخة الفريد"
            },
            "access_token": {
              "description": "مفتاح الوصول الخاص بـ API"
            }
          },
          "extraInfo": "\n# تشغيل المحرك: الدليل الكامل لنقطة النهاية /v2/session/start\n\nإذا كان إنشاء الجلسة هو \"حجز السيارة\"، فإن استدعاء `/v2/session/start` هو \"تشغيل المحرك\". بدون هذه الخطوة، تظل الجلسة مجرد سجل في قاعدة البيانات، غير قادرة على الاتصال بواتساب أو معالجة أي بيانات.\n\n---\n\n## ماذا يحدث تقنياً عند النقر على \"بدء\"؟\nعملية البدء هي عملية كثيفة الموارد تتضمن عدة مراحل تقنية دقيقة:\n1. **استدعاء الحاوية (Container Awakening)**: نقوم بإيقاظ البيئة المعزولة المخصصة لجلستك.\n2. **تحميل نظام ملفات واتساب (WhatsApp FileSystem)**: يتم تحميل قاعدة بيانات الـ SQLite المحلية والبيانات التعريفية للمتصفح (Headless Browser) التي تحاكي بيئة واتساب ويب.\n3. **مصافحة الشبكة (Network Handshake)**: يبدأ المحرك في محاولة الاتصال بخوادم واتساب الموزعة عالمياً.\n4. **تحديد الحالة التالية**: \n    *   إذا كانت الجلسة مرتبطة مسبقاً برقم هاتفك، فسينتقل المحرك مباشرة إلى حالة `WORKING`.\n    *   إذا كانت جلسة جديدة، فسيقوم المحرك بتوليد أول رمز QR وينتقل إلى حالة `SCAN_QR_CODE`.\n\n---\n\n## الأوركسترا البرمجية: كيف تدمج \"البدء\" في تطبيقك؟\n\n### التعامل مع الحالات الانتقالية\nأحد الأخطاء الشائعة هو توقع تغير الحالة فوراً بعد استدعاء `start`. تذكر أن الحالة ستكون `STARTING` لعدة ثوانٍ.\n**أفضل ممارسة**:\n- أرسل طلب `start`.\n- ابدأ \"بولينج\" (Polling) خفيف على نقطة النهاية `/v2/session/info` كل 3 ثوانٍ.\n- بمجرد رصد انتقال الحالة إلى `SCAN_QR_CODE` أو `WORKING`، قم بتحديث واجهة المستخدم فوراً.\n\n### استراتيجية \"الإحماء التلقائي\" (Auto-Warmup)\nلتحسين تجربة العميل (UX)، يمكنك البدء بتشغيل المحرك بمجرد دخول المستخدم إلى صفحة الربط، حتى قبل أن يطلب ذلك صراحة. هذا يوفر عليه 10-15 ثانية من وقت الانتظار.\n> [!TIP]\n> لا تقم أبداً بتلقيم استدعاء `start` في كل مرة يفتح فيها المستخدم التطبيق إذا كانت الجلسة في حالة `WORKING` بالفعل؛ فهذا قد يسبب قطع الاتصال النشط وإعادة الاتصال بلا داعٍ.\n\n---\n\n## الأمان والمرونة (Resilience)\n\n### التعامل مع حالات الفشل عند التشغيل\nفي بعض الأحيان، قد يفشل المحرك في البدء بسبب \"تضارب الجلسات\" (Session Conflict) - وهو أن يحاول المحرك العمل بينما هناك نسخة أخرى منه لا تزال عالقة في الذاكرة.\n**الحل**: إذا ظل المحرك في حالة `STARTING` لأكثر من 60 ثانية، استخدم استراتيجية \"الإجبار على الإغلاق ثم البدء\" عبر استدعاء `/v2/session/stop` ثم `/v2/session/start`.\n\n### استمرارية الجلسة (Session Persistence)\nتتميز Wawp بقدرتها العالية على الحفاظ على الربط. بمجرد استدعاء `start` والوصول لحالة `WORKING`، سيحاول النظام إعادة تشغيل نفسه تلقائياً إذا حدث خلل في الخادم المضيف، دون تدخل منك. ومع ذلك، ننصح دائماً بمراقبة الويب هوك الخاص بحالة الجلسة.\n\n---\n\n## حالات استخدام متقدمة\n\n### أ- البوتات المجدولة (Scheduled Bots)\nإذا كان لديك بوت يرسل تقارير صباحية في الساعة 8:00 صباحاً، يمكنك جدولة كود برمجي يستدعي `start` في الساعة 7:55 لضمان أن المحرك \"دافئ\" وجاهز للإرسال في الموعد المحدد.\n\n### ب- أنظمة توفير التكلفة (Cost Efficiency)\nإذا كنت تستخدم Wawp لإرسال حملات تسويقية شهرية فقط، يمكنك إبقاء الجلسات في حالة `STOPPED` طوال الشهر، وتشغيلها فقط في يوم الحملة. هذا يقلل من الاستهلاك العام للموارد ويحافظ على صحة حسابك.\n\n---\n\n## استكشاف الأخطاء (Troubleshooting)\n\n### \"Instance is already starting\" (400 Bad Request)\nهذا يعني أن هناك طلب `start` قيد المعالجة حالياً. لا تقم بإرسال طلبات متكررة؛ فقط انتظر وراقب الحالة عبر `/session/info`.\n\n### \"Session data corrupted\"\nفي حالات نادرة جداً، قد تفشل الجلسة في البدء بسبب تلف ملفات التعريف المحلية. إذا واجهت هذا، الحل الوحيد هو استدعاء `/v2/session/logout` ثم `/v2/session/start` من جديد لمسح البيانات التالفة.\n\n---\n\n## ملخص الخطوات\n1. تأكد أن الحالة `STOPPED`.\n2. استدعِ `/v2/session/start`.\n3. انتظر انتقالات الحالة (`STARTING` -> `SCAN_QR_CODE`/`WORKING`).\n4. ابدأ في استخدام وظائف المراسلة.\n",
          "recommendations": [
            "استخدم نقطة النهاية /v2/session/info لجلب رمز QR بمجرد انتقال الحالة إلى 'SCAN_QR_CODE'.",
            "إذا تلقيت خطأ 404، فمن المحتمل أن يكون 'instance_id' غير صحيح أو أن النسخة قد حذفت."
          ]
        }
      }
    },
    {
      "path": "/v2/session/stop",
      "methods": [
        "POST",
        "GET"
      ],
      "title": "Stop Session",
      "category": "Session Management",
      "description": "Gracefully shuts down the WhatsApp engine for an instance without logging it out. Used to save resources or restart a stuck session.",
      "extraInfo": "\n# Controlled Hibernation: The Power of the /v2/session/stop Endpoint\n\nThe `/v2/session/stop` endpoint is the specialized \"Pause\" button for your WhatsApp instance. Unlike a deletion, which wipes the slate clean, a \"Stop\" command puts your engine into a state of **Controlled Hibernation**. It preserves your authentication data and settings while releasing the underlying compute resources on our high-performance infrastructure.\n\n---\n\n## 🏗️ The Technical Lifecycle of a Stopped Session\n\nWhen you initiate a stop command, Wawp executes a series of clean-up operations:\n1. **Queue Flushing**: The engine attempts to finalize any outbound transmission tasks currently in the buffer.\n2. **Library Shutdown**: The WhatsApp-bridge process is signaled to disconnect and save its internal state.\n3. **Container Freezing**: The isolated environment is paused, meaning it consumes 0% CPU and RAM on our nodes, allowing us to maintain a more efficient and cost-effective ecosystem for you.\n4. **Data Persistence**: Crucially, your **Session Keys** and **Encryption Secrets** are kept in secure persistent storage. This ensures that when you restart, no fresh QR scan is required.\n\n---\n\n## 🛡️ Strategic Best Practices\n\n### 1. Resource Optimization\nIf you are a SaaS provider with thousands of instances, leaving every session running 24/7 is inefficient. \n- **The Idle-Shutdown Strategy**: Monitor your sessions. If a user has been inactive for 72 hours, call `/v2/session/stop`. This keeps your billing predictable and your dashboard organized.\n\n### 2. The \"Clean Reboot\" Sequence\nSometimes, the underlying WhatsApp WebSocket can become \"de-synced\" from the mobile device. \n- **The Fix**: Instead of calling `/v2/session/logout`, try a sequence of [`stop`](/v2/session/stop) followed by [`start`](/v2/session/start). This forces the engine to reload its libraries and establish a fresh connection to the WhatsApp servers, often resolving transient issues.\n\n### 3. Webhook Awareness\nRemember that a **STOPPED** session is effectively \"offline.\" \n- **The Warning**: You will not receive any `message` or `status` webhooks while an instance is stopped. WhatsApp's servers will buffer incoming messages for a limited time (usually 24-72 hours), but prolonged hibernation may lead to message loss once their internal TTL (Time-To-Live) expires.\n\n---\n\n## 💡 Industry-Standard Use Cases\n\n### A. Nightly Maintenance\nFor businesses that operate only during local business hours (e.g., a support desk open 9 AM - 5 PM), you can schedule a script to stop all support instances at 6 PM. This provides a clear \"Offline\" signal to anyone trying to message the business outside of hours.\n\n### B. Scalability Management\nIn a multi-agent environment, where agents log in and out throughout the day, use this endpoint to stop an agent's dedicated instance when they clock out. This ensures that no automated replies or background processes are running while the human agent is away.\n\n---\n\n## ⚠️ Common Pitfalls and Troubleshooting\n\n### \"Instance Not Found\" (404)\nThis error occurs if the session was deleted before the stop command was issued. Ensure your front-end logic respects the sequence of operations.\n\n### Delay in Restarting\nAfter calling `stop`, we recommend waiting at least 3 seconds before calling [`start`](/v2/session/start) again. This gives our cloud orchestrator enough time to fully decommission the previous container before Spinning up a new one.\n\n---\n\n## Summary of Capabilities:\n- Gracefully disconnect from WhatsApp servers.\n- Preserve all authentication and QR scan data for future use.\n- Optimize infrastructure resource consumption.\n- Provide a \"Pause\" state for maintenance or off-peak hours.\n            ",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "The 12-character ID of the instance",
          "example": "Your_Instance_ID"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        }
      },
      "tips": [
        {
          "type": "info",
          "title": "Data Persistence",
          "content": "Stopping a session DOES NOT delete your authentication data. You can restart it anytime without re-scanning the QR code."
        }
      ],
      "recommendations": [
        "Use this endpoint to reboot a session if it gets stuck.",
        "Implement an idle-timer in your app to auto-stop sessions that haven't been used for 24+ hours."
      ],
      "responses": [
        {
          "status": 200,
          "description": "Success - Session Stopped",
          "contentType": "application/json",
          "example": {
            "name": "wawp-84729105",
            "status": "STOPPED",
            "config": {
              "webhooks": [],
              "proxy": null
            }
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "إيقاف الجلسة",
          "description": "إغلاق محرك واتساب وتحرير الموارد.",
          "args": {
            "instance_id": {
              "description": "معرف النسخة الفريد"
            },
            "access_token": {
              "description": "مفتاح الوصول الخاص بـ API"
            }
          },
          "extraInfo": "\n# إدارة الموارد: الدليل الكامل لإيقاف الجلسة /v2/session/stop\n\nتعد نقطة النهاية `/v2/session/stop` أداة حيوية لإدارة كفاءة نظامك وتوفير موارد الحوسبة. هي تمثل وضع الجلسة في \"حالة سبات\" (Hibernation)، حيث نقوم بإغلاق كافة العمليات النشطة وتحرير الذاكرة العشوائية (RAM) والمعالج (CPU) المخصصين لهذه النسخة، مع الحفاظ الكامل على سلامة بيانات المصادقة.\n\n---\n\n## فلسفة \"الإيقاف النظيف\" مقابل \"الحذف\"\nمن المهم جداً التمييز بين الإيقاف (`stop`) والحذف (`delete`).\n- **الإيقاف (`stop`)**: يحافظ على \"شخصية\" الجلسة. عندما تعيد تشغيلها لاحقاً، ستظل مرتبطة بنفس رقم الهاتف ولن تحتاج لمسح رمز QR جديد. هو إجراء مؤقت للصيانة وتوفير الموارد.\n- **الحذف (`delete`)**: إجراء مدمر يمسح كل شيء.\n\n### لماذا يجب عليك استخدام الإيقاف بانتظام؟\n1. **استقرار الأداء**: الجلسات التي تعمل لأسابيع طويلة دون توقف قد تواجه أحياناً تسرباً في الذاكرة (Memory Leaks) بسبب طبيعة متصفح Headless Chrome. الإيقاف ثم التشغيل ينظف الذاكرة تماماً.\n2. **الامتثال لقواعد واتساب**: إبقاء الجلسة متصلة 24/7 بينما لا يوجد نشاط حقيقي قد يثير أحياناً أنظمة الرقابة الآلية لدى واتساب. الإيقاف في فترات الخمول الطويلة يحاكي السلوك البشري الطبيعي.\n\n---\n\n## الأوركسترا التقنية: ماذا يحدث عند طلب الإيقاف؟\nعند إرسال طلب إلى `/v2/session/stop`، يقوم نظام Wawp بالخطوات التالية:\n1. **إيقاف الاستلام (Intercept Stop)**: نتوقف فوراً عن استقبال أي رسائل جديدة من خوادم واتساب.\n2. **مزامنة البيانات (State Sync)**: نقوم بحفظ الحالة النهائية لقاعدة البيانات المحلية للتأكد من عدم فقدان أي \"علامات قراءة\" (Seen Marks) أو تعديلات أخيرة.\n3. **قتل العمليات (Process Termination)**: نرسل إشارة `SIGTERM` للمتصفح الخفي لإغلاقه بشكل آمن.\n4. **تحرير الحاوية**: يتم وضع الحاوية البرمجية في حالة \"متوقف\"، مما يقلل استهلاك موارد الخادم المضيف إلى الصفر تقريباً.\n\n---\n\n## استراتيجيات التشغيل الذكي\n\n### 1. مؤقت الخمول (Idle Timeout)\nأحد أفضل الأنماط المعمارية هو تنفيذ \"مؤقت خمول\" في تطبيقك.\n**مثال**: إذا لم يقم المستخدم بإرسال رسالة ولم يستقبل النظام أي رسالة لهذا المستخدم خلال آخر 12 ساعة، قم تلقائياً باستدعاء `/v2/session/stop`. هذا يضمن أن خوادمك تعمل دائماً بأقصى كفاءة للجلسات النشطة فعلياً.\n\n### 2. الصيانة المجدولة\nننصح بجدولة عملية إيقاف وتشغيل (Stop -> Start) لجميع الجلسات مرة كل أسبوع في ساعات الفجر. هذا الإجراء البسيط يضمن تحديث كافة الكاشات (Caches) وحل أي مشاكل تقنية خفية قد تكون تراكمت.\n\n---\n\n## الأمان والاعتبارات الهامة\n\n### تفادي فقدان البيانات\nقبل استدعاء `stop` عبر الكود الخاص بك، تأكد من أنك قمت بمعالجة كافة أحداث الويب هوك (Webhooks) الواردة. في اللحظة التي تتوقف فيها الجلسة، لن تصلك أي تحديثات حتى يتم التشغيل مرة أخرى.\n\n### حالة الطوارئ\nإذا واجهت جلسة \"مجمدة\" (Frozen) لا تستجيب لأوامر الإرسال ولا ترسل ويب هوك، فإن استدعاء `/v2/session/stop` هو الخطوة الأولى لاستعادة السيطرة. هو بمثابة \"إعادة تعيين قسري\" للبيئة البرمجية.\n\n---\n\n## استكشاف الأخطاء (Troubleshooting)\n\n### الخطأ: \"Instance is already stopped\" (400)\nهذا يعني أن الطلب وصل ولكن الجلسة ليست في حالة تشغيل. يمكنك تجاهل هذا الخطأ في نظامك لأنه يعني الوصول للنتيجة المطلوبة.\n\n### الخطأ: \"Stop request timed out\"\nفي حالات نادرة، قد يرفض متصفح Chrome الإغلاق بسبب عملية معلقة. إذا حدث هذا، انتظر 30 ثانية ثم حاول مرة أخرى. نظامنا يمتلك \"قاتل عمليات\" تلقائي يعمل في الخلفية لمعالجة هذه الحالات.\n\n---\n\n## قائمة التحقق للإيقاف الناجح:\n1. تحقق أن الحالة الحالية هي `WORKING` أو `SCAN_QR_CODE` أو `STARTING`.\n2. استدعِ `/v2/session/stop`.\n3. راقب الحالة عبر `/v2/session/info` حتى تصبح `STOPPED`.\n4. اعرض حالة \"غير متصل\" أو \"في وضع السبات\" لمستخدمك النهائي.\n",
          "recommendations": [
            "استخدم نقطة النهاية هذه لإيقاف الجلسة إذا علقت، ثم أعد تشغيلها.",
            "قم بتنفيذ مؤقت خمول في تطبيقك لإيقاف الجلسات التي لم تستخدم لأكثر من 24 ساعة تلقائياً."
          ],
          "tips": [
            {
              "title": "استمرار البيانات",
              "content": "إيقاف الجلسة لا يحذف بيانات المصادقة. يمكنك إعادة التشغيل في أي وقت دون إعادة مسح QR."
            }
          ]
        }
      }
    },
    {
      "path": "/v2/session/restart",
      "methods": [
        "POST",
        "GET"
      ],
      "title": "Restart Session",
      "category": "Session Management",
      "description": "Reboots the WhatsApp instance. Useful for fixing stuck sessions or applying settings.",
      "extraInfo": "\n# The Self-Healing Mechanism: Mastering the /v2/session/restart Endpoint\n\nThe `/v2/session/restart` endpoint is the specialized \"Soft Reboot\" tool for your WhatsApp instance. In the complex world of WhatsApp automation—where network jitter, WebSocket timeouts, and engine de-syncs are common—a well-implemented restart strategy is the difference between a fragile integration and a production-grade communication system.\n\n---\n\n## 🏗️ The Anatomy of a Restart Orchestration\n\nWhen you call `restart`, Wawp performs an atomic \"Stop and Start\" sequence within our cloud infrastructure:\n1. **Engine Shutdown**: The active WhatsApp-bridge process is signaled to close its connections cleanly and save its current authentication state to persistent storage.\n2. **Environment Flush**: The temporary caches and buffer memory of the isolated container are cleared to resolve any memory leaks or hanging processes.\n3. **Engine Boot**: A fresh bridge process is launched using the previously saved authentication keys.\n4. **Resumption**: The engine automatically attempts to re-establish the encrypted handshake with WhatsApp's servers.\n\n---\n\n## 🛡️ Strategic Best Practices\n\n### 1. The \"Auto-Healing\" Pattern\nDon't wait for a human to notice a problem. Your application should monitor the delivery status of outbound messages.\n- **The Recovery Flow**: If you detect three consecutive \"Message Failed\" errors or if the [`/v2/session/info`](/v2/session/info) endpoint shows a status of `FAILED`, trigger a `/v2/session/restart` automatically. A single restart resolves approximately 85% of transient connection issues.\n\n### 2. The 30-Second Stabilization Window\nWhile the API returns a success message (200 OK) almost instantly, the internal handshake takes time.\n- **Developer Action**: Implement a \"Quiet Period\" after a restart. We recommend waiting at least 30 seconds before resuming high-frequency automated message campaigns. This allows the engine to fully synchronize the message history and stabilize the WebSocket connection.\n\n### 3. Avoiding the \"Restart Loop\"\nA common mistake is restarting an instance every few seconds if it's not working.\n- **The Limit**: If a restart doesn't transition the session to `WORKING` within 60 seconds, do not restart again immediately. Instead, check the [`/v2/session/info`](/v2/session/info) response. If it shows **SCAN_QR_CODE**, it means the user has been logged out from the mobile app, and no amount of restarting will fix it—they must scan the QR code again.\n\n---\n\n## 💡 Industry-Standard Use Cases\n\n### A. Maintenance \"Pulse\"\nFor mission-critical bots (e.g., 24/7 bank alert systems), schedule a weekly restart during low-traffic windows (e.g., Sunday at 3 AM). This ensures the engine is always running on fresh resources and clears any long-term memory accumulation.\n\n### B. Post-Update Synchronization\nIf you update high-level instance configurations (like changing your Webhook URL or adding a new proxy), a `restart` is the cleanest way to ensure all underlying library settings are refreshed and applied across the environment.\n\n---\n\n## ⚠️ Common Pitfalls and Troubleshooting\n\n### Interruption of Active Queues\nRestarting acts as a \"hard stop\" for the internal message queue. If you have 500 messages currently being processed for delivery, they will be purged from the transient buffer. Ensure your campaign logic can handle \"Resuming\" from where it left off by tracking message IDs in your own database.\n\n### Stuck in \"STARTING\" post-restart\nThis is usually caused by a conflict with the previous process. Wait 15 seconds and try one more restart. If the issue persists, use the [`/v2/session/stop`](/v2/session/stop) command, wait 5 seconds, and then call [`/v2/session/start`](/v2/session/start) for a full lifecycle reset.\n\n---\n\n## Summary of Capabilities:\n- Perform an atomic reboot of the isolated engine.\n- Resolve 85% of transient connectivity and de-sync issues.\n- Preserve all session data and QR scan history.\n- Refresh container resources without requiring user interaction.\n            ",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "The 12-character ID of the instance",
          "example": "Your_Instance_ID"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        }
      },
      "tips": [
        {
          "type": "info",
          "title": "Zero Data Loss",
          "content": "Restarting is safe. It does not delete your session data or log you out."
        }
      ],
      "recommendations": [
        "Use this as a first troubleshooting step before deleting an instance.",
        "Wait at least 30 seconds after a restart before sending messages."
      ],
      "responses": [
        {
          "status": 200,
          "description": "Success - Reboot Initiated",
          "contentType": "application/json",
          "example": {
            "name": "wawp-84729105",
            "status": "STARTING",
            "config": {
              "webhooks": [],
              "proxy": null
            }
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "إعادة تشغيل الجلسة",
          "description": "إعادة تشغيل محرك الواتساب وحل التعليق.",
          "args": {
            "instance_id": {
              "description": "معرف النسخة الفريد"
            },
            "access_token": {
              "description": "مفتاح الوصول"
            }
          },
          "extraInfo": "\n# آلية الاستعادة الذاتية: إتقان نقطة النهاية /v2/session/restart\n\nتعد نقطة النهاية `/v2/session/restart` أداة \"إعادة التشغيل الناعم\" (Soft Reboot) المتخصصة لنسخة واتساب الخاصة بك. في العالم المعقد لأتمتة واتساب - حيث يعد تذبذب الشبكة، وانقطاع اتصال WebSocket، وفقدان تزامن المحرك أمراً شائعاً - تعتبر استراتيجية إعادة التشغيل المنفذة جيداً هي الفارق بين تكامل هش ونظام اتصالات بمستوى المؤسسات.\n\n---\n\n## تشريح عملية إعادة التشغيل\nعند استدعاء `restart`، يقوم Wawp بتنفيذ تتابع ذري (Atomic) لعملية \"إيقاف وتشغيل\" داخل بنيتنا التحتية السحابية:\n1. **إغلاق المحرك**: يتم إرسال إشارة لعملية جسر واتساب النشطة لغلق اتصالاتها بشكل نظيف وحفظ حالة المصادقة الحالية في وحدة التخزين الدائمة.\n2. **تطهير البيئة**: يتم مسح الذاكرة المؤقتة (Caches) وذاكرة التخزين المؤقت للحاوية المعزولة لحل أي تسرب في الذاكرة أو عمليات معلقة.\n3. **تشغيل المحرك**: يتم إطلاق عملية جسر جديدة باستخدام مفاتيح المصادقة المحفوظة مسبقاً.\n4. **الاستئناف**: يحاول المحرك تلقائياً إعادة إنشاء المصافحة المشفرة مع خوادم واتساب.\n\n---\n\n## أفضل الممارسات الاستراتيجية\n\n### 1. نمط \"الاستشفاء الآلي\" (Auto-Healing)\nلا تنتظر حتى يلاحظ العميل وجود مشكلة. يجب أن يراقب تطبيقك حالة تسليم الرسائل الصادرة.\n- **سير عمل الاستعادة**: إذا اكتشفت ثلاثة أخطاء متتالية في \"فشل إرسال الرسالة\" أو إذا أظهرت نقطة النهاية [`/v2/session/info`](/v2/session/info) حالة `FAILED`، فقم بتفعيل `/v2/session/restart` تلقائياً. إعادة تشغيل واحدة تحل ما يقرب من 85% من مشاكل الاتصال العابرة.\n\n### 2. نافذة الاستقرار لمدة 30 ثانية\nعلى الرغم من أن API تعيد رسالة نجاح (200 OK) بشكل فوري تقريباً، إلا أن المصافحة الداخلية تستغرق وقتاً.\n- **إجراء المطور**: نفذ \"فترة هدوء\" بعد إعادة التشغيل. نوصي بالانتظار لمدة 30 ثانية على الأقل قبل استئناف حملات الرسائل المؤتمتة عالية الكثافة. هذا يسمح للمحرك بمزامنة سجل الرسائل بالكامل واستقرار اتصال WebSocket.\n\n### 3. تجنب \"حلقة إعادة التشغيل\" (Restart Loop)\nمن الأخطاء الشائعة إعادة تشغيل النسخة كل بضع ثوانٍ إذا كانت لا تعمل.\n- **الحد المسموح**: إذا لم تؤدِ إعادة التشغيل إلى نقل الجلسة لحالة `WORKING` خلال 60 ثانية، فلا تقم بإعادة التشغيل مرة أخرى فوراً. بدلاً من ذلك، افحص استجابة [`/v2/session/info`](/v2/session/info). إذا أظهرت **SCAN_QR_CODE**، فهذا يعني أن المستخدم قد سجل خروجه من تطبيق الهاتف، ولن ينفع أي قدر من إعادة التشغيل - يجب عليهم مسح رمز QR مرة أخرى.\n\n---\n\n## حالات استخدام معيارية\n\n### أ- \"نبض\" الصيانة\nبالنسبة للبوتات الهامة (مثل أنظمة تنبيهات البنوك التي تعمل 24/7)، قم بجدولة إعادة تشغيل أسبوعية خلال فترات انخفاض حركة المرور (مثلاً: الأحد الساعة 3 فجراً). هذا يضمن تشغيل المحرك دائماً بموارد متجددة ويمسح أي تراكم لذاكرة المدى الطويل.\n\n### ب- المزامنة بعد التحديث\nإذا قمت بتحديث إعدادات النسخة عالية المستوى (مثل تغيير رابط الويب هوك أو إضافة بروكسي جديد)، فإن `restart` هي أنظف طريقة لضمان تحديث كافة إعدادات المكتبة الأساسية وتطبيقها في كامل البيئة.\n\n---\n\n## استكشاف الأخطاء وإصلاحها (Troubleshooting)\n\n### انقطاع الطوابير النشطة\nتعمل إعادة التشغيل كـ \"إيقاف قسري\" لطابور الرسائل الداخلي. إذا كان لديك 500 رسالة قيد المعالجة للتسليم، فسيتم مسحها من الذاكرة المؤقتة. تأكد من أن منطق حملتك يمكنه التعامل مع \"الاستئناف\" من حيث توقف عن طريق تتبع معرفات الرسائل في قاعدة بياناتك الخاصة.\n\n### التعليق في حالة \"STARTING\" بعد إعادة التشغيل\nيحدث هذا عادة بسبب تعارض مع العملية السابقة. انتظر 15 ثانية وجرب إعادة تشغيل واحدة أخرى. إذا استمرت المشكلة، استخدم أمر [`/v2/session/stop`](/v2/session/stop)، انتظر 5 ثوانٍ، ثم استدعِ [`/v2/session/start`](/v2/session/start) لإعادة ضبط دورة الحياة بالكامل.\n\n---\n\n## ملخص الوظائف:\n- تنفيذ إعادة تشغيل ذرية للمحرك المعزول.\n- حل 85% من مشاكل الاتصال وفقدان التزامن العابرة.\n- الحفاظ على جميع بيانات الجلسة وسجل مسح QR.\n- تحديث موارد الحاوية دون الحاجة لتفاعل المستخدم.\n",
          "recommendations": [
            "استخدم هذا الخيار كخطوة أولى لاستكشاف الأخطاء قبل حذف النسخة.",
            "انتظر 30 ثانية على الأقل بعد إعادة التشغيل قبل إرسال الرسائل."
          ],
          "tips": [
            {
              "title": "لا فقدان للبيانات",
              "content": "إعادة التشغيل آمنة. لا تحذف بيانات جلستك ولا تسجل خروجك."
            }
          ]
        }
      }
    },
    {
      "path": "/v2/session/logout",
      "methods": [
        "POST",
        "GET"
      ],
      "title": "Logout Session",
      "category": "Session Management",
      "description": "Logs the instance out of WhatsApp. This removes the paired device link but keeps the instance alive in a 'SCAN_QR_CODE' state.",
      "extraInfo": "\n# Starting Fresh: The Deep Dive into /v2/session/logout\n\nThe `/v2/session/logout` endpoint is a critical component of session lifecycle management. It is not merely a \"disconnect\" button; it is a specialized command that communicates directly with WhatsApp's official servers to signal a clean **Unpairing** (Unlinking) of the device. Mastering this endpoint is the key to building secure, multi-account, and user-friendly automation platforms.\n\n---\n\n## 🏗️ The Technical Orchestration of a Logout\n\nWhen you trigger a logout, Wawp executes a series of coordinated steps across our infrastructure:\n1. **Unlink Signal**: The engine sends a specific \"Unpair\" message to the WhatsApp WebSocket. This ensures that the device is instantly removed from the \"Linked Devices\" list on the user's mobile phone.\n2. **State Purge**: The isolated container wipes the current encryption keys and session tokens from its active memory, ensuring no unauthorized access can persist.\n3. **Transition to Scan**: The instance is **not** deleted. Instead, it transitions immediately from **WORKING** to **SCAN_QR_CODE**, effectively returning the session to \"Square One\" and making it ready for a fresh link.\n4. **Configuration Retention**: Importantly, all your instance-level settings (like Webhook URLs or Proxy configurations) remain intact. Only the WhatsApp identity is removed.\n\n---\n\n## 🛡️ Strategic Best Practices\n\n### 1. The \"Account Switching\" Pattern\nLogout is the correct way to handle situations where a user wants to change the WhatsApp number associated with an instance.\n- **The Workflow**: Do not delete the instance and create a new one. Simply call `logout`. This preserves the `instance_id` and the API endpoint structure in your own backend while allowing the user to scan a different phone.\n\n### 2. Security and Data Privacy\nIn any SaaS platform, security is paramount.\n- **The Best Practice**: Encourage your users to use the \"Log Out\" button whenever they are performing a security audit or decommissioning a specific employee's dashboard access. This provides them with peace of mind that the link has been truly severed at the protocol level.\n\n### 3. Graceful Handling of Sudden Disconnects\nUsers can manually log out of your session directly from their mobile app's \"Linked Devices\" settings.\n- **The Strategy**: Your application should listen for the `DISCONNECTED` or `LOGOUT` event via our status webhooks. When this occurs, you should update your UI to show a \"Disconnected\" state and prompt the user to re-scan the QR code.\n\n---\n\n## 💡 Industry-Standard Use Cases\n\n### A. Team Rotation Dashboards\nIf you manage a business where different agents use the same WhatsApp number at different times of the day, you can use `logout` to ensure that a previous agent's session is completely terminated before the next agent takes over.\n\n### B. Self-Service Troubleshooting\nAdd a \"Reset Connection\" button in your user settings. Often, if a user experiences message delivery delays or sync issues, a clean `logout` and re-link will reset the internal WhatsApp state and solve the problem without requiring manual support intervention.\n\n---\n\n## ⚠️ Common Pitfalls and Troubleshooting\n\n### Sync Latency\nOccasionally, the WhatsApp mobile app might continue to show the \"Linked Device\" as active for a few seconds after the API call. This is due to internal WhatsApp sync latency. Rest assured, the API has severed the link, and the phone's UI will eventually catch up.\n\n### Calling Logout on a Stopped Session\nYou cannot execute a clean protocol logout if the engine is **STOPPED**.\n- **Fix**: The engine must be in a **STARTING** or **WORKING** state to communicate the logout signal to WhatsApp. If the session is stopped, you must call [`/v2/session/start`](/v2/session/start) first, or simply perform a [`/v2/session/delete`](/v2/session/delete) if you wish to wipe everything.\n\n---\n\n## Summary of Capabilities:\n- Sever the secure link with the WhatsApp mobile app.\n- Transition the instance to a state ready for a fresh QR scan.\n- Ensure data privacy by purging encryption keys from memory.\n- Provide a clean \"Start Over\" mechanism without losing instance configurations.\n            ",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "The ID of the instance to logout",
          "example": "Your_Instance_ID"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        }
      },
      "tips": [
        {
          "type": "info",
          "title": "Re-Pairing",
          "content": "After logout, the instance ID remains valid. You do not need to create a new session."
        }
      ],
      "recommendations": [
        "Use this endpoint to allow users to switch accounts easily.",
        "Always confirm with the user before logging out, as they will need physical access to the phone to reconnect."
      ],
      "responses": [
        {
          "status": 200,
          "description": "Success - Logged Out",
          "contentType": "application/json",
          "example": {
            "name": "wawp-84729105",
            "status": "SCAN_QR_CODE",
            "instance_id": "3EB0BCB2E3D4"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "تسجيل الخروج من الجلسة",
          "description": "تسجيل الخروج من جلسة واتساب نشطة.",
          "args": {
            "instance_id": {
              "description": "معرف النسخة الفريد"
            },
            "access_token": {
              "description": "مفتاح الوصول"
            }
          },
          "extraInfo": "\n# البداية من جديد: الدليل الشامل لنقطة النهاية /v2/session/logout\n\nتعد نقطة النهاية `/v2/session/logout` مكوناً حيوياً في إدارة دورة حياة الجلسة. هي ليست مجرد زر \"قطع اتصال\"؛ بل هي أمر متخصص يتواصل مباشرة مع خوادم واتساب الرسمية للإشارة إلى **فك ارتباط** (Unlinking) نظيف للجهاز. إتقان هذه النقطة هو المفتاح لبناء منصات أتمتة آمنة، متعددة الحسابات، وسهلة الاستخدام.\n\n---\n\n## كيف تتم عملية تسجيل الخروج تقنياً؟\nعندما تقوم باستدعاء أمر تسجيل الخروج، يقوم نظام Wawp بتنفيذ سلسلة من الخطوات المنسقة:\n1. **إشارة فك الارتباط**: يرسل المحرك رسالة \"فك ارتباط\" محددة إلى خادم واتساب. يضمن هذا إزالة الجهاز فوراً من قائمة \"الأجهزة المرتبطة\" (Linked Devices) في هاتف المستخدم المحمول.\n2. **تطهير الحالة**: تقوم الحاوية المعزولة بمسح مفاتيح التشفير ورموز الجلسة الحالية من ذاكرتها النشطة، مما يضمن عدم استمرار أي وصول غير مصرح به.\n3. **الانتقال لغرض المسح**: **لا** يتم حذف الجلسة. بدلاً من ذلك، تنتقل فوراً من حالة **WORKING** إلى **SCAN_QR_CODE**، مما يعيد الجلسة إلى نقطة الصفر وجعلها جاهزة لربط جديد.\n4. **الاحتفاظ بالإعدادات**: بشكل هام، تظل جميع إعداداتك على مستوى النسخة (مثل روابط الويب هوك أو إعدادات البروكسي) سليمة. يتم فقط إزالة هوية الواتساب.\n\n---\n\n## أفضل الممارسات الاستراتيجية\n\n### 1. نمط \"تبديل الحسابات\"\nتسجيل الخروج هو الطريقة الصحيحة للتعامل مع المواقف التي يريد فيها المستخدم تغيير رقم الواتساب المرتبط بالنسخة.\n- **سير العمل**: لا تقم بحذف النسخة وإنشاء واحدة جديدة. ببساطة استدعِ `logout`. هذا يحافظ على `instance_id` وهيكل الروابط البرمجية في نظامك الخلفي مع السماح للمستخدم بمسح هاتف مختلف.\n\n### 2. الأمن وخصوصية البيانات\nفي أي منصة SaaS، يعتبر الأمن أمراً بالغ الأهمية.\n- **أفضل ممارسة**: شجع مستخدميك على استخدام زر \"تسجيل الخروج\" عندما يقومون بمراجعة أمنية أو عند إنهاء وصول موظف معين للوحة التحكم. هذا يمنحهم راحة البال بأن الرابط قد تم قطعه فعلياً على مستوى البروتوكول.\n\n### 3. التعامل مع قطع الاتصال المفاجئ\nيمكن للمستخدمين تسجيل الخروج من جلستك يدوياً مباشرة من تطبيق واتساب على هواتفهم (إعدادات الأجهزة المرتبطة).\n- **الاستراتيجية**: يجب أن يستمع تطبيقك لحدث `DISCONNECTED` أو `LOGOUT` عبر الويب هوك الخاص بالحالة. عندما يحدث هذا، قم بتحديث واجهتك لتظهر حالة \"غير متصل\" واطلب من المستخدم إعادة مسح رمز QR.\n\n---\n\n## حالات استخدام معيارية\n\n### أ- لوحات توزيع المهام بين الفرق\nإذا كنت تدير عملاً حيث يستخدم وكلاء مختلفون نفس رقم الواتساب في أوقات مختلفة، يمكنك استخدام `logout` لضمان إنهاء جلسة الوكيل السابق تماماً قبل أن يتسلم الوكيل التالي العمل.\n\n### ب- استكشاف الأخطاء ذاتياً\nأضف زر \"إعادة ضبط الاتصال\" في إعدادات المستخدم. غالباً، إذا واجه المستخدم تأخيراً في وصول الرسائل أو مشاكل في المزامنة، فإن عملية تسجيل خروج نظيفة ثم إعادة ربط ستقوم بإعادة ضبط حالة واتساب الداخلية وحل المشكلة دون الحاجة لتدخل الدعم الفني.\n\n---\n\n## استكشاف الأخطاء وإصلاحها (Troubleshooting)\n\n### تأخر المزامنة\nأحياناً، قد يستمر تطبيق واتساب على الهاتف في إظهار \"الجهاز المرتبط\" كنشط لبضع ثوانٍ بعد استدعاء API. هذا يرجع إلى تأخر المزامنة الداخلي في واتساب. اطمئن، لقد قامت API بقطع الرابط، وستقوم واجهة الهاتف بتحديث نفسها في النهاية.\n\n### تسجيل الخروج من جلسة متوقفة\nلا يمكنك تنفيذ تسجيل خروج نظيف إذا كان المحرك في حالة **STOPPED**.\n- **الحل**: يجب أن يكون المحرك في حالة **STARTING** أو **WORKING** لإرسال إشارة تسجيل الخروج لواتساب. إذا كانت الجلسة متوقفة، يجب استدعاء `/v2/session/start` أولاً، أو القيام بعملية `/v2/session/delete` إذا كنت ترغب في مسح كل شيء.\n\n---\n\n## ملخص الوظائف:\n- قطع الرابط الآمن مع تطبيق واتساب على الهاتف.\n- نقل النسخة إلى حالة جاهزة لمسح رمز QR جديد.\n- ضمان خصوصية البيانات بتطهير مفاتيح التشفير من الذاكرة.\n- توفير آلية \"البدء من جديد\" دون فقدان إعدادات النسخة.\n",
          "recommendations": [
            "استخدم نقطة النهاية هذه للسماح للمستخدمين بتغيير الحسابات بسهولة.",
            "أكد دائماً مع المستخدم قبل تسجيل الخروج، حيث سيحتاجون لوجود الهاتف فعلياً لإعادة الاتصال."
          ],
          "tips": [
            {
              "title": "إعادة الربط",
              "content": "بعد تسجيل الخروج، يظل معرف النسخة (Instance ID) صالحاً. لا تحتاج لإنشاء جلسة جديدة."
            }
          ]
        }
      }
    },
    {
      "path": "/v2/session/delete",
      "methods": [
        "DELETE"
      ],
      "title": "Delete Session",
      "category": "Session Management",
      "description": "Permanently deletes a WhatsApp session locally and from the server. This action is irreversible.",
      "extraInfo": "\n# The Point of No Return: Mastering the /v2/session/delete Endpoint\n\nThe `/v2/session/delete` endpoint is the most decisive action in our API suite. It is not merely a shutdown command; it is an instruction for the **Atomic Deconstruction** of the instance. It permanently removes the isolated environment, all associated session data, and the authentication credentials from our high-performance infrastructure.\n\n---\n\n## 🏗️ The Anatomy of a Clean Deletion\n\nWhen you trigger a deletion, Wawp orchestrates several high-concurrency cleanup tasks in milliseconds:\n1. **Container Termination**: The active engine process is signaled to shut down immediately.\n2. **Data Purge**: All transient files, message buffers, and encryption keys stored in the instance's isolated directory are wiped from our disks.\n3. **Resource Recovery**: The RAM and CPU overhead allocated to that session is instantly released and returned to the server pool, allowing for fresh allocations.\n4. **Credential Expiry**: The `instance_id` and `session_name` are decoupled from your account, and any future requests using those identifiers will result in a `404 Not Found` error.\n\n---\n\n## 🛡️ Strategic Best Practices\n\n### 1. The \"Danger Zone\" UX\nBecause this action is permanent, it must be protected by significant UI guardrails.\n- **The Best Practice**: Never trigger a deletion from a single click. Implement a \"Danger Zone\" in your dashboard that requires the user to type \"DELETE\" or the instance ID to confirm their intent. This prevents catastrophic data loss from accidental clicks.\n\n### 2. The \"Logout First\" Recommendation\nWhile deletion severs the bridge, it doesn't always signal the mobile phone to \"Unpair\" if the engine is stopped.\n- **The Strategy**: For the most professional experience, call [`/v2/session/logout`](/v2/session/logout) before calling `delete`. This ensures that the device is cleanly removed from the \"Linked Devices\" list on the user's phone, preventing \"Ghost Device\" entries that can clutter the WhatsApp app UI.\n\n### 3. Subscription and Churn Lifecycle\nIntegrate this endpoint into your platform's subscription management.\n- **The Workflow**: If a user cancels their plan or fails to pay, your system should automatically call `/v2/session/delete` after a grace period. This ensures your instance quota remains available for active, paying customers.\n\n---\n\n## 💡 Industry-Standard Use Cases\n\n### A. Data Compliance (GDPR/SOC2)\nIf your application handles highly sensitive data, use the delete endpoint to ensure that once a customer interaction is finished, no residue of their session remains on our servers. This is a core part of building a \"Zero-Trust\" communication architecture.\n\n### B. Development and Testing\nDuring the development phase, you may frequently create and destroy instances while testing your integration. Using the delete endpoint allows you to keep your test environment clean and avoid hitting your plan's quota limits.\n\n---\n\n## ⚠️ Common Pitfalls and Troubleshooting\n\n### \"Instance Not Found\" (404)\nThis occurs if the deletion has already been processed or if the ID provided is incorrect. In your backend, you should treat a 404 response to a delete request as a \"de-facto success,\" meaning the instance is indeed gone.\n\n### Is Recovery Possible?\n**No.** We prioritize data privacy and server efficiency. Once the delete command is executed, the encryption keys are purged from our secure persistent storage. There is no \"Trash Bin\" or \"Restore\" feature. Always ensure your internal database is updated to reflect that the session no longer exists.\n\n---\n\n## Summary of Capabilities:\n- Permanently decommission an isolated engine.\n- Purge all encryption keys and transient data for maximum privacy.\n- Free up instance slots within your Wawp plan quota.\n- Ensure a clean architectural slate for future provisioning.\n            ",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "The 12-character ID of the instance to delete",
          "example": "Your_Instance_ID"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        }
      },
      "tips": [
        {
          "type": "warning",
          "title": "No Undo",
          "content": "There is no 'trash bin'. Deleted sessions cannot be recovered."
        }
      ],
      "recommendations": [
        "Always prompt for confirmation in your UI before triggering this endpoint.",
        "Use /v2/logout before /v2/delete to ensure the session is properly closed on the phone side."
      ],
      "responses": [
        {
          "status": 200,
          "description": "Success - Session Deleted",
          "contentType": "application/json",
          "example": {
            "name": "wawp-84729105",
            "status": "DELETED",
            "instance_id": "3EB0BCB2E3D4"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "حذف الجلسة",
          "description": "حذف الجلسة نهائياً من النظام.",
          "args": {
            "instance_id": {
              "description": "معرف النسخة الفريد"
            },
            "access_token": {
              "description": "مفتاح الوصول"
            }
          },
          "extraInfo": "\n# نقطة اللاعودة: إتقان نقطة النهاية /v2/session/delete\n\nتعد نقطة النهاية `/v2/session/delete` الإجراء الأكثر حسماً في واجهة برمجة التطبيقات الخاصة بنا. هي ليست مجرد أمر إيقاف تشغيل؛ بل هي تعليمات لـ **التفكيك الذري** للنسخة. هي تقوم بحذف البيئة المعزولة نهائياً، وجميع بيانات الجلسة المرتبطة بها، ورموز المصادقة من بنيتنا التحتية عالية الأداء.\n\n---\n\n## تشريح الحذف النظيف\nعند تفعيل الحذف، يقوم Wawp بتنفيذ عدة مهام تنظيف عالية التزامن في أجزاء من الثانية:\n1. **إنهاء الحاوية**: يتم إرسال إشارة لمحرك التشغيل النشط للإغلاق الفوري.\n2. **تطهير البيانات**: يتم مسح كافة الملفات المؤقتة، وطوابير الرسائل، ومفاتيح التشفير المخزنة في الدليل المعزول للنسخة من أقراصنا تماماً.\n3. **استعادة الموارد**: يتم تحرير الذاكرة العشوائية (RAM) وحمل المعالج (CPU) المخصص لتلك الجلسة فوراً وإعادتهما إلى مجمع موارد السيرفر، مما يسمح بتخصيصات جديدة.\n4. **انتهاء صلاحية المعرفات**: يتم فصل `instance_id` و `session_name` عن حسابك، وأي طلبات مستقبلية باستخدام هذه المعرفات ستؤدي إلى خطأ `404 Not Found`.\n\n---\n\n## أفضل الممارسات الاستراتيجية\n\n### 1. واجهة مستخدم \"منطقة الخطر\"\nنظرًا لأن هذا الإجراء دائم، يجب حمايته بضمانات قوية في واجهة المستخدم.\n- **أفضل ممارسة**: لا تسمح أبداً بتفعيل الحذف بنقرة واحدة. نفذ \"منطقة خطر\" في لوحة التحكم الخاصة بك تتطلب من المستخدم كتابة كلمة \"DELETE\" أو معرف النسخة لتأكيد رغبته. هذا يمنع فقدان البيانات الكارثي الناجم عن النقرات غير المقصودة.\n\n### 2. نصيحة \"تسجيل الخروج أولاً\"\nعلى الرغم من أن الحذف يقطع الجسر البرمجي، إلا أنه لا يرسل دائماً إشارة للهاتف لـ \"فك الارتباط\" إذا كان المحرك متوقفاً.\n- **الاستراتيجية**: للحصول على أفضل تجربة احترافية، استدعِ [`/v2/session/logout`](/v2/session/logout) قبل استدعاء `delete`. هذا يضمن إزالة الجهاز بشكل نظيف من قائمة \"الأجهزة المرتبطة\" في هاتف المستخدم، مما يمنع ظهور مداخل \"أجهزة شبحية\" في واجهة تطبيق واتساب.\n\n### 3. دورة حياة الاشتراك والاشتراكات الملغاة\nادمج هذه النقطة في إدارة الاشتراكات بمنصتك.\n- **سير العمل**: إذا ألغى مستخدم خطته أو فشل في الدفع، يجب أن يقوم نظامك تلقائياً باستدعاء `/v2/session/delete` بعد فترة سماح. هذا يضمن بقاء حصتك من الجلسات متاحة للعملاء النشطين والدافعين.\n\n---\n\n## حالات استخدام معيارية\n\n### أ- الامتثال للبيانات (GDPR/SOC2)\nإذا كان تطبيقك يتعامل مع بيانات حساسة للغاية، استخدم نقطة نهاية الحذف للتأكد من أنه بمجرد انتهاء تفاعل العميل، لا يتبقى أي أثر لجلسته على خوادمنا. هذا جزء أساسي من بناء بنية اتصالات قائمة على \"الثقة الصفرية\".\n\n### ب- التطوير والاختبار\nخلال مرحلة التطوير، قد تقوم بإنشاء وتدمير النسخ بشكل متكرر أثناء اختبار التكامل. استخدام نقطة نهاية الحذف يسمح لك بإبقاء بيئة الاختبار نظيفة وتجنب بلوغ حدود حصة خطتك.\n\n---\n\n## استكشاف الأخطاء وإصلاحها (Troubleshooting)\n\n### الخطأ 404: \"Instance Not Found\"\nيحدث هذا إذا كانت عملية الحذف قد تمت بالفعل أو إذا كان المعرف المزود غير صحيح. في نظامك الخلفي، يجب أن تعامل استجابة 404 لطلب الحذف على أنها \"نجاح بحكم الأمر الواقع\"، مما يعني أن النسخة قد اختفت بالفعل.\n\n### هل الاستعادة ممكنة؟\n**لا.** نحن نولي الأولوية لخصوصية البيانات وكفاءة الخادم. بمجرد تنفيذ أمر الحذف، يتم تطهير مفاتيح التشفير من وحدة التخزين الدائمة الآمنة لدينا. لا توجد \"سلة مهملات\" أو ميزة \"استعادة\". تأكد دائماً من تحديث قاعدة بياناتك الداخلية لتعكس أن الجلسة لم تعد موجودة.\n\n---\n\n## ملخص الوظائف:\n- إنهاء دائم للمحرك المعزول.\n- تطهير كافة مفاتيح التشفير والبيانات المؤقتة لأقصى قدر من الخصوصية.\n- تحرير فجوات الجلسات ضمن حصة خطة Wawp الخاصة بك.\n- ضمان صفحة معمارية نظيفة للتخصيصات المستقبلية.\n",
          "recommendations": [
            "اطلب دائماً التأكيد في واجهتك قبل تفعيل هذه النقطة.",
            "استخدم /v2/logout قبل /v2/delete لضمان إغلاق الجلسة بشكل صحيح من جهة الهاتف."
          ],
          "tips": [
            {
              "title": "لا تراجع",
              "content": "لا توجد 'سلة مهملات'. الجلسات المحذوفة لا يمكن استعادتها."
            }
          ]
        }
      }
    },
    {
      "path": "/v2/session/info",
      "methods": [
        "POST"
      ],
      "title": "Session Info",
      "category": "Session Management",
      "description": "Retrieve complete information about a WhatsApp session, including connection status, authenticated user info, and server details.",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "The 12-character ID of the instance to check",
          "example": "Your_Instance_ID"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        }
      },
      "extraInfo": "\n# The Pulse of the Engine: Decoding the Session Info Endpoint\n\nThe `/v2/session/info` endpoint is the most critical monitoring tool in your Wawp toolkit. It serves as the \"Heartbeat\" of your instance, providing real-time data on connection health, authentication state, and identity metadata. Mastering this endpoint is the key to building responsive, self-healing applications.\n\n---\n\n## 🔍 The Anatomy of a Status Response\n\nThe `status` field in the response is the primary director for your front-end logic. Understanding each state is essential:\n\n### 1. **WORKING (Active)**\n✅ The engine is fully connected to WhatsApp's servers and authenticated.\n- **Developer Action**: You are clear to send messages, fetch contacts, or update profile settings. No restrictions apply.\n\n### 2. **SCAN_QR_CODE (Authentication Pending)**\n⚠️ The engine is running but lacks valid credentials.\n- **Developer Action**: This is the **only** time the `qr` field in the response will contain a Base64 string. Display this QR code to the user immediately.\n- **Pro Tip**: QR codes expire rapidly (approx. 20-40 seconds). You must refresh your UI whenever a new QR string is returned by this endpoint.\n\n### 3. **STARTING (Warming Up)**\n⏳ The dedicated engine is booting and preparing the secure bridge.\n- **Developer Action**: Show a \"Connecting...\" spinner. Prevent the user from attempting to send messages until the state transitions.\n\n### 4. **STOPPED (Hibernating)**\n🛑 The instance is dormant. No system resources are being consumed.\n- **Developer Action**: Call the [`/v2/session/start`](/v2/session/start) endpoint to wake the engine.\n\n---\n\n## 🏗️ Monitoring Architecture: Best Practices\n\n### The \"Intelligent Polling\" Strategy\nPolling is efficient if done correctly. We recommend the following orchestration for user-facing dashboards:\n1. **Initial Check**: When the user opens their dashboard, call `/session/info`.\n2. **The QR Loop**: If the status is `SCAN_QR_CODE`, poll every 3-5 seconds. This ensures the QR code on the screen is always \"fresh\" and detects the successful scan the moment it happens.\n3. **The Stop Condition**: Once the status transitions to `WORKING`, stop polling immediately to save network overhead and battery life on mobile clients.\n\n### Leveraging the \"Me\" Object\nWhen a session is **WORKING**, the `me` object provides essential identity metadata:\n- **pushName**: Use this to welcome the user (e.g., \"Welcome back, Sarah!\").\n- **platform**: Understand if the user is connected via a specific OS, which can help in tailoring support if they report sync issues.\n\n---\n\n## 🛡️ Reliability and Health Monitoring\n\n### Building a \"Health Check\" Cron\nFor mission-critical bots, run a background task every 15 minutes that calls `/session/info`. \n- **Auto-Recovery**: If a session that should be active returns `STOPPED` or `FAILED`, your system should automatically trigger a [`start`](/v2/session/start) or [`restart`](/v2/session/restart) call.\n- **Alerting**: If a session transitions to `SCAN_QR_CODE` unexpectedly, it means the user has logged out from their phone. Send them a push notification or email to re-link their account.\n\n---\n\n## Troubleshooting Guide\n\n### Why is the QR field empty?\nThe `qr` field is context-aware. It will only contain data when the `status` is explicitly **SCAN_QR_CODE**. In any other state (like `STARTING` or `WORKING`), the field will be `null` or omitted because a handshake is either not ready or no longer needed.\n\n### Latency in Status Updates\nWhile our engine is near real-time, there can be a 1-3 second delay as the WhatsApp handshake completes. If a session is stuck in `STARTING` for more than 60 seconds, it indicates a transient network failure. We recommend calling the [`/v2/session/restart`](/v2/session/restart) endpoint to clear the state.\n\n---\n\n## Summary of Capabilities:\n- Verify message-sending readiness.\n- Retrieve the latest QR or Pairing Code.\n- Identify the phone number and name of the connected account.\n- Monitor server-side resource allocation and engine health.\n            ",
      "tips": [
        {
          "type": "info",
          "title": "Real-time Updates",
          "content": "This endpoint fetches data directly from the container. It is always the source of truth for connection status."
        }
      ],
      "recommendations": [
        "Poll this endpoint every 3-5 seconds while waiting for the user to scan the QR code.",
        "Stop polling once the status becomes 'WORKING'.",
        "Use this endpoint to build a 'System Status' page in your application dashboard."
      ],
      "responses": [
        {
          "status": 200,
          "description": "Success - Session Info",
          "contentType": "application/json",
          "example": {
            "name": "wawp-84729105",
            "status": "WORKING",
            "config": {
              "webhooks": [],
              "proxy": null
            },
            "me": {
              "id": "201012345678@c.us",
              "pushName": "John Doe"
            }
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "معلومات الجلسة",
          "description": "الحصول على الحالة التفصيلية وبيانات التعريف لجلسة واتساب نشطة.",
          "args": {
            "instance_id": {
              "description": "معرف النسخة الفريد"
            },
            "access_token": {
              "description": "مفتاح الوصول الخاص بـ API"
            }
          },
          "extraInfo": "\n# نبض النظام: الدليل الشامل لنقطة النهاية /v2/session/info\n\nتعتبر نقطة النهاية `/v2/session/info` هي الأداة الأهم في ترسانة المطور عند التعامل مع Wawp. هي بمثابة \"نبض القلب\" (Heartbeat) الذي يخبرك بكل ما تحتاج معرفته عن الحالة الصحية والتقنية لجلستك في أي لحظة. الاستخدام الصحيح لهذه النقطة هو المفتاح لبناء واجهة مستخدم متجاوبة ونظام أتمتة مستقر.\n\n---\n\n## تشريح استجابة الحالة (Status Breakdown)\nحقل `status` في الاستجابة هو الموجه الرئيسي لمنطق تطبيقك. إليك الفهم العميق لكل حالة:\n\n### 1. **WORKING (فعال)**\n✅ تعني أن المحرك متصل بخوادم واتساب، وتمت المصادقة بنجاح.\n- **الإجراء التقني**: يمكنك الآن البدء في إرسال الرسائل، جلب جهات الاتصال، أو تحديث الحالة. لا توجد قيود برمجية في هذه المرحلة.\n\n### 2. **SCAN_QR_CODE (انتظار المسح)**\n⚠️ المحرك يعمل ولكنه يفتقر لبيانات الاعتماد.\n- **الإجراء التقني**: يجب عليك إظهار رمز QR للمستخدم. في هذه الحالة فقط، سيعود حقل `qr` في الاستجابة بقيمة نصية (Base64) يمكن تحويلها لصورة. \n- **نصيحة**: تنتهي صلاحية رمز QR بسرعة؛ لذا يجب تحديث الواجهة فور تغير قيمة الحقل في الاستجابات المتتالية.\n\n### 3. **STARTING (قيد التشغيل)**\n⏳ المحرك في مرحلة الإحماء (Warm-up).\n- **الإجراء التقني**: يمنع إرسال أي أوامر إرسال في هذه المرحلة. يجب على تطبيقك إظهار مؤشر \"جاري الاتصال...\" والانتظار حتى تتغير الحالة.\n\n### 4. **STOPPED (متوقف)**\n🛑 الجلسة في وضع السبات ولا تستهلك موارد.\n- **الإجراء التقني**: يجب استدعاء `/v2/session/start` لتنتقل الجلسة لدورة الحياة النشطة.\n\n### 5. **FAILED (فشل)**\n❌ حدث خلل غير متوقع يمنع المحرك من البدء.\n- **الإجراء التقني**: لا تستسلم! استدعِ `/v2/session/restart` لمحاولة إصلاح الخلل آلياً.\n\n---\n\n## هندسة المراقبة الذكية (Monitoring Architecture)\n\n### استراتيجية \"الاستجابة الفورية\"\nلتقديم أفضل تجربة مستخدم، لا تعتمد فقط على الاستدعاء اليدوي. نقترح النمط التالي:\n1. عندما يفتح العميل لوحة التحكم، استدعِ `/v2/session/info`.\n2. إذا كانت الحالة `SCAN_QR_CODE`، ابدأ \"بولينج\" (Polling) كل 3 ثوانٍ لتحديث رمز QR ومراقبة لحظة نجاح المسح.\n3. بمجرد تحول الحالة إلى `WORKING`، أوقف \"البولينج\" فوراً لتوفير موارد الشبكة.\n\n### استغلال بيانات \"Me\"\nعندما تصبح الجلسة `WORKING`، لا تكتفِ بمعرفة الحالة، بل استفد من كائن `me` الذي يعود في الاستجابة:\n- **التوثيق**: خزن `pushName` والرقم المرتبط في قاعدة بياناتك لعرض اسم الحساب المتصل في واجهتك (مثلاً: \"متصل بحساب: محمد أحمد\").\n- **التنبيهات**: استلهم من نوع الجهاز (Platform) لتخصيص نصائح الأداء لعملائك.\n\n---\n\n## أفضل الممارسات التقنية\n\n### 🛡️ تجنب \"عنق الزجاجة\" (Rate Limiting)\nعلى الرغم من أن نظامنا سريع جداً، إلا أن استدعاء `/session/info` مئات المرات في الثانية لنفس الجلسة أمر غير محبذ.\n- **القاعدة الذهبية**: استفسر كل 3-5 ثوانٍ أثناء عمليات الربط، ومرة كل دقيقة (أو اعتمد كلياً على الويب هوك) لمراقبة الصحة العامة للجلسات المستقرة.\n\n### 💡 بناء \"لوحة مراقبة الصحة\" (Health Dashboard)\nاستخدم هذه النقطة لبناء صفحة \"حالة النظام\" لشركتك. يمكنك رصد الجلسات التي انتقلت لحالة `STOPPED` بشكل مفاجئ وإعادة تشغيلها برمجياً لضمان عدم ضياع أي رسائل واردة من عملائك.\n\n---\n\n## استكشاف الأخطاء وإصلاحها (Troubleshooting)\n\n### لماذا يعود حقل الـ QR فارغاً؟\nحقل `qr` يمتلئ **فقط** عندما تكون الحالة `SCAN_QR_CODE`. في أي حالة أخرى (مثل `STARTING` أو `WORKING`) سيكون الحقل غير موجود أو قيمته `null`. تأكد دائماً من فحص `status` أولاً.\n\n### التأخير في تحديث الحالة\nفي حالات نادرة، قد يتأخر المحرك في تحديث حالته من `STARTING` إلى `WORKING`. إذا استغرق الأمر أكثر من 45 ثانية، فإننا ننصح بإعادة تشغيل الجلسة لضمان عدم وجود عملية عالقة.\n\n---\n\n## ملخص الوظائف:\n- التحقق من جاهزية الإرسال.\n- الحصول على رمز QR للربط.\n- معرفة بيانات الحساب المرتبط حالياً.\n- مراقبة استهلاك الموارد وحالة المحرك.\n",
          "recommendations": [
            "استجوب نقطة النهاية هذه كل 3-5 ثوانٍ أثناء انتظار المستخدم لمسح رمز QR.",
            "توقف عن الاستجواب بمجرد أن تصبح الحالة 'WORKING'.",
            "استخدم نقطة النهاية هذه لبناء صفحة 'حالة النظام' في لوحة تحكم تطبيقك."
          ],
          "tips": [
            {
              "title": "تحديثات في الوقت الفعلي",
              "content": "تجلب نقطة النهاية هذه البيانات مباشرة من الحاوية. هي دائماً مصدر الحقيقة لحالة الاتصال."
            }
          ]
        }
      }
    },
    {
      "path": "/v2/session/me",
      "methods": [
        "GET"
      ],
      "title": "About WhatsApp Data",
      "category": "Session Management",
      "description": "Retrieves the profile information of the WhatsApp account connected to this session.",
      "extraInfo": "\n# Mirror of Identity: The Deep Dive into /v2/session/me\n\nThe `/v2/session/me` endpoint is your direct window into the \"Digital Persona\" currently linked to your Wawp instance. While [`/v2/session/info`](/v2/session/info) tells you about the technical health of the engine, `me` provides the identity details of the actual WhatsApp account that was scanned. Mastering this endpoint is essential for building personalized dashboards and verifying user intentions.\n\n---\n\n## 🏗️ Anatomy of the Digital Identity\n\nWhen you call this endpoint, you receive a payload containing the following pivotal fields:\n\n### 1. **The WhatsApp ID (JID - `id`)**\nThis is the immutable, unique identifier for the account on the WhatsApp network (e.g., `15551234567@c.us`).\n- **Technical Importance**: Use this ID as the \"Primary Key\" in your database to link inbound and outbound messages to a specific business unit or agent.\n\n### 2. **The Push Name (Display Name)**\nThis is the public name configured by the user in their WhatsApp mobile settings.\n- **Developer Action**: Use this string to personalize your dashboard. Instead of showing \"Instance #482,\" you can show \"Connected as: **Global Sales Dept**.\" This significantly improves the user experience for your non-technical staff.\n\n### 3. **The Platform Identifier**\nIdentifies whether the connected device is running on `android`, `ios`, or a `web` client.\n- **Analytics Insight**: Understanding the distribution of hardware among your connected instances can help you optimize your support procedures and predict sync behaviors, as different OS platforms have slight variations in how they handle long-lived WebSocket connections.\n\n---\n\n## 🛡️ Strategic Best Practices\n\n### 1. The \"Intent Verification\" Pattern\nIn enterprise environments, it's common for a staff member to accidentally scan a QR code with their personal WhatsApp instead of the corporate one.\n- **The Solution**: Immediately after a session hits the **WORKING** status, call `/v2/session/me`. Compare the returned JID with the expected phone number in your database. If they don't match, trigger an automated alert or call [`/v2/session/logout`](/v2/session/logout) to prevent data crossing.\n\n### 2. Intelligent Caching\nIdentity data (Name, ID, Platform) is relatively static and does not change often.\n- **The Optimization**: Do not call `/v2/session/me` every time you send a message. Instead, call it once during the \"Successful Connection\" event and store the result in your application's cache (Redis or local DB). Clear the cache only when you detect a `LOGOUT` or `DISCONNECTED` event via webhooks.\n\n---\n\n## 💡 Industry-Standard Use Cases\n\n### A. Dynamic Message Signatures\nIf you are running a multi-agent helpdesk where all agents share one Wawp instance, use `/v2/session/me` to verify the current \"Sender Identity\" and dynamically append a signature like \"Sent by: {{pushName}}\" to outbound texts.\n\n### B. Account Syncing Dashboards\nBuild a \"Profile Page\" in your SaaS that automatically pulls in the connected account's name and JID. This allows your customers to visually confirm which of their office numbers is currently active without checking their physical phones.\n\n---\n\n## ⚠️ Common Pitfalls and Troubleshooting\n\n### \"Session Not Connected\" (404/401)\nYou cannot fetch identity data if the engine is not in a **WORKING** state. The underlying WhatsApp libraries cannot \"see\" the identity until the secure handshake is complete.\n- **Fix**: Always verify the status via [`/v2/session/info`](/v2/session/info) before calling `me`.\n\n### Missing Push Name\nIn rare cases, if a user has never set a name in their WhatsApp settings, the field may be empty or `null`.\n- **Recommendation**: Implement a fallback in your code that uses the numeric portion of the JID if the `pushName` is missing.\n\n---\n\n## Summary of Capabilities:\n- Confirm the legal and technical identity of the connected account.\n- Personalize multi-tenant dashboards with user-specific names.\n- Analyze device platform distribution for technical optimizations.\n- Implement security guardrails to ensure only authorized numbers are linked.\n            ",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "The 12-character ID of the instance",
          "example": "Your_Instance_ID"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        }
      },
      "tips": [
        {
          "type": "info",
          "title": "Cached Data",
          "content": "This information is fetched directly from the WhatsApp engine. If you just changed your profile picture or name, it might take a moment to reflect."
        }
      ],
      "recommendations": [
        "Cache this response locally to display 'Connected to +201XXXX' in your UI without pinging the API repeatedly.",
        "Validate the returned 'id' against your database records to ensure the user scanned the correct number."
      ],
      "responses": [
        {
          "status": 200,
          "description": "Success - Profile Data",
          "contentType": "application/json",
          "example": {
            "id": "201012345678@c.us",
            "pushName": "John Doe",
            "platform": "android",
            "me": {
              "id": "201012345678@c.us",
              "name": "John Doe"
            }
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "عن بيانات الواتساب",
          "description": "الحصول على الملف الشخصي والبيانات العامة للحساب المرتبط.",
          "args": {
            "instance_id": {
              "description": "معرف النسخة الفريد"
            },
            "access_token": {
              "description": "مفتاح الوصول"
            }
          },
          "extraInfo": "\n# مرآة الهوية: الدليل الشامل لنقطة النهاية /v2/session/me\n\nتعد نقطة النهاية `/v2/session/me` نافذتك المباشرة على \"الشخصية الرقمية\" المرتبطة حالياً بنسخة Wawp الخاصة بك. بينما تخبرك [`/v2/session/info`](/v2/session/info) عن الحالة الصحية والتقنية للمحرك، توفر `me` تفاصيل الهوية لحساب واتساب الفعلي الذي تم مسحه. إتقان هذه النقطة ضروري لبناء لوحات تحكم مخصصة والتحقق من نوايا المستخدمين.\n\n---\n\n## تشريح الهوية الرقمية\nعند استدعاء هذه النقطة بنجاح، ستحصل على كائن يحتوي على الحقول المحورية التالية:\n\n### 1. **المعرف الفريد (JID - `id`)**\nهذا هو حجر الزاوية في نظام واتساب. لا يعود فقط كرقم هاتف، بل كمعرف شامل (مثلاً `966500000000@c.us`).\n- **الأهمية التقنية**: يجب أن يكون هذا المعرف هو \"المفتاح الأساسي\" في قاعدة بياناتك لربط الرسائل الصادرة والواردة بهذا الرقم بالتحديد.\n\n### 2. **الاسم التعريفي (Push Name - `pushname`)**\nهو الاسم الذي وضعه المستخدم في إعدادات واتساب الخاصة به. \n- **أفضل استغلال**: استلهم منه لتحية المستخدم في لوحة التحكم الخاصة بك (مثلاً: \"أهلاً بك يا محمد، حسابك متصل الآن\"). هذا يضفي لمسة احترافية وشخصية على تطبيقك.\n\n### 3. **المنصة الأم (Platform)**\nيوضح لك هذا الحقل ما إذا كان الحساب يعمل من جهاز `android`، `ios packaging` أو `web`.\n- **رؤية الأداء**: تساعدك هذه المعلومة في فهم قيود أو ميزات بعض المنصات، حيث توجد اختلافات طفيفة أحياناً في سرعة مزامنة البيانات بين أندرويد وآيفون.\n\n---\n\n## حالات استخدام استراتيجية\n\n### 🛡️ التحقق من \"الهوية المقصودة\"\nفي أنظمة الشركات الكبيرة، قد يخطئ الموظف ويمسح رمز QR برقم هاتفه الشخصي بدلاً من رقم العمل. \n- **الحل الذكي**: بمجرد نجاح الاتصال، استدعِ `/v2/session/me` وقارن الرقم العائد بالرقم الذي تتوقع ربطه في نظامك. إذا وجد تعارض، يمكنك إخطار المستخدم فوراً أو إنهاء الجلسة آلياً لمنع التداخل.\n\n### 📊 تقارير \"مركز الاتصال\" (Call Center)\nإذا كنت تدير عدة أرقام واتساب في لوحة واحدة، استخدم بيانات `me` لعرض قائمة بالأرقام المتصلة الآن مع أسمائها وصورها، مما يسهل على مدير النظام توزيع المهام بين الأرقام المختلفة.\n\n---\n\n## هندسة التكامل وأفضل الممارسات\n\n### ⚡ التخزين المؤقت (Caching Power)\nبيانات الحساب الشخصي (الاسم، الرقم، نوع الجهاز) لا تتغير بشكل متكرر. \n- **النصيحة الذهبية**: لا تستدعِ `/v2/session/me` مع كل عملية إرسال رسالة. بدلاً من ذلك، استدعها \"مرة واحدة\" عند تحول حالة الجلسة إلى **WORKING**، وخزن البيانات في ذاكرة التخزين المؤقت (Cache) أو قاعدة البيانات الخاصة بك.\n\n### 📸 مزامنة الصورة الشخصية\nيمكنك دمج استدعاء `me` مع نقطة النهاية الخاصة بصورة الملف الشخصي لتكوين \"بروفايل\" كامل لموظفك أو عميلك داخل واجهتك البرمجية.\n\n---\n\n## استكشاف الأخطاء وإصلاحها (Troubleshooting)\n\n### الخطأ 404: \"Session not connected\"\nهذا هو الخطأ الأكثر شيوعاً. لا يمكنك الحصول على بيانات \"Me\" وجلسة الواتساب غير متصلة فعلياً بالخوادم.\n- **الحل**: تأكد دائماً من أن حالة الجلسة (عبر `/v2/session/info`) هي **WORKING** قبل محاولة جلب بيانات الهوية.\n\n### لماذا يظهر الـ pushname كـ \"null\"؟\nفي حالات نادرة جداً، قد لا يكون المستخدم قد عين اسماً شخصياً في إعدادات واتساب (رغم أن واتساب يفرض ذلك الآن). في هذه الحالة، اعتمد على رقم الهاتف (User ID) كمعرف بديل في واجهتك.\n\n---\n\n## ملخص الوظائف:\n- التحقق من الرقم المرتبط فعلياً بالجلسة.\n- الحصول على الاسم العام للمستخدم والمستخدم في التحيات آلياً.\n- تحديد نوع النظام المشغل للواتساب.\n- بناء واجهات مستخدم مخصصة تعكس هوية الحساب المرتبط.\n",
          "recommendations": [
            "قم بتخزين هذه الاستجابة محلياً لعرض 'متصل بـ +201XXXX' في واجهتك دون استدعاء API بشكل متكرر.",
            "تحقق من صحة 'id' المرجع مقابل سجلات قاعدة البيانات لضمان أن المستخدم قام بمسح الرقم الصحيح."
          ],
          "tips": [
            {
              "title": "بيانات مخزنة مؤقتاً",
              "content": "يتم جلب هذه المعلومات مباشرة من محرك واتساب. إذا قمت بتغيير صورتك أو اسمك للتو، قد يستغرق الأمر لحظة لينعكس هنا."
            }
          ]
        }
      }
    },
    {
      "path": "/v2/auth-overview",
      "methods": [
        "GET"
      ],
      "category": "Authentication - Login",
      "isArticle": true,
      "title": "About login authentication",
      "description": "Wawp’s Authentication & Login endpoints are designed to make device onboarding and re-authentication fast, secure, and developer-friendly.",
      "extraInfo": "\n# Seamless Onboarding: The Architecture of Wawp Authentication\n\nWawp’s Authentication & Login infrastructure is engineered to solve the most difficult hurdle in WhatsApp automation: **Secure, reliable, and frictionless device linking.** Our system treats authentication not as a one-time event, but as a continuous, interactive handshake between your application, our high-performance engine, and the official WhatsApp network.\n\n![Screenshot 2025-09-11 003415.png](https://api.apidog.com/api/v1/projects/1017306/resources/361310/image-preview)\n\n---\n\n## 🏗️ The \"Interactive Handshake\" Philosophy\n\nUnlike legacy solutions that require manual session-file management, Wawp uses an **Isolated Engine Model**. When you initiate an authentication flow, we spin up a dedicated, containerized instance specifically for your session. This provides several critical advantages:\n1. **Sandboxed Security**: Each session’s encryption keys and WebSocket bridges are physically separated from other users.\n2. **State Transparency**: Through our Authentication endpoints, you can visualize exactly what the headless engine \"sees\" in real-time.\n3. **Automated Recovery**: Our system monitors the health of the authentication bridge. If a handshake stalls or the WhatsApp WebSocket disconnects unexpectedly, the engine performs a \"Warm Reset\" to restore the link without losing your paired status.\n\n---\n\n## 🛡️ Strategic Best Practices for Developers\n\n### 1. Hybrid Authentication Strategy\nFor the best User Experience (UX), we recommend implementing a hybrid approach in your application dashboard:\n- **Default (QR Image)**: Provide the direct [`/v2/auth/qr-image`](/v2/auth/qr-image) for desktop users. It’s the fastest and most familiar way to link.\n- **Advanced (Pairing Code)**: Offer the [`/v2/auth/request-code`](/v2/auth/request-code) method as a primary option for mobile-to-mobile onboarding or users with broken cameras. This allows a user to simply copy an 8-digit code and paste it into their WhatsApp settings.\n\n### 2. The \"Trust but Verify\" Security Model\nWawp adheres to a **Zero-Secrets Policy**. We do not log your API Access Tokens or WhatsApp Session Keys in our persistent application logs. \n- **Developer Action**: Ensure that your frontend never exposes the `access_token` in client-side logs. Always proxy authentication requests through your own backend to maintain a secure \"Server-to-Server\" relationship with Wawp.\n\n### 3. Implementing \"Live\" UI Updates\nWhatsApp QR codes are dynamic and expire every 20-30 seconds. \n- **The Ideal Workflow**: Use a WebSocket or a 5-second polling loop to refresh the QR image on your screen. If our API returns a `422` status, it signals that the engine is refreshing its state. Your UI should show a \"Generating fresh code...\" spinner rather than an error message.\n\n---\n\n## ⚖️ QR Code vs. Pairing Code: Which to Use?\n\n| Comparison | QR Code Method | Pairing Code Method |\n| :--- | :--- | :--- |\n| **User Effort** | Scan with Camera (Fast) | Manual Entry (Medium) |\n| **Supported Devices** | All (Standard) | Modern Android/iOS |\n| **Reliability** | High | Extremely High (Headless) |\n| **Best For** | Web-based Dashboards | CLI tools, VPS, Mobile Apps |\n\n---\n\n## 🧪 Technical Flow & Deployment Logic\n\nTo build a professional onboarding flow, your orchestration logic should follow these steps:\n\n1.  **State Audit**: Call [`/v2/session/info`](/v2/session/info).\n2.  **Logic Branching**:\n    *   **if WORKING**: Redirect user to their active dashboard.\n    *   **if STOPPED**: Call [`/v2/session/start`](/v2/session/start) and wait 5 seconds.\n    *   **if SCAN_QR_CODE**: The engine is ready for an identity link.\n3.  **Visual Presentation**:\n    *   Fetch the latest image via [`/v2/auth/qr-image`](/v2/auth/qr-image).\n    *   Render it in a responsive container with a 30-second countdown timer to manage user expectations.\n4.  **Verification**: Poll [`/v2/session/info`](/v2/session/info) every 3 seconds. The moment the status transitions to **WORKING**, trigger a \"Success\" animation and fetch the account details via [`/v2/session/me`](/v2/session/me).\n\n---\n\n## ⚠️ Common Pitfalls to Avoid\n\n- **Token Exposure**: Never append the `access_token` to a public URL that might be cached by CDNs or proxies. Use POST requests whenever possible.\n- **Poll Flooding**: Do not poll for authentication status faster than once every 2 seconds. Excessive requests can cause transient latency in the engine’s encryption handshake.\n\n---\n\n## Summary of Capabilities:\n- Power a white-labeled \"Connect WhatsApp\" experience.\n- Choose between QR image, raw QR string, or Pairing codes.\n- Monitor session persistence with high-fidelity screenshots.\n- Leverage automatic background engine restarts for 99.9% pairing reliability.\n    ",
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "Auto-reconnect",
          "content": "Wawp automatically attempts to reconnect 'WORKING' sessions if a node restarts or a network glitch occurs."
        }
      ],
      "recommendations": [
        "Store the 'instance_id' in your database linked to your internal user ID.",
        "Implement a 'Session Manager' page where users can see their current connection status.",
        "Listen for 'DISCONNECTED' or 'LOGOUT' webhook events to notify users they need to re-scan.",
        "Use the /v2/logout endpoint before deleting an instance to ensure a clean disconnection from WhatsApp servers."
      ],
      "responses": [],
      "translations": {
        "ar": {
          "title": "عن مصادقة تسجيل الدخول",
          "description": "صُممت روابط المصادقة وتسجيل الدخول في Wawp لتجعل عملية ربط الأجهزة وإعادة المصادقة سريعة وآمنة وسهلة للمطورين.",
          "tips": [
            {
              "title": "إعادة الاتصال التلقائي",
              "content": "يحاول Wawp تلقائيًا إعادة توصيل الجلسات 'النشطة' (WORKING) إذا حدثت خلل في الشبكة."
            }
          ],
          "recommendations": [
            "قم تخزين 'instance_id' في قاعدة بياناتك مرتبطًا بمعرف المستخدم الداخلي الخاص بك.",
            "قم بتنفيذ صفحة 'مدير الجلسات' حيث يمكن للمستخدمين رؤية حالة اتصالهم الحالية.",
            "استمع لأحداث Webhook مثل 'DISCONNECTED' لإبلاغ المستخدمين بالحاجة إلى إعادة المسح.",
            "استخدم نقطة النهاية /v2/logout قبل حذف أي مثيل لضمان قطع الاتصال النظيف."
          ],
          "extraInfo": "\n# إعداد سلس: بنية مصادقة Wawp\n\nتم تصميم بنية التحتية للمصادقة وتسجيل الدخول في Wawp لحل أصعب عقبة في أتمتة واتساب: **ربط الأجهزة بشكل آمن وموثوق وسلس.** يعامل نظامنا المصادقة ليس كحدث لمرة واحدة، بل كمصافحة تفاعلية مستمرة بين تطبيقك، ومحركنا عالي الأداء، وشبكة واتساب الرسمية.\n\n---\n\n## 🏗️ فلسفة \"المصافحة التفاعلية\"\n\nعلى عكس الحلول القديمة التي تتطلب إدارة يدوية لملفات الجلسة، تستخدم Wawp **نموذج المحرك المعزول**. عندما تبدأ عملية المصادقة، نقوم بتشغيل نسخة مخصصة ومنعزلة تماماً لجلستك. يوفر هذا عدة مزايا حاسمة:\n1. **أمان معزول**: يتم فصل مفاتيح التشفير وجسور WebSocket الخاصة بكل جلسة فعلياً عن المستخدمين الآخرين.\n2. **شفافية الحالة**: من خلال روابط المصادقة، يمكنك رؤية ما يراه المحرك بدقة في الوقت الفعلي.\n3. **التعافي التلقائي**: يراقب نظامنا صحة جسر المصادقة. إذا تعثرت المصافحة، يقوم المحرك بـ \"إعادة ضبط دافئة\" لاستعادة الاتصال دون فقدان حالة الاقتران.\n\n---\n\n## 🛡️ أفضل الممارسات الاستراتيجية للمطورين\n\n### 1. استراتيجية المصادقة المختلطة\nللحصول على أفضل تجربة مستخدم (UX)، نوصي باتباع نهج مختلط في لوحة تحكم تطبيقك:\n- **الافتراضي (صورة QR)**: وفر رابط [`/v2/auth/qr-image`](/v2/auth/qr-image) لمستخدمي سطح المكتب. إنها الطريقة الأسرع والأكثر فلفاً للربط.\n- **متقدم (كود الاقتران)**: قدم طريقة [`/v2/auth/request-code`](/v2/auth/request-code) كخيار أساسي للربط من هاتف إلى هاتف أو للمستخدمين الذين لديهم كاميرات معطلة.\n\n### 2. نموذج أمان \"ثق ولكن تحقق\"\nتلتزم Wawp بـ **سياسة عدم الاحتفاظ بالأسرار**. نحن لا نسجل مفاتيح الوصول الخاصة بك أو مفاتيح جلسة واتساب في سجلاتنا الدائمة.\n- **إجراء المطور**: تأكد من أن واجهتك الأمامية لا تعرض `access_token` في سجلات العميل. قم دائماً بتمرير طلبات المصادقة عبر خادمك الخلفي (Backend).\n\n### 3. تنفيذ تحديثات واجهة المستخدم \"المباشرة\"\nأكواد QR الخاصة بواتساب ديناميكية وتنتهي صلاحيتها كل 20-30 ثانية.\n- **سير العمل المثالي**: استخدم حلقة فحص مدتها 5 ثوانٍ لتحديث صورة QR على شاشتك. إذا أرجعت API حالة `422`، فهذا يعني أن المحرك يقوم بتحديث حالته. يجب أن تظهر واجهتك مؤشر تحميل بدلاً من رسالة خطأ.\n\n---\n\n## ⚖️ كود QR مقابل كود الاقتران: أيهما تختار؟\n\n| وجه المقارنة | طريقة كود QR | طريقة كود الاقتران |\n| :--- | :--- | :--- |\n| **جهد المستخدم** | مسح بالكاميرا (سريع) | إدخال يدوي (متوسط) |\n| **الأجهزة المدعومة** | الكل (قياسي) | أندرويد/iOS حديث |\n| **الموثوقية** | عالية | عالية جداً (Headless) |\n| **الأفضل لـ** | لوحات الويب | أدوات CLI، السيرفرات، تطبيقات الهاتف |\n\n---\n\n## 🧪 التدفق التقني ومنطق النشر\nلبناء مسار إعداد احترافي، يجب أن يتبع منطق التنسيق الخاص بك هذه الخطوات:\n1. **تدقيق الحالة**: استدعِ [`/v2/session/info`](/v2/session/info).\n2. **تفرع المنطق**:\n    - **إذا كانت الحالة WORKING**: وجه المستخدم إلى لوحة التحكم النشطة.\n    - **إذا كانت الحالة STOPPED**: استدعِ [`/v2/session/start`](/v2/session/start) وانتظر 5 ثوانٍ.\n    - **إذا كانت الحالة SCAN_QR_CODE**: المحرك جاهز لربط الهوية.\n3. **العرض المرئي**: جلب أحدث صورة عبر [`/v2/auth/qr-image`](/v2/auth/qr-image) وعرضها مع مؤقت عد تنازلي.\n4. **التحقق**: افحص الحالة كل 3 ثوانٍ، وبمجرد التحول إلى **WORKING**، ابدأ عرض الرسوم المتحركة للنجاح.\n\n---\n\n## ⚠️ أخطاء شائعة يجب تجنبها\n- **تعريض المفاتيح**: لا تضف `access_token` أبداً إلى رابط عام قد يتم تخزينه في الذاكرة المؤقتة. استخدم طلبات POST دائماً.\n- **إغراق الطلبات**: لا تفحص حالة المصادقة بسرعة أكبر من مرة كل ثانيتين، لتجنب التأثير على عملية التشفير.\n\n---\n\n## ملخص القدرات:\n- توفير تجربة \"ربط واتساب\" بعلامتك التجارية الخاصة.\n- الاختيار بين صورة QR، أو البيانات الخام، أو أكواد الاقتران.\n- مراقبة استمرارية الجلسة بلقطات شاشة عالية الدقة.\n- الاستفادة من إعادة التشغيل التلقائي للمحرك لضمان موثوقية اقتران بنسبة 99.9%.\n            "
        }
      }
    },
    {
      "path": "/v2/auth/qr",
      "methods": [
        "POST",
        "GET"
      ],
      "title": "GET QR raw",
      "category": "Authentication - Login",
      "description": "Retrieves the raw QR payload as binary/base64 plus a mimetype.",
      "extraInfo": "\n# Deciphering the Protocol: The Raw QR Payload Guide\n\nThe `/v2/auth/qr` endpoint is the specialized \"Engine Access\" tool for developers who require surgical control over the authentication process. Unlike the image-based endpoint, which is optimized for quick rendering, this route provides the raw, Base64-encoded protocol string. This is essential for building custom QR generators, CLI-based tools, or native mobile implementations where binary data is preferred over a static image.\n\n---\n\n## 🏗️ Technical Breakdown: The JSON Envelope\n\nThe response from this endpoint is a JSON object containing two primary components:\n1. **mimetype**: Typically `application/json`, indicating that the payload is a structured data object.\n2. **data**: A Base64-encoded string. Once decoded, this string yields a JSON object containing the **Protocol Signature** required by the WhatsApp WebSocket.\n\n### The Decoded Payload Structure\nWhen you decode the `data` field, you will find:\n- **value**: The actual alphanumeric string that needs to be encoded into a QR pattern.\n- **expiry**: A Unix timestamp representing the exact millisecond when this specific QR code will be invalidated by the WhatsApp servers.\n\n---\n\n## 🛡️ Strategic Best Practices\n\n### 1. Implementing a CLI-Based ASCII Renderer\nIf you are building a headless tool (like a VPS manager or a terminal-based bot), fetching the raw QR string allows you to render the code directly in the terminal using ASCII characters.\n- **Developer Action**: Use a library like `qrcode-terminal` in Node.js or `qrcode` in Python. Pass the `value` from the decoded response to the library to display the scanable pattern directly to your server administrators.\n\n### 2. Synchronization and Rate Limiting\nFetching the raw QR is a relatively resource-intensive task for the underlying engine as it involves a real-time probe of the browser state.\n- **The Polling Window**: We recommend a polling interval of **5-7 seconds**. Polling faster than this will not yield a \"fresher\" code (as WhatsApp only rotates codes every 20-30 seconds) and may lead to 429 Rate Limit responses from our infrastructure.\n\n### 3. Handling the Recovery Window (422 Status)\nIf the engine is busy resetting its internal WhatsApp bridge, you will receive a `422 Session Status Not Expected` error. \n- **The Fix**: This is not a failure; it’s a \"Please Wait\" signal. Your application should implement an exponential backoff. Wait 10 seconds, then 20 seconds, before attempting to fetch the QR again. This gives the engine time to finalize its background handshake.\n\n---\n\n## 💡 Industry-Standard Use Cases\n\n### A. Deep-Link Mobile Integration\nIf you are building a native iOS or Android app, you can fetch the raw QR string and use the mobile OS's native QR generation libraries (like CoreImage on iOS). This results in a much sharper, high-contrast QR code that is easier for the user's secondary device to scan compared to a compressed PNG image.\n\n### B. Security-Hardened Dashboards\nFor high-security environments where you do not want to load external images from our servers, you can fetch the raw string on your backend, verify its integrity, and then generate the QR pattern locally using your own internal corporate styling.\n\n---\n\n## ⚠️ Common Pitfalls\n\n- **Binary vs. String**: The `data` field is **Base64 encoded**. If you try to pass the raw Base64 string directly into a QR generator without decoding it first, the scan will fail because the data will be interpreted as a literal Base64 string rather than the underlying WhatsApp protocol ID.\n- **Expiry Ignorance**: Always check the `expiry` field. If your frontend displays a QR code that has already passed its expiry timestamp, the user will scan it only to see an \"Expired\" error on their phone, leading to significant UX frustration.\n\n---\n\n## Summary of Responsibilities:\n- Retrieve the raw cryptographic string required for a WhatsApp handshake.\n- Provide a Base64-wrapped JSON envelope for protocol compatibility.\n- Enable custom rendering in non-browser environments (CLI, Mobile).\n- Facilitate advanced monitoring of QR rotation cycles and expiration.\n            ",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "The 12-character ID of the instance",
          "example": "Your_Instance_ID"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "format": {
          "required": false,
          "type": "string",
          "description": "Output format (default: raw)",
          "example": "raw"
        }
      },
      "tips": [
        {
          "type": "info",
          "title": "Freshness",
          "content": "This endpoint returns a non-cached response header to ensure you always get the latest QR code."
        },
        {
          "type": "warning",
          "title": "Expiry",
          "content": "The returned QR string has a short lifespan (20-60s). Use the 'expiry' timestamp to refresh it."
        }
      ],
      "recommendations": [
        "Use this endpoint for custom CLI dashboards or mobile app integrations.",
        "Decode the Base64 'data' field before passing it to a QR generation library.",
        "Implement a polling mechanism to fetch a new code upon expiry."
      ],
      "responses": [
        {
          "status": 200,
          "description": "Success - QR Raw Data",
          "contentType": "application/json",
          "example": {
            "mimetype": "application/json; charset=utf-8",
            "data": "eyJ2YWx1ZSI6IjJAR0JoWWtpTkV1U0tpeXpIeVVOYy9RQi9lTnhpSkJWSE96bGhOQ1daRERvRUZyOEhDWEhxTENKdEVpZHh6WWoxWkpqRzZ4K2NOaFVlVGlZeUJHWExJQzU1Z2ppKzRHQ2VyakRvPSIsImV4cGlyeSI6MTIzNDU2Nzg5MH0="
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 422,
          "description": "Unprocessable Entity - Session Status Mismatch",
          "contentType": "application/json",
          "example": {
            "code": "session_unexpected_status",
            "message": "Session status is not as expected for this operation. We are attempting to auto-recover.",
            "details": {
              "current_status": "FAILED",
              "expected_status": [
                "SCAN_QR_CODE"
              ],
              "action": "auto_restart_triggered",
              "recommendation": "The instance encountered an error and is being restarted. Please wait a few seconds and try again."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "الحصول على كود QR الخام",
          "description": "يستخرج هذا الرابط بيانات كود QR الخام كبيانات ثنائية أو بصيغة base64 مع تحديد نوع الملف (mimetype).",
          "recommendations": [
            "استخدم نقطة النهاية هذه للوحات تحكم CLI المخصصة أو تكاملات تطبيقات الهاتف المحمول.",
            "قم بفك تشفير حقل 'data' بتنسيق Base64 قبل تمريره إلى مكتبة توليد QR.",
            "قم بتنفيذ آلية استطلاع لجلب رمز جديد عند انتهاء الصلاحية."
          ],
          "extraInfo": "\n# فك شيفرة البروتوكول: دليل بيانات QR الخام\n\nيُعد الرابط `/v2/auth/qr` أداة متخصصة للمطورين الذين يحتاجون إلى تحكم دقيق في عملية المصادقة. بخلاف رابط الصورة، يوفر هذا المسار سلسلة البروتوكول الخام بتنسيق Base64، وهو أمر ضروري لإنشاء مولدات QR مخصصة، أو أدوات سطر الأوامر (CLI)، أو تطبيقات الهاتف الأصلية.\n\n---\n\n## 🏗️ التحليل التقني: مغلف JSON\n\nتحصل من هذا الرابط على كائن JSON يحتوي على مكونين رئيسيين:\n1. **mimetype**: عادة ما يكون `application/json`، مما يشير إلى أن البيانات عبارة عن كائن بيانات مهيكل.\n2. **data**: سلسلة نصية مشفرة بصيغة Base64. بمجرد فك تشفيرها، تنتج كائن JSON يحتوي على **توقيع البروتوكول** المطلوب بواسطة WhatsApp WebSocket.\n\n### هيكل البيانات بعد فك التشفير\nعند فك تشفير حقل `data`، ستجد:\n- **value**: السلسلة النصية الفعلية التي يجب تحويلها إلى نمط QR.\n- **expiry**: طابع زمني (Unix timestamp) يمثل اللحظة التي سينتهي فيها صلاحية هذا الكود من قبل خوادم واتساب.\n\n---\n\n## 🛡️ أفضل الممارسات الاستراتيجية\n\n### 1. تنفيذ عارض ASCII لسطر الأوامر\nإذا كنت تبني أداة لسطر الأوامر (مثل مدير VPS)، فإن الحصول على سلسلة QR الخام يسمح لك بعرض الكود مباشرة في الطرفية باستخدام أحرف ASCII.\n- **إجراء المطور**: استخدم مكتبة مثل `qrcode-terminal` في Node.js وقم بتمرير قيمة `value` إليها لعرض النمط القابل للمسح مباشرة للمسؤولين.\n\n### 2. التزامن وحدود الطلبات\nيعد جلب كود QR الخام عملية تستهلك موارد لأنها تتطلب فحص حالة المحرك في الوقت الفعلي.\n- **نافذة الجلب**: نوصي بفاصل زمني يتراوح بين **5-7 ثوانٍ**. الجلب بمعدل أسرع من ذلك لن يعطي كوداً \"أحدث\" (لأن واتساب يقوم بتدوير الأكواد كل 20-30 ثانية) وقد يؤدي ذلك لظهور خطأ 429.\n\n### 3. التعامل مع نافذة التعافي (حالة 422)\nإذا كان المحرك مشغولاً بإعادة ضبط جسر واتساب الداخلي، ستتلقى خطأ `422 Session Status Not Expected`.\n- **الحل**: هذا ليس فشلاً، بل إشارة \"يرجى الانتظار\". يجب أن ينفذ تطبيقك استراتيجية انتظار (exponential backoff) والانتظار لمدة 10 ثوانٍ قبل محاولة الجلب مرة أخرى.\n\n---\n\n## 💡 حالات الاستخدام القياسية\n\n### أ. تكامل تطبيقات الهاتف\nيمكنك جلب سلسلة QR الخام واستخدام مكتبات إنشاء كود QR الأصلية في نظام iOS أو Android، مما يؤدي لظهور الكود بوضوح أعلى وتباين أفضل يسهل مسحه.\n\n### ب. لوحات التحكم عالية الأمان\nفي البيئات التي لا تريد فيها تحميل صور خارجية من خوادمنا، يمكنك جلب السلسلة الخام على خادمك الخاص، والتحقق منها، ثم إنشاء نمط QR محلياً باستخدام التصميم الخاص بشركتك.\n\n---\n\n## ⚠️ الأخطاء الشائعة\n\n- **البيانات الثنائية مقابل النص**: حقل `data` مشفر بصيغة **Base64**. إذا حاولت تمريره مباشرة لمولد QR دون فك تشفيره، سيفشل المسح لأنه سيتم تفسيره كنص حرفي بدلاً من كونه معرف بروتوكول واتساب.\n- **تجاهل الصلاحية**: تحقق دائماً من حقل `expiry`. إذا عرضت كوداً منتهي الصلاحية، سيظهر للمستخدم خطأ \"منتهي\" على هاتفه، مما يسبب تجربة مستخدم سيئة.\n\n---\n\n## ملخص المسؤوليات:\n- استرجاع السلسلة التشفيرية الخام المطلوبة لمصادقة واتساب.\n- توفير مغلف JSON مغلف بـ Base64 لضمان توافق البروتوكول.\n- تمكين العرض المخصص في البيئات غير المتصفحية (CLI، Mobile).\n- تسهيل المراقبة المتقدمة لدورات تدوير كود QR وصلاحيته.\n            ",
          "args": {
            "instance_id": {
              "description": "معرف النسخة المكون من 12 رمزاً"
            },
            "access_token": {
              "description": "مفتاح الوصول الخاص بـ API"
            },
            "format": {
              "description": "تنسيق المخرجات (الافتراضي: raw)"
            }
          },
          "tips": [
            {
              "title": "حداثة البيانات",
              "content": "تعيد نقطة النهاية هذه ترويسة استجابة غير مخزنة مؤقتًا لضمان حصولك دائمًا على أحدث رمز QR."
            },
            {
              "title": "انتهاء الصلاحية",
              "content": "سلسلة QR المرجعة لها عمر قصير (20-60 ثانية). استخدم طابع الوقت 'expiry' لتحديثها."
            }
          ]
        }
      }
    },
    {
      "path": "/v2/auth/qr-image",
      "methods": [
        "POST",
        "GET"
      ],
      "title": "Get QR Image",
      "category": "Authentication - Login",
      "description": "Returns a base64-encoded PNG image of the WhatsApp QR code for easy rendering in web and mobile applications.",
      "extraInfo": "\n# The Visual Gateway: A Masterclass in QR Image Authentication\n\nThe `/v2/auth/qr-image` endpoint is the gold standard for web-based WhatsApp integrations. It abstracts away the complexity of raw binary data and Base64 decoding, providing a ready-to-use **Data URI** that can be injected directly into any modern browser environment. This endpoint is specifically tuned for speed and ease of use in React, Vue, and vanilla JS dashboards.\n\n---\n\n## 🏗️ Anatomy of the Data URI Response\n\nWhen you call this endpoint, you receive a JSON response containing a single `qr` field. This field contains a string prefixed with `data:image/png;base64,...`.\n- **The Core Value**: This is a high-contrast, optimized PNG image of the WhatsApp pairing code.\n- **Frontend Implementation**:\n  ```javascript\n  // Example: Updating an image element in Vanilla JS\n  fetch('/v2/auth/qr-image', { method: 'POST', body: JSON.stringify({ instance_id, access_token }) })\n    .then(res => res.json())\n    .then(data => {\n      document.getElementById('qr-container').src = data.qr;\n    });\n  ```\n\n---\n\n## 🛡️ Strategic Best Practices\n\n### 1. Intelligent UI Polling\nBecause QR codes refresh frequently (every 20-40 seconds), your UI needs a \"Heartbeat.\"\n- **The Strategy**: Set an interval to refresh the image every 5-10 seconds. This ensures that when the user finally holds up their phone to scan, the code they see is guaranteed to be within its valid window.\n- **Visual UX**: Implement a subtle \"Pulse\" animation or a loading overlay when the image is refreshing to inform the user that the system is keeping the link alive.\n\n### 2. Mastering the 422 Auto-Recovery State\nOne of Wawp’s unique features is the **Background Engine Healer**. If you call this endpoint and the engine is currently de-synced from WhatsApp, it will return a `422 Session Status Not Expected` error.\n- **The Lifecycle**: This response signals that our cloud orchestrator has detected a stall and is currently performing a `Stop -> Start` sequence for you automatically.\n- **Developer Action**: Do not show an \"Operation Failed\" error. Instead, show a message like \"Recovering the engine bridge... please wait 15 seconds.\" After the delay, retry the request—you will likely be greeted with a fresh, working QR code.\n\n### 3. Cache Management\nTo prevent accidental exposure of sensitive QR data, this endpoint is served with strict `Cache-Control: no-store` headers.\n- **Warning**: Never attempt to bypass these headers. Storing a QR image in a CDN or browser cache is a security risk and will lead to \"Failed to scan\" errors for the user, as the cached code will be stale.\n\n---\n\n## 💡 Developer Use Cases\n\n### A. Mobile-Responsive Dashboards\nThe PNG returned by this endpoint is dynamically generated to be high-contrast and clear even on low-budget smartphone displays. This makes it perfect for \"Scan on iPad\" or \"Scan on Chromebook\" scenarios where screen glare can sometimes interfere with lower-quality QR renderers.\n\n### B. Onboarding Progress Bars\nBy monitoring the response of this endpoint in parallel with [`/v2/session/info`](/v2/session/info), you can build a multi-step onboarding wizard:\n1. **Step 1**: \"Warming up engine\" (Poll until Status is `SCAN_QR_CODE`).\n2. **Step 2**: \"Ready to Scan\" (Fetch and display the QR image).\n3. **Step 3**: \"Success!\" (Transition to `WORKING`).\n\n---\n\n## ⚠️ Common Pitfalls\n\n- **GET Request Leakage**: Avoid using GET requests for this endpoint in production dashboards. Browsers often log GET parameters (like your `access_token`) in the command history or developer console. Use POST to keep your credentials in the request body.\n- **Ignoring the Mimetype**: Always ensure your image tag or CSS background-image property correctly handles the `data:image/png;base64` prefix. Omitting this part of the string will result in a \"Broken Image\" icon.\n\n---\n\n## Summary of Capabilities:\n- Instantly retrieve a scan-ready PNG image of the WhatsApp QR code.\n- Leverage the \"One-Click\" rendering power of Data URIs.\n- Trigger automatic environment healing during state de-syncs.\n- Maintain high security with non-persistent, non-cached visual data.\n            ",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "The 12-character ID of the instance",
          "example": "Your_Instance_ID"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        }
      },
      "tips": [
        {
          "type": "positive",
          "title": "Direct Rendering",
          "content": "The 'qr' field is a full Data URI. Bind it directly to an <img src='...'> tag."
        },
        {
          "type": "warning",
          "title": "Wait for Engine",
          "content": "After starting a session, it may take 5-15 seconds for the QR code to be ready."
        }
      ],
      "recommendations": [
        "Embed directly in your frontend without saving to disk for better security.",
        "Refresh the image every 30 seconds to avoid showing expired codes.",
        "Do not cache this response; always fetch a fresh image."
      ],
      "responses": [
        {
          "status": 200,
          "description": "Success - QR Image URL",
          "contentType": "application/json",
          "example": {
            "qr": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgA..."
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 422,
          "description": "Unprocessable Entity - Session Status Mismatch",
          "contentType": "application/json",
          "example": {
            "code": "session_unexpected_status",
            "message": "Session status is not as expected for this operation. We are attempting to auto-recover.",
            "details": {
              "current_status": "FAILED",
              "expected_status": [
                "SCAN_QR_CODE"
              ],
              "action": "auto_restart_triggered",
              "recommendation": "The instance encountered an error and is being restarted. Please wait a few seconds and try again."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "الحصول على صورة كود QR",
          "description": "يعيد صورة PNG لكود QR الخاص بواتساب مشفرة بصيغة base64 لسهولة العرض في تطبيقات الويب والهاتف.",
          "recommendations": [
            "قم بالتضمين مباشرة في الواجهة الأمامية دون الحفظ على القرص لأمان أفضل.",
            "قم بتحديث الصورة كل 30 ثانية لتجنب عرض رموز منتهية الصلاحية.",
            "لا تقم بتخزين هذه الاستجابة مؤقتًا؛ اجلب دائمًا صورة جديدة."
          ],
          "extraInfo": "\n# البوابة المرئية: دليل احترافي لمصادقة صورة QR\n\nيُعد الرابط `/v2/auth/qr-image` المعيار الذهبي لتكاملات واتساب القائمة على الويب. فهو يبسط تعقيد البيانات الثنائية، ويوفر **Data URI** جاهزاً للاستخدام يمكن حقنه مباشرة في أي متصفح حديث. تم ضبط هذا الرابط خصيصاً للسرعة وسهولة الاستخدام في لوحات التحكم المبنية بـ React أو Vue أو JS العادية.\n\n---\n\n## 🏗️ تشريح استجابة Data URI\nعند استدعاء هذا الرابط، تتلقى استجابة JSON تحتوي على حقل `qr` واحد. يبدأ هذا الحقل ببادئة `data:image/png;base64,...`.\n- **القيمة الأساسية**: هي صورة PNG عالية التباين ومحسنة لكود اقتران واتساب.\n- **التنفيذ في الواجهة الأمامية**:\n  ```javascript\n  // مثال: تحديث عنصر صورة باستخدام Vanilla JS\n  fetch('/v2/auth/qr-image', { method: 'POST', body: JSON.stringify({ instance_id, access_token }) })\n    .then(res => res.json())\n    .then(data => {\n      document.getElementById('qr-container').src = data.qr;\n    });\n  ```\n\n---\n\n## 🛡️ أفضل الممارسات الاستراتيجية\n\n### 1. التحديث الذكي لواجهة المستخدم\nنظراً لأن أكواد QR تتحدث بشكل متكرر (كل 20-40 ثانية)، فمن الضروري تحديث الصورة دورياً.\n- **الاستراتيجية**: اضبط فاصلاً زمنياً لتحديث الصورة كل 5-10 ثوانٍ لضمان أن الكود الذي يراه المستخدم صالح دائماً.\n- **تجربة المستخدم**: أضف مؤشر تحميل بسيط عند تحديث الصورة لإعلام المستخدم أن النظام يحافظ على استمرارية الرابط.\n\n### 2. إتقان حالة التعافي التلقائي (خطأ 422)\nتتميز Wawp بوجود **مُعالج المحرك الخلفي**. إذا استدعيت هذا الرابط وكان المحرك غير متزامن، سيعود خطأ `422 Session Status Not Expected`.\n- **دورة الحياة**: تشير هذه الاستجابة إلى أن نظامنا قد اكتشف تعطلاً ويقوم حالياً بسلسلة `Stop -> Start` تلقائياً لك.\n- **إجراء المطور**: لا تعرض خطأ \"فشلت العملية\"، بل اعرض رسالة مثل \"يتم استعادة اتصال المحرك... يرجى الانتظار 15 ثانية\". بعد ذلك، أعد المحاولة.\n\n### 3. إدارة التخزين المؤقت\nلضمان الأمان، يتم تقديم هذا الرابط مع ترويسة `Cache-Control: no-store`.\n- **تحذير**: لا تحاول أبداً تجاوز هذه الترويسة. تخزين صورة QR في الذاكرة المؤقتة يشكل خطراً أمنياً وسيؤدي إلى أخطاء في المسح للمستخدم.\n\n---\n\n## 💡 حالات استخدام المطورين\n\n### أ. لوحات التحكم المتجاوبة للهواتف\nصورة PNG التي يعيدها هذا الرابط مصممة لتكون عالية التباين وواضحة حتى على شاشات الهواتف اقتصادية التكلفة، مما يجعلها مثالية لسيناريوهات \"المسح من الجهاز اللوحي\".\n\n### ب. شريط تقدم الإعداد\nمن خلال مراقبة استجابة هذا الرابط مع [`/v2/session/info`](/v2/session/info)، يمكنك بناء دليل إعداد متعدد الخطوات:\n1. **الخطوة 1**: \"تسخين المحرك\" (الجلب حتى تصبح الحالة `SCAN_QR_CODE`).\n2. **الخطوة 2**: \"جاهز للمسح\" (جلب وعرض صورة QR).\n3. **الخطوة 3**: \"نجاح!\" (الانتقال إلى حالة `WORKING`).\n\n---\n\n## ⚠️ الأخطاء الشائعة\n- **تسرب طلبات GET**: تجنب استخدام طلبات GET في لوحات التحكم الإنتاجية. فالمتصفحات غالباً ما تسجل معاملات GET (مثل `access_token`) في السجل. استخدم POST للحفاظ على سرية بياناتك.\n- **تجاهل نوع الملف (Mimetype)**: تأكد دائماً من أن علامة الصورة أو خاصية CSS تتعامل بشكل صحيح مع بادئة `data:image/png;base64`.\n\n---\n\n## ملخص القدرات:\n- الحصول الفوري على صورة PNG جاهزة للمسح لكود QR الخاص بواتساب.\n- الاستفادة من قوة Data URIs للعرض بضغطة واحدة.\n- تفعيل ميزة الإصلاح التلقائي للبيئة أثناء عدم التزامن.\n- الحفاظ على أمان عالٍ ببيانات مرئية غير دائمة وغير مخزنة مؤقتاً.\n            ",
          "args": {
            "instance_id": {
              "description": "معرف النسخة المكون من 12 رمزاً"
            },
            "access_token": {
              "description": "مفتاح الوصول الخاص بـ API"
            }
          },
          "tips": [
            {
              "title": "العرض المباشر",
              "content": "حقل 'qr' هو Data URI كامل. اربطه مباشرة بوسم <img src='...'>."
            },
            {
              "title": "انتظار المحرك",
              "content": "بعد بدء الجلسة، قد يستغرق الأمر من 5 إلى 15 ثانية حتى يصبح رمز QR جاهزًا."
            }
          ]
        }
      }
    },
    {
      "path": "/v2/auth/request-code",
      "methods": [
        "POST"
      ],
      "title": "Request Code (Phone Login)",
      "category": "Authentication - Login",
      "description": "Requests a linking code for phone-based WhatsApp authentication (OTP style).",
      "extraInfo": "\n# Headless Onboarding: The Power of Phone-Based Pairing Codes\n\nThe `/v2/auth/request-code` endpoint is a game-changer for WhatsApp automation, specifically designed for \"Headless\" environments where scanning a QR code is physically impossible or technically inconvenient. This method—often referred to as **OTP-style Linking**—allows you to link a WhatsApp account to a Wawp instance by entering an 8-character alphanumeric code directly into the WhatsApp mobile app.\n\n---\n\n## 🏗️ The Dual-Handshake Architecture\n\nWhen you call this endpoint with a `phone_number`, Wawp initiates a complex background orchestration:\n1. **Targeting**: The engine establishes a connection to WhatsApp’s servers and \"announces\" its intent to link with the specific phone number provided.\n2. **Code Generation**: Wawp’s cloud infrastructure negotiates a unique, short-lived 8-character pairing code (e.g., `ABCD-1234`).\n3. **Session Binding**: The generated code is cryptographically bound to your `instance_id`.\n4. **Interactive Waiting**: The engine enters an \"Interactive Listening\" mode, waiting for the user to type this code into their mobile device.\n\n---\n\n## 🛡️ Strategic Best Practices\n\n### 1. Global Number Normalization\nWhatsApp follows a strict international numbering format. Provisioning will fail if the format is incorrect.\n- **Developer Action**: Before passing the `phone_number` to this API, strictly normalize it on your backend:\n  - Remove all spaces, dashes, and parentheses.\n  - Remove any leading `+` or `00` (the global prefix).\n  - Ensure the Country Code is present (e.g., Use `201112223333` instead of `01112223333`).\n\n### 2. Building an OTP-Style UX\nSince the user needs to enter the code on their phone, the UX of your dashboard is critical.\n- **The Workflow**:\n  - Show the 8-character code in a **Big, Bold font**.\n  - Provide a countdown timer (codes are valid for approx. 2-5 minutes).\n  - Include a \"How to Link\" guide: **WhatsApp -> Settings -> Linked Devices -> Link with Phone Number**.\n\n### 3. Handling the 422 \"Not Ready\" State\nIf the engine is still initializing or has just been started, it may not be ready to generate a code instantly.\n- **The Response**: You will receive a `422 Session Status Not Expected` error. This indicates the engine is currently performing an internal warm-up. Implement a 10-second wait on your frontend before allowing the user to click the \"Generate Code\" button again.\n\n---\n\n## 💡 Industry-Standard Use Cases\n\n### A. Headless Server Provisioning\nFor enterprise clients running hundreds of bots on isolated linux servers without any GPU or display, the Pairing Code method is the only way to scale. Devs can generate codes on their central management panel and send them to field agents to link their work numbers.\n\n### B. Remote Support & Onboarding\nIf your customer is non-technical and struggling to scan a QR code (due to a cracked camera or low screen brightness), your support agent can generate a Pairing Code for them and read it aloud during a support call, resulting in a successful link in seconds.\n\n---\n\n## ⚠️ Common Pitfalls\n\n- **Retry Limit Abuse**: WhatsApp has a hidden internal rate limit for pairing codes. Requesting a code more than 3-5 times in a short window can cause WhatsApp to temporarily block the pairing feature for that phone number. \n- **Incorrect Status**: You can only request a code if the session status is **SCAN_QR_CODE**. If the session is already **WORKING**, the request will be rejected to prevent accidental hijacking of an active session.\n\n---\n\n## Summary of Responsibilities:\n- Initiate the Phone-Based Pairing protocol.\n- Retrieve a unique 8-character linking code.\n- Prepare the engine to listen for remote credential injection.\n- Support \"Mobile-Only\" onboarding flows where cameras are not used.\n            ",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "The 12-character ID of the instance",
          "example": "Your_Instance_ID"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "phone_number": {
          "required": true,
          "type": "string",
          "description": "The phone number to link (e.g., 201145202826)",
          "example": "201145202826"
        }
      },
      "tips": [
        {
          "type": "info",
          "title": "Wait Time",
          "content": "WhatsApp generation takes 2-5 seconds. UI should show a spinner."
        },
        {
          "type": "warning",
          "title": "Rate Limit",
          "content": "Do not request codes frequently. WhatsApp may temporarily block the number."
        }
      ],
      "recommendations": [
        "Use this as a fallback for users with broken cameras.",
        "Display the 8-character code in a large, clear font with a countdown.",
        "Ensure the session is in 'SCAN_QR_CODE' status before requesting."
      ],
      "responses": [
        {
          "status": 200,
          "description": "Success - Linking Code Generated",
          "contentType": "application/json",
          "example": {
            "code": "ABCD-1234"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 422,
          "description": "Unprocessable Entity - Session Status Mismatch",
          "contentType": "application/json",
          "example": {
            "code": "session_unexpected_status",
            "message": "Session status is not as expected for this operation. We are attempting to auto-recover.",
            "details": {
              "current_status": "FAILED",
              "expected_status": [
                "SCAN_QR_CODE"
              ],
              "action": "auto_restart_triggered",
              "recommendation": "The instance encountered an error and is being restarted. Please wait a few seconds and try again."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "طلب كود الربط (تسجيل الدخول بالهاتف)",
          "description": "يطلب كود ربط للمصادقة القائمة على الهاتف في واتساب (بأسلوب OTP).",
          "recommendations": [
            "استخدم هذا كحل بديل للمستخدمين الذين لديهم كاميرات معطلة.",
            "اعرض الكود المكون من 8 أحرف بخط كبير وواضح مع عد تنازلي.",
            "تأكد من أن الجلسة في حالة 'SCAN_QR_CODE' قبل الطلب."
          ],
          "extraInfo": "\n# الربط بدون واجهة: قوة أكواد الاقتران عبر الهاتف\n\nيُعد الرابط `/v2/auth/request-code` نقلة نوعية في أتمتة واتساب، وهو مصمم خصيصاً للبيئات التي يكون فيها مسح كود QR مستحيلاً فيزيائياً أو غير مريح تقنياً. تسمح لك هذه الطريقة بربط حساب واتساب بنسخة Wawp عن طريق إدخال كود أبجدي رقمي مكون من 8 رموز مباشرة في تطبيق واتساب على الهاتف.\n\n---\n\n## 🏗️ هندسة المصافحة الثنائية\nعند استدعاء هذا الرابط مع `phone_number`، تبدأ Wawp في تنسيق خلفي معقد:\n1. **الاستهداف**: ينشئ المحرك اتصالاً بخوادم واتساب و\"يعلن\" رغبته في الارتباط برقم الهاتف المقدم.\n2. **إنشاء الكود**: تتفاوض بنية Wawp التحتية على كود اقتران فريد وقصير الأجل مكون من 8 رموز (مثال: `ABCD-1234`).\n3. **ربط الجلسة**: يتم ربط الكود الناتج تشفيرياً بـ `instance_id` الخاص بك.\n4. **الانتظار التفاعلي**: يدخل المحرك في وضع \"الاستماع التفاعلي\"، بانتظار كتابة المستخدم لهذا الكود في جهازه المحمول.\n\n---\n\n## 🛡️ أفضل الممارسات الاستراتيجية\n\n### 1. توحيد أرقام الهواتف عالمياً\nيتبع واتساب تنسيقاً دولياً صارماً للأرقام. ستفشل العملية إذا كان التنسيق غير صحيح.\n- **إجراء المطور**: قبل تمرير رقم الهاتف، قم بتوحيده برمجياً:\n  - قم بإزالة جميع المسافات والواصلات والأقواس.\n  - قم بإزالة أي بادئة `+` أو `00`.\n  - تأكد من وجود رمز الدولة (مثال: استخدم `201112223333` بدلاً من `01112223333`).\n\n### 2. بناء تجربة مستخدم بأسلوب OTP\nبما أن المستخدم يحتاج لإدخال الكود في هاتفه، فإن تصميم واجهة المستخدم الخاصة بك أمر بالغ الأهمية.\n- **سير العمل**:\n  - اعرض الكود المكون من 8 رموز **بخط كبير وعريض**.\n  - وفر مؤقت عد تنازلي (الأكواد صالحة لمدة تقريبية 2-5 دقائق).\n  - أضف دليلاً بسيطاً للمستخدم: **واتساب -> الإعدادات -> الأجهزة المرتبطة -> الربط باستخدام رقم الهاتف**.\n\n### 3. التعامل مع حالة 422 \"غير جاهز\"\nإذا كان المحرك قيد التشغيل للتو، فقد لا يكون جاهزاً لإنشاء الكود فوراً.\n- **الاستجابة**: ستتلقى خطأ `422 Session Status Not Expected`. هذا يشير إلى أن المحرك في مرحلة \"التسخين\". انتظر 10 ثوانٍ قبل السماح للمستخدم بالنقر على زر \"إنشاء الكود\" مرة أخرى.\n\n---\n\n## 💡 حالات الاستخدام القياسية\n\n### أ. تهيئة الخوادم بدون واجهة رسومية (Headless)\nللعملاء الذين يديرون مئات الحسابات على خوادم لينكس معزولة بدون شاشات، تعد طريقة كود الاقتران هي الطريقة الوحيدة للتوسع.\n\n### ب. الدعم الفني والربط عن بُعد\nإذا كان العميل يواجه صعوبة في مسح كود QR (بسبب كاميرا تالفة أو ضعف إضاءة الشاشة)، يمكن لموظف الدعم إنشاء كود اقتران وإملائه للعميل هاتفياً، مما يضمن نجاح الربط في ثوانٍ.\n\n---\n\n## ⚠️ الأخطاء الشائعة\n- **إساءة استخدام حد المحاولات**: لدى واتساب حد داخلي لعدد مرات طلب أكواد الاقتران. طلب الكود أكثر من 3-5 مرات في وقت قصير قد يؤدي لحظر الميزة مؤقتاً لهذا الرقم.\n- **الحالة غير الصحيحة**: يمكنك طلب الكود فقط إذا كانت حالة الجلسة هي **SCAN_QR_CODE**.\n\n---\n\n## ملخص المسؤوليات:\n- بدء بروتوكول الاقتران عبر الهاتف.\n- استرداد كود ربط فريد مكون من 8 رموز.\n- تهيئة المحرك للاستماع لحقن أوراق الاعتماد عن بُعد.\n- دعم عمليات الربط \"عبر الهاتف فقط\" في الحالات التي لا تُستخدم فيها الكاميرات.\n            ",
          "args": {
            "instance_id": {
              "description": "معرف النسخة المكون من 12 رمزاً"
            },
            "access_token": {
              "description": "مفتاح الوصول الخاص بـ API"
            },
            "phone_number": {
              "description": "رقم الهاتف المراد ربطه (مثال: 201145202826)"
            }
          },
          "tips": [
            {
              "title": "وقت الانتظار",
              "content": "يستغرق توليد واتساب من 2 إلى 5 ثوانٍ. يجب أن تظهر واجهة المستخدم مؤشر تحميل."
            },
            {
              "title": "حد المعدل",
              "content": "لا تطلب الرموز بشكل متكرر. قد يقوم واتساب بحظر الرقم مؤقتًا."
            }
          ]
        }
      }
    },
    {
      "path": "/v2/messaging-overview",
      "methods": [
        "GET"
      ],
      "category": "Send Messages",
      "isArticle": true,
      "title": "Messaging Guide",
      "description": "Overview of Wawp's Messaging capabilities and best practices.",
      "extraInfo": "\n# The Art of Omnichannel Engagement: Mastering Wawp Messaging\n\nWawp’s messaging suite is the core of our platform, designed to transform how businesses interact with the WhatsApp ecosystem. By centralizing text, media, and interactive chat actions behind a consistent, hardened proxy, Wawp makes high-volume messaging reliable, efficient, and safe for production-grade environments. Whether you are building a simple notification service or a complex, AI-driven customer support bot, understanding the nuances of our messaging engine is key to success.\n\n![Messaging Guide](https://api.apidog.com/api/v1/projects/1017306/resources/361311/image-preview)\n\n---\n\n## 🏗️ Architectural Philosophy: The Stateless Proxy\n\nUnlike direct browser-based automation, Wawp’s messaging engine operates as a **Stateless Event Proxy**. When you send a message, it doesn't just \"hit\" a browser; it undergoes a multi-stage validation and optimization process:\n1. **Schema Validation**: Every request is instantly checked against our internal schemas (validating `chatId` formats, media types, and required fields).\n2. **Buffer Management**: For media messages, the engine handles the binary stream directly, ensuring that large videos or documents don't cause memory spikes in your application.\n3. **Optimized Queuing**: While your request is async from the server perspective, our engine manages a localized queue to ensure messages are delivered in the order they were received, preventing \"out-of-sync\" conversations.\n\n---\n\n## 🛡️ Strategic Best Practices for Sustainable Growth\n\nWhatsApp is a protected network. To ensure your account remains in good standing while delivering high engagement, follow these three pillars of \"Responsible Automation\":\n\n### 1. The \"Human Mimicry\" Strategy\nWhatsApp’s AI-driven anti-spam filters look for patterns that don't match human behavior. \n- **Variable Delays**: Never send 100 messages at the exact same millisecond. Use a jittered interval approach (e.g., 2–5 seconds between messages).\n- **Interactive Warm-up**: If using a new number, start with low intensity and encourage replies. High reply rates are the \"green flag\" for WhatsApp's reliability algorithms.\n\n### 2. Intelligent Data Management\nWith Wawp, we adhere to a **Privacy-First Protocol**. We do not store your message content in our long-term database after it has been handed over to the WhatsApp network.\n- **Developer Action**: Always store your own message logs in your database. Use our `message_id` as the foreign key to track delivery status via our Webhooks.\n\n### 3. Media Precision\nDon't just send files; send the *right* files. \n- **Mime Awareness**: Ensure your `mimetype` matches the actual file extension. Misaligned headers can cause rendering issues on the recipient's phone.\n- **Optimization**: WhatsApp compresses images and videos. For the best quality, use our [`/v2/media/convert`](/v2/media/convert) utility to prepare your media before sending.\n\n---\n\n## 🧩 Advanced Messaging Logic\n\n### <a id=\"chatid-formats\"></a>Targeting the Right Audience (Chat ID Formats)\n\nUnderstanding the destination is half the battle. Wawp supports four distinct destination types:\n\n| Context         | Syntax                 | Scenario                                                                 |\n| --------------- | ---------------------- | ------------------------------------------------------------------------ |\n| **Individual**  | `[number]@c.us`        | Standard private chat. No `+` or leading zeros.                        |\n| **Groups**      | `[random-id]@g.us`     | Internal WhatsApp Group strings.                                         |\n| **Identity (LID)**| `[id]@lid`             | Used for \"Hidden\" identities in large communities or new privacy flows. |\n| **Channels**    | `[id]@newsletter`      | One-way broadcasts. Requries specific permissions to post.                |\n\n---\n\n## 📡 The Lifecycle of a Message\n\nA message sent via Wawp isn't just \"sent.\" It passes through several technical states:\n1. **PENDING**: The request is validated and added to the local engine queue.\n2. **SENT**: The engine successfully handed the message to the WhatsApp WebSocket.\n3. **DELIVERED**: The recipient's device acknowledged receipt.\n4. **READ**: (Optional) The recipient opened the message (requires read receipts to be enabled).\n\nUse our **Webhooks** to listen for these state changes to build \"Delivery Confirmation\" indicators in your UI.\n\n---\n\n## 🛠️ Common Operational Pitfalls\n\n- **Payload Bloat**: Sending excessive text (over 4096 characters) in a single message can cause the engine to truncate content or return an error.\n- **Malformed Identifiers**: Including characters like `+` or spaces in the `chatId` is the #1 cause of `400 Bad Request` errors.\n- **Session Wake-up**: If your session is in **STOPPED** status, messaging will fail. Always check [`/v2/session/info`](/v2/session/info) before initiating a campaign.\n\n---\n\n## 🧪 Interactive Elements: Beyond Just Text\n\nModern engagement relies on structure. Wawp supports advanced interactive types:\n- **Polls**: Gather consensus within groups without clogging the chat.\n- **List Messages**: provide clean, selectable menus (ideal for Support Bots).\n- **Template Events**: Perfect for reminders or webinar invites.\n\n---\n\n## Summary of Capabilities:\n- Send global, high-volume messages via a secure proxy.\n- Support for 12+ media and interactive types.\n- Automatic binary stream handling for large files.\n- Real-time delivery tracking via Webhook integration.\n- Intelligent error reporting with actionable status codes.\n    ",
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "Bulk Sending",
          "content": "For large campaigns, we recommend spacing out messages to mimic natural human behavior."
        }
      ],
      "recommendations": [
        "Include a clear way for users to opt-out of communications.",
        "Use webhooks to track delivery status if your application requires confirmation."
      ],
      "responses": [],
      "translations": {
        "ar": {
          "title": "دليل المراسلة",
          "description": "نظرة عامة على إمكانيات المراسلة في Wawp وأفضل الممارسات.",
          "tips": [
            {
              "title": "حدود معدل API",
              "content": "احترم حدود معدل API لتجنب الحظر المؤقت."
            },
            {
              "title": "العمليات غير المتزامنة",
              "content": "معظم العمليات غير متزامنة. استخدم Webhooks للتحديثات في الوقت الفعلي."
            }
          ],
          "recommendations": [
            "استخدم متغيرات البيئة لبيانات الاعتماد الحساسة مثل رموز الوصول.",
            "قم بتنفيذ معالجة قوية للأخطاء ومنطق إعادة المحاولة."
          ],
          "extraInfo": "\n# فن التفاعل عبر القنوات المتعددة: إتقان المراسلة عبر Wawp\n\nتعد مجموعة مراسلة Wawp جوهر منصتنا، وهي مصممة لإحداث ثورة في كيفية تفاعل الشركات مع منظومة واتساب. من خلال مركزية النصوص والوسائط وإجراءات الدردشة التفاعلية خلف بروكسي متسق وقوي، تجعل Wawp المراسلة عالية المجلد موثوقة وفعالة وآمنة لبيئات الإنتاج. سواء كنت تبني خدمة إشعارات بسيطة أو بوت دعم عملاء معقدًا يعتمد على الذكاء الاصطناعي، فإن فهم تفاصيل محرك المراسلة لدينا هو مفتاح النجاح.\n\n![دليل المراسلة](https://api.apidog.com/api/v1/projects/1017306/resources/361311/image-preview)\n\n---\n\n## 🏗️ الفلسفة المعمارية: البروكسي عديم الحالة (Stateless Proxy)\n\nعلى عكس أتمتة المتصفح المباشرة، يعمل محرك مراسلة Wawp كـ **بروكسي أحداث عديم الحالة**. عندما ترسل رسالة، فإنها لا \"تصل\" فقط إلى المتصفح؛ بل تخضع لعملية تحقق وتحسين متعددة المراحل:\n1. **التحقق من المخطط (Schema Validation)**: يتم فحص كل طلب فورًا مقابل مخططاتنا الداخلية (التحقق من تنسيقات `chatId` وأنواع الوسائط والحقول المطلوبة).\n2. **إدارة المخزن المؤقت (Buffer Management)**: بالنسبة لرسائل الوسائط، يتعامل المحرك مع دفق البيانات الثنائية مباشرة، مما يضمن أن مقاطع الفيديو أو المستندات الكبيرة لا تسبب استهلاكًا مفاجئًا للذاكرة في تطبيقك.\n3. **زمام الأمور المحسن (Optimized Queuing)**: بينما يكون طلبك غير متزامن من منظور الخادم، يدير محركنا زمام أمور محليًا لضمان تسليم الرسائل بالترتيب الذي تم استلامها به، مما يمنع المحادثات \"خارج المزامنة\".\n\n---\n\n## 🛡️ أفضل الممارسات الاستراتيجية للنمو المستدام\n\nواتساب شبكة محمية. لضمان بقاء حسابك في وضع جيد مع تقديم تفاعل عالٍ، اتبع الركائز الثلاث لـ \"الأتمتة المسؤولة\":\n\n### 1. استراتيجية \"محاكاة البشر\"\nتبحث مرشحات واتساب لمكافحة البريد العشوائي المدعومة بالذكاء الاصطناعي عن الأنماط التي لا تتوافق مع السلوك البشري.\n- **تأخيرات متغيرة**: لا ترسل أبدًا 100 رسالة في نفس الملي ثانية بالضبط. استخدم نهج الفاصل الزمني المتردد (مثلاً، 2-5 ثوانٍ بين الرسائل).\n- **الإحماء التفاعلي**: إذا كنت تستخدم رقمًا جديدًا، ابدأ بكثافة منخفضة وشجع الردود. تعد معدلات الرد العالية بمثابة \"الضوء الأخضر\" لخوارزميات الموثوقية في واتساب.\n\n### 2. الإدارة الذكية للبيانات\nمع Wawp، نلتزم بـ **بروتوكول الخصوصية أولاً**. نحن لا نخزن محتوى رسالتك في قاعدة بياناتنا طويلة المدى بعد تسليمها إلى شبكة واتساب.\n- **إجراء المطور**: قم دائمًا بتخزين سجلات الرسائل الخاصة بك في قاعدة بياناتك. استخدم `message_id` الخاص بنا كمفتاح خارجي لتتبع حالة التسليم عبر Webhooks الخاصة بنا.\n\n### 3. دقة الوسائط\nلا ترسل ملفات فقط؛ أرسل الملفات *الصحيحة*.\n- **الوعي بنوع Mime**: تأكد من أن `mimetype` يتطابق مع امتداد الملف الفعلي. يمكن أن تؤدي الرؤوس غير المتوافقة إلى مشكلات في العرض على هاتف المستلم.\n- **التحسين**: يقوم واتساب بضغط الصور ومقاطع الفيديو. للحصول على أفضل جودة، استخدم أداة [`/v2/media/convert`](/v2/media/convert) الخاصة بنا لإعداد الوسائط قبل إرسالها.\n\n---\n\n## 🧩 منطق المراسلة المتقدم\n\n### استهداف الجمهور الصحيح (تنسيقات معرف الدردشة)\n\nفهم الوجهة هو نصف المعركة. يدعم Wawp أربعة أنواع متميزة من الوجهات:\n\n| السياق | الصيغة | السيناريو |\n| :--- | :--- | :--- |\n| **الأفراد** | `[number]@c.us` | دردشة خاصة قياسية. لا يوجد `+` أو أصفار بادئة. |\n| **المجموعات** | `[random-id]@g.us` | سلاسل مجموعات واتساب الداخلية. |\n| **الهوية (LID)** | `[id]@lid` | يستخدم للهويات \"المخفية\" في المجتمعات الكبيرة أو تدفقات الخصوصية الجديدة. |\n| **القنوات** | `[id]@newsletter` | بث في اتجاه واحد. يتطلب أذونات محددة للنشر. |\n\n---\n\n## 📡 دورة حياة الرسالة\n\nالرسالة المرسلة عبر Wawp لا يتم \"إرسالها\" فحسب. بل تمر عبر عدة حالات تقنية:\n1. **PENDING (قيد الانتظار)**: تم التحقق من الطلب وإضافته إلى زمام أمور المحرك المحلي.\n2. **SENT (مرسل)**: نجح المحرك في تسليم الرسالة إلى WebSocket الخاص بواتساب.\n3. **DELIVERED (تم التسليم)**: أكد جهاز المستلم الاستلام.\n4. **READ (تمت القراءة)**: (اختياري) فتح المستلم الرسالة (يتطلب تفعيل مؤشرات القراءة).\n\nاستخدم **Webhooks** للاستماع إلى هذه التغييرات في الحالة لبناء مؤشرات \"تأكيد التسليم\" في واجهة المستخدم الخاصة بك.\n\n---\n\n## 🛠️ المزالق التشغيلية الشائعة\n\n- **تضخم الحمولة**: إرسال نص مفرط (أكثر من 4096 حرفًا) في رسالة واحدة قد يتسبب في قيام المحرك باقتطاع المحتوى أو إرجاع خطأ.\n- **المعرفات المشوهة**: تضمين رموز مثل `+` أو مسافات في `chatId` هو السبب الأول لأخطاء `400 Bad Request`.\n- **استيقاظ الجلسة**: إذا كانت جلستك في حالة **STOPPED**، فستفشل المراسلة. تحقق دائمًا من [`/v2/session/info`](/v2/session/info) قبل بدء الحملة.\n\n---\n\n## 🧪 العناصر التفاعلية: ما وراء النص فحسب\n\nيعتمد التفاعل الحديث على الهيكل. يدعم Wawp أنواعًا تفاعلية متقدمة:\n- **الاستطلاعات**: جمع الإجماع داخل المجموعات دون سد الدردشة.\n- **رسائل القائمة**: توفر قوائم نظيفة وقابلة للاختيار (مثالية لبوتات الدعم).\n- **أحداث القوالب**: مثالية للتذكيرات أو دعوات الندوات عبر الإنترنت.\n\n---\n\n## ملخص الإمكانيات:\n- إرسال رسائل عالمية عالية المجلد عبر بروكسي آمن.\n- دعم لأكثر من 12 نوعًا من الوسائط والعناصر التفاعلية.\n- معالجة تلقائية لدفق البيانات الثنائية للملفات الكبيرة.\n- تتبع التسليم في الوقت الفعلي عبر تكامل Webhook.\n- تقارير أخطاء ذكية مع أكواد حالة قابلة للتنفيذ.\n"
        }
      }
    },
    {
      "path": "/v2/send/text",
      "methods": [
        "POST",
        "GET"
      ],
      "title": "Send Text Message",
      "category": "Send Messages",
      "description": "Use for core text messaging. Required params: instance_id, access_token, chatId, message.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Unique ID of the WhatsApp session",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API access token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Recipient's WhatsApp ID (JID). Supports Individuals (@c.us), Groups (@g.us), and Newsletters (@newsletter).",
          "example": "447441429009@c.us"
        },
        "message": {
          "required": true,
          "type": "string",
          "description": "Message text to be sent",
          "example": "Hi from Wawp"
        },
        "reply_to": {
          "required": false,
          "type": "string",
          "description": "The ID of the message you are replying to",
          "example": "false_111...AAAA"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Message Sent Successfully",
          "contentType": "application/json",
          "example": {
            "_data": {
              "id": {
                "fromMe": true,
                "remote": "000000000000@c.us",
                "id": "MSG_ID_123456",
                "_serialized": "true_000000000000@c.us_MSG_ID_123456"
              },
              "viewed": false,
              "body": "BASE64_IMAGE_DATA",
              "type": "image",
              "t": 1759108866,
              "from": {
                "server": "c.us",
                "user": "111111111111",
                "_serialized": "111111111111@c.us"
              },
              "to": {
                "server": "c.us",
                "user": "000000000000",
                "_serialized": "000000000000@c.us"
              },
              "ack": 0,
              "isNewMsg": true,
              "star": false,
              "kicNotified": false,
              "caption": "Here's your requested image.",
              "deprecatedMms3Url": "https://example.com/media-url",
              "directPath": "/media/direct/path/example",
              "mimetype": "image/jpeg",
              "filehash": "FILE_HASH_PLACEHOLDER",
              "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
              "size": 192487,
              "mediaKey": "MEDIA_KEY_PLACEHOLDER",
              "mediaKeyTimestamp": 1759108865,
              "streamable": false,
              "mediaHandle": null,
              "isFromTemplate": false,
              "pollInvalidated": false,
              "isSentCagPollCreation": false,
              "latestEditMsgKey": null,
              "latestEditSenderTimestampMs": null,
              "mentionedJidList": [],
              "groupMentions": [],
              "isEventCanceled": false,
              "eventInvalidated": false,
              "isVcardOverMmsDocument": false,
              "isForwarded": false,
              "isQuestion": false,
              "questionReplyQuotedMessage": null,
              "questionResponsesCount": 0,
              "readQuestionResponsesCount": 0,
              "labels": [],
              "hasReaction": false,
              "disappearingModeInitiator": "chat",
              "disappearingModeTrigger": "chat_settings",
              "productHeaderImageRejected": false,
              "lastPlaybackProgress": 0,
              "isDynamicReplyButtonsMsg": false,
              "isCarouselCard": false,
              "parentMsgId": null,
              "callSilenceReason": null,
              "isVideoCall": false,
              "callDuration": null,
              "callCreator": null,
              "callParticipants": null,
              "isCallLink": null,
              "callLinkToken": null,
              "isMdHistoryMsg": false,
              "stickerSentTs": 0,
              "lastUpdateFromServerTs": 0,
              "invokedBotWid": null,
              "bizBotType": null,
              "botResponseTargetId": null,
              "botPluginType": null,
              "botPluginReferenceIndex": null,
              "botPluginSearchProvider": null,
              "botPluginSearchUrl": null,
              "botPluginSearchQuery": null,
              "botPluginMaybeParent": false,
              "botReelPluginThumbnailCdnUrl": null,
              "botMessageDisclaimerText": null,
              "botMsgBodyType": null,
              "requiresDirectConnection": false,
              "bizContentPlaceholderType": null,
              "hostedBizEncStateMismatch": false,
              "senderOrRecipientAccountTypeHosted": false,
              "placeholderCreatedWhenAccountIsHosted": false,
              "galaxyFlowDisabled": false,
              "links": []
            },
            "mediaKey": "MEDIA_KEY_PLACEHOLDER",
            "id": {
              "fromMe": true,
              "remote": "000000000000@c.us",
              "id": "MSG_ID_123456",
              "_serialized": "true_000000000000@c.us_MSG_ID_123456"
            },
            "ack": 0,
            "hasMedia": true,
            "body": "Here's your requested image.",
            "type": "image",
            "timestamp": 1759108866,
            "from": "111111111111@c.us",
            "to": "000000000000@c.us",
            "deviceType": "android",
            "isForwarded": false,
            "forwardingScore": 0,
            "isStatus": false,
            "isStarred": false,
            "fromMe": true,
            "hasQuotedMsg": false,
            "hasReaction": false,
            "vCards": [],
            "mentionedIds": [],
            "groupMentions": [],
            "isGif": false,
            "links": []
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Egypt)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Egypt mobile numbers must be 11 digits (national format).",
            "details": {
              "provided": "20114520282",
              "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
              "info": {
                "country": "EG",
                "type": "MOBILE"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Saudi Arabia)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for SA.",
            "details": {
              "provided": "96655555",
              "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
              "info": {
                "country": "SA"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Unknown)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for Unknown.",
            "details": {
              "provided": "01145202826",
              "recommendation": "Ensure individual numbers are in international format (starting with country code).",
              "info": {
                "country": "Unknown"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 429,
          "description": "Too Many Requests - Rate Limit Exceeded",
          "contentType": "application/json",
          "example": {
            "code": "rate_limit_exceeded",
            "message": "Too many requests. Please slow down.",
            "details": {
              "retryAfter": 60,
              "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
              "upstream": {
                "error": "Rate limit",
                "statusCode": 429
              }
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "extraInfo": "\n# Narrative Power: Mastering the Core Text Engine\n\nThe `/v2/send/text` endpoint is the most fundamental and frequently used tool in the Wawp arsenal. While it may seem simple to \"just send text,\" this endpoint is powered by a high-performance rendering engine that manages character encoding, markdown parsing, and delivery synchronization. For businesses, this is the primary channel for notifications, support responses, and conversational marketing.\n\n![send text.png](https://api.apidog.com/api/v1/projects/1017306/resources/369237/image-preview)\n\n---\n\n## 🏗️ Technical Architecture of the Text Pipeline\n\nWhen a POST request hits this endpoint, Wawp initiates a stateless workflow:\n1. **Normalization**: The `chatId` is sanitized (removing `+` or extraneous spaces) and verified against the WhatsApp network routing table.\n2. **Text Bufferings**: The `message` string is buffered to prevent memory overflow. WhatsApp supports up to **4,096 characters**, and our proxy enforces this limit to ensure upstream delivery remains atomic.\n3. **Markdown Pre-processing**: Wawp preserves WhatsApp-specific markdown (e.g., `*bold*`, `_italic_`, `~strikethrough~`, and ```code blocks```). This allows you to send rich, structured text without needing complex HTML or XML wrappers.\n\n---\n\n## 🛡️ Strategic Best Practices for Developers\n\n### 1. The Optimistic UI Pattern\nFor high-quality user experiences, don't make the user wait for the API response before showing the message in your frontend. \n- **Implementation**: When the user clicks \"Send,\" immediately render the message in your chat UI with a \"Sending...\" indicator. Call [`/v2/send/start-typing`](/v2/send/start-typing) a few seconds before the actual POST to mimic human behavior. Once the `/send/text` returns a `message_id`, update the UI state to \"Sent.\"\n\n### 2. Handling Character Complexity\nIf you are sending technical logs, code snippets, or non-Latin character sets (Arabic, Mandarin, etc.), note that:\n- **Encoding**: Wawp uses UTF-8 encoding by default. Ensure your application server sends the correct `Content-Type: application/json` headers to prevent character corruption.\n- **Truncation Safety**: If your text exceeds 4,000 characters, we recommend splitting it into multiple logical messages or using the CLIP (Copy Link in Profile) strategy to host longer content on a web page.\n\n### 3. Error Recovery and Upstream Reliability\nOccasionally, the WhatsApp network (Upstream) may experience transient lag.\n- **The \"2xx vs Delivery\" Fallacy**: A `200 OK` from Wawp means the message was successfully accepted and queued for delivery to the engine. It does not guarantee the recipient's phone is on.\n- **Monitoring**: Always use **Webhooks** (`message.ack`) to track when the status moves from \"Sent\" (1 checkmark) to \"Delivered\" (2 checkmarks) and finally \"Read\" (blue checkmarks).\n\n---\n\n## 🧩 Advanced Use Cases\n\n### Variable Injection and Templating\nBecause Wawp is stateless, you can easily build a templating engine on your side. \n- **Example**: \"Hi {{name}}, your order #{{order_id}} is ready!\"\n- **Technique**: Perform the string replacement in your backend before sending the final string to Wawp. This keeps the logic localized to your business rules while Wawp handles the heavy lifting of delivery.\n\n### Threaded Conversations (Reply-to)\nBy including the `reply_to` parameter (the `message_id` of a previous message), you can create structured threads. This is crucial for:\n- Support systems where the agent needs to clarify a specific customer question.\n- Group chats where multiple topics are being discussed simultaneously.\n\n---\n\n## 🛠️ Common Pitfalls and Solutions\n\n- **Forbidden Characters**: While emojis are fully supported, stay away from low-level control characters (`\\x00-\\x1F`) which can trigger security flags or cause the engine to crash.\n- **Empty Messages**: Sending an empty `message` or one consisting only of whitespace will return a `400 Bad Request`. Always validate your input fields.\n- **Rate Overload**: Sending 1,000 text messages to the same user in 60 seconds is a guaranteed \"spam\" flag. Use a sane \"Consumer Protection\" delay (minimum 1 second between messages to the same recipient).\n\n---\n\n## Summary of Capabilities:\n- Send structured, rich text with full support for WhatsApp Markdown.\n- High-concurrency support for notification and alert systems.\n- Seamless integration with threading/replies via `reply_to`.\n- Real-time event tracking through consistent `message_id` generation.\n- Support for all global languages and emoji sets via UTF-8.\n",
      "image": "https://api.apidog.com/api/v1/projects/1017306/resources/369237/image-preview",
      "tips": [
        {
          "type": "positive",
          "title": "Optimistic UI",
          "content": "Send instantly with optimistic UI ( [show “typing...”](https://docs.wawp.net/start-typing-19609223e0) then update on response)."
        },
        {
          "type": "info",
          "title": "Character Limits",
          "content": "WhatsApp supports up to 4096 characters per message. However, for marketing or automated alerts, keep it under 1000 for better readability."
        }
      ],
      "recommendations": [
        "Include a clear way for users to opt-out of communications.",
        "Use webhooks to track delivery status if your application requires confirmation.",
        "Implement a retry strategy with exponential backoff for 'wawp_upstream_error' scenarios."
      ],
      "translations": {
        "ar": {
          "title": "إرسال رسالة نصية",
          "description": "استخدم للإرسال الأساسي للرسائل النصية. المعلمات المطلوبة: instance_id، access_token، chatId، message.",
          "extraInfo": "\n# قوة السرد: إتقان محرك النصوص الأساسي\n\nتعد نقطة النهاية `/v2/send/text` الأداة الأكثر جوهرية واستخدامًا في ترسانة Wawp. وبينما قد يبدو إرسال \"نص فقط\" أمرًا بسيطًا، إلا أن نقطة النهاية هذه مدعومة بمحرك عرض عالي الأداء يدير ترميز الأحرف، وتحليل Markdown، ومزامنة التسليم. بالنسبة للشركات، تعد هذه القناة الرئيسية للإشعارات واستجابات الدعم والتسويق الحواري.\n\n![إرسال نص](https://api.apidog.com/api/v1/projects/1017306/resources/369237/image-preview)\n\n---\n\n## 🏗️ البنية التقنية لمسار النصوص\n\nعندما يصل طلب POST إلى هذه النقطة، يبدأ Wawp سير عمل عديم الحالة:\n1. **التطبيع (Normalization)**: يتم تنظيف `chatId` (إزالة رموز `+` أو المسافات الزائدة) والتحقق منه مقابل جدول توجيه شبكة واتساب.\n2. **تخزين النصوص مؤقتًا (Text Buffering)**: يتم تخزين سلسلة `message` مؤقتًا لمنع تجاوز سعة الذاكرة. يدعم واتساب ما يصل إلى **4096 حرفًا**، ويقوم البروكسي الخاص بنا بفرض هذا الحد لضمان بقاء التسليم ذريًا.\n3. **المعالجة المسبقة لـ Markdown**: يحافظ Wawp على تنسيق Markdown الخاص بواتساب (مثل `*bold*` للخط العريض، `_italic_` للمائل، `~strikethrough~` للشطب، وكُتل الكود ```code blocks```). يتيح لك ذلك إرسال نصوص غنية ومنظمة دون الحاجة إلى أغلفة HTML أو XML معقدة.\n\n---\n\n## 🛡️ أفضل الممارسات الاستراتيجية للمطورين\n\n### 1. نمط واجهة المستخدم المتفائلة (Optimistic UI Pattern)\nللحصول على تجارب مستخدم عالية الجودة، لا تجعل المستخدم ينتظر استجابة API قبل عرض الرسالة في واجهتك الأمامية.\n- **التنفيذ**: عندما ينقر المستخدم على \"إرسال\"، قم فورًا بعرض الرسالة في واجهة الدردشة مع مؤشر \"جاري الإرسال...\". اتصل بـ [`/v2/send/start-typing`](/v2/send/start-typing) قبل بضع ثوانٍ من طلب POST الفعلي لمحاكاة السلوك البشري. بمجرد أن تعيد `/send/text` معرف `message_id`، قم بتحديث حالة واجهة المستخدم إلى \"تم الإرسال\".\n\n### 2. التعامل مع تعقيد الأحرف\nإذا كنت ترسل سجلات تقنية، أو قصاصات برمجية، أو مجموعات أحرف غير لاتينية (العربية، الماندرين، إلخ)، فلاحظ ما يلي:\n- **الترميز**: يستخدم Wawp ترميز UTF-8 افتراضيًا. تأكد من أن خادم تطبيقك يرسل رؤوس `Content-Type: application/json` الصحيحة لمنع تلف الأحرف.\n- **سلامة الاقتطاع**: إذا تجاوز نصك 4000 حرف، نوصي بتقسيمه إلى عدة رسائل منطقية أو استخدام استراتيجية CLIP لاستضافة محتوى أطول على صفحة ويب.\n\n### 3. استعادة الأخطاء وموثوقية الاتصال\nفي بعض الأحيان، قد تواجه شبكة واتساب تأخيرًا عابرًا.\n- **مغالطة \"2xx مقابل التسليم\"**: تعني استجابة `200 OK` من Wawp أنه تم قبول الرسالة بنجاح ووضعها في زمام الأمور للتسليم. هذا لا يضمن أن هاتف المستلم قيد التشغيل.\n- **المراقبة**: استخدم دائمًا **Webhooks** (`message.ack`) لتتبع متى تنتقل الحالة من \"مرسل\" (علامة صح واحدة) إلى \"تم التسليم\" (علامتان) وأخيرًا \"تمت القراءة\" (علامتان زرقاوان).\n\n---\n\n## 🧩 حالات استخدام متقدمة\n\n### حقن المتغيرات والقوالب\nنظرًا لأن Wawp عديم الحالة، يمكنك بسهولة بناء محرك قوالب من جانبك.\n- **مثال**: \"مرحبًا {{name}}، طلبك رقم #{{order_id}} جاهز!\"\n- **التقنية**: قم بإجراء استبدال السلسلة في خلفية تطبيقك قبل إرسال السلسلة النهائية إلى Wawp. هذا يبقي المنطق محليًا لقواعد عملك بينما يتعامل Wawp مع عبء التسليم الثقيل.\n\n### المحادثات المتسلسلة (Reply-to)\nمن خلال تضمين معلمة `reply_to` (معرف `message_id` لرسالة سابقة)، يمكنك إنشاء خيوط محادثة منظمة. هذا أمر بالغ الأهمية لـ:\n- أنظمة الدعم حيث يحتاج الوكيل إلى توضيح سؤال محدد للعميل.\n- المجموعات حيث تتم مناقشة مواضيع متعددة في وقت واحد.\n\n---\n\n## 🛠️ المزالق الشائعة والحلول\n\n- **الأحرف المحظورة**: في حين أن الرموز التعبيرية (Emoji) مدعومة بالكامل، ابتعد عن أحرف التحكم منخفضة المستوى (`\\x00-\\x1F`) التي يمكن أن تطلق تنبيهات أمنية أو تتسبب في تعطل المحرك.\n- **الرسائل الفارغة**: إرسال `message` فارغ أو يتكون من مسافات فقط سيعيد خطأ `400 Bad Request`. قم دائمًا بالتحقق من صحة حقول الإدخال.\n- **تجاوز معدل الإرسال**: إرسال 1000 رسالة نصية لنفس المستخدم في 60 ثانية هو علامة \"بريد عشوائي\" مضمونة. استخدم تأخيرًا معقولًا لـ \"حماية المستهلك\" (بحد أدنى ثانية واحدة بين الرسائل لنفس المستلم).\n\n---\n\n## ملخص الإمكانيات:\n- إرسال نصوص منظمة وغنية بدعم كامل لـ Markdown الخاص بواتساب.\n- دعم عالي للتزامن لأنظمة الإشعارات والتنبيهات.\n- تكامل سلس مع الردود/الخيوط عبر `reply_to`.\n- تتبع الأحداث في الوقت الفعلي من خلال توليد متسق لـ `message_id`.\n- دعم لجميع اللغات العالمية ومجموعات الرموز التعبيرية عبر UTF-8.\n",
          "args": {
            "instance_id": {
              "description": "المعرف الفريد لجلسة واتساب"
            },
            "access_token": {
              "description": "رمز وصول API"
            },
            "chatId": {
              "description": "معرف واتساب للمستلم (JID). يدعم الأفراد (@c.us)، المجموعات (@g.us)، والقنوات (@newsletter)."
            },
            "message": {
              "description": "نص الرسالة المراد إرسالها"
            },
            "reply_to": {
              "description": "معرف الرسالة التي تقوم بالرد عليها"
            }
          },
          "tips": [
            {
              "title": "واجهة مستخدم متفائلة",
              "content": "أرسل الفورية باستخدام واجهة مستخدم متفائلة ( [إظهار جاري الكتابة...](https://docs.wawp.net/start-typing-19609223e0) ثم التحديث عند الاستجابة)."
            },
            {
              "title": "حدود الأحرف",
              "content": "يدعم واتساب ما يصل إلى 4096 حرفًا لكل رسالة. ومع ذلك، للتسويق أو التنبيهات المؤتمتة، اجعلها أقل من 1000 لسهولة القراءة."
            }
          ],
          "recommendations": [
            "قم بتضمين طريقة واضحة للمستخدمين لإلغاء الاشتراك في الاتصالات.",
            "استخدم Webhooks لتتبع حالة التسليم إذا كان تطبيقك يتطلب تأكيدًا.",
            "قم بتنفيذ استراتيجية تكرار مع تراجع أسي لسيناريوهات 'wawp_upstream_error'."
          ]
        }
      }
    },
    {
      "path": "/v2/send/image",
      "methods": [
        "POST",
        "GET"
      ],
      "title": "Send Image",
      "category": "Send Messages",
      "description": "SendImage expects a file object (url, mimetype, filename) and required caption/reply_to.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Unique ID of the WhatsApp session",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API access token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Recipient's WhatsApp ID (JID). Supports Individuals (@c.us), Groups (@g.us), and Newsletters (@newsletter).",
          "example": "447441429009@c.us"
        },
        "file[url]": {
          "required": true,
          "type": "string",
          "description": "Publicly accessible HTTPS URL of the image",
          "example": "https://wawp.net/samples/cat.jpg"
        },
        "file[filename]": {
          "required": true,
          "type": "string",
          "description": "Filename for the image",
          "example": "image.jpg"
        },
        "file[mimetype]": {
          "required": true,
          "type": "string",
          "description": "MIME type (image/jpeg or image/png)",
          "example": "image/jpeg"
        },
        "caption": {
          "required": true,
          "type": "string",
          "description": "Caption for the image",
          "example": "Here's your requested image."
        },
        "reply_to": {
          "required": false,
          "type": "string",
          "description": "The ID of the message you are replying to",
          "example": "false_111...AAAA"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Message Sent Successfully",
          "contentType": "application/json",
          "example": {
            "_data": {
              "id": {
                "fromMe": true,
                "remote": "000000000000@c.us",
                "id": "MSG_ID_123456",
                "_serialized": "true_000000000000@c.us_MSG_ID_123456"
              },
              "viewed": false,
              "body": "BASE64_IMAGE_DATA",
              "type": "image",
              "t": 1759108866,
              "from": {
                "server": "c.us",
                "user": "111111111111",
                "_serialized": "111111111111@c.us"
              },
              "to": {
                "server": "c.us",
                "user": "000000000000",
                "_serialized": "000000000000@c.us"
              },
              "ack": 0,
              "isNewMsg": true,
              "star": false,
              "kicNotified": false,
              "caption": "Here's your requested image.",
              "deprecatedMms3Url": "https://example.com/media-url",
              "directPath": "/media/direct/path/example",
              "mimetype": "image/jpeg",
              "filehash": "FILE_HASH_PLACEHOLDER",
              "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
              "size": 192487,
              "mediaKey": "MEDIA_KEY_PLACEHOLDER",
              "mediaKeyTimestamp": 1759108865,
              "streamable": false,
              "mediaHandle": null,
              "isFromTemplate": false,
              "pollInvalidated": false,
              "isSentCagPollCreation": false,
              "latestEditMsgKey": null,
              "latestEditSenderTimestampMs": null,
              "mentionedJidList": [],
              "groupMentions": [],
              "isEventCanceled": false,
              "eventInvalidated": false,
              "isVcardOverMmsDocument": false,
              "isForwarded": false,
              "isQuestion": false,
              "questionReplyQuotedMessage": null,
              "questionResponsesCount": 0,
              "readQuestionResponsesCount": 0,
              "labels": [],
              "hasReaction": false,
              "disappearingModeInitiator": "chat",
              "disappearingModeTrigger": "chat_settings",
              "productHeaderImageRejected": false,
              "lastPlaybackProgress": 0,
              "isDynamicReplyButtonsMsg": false,
              "isCarouselCard": false,
              "parentMsgId": null,
              "callSilenceReason": null,
              "isVideoCall": false,
              "callDuration": null,
              "callCreator": null,
              "callParticipants": null,
              "isCallLink": null,
              "callLinkToken": null,
              "isMdHistoryMsg": false,
              "stickerSentTs": 0,
              "lastUpdateFromServerTs": 0,
              "invokedBotWid": null,
              "bizBotType": null,
              "botResponseTargetId": null,
              "botPluginType": null,
              "botPluginReferenceIndex": null,
              "botPluginSearchProvider": null,
              "botPluginSearchUrl": null,
              "botPluginSearchQuery": null,
              "botPluginMaybeParent": false,
              "botReelPluginThumbnailCdnUrl": null,
              "botMessageDisclaimerText": null,
              "botMsgBodyType": null,
              "requiresDirectConnection": false,
              "bizContentPlaceholderType": null,
              "hostedBizEncStateMismatch": false,
              "senderOrRecipientAccountTypeHosted": false,
              "placeholderCreatedWhenAccountIsHosted": false,
              "galaxyFlowDisabled": false,
              "links": []
            },
            "mediaKey": "MEDIA_KEY_PLACEHOLDER",
            "id": {
              "fromMe": true,
              "remote": "000000000000@c.us",
              "id": "MSG_ID_123456",
              "_serialized": "true_000000000000@c.us_MSG_ID_123456"
            },
            "ack": 0,
            "hasMedia": true,
            "body": "Here's your requested image.",
            "type": "image",
            "timestamp": 1759108866,
            "from": "111111111111@c.us",
            "to": "000000000000@c.us",
            "deviceType": "android",
            "isForwarded": false,
            "forwardingScore": 0,
            "isStatus": false,
            "isStarred": false,
            "fromMe": true,
            "hasQuotedMsg": false,
            "hasReaction": false,
            "vCards": [],
            "mentionedIds": [],
            "groupMentions": [],
            "isGif": false,
            "links": []
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Egypt)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Egypt mobile numbers must be 11 digits (national format).",
            "details": {
              "provided": "20114520282",
              "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
              "info": {
                "country": "EG",
                "type": "MOBILE"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Saudi Arabia)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for SA.",
            "details": {
              "provided": "96655555",
              "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
              "info": {
                "country": "SA"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Unknown)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for Unknown.",
            "details": {
              "provided": "01145202826",
              "recommendation": "Ensure individual numbers are in international format (starting with country code).",
              "info": {
                "country": "Unknown"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 429,
          "description": "Too Many Requests - Rate Limit Exceeded",
          "contentType": "application/json",
          "example": {
            "code": "rate_limit_exceeded",
            "message": "Too many requests. Please slow down.",
            "details": {
              "retryAfter": 60,
              "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
              "upstream": {
                "error": "Rate limit",
                "statusCode": 429
              }
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "extraInfo": "\n# Visual Storytelling: Harnessing the Image Messaging Engine\n\nImages are the most engaging form of communication on WhatsApp. Whether it's a product catalog, a promotional banner, or a technical screenshot, the `/v2/send/image` endpoint provides a robust way to deliver high-quality visuals to your users. Wawp’s image engine handles the heavy lifting of fetching remote assets, validating MIME types, and ensuring that images are rendered correctly on all WhatsApp clients (Mobile, Web, and Desktop).\n\n---\n\n## 🏗️ The Multi-Stage Media Pipeline\n\nWhen you call the `/send/image` endpoint, Wawp orchestrates a complex background process:\n1. **Asynchronous Fetching**: The engine uses a high-speed fetcher to retrieve the file from the providing URL. We recommend using a Content Delivery Network (CDN) to ensure low-latency transfers.\n2. **Format Verification**: WhatsApp is strict about image standards. Our engine verifies that the file is a valid **PNG** or **JPEG**. If the upstream server provides a different format (like WebP or SVG via a mismatched extension), Wawp attempts to normalize the stream or returns an informative error code.\n3. **Caption Injection**: Unlike simple attachments, captions in Wawp are treated as first-class text citizens. They support full UTF-8 encoding and WhatsApp markdown (`*bold*`, etc.), allowing you to provide context directly alongside the visual.\n\n---\n\n## 🛡️ Strategic Best Practices for Media Delivery\n\n### 1. The Pre-fetch Metadata Pattern\nTo provide the best user experience, your application should know what it's sending before it hits our API.\n- **Validation**: Before calling the API, perform a `HEAD` request to the image URL to verify the `Content-Length` and `Content-Type`. This prevents \"Blind Sending\" which leads to higher failure rates.\n- **Client-Side Thumbs**: In your frontend, render a local thumbnail of the image. This gives the user immediate visual feedback while our engine handles the upstream delivery.\n\n### 2. File Size and Resolution Strategy\nWhile WhatsApp supports large files, efficiency is key to engagement.\n- **Optimal Resolution**: Aim for **1200x1600 pixels**. This provides a sharp, full-screen experience on most mobile devices without excessive bandwidth consumption.\n- **Compression**: Leverage our [`/v2/media/convert`](/v2/media/convert) endpoint if you need to downscale or compress high-resolution photography before sending it to a mass audience.\n\n### 3. URL Accessibility and Security\n- **Public Accessibility**: The `file[url]` must be publicly accessible via HTTPS. Our engine cannot bypass login screens or VPN-locked assets.\n- **Expiring Links**: If you use signed S3 URLs, ensure the expiration time is at least **5 minutes**. This gives the Wawp engine enough time to fetch and process the file even during peak traffic periods.\n\n---\n\n## 🧩 Advanced Use Cases\n\n### Catalog Branding\nImages are perfect for sending product highlights. Pair the image with a long, descriptive caption that includes a CTA (Call to Action) link. Since the caption remains attached to the image upon forwarding, your branding stays intact.\n\n### Technical Support via Visuals\nUse images to send \"Before/After\" comparisons or flow diagrams. By using the `reply_to` field, you can link an instruction image directly to a user's specific query, creating a seamless support thread.\n\n---\n\n## 🛠️ Common Pitfalls and Solutions\n\n- **Invalid Mime-Types**: Sending a `.jpg` file with an `image/gif` header is a common technical error. Wawp will return an `Unsupported Mimetype` error. Always ensure your server headers are correct.\n- **Filename Ambiguity**: Use descriptive but clean filenames (e.g., `invoice_123.jpg`). Avoid using special characters or spaces in the `file[filename]` parameter to ensure compatibility across different OS file systems.\n- **The \"Broken Thumbnail\" Issue**: If an image appears as a grey box on the recipient's phone, it usually means the source URL was cut off mid-download or the server returned a 404/500 code during Wawp's fetch phase.\n\n---\n\n## Summary of Capabilities:\n- Deliver high-fidelity JPEG and PNG images with integrated captions.\n- Remote fetching from any secure HTTPS URL.\n- Support for complex thread-nesting via the `reply_to` parameter.\n- Reliable MIME-type validation and header normalization.\n- Consistent success reporting with unique `message_id` generation for delivery tracking.\n",
      "image": "https://api.apidog.com/api/v1/projects/1017306/resources/369236/image-preview",
      "tips": [
        {
          "type": "positive",
          "title": "Direct Rendering",
          "content": "Display a client-side thumbnail before sending to give users immediate feedback."
        },
        {
          "type": "warning",
          "title": "Supported Formats",
          "content": "WhatsApp primarily accepts PNG and JPEG. Ensure your URLs point to valid image files."
        }
      ],
      "recommendations": [
        "Use \"reply_to\" to maintain conversation context.",
        "Handle distinct message types (text, image, video) appropriately.",
        "Implement a robust retry mechanism for failed sends."
      ],
      "translations": {
        "ar": {
          "title": "إرسال صورة",
          "description": "تتوقع SendImage كائن ملف (url، mimetype، filename) وشرح/رد مطلوب.",
          "recommendations": [
            "أضف تأخيرات عشوائية بين الرسائل لمحاكاة السلوك البشري.",
            "تحقق من أرقام الهواتف قبل الإرسال لضمان التسليم."
          ],
          "extraInfo": "\n# رواية القصص المرئية: تسخير محرك رسائل الصور\n\nالصور هي أكثر أشكال التواصل جاذبية على واتساب. سواء كان ذلك كتالوج منتجات، أو بنر ترويجي، أو لقطة شاشة تقنية، فإن نقطة النهاية `/v2/send/image` توفر طريقة قوية لتقديم مرئيات عالية الجودة لمستخدميك. يتعامل محرك صور Wawp مع الأعباء الثقيلة لجلب الأصول عن بُعد، والتحقق من أنواع MIME، وضمان عرض الصور بشكل صحيح على جميع عملاء واتساب (الجوال، الويب، وسطح المكتب).\n\n![إرسال صورة](https://api.apidog.com/api/v1/projects/1017306/resources/369236/image-preview)\n\n---\n\n## 🏗️ مسار الوسائط متعدد المراحل\n\nعندما تستدعي نقطة النهاية `/send/image`، ينظم Wawp عملية خلفية معقدة:\n1. **الجلب غير المتزامن (Asynchronous Fetching)**: يستخدم المحرك جالبًا عالي السرعة لاسترداد الملف من عنوان URL المقدم. نوصي باستخدام شبكة توصيل المحتوى (CDN) لضمان عمليات نقل منخفضة التأخير.\n2. **التحقق من التنسيق**: واتساب صارم بشأن معايير الصور. يتحقق محركنا من أن الملف هو **PNG** أو **JPEG** صالح. إذا قدم الخادم المصدر تنسيقًا مختلفًا (مثل WebP أو SVG عبر امتداد غير متطابق)، يحاول Wawp تطبيع الدفق أو يرجع رمز خطأ مفيدًا.\n3. **حقن الشرح (Caption Injection)**: على عكس المرفقات البسيطة، يتم التعامل مع الشروحات في Wawp كمواطنين نصيين من الدرجة الأولى. وهي تدعم ترميز UTF-8 الكامل وتنسيق Markdown الخاص بواتساب (`*bold*` إلخ)، مما يتيح لك تقديم سياق مباشر بجانب المرئيات.\n\n---\n\n## 🛡️ أفضل الممارسات الاستراتيجية لتسليم الوسائط\n\n### 1. نمط البيانات المسبقة (Pre-fetch Metadata Pattern)\nلتقديم أفضل تجربة مستخدم، يجب أن يعرف تطبيقك ما يرسله قبل أن يصل إلى واجهة البرمجة الخاصة بنا.\n- **التحقق**: قبل استدعاء API، قم بإجراء طلب `HEAD` لعنوان URL للصورة للتحقق من `Content-Length` و `Content-Type`. هذا يمنع \"الإرسال الأعمى\" الذي يؤدي إلى معدلات فشل أعلى.\n- **الصور المصغرة من جانب العميل**: في واجهتك الأمامية، قم بعرض صورة مصغرة محلية للصورة. يعطي هذا المستخدم ملاحظات مرئية فورية بينما يتعامل محركنا مع التسليم الأصلي.\n\n### 2. استراتيجية حجم الملف والدقة\nبينما يدعم واتساب الملفات الكبيرة، فإن الكفاءة هي مفتاح التفاعل.\n- **الدقة المثالية**: استهدف **1200x1600 بكسل**. يوفر هذا تجربة حادة بملء الشاشة على معظم الأجهزة المحمولة دون استهلاك مفرط للنطاق الترددي.\n- **الضغط**: استفد من نقطة النهاية [`/v2/media/convert`](/v2/media/convert) الخاصة بنا إذا كنت بحاجة إلى تقليل حجم الصور عالية الدقة أو ضغطها قبل إرسالها إلى جمهور كبير.\n\n### 3. سهولة الوصول إلى URL والأمان\n- **الوصول العام**: يجب أن يكون `file[url]` متاحًا علنًا عبر HTTPS. لا يمكن لمحركنا تجاوز شاشات تسجيل الدخول أو الأصول المقفولة بـ VPN.\n- **الروابط منتهية الصلاحية**: إذا كنت تستخدم روابط S3 الموقعة، فتأكد من أن وقت انتهاء الصلاحية لا يقل عن **5 دقائق**. يمنح هذا محرك Wawp وقتًا كافيًا لجلب الملف ومعالجته حتى في فترات ذروة الحركة.\n\n---\n\n## 🧩 حالات استخدام متقدمة\n\n### هوية الكتالوج\nالصور مثالية لإرسال أبرز ميزات المنتج. اربط الصورة بشرح وصفي طويل يتضمن رابطًا لاتخاذ إجراء (CTA). نظرًا لأن الشرح يظل مرفقًا بالصورة عند إعادة التوجيه، فإن هويتك تظل سليمة.\n\n### الدعم الفني عبر المرئيات\nاستخدم الصور لإرسال مقارنات \"قبل/بعد\" أو مخططات التدفق. باستخدام حقل `reply_to`، يمكنك ربط صورة تعليمية مباشرة باستفسار محدد للمستخدم، مما يؤدي إلى إنشاء خيط دعم سلس.\n\n---\n\n## 🛠️ المزالق الشائعة والحلول\n\n- **أنواع Mime غير صالحة**: إرسال ملف `.jpg` مع رأس `image/gif` هو خطأ تقني شائع. سيعيد Wawp خطأ `Unsupported Mimetype`. تأكد دائمًا من صحة رؤوس الخادم الخاص بك.\n- **غموض اسم الملف**: استخدم أسماء ملفات وصفية ولكن نظيفة (مثلاً `invoice_123.jpg`). تجنب استخدام رموز خاصة أو مسافات في معلمة `file[filename]` لضمان التوافق عبر أنظمة تشغيل الملفات المختلفة.\n- **مشكلة \"الصورة المصغرة المعطلة\"**: إذا ظهرت الصورة كمربع رمادي على هاتف المستلم، فهذا يعني عادةً أن عنوان URL المصدر قد انقطع في منتصف التنزيل أو أن الخادم أرجع رمز 404/500 أثناء مرحلة جلب Wawp.\n\n---\n\n## ملخص الإمكانيات:\n- تقديم صور JPEG و PNG عالية الدقة مع شروحات متكاملة.\n- الجلب عن بُعد من أي عنوان URL آمن (HTTPS).\n- دعم لتداخل الخيوط المعقدة عبر معلمة `reply_to`.\n- تحقق موثوق من نوع MIME وتطبيع الرؤوس.\n- تقارير نجاح متسقة مع توليد معرف `message_id` فريد لتتبع التسليم.\n",
          "args": {
            "instance_id": {
              "description": "المعرف الفريد لجلسة واتساب"
            },
            "access_token": {
              "description": "رمز وصول API"
            },
            "chatId": {
              "description": "معرف واتساب للمستلم (JID). يدعم الأفراد (@c.us)، المجموعات (@g.us)، والقنوات (@newsletter)."
            },
            "file[url]": {
              "description": "عنوان URL متاح للعامة عبر HTTPS للصورة"
            },
            "file[filename]": {
              "description": "اسم الملف للصورة"
            },
            "file[mimetype]": {
              "description": "نوع MIME (image/jpeg أو image/png)"
            },
            "caption": {
              "description": "الشرح التوضيحي للصورة"
            },
            "reply_to": {
              "description": "معرف الرسالة التي تقوم بالرد عليها"
            }
          },
          "tips": [
            {
              "title": "العرض المباشر",
              "content": "قم بعرض صورة مصغرة من جانب العميل قبل الإرسال لمنح المستخدمين ملاحظات فورية."
            },
            {
              "title": "التنسيقات المدعومة",
              "content": "يقبل واتساب بشكل أساسي PNG و JPEG. تأكد من أن روابطك تشير إلى ملفات صور صالحة."
            }
          ]
        }
      }
    },
    {
      "path": "/v2/send/pdf",
      "methods": [
        "POST",
        "GET"
      ],
      "title": "Send PDF",
      "category": "Send Messages",
      "description": "Treat PDFs as general file deliveries via the file endpoint. Require file.url and required caption.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Unique ID of the WhatsApp session",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API access token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Recipient's WhatsApp ID (JID). Supports Individuals (@c.us), Groups (@g.us), and Newsletters (@newsletter).",
          "example": "447441429009@c.us"
        },
        "file[url]": {
          "required": true,
          "type": "string",
          "description": "Publicly accessible HTTPS URL of the PDF file",
          "example": "https://wawp.net/samples/file-sample.pdf"
        },
        "file[filename]": {
          "required": true,
          "type": "string",
          "description": "Filename for the document",
          "example": "document.pdf"
        },
        "file[mimetype]": {
          "required": true,
          "type": "string",
          "description": "MIME type (e.g., application/pdf)",
          "example": "application/pdf"
        },
        "caption": {
          "required": true,
          "type": "string",
          "description": "Caption for the document",
          "example": "Here's your requested document."
        },
        "reply_to": {
          "required": false,
          "type": "string",
          "description": "The ID of the message you are replying to",
          "example": "false_111...AAAA"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Message Sent Successfully",
          "contentType": "application/json",
          "example": {
            "_data": {
              "id": {
                "fromMe": true,
                "remote": "000000000000@c.us",
                "id": "MSG_ID_123456",
                "_serialized": "true_000000000000@c.us_MSG_ID_123456"
              },
              "viewed": false,
              "body": "BASE64_IMAGE_DATA",
              "type": "image",
              "t": 1759108866,
              "from": {
                "server": "c.us",
                "user": "111111111111",
                "_serialized": "111111111111@c.us"
              },
              "to": {
                "server": "c.us",
                "user": "000000000000",
                "_serialized": "000000000000@c.us"
              },
              "ack": 0,
              "isNewMsg": true,
              "star": false,
              "kicNotified": false,
              "caption": "Here's your requested image.",
              "deprecatedMms3Url": "https://example.com/media-url",
              "directPath": "/media/direct/path/example",
              "mimetype": "image/jpeg",
              "filehash": "FILE_HASH_PLACEHOLDER",
              "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
              "size": 192487,
              "mediaKey": "MEDIA_KEY_PLACEHOLDER",
              "mediaKeyTimestamp": 1759108865,
              "streamable": false,
              "mediaHandle": null,
              "isFromTemplate": false,
              "pollInvalidated": false,
              "isSentCagPollCreation": false,
              "latestEditMsgKey": null,
              "latestEditSenderTimestampMs": null,
              "mentionedJidList": [],
              "groupMentions": [],
              "isEventCanceled": false,
              "eventInvalidated": false,
              "isVcardOverMmsDocument": false,
              "isForwarded": false,
              "isQuestion": false,
              "questionReplyQuotedMessage": null,
              "questionResponsesCount": 0,
              "readQuestionResponsesCount": 0,
              "labels": [],
              "hasReaction": false,
              "disappearingModeInitiator": "chat",
              "disappearingModeTrigger": "chat_settings",
              "productHeaderImageRejected": false,
              "lastPlaybackProgress": 0,
              "isDynamicReplyButtonsMsg": false,
              "isCarouselCard": false,
              "parentMsgId": null,
              "callSilenceReason": null,
              "isVideoCall": false,
              "callDuration": null,
              "callCreator": null,
              "callParticipants": null,
              "isCallLink": null,
              "callLinkToken": null,
              "isMdHistoryMsg": false,
              "stickerSentTs": 0,
              "lastUpdateFromServerTs": 0,
              "invokedBotWid": null,
              "bizBotType": null,
              "botResponseTargetId": null,
              "botPluginType": null,
              "botPluginReferenceIndex": null,
              "botPluginSearchProvider": null,
              "botPluginSearchUrl": null,
              "botPluginSearchQuery": null,
              "botPluginMaybeParent": false,
              "botReelPluginThumbnailCdnUrl": null,
              "botMessageDisclaimerText": null,
              "botMsgBodyType": null,
              "requiresDirectConnection": false,
              "bizContentPlaceholderType": null,
              "hostedBizEncStateMismatch": false,
              "senderOrRecipientAccountTypeHosted": false,
              "placeholderCreatedWhenAccountIsHosted": false,
              "galaxyFlowDisabled": false,
              "links": []
            },
            "mediaKey": "MEDIA_KEY_PLACEHOLDER",
            "id": {
              "fromMe": true,
              "remote": "000000000000@c.us",
              "id": "MSG_ID_123456",
              "_serialized": "true_000000000000@c.us_MSG_ID_123456"
            },
            "ack": 0,
            "hasMedia": true,
            "body": "Here's your requested image.",
            "type": "image",
            "timestamp": 1759108866,
            "from": "111111111111@c.us",
            "to": "000000000000@c.us",
            "deviceType": "android",
            "isForwarded": false,
            "forwardingScore": 0,
            "isStatus": false,
            "isStarred": false,
            "fromMe": true,
            "hasQuotedMsg": false,
            "hasReaction": false,
            "vCards": [],
            "mentionedIds": [],
            "groupMentions": [],
            "isGif": false,
            "links": []
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Egypt)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Egypt mobile numbers must be 11 digits (national format).",
            "details": {
              "provided": "20114520282",
              "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
              "info": {
                "country": "EG",
                "type": "MOBILE"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Saudi Arabia)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for SA.",
            "details": {
              "provided": "96655555",
              "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
              "info": {
                "country": "SA"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Unknown)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for Unknown.",
            "details": {
              "provided": "01145202826",
              "recommendation": "Ensure individual numbers are in international format (starting with country code).",
              "info": {
                "country": "Unknown"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 429,
          "description": "Too Many Requests - Rate Limit Exceeded",
          "contentType": "application/json",
          "example": {
            "code": "rate_limit_exceeded",
            "message": "Too many requests. Please slow down.",
            "details": {
              "retryAfter": 60,
              "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
              "upstream": {
                "error": "Rate limit",
                "statusCode": 429
              }
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "extraInfo": "\n# Document Integrity: Empowering the PDF Messaging Engine\n\nIn the world of business automation, PDFs are the primary vehicle for high-value data—invoices, contracts, medical reports, and technical manuals. The `/v2/send/pdf` endpoint is designed to bridge the gap between your cloud storage and your user's WhatsApp conversation, ensuring that critical documents arrive with their integrity and formatting intact. Unlike media messages which are often compressed, Wawp treats PDFs as authoritative documents, preserving their binary structure for professional use.\n\n![send pdf.png](https://api.apidog.com/api/v1/projects/1017306/resources/369241/image-preview)\n\n---\n\n## 🏗️ The Document Delivery Architecture\n\nWhen you initiate a PDF transfer, Wawp’s document engine follows a specialized protocol:\n1. **Header Inspection**: Before downloading the full file, Wawp inspects the `Content-Type` to ensure it aligns with `application/pdf`. This prevents the \"Mangled File\" error that occurs if a server accidentally serves an HTML page instead of a PDF during a transient error.\n2. **Authoritative Naming**: The `file[filename]` parameter is crucial. Wawp injects this name into the WhatsApp metadata, ensuring that when the user saves the document, it retains the professional name you’ve assigned it (e.g., `Inv_2025_001.pdf`) rather than a random UUID.\n3. **Caption Correlation**: Wawp allows you to attach a markdown-rich caption to the document. This is ideal for providing instructions (e.g., \"Please sign and return to this chat\") without sending a separate, disconnected text message.\n\n---\n\n## 🛡️ Strategic Best Practices for Corporate Document Flow\n\n### 1. The Security First Approach\nSince PDFs often contain sensitive Personal Identifiable Information (PII):\n- **Short-Lived URLs**: Host your PDFs on URLs that expire shortly after the transfer is complete. Wawp only needs access for a few seconds to fetch and hand off the file to the WhatsApp network.\n- **No-Log Policy**: Wawp adheres to a **Zero-Secrets Policy**. We do not archive your PDF contents. Once we receive the \"Sent\" acknowledgement from the WhatsApp WebSocket, the binary buffer is purged from our engine's volatile memory.\n\n### 2. File Size and Optimization Strategy\nWhile WhatsApp supports documents up to **100MB** (and sometimes up to 2GB in newer versions), user experience dictates a leaner approach.\n- **The \"Mobile Friendly\" Rule**: Most users are on mobile data. We recommend keeping PDFs under **5MB** for instant loading. If you are sending a 50MB manual, consider compressing it or sending a link via [`/v2/send/link-preview`](/v2/send/link-preview) instead.\n- **Fast Serialization**: Use linearized (web-optimized) PDFs. This allows the recipient's phone to start rendering the first page before the entire document has finished downloading.\n\n### 3. Error Handling and Verification\n- **Upstream Timeouts**: For very large PDFs, ensure your file server has a high enough bandwidth to serve the entire file to Wawp within 15–20 seconds.\n- **Webhook Monitoring**: Listen for the `message.ack` events. For a PDF, the \"Delivered\" status is your confirmation that the document is safely on the user's encrypted device.\n\n---\n\n## 🧩 Advanced Use Cases\n\n### Automated Invoicing and Billing\nIntegrate this endpoint with your billing system. As soon as a payment is processed, generate a PDF and send it via Wawp. The `reply_to` parameter can be used to link the invoice to the customer's previous \"Payment Confirmation\" message, creating a professional audit trail for the user.\n\n### Legal and Contractual Workflows\nSend contracts for digital review. Use the `caption` field to explain the terms briefly. Because Wawp supports international character sets, your captions can support legal terminology in any language while maintaining the structural integrity of the PDF attachment.\n\n---\n\n## 🛠️ Common Pitfalls and Solutions\n\n- **Invalid MIME-Type**: If your server sends `text/html` (often due to a 404 page) but you specified `application/pdf`,\n  tips: [\n        {\n            type: 'info',\n            title: 'Size',\n            content: 'WhatsApp has a file size limit (approx 100MB).'\n        },\n        {\n            type: 'positive',\n            title: 'Preview',\n            content: 'Shows the first page as a thumbnail on some devices.'\n        }\n    ],\n  recommendations: [\n        \"Compress large PDFs before sending to ensure delivery.\",\n        \"Use descriptive filenames; users see this when downloading.\"\n    ]\n  \n   Wawp will fail the request to prevent sending corrupted files to your users.\n- **Complex Filenames**: Avoid using emojis or non-ASCII characters in the `file[filename]` string. While Wawp supports them, some older Android PDF readers may fail to open files with complex filenames.\n- **The \"Attachment Only\" UI**: Remind your frontend developers that PDFs do not show a visual preview in the chat bubble (unlike images). Use a descriptive caption to tell the user what the file is before they download it.\n\n---\n\n## Summary of Capabilities:\n- Deliver professional-grade PDF documents with custom filenames and captions.\n- Support for large files (up to 100MB) with reliable fetching from HTTPS sources.\n- End-to-end markdown support for document captions and instructions.\n- Seamless integration with conversational threads via `reply_to`.\n- Consistent delivery tracking through unique `message_id` generation and Webhook support.\n",
      "image": "https://api.apidog.com/api/v1/projects/1017306/resources/369241/image-preview",
      "translations": {
        "ar": {
          "title": "إرسال ملف PDF",
          "description": "عامل ملفات PDF كعمليات تسليم ملفات عامة عبر نقطة نهاية الملف. تتطلب file.url وشرح مطلوب.",
          "tips": [
            {
              "title": "الحجم",
              "content": "لدى واتساب حد لحجم الملف (حوالي 100 ميجابايت)."
            },
            {
              "title": "معاينة",
              "content": "يعرض الصفحة الأولى كصورة مصغرة على بعض الأجهزة."
            }
          ],
          "recommendations": [
            "قم بضغط ملفات PDF الكبيرة قبل الإرسال لضمان التسليم.",
            "استخدم أسماء ملفات وصفية؛ يرى المستخدمون هذا عند التنزيل."
          ],
          "extraInfo": "\n# سلامة المستندات: تمكين محرك رسائل PDF\n\nفي عالم أتمتة الأعمال، تعد ملفات PDF الوسيلة الأساسية للبيانات عالية القيمة - الفواتير، العقود، التقارير الطبية، والأدلة التقنية. تم تصميم نقطة نهاية `/v2/send/pdf` لسد الفجوة بين التخزين السحابي الخاص بك ومحادثة واتساب الخاصة بمستخدمك، مما يضمن وصول المستندات المهمة مع الحفاظ على سلامتها وتنسيقها. على عكس رسائل الوسائط التي يتم ضغطها غالبًا، يتعامل Wawp مع ملفات PDF كمستندات موثوقة، مع الحفاظ على بنيتها الثنائية للاستخدام المهني.\n\n![إرسال PDF](https://api.apidog.com/api/v1/projects/1017306/resources/369241/image-preview)\n\n---\n\n## 🏗️ معمارية تسليم المستندات\n\nعندما تبدأ عملية نقل PDF، يتبع محرك مستندات Wawp بروتوكولاً متخصصًا:\n1. **فحص الرؤوس (Header Inspection)**: قبل تنزيل الملف كاملاً، يفحص Wawp رأس `Content-Type` للتأكد من توافقه مع `application/pdf`. هذا يمنع خطأ \"الملف المشوه\" الذي يحدث إذا قدم الخادم بالخطأ صفحة HTML بدلاً من PDF أثناء خطأ عابر.\n2. **التسمية الموثوقة**: معلمة `file[filename]` بالغة الأهمية. يقوم Wawp بحقن هذا الاسم في بيانات واتساب الوصفية، مما يضمن أنه عندما يحفظ المستخدم المستند، فإنه يحتفظ بالاسم المهني الذي عينته له (مثل `Inv_2025_001.pdf`) بدلاً من معرف فريد عشوائي.\n3. **ارتباط الشرح**: يتيح لك Wawp إرفاق شرح غني بتنسيق Markdown بالمستند. هذا مثالي لتقديم التعليمات (مثلاً \"يرجى التوقيع وإعادته لهذه الدردشة\") دون إرسال رسالة نصية منفصلة غير متصلة.\n\n---\n\n## 🛡️ أفضل الممارسات الاستراتيجية لتدفق مستندات الشركات\n\n### 1. نهج الأمان أولاً\nبما أن ملفات PDF غالبًا ما تحتوي على معلومات شخصية حساسة (PII):\n- **روابط قصيرة الأجل**: استضف ملفات PDF الخاصة بك على عناوين URL تنتهي صلاحيتها بعد وقت قصير من اكتمال النقل. يحتاج Wawp فقط إلى الوصول لبضع ثوانٍ لجلب الملف وتسليمه لشبكة واتساب.\n- **سياسة عدم التسجيل**: يلتزم Wawp بـ **سياسة عدم الاحتفاظ بالأسرار**. نحن لا نقوم بأرشفة محتويات ملفات PDF الخاصة بك. بمجرد استلامنا لتأكيد \"تم الإرسال\" من WhatsApp WebSocket للواتساب، يتم مسح المخزن المؤقت الثنائي من ذاكرة المحرك المتطايرة.\n\n### 2. استراتيجية حجم الملف والتحسين\nبينما يدعم واتساب المستندات حتى **100 ميجابايت** (وأحيانًا حتى 2 جيجابايت في الإصدارات الأحدث)، تملي تجربة المستخدم نهجاً أكثر رشاقة.\n- **قاعدة \"صديق الجوال\"**: معظم المستخدمين يستخدمون بيانات الجوال. نوصي بإبقاء ملفات PDF أقل من **5 ميجابايت** للتحميل الفوري. إذا كنت ترسل دليلاً بحجم 50 ميجابايت، ففكر في ضغطه أو إرسال رابط عبر [`/v2/send/link-preview`](/v2/send/link-preview) بدلاً من ذلك.\n- **التسلسل السريع**: استخدم ملفات PDF الخطية (المحسنة للويب). يتيح ذلك لهاتف المستلم البدء في عرض الصفحة الأولى قبل انتهاء تنزيل المستند بالكامل.\n\n### 3. معالجة الأخطاء والتحقق\n- **مهلات المصدر**: بالنسبة لملفات PDF الكبيرة جداً، تأكد من أن خادم الملفات لديه نطاق ترددي كافٍ لخدمة الملف بالكامل لـ Wawp في غضون 15-20 ثانية.\n- **مراقبة Webhook**: استمع لأحداث `message.ack`. بالنسبة لملف PDF، تعد حالة \"تم التسليم\" تأكيدك على أن المستند بأمان على جهاز المستخدم المشفر.\n\n---\n\n## 🧩 حالات استخدام متقدمة\n\n### الفوترة والتحصيل المؤتمت\nقم بدمج هذه النقطة مع نظام الفوترة الخاص بك. بمجرد معالجة الدفعة، قم بتوليد ملف PDF وأرسله عبر Wawp. يمكن استخدام معلمة `reply_to` لربط الفاتورة برسالة \"تأكيد الدفع\" السابقة للعميل، مما يخلق مسار تدقيق مهني للمستخدم.\n\n### سير العمل القانوني والتعاقدي\nأرسل العقود للمراجعة الرقمية. استخدم حقل `caption` لشرح الشروط باختصار. نظرًا لأن Wawp يدعم مجموعات الأحرف الدولية، يمكن أن تدعم شروحاتك المصطلحات القانونية بأي لغة مع الحفاظ على السلامة الهيكلية لمرفق PDF.\n\n---\n\n## 🛠️ المزالق الشائعة والحلول\n\n- **نوع MIME غير صالح**: إذا أرسل خادمك `text/html` (غالبًا بسبب صفحة 404) ولكنك حددت `application/pdf`، فسينهي Wawp الطلب لمنع إرسال ملفات تالفة لمستخدميك.\n- **أسماء ملفات معقدة**: تجنب استخدام رموز تعبيرية أو أحرف غير ASCII في سلسلة `file[filename]`. بينما يدعمها Wawp، قد تفشل بعض قارئات PDF القديمة على Android في فتح ملفات بأسماء معقدة.\n- **واجهة \"المرفق فقط\"**: ذكر مطوري الواجهة الأمامية لديك بأن ملفات PDF لا تظهر معاينة مرئية في فقاعة الدردشة (على عكس الصور). استخدم شرحًا وصفيًا لإخبار المستخدم بماهية الملف قبل تنزيله.\n\n---\n\n## ملخص الإمكانيات:\n- تقديم مستندات PDF احترافية مع أسماء ملفات وشروحات مخصصة.\n- دعم للملفات الكبيرة (حتى 100 ميجابايت) مع جلب موثوق من مصادر HTTPS.\n- دعم كامل لـ Markdown في شروحات وتوجيهات المستندات.\n- تكامل سلس مع خيوط المحادثة عبر `reply_to`.\n- تتبع تسليم متسق من خلال توليد معرف `message_id` فريد ودعم Webhook.\n",
          "args": {
            "instance_id": {
              "description": "المعرف الفريد لجلسة واتساب"
            },
            "access_token": {
              "description": "رمز وصول API"
            },
            "chatId": {
              "description": "معرف واتساب للمستلم (JID). يدعم الأفراد (@c.us)، المجموعات (@g.us)، والقنوات (@newsletter)."
            },
            "file[url]": {
              "description": "عنوان URL متاح للعامة عبر HTTPS لملف PDF"
            },
            "file[filename]": {
              "description": "اسم الملف للمستند"
            },
            "file[mimetype]": {
              "description": "نوع MIME (مثلاً application/pdf)"
            },
            "caption": {
              "description": "الشرح التوضيحي للمستند"
            },
            "reply_to": {
              "description": "معرف الرسالة التي تقوم بالرد عليها"
            }
          }
        }
      }
    },
    {
      "path": "/v2/send/list",
      "methods": [
        "POST",
        "GET"
      ],
      "title": "Send List Message",
      "category": "Send Messages",
      "description": "Sends an interactive List Message (menu) to a chat. This message type displays a button that, when tapped, opens a list of options.",
      "modifiedAt": "Just now",
      "bodyEditor": true,
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Unique ID of the WhatsApp session",
          "example": "YOUR_INSTANCE_ID",
          "in": "body"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API access token",
          "example": "YOUR_ACCESS_TOKEN",
          "in": "body"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Recipient's WhatsApp number",
          "example": "447441429009",
          "in": "body"
        },
        "message": {
          "required": true,
          "type": "object",
          "description": "The interactive list message structure.",
          "example": "{\n  \"title\": \"Simple Menu\",\n  \"description\": \"Please choose an option\",\n  \"footer\": \"Thank you!\",\n  \"button\": \"Open Menu\",\n  \"sections\": [\n    {\n      \"title\": \"Main Options\",\n      \"rows\": [\n        {\n          \"title\": \"Option 1\",\n          \"rowId\": \"opt1\",\n          \"description\": \"Description for 1\"\n        },\n        {\n          \"title\": \"Option 2\",\n          \"rowId\": \"opt2\"\n        }\n      ]\n    }\n  ]\n}",
          "in": "body"
        },
        "message.title": {
          "required": true,
          "type": "string",
          "description": "Header title of the list message.",
          "example": "Simple Menu",
          "in": "body"
        },
        "message.description": {
          "required": true,
          "type": "string",
          "description": "Body text of the message.",
          "example": "Please select an option below",
          "in": "body"
        },
        "message.footer": {
          "required": true,
          "type": "string",
          "description": "Small text at the bottom.",
          "example": "Powered by Wawp",
          "in": "body"
        },
        "message.button": {
          "required": true,
          "type": "string",
          "description": "Text on the button that opens the list.",
          "example": "Open Menu",
          "in": "body"
        },
        "message.sections": {
          "required": true,
          "type": "array",
          "description": "Array of sections, each containing a title and rows.",
          "example": "[{ title: 'Section 1', rows: [...] }]",
          "in": "body"
        },
        "reply_to": {
          "required": false,
          "type": "string",
          "description": "The ID of the message you are replying to",
          "example": "false_111...AAAA",
          "in": "body"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Message Sent Successfully",
          "contentType": "application/json",
          "example": {
            "_data": {
              "id": {
                "fromMe": true,
                "remote": "000000000000@c.us",
                "id": "MSG_ID_123456",
                "_serialized": "true_000000000000@c.us_MSG_ID_123456"
              },
              "viewed": false,
              "body": "BASE64_IMAGE_DATA",
              "type": "image",
              "t": 1759108866,
              "from": {
                "server": "c.us",
                "user": "111111111111",
                "_serialized": "111111111111@c.us"
              },
              "to": {
                "server": "c.us",
                "user": "000000000000",
                "_serialized": "000000000000@c.us"
              },
              "ack": 0,
              "isNewMsg": true,
              "star": false,
              "kicNotified": false,
              "caption": "Here's your requested image.",
              "deprecatedMms3Url": "https://example.com/media-url",
              "directPath": "/media/direct/path/example",
              "mimetype": "image/jpeg",
              "filehash": "FILE_HASH_PLACEHOLDER",
              "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
              "size": 192487,
              "mediaKey": "MEDIA_KEY_PLACEHOLDER",
              "mediaKeyTimestamp": 1759108865,
              "streamable": false,
              "mediaHandle": null,
              "isFromTemplate": false,
              "pollInvalidated": false,
              "isSentCagPollCreation": false,
              "latestEditMsgKey": null,
              "latestEditSenderTimestampMs": null,
              "mentionedJidList": [],
              "groupMentions": [],
              "isEventCanceled": false,
              "eventInvalidated": false,
              "isVcardOverMmsDocument": false,
              "isForwarded": false,
              "isQuestion": false,
              "questionReplyQuotedMessage": null,
              "questionResponsesCount": 0,
              "readQuestionResponsesCount": 0,
              "labels": [],
              "hasReaction": false,
              "disappearingModeInitiator": "chat",
              "disappearingModeTrigger": "chat_settings",
              "productHeaderImageRejected": false,
              "lastPlaybackProgress": 0,
              "isDynamicReplyButtonsMsg": false,
              "isCarouselCard": false,
              "parentMsgId": null,
              "callSilenceReason": null,
              "isVideoCall": false,
              "callDuration": null,
              "callCreator": null,
              "callParticipants": null,
              "isCallLink": null,
              "callLinkToken": null,
              "isMdHistoryMsg": false,
              "stickerSentTs": 0,
              "lastUpdateFromServerTs": 0,
              "invokedBotWid": null,
              "bizBotType": null,
              "botResponseTargetId": null,
              "botPluginType": null,
              "botPluginReferenceIndex": null,
              "botPluginSearchProvider": null,
              "botPluginSearchUrl": null,
              "botPluginSearchQuery": null,
              "botPluginMaybeParent": false,
              "botReelPluginThumbnailCdnUrl": null,
              "botMessageDisclaimerText": null,
              "botMsgBodyType": null,
              "requiresDirectConnection": false,
              "bizContentPlaceholderType": null,
              "hostedBizEncStateMismatch": false,
              "senderOrRecipientAccountTypeHosted": false,
              "placeholderCreatedWhenAccountIsHosted": false,
              "galaxyFlowDisabled": false,
              "links": []
            },
            "mediaKey": "MEDIA_KEY_PLACEHOLDER",
            "id": {
              "fromMe": true,
              "remote": "000000000000@c.us",
              "id": "MSG_ID_123456",
              "_serialized": "true_000000000000@c.us_MSG_ID_123456"
            },
            "ack": 0,
            "hasMedia": true,
            "body": "Here's your requested image.",
            "type": "image",
            "timestamp": 1759108866,
            "from": "111111111111@c.us",
            "to": "000000000000@c.us",
            "deviceType": "android",
            "isForwarded": false,
            "forwardingScore": 0,
            "isStatus": false,
            "isStarred": false,
            "fromMe": true,
            "hasQuotedMsg": false,
            "hasReaction": false,
            "vCards": [],
            "mentionedIds": [],
            "groupMentions": [],
            "isGif": false,
            "links": []
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Egypt)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Egypt mobile numbers must be 11 digits (national format).",
            "details": {
              "provided": "20114520282",
              "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
              "info": {
                "country": "EG",
                "type": "MOBILE"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Saudi Arabia)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for SA.",
            "details": {
              "provided": "96655555",
              "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
              "info": {
                "country": "SA"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Unknown)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for Unknown.",
            "details": {
              "provided": "01145202826",
              "recommendation": "Ensure individual numbers are in international format (starting with country code).",
              "info": {
                "country": "Unknown"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 429,
          "description": "Too Many Requests - Rate Limit Exceeded",
          "contentType": "application/json",
          "example": {
            "code": "rate_limit_exceeded",
            "message": "Too many requests. Please slow down.",
            "details": {
              "retryAfter": 60,
              "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
              "upstream": {
                "error": "Rate limit",
                "statusCode": 429
              }
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "extraInfo": "\n# Conversational Navigation: Mastering the Interactive List Engine\n\nIn the evolution of commercial messaging, the `/v2/send/list` endpoint represents a shift from \"Command-Line\" style interactions to a modern, \"App-like\" user experience. List messages provide a structured, high-conversion way for users to select from a menu of options without the friction of typing words or numbers. By organizing choices into sections and rows, you can build complex navigation menus, product directories, or support triage flows that feel native to the WhatsApp ecosystem.\n\n![List.png](https://api.apidog.com/api/v1/projects/1017306/resources/369238/image-preview)\n\n![list options.png](https://api.apidog.com/api/v1/projects/1017306/resources/369239/image-preview)\n\n---\n\n## 🏗️ The List Message Hierarchy\n\nA List message is a multi-layered object designed for clarity and scannability:\n1. **The Header (Title)**: This is the first thing the user sees. It should clearly state the purpose of the menu (e.g., \"Customer Support Menu\").\n2. **The Body (Description)**: Use this for the primary instruction or context (e.g., \"Please select the department you wish to speak with\").\n3. **The Activation Button**: A custom label (max 20 characters) that triggers the overlay.\n4. **Sections and Rows**: The core content. Sections allow you to group related options (e.g., \"Technical Support\" vs. \"Billing Queries\"), while rows represent the individual clickable items.\n\n---\n\n## 🛡️ Strategic Best Practices for Menu Design\n\n### 1. The 10-Row Boundary\nWhatsApp enforces a hard limit of **10 rows** across all sections in a single list.\n- **Developer Action**: If you have 20 products to show, do not try to squeeze them into one list. Instead, use a \"Category\" list first, and then have the user's selection trigger a *second* list message for that specific category. This \"Multi-Step Triage\" prevents the user from being overwhelmed by a single, monolithic menu.\n- **Row Descriptions**: Each row has an optional `description` field. Use this to provide \"Hint Text\" (e.g., \"Fastest response time\") to guide the user's decision process.\n\n### 2. Unique Identifier (rowId) Strategy\nThe `rowId` is for your backend, while the `title` is for the user.\n- **Decoupling**: Never rely on the row title for your logic. Always use a unique, alphanumeric `rowId` (e.g., `dept_billing_v1`). This allows you to change the display text for marketing purposes without breaking your backend processing logic.\n- **State Persistence**: You can include small bits of state metadata in the `rowId` (e.g., `user_123_opt_4`) if your system is completely stateless, though we recommend maintaining user state in your own database associated with the `chatId`.\n\n### 3. Visual Scannability and Emojis\n- **Section Headers**: Use section titles as \"Visual Anchors.\" \n- **Emoji Bullet Points**: Prefix your row titles with emojis (e.g., \"💳 Billing,\" \"🛠️ Technical\"). This significantly reduces the cognitive load on the user, allowing them to find their desired option via icons rather than reading every word.\n\n---\n\n## 🧩 Advanced Use Cases\n\n### Automated Product Catalogs\nBuild a mini-storefront within the chat. The first section can be \"New Arrivals,\" and the second \"Best Sellers.\" When a user clicks a row, your **Webhooks** (`list_response`) will capture the `rowId`. Your system can then immediately send an [`/v2/send/image`](/v2/send/image) of that product with a \"Buy Now\" link.\n\n### Intelligent Support Triage\nInstead of a human greeting every user, send a List message. Section 1: \"Urgent Issues,\" Section 2: \"General Info.\" Based on the user's selection, the bot can route the conversation to the most qualified agent or provide an automated knowledge-base article.\n\n---\n\n## 🛠️ Common Pitfalls and Solutions\n\n- **Button Text Length**: If your button text exceeds 20 characters, the message will fail to send with a `Validation Error`. Keep it punchy: \"See Options,\" \"Start Here,\" or \"Main Menu.\"\n- **Empty Sections**: Every section must contain at least one row. Sending an empty section will cause a rendering failure on the WhatsApp network.\n- **The \"No Response\" Trap**: Users sometimes open a list but don't select anything. Ensure your bot has a \"Timeout\" or follow-up logic to re-engage the user if they've been inactive for more than 5 minutes after receiving a menu.\n\n---\n\n## Summary of Capabilities:\n- Deliver interactive, overlay-style list menus with up to 10 rows.\n- Support for multiple logically grouped sections with custom titles.\n- High-conversion UX using custom buttons and descriptive row metadata.\n- Real-time interaction tracking via specialized `list_response` Webhook events.\n- Full markdown support for header titles and body descriptions.\n",
      "image": "https://api.apidog.com/api/v1/projects/1017306/resources/369238/image-preview",
      "tips": [
        {
          "type": "positive",
          "title": "Better Conversions",
          "content": "List messages have a significantly higher engagement rate than plain text menus because they reduce typing effort for the user."
        },
        {
          "type": "warning",
          "title": "Unique rowId",
          "content": "Always ensure your `rowId` is unique within the list to correctly identify the user's choice in your backend logic."
        }
      ],
      "recommendations": [
        "Use \"reply_to\" to maintain conversation context.",
        "Handle distinct message types (text, image, video) appropriately.",
        "Implement a robust retry mechanism for failed sends."
      ],
      "translations": {
        "ar": {
          "title": "إرسال رسالة قائمة (Menu)",
          "description": "إرسال رسالة قائمة تفاعلية (قائمة خيارات) إلى الدردشة. يعرض هذا النوع من الرسائل زراً يفتح قائمة خيارات عند النقر عليه.",
          "recommendations": [
            "أضف تأخيرات عشوائية بين الرسائل لمحاكاة السلوك البشري.",
            "تحقق من أرقام الهواتف قبل الإرسال لضمان التسليم."
          ],
          "extraInfo": "\n# التنقل الحواري: إتقان محرك القوائم التفاعلية\n\nفي تطور المراسلات التجارية، تمثل نقطة نهاية `/v2/send/list` تحولاً من التفاعلات التقليدية إلى تجربة مستخدم حديثة تشبه \"التطبيقات\". توفر رسائل القوائم طريقة منظمة وعالية التحويل للمستخدمين لاختيار خيارات من قائمة دون عناء كتابة الكلمات أو الأرقام. من خلال تنظيم الخيارات في أقسام وصفوف، يمكنك بناء قوائم تنقل معقدة، أو أدلة منتجات، أو تدفقات فرز الدعم التي تبدو أصلية في نظام واتساب البيئي.\n\n![قائمة](https://api.apidog.com/api/v1/projects/1017306/resources/369238/image-preview)\n\n![خيارات قائمة](https://api.apidog.com/api/v1/projects/1017306/resources/369239/image-preview)\n\n---\n\n## 🏗️ الهيكل الهرمي لرسالة القائمة\n\nرسالة القائمة هي كائن متعدد الطبقات مصمم للوضوح وسهولة المسح البصري:\n1. **العنوان الرئيسي (Title)**: وهو أول ما يراه المستخدم. يجب أن يوضح بوضوح هدف القائمة (مثلاً \"قائمة دعم العملاء\").\n2. **الوصف (Description)**: استخدم هذا للتعليمات الأساسية أو السياق (مثلاً \"يرجى اختيار القسم الذي ترغب في التحدث إليه\").\n3. **زر التنشيط (Activation Button)**: تسمية مخصصة (بحد أقصى 20 حرفاً) تفتح القائمة المنبثقة.\n4. **الأقسام والصفوف**: المحتوى الأساسي. تسمح لك الأقسام بتجميع الخيارات ذات الصلة (مثلاً \"الدعم الفني\" مقابل \"استفسارات الفواتير\")، بينما تمثل الصفوف العناصر الفردية القابلة للنقر.\n\n---\n\n## 🛡️ أفضل الممارسات الاستراتيجية لتصميم القوائم\n\n### 1. حد الـ 10 صفوف\nيفرض واتساب حداً صارماً بـ **10 صفوف** كإجمالي لجميع الأقسام في رسالة قائمة واحدة.\n- **إجراء المطور**: إذا كان لديك 20 منتجاً لعرضها، فلا تحاول حشرها في قائمة واحدة. بدلاً من ذلك، استخدم قائمة \"فئات\" أولاً، ثم اجعل اختيار المستخدم يطلق رسالة قائمة *ثانية* لتلك الفئة المحددة. هذا النوع من \"الفرز متعدد الخطوات\" يمنع إرهاق المستخدم بقائمة واحدة ضخمة.\n- **وصف الصفوف**: يحتوي كل صف على حقل `description` اختياري. استخدمه لتقديم \"نص تلميحي\" (مثلاً \"أسرع وقت استجابة\") لتوجيه عملية اتخاذ القرار لدى المستخدم.\n\n### 2. استراتيجية المعرف الفريد (rowId)\nمعرف `rowId` مخصص لنظامك الخلفي، بينما `title` للمستخدم.\n- **الفصل**: لا تعتمد أبداً على عنوان الصف في منطقك البرمجي. استخدم دائماً `rowId` فريداً وأبجدياً رقمياً (مثلاً `dept_billing_v1`). يتيح لك ذلك تغيير نص العرض لأغراض تسويقية دون كسر منطق المعالجة في نظامك الخلفي.\n- **استمرارية الحالة**: يمكنك تضمين قطع صغيرة من بيانات الحالة في `rowId` (مثلاً `user_123_opt_4`) إذا كان نظامك عديم الحالة تماماً، رغم أننا نوصي بالحفاظ على حالة المستخدم في قاعدة بياناتك الخاصة المرتبطة بـ `chatId`.\n\n### 3. المسح البصري والرموز التعبيرية\n- **عناوين الأقسام**: استخدم عناوين الأقسام كـ \"مراسي بصرية\".\n- **نقاط الرموز التعبيرية**: ابدأ عناوين صفوفك برموز تعبيرية (مثلاً \"💳 الفواتير\"، \"🛠️ دعم فني\"). يقلل هذا بشكل كبير من الجهد المعرفي للمستخدم، مما يسمح له بالعثور على خياره المطلوب عبر الأيقونات بدلاً من قراءة كل كلمة.\n\n---\n\n## 🧩 حالات استخدام متقدمة\n\n### أدلة المنتجات المؤتمتة\nقم ببناء واجهة متجر مصغرة داخل الدردشة. يمكن أن يكون القسم الأول \"وصل حديثاً\"، والثاني \"الأكثر مبيعاً\". عندما ينقر المستخدم على صف، سيقوم **Webhooks** (`list_response`) بالتقاط `rowId`. يمكن لنظامك حينها إرسال صورة [`/v2/send/image`](/v2/send/image) لذلك المنتج فوراً مع رابط \"اشترِ الآن\".\n\n### فرز الدعم الذكي\nبدلاً من أن يقوم إنسان بتحية كل مستخدم، أرسل رسالة قائمة. القسم 1: \"مشاكل عاجلة\"، القسم 2: \"معلومات عامة\". بناءً على اختيار المستخدم، يمكن للبوت توجيه المحادثة إلى الوكيل الأكثر تأهيلاً أو توفير مقال من قاعدة المعرفة تلقائياً.\n\n---\n\n## 🛠️ المزالق الشائعة والحلول\n\n- **طول نص الزر**: إذا تجاوز نص الزر 20 حرفاً، ستفشل الرسالة في الإرسال بخطأ `Validation Error`. اجعل النص مقتضباً: \"الخيارات\"، \"ابدأ هنا\"، أو \"القائمة\".\n- **الأقسام الفارغة**: يجب أن يحتوي كل قسم على صف واحد على الأقل. إرسال قسم فارغ سيؤدي إلى فشل العرض على شبكة واتساب.\n- **فخ \"عدم الاستجابة\"**: يفتح المستخدمون أحياناً القائمة ولكن لا يختارون شيئاً. تأكد من أن البوت لديه منطق \"مهلة\" (Timeout) أو متابعة لإعادة إشراك المستخدم إذا ظل غير نشط لأكثر من 5 دقائق بعد استلام القائمة.\n\n---\n\n## ملخص الإمكانيات:\n- تقديم قوائم تفاعلية منبثقة مع ما يصل إلى 10 صفوف.\n- دعم لأقسام متعددة مجمعة منطقياً مع عناوين مخصصة.\n- تجربة مستخدم عالية التحويل باستخدام أزرار مخصصة وبيانات وصفية للصفوف.\n- تتبع التفاعل في الوقت الفعلي عبر أحداث `list_response` في Webhook.\n- دعم كامل لـ Markdown لعناوين الأقسام وأوصاف المتن.\n",
          "args": {
            "instance_id": {
              "description": "المعرف الفريد لجلسة واتساب"
            },
            "access_token": {
              "description": "رمز وصول API"
            },
            "chatId": {
              "description": "رقم واتساب للمستلم"
            },
            "message": {
              "description": "هيكل رسالة القائمة التفاعلية."
            },
            "message.title": {
              "description": "عنوان رأس رسالة القائمة."
            },
            "message.description": {
              "description": "نص متن الرسالة."
            },
            "message.footer": {
              "description": "نص صغير في الأسفل."
            },
            "message.button": {
              "description": "النص الموجود على الزر الذي يفتح القائمة."
            },
            "message.sections": {
              "description": "مصفوفة من الأقسام، يحتوي كل منها على عنوان وصفوف."
            },
            "reply_to": {
              "description": "معرف الرسالة التي تقوم بالرد عليها"
            }
          },
          "tips": [
            {
              "title": "تحويلات أفضل",
              "content": "تتمتع رسائل القوائم بمعدل تفاعل أعلى بكثير من القوائم النصية العادية لأنها تقلل من جهد الكتابة للمستخدم."
            },
            {
              "title": "معرف صف فريد",
              "content": "تأكد دائماً من أن `rowId` فريد داخل القائمة لتحديد اختيار المستخدم بشكل صحيح في منطق نظامك الخلفي."
            }
          ]
        }
      }
    },
    {
      "path": "/v2/send/event",
      "methods": [
        "POST"
      ],
      "title": "Send Event",
      "category": "Send Messages",
      "description": "Sends a calendar event message to a chat. Users can tap on the event to view details, add it to their calendar, or join a call.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Unique ID of the WhatsApp session",
          "example": "YOUR_INSTANCE_ID"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API access token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Recipient's WhatsApp number",
          "example": "447441429009"
        },
        "event.name": {
          "required": true,
          "type": "string",
          "description": "Name of the event (e.g. Team Meeting 📅)",
          "example": "Team Meeting 📅"
        },
        "event.description": {
          "required": true,
          "type": "string",
          "description": "Discussing Q1 Roadmap",
          "example": "Discussing Q1 Roadmap"
        },
        "event.startTime": {
          "required": true,
          "type": "number",
          "description": "Start time (Unix timestamp in seconds)",
          "example": "1735920000"
        },
        "event.endTime": {
          "required": true,
          "type": "number",
          "description": "End time (Unix timestamp in seconds)",
          "example": "1735923600"
        },
        "event.location.name": {
          "required": true,
          "type": "string",
          "description": "Meeting Room A",
          "example": "Meeting Room A"
        },
        "event.extraGuestsAllowed": {
          "required": true,
          "type": "boolean",
          "description": "Whether extra guests are allowed",
          "example": "true"
        },
        "reply_to": {
          "required": false,
          "type": "string",
          "description": "The ID of the message you are replying to",
          "example": "false_111...AAAA"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Message Sent Successfully",
          "contentType": "application/json",
          "example": {
            "_data": {
              "id": {
                "fromMe": true,
                "remote": "000000000000@c.us",
                "id": "MSG_ID_123456",
                "_serialized": "true_000000000000@c.us_MSG_ID_123456"
              },
              "viewed": false,
              "body": "BASE64_IMAGE_DATA",
              "type": "image",
              "t": 1759108866,
              "from": {
                "server": "c.us",
                "user": "111111111111",
                "_serialized": "111111111111@c.us"
              },
              "to": {
                "server": "c.us",
                "user": "000000000000",
                "_serialized": "000000000000@c.us"
              },
              "ack": 0,
              "isNewMsg": true,
              "star": false,
              "kicNotified": false,
              "caption": "Here's your requested image.",
              "deprecatedMms3Url": "https://example.com/media-url",
              "directPath": "/media/direct/path/example",
              "mimetype": "image/jpeg",
              "filehash": "FILE_HASH_PLACEHOLDER",
              "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
              "size": 192487,
              "mediaKey": "MEDIA_KEY_PLACEHOLDER",
              "mediaKeyTimestamp": 1759108865,
              "streamable": false,
              "mediaHandle": null,
              "isFromTemplate": false,
              "pollInvalidated": false,
              "isSentCagPollCreation": false,
              "latestEditMsgKey": null,
              "latestEditSenderTimestampMs": null,
              "mentionedJidList": [],
              "groupMentions": [],
              "isEventCanceled": false,
              "eventInvalidated": false,
              "isVcardOverMmsDocument": false,
              "isForwarded": false,
              "isQuestion": false,
              "questionReplyQuotedMessage": null,
              "questionResponsesCount": 0,
              "readQuestionResponsesCount": 0,
              "labels": [],
              "hasReaction": false,
              "disappearingModeInitiator": "chat",
              "disappearingModeTrigger": "chat_settings",
              "productHeaderImageRejected": false,
              "lastPlaybackProgress": 0,
              "isDynamicReplyButtonsMsg": false,
              "isCarouselCard": false,
              "parentMsgId": null,
              "callSilenceReason": null,
              "isVideoCall": false,
              "callDuration": null,
              "callCreator": null,
              "callParticipants": null,
              "isCallLink": null,
              "callLinkToken": null,
              "isMdHistoryMsg": false,
              "stickerSentTs": 0,
              "lastUpdateFromServerTs": 0,
              "invokedBotWid": null,
              "bizBotType": null,
              "botResponseTargetId": null,
              "botPluginType": null,
              "botPluginReferenceIndex": null,
              "botPluginSearchProvider": null,
              "botPluginSearchUrl": null,
              "botPluginSearchQuery": null,
              "botPluginMaybeParent": false,
              "botReelPluginThumbnailCdnUrl": null,
              "botMessageDisclaimerText": null,
              "botMsgBodyType": null,
              "requiresDirectConnection": false,
              "bizContentPlaceholderType": null,
              "hostedBizEncStateMismatch": false,
              "senderOrRecipientAccountTypeHosted": false,
              "placeholderCreatedWhenAccountIsHosted": false,
              "galaxyFlowDisabled": false,
              "links": []
            },
            "mediaKey": "MEDIA_KEY_PLACEHOLDER",
            "id": {
              "fromMe": true,
              "remote": "000000000000@c.us",
              "id": "MSG_ID_123456",
              "_serialized": "true_000000000000@c.us_MSG_ID_123456"
            },
            "ack": 0,
            "hasMedia": true,
            "body": "Here's your requested image.",
            "type": "image",
            "timestamp": 1759108866,
            "from": "111111111111@c.us",
            "to": "000000000000@c.us",
            "deviceType": "android",
            "isForwarded": false,
            "forwardingScore": 0,
            "isStatus": false,
            "isStarred": false,
            "fromMe": true,
            "hasQuotedMsg": false,
            "hasReaction": false,
            "vCards": [],
            "mentionedIds": [],
            "groupMentions": [],
            "isGif": false,
            "links": []
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Egypt)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Egypt mobile numbers must be 11 digits (national format).",
            "details": {
              "provided": "20114520282",
              "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
              "info": {
                "country": "EG",
                "type": "MOBILE"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Saudi Arabia)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for SA.",
            "details": {
              "provided": "96655555",
              "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
              "info": {
                "country": "SA"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Unknown)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for Unknown.",
            "details": {
              "provided": "01145202826",
              "recommendation": "Ensure individual numbers are in international format (starting with country code).",
              "info": {
                "country": "Unknown"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 429,
          "description": "Too Many Requests - Rate Limit Exceeded",
          "contentType": "application/json",
          "example": {
            "code": "rate_limit_exceeded",
            "message": "Too many requests. Please slow down.",
            "details": {
              "retryAfter": 60,
              "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
              "upstream": {
                "error": "Rate limit",
                "statusCode": 429
              }
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "extraInfo": "\n# Orchestrating Time: Mastering the WhatsApp Event Engine\n\nThe `/v2/send/event` endpoint introduces a sophisticated way to manage time and attendance directly within a chat. Instead of sending a plain text reminder that a user might forget, \"Event Messages\" create a professional, structured calendar object. These objects allow users to view duration, location, and description in a dedicated UI and, most importantly, add the event to their local mobile calendar (Google Calendar, iCal, etc.) with a single tap.\n\n![Send Event.png](https://api.apidog.com/api/v1/projects/1017306/resources/369240/image-preview)\n\n---\n\n## 🏗️ The Event Lifecycle Architecture\n\nAn Event message is more than a notification; it's a persistent state-object within the chat:\n1. **Timestamp Precision**: The engine uses Unix timestamps (in seconds) to define the `startTime` and `endTime`. Wawp validates that the end time occurs after the start time and handles the translation of these timestamps into the recipient's local phone time zone automatically.\n2. **Metadata Aggregation**: The `event.name`, `event.description`, and `event.location.name` are aggregated into a native WhatsApp Event packet. This packet is interactive—users can click it to expand a \"Full Details\" view that remains accessible even after the chat has moved on.\n3. **Guest Management**: The `extraGuestsAllowed` flag is a structural signal. If true, it signals to the user that the event is open for broader participation, often used in webinars or community gatherings.\n\n---\n\n## 🛡️ Strategic Best Practices for Event Engagement\n\n### 1. The \"Call-to-Action\" Description\nThe `event.description` is your most valuable text field.\n- **Deep Linking**: If the event is a virtual meeting (Zoom, Google Meet, WhatsApp Call), include the join link directly in the description. Most mobile OSs will recognize the URL and make it clickable within the event details view.\n- **Engagement**: Use the description to provide a high-level agenda. Since the event persists at the top of the chat or in the \"Media/Links/Docs\" section, it acts as a permanent reference point for the user.\n\n### 2. Timezone Integrity\nOne of the biggest causes of missed appointments is timezone confusion.\n- **The Global Standard**: Wawp expects Unix timestamps in **UTC**. Never send timestamps in a local format without first normalizing them to the UTC epoch. \n- **User Experience**: Because Wawp hands the UTC timestamp to the WhatsApp network, the recipient's phone will automatically display the time in *their* local time (e.g., if you send an event for 3 PM UTC, a user in London sees 3 PM, while a user in New York sees 10 AM).\n\n### 3. Location Clarity (Physical vs. Virtual)\n- **Physical Events**: Use the `event.location.name` for the room number or building name. \n- **Virtual Events**: Set the location name to \"💻 Virtual Meeting\" or \"🎥 Live Stream.\" This provides instant visual context before the user even opens the details.\n\n---\n\n## 🧩 Advanced Use Cases\n\n### Automated Webinar Onboarding\nWhen a user signs up for a webinar via a bot, trigger a `/v2/send/event` immediately. This allows the user to click \"Add to Calendar\" while their intent is high. Combine this with the `reply_to` parameter to link the event card to their \"Successful Registration\" text message.\n\n### Service Appointment Booking\nFor hair salons, doctors, or repair services, send an event card as soon as the appointment is confirmed. The professional look of an Event card significantly increases the \"Perceived Quality\" of the service and reduces the rate of \"No-Shows\" by integrating with the user's primary planning tool (their calendar).\n\n---\n\n## 🛠️ Common Pitfalls and Solutions\n\n- **Seconds vs. Milliseconds**: A common technical error is sending JS `Date.now()` (which is milliseconds) instead of the required Unix seconds. This will result in an event scheduled thousands of years in the future. Always divide by 1000.\n- **Short Durations**: While WhatsApp allows very short events, we recommend a minimum duration of **15 minutes** to ensure the calendar block is visually significant enough for the user to notice.\n- **The \"Overlapping\" Conflict**: WhatsApp doesn't prevent you from sending overlapping events, but your system should. If a session is already busy, consider using a poll first to find an available slot before sending the final Event card.\n\n---\n\n## Summary of Capabilities:\n- Deliver interactive, native-style WhatsApp Event cards with one-tap calendar integration.\n- Full support for Unix-timestamp based scheduling with automatic timezone normalization.\n- High-fidelity metadata support for event names, descriptions, and custom locations.\n- Structural signaling for guest permissions via the `extraGuestsAllowed` flag.\n- Seamless integration with conversational threads via the `reply_to` parameter.\n- Persistent UI presence within the chat, acting as a permanent reference for scheduled activities.\n",
      "image": "https://api.apidog.com/api/v1/projects/1017306/resources/369240/image-preview",
      "tips": [
        {
          "type": "info",
          "title": "Unix Timestamps",
          "content": "Double-check your timestamp logic. Ensure you are sending seconds (e.g. 1735920000) not milliseconds."
        }
      ],
      "recommendations": [
        "Use \"reply_to\" to maintain conversation context.",
        "Handle distinct message types (text, image, video) appropriately.",
        "Implement a robust retry mechanism for failed sends."
      ],
      "translations": {
        "ar": {
          "title": "إرسال حدث (Event)",
          "description": "يرسل رسالة حدث (تقويم) إلى الدردشة. يمكن للمستخدمين النقر فوق الحدث لعرض التفاصيل، أو إضافته إلى تقويمهم، أو الانضمام إلى مكالمة.",
          "extraInfo": "\n# إدارة الوقت: إتقان محرك أحداث واتساب\n\nتقدم نقطة النهاية `/v2/send/event` طريقة متطورة لإدارة الوقت والحضور مباشرة داخل الدردشة. بدلاً من إرسال تذكير نصي عادي قد ينساه المستخدم، تفتح \"رسائل الأحداث\" كائناً تقويمياً منظماً ومحترفاً. تتيح هذه الكائنات للمستخدمين عرض المدة والموقع والوصف في واجهة مخصصة، والأهم من ذلك، إضافة الحدث إلى تقويم هاتفهم المحلي (مثل تقويم Google أو iCal) بنقرة واحدة.\n\n![إرسال حدث](https://api.apidog.com/api/v1/projects/1017306/resources/369240/image-preview)\n\n---\n\n## 🏗️ دورة حياة الحدث وهيكله\n\nرسالة الحدث هي أكثر من مجرد إشعار؛ إنها كائن حالة مستمر داخل الدردشة:\n1. **دقة الطوابع الزمنية**: يستخدم المحرك طوابع Unix الزمنية (بالثواني) لتعريف `startTime` و `endTime`. يتحقق Wawp من أن وقت الانتهاء يأتي بعد وقت البدء، ويتولى تحويل هذه الطوابع الزمنية إلى المنطقة الزمنية المحلية لهاتف المستلم تلقائياً.\n2. **تجميع البيانات الوصفية**: يتم تجميع `event.name` و `event.description` و `event.location.name` في حزمة حدث واتساب أصلية. هذه الحزمة تفاعلية—يمكن للمستخدمين النقر عليها لتوسيع عرض \"التفاصيل الكاملة\" الذي يظل متاحاً حتى بعد تحرك الدردشة للأمام.\n3. **إدارة الضيوف**: تعد علامة `extraGuestsAllowed` إشارة هيكلية. إذا كانت صحيحة، فإنها تشير للمستخدم بأن الحدث مفتوح لمشاركة أوسع، وغالباً ما تُستخدم في الندوات عبر الإنترنت أو التجمعات المجتمعية.\n\n---\n\n## 🛡️ أفضل الممارسات الاستراتيجية للتفاعل مع الأحداث\n\n### 1. الوصف كـ \"نداء للعمل\" (Call-to-Action)\nحقل `event.description` هو أثمن حقل نصي لديك.\n- **الروابط العميقة**: إذا كان الحدث اجتماعاً افتراضياً (Zoom، Google Meet، مكالمة WhatsApp)، فقم بتضمين رابط الانضمام مباشرة في الوصف. ستتعرف أنظمة تشغيل الهواتف المحمولة على الرابط وتجعله قابلاً للنقر داخل عرض تفاصيل الحدث.\n- **المشاركة**: استخدم الوصف لتقديم جدول أعمال رفيع المستوى. بما أن الحدث يستمر في الجزء العلوي من الدردشة أو في قسم \"الوسائط/الروابط/المستندات\"، فإنه يعمل كنقطة مرجعية دائمة للمستخدم.\n\n### 2. نزاهة المنطقة الزمنية\nأحد أكبر أسباب فوات المواعيد هو الارتباك في المناطق الزمنية.\n- **المعيار العالمي**: يتوقع Wawp طوابع Unix الزمنية بصيغة **UTC**. لا ترسل أبداً طوابع زمنية بتنسيق محلي دون تطبيعها أولاً إلى عهد UTC.\n- **تجربة المستخدم**: لأن Wawp يسلم طابع UTC لشبكة واتساب، فإن هاتف المستلم سيعرض الوقت تلقائياً بوقته المحلي (مثلاً ، إذا أرسلت حدثاً للساعة 3 مساءً UTC، سيرى مستخدم في لندن الساعة 3 مساءً، بينما يرى مستخدم في نيويورك الساعة 10 صباحاً).\n\n### 3. وضوح الموقع (مادي مقابل افتراضي)\n- **الأحداث المادية**: استخدم `event.location.name` لرقم الغرفة أو اسم المبنى.\n- **الأحداث الافتراضية**: اضبط اسم الموقع على \"💻 اجتماع افتراضي\" أو \"🎥 بث مباشر\". يوفر هذا سياقاً بصرياً فورياً قبل أن يفتح المستخدم التفاصيل.\n\n---\n\n## 🧩 حالات استخدام متقدمة\n\n### التسجيل المؤتمت في الندوات (Webinars)\nعندما يسجل مستخدم في ندوة عبر بوت، أطلق `/v2/send/event` فوراً. يتيح ذلك للمستخدم النقر على \"إضافة إلى التقويم\" بينما لا يزال اهتمامه في ذروته. ادمج هذا مع معلمة `reply_to` لربط بطاقة الحدث برسالة \"تم التسجيل بنجاح\".\n\n### حجز مواعيد الخدمة\nلصالونات الحلاقة، الأطباء، أو خدمات الإصلاح، أرسل بطاقة حدث بمجرد تأكيد الموعد. المظهر الاحترافي لبطاقة الحدث يزيد بشكل كبير من \"الجودة المدركة\" للخدمة ويقلل من معدل \"عدم الحضور\" من خلال التكامل مع أداة التخطيط الأساسية للمستخدم (تقويمه الشخصي).\n\n---\n\n## 🛠️ المزالق الشائعة والحلول\n\n- **الثواني مقابل الملي ثانية**: خطأ تقني شائع هو إرسال `Date.now()` الخاص بـ JS (وهو بالملي ثانية) بدلاً من ثواني Unix المطلوبة. سيؤدي هذا إلى جدولة حدث بعد آلاف السنين في المستقبل. اقسم دائماً القيمة على 1000.\n- **المدد القصيرة**: بينما يسمح واتساب بأحداث قصيرة جداً، نوصي بمدة أدناها **15 دقيقة** لضمان أن تكون كتلة التقويم بارزة بصرياً بما يكفي ليلاحظها المستخدم.\n- **تضارب التداخل**: لا يمنعك واتساب من إرسال أحداث متداخلة، لكن يجب على نظامك فعل ذلك. إذا كانت الجلسة مشغولة بالفعل، ففكر في استخدام استطلاع أولاً للعثور على فتحة متاحة قبل إرسال بطاقة الحدث النهائية.\n\n---\n\n## ملخص الإمكانيات:\n- تقديم بطاقات أحداث واتساب أصلية وتفاعلية مع تكامل التقويم بنقرة واحدة.\n- دعم كامل للجدولة المبنية على طوابع Unix الزمنية مع تطبيع المنطقة الزمنية تلقائياً.\n- دعم بيانات وصفية عالية الدقة لأسماء الأحداث، الأوصاف، والمواقع المخصصة.\n- إشارات هيكلية لأذونات الضيوف عبر علامة `extraGuestsAllowed`.\n- تكامل سلس مع خيوط المحادثة عبر معلمة `reply_to`.\n- حضور دائم في واجهة المستخدم داخل الدردشة، مما يجعله مرجعاً دائماً للأنشطة المجدولة.\n",
          "args": {
            "instance_id": {
              "description": "المعرف الفريد لجلسة واتساب"
            },
            "access_token": {
              "description": "رمز وصول API"
            },
            "chatId": {
              "description": "رقم واتساب للمستلم"
            },
            "event.name": {
              "description": "اسم الحدث (مثل اجتماع الفريق 📅)"
            },
            "event.description": {
              "description": "وصف الحدث"
            },
            "event.startTime": {
              "description": "وقت البدء (طابع Unix الزمني بالثواني)"
            },
            "event.endTime": {
              "description": "وقت الانتهاء (طابع Unix الزمني بالثواني)"
            },
            "event.location.name": {
              "description": "اسم الموقع (مثل غرفة الاجتماعات أ)"
            },
            "event.extraGuestsAllowed": {
              "description": "ما إذا كان يسمح بضيوف إضافيين"
            },
            "reply_to": {
              "description": "معرف الرسالة التي تقوم بالرد عليها"
            }
          },
          "tips": [
            {
              "title": "طوابع Unix الزمنية",
              "content": "تحقق مرتين من منطق الطوابع الزمنية الخاصة بك. تأكد من إرسال الثواني (مثل 1735920000) وليس الملي ثانية."
            }
          ]
        }
      }
    },
    {
      "path": "/v2/send/voice",
      "methods": [
        "POST",
        "GET"
      ],
      "title": "Send Voice",
      "category": "Send Messages",
      "description": "Voice messages accept OGG/Opus. Required params: instance_id, access_token, chatId, file[url], file[filename], file[mimetype], convert.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Unique ID of the WhatsApp session",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API access token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Recipient's WhatsApp ID (JID). Supports Individuals (@c.us), Groups (@g.us), and Newsletters (@newsletter).",
          "example": "447441429009@c.us"
        },
        "file[url]": {
          "required": true,
          "type": "string",
          "description": "Publicly accessible HTTPS URL of the audio file",
          "example": "https://raw.githubusercontent.com/rafaelreis-hotmart/Audio-Sample-files/master/sample.ogg"
        },
        "file[filename]": {
          "required": true,
          "type": "string",
          "description": "Filename for the audio note",
          "example": "voice.ogg"
        },
        "file[mimetype]": {
          "required": true,
          "type": "string",
          "description": "MIME type (audio/ogg; codecs=opus recommended)",
          "example": "audio/ogg; codecs=opus"
        },
        "convert": {
          "required": true,
          "type": "boolean",
          "description": "Automatically transcode to WhatsApp compatible OGG/Opus",
          "example": "true"
        },
        "reply_to": {
          "required": false,
          "type": "string",
          "description": "The ID of the message you are replying to",
          "example": "false_111...AAAA"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Message Sent Successfully",
          "contentType": "application/json",
          "example": {
            "_data": {
              "id": {
                "fromMe": true,
                "remote": "000000000000@c.us",
                "id": "MSG_ID_123456",
                "_serialized": "true_000000000000@c.us_MSG_ID_123456"
              },
              "viewed": false,
              "body": "BASE64_IMAGE_DATA",
              "type": "image",
              "t": 1759108866,
              "from": {
                "server": "c.us",
                "user": "111111111111",
                "_serialized": "111111111111@c.us"
              },
              "to": {
                "server": "c.us",
                "user": "000000000000",
                "_serialized": "000000000000@c.us"
              },
              "ack": 0,
              "isNewMsg": true,
              "star": false,
              "kicNotified": false,
              "caption": "Here's your requested image.",
              "deprecatedMms3Url": "https://example.com/media-url",
              "directPath": "/media/direct/path/example",
              "mimetype": "image/jpeg",
              "filehash": "FILE_HASH_PLACEHOLDER",
              "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
              "size": 192487,
              "mediaKey": "MEDIA_KEY_PLACEHOLDER",
              "mediaKeyTimestamp": 1759108865,
              "streamable": false,
              "mediaHandle": null,
              "isFromTemplate": false,
              "pollInvalidated": false,
              "isSentCagPollCreation": false,
              "latestEditMsgKey": null,
              "latestEditSenderTimestampMs": null,
              "mentionedJidList": [],
              "groupMentions": [],
              "isEventCanceled": false,
              "eventInvalidated": false,
              "isVcardOverMmsDocument": false,
              "isForwarded": false,
              "isQuestion": false,
              "questionReplyQuotedMessage": null,
              "questionResponsesCount": 0,
              "readQuestionResponsesCount": 0,
              "labels": [],
              "hasReaction": false,
              "disappearingModeInitiator": "chat",
              "disappearingModeTrigger": "chat_settings",
              "productHeaderImageRejected": false,
              "lastPlaybackProgress": 0,
              "isDynamicReplyButtonsMsg": false,
              "isCarouselCard": false,
              "parentMsgId": null,
              "callSilenceReason": null,
              "isVideoCall": false,
              "callDuration": null,
              "callCreator": null,
              "callParticipants": null,
              "isCallLink": null,
              "callLinkToken": null,
              "isMdHistoryMsg": false,
              "stickerSentTs": 0,
              "lastUpdateFromServerTs": 0,
              "invokedBotWid": null,
              "bizBotType": null,
              "botResponseTargetId": null,
              "botPluginType": null,
              "botPluginReferenceIndex": null,
              "botPluginSearchProvider": null,
              "botPluginSearchUrl": null,
              "botPluginSearchQuery": null,
              "botPluginMaybeParent": false,
              "botReelPluginThumbnailCdnUrl": null,
              "botMessageDisclaimerText": null,
              "botMsgBodyType": null,
              "requiresDirectConnection": false,
              "bizContentPlaceholderType": null,
              "hostedBizEncStateMismatch": false,
              "senderOrRecipientAccountTypeHosted": false,
              "placeholderCreatedWhenAccountIsHosted": false,
              "galaxyFlowDisabled": false,
              "links": []
            },
            "mediaKey": "MEDIA_KEY_PLACEHOLDER",
            "id": {
              "fromMe": true,
              "remote": "000000000000@c.us",
              "id": "MSG_ID_123456",
              "_serialized": "true_000000000000@c.us_MSG_ID_123456"
            },
            "ack": 0,
            "hasMedia": true,
            "body": "Here's your requested image.",
            "type": "image",
            "timestamp": 1759108866,
            "from": "111111111111@c.us",
            "to": "000000000000@c.us",
            "deviceType": "android",
            "isForwarded": false,
            "forwardingScore": 0,
            "isStatus": false,
            "isStarred": false,
            "fromMe": true,
            "hasQuotedMsg": false,
            "hasReaction": false,
            "vCards": [],
            "mentionedIds": [],
            "groupMentions": [],
            "isGif": false,
            "links": []
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Egypt)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Egypt mobile numbers must be 11 digits (national format).",
            "details": {
              "provided": "20114520282",
              "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
              "info": {
                "country": "EG",
                "type": "MOBILE"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Saudi Arabia)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for SA.",
            "details": {
              "provided": "96655555",
              "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
              "info": {
                "country": "SA"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Unknown)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for Unknown.",
            "details": {
              "provided": "01145202826",
              "recommendation": "Ensure individual numbers are in international format (starting with country code).",
              "info": {
                "country": "Unknown"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 429,
          "description": "Too Many Requests - Rate Limit Exceeded",
          "contentType": "application/json",
          "example": {
            "code": "rate_limit_exceeded",
            "message": "Too many requests. Please slow down.",
            "details": {
              "retryAfter": 60,
              "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
              "upstream": {
                "error": "Rate limit",
                "statusCode": 429
              }
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "extraInfo": "\n# The Human Touch: Mastering the Voice Messaging Engine\n\nVoice messages are the most personal way to communicate on WhatsApp, often preferred for their convenience and emotional resonance. The `/v2/send/voice` endpoint provides a specialized pipeline for delivering high-fidelity audio notes that appear as the native \"blue-microphone\" messages users expect. Wawp’s voice engine manages the intricate requirements of audio transcoding, MIME-type enforcement, and network buffering to ensure a seamless listening experience.\n\n![send voice.png](https://api.apidog.com/api/v1/projects/1017306/resources/369242/image-preview)\n\n---\n\n## 🏗️ The Intelligent Audio Transcoding Pipeline\n\nWhatsApp is extremely specific about its voice message format. Unlike standard audio file transfers (which appear as documents), true voice notes must be **OGG/Opus** with specific metadata headers. Wawp simplifies this for you:\n1. **Source Evaluation**: The engine analyzes the source file from your `file[url]`. It determines the bitrate, sample rate, and codec.\n2. **The \"Convert\" Logic**: When `convert: true` is set, Wawp initiates a high-performance cloud transcoding process. It takes standard formats like MP3, AAC, or WAV and transforms them into the exact OGG/Opus profile optimized for the WhatsApp mobile app.\n3. **MIME-Type Alignment**: The engine ensures that the emitted file has the correct `audio/ogg; codecs=opus` header, which triggers the specialized \"Voice Note\" UI on the recipient's phone.\n\n---\n\n## 🛡️ Strategic Best Practices for Audio Delivery\n\n### 1. Recording for Quality\nTo ensure your automated voice messages sound professional:\n- **Sample Rate**: Record your source audio at **16kHz or 24kHz**. WhatsApp’s Opus implementation is optimized for these lower-to-mid ranges, and higher fidelity (like 48kHz) often leads to unnecessary file size increases without a perceptible gain in mobile speaker quality.\n- **Mono vs. Stereo**: Always use **Mono**. WhatsApp will down-mix stereo signals anyway, and mono files half the bandwidth requirements for both your server and your user.\n\n### 2. The Conversion Lifecycle\n- **Efficiency Hint**: If your source is already OGG/Opus, you can set `convert: false`. However, we recommend defaulting to `true` to protect against edge cases where the source metadata might be slightly off-spec, which can cause the play button to fail on some Android devices.\n- **Transcoding Latency**: Cloud transcoding adds a small amount of latency (typically 1–3 seconds) to the processing time. Factor this into your application's timeout logic.\n\n### 3. UX and Accessibility\nVoice messaging isn't just about the audio; it's about the context.\n- **Typing Indicator**: Before sending a voice note, call the [`/v2/send/start-typing`](/v2/send/start-typing) endpoint. This creates the \"Typing...\" or \"Recording audio...\" status on the recipient's phone, making the message feel more organic and less like an automated broadcast.\n- **Interactive Feedback**: In your frontend, show a \"Transcoding...\" spinner after the user submits an audio file to manage expectations during the cloud processing phase.\n\n---\n\n## 🧩 Advanced Use Cases\n\n### Voice-Powered Notification Banners\nInstead of a text-based order update, send a 5-second voice note saying, \"Hi there! Your order is on the way.\" The personal touch significantly increases engagement and brand loyalty in localized markets.\n\n### Interactive Voice Response (IVR) for WhatsApp\nBuild a support bot where users can send voice notes for queries. Your backend can transcribe the audio using an AI service, and then respond with a pre-recorded voice note via Wawp, creating a truly conversational voice interface.\n\n---\n\n## 🛠️ Common Pitfalls and Solutions\n\n- **Mismatched Mime-Types**: Providing a `.mp3` extension with an `audio/ogg` mimetype will often cause the engine to return a `Bad Request`. Ensure your `file[filename]` and `file[mimetype]` align with the actual source file on your server.\n- **Corrupted Headers**: Some audio recorders produce OGG files with non-standard page sizes. If a voice note arrives but won't play, it’s a sign that the headers are corrupted. Enabling `convert: true` almost always fixes this by rebuilding the file from the raw audio stream.\n- **Volume Normalization**: Automated voices can sometimes be too loud or too quiet. We recommend normalizing your source clips to **-3dB** to ensure consistent volume regardless of the recipient's phone settings.\n\n---\n\n## Summary of Capabilities:\n- Deliver native WhatsApp \"Voice Notes\" (OGG/Opus) from any public HTTPS URL.\n- Full support for cloud-based transcoding from MP3, AAC, and WAV via the `convert` flag.\n- Precise integration with threading and replies using the `reply_to` parameter.\n- Consistent success reporting with unique `message_id` generation.\n- Optimized for low-bandwidth mobile consumption while maintaining high vocal clarity.\n",
      "tips": [
        {
          "type": "info",
          "title": "Format",
          "content": "Requires OGG format with Opus codec for PTT (Push-to-Talk) styling."
        },
        {
          "type": "positive",
          "title": "Experience",
          "content": "Appears as a playable waveform in the chat."
        }
      ],
      "recommendations": [
        "Convert audio to the correct format using ffmpeg before sending.",
        "Keep voice notes short (under 2 minutes) for better engagement."
      ],
      "image": "https://api.apidog.com/api/v1/projects/1017306/resources/369242/image-preview",
      "translations": {
        "ar": {
          "title": "إرسال رسالة صوتية",
          "description": "تقبل الرسائل الصوتية OGG/Opus. المعلمات المطلوبة: instance_id، access_token، chatId، file[url]، file[filename]، file[mimetype]، convert.",
          "tips": [
            {
              "title": "التنسيق",
              "content": "يتطلب تنسيق OGG مع برنامج ترميز Opus لنمط PTT (اضغط لتتحدث)."
            },
            {
              "title": "التجربة",
              "content": "يظهر كموجة صوتية قابلة للتشغيل في الدردشة."
            }
          ],
          "recommendations": [
            "قم بتحويل الصوت إلى التنسيق الصحيح باستخدام ffmpeg قبل الإرسال.",
            "اجعل الملاحظات الصوتية قصيرة (أقل من دقيقتين) لتفاعل أفضل."
          ],
          "extraInfo": "\n# اللمسة الإنسانية: إتقان محرك الرسائل الصوتية\n\nالرسائل الصوتية هي الطريقة الأكثرشخصية للتواصل على واتساب، وغالبًا ما تُفضل لراحتها ورنينها العاطفي. توفر نقطة نهاية `/v2/send/voice` مسارًا متخصصًا لتقديم ملاحظات صوتية عالية الدقة تظهر كرسائل \"الميكروفون الأزرق\" الأصلية التي يتوقعها المستخدمون. يدير محرك صوت Wawp المتطلبات المعقدة لفك تشفير الصوت، وفرض نوع MIME، وتخزين الشبكة المؤقت لضمان تجربة استماع سلسة.\n\n![إرسال صوت](https://api.apidog.com/api/v1/projects/1017306/resources/369242/image-preview)\n\n---\n\n## 🏗️ محرك فك تشفير الصوت الذكي سحابيًا\n\nواتساب محدد للغاية بشأن تنسيق الرسائل الصوتية الخاصة به. على عكس عمليات نقل ملفات الصوت القياسية (التي تظهر كمستندات)، يجب أن تكون الملاحظات الصوتية الحقيقية بتنسيق **OGG/Opus** مع رؤوس بيانات وصفية محددة. يسهل Wawp ذلك عليك:\n1. **تقييم المصدر**: يقوم المحرك بتحليل ملف المصدر من `file[url]` الخاص بك. ويحدد معدل البت ومعدل العينة وبرنامج الترميز.\n2. **منطق \"التحويل\" (Convert Logic)**: عند تعيين `convert: true`، يبدأ Wawp عملية فك تشفير سحابية عالية الأداء. يأخذ التنسيقات القياسية مثل MP3 أو AAC أو WAV ويحولها إلى ملف OGG/Opus الدقيق المحسن لتطبيق واتساب للجوال.\n3. **محاذاة نوع MIME**: يضمن المحرك أن الملف الصادر لديه رأس `audio/ogg; codecs=opus` الصحيح، والذي يطلق واجهة مستخدم \"ملاحظة صوتية\" المتخصصة على هاتف المستلم.\n\n---\n\n## 🛡️ أفضل الممارسات الاستراتيجية لتسليم الصوت\n\n### 1. التسجيل من أجل الجودة\nلضمان سماع رسائلك الصوتية المؤتمتة بشكل احترافي:\n- **معدل العينة**: سجل صوت المصدر الخاص بك بتردد **16 كيلو هرتز أو 24 كيلو هرتز**. تم تحسين تنفيذ Opus في واتساب لهذه النطاقات المنخفضة إلى المتوسطة، وغالبًا ما تؤدي الدقة الأعلى (مثل 48 كيلو هرتز) إلى زيادات غير ضرورية في حجم الملف دون مكاسب ملموسة في جودة سماعة الهاتف المحمول.\n- **أحادية مقابل ستيريو (Mono vs. Stereo)**: استخدم دائمًا **Mono**. سيقوم واتساب بخلط إشارات الستيريو إلى أحادية على أي حال، والملفات الأحادية تقلل من متطلبات النطاق الترددي لكل من خادمك ومستخدمك.\n\n### 2. دورة حياة التحويل\n- **تلميح الكفاءة**: إذا كان المصدر الخاص بك بالفعل OGG/Opus، يمكنك تعيين `convert: false`. ومع ذلك، نوصي بالالتزام بـ `true` للحماية من الحالات الحدودية حيث قد تكون البيانات الوصفية للمصدر غير دقيقة قليلاً، مما قد يؤدي إلى فشل زر التشغيل على بعض أجهزة Android.\n- **تأخير فك التشفير**: يضيف فك التشفير السحابي قدرًا صغيرًا من التأخير (عادةً 1-3 ثوانٍ) إلى وقت المعالجة. ضع ذلك في الاعتبار في منطق المهلة الخاص بتطبيقك.\n\n### 3. تجربة المستخدم وسهولة الوصول\nالمراسلة الصوتية لا تتعلق فقط بالصوت؛ بل تتعلق بالسياق.\n- **مؤشر الكتابة**: قبل إرسال ملاحظة صوتية، استدعِ نقطة النهاية [`/v2/send/start-typing`](/v2/send/start-typing). هذا ينشئ حالة \"جاري الكتابة...\" أو \"جاري تسجيل صوت...\" على هاتف المستلم، مما يجعل الرسالة تبدو أكثر حيوية وأقل شبهًا ببث مؤتمت.\n- **ملاحظات تفاعلية**: في واجهتك الأمامية، اعرض مؤشر \"جاري معالجة الصوت...\" بعد أن يرسل المستخدم ملفًا صوتيًا لإدارة التوقعات أثناء مرحلة المعالجة السحابية.\n\n---\n\n## 🧩 حالات استخدام متقدمة\n\n### لافتات إشعارات مدعومة بالصوت\nبدلاً من تحديث طلب نصي، أرسل ملاحظة صوتية مدتها 5 ثوانٍ تقول: \"مرحبًا! طلبك في الطريق\". تزيد اللمسة الشخصية بشكل كبير من التفاعل وولاء العلامة التجارية في الأسواق المحلية.\n\n### استجابة صوتية تفاعلية (IVR) لواتساب\nقم ببناء بوت دعم حيث يمكن للمستخدمين إرسال ملاحظات صوتية للاستفسارات. يمكن لخلفية تطبيقك تحويل الصوت إلى نص باستخدام خدمة ذكاء اصطناعي، ثم الرد بملاحظة صوتية مسجلة مسبقًا عبر Wawp، مما يخلق واجهة صوتية حوارية حقًا.\n\n---\n\n## 🛠️ المزالق الشائعة والحلول\n\n- **أنواع Mime غير متطابقة**: تقديم امتداد `.mp3` مع نوع mime `audio/ogg` سيؤدي غالبًا إلى إرجاع المحرك لخطأ `Bad Request`. تأكد من توافق `file[filename]` و `file[mimetype]` مع ملف المصدر الفعلي على خادمك.\n- **رؤوس تالفة**: تنتج بعض مسجلات الصوت ملفات OGG بأحجام صفحات غير قياسية. إذا وصلت ملاحظة صوتية ولكن لم تعمل، فهذه علامة على تلف الرؤوس. تفعيل `convert: true` يحل هذا الأمر دائمًا تقريبًا عن طريق إعادة بناء الملف من دفق الصوت الخام.\n- **تطبيع مستوى الصوت**: يمكن أن تكون الأصوات المؤتمتة صاخبة جدًا أو هادئة جدًا في بعض الأحيان. نوصي بتطبيع مقاطع المصدر الخاصة بك إلى **-3dB** لضمان مستوى صوت متسق بغض النظر عن إعدادات هاتف المستلم.\n\n---\n\n## ملخص الإمكانيات:\n- تقديم \"ملاحظات صوتية\" أصلية لواتساب (OGG/Opus) من أي عنوان URL عام (HTTPS).\n- دعم كامل لفك التشفير السحابي من MP3 و AAC و WAV عبر علم `convert`.\n- تكامل دقيق مع الخيوط والردود باستخدام معلمة `reply_to`.\n- تقارير نجاح متسقة مع توليد معرف `message_id` فريد.\n- محسّن للاستهلاك المحمول منخفض النطاق الترددي مع الحفاظ على وضوح صوتي عالٍ.\n",
          "args": {
            "instance_id": {
              "description": "المعرف الفريد لجلسة واتساب"
            },
            "access_token": {
              "description": "رمز وصول API"
            },
            "chatId": {
              "description": "معرف واتساب للمستلم (JID). يدعم الأفراد (@c.us)، المجموعات (@g.us)، والقنوات (@newsletter)."
            },
            "file[url]": {
              "description": "عنوان URL متاح للعامة عبر HTTPS لملف الصوت"
            },
            "file[filename]": {
              "description": "اسم الملف للملاحظة الصوتية"
            },
            "file[mimetype]": {
              "description": "نوع MIME (يوصى بـ audio/ogg; codecs=opus)"
            },
            "convert": {
              "description": "التحويل التلقائي إلى تنسيق OGG/Opus المتوافق مع واتساب"
            },
            "reply_to": {
              "description": "معرف الرسالة التي تقوم بالرد عليها"
            }
          }
        }
      }
    },
    {
      "path": "/v2/send/video",
      "methods": [
        "POST",
        "GET"
      ],
      "title": "Send Video",
      "category": "Send Messages",
      "description": "Send a video file to a chat.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Recipient's WhatsApp ID (JID). Supports Individuals (@c.us), Groups (@g.us), and Newsletters (@newsletter).",
          "example": "447441429009@c.us"
        },
        "caption": {
          "required": true,
          "type": "string",
          "description": "Video caption",
          "example": "Watch this clip"
        },
        "convert": {
          "required": true,
          "type": "boolean",
          "description": "Attempt to convert video to compatible MP4 if needed",
          "example": "true"
        },
        "asNote": {
          "required": true,
          "type": "boolean",
          "description": "Send as a round 'Video Note' (if supported by engine)",
          "example": "false"
        },
        "file[url]": {
          "required": true,
          "type": "string",
          "description": "Publicly accessible URL of the video",
          "example": "https://wawp.net/samples/file_example_MP4_480_1_5MG.mp4"
        },
        "file[filename]": {
          "required": true,
          "type": "string",
          "description": "Filename for the video",
          "example": "video.mp4"
        },
        "file[mimetype]": {
          "required": true,
          "type": "string",
          "description": "MIME type of the video",
          "example": "video/mp4"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Message Sent Successfully",
          "contentType": "application/json",
          "example": {
            "_data": {
              "id": {
                "fromMe": true,
                "remote": "000000000000@c.us",
                "id": "MSG_ID_123456",
                "_serialized": "true_000000000000@c.us_MSG_ID_123456"
              },
              "viewed": false,
              "body": "BASE64_IMAGE_DATA",
              "type": "image",
              "t": 1759108866,
              "from": {
                "server": "c.us",
                "user": "111111111111",
                "_serialized": "111111111111@c.us"
              },
              "to": {
                "server": "c.us",
                "user": "000000000000",
                "_serialized": "000000000000@c.us"
              },
              "ack": 0,
              "isNewMsg": true,
              "star": false,
              "kicNotified": false,
              "caption": "Here's your requested image.",
              "deprecatedMms3Url": "https://example.com/media-url",
              "directPath": "/media/direct/path/example",
              "mimetype": "image/jpeg",
              "filehash": "FILE_HASH_PLACEHOLDER",
              "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
              "size": 192487,
              "mediaKey": "MEDIA_KEY_PLACEHOLDER",
              "mediaKeyTimestamp": 1759108865,
              "streamable": false,
              "mediaHandle": null,
              "isFromTemplate": false,
              "pollInvalidated": false,
              "isSentCagPollCreation": false,
              "latestEditMsgKey": null,
              "latestEditSenderTimestampMs": null,
              "mentionedJidList": [],
              "groupMentions": [],
              "isEventCanceled": false,
              "eventInvalidated": false,
              "isVcardOverMmsDocument": false,
              "isForwarded": false,
              "isQuestion": false,
              "questionReplyQuotedMessage": null,
              "questionResponsesCount": 0,
              "readQuestionResponsesCount": 0,
              "labels": [],
              "hasReaction": false,
              "disappearingModeInitiator": "chat",
              "disappearingModeTrigger": "chat_settings",
              "productHeaderImageRejected": false,
              "lastPlaybackProgress": 0,
              "isDynamicReplyButtonsMsg": false,
              "isCarouselCard": false,
              "parentMsgId": null,
              "callSilenceReason": null,
              "isVideoCall": false,
              "callDuration": null,
              "callCreator": null,
              "callParticipants": null,
              "isCallLink": null,
              "callLinkToken": null,
              "isMdHistoryMsg": false,
              "stickerSentTs": 0,
              "lastUpdateFromServerTs": 0,
              "invokedBotWid": null,
              "bizBotType": null,
              "botResponseTargetId": null,
              "botPluginType": null,
              "botPluginReferenceIndex": null,
              "botPluginSearchProvider": null,
              "botPluginSearchUrl": null,
              "botPluginSearchQuery": null,
              "botPluginMaybeParent": false,
              "botReelPluginThumbnailCdnUrl": null,
              "botMessageDisclaimerText": null,
              "botMsgBodyType": null,
              "requiresDirectConnection": false,
              "bizContentPlaceholderType": null,
              "hostedBizEncStateMismatch": false,
              "senderOrRecipientAccountTypeHosted": false,
              "placeholderCreatedWhenAccountIsHosted": false,
              "galaxyFlowDisabled": false,
              "links": []
            },
            "mediaKey": "MEDIA_KEY_PLACEHOLDER",
            "id": {
              "fromMe": true,
              "remote": "000000000000@c.us",
              "id": "MSG_ID_123456",
              "_serialized": "true_000000000000@c.us_MSG_ID_123456"
            },
            "ack": 0,
            "hasMedia": true,
            "body": "Here's your requested image.",
            "type": "image",
            "timestamp": 1759108866,
            "from": "111111111111@c.us",
            "to": "000000000000@c.us",
            "deviceType": "android",
            "isForwarded": false,
            "forwardingScore": 0,
            "isStatus": false,
            "isStarred": false,
            "fromMe": true,
            "hasQuotedMsg": false,
            "hasReaction": false,
            "vCards": [],
            "mentionedIds": [],
            "groupMentions": [],
            "isGif": false,
            "links": []
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Egypt)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Egypt mobile numbers must be 11 digits (national format).",
            "details": {
              "provided": "20114520282",
              "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
              "info": {
                "country": "EG",
                "type": "MOBILE"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Saudi Arabia)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for SA.",
            "details": {
              "provided": "96655555",
              "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
              "info": {
                "country": "SA"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Unknown)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for Unknown.",
            "details": {
              "provided": "01145202826",
              "recommendation": "Ensure individual numbers are in international format (starting with country code).",
              "info": {
                "country": "Unknown"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 429,
          "description": "Too Many Requests - Rate Limit Exceeded",
          "contentType": "application/json",
          "example": {
            "code": "rate_limit_exceeded",
            "message": "Too many requests. Please slow down.",
            "details": {
              "retryAfter": 60,
              "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
              "upstream": {
                "error": "Rate limit",
                "statusCode": 429
              }
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "extraInfo": "\n# Moving Pictures: Mastering the Video Messaging Engine\n\nVideo is the ultimate medium for complex information delivery, whether it's an educational tutorial, a personalized message from a CEO, or a visually rich product demonstration. The `/v2/send/video` endpoint is engineered to handle the substantial data and processing requirements of video files, ensuring they arrive on the recipient's phone in a format that is ready for instant playback.\n\n---\n\n## 🏗️ The Intelligent Video Processing Pipeline\n\nUnlike basic file transfers, Wawp treats videos as dynamic assets. Our pipeline includes several specialized stages:\n1. **Validation & Mime-Type Consistency**: The engine checks the `file[mimetype]` against the actual binary headers. While MP4 is the standard, our engine can handle various containers and normalize them for the WhatsApp network.\n2. **The \"Conversion\" Engine**: One of Wawp's most powerful features is the `convert` flag. When enabled, the engine evaluates the source video's bitrate, resolution, and encoding (H.264/AAC). If the video is likely to be rejected by WhatsApp due to incompatible parameters, Wawp performs a cloud-based re-encoding to ensure a successful delivery.\n3. **Stream Buffering**: To prevent transient network failures from killing a transfer, our engine uses an adaptive buffering strategy when fetching videos from your remote `file[url]`.\n\n---\n\n## 🛡️ Strategic Best Practices for Video Optimization\n\n### 1. The 16MB Frontier\nWhatsApp has a hard limit of **16MB** for video transfers on most mobile devices.\n- **Developer Action**: If your source video is 50MB, do not send it directly. Use a pre-processing tool or our [`/v2/media/convert`](/v2/media/convert) utility to bring it under the 16MB threshold.\n- **Target Bitrate**: Aim for a bitrate of **1.5 Mbps to 2 Mbps** with a resolution of **480p or 720p**. This strikes the perfect balance between visual clarity and file size safety.\n\n### 2. Formatting for Success (MP4 vs. Others)\nWhile many formats exist, **MP4 (H.264)** is the gold standard for Wawp.\n- **Universal Playback**: By sticking to H.264, you ensure that even users on older Android or iOS devices can play the video instantly without downloading additional codecs.\n- **Audio Sync**: Always ensure your audio is encoded in **AAC** at 44.1kHz or 48kHz to prevent \"Mute Video\" errors on the recipient's device.\n\n### 3. AsNote: The \"Video Note\" Advantage\nThe `asNote` parameter allows you to send videos in the distinctive circular \"Video Note\" format. \n- **UX Impact**: Round video notes feel more personal and spontaneous. They are perfect for \"Thank You\" messages or quick status updates. \n- **Constraint**: Video notes are typically limited to **60 seconds** and do not support captions. Ensure your content fits these constraints when switching to \"Note\" mode.\n\n---\n\n## 🧩 Advanced Use Cases\n\n### Educational Drip Campaigns\nVideos are perfect for daily educational content. By using the `caption` field, you can provide a textual summary of the video's key points. Because Wawp supports full markdown, you can use `*bold*` headers to make the caption as engaging as the video itself.\n\n### Customer Support via Screen-Cast\nInstead of explaining a complex UI step-by-step in text, send a 30-second screen-cast. Use the `reply_to` field to link the video directly to the user's specific support ticket, creating a high-resolution support experience.\n\n---\n\n## 🛠️ Common Pitfalls and Solutions\n\n- **Failed Fetches**: If your video server is behind a slow connection, the Wawp engine might timeout. Ensure your video host responds to `GET` requests within **5-10 seconds**.\n- **The \"No Thumbnail\" Bug**: If a video arrives but the thumbnail is black, it’s often because the first frame of the video is black. Consider fading into your content or ensuring the metadata isn't corrupted.\n- **Unsupported Codecs**: Attempting to send H.265 (HEVC) or AV1 without setting `convert: true` may lead to a \"Format Not Supported\" error on older devices. Always default to `true` if you aren't 100% sure of your source encoding.\n\n---\n\n## Summary of Capabilities:\n- Deliver high-quality MP4 videos with integrated, markdown-rich captions.\n- Automated cloud-based video re-encoding via the `convert` flag.\n- Support for the \"Video Note\" circular format for high-engagement messaging.\n- Remote fetching from any secure HTTPS URL with adaptive buffering.\n- Consistent success reporting with unique `message_id` generation for full delivery tracking.\n",
      "tips": [
        {
          "type": "info",
          "title": "Auto-Download",
          "content": "Most users have auto-download enabled for videos on Wi-Fi but disabled on data. Consider this for your marketing hooks."
        },
        {
          "type": "warning",
          "title": "Compression",
          "content": "Sending raw 4K video is not recommended. Pre-compress your videos to 720p or 480p."
        }
      ],
      "recommendations": [
        "Use \"reply_to\" to maintain conversation context.",
        "Handle distinct message types (text, image, video) appropriately.",
        "Implement a robust retry mechanism for failed sends."
      ],
      "translations": {
        "ar": {
          "title": "إرسال فيديو",
          "description": "إرسال ملف فيديو إلى دردشة.",
          "recommendations": [
            "أضف تأخيرات عشوائية بين الرسائل لمحاكاة السلوك البشري.",
            "تحقق من أرقام الهواتف قبل الإرسال لضمان التسليم."
          ],
          "extraInfo": "\n# الصور المتحركة: إتقان محرك رسائل الفيديو\n\nيعد الفيديو الوسيلة المثلى لتقديم المعلومات المعقدة، سواء كان ذلك برنامجًا تعليميًا، أو رسالة شخصية من مدير تنفيذي، أو عرضًا توضيحيًا للمنتج غنيًا بصريًا. تم تصميم نقطة نهاية `/v2/send/video` للتعامل مع متطلبات البيانات والمعالجة الكبيرة لملفات الفيديو، مما يضمن وصولها إلى هاتف المستلم بتنسيق جاهز للتشغيل الفوري.\n\n---\n\n## 🏗️ محرك معالجة الفيديو الذكي\n\nعلى عكس عمليات نقل الملفات الأساسية، يتعامل Wawp مع مقاطع الفيديو كأصول ديناميكية. يتضمن مسارنا عدة مراحل متخصصة:\n1. **التحقق واتساق نوع Mime**: يتحقق المحرك من `file[mimetype]` مقابل الرؤوس الثنائية الفعلية. بينما يعد MP4 هو المعيار، يمكن لمحركنا التعامل مع حاويات مختلفة وتطبيعها لشبكة واتساب.\n2. **محرك \"التحويل\" (Conversion Engine)**: من أقوى ميزات Wawp هو علم `convert`. عند تفعيله، يقوم المحرك بتقييم معدل البت والدقة والترميز (H.264/AAC) للفيديو المصدر. إذا كان من المحتمل أن يرفض واتساب الفيديو بسبب معلمات غير متوافقة، يقوم Wawp بإعادة ترميز سحابية لضمان تسليم ناجح.\n3. **تخزين الدفق مؤقتًا (Stream Buffering)**: لمنع فشل الشبكة العابر من إنهاء عملية النقل، يستخدم محركنا استراتيجية تخزين مؤقت تكيفية عند جلب مقاطع الفيديو من `file[url]` البعيد.\n\n---\n\n## 🛡️ أفضل الممارسات الاستراتيجية لتحسين الفيديو\n\n### 1. حدود الـ 16 ميجابايت\nلدى واتساب حد أقصى قدره **16 ميجابايت** لعمليات نقل الفيديو على معظم الأجهزة المحمولة.\n- **إجراء المطور**: إذا كان الفيديو المصدر الخاص بك 50 ميجابايت، فلا ترسله مباشرة. استخدم أداة معالجة مسبقة أو أداة [`/v2/media/convert`](/v2/media/convert) الخاصة بنا لجعله أقل من عتبة الـ 16 ميجابايت.\n- **معدل البت المستهدف**: استهدف معدل بت يتراوح بين **1.5 ميجا بت في الثانية إلى 2 ميجا بت في الثانية** بدقة **480p أو 720p**. هذا يحقق التوازن المثالي بين الوضوح البصري وسلامة حجم الملف.\n\n### 2. التنسيق من أجل النجاح (MP4 مقابل غيره)\nبينما وجود تنسيقات عديدة، فإن **MP4 (H.264)** هو المعيار الذهبي لـ Wawp.\n- **التشغيل العالمي**: من خلال الالتزام بـ H.264، تضمن أن المستخدمين حتى على أجهزة Android أو iOS القديمة يمكنهم تشغيل الفيديو فورًا دون تنزيل برامج ترميز إضافية.\n- **مزامنة الصوت**: تأكد دائمًا من ترميز الصوت بتنسيق **AAC** بتردد 44.1 كيلو هرتز أو 48 كيلو هرتز لمنع أخطاء \"فيديو بدون صوت\" على جهاز المستلم.\n\n### 3. AsNote: ميزة \"ملاحظة الفيديو\"\nتتيح لك معلمة `asNote` إرسال مقاطع فيديو بتنسيق \"ملاحظة فيديو\" دائري مميز.\n- **تأثير تجربة المستخدم**: تبدو ملاحظات الفيديو الدائرية أكثر شخصية وعفوية. إنها مثالية لرسائل \"شكرًا لك\" أو تحديثات الحالة السريعة.\n- **القيد**: تقتصر ملاحظات الفيديو عادةً على **60 ثانية** ولا تدعم الشروحات. تأكد من أن محتواك يناسب هذه القيود عند الانتقال إلى وضع \"الملاحظة\".\n\n---\n\n## 🧩 حالات استخدام متقدمة\n\n### حملات التدريب بالتنقيط\nمقاطع الفيديو مثالية للمحتوى التعليمي اليومي. باستخدام حقل `caption`، يمكنك تقديم ملخص نصي للنقاط الرئيسية للفيديو. نظرًا لأن Wawp يدعم Markdown بالكامل، يمكنك استخدام رؤوس `*عريضة*` لجعل الشرح جذابًا مثل الفيديو نفسه.\n\n### دعم العملاء عبر لقطات الشاشة المتحركة\nبدلاً من شرح واجهة مستخدم معقدة خطوة بخطوة في نص، أرسل لقطة شاشة متحركة مدتها 30 ثانية. استخدم حقل `reply_to` لربط الفيديو مباشرة بتذكرة دعم محددة للمستخدم، مما يؤدي إلى إنشاء تجربة دعم عالية الدقة.\n\n---\n\n## 🛠️ المزالق الشائعة والحلول\n\n- **فشل الجلب (Failed Fetches)**: إذا كان خادم الفيديو خلف اتصال بطيء، فقد يتوقف محرك Wawp. تأكد من استجابة مضيف الفيديو الخاص بك لطلبات `GET` في غضون **5-10 ثوانٍ**.\n- **مشكلة \"لا توجد صورة مصغرة\"**: إذا وصل فيديو ولكن الصورة المصغرة سوداء، فغالباً ما يكون السبب هو أن الإطار الأول من الفيديو أسود. حاول التلاشي للداخل لمحتواك أو التأكد من عدم تلف البيانات الوصفية.\n- **برامج ترميز غير مدعومة**: محاولة إرسال H.265 (HEVC) أو AV1 دون تعيين `convert: true` قد يؤدي إلى خطأ \"تنسيق غير مدعوم\" على الأجهزة القديمة. التزم دائمًا بـ `true` إذا لم تكن متأكدًا بنسبة 100% من ترميز المصدر.\n\n---\n\n## ملخص الإمكانيات:\n- تقديم مقاطع فيديو MP4 عالية الجودة مع شروحات غنية بتنسيق Markdown.\n- إعادة ترميز الفيديو سحابيًا تلقائيًا عبر علم `convert`.\n- دعم تنسيق \"ملاحظة الفيديو\" الدائري لرسائل عالية التفاعل.\n- الجلب عن بُعد من أي عنوان URL آمن (HTTPS) مع تخزين مؤقت تكيفي.\n- تقارير نجاح متسقة مع توليد معرف `message_id` فريد لتتبع التسليم الكامل.\n",
          "args": {
            "instance_id": {
              "description": "المعرف الفريد لجلسة واتساب"
            },
            "access_token": {
              "description": "رمز وصول API"
            },
            "chatId": {
              "description": "معرف واتساب للمستلم (JID). يدعم الأفراد (@c.us)، المجموعات (@g.us)، والقنوات (@newsletter)."
            },
            "caption": {
              "description": "الشرح التوضيحي للفيديو"
            },
            "convert": {
              "description": "محاولة تحويل الفيديو إلى MP4 متوافق إذا لزم الأمر"
            },
            "asNote": {
              "description": "الإرسال كـ 'ملاحظة فيديو' دائرية (إذا كان المحرك يدعم ذلك)"
            },
            "file[url]": {
              "description": "عنوان URL متاح للعامة للفيديو"
            },
            "file[filename]": {
              "description": "اسم الملف للفيديو"
            },
            "file[mimetype]": {
              "description": "نوع MIME للفيديو"
            }
          },
          "tips": [
            {
              "title": "التنزيل التلقائي",
              "content": "معظم المستخدمين لديهم تنزيل تلقائي مفعل لمقاطع الفيديو على Wi-Fi ولكن معطل على بيانات الجوال. ضع ذلك في اعتبارك لخططك التسويقية."
            },
            {
              "title": "الضغط",
              "content": "لا يُنصح بإرسال فيديو 4K خام. قم بضغط مقاطع الفيديو مسبقًا إلى 720p أو 480p."
            }
          ]
        }
      }
    },
    {
      "path": "/v2/send/link-preview",
      "methods": [
        "POST",
        "GET"
      ],
      "title": "Send Link Preview",
      "category": "Send Messages",
      "description": "Send a message with a custom rich link preview card.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Target phone number with country code",
          "example": "447441429009"
        },
        "url": {
          "required": true,
          "type": "string",
          "description": "The URL to preview",
          "example": "https://wawp.net"
        },
        "text": {
          "required": true,
          "type": "string",
          "description": "Optional text message accompanying the link.",
          "example": "Check out our new website!"
        },
        "thumbnail": {
          "required": true,
          "type": "string",
          "description": "URL for a custom thumbnail image (JPEG/PNG)",
          "example": "https://wawp.net/samples/cat.jpg"
        },
        "title": {
          "required": true,
          "type": "string",
          "description": "Custom title for the preview card",
          "example": "Wawp - Advanced WhatsApp API"
        },
        "description": {
          "required": true,
          "type": "string",
          "description": "Custom description for the preview card",
          "example": "The ultimate platform for WhatsApp automation."
        },
        "linkPreviewHighQuality": {
          "required": true,
          "type": "boolean",
          "description": "Try to generate a larger, high-quality preview",
          "example": "true"
        },
        "reply_to": {
          "required": false,
          "type": "string",
          "description": "The ID of a message to reply to",
          "example": "null"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Message Sent Successfully",
          "contentType": "application/json",
          "example": {
            "_data": {
              "id": {
                "fromMe": true,
                "remote": "000000000000@c.us",
                "id": "MSG_ID_123456",
                "_serialized": "true_000000000000@c.us_MSG_ID_123456"
              },
              "viewed": false,
              "body": "BASE64_IMAGE_DATA",
              "type": "image",
              "t": 1759108866,
              "from": {
                "server": "c.us",
                "user": "111111111111",
                "_serialized": "111111111111@c.us"
              },
              "to": {
                "server": "c.us",
                "user": "000000000000",
                "_serialized": "000000000000@c.us"
              },
              "ack": 0,
              "isNewMsg": true,
              "star": false,
              "kicNotified": false,
              "caption": "Here's your requested image.",
              "deprecatedMms3Url": "https://example.com/media-url",
              "directPath": "/media/direct/path/example",
              "mimetype": "image/jpeg",
              "filehash": "FILE_HASH_PLACEHOLDER",
              "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
              "size": 192487,
              "mediaKey": "MEDIA_KEY_PLACEHOLDER",
              "mediaKeyTimestamp": 1759108865,
              "streamable": false,
              "mediaHandle": null,
              "isFromTemplate": false,
              "pollInvalidated": false,
              "isSentCagPollCreation": false,
              "latestEditMsgKey": null,
              "latestEditSenderTimestampMs": null,
              "mentionedJidList": [],
              "groupMentions": [],
              "isEventCanceled": false,
              "eventInvalidated": false,
              "isVcardOverMmsDocument": false,
              "isForwarded": false,
              "isQuestion": false,
              "questionReplyQuotedMessage": null,
              "questionResponsesCount": 0,
              "readQuestionResponsesCount": 0,
              "labels": [],
              "hasReaction": false,
              "disappearingModeInitiator": "chat",
              "disappearingModeTrigger": "chat_settings",
              "productHeaderImageRejected": false,
              "lastPlaybackProgress": 0,
              "isDynamicReplyButtonsMsg": false,
              "isCarouselCard": false,
              "parentMsgId": null,
              "callSilenceReason": null,
              "isVideoCall": false,
              "callDuration": null,
              "callCreator": null,
              "callParticipants": null,
              "isCallLink": null,
              "callLinkToken": null,
              "isMdHistoryMsg": false,
              "stickerSentTs": 0,
              "lastUpdateFromServerTs": 0,
              "invokedBotWid": null,
              "bizBotType": null,
              "botResponseTargetId": null,
              "botPluginType": null,
              "botPluginReferenceIndex": null,
              "botPluginSearchProvider": null,
              "botPluginSearchUrl": null,
              "botPluginSearchQuery": null,
              "botPluginMaybeParent": false,
              "botReelPluginThumbnailCdnUrl": null,
              "botMessageDisclaimerText": null,
              "botMsgBodyType": null,
              "requiresDirectConnection": false,
              "bizContentPlaceholderType": null,
              "hostedBizEncStateMismatch": false,
              "senderOrRecipientAccountTypeHosted": false,
              "placeholderCreatedWhenAccountIsHosted": false,
              "galaxyFlowDisabled": false,
              "links": []
            },
            "mediaKey": "MEDIA_KEY_PLACEHOLDER",
            "id": {
              "fromMe": true,
              "remote": "000000000000@c.us",
              "id": "MSG_ID_123456",
              "_serialized": "true_000000000000@c.us_MSG_ID_123456"
            },
            "ack": 0,
            "hasMedia": true,
            "body": "Here's your requested image.",
            "type": "image",
            "timestamp": 1759108866,
            "from": "111111111111@c.us",
            "to": "000000000000@c.us",
            "deviceType": "android",
            "isForwarded": false,
            "forwardingScore": 0,
            "isStatus": false,
            "isStarred": false,
            "fromMe": true,
            "hasQuotedMsg": false,
            "hasReaction": false,
            "vCards": [],
            "mentionedIds": [],
            "groupMentions": [],
            "isGif": false,
            "links": []
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Egypt)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Egypt mobile numbers must be 11 digits (national format).",
            "details": {
              "provided": "20114520282",
              "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
              "info": {
                "country": "EG",
                "type": "MOBILE"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Saudi Arabia)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for SA.",
            "details": {
              "provided": "96655555",
              "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
              "info": {
                "country": "SA"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Unknown)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for Unknown.",
            "details": {
              "provided": "01145202826",
              "recommendation": "Ensure individual numbers are in international format (starting with country code).",
              "info": {
                "country": "Unknown"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 429,
          "description": "Too Many Requests - Rate Limit Exceeded",
          "contentType": "application/json",
          "example": {
            "code": "rate_limit_exceeded",
            "message": "Too many requests. Please slow down.",
            "details": {
              "retryAfter": 60,
              "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
              "upstream": {
                "error": "Rate limit",
                "statusCode": 429
              }
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "extraInfo": "# Click-Through Authority: Mastering the Rich Link Preview Engine\n\nIn a vertical feed of text and media, a \"Rich Link Preview\" (`/v2/send/link-preview`) is the most effective way to drive traffic from a WhatsApp chat to an external web property. While standard apps generate previews only when a human slow-types a URL, Wawp allows you to programmatically **force** a high-fidelity preview card. This is essential for professional broadcasts, product links, and personalized landing pages where you want total control over the visual branding and the narrative.\n\n---\n\n## 🏗️ The Link-Card Synthetic Engine\n\nWawp’s link engine doesn't just \"scrape\" the destination; it actively constructs a synthetic OpenGraph card:\n1. **Metadata Override**: Unlike standard link sharing, Wawp allows you to override the `title`, `description`, and `thumbnail` even if the destination website has no metadata or blocked crawlers. This ensures your link always looks professional.\n2. **Binary Fetching**: The engine retrieves your custom `thumbnail` and optimizes it for the WhatsApp mobile app. It supports **JPEG** and **PNG**, ensuring the thumbnail loads instantly even on poor connections.\n3. **The High-Quality Mesh**: Setting `linkPreviewHighQuality: true` triggers a specialized rendering mode. If the recipient's phone supports it, WhatsApp will render a much larger image card (similar to a native image message) instead of the small square icon. This drastically increases the \"Visual Real-Estate\" your message occupies in the user's thread.\n\n---\n\n## 🛡️ Strategic Best Practices for Click-Through Rates (CTR)\n\n### 1. The \"Call-to-Action\" Title\nYour `title` should be a directive, not just a label.\n- **Example**: Instead of \"Our Blog,\" use \"🔥 Read Now: 5 Ways to Scale your API.\"\n- **UX Impact**: High-action titles combined with a high-quality preview card can increase CTR by up to **400%** compared to a raw URL string.\n\n### 2. Thumbnail Composition\nThe thumbnail is the visual anchor of the card.\n- **Ratio**: Use **1:1 (Square)** images for standard previews or **1.91:1 (Wide)** images if you are using the `linkPreviewHighQuality` flag.\n- **Clarity**: Avoid putting small text in the thumbnail. Because thumbnails are compressed and rendered small on mobile screens, use bold icons or clear photography that represents the link's destination.\n\n### 3. URL Transparency and Hygiene\n- **Text Inclusion**: The `text` field allows you to provide a preceding message (e.g., \"Check this out:\"). We recommend including the URL again at the end of the text field as a fallback for the rare cases where a user's phone has preview rendering disabled.\n- **Tracking**: Use UTM parameters in your `url` (e.g., `?utm_source=whatsapp&utm_medium=wawp`). This allows you to measure the exact effectiveness of your API campaigns in your analytics dashboard.\n\n---\n\n## 🧩 Advanced Use Cases\n\n### Dynamic Checkout Previews\nWhen a user adds an item to their cart, send them a link preview of the checkout page. Use a custom `thumbnail` that shows the exact product they are buying. This creates a deeply personalized and trustworthy path to purchase directly within the chat.\n\n### Content Gating and Personalized Reports\nIf you provide personalized PDF reports or secure dashboard links, use the `/v2/send/link-preview` to create a \"Dashboard Card.\" Use the `description` to show a snippet of the user's data (e.g., \"Your Q1 Savings: $1,250\"), encouraging them to click through to the full site for the detailed breakdown.\n\n---\n\n## 🛠️ Common Pitfalls and Solutions\n\n- **Blocked Crawlers**: If you rely on auto-previews (not providing a custom thumbnail), the WhatsApp network may fail to scrape sites behind Cloudflare or login screens. Always provide your own **Custom Thumbnail URL** to ensure 100% reliability.\n- **Image Type Errors**: Using a `thumbnail` URL that points to a WebP or SVG file will often result in a generic \"Link\" icon with no image. Stick to standard **JPEG** for the highest compatibility.\n- **Protocol Requirements**: The `url` and `thumbnail` must both use the **HTTPS** protocol. Unsecured HTTP links will frequently be rejected or show security warnings to the recipient.\n\n---\n\n## Summary of Capabilities:\n- Programmatically force high-fidelity interactive link cards with or without OpenGraph support.\n- Full control over Title, Description, and Thumbnail metadata overrides.\n- \"High Quality\" mode for large-format visual cards with extreme visibility.\n- Seamless conversion from raw URLs to \"App-like\" interactive elements.\n- Integrated threading support via the `reply_to` parameter for contextual sharing.\n- Reliable delivery tracking with integrated `message_id` generation.",
      "translations": {
        "ar": {
          "title": "إرسال رابط معاينة (Link Preview)",
          "description": "إرسال رسالة مع بطاقة معاينة رابط غنية ومخصصة.",
          "tips": [
            {
              "title": "محتوى غني",
              "content": "يولد بطاقة معاينة بالعنوان والوصف والصورة."
            },
            {
              "title": "زمن الوصول",
              "content": "يستغرق إنشاء الرابط وقتًا إضافيًا؛ ترسل الرسالة بشكل أبطأ قليلاً."
            }
          ],
          "recommendations": [
            "تأكد من أن الرابط المستهدف يحتوي على علامات Open Graph (OG) صالحة.",
            "ارجع إلى رسالة نصية قياسية إذا فشل إنشاء المعاينة."
          ],
          "extraInfo": "# سلطة النقر: إتقان محرك معاينة الروابط الغنية\n\nفي المخطط الرأسي للرسائل المليئة بالنصوص والوسائط، تعد \"معاينة الرابط الغنية\" (`/v2/send/link-preview`) الطريقة الأكثر فعالية لتوجيه الزيارات من دردشة واتساب إلى موقع ويب خارجي. بينما تقوم التطبيقات القياسية بإنشاء معاينات فقط عندما يكتب الإنسان يدوياً رابطاً ببطء، يتيح لك Wawp برمجياً **فرض** بطاقة معاينة عالية الدقة. هذا أمر ضروري للإعلانات المهنية، وروابط المنتجات، وصفحات الهبوط المخصصة حيث تريد التحكم الكامل في الهوية البصرية والسرد.\n\n---\n\n## 🏗️ محرك إنشاء بطاقات الروابط\n\nمحرك الروابط في Wawp لا يكتفي \"بكشط\" الوجهة؛ بل يقوم بنشاط بتركيب بطاقة OpenGraph اصطناعية:\n1. **تجاوز البيانات الوصفية**: على عكس مشاركة الروابط العادية، يتيح لك Wawp تجاوز `title` و `description` و `thumbnail` حتى لو لم يكن لموقع الوجهة بيانات وصفية أو كان يحظر برامج الزحف. يضمن ذلك أن يظهر رابطك دائماً باحترافية.\n2. **جلب الصور الثنائية**: يقوم المحرك بجلب صورتك المصغرة المخصصة (`thumbnail`) وتحسينها لتطبيق واتساب للهاتف المحمول. يدعم صيغ **JPEG** و **PNG**، مما يضمن تحميل الصورة المصغرة فوراً حتى في الاتصالات الضعيفة.\n3. **المعاينة عالية الجودة**: يؤدي تفعيل `linkPreviewHighQuality: true` إلى تشغيل وضع عرض متخصص. إذا كان هاتف المستلم يدعم ذلك، فسيقوم واتساب بعرض بطاقة صورة أكبر بكثير (تشبه رسالة صور أصلية) بدلاً من الأيقونة المربعة الصغيرة. هذا يزيد بشكل كبير من \"المساحة البصرية\" التي تشغلها رسالتك في واجهة المستخدم.\n\n---\n\n## 🛡️ أفضل الممارسات الاستراتيجية لمعدلات النقر (CTR)\n\n### 1. العنوان كـ \"توجيه للعمل\"\nيجب أن يكون العنوان (`title`) موجهاً وليس مجرد تسمية.\n- **مثال**: بدلاً من \"مدونتنا\"، استخدم \"🔥 اقرأ الآن: 5 طرق لتوسيع API الخاص بك\".\n- **تأثير تجربة المستخدم**: يمكن للعناوين المليئة بالحركة جنباً إلى جنب مع بطاقة معاينة عالية الجودة زيادة معدل النقر بنسبة تصل إلى **400%** مقارنة برابط نصي خام.\n\n### 2. تكوين الصورة المصغرة\nالصورة المصغرة هي المرساة البصرية للبطاقة.\n- **النسبة**: استخدم صوراً بنسبة **1:1 (مربعة)** للمعاينة القياسية أو **1.91:1 (عريضة)** إذا كنت تستخدم علامة `linkPreviewHighQuality`.\n- **الوضوح**: تجنب وضع نصوص صغيرة في الصورة المصغرة. نظراً لأن الصور المصغرة يتم ضغطها وعرضها بحجم صغير على شاشات الجوال، استخدم أيقونات بارزة أو صوراً واضحة تمثل وجهة الرابط.\n\n### 3. شفافية الروابط ونظافتها\n- **تضمين النص**: يتيح لك حقل `text` تقديم رسالة سابقة (مثلاً \"اطلع على هذا:\"). نوصي بتكرار الرابط في نهاية حقل النص كبديل احتياطي في الحالات النادرة التي يكون فيها جوال المستخدم معطلاً لمعاينة الروابط.\n- **التتبع**: استخدم معلمات UTM في رابطك (`url`) (مثلاً `?utm_source=whatsapp&utm_medium=wawp`). يتيح لك ذلك قياس مدى فعالية حملات API الخاصة بك في لوحة تحليلاتك.\n\n---\n\n## 🧩 حالات استخدام متقدمة\n\n### معاينات الدفع الديناميكية\nعندما يضيف مستخدم عنصراً إلى سلة التسوق الخاصة به، أرسل له معاينة رابط لصفحة الدفع. استخدم صورة مصغرة (`thumbnail`) مخصصة تظهر المنتج الذي يشتريه بالضبط. يخلق هذا مساراً شخصياً وموثوقاً للشراء مباشرة داخل الدردشة.\n\n### تقارير مخصصة ومحتوى محمي\nإذا كنت تقدم تقارير PDF مخصصة أو روابط آمنة للوحة التحكم، استخدم `/v2/send/link-preview` لإنشاء \"بطاقة لوحة تحكم\". استخدم الوصف لإظهار مقتطف من بيانات المستخدم (مثلاً \"توفيراتك للربع الأول: 1,250 دولاراً\")، مما يشجعهم على النقر للوصول للموقع الكامل.\n\n---\n\n## 🛠️ المزالق الشائعة والحلول\n\n- **برامج الزحف المحظورة**: إذا كنت تعتمد على المعاينة التلقائية (عدم توفير صورة مصغرة مخصصة)، فقد تفشل شبكة واتساب في كشط المواقع المحمية بـ Cloudflare أو شاشات تسجيل الدخول. دائماً قدم **رابط صورة مصغرة مخصصة** لضمان موثوقية 100%.\n- **أخطاء نوع الصورة**: استخدام رابط صورة مصغرة يشير لملف WebP أو SVG سيؤدي غالباً لظهور أيقونة \"رابط\" عامة بدون صورة. التزم بصيغة **JPEG** القياسية لأعلى توافق.\n- **متطلبات البروتوكول**: يجب أن يستخدم كل من `url` و `thumbnail` بروتوكول **HTTPS**. الروابط غير الآمنة (HTTP) غالباً ما يتم رفضها أو تظهر تحذيرات أمنية للمستلم.\n\n---\n\n## ملخص الإمكانيات:\n- فرض بطاقات روابط تفاعلية عالية الدقة برمجياً مع أو بدون دعم OpenGraph.\n- تحكم كامل في تجاوز البيانات الوصفية للعنوان والوصف والصورة المصغرة.\n- وضع \"الجودة العالية\" للبطاقات البصرية الكبيرة ذات الوضوح الشديد.\n- تحويل سلس من الروابط الخام إلى عناصر تفاعلية تشبه \"التطبيقات\".\n- دعم متكامل للخيوط عبر معلمة `reply_to` لمشاركة سياقية.\n- تتبع تسليم موثوق مع إنشاء `message_id` متكامل.",
          "args": {
            "instance_id": {
              "description": "المعرف الفريد لجلسة واتساب"
            },
            "access_token": {
              "description": "رمز وصول API الخاص بك"
            },
            "chatId": {
              "description": "رقم الهاتف المستهدف مع كود الدولة"
            },
            "url": {
              "description": "الرابط المراد معاينته"
            },
            "text": {
              "description": "نص اختياري مرافق للرابط."
            },
            "thumbnail": {
              "description": "رابط لصورة مصغرة مخصصة (JPEG/PNG)"
            },
            "title": {
              "description": "عنوان مخصص لبطاقة المعاينة"
            },
            "description": {
              "description": "وصف مخصص لبطاقة المعاينة"
            },
            "linkPreviewHighQuality": {
              "description": "محاولة إنشاء معاينة كبيرة عالية الجودة"
            },
            "reply_to": {
              "description": "معرف الرسالة التي تقوم بالرد عليها"
            }
          }
        }
      },
      "tips": [
        {
          "type": "positive",
          "title": "Marketing Power",
          "content": "Use custom titles and descriptions to create compelling Call-to-Actions (CTAs) that standard links cannot provide."
        },
        {
          "type": "info",
          "title": "High Quality Flag",
          "content": "The `linkPreviewHighQuality` flag attempts to render a larger image card, which takes more visual space in the chat."
        }
      ]
    },
    {
      "path": "/v2/send/location",
      "methods": [
        "POST",
        "GET"
      ],
      "title": "Send Location",
      "category": "Send Messages",
      "description": "Send a static geographic location to a chat.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Unique ID of the WhatsApp session",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API access token",
          "example": "123456789"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Recipient's WhatsApp number",
          "example": "447441429009"
        },
        "latitude": {
          "required": true,
          "type": "string",
          "description": "Geographic latitude (e.g. 38.8937255)",
          "example": "38.8937255"
        },
        "longitude": {
          "required": true,
          "type": "string",
          "description": "Geographic longitude (e.g. -77.0969763)",
          "example": "-77.0969763"
        },
        "title": {
          "required": true,
          "type": "string",
          "description": "Name of the place (e.g., 'Our Office')",
          "example": "Our office"
        },
        "message": {
          "required": true,
          "type": "string",
          "description": "Address or additional description text",
          "example": "123 Main St, New York"
        },
        "reply_to": {
          "required": false,
          "type": "string",
          "description": "Message ID to reply to",
          "example": "null"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Message Sent Successfully",
          "contentType": "application/json",
          "example": {
            "_data": {
              "id": {
                "fromMe": true,
                "remote": "000000000000@c.us",
                "id": "MSG_ID_123456",
                "_serialized": "true_000000000000@c.us_MSG_ID_123456"
              },
              "viewed": false,
              "body": "BASE64_IMAGE_DATA",
              "type": "image",
              "t": 1759108866,
              "from": {
                "server": "c.us",
                "user": "111111111111",
                "_serialized": "111111111111@c.us"
              },
              "to": {
                "server": "c.us",
                "user": "000000000000",
                "_serialized": "000000000000@c.us"
              },
              "ack": 0,
              "isNewMsg": true,
              "star": false,
              "kicNotified": false,
              "caption": "Here's your requested image.",
              "deprecatedMms3Url": "https://example.com/media-url",
              "directPath": "/media/direct/path/example",
              "mimetype": "image/jpeg",
              "filehash": "FILE_HASH_PLACEHOLDER",
              "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
              "size": 192487,
              "mediaKey": "MEDIA_KEY_PLACEHOLDER",
              "mediaKeyTimestamp": 1759108865,
              "streamable": false,
              "mediaHandle": null,
              "isFromTemplate": false,
              "pollInvalidated": false,
              "isSentCagPollCreation": false,
              "latestEditMsgKey": null,
              "latestEditSenderTimestampMs": null,
              "mentionedJidList": [],
              "groupMentions": [],
              "isEventCanceled": false,
              "eventInvalidated": false,
              "isVcardOverMmsDocument": false,
              "isForwarded": false,
              "isQuestion": false,
              "questionReplyQuotedMessage": null,
              "questionResponsesCount": 0,
              "readQuestionResponsesCount": 0,
              "labels": [],
              "hasReaction": false,
              "disappearingModeInitiator": "chat",
              "disappearingModeTrigger": "chat_settings",
              "productHeaderImageRejected": false,
              "lastPlaybackProgress": 0,
              "isDynamicReplyButtonsMsg": false,
              "isCarouselCard": false,
              "parentMsgId": null,
              "callSilenceReason": null,
              "isVideoCall": false,
              "callDuration": null,
              "callCreator": null,
              "callParticipants": null,
              "isCallLink": null,
              "callLinkToken": null,
              "isMdHistoryMsg": false,
              "stickerSentTs": 0,
              "lastUpdateFromServerTs": 0,
              "invokedBotWid": null,
              "bizBotType": null,
              "botResponseTargetId": null,
              "botPluginType": null,
              "botPluginReferenceIndex": null,
              "botPluginSearchProvider": null,
              "botPluginSearchUrl": null,
              "botPluginSearchQuery": null,
              "botPluginMaybeParent": false,
              "botReelPluginThumbnailCdnUrl": null,
              "botMessageDisclaimerText": null,
              "botMsgBodyType": null,
              "requiresDirectConnection": false,
              "bizContentPlaceholderType": null,
              "hostedBizEncStateMismatch": false,
              "senderOrRecipientAccountTypeHosted": false,
              "placeholderCreatedWhenAccountIsHosted": false,
              "galaxyFlowDisabled": false,
              "links": []
            },
            "mediaKey": "MEDIA_KEY_PLACEHOLDER",
            "id": {
              "fromMe": true,
              "remote": "000000000000@c.us",
              "id": "MSG_ID_123456",
              "_serialized": "true_000000000000@c.us_MSG_ID_123456"
            },
            "ack": 0,
            "hasMedia": true,
            "body": "Here's your requested image.",
            "type": "image",
            "timestamp": 1759108866,
            "from": "111111111111@c.us",
            "to": "000000000000@c.us",
            "deviceType": "android",
            "isForwarded": false,
            "forwardingScore": 0,
            "isStatus": false,
            "isStarred": false,
            "fromMe": true,
            "hasQuotedMsg": false,
            "hasReaction": false,
            "vCards": [],
            "mentionedIds": [],
            "groupMentions": [],
            "isGif": false,
            "links": []
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Egypt)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Egypt mobile numbers must be 11 digits (national format).",
            "details": {
              "provided": "20114520282",
              "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
              "info": {
                "country": "EG",
                "type": "MOBILE"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Saudi Arabia)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for SA.",
            "details": {
              "provided": "96655555",
              "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
              "info": {
                "country": "SA"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Unknown)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for Unknown.",
            "details": {
              "provided": "01145202826",
              "recommendation": "Ensure individual numbers are in international format (starting with country code).",
              "info": {
                "country": "Unknown"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 429,
          "description": "Too Many Requests - Rate Limit Exceeded",
          "contentType": "application/json",
          "example": {
            "code": "rate_limit_exceeded",
            "message": "Too many requests. Please slow down.",
            "details": {
              "retryAfter": 60,
              "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
              "upstream": {
                "error": "Rate limit",
                "statusCode": 429
              }
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "extraInfo": "\n# Precision Positioning: Mastering the Geographic Location Engine\n\nLocation sharing is a powerful tool for bridging the gap between the digital conversation and the physical world. Whether you are helping a customer find a brick-and-mortar store, directing a delivery rider to a precise drop-off point, or organizing a physical meetup, the `/v2/send/location` endpoint provides a reliable way to send interactive map pins directly into a WhatsApp chat. \n\n---\n\n## 🏗️ The Geolocation Pipeline: From Data to Pin\n\nWhen you call the `/send/location` endpoint, Wawp’s engine translates raw geographic data into a rich, interactive bubble on the recipient's phone:\n1. **Coordinate Verification**: The engine accepts `latitude` and `longitude` as decimal strings. It validates that these coordinates fall within the valid ranges (-90 to 90 for latitude, -180 to 180 for longitude).\n2. **Metadata Injection**: The `title` and `message` fields are injected into the message's metadata. These don't just appear on the bubble; they are often used as the \"Label\" when the user clicks the pin and opens it in external apps like Google Maps or Waze.\n3. **Interactive Rendering**: Wawp ensures the resulting message is rendered with a clickable map thumbnail. This thumbnail is generated by the WhatsApp network based on the coordinates provided, giving the user an instant visual \"Context\" of the surrounding area.\n\n---\n\n## 🛡️ Strategic Best Practices for Geographic Data\n\n### 1. Decimal Precision (The Roof-Top Rule)\nFor location data, precision is everything. \n- **Developer Action**: Use at least **6 decimal places** for your coordinates (e.g., `38.893725`). This level of precision is accurate to approximately 0.1 meters—the difference between a pin landing on a building's roof and landing in the middle of a busy intersection.\n- **Safety**: Avoid rounding coordinates in your backend, as even slight changes in the 4th decimal place can shift a location by dozens of meters.\n\n### 2. Crafting Meaningful Labels\nThe `title` and `message` fields are your chance to provide brand clarity.\n- **Title (Place Name)**: Use the name of the destination (e.g., \"Grand Plaza Hotel - Main Entrance\"). \n- **Message (Context/Address)**: Use this for the specific address or helpful hints (e.g., \"1st Floor, next to the fountain\"). \n- **UX Impact**: High-quality labels reduce user anxiety and make the automated message feel deliberate and professional.\n\n### 3. Static vs. Dynamic Locations\n- **Static Pins**: This endpoint sends a **Static Pin**. It represents a specific \"Snapshot\" in space. \n- **Live Location**: Note that Wawp currently focuses on static pins for high-concurrency business flows. If your use case requires a real-time moving dot (Live Location), we recommend combining static pins with regular text updates or external tracking links via [`/v2/send/link-preview`](/v2/send/link-preview).\n\n---\n\n## 🧩 Advanced Use Cases\n\n### Last-Mile Delivery Support\nIn a delivery app, as soon as the rider clicks \"Arrived,\" your system can automatically send the exact location pin to the customer. This enables the customer to open the pin in their preferred navigation app to cross-verify the rider's position, drastically reducing support calls.\n\n### Geo-Fenced Personalized Offers\nIf your system detects a user is near a specific retail branch, you can trigger an automated \"Welcome\" message that includes the location pin for that exact branch. Using the `reply_to` parameter, you can link this location to a specific discount coupon message, creating a highly relevant \"Online-to-Offline\" funnel.\n\n---\n\n## 🛠️ Common Pitfalls and Solutions\n\n- **Swapped Coordinates**: Mixing up latitude and longitude is a common developer error that results in pins landing in the middle of the ocean. Always double-check your coordinate pairs.\n- **Blank Labels**: Sending a location with an empty `title` often results in a generic \"Location\" bubble. To maintain brand authority, always provide a descriptive title.\n- **Coordinate Strings**: Ensure you send the coordinates as strings through the API to prevent floating-point precision loss that sometimes occurs with JSON number types at high decimal counts.\n\n---\n\n## Summary of Capabilities:\n- Send interactive, clickable static map pins with custom titles and addresses.\n- High-precision support for decimal coordinates (latitude/longitude).\n- Seamless integration with Google Maps, Apple Maps, and Waze for the end-user.\n- Support for complex thread-nesting via the `reply_to` parameter.\n- Reliable success reporting with unique `message_id` generation for full delivery tracking.\n",
      "image": "https://api.apidog.com/api/v1/projects/1017306/resources/369237/image-preview",
      "tips": [
        {
          "type": "positive",
          "title": "Exact Coordinates",
          "content": "Always Use GPS-accurate decimal coordinates. Avoid rounding to ensure the pin lands exactly on the right roof."
        },
        {
          "type": "info",
          "title": "Apple/Google Maps",
          "content": "The \"title\" and \"message\" fields often appear as the label in the recipient's map app."
        }
      ],
      "recommendations": [
        "Use \"reply_to\" to maintain conversation context.",
        "Handle distinct message types (text, image, video) appropriately.",
        "Implement a robust retry mechanism for failed sends."
      ],
      "translations": {
        "ar": {
          "title": "إرسال الموقع",
          "description": "إرسال موقع جغرافي ثابت إلى الدردشة.",
          "recommendations": [
            "أضف تأخيرات عشوائية بين الرسائل لمحاكاة السلوك البشري.",
            "تحقق من أرقام الهواتف قبل الإرسال لضمان التسليم."
          ],
          "extraInfo": "\n# تحديد المواقع بدقة: إتقان محرك الموقع الجغرافي\n\nتعد مشاركة الموقع أداة قوية لسد الفجوة بين المحادثة الرقمية والعالم المادي. سواء كنت تساعد عميلًا في العثور على متجر واقعي، أو توجه سائق توصيل إلى نقطة تسليم دقيقة، أو تنظم تجمعًا ماديًا، فإن نقطة نهاية `/v2/send/location` توفر طريقة موثوقة لإرسال دبابيس خريطة تفاعلية مباشرة إلى دردشة واتساب.\n\n---\n\n## 🏗️ مسار الموقع الجغرافي: من البيانات إلى الدبوس\n\nعندما تستدعي نقطة النهاية `/send/location`، يقوم محرك Wawp بترجمة البيانات الجغرافية الخام إلى فقاعة تفاعلية غنية على هاتف المستلم:\n1. **التحقق من الإحداثيات**: يقبل المحرك خطوط العرض (`latitude`) وخطوط الطول (`longitude`) كسلاسل عشرية. ويتحقق من وقوع هذه الإحداثيات ضمن النطاقات الصالحة (-90 إلى 90 لخط العرض، و-180 إلى 180 لخط الطول).\n2. **حقن البيانات الوصفية**: يتم حقن حقلي `title` (العنوان) و `message` (الرسالة/العنوان المفصل) في البيانات الوصفية للرسالة. لا تظهر هذه الحقول على الفقاعة فحسب؛ بل تُستخدم غالبًا كـ \"تسمية\" عندما ينقر المستخدم على الدبوس ويفتحه في تطبيقات خارجية مثل خرائط جوجل أو Waze.\n3. **العرض التفاعلي**: يضمن Wawp عرض الرسالة الناتجة مع صورة مصغرة لخريطة قابلة للنقر. يتم إنشاء هذه الصورة المصغرة بواسطة شبكة واتساب بناءً على الإحداثيات المقدمة، مما يمنح المستخدم \"سياقًا\" بصريًا فوريًا للمنطقة المحيطة.\n\n---\n\n## 🛡️ أفضل الممارسات الاستراتيجية للبيانات الجغرافية\n\n### 1. الدقة العشرية (قاعدة \"سقف المبنى\")\nفي بيانات الموقع، الدقة هي كل شيء.\n- **إجراء المطور**: استخدم **6 منازل عشرية** على الأقل لإحداثياتك (مثل `38.893725`). هذا المستوى من الدقة دقيق بما يصل إلى 0.1 متر تقريبًا - وهو الفرق بين سقوط الدبوس على سطح مبنى أو سقوطه في منتصف تقاطع مزدحم.\n- **الأمان**: تجنب تقريب الإحداثيات في خلفية تطبيقك، حيث أن التغييرات الطفيفة حتى في المنزلة العشرية الرابعة يمكن أن تزيح الموقع بعشرات الأمتار.\n\n### 2. صياغة تسميات ذات معنى\nحقلا `title` و `message` هما فرصتك لتوفير وضوح لهوية علامتك التجارية.\n- **العنوان (اسم المكان)**: استخدم اسم الوجهة (مثل \"فندق جراند بلازا - المدخل الرئيسي\").\n- **الرسالة (السياق/العنوان)**: استخدم هذا للعنوان المحدد أو التلميحات المفيدة (مثل \"الطابق الأول، بجوار النافورة\").\n- **تأثير تجربة المستخدم**: تقلل التسميات عالية الجودة من قلق المستخدم وتجعل الرسالة المؤتمتة تبدو مدروسة واحترافية.\n\n### 3. المواقع الثابتة مقابل الحية\n- **الدبابيس الثابتة**: ترسل نقطة النهاية هذه **دبوسًا ثابتًا**. إنه يمثل \"لقطة\" محددة في المكان.\n- **الموقع الحي (Live Location)**: لاحظ أن Wawp يركز حاليًا على الدبابيس الثابتة لتدفقات الأعمال عالية التزامن. إذا كانت حالة الاستخدام الخاصة بك تتطلب نقطة متحركة في الوقت الفعلي (الموقع الحي)، نوصي بدمج الدبابيس الثابتة مع تحديثات نصية منتظمة أو روابط تتبع خارجية عبر [`/v2/send/link-preview`](/v2/send/link-preview).\n\n---\n\n## 🧩 حالات استخدام متقدمة\n\n### دعم توصيل الميل الأخير\nفي تطبيق التوصيل، بمجرد أن ينقر السائق على \"وصلت\"، يمكن لنظامك إرسال دبوس الموقع الدقيق تلقائيًا إلى العميل. يتيح ذلك للعميل فتح الدبوس في تطبيق التنقّل المفضل لديه للتحقق من موقع السائق، مما يقلل بشكل كبير من مكالمات الدعم.\n\n### العروض الشخصية المعتمدة على الموقع (Geo-Fencing)\nإذا اكتشف نظامك أن مستخدمًا بالقرب من فرع تجزئة معين، يمكنك إرسال رسالة \"ترحيب\" مؤتمتة تتضمن دبوس الموقع لهذا الفرع بالضبط. باستخدام معلمة `reply_to`، يمكنك ربط هذا الموقع برسالة كوبون خصم محددة، مما يخلق مسار مبيعات فعالاً من \"الإنترنت إلى الواقع\".\n\n---\n\n## 🛠️ المزالق الشائعة والحلول\n\n- **تبديل الإحداثيات**: يعد الخلط بين خطوط العرض وخطوط الطول خطأً فنيًا شائعًا يؤدي إلى سقوط الدبابيس في وسط المحيط. تحقق دائمًا من أزواج إحداثياتك.\n- **التسميات الفارغة**: يؤدي إرسال موقع بعنوان `title` فارغ غالبًا إلى فقاعة \"موقع\" عامة. للحفاظ على سلطة علامتك التجارية، قدم دائمًا عنوانًا وصفيًا.\n- **سلاسل الإحداثيات**: تأكد من إرسال الإحداثيات كسلاسل (Strings) عبر API لمنع فقدان دقة الفاصلة العائمة الذي يحدث أحيانًا مع أنواع أرقام JSON عند عدد كبير من المنازل العشرية.\n\n---\n\n## ملخص الإمكانيات:\n- إرسال دبابيس خريطة ثابتة تفاعلية وقابلة للنقر مع عناوين وأسماء مخصصة.\n- دعم عالي الدقة للإحداثيات العشرية (خط العرض/خط الطول).\n- تكامل سلس مع خرائط جوجل، وخرائط آبل، و Waze للمستخدم النهائي.\n- دعم لتداخل الخيوط المعقدة عبر معلمة `reply_to`.\n- تقارير نجاح موثوقة مع توليد معرف `message_id` فريد لتتبع التسليم الكامل.\n",
          "args": {
            "instance_id": {
              "description": "المعرف الفريد لجلسة واتساب"
            },
            "access_token": {
              "description": "رمز وصول API"
            },
            "chatId": {
              "description": "رقم واتساب للمستلم"
            },
            "latitude": {
              "description": "خط العرض الجغرافي (مثل 38.8937255)"
            },
            "longitude": {
              "description": "خط الطول الجغرافي (مثل -77.0969763)"
            },
            "title": {
              "description": "اسم المكان (مثل 'مكتبنا الرئيسي')"
            },
            "message": {
              "description": "العنوان أو نص وصفي إضافي"
            },
            "reply_to": {
              "description": "معرف الرسالة التي تقوم بالرد عليها"
            }
          },
          "tips": [
            {
              "title": "إحداثيات دقيقة",
              "content": "استخدم دائمًا إحداثيات عشرية دقيقة بنظام GPS. تجنب التقريب لضمان سقوط الدبوس بالضبط على الموقع الصحيح."
            },
            {
              "title": "خرائط آبل/جوجل",
              "content": "غالبًا ما تظهر حقول 'العنوان' و 'الرسالة' كالتسمية في تطبيق الخرائط الخاص بالمستلم."
            }
          ]
        }
      }
    },
    {
      "path": "/v2/send/poll",
      "methods": [
        "POST"
      ],
      "title": "Send Poll",
      "category": "Send Messages",
      "description": "Send an interactive poll with multiple options.",
      "modifiedAt": "Just now",
      "bodyEditor": true,
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Target phone number or group ID",
          "example": "447441429009@c.us"
        },
        "poll": {
          "required": true,
          "type": "object",
          "description": "The poll structure containing name and options.",
          "example": "{\n  \"name\": \"How are you?\",\n  \"options\": [\n    \"Awesome!\",\n    \"Good!\",\n    \"Not bad!\"\n  ],\n  \"multipleAnswers\": true\n}"
        },
        "reply_to": {
          "required": false,
          "type": "string",
          "description": "Message ID to reply to",
          "example": "null"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Message Sent Successfully",
          "contentType": "application/json",
          "example": {
            "_data": {
              "id": {
                "fromMe": true,
                "remote": "000000000000@c.us",
                "id": "MSG_ID_123456",
                "_serialized": "true_000000000000@c.us_MSG_ID_123456"
              },
              "viewed": false,
              "body": "BASE64_IMAGE_DATA",
              "type": "image",
              "t": 1759108866,
              "from": {
                "server": "c.us",
                "user": "111111111111",
                "_serialized": "111111111111@c.us"
              },
              "to": {
                "server": "c.us",
                "user": "000000000000",
                "_serialized": "000000000000@c.us"
              },
              "ack": 0,
              "isNewMsg": true,
              "star": false,
              "kicNotified": false,
              "caption": "Here's your requested image.",
              "deprecatedMms3Url": "https://example.com/media-url",
              "directPath": "/media/direct/path/example",
              "mimetype": "image/jpeg",
              "filehash": "FILE_HASH_PLACEHOLDER",
              "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
              "size": 192487,
              "mediaKey": "MEDIA_KEY_PLACEHOLDER",
              "mediaKeyTimestamp": 1759108865,
              "streamable": false,
              "mediaHandle": null,
              "isFromTemplate": false,
              "pollInvalidated": false,
              "isSentCagPollCreation": false,
              "latestEditMsgKey": null,
              "latestEditSenderTimestampMs": null,
              "mentionedJidList": [],
              "groupMentions": [],
              "isEventCanceled": false,
              "eventInvalidated": false,
              "isVcardOverMmsDocument": false,
              "isForwarded": false,
              "isQuestion": false,
              "questionReplyQuotedMessage": null,
              "questionResponsesCount": 0,
              "readQuestionResponsesCount": 0,
              "labels": [],
              "hasReaction": false,
              "disappearingModeInitiator": "chat",
              "disappearingModeTrigger": "chat_settings",
              "productHeaderImageRejected": false,
              "lastPlaybackProgress": 0,
              "isDynamicReplyButtonsMsg": false,
              "isCarouselCard": false,
              "parentMsgId": null,
              "callSilenceReason": null,
              "isVideoCall": false,
              "callDuration": null,
              "callCreator": null,
              "callParticipants": null,
              "isCallLink": null,
              "callLinkToken": null,
              "isMdHistoryMsg": false,
              "stickerSentTs": 0,
              "lastUpdateFromServerTs": 0,
              "invokedBotWid": null,
              "bizBotType": null,
              "botResponseTargetId": null,
              "botPluginType": null,
              "botPluginReferenceIndex": null,
              "botPluginSearchProvider": null,
              "botPluginSearchUrl": null,
              "botPluginSearchQuery": null,
              "botPluginMaybeParent": false,
              "botReelPluginThumbnailCdnUrl": null,
              "botMessageDisclaimerText": null,
              "botMsgBodyType": null,
              "requiresDirectConnection": false,
              "bizContentPlaceholderType": null,
              "hostedBizEncStateMismatch": false,
              "senderOrRecipientAccountTypeHosted": false,
              "placeholderCreatedWhenAccountIsHosted": false,
              "galaxyFlowDisabled": false,
              "links": []
            },
            "mediaKey": "MEDIA_KEY_PLACEHOLDER",
            "id": {
              "fromMe": true,
              "remote": "000000000000@c.us",
              "id": "MSG_ID_123456",
              "_serialized": "true_000000000000@c.us_MSG_ID_123456"
            },
            "ack": 0,
            "hasMedia": true,
            "body": "Here's your requested image.",
            "type": "image",
            "timestamp": 1759108866,
            "from": "111111111111@c.us",
            "to": "000000000000@c.us",
            "deviceType": "android",
            "isForwarded": false,
            "forwardingScore": 0,
            "isStatus": false,
            "isStarred": false,
            "fromMe": true,
            "hasQuotedMsg": false,
            "hasReaction": false,
            "vCards": [],
            "mentionedIds": [],
            "groupMentions": [],
            "isGif": false,
            "links": []
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Egypt)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Egypt mobile numbers must be 11 digits (national format).",
            "details": {
              "provided": "20114520282",
              "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
              "info": {
                "country": "EG",
                "type": "MOBILE"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Saudi Arabia)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for SA.",
            "details": {
              "provided": "96655555",
              "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
              "info": {
                "country": "SA"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Unknown)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for Unknown.",
            "details": {
              "provided": "01145202826",
              "recommendation": "Ensure individual numbers are in international format (starting with country code).",
              "info": {
                "country": "Unknown"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 429,
          "description": "Too Many Requests - Rate Limit Exceeded",
          "contentType": "application/json",
          "example": {
            "code": "rate_limit_exceeded",
            "message": "Too many requests. Please slow down.",
            "details": {
              "retryAfter": 60,
              "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
              "upstream": {
                "error": "Rate limit",
                "statusCode": 429
              }
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "extraInfo": "\n# Democracy in Chat: Mastering the Interactive Poll Engine\n\nPolls (`/v2/send/poll`) are the gold standard for gathering structured feedback in a conversational environment. They eliminate the \"Decision Fatigue\" associated with typing out text responses and provide a clean, visual way for users to express preferences. In a Wawp-powered application, polls act as interactive data entry points that can trigger complex backend workflows based on user selection.\n\n---\n\n## 🏗️ The Multi-Option Synchronization Pipeline\n\nWhen you call the `/send/poll` endpoint, Wawp initiates a specialized synchronization flow:\n1. **Schema Validation**: The engine verifies that your `options` array contains at least two choices and does not exceed the WhatsApp maximum of **12 options**. It also ensures each option string is under 255 characters.\n2. **Metadata Consistency**: The `name` (your question) and `options` are serialized into a native WhatsApp Poll packet. Wawp maintains a mapping between these string options and their internal index IDs, ensuring that when a user votes, you get a clean, predictable value in your Webhook.\n3. **The MultipleAnswers Logic**: Setting `multipleAnswers: true` instructs the WhatsApp network to render checkboxes instead of radio buttons. This changes the fundamental nature of the engagement from a \"Choice\" to a \"Survey,\" allowing for more complex data collection.\n\n---\n\n## 🛡️ Strategic Best Practices for Feedback Engagement\n\n### 1. The \"Power of Five\" Rule\nWhile you *can* send 12 options, research indicates that conversion drops significantly after five.\n- **UX Impact**: On mobile screens, long polls require scrolling, which leads to user abandonment. Keep your most important choices in the top three slots.\n- **Clarity**: Use emojis in your option strings (e.g., \"✅ Yes,\" \"❌ No\") to provide immediate visual cues that transcend language barriers.\n\n### 2. High-Fidelity Vote Tracking\nA poll is only as good as the data it produces.\n- **Monitoring**: Always use **Webhooks** (`poll.vote`) to capture user interaction. When a user changes their vote, WhatsApp sends a new event. Your backend should be idempotent, updating the user's choice based on the latest `poll_vote` timestamp.\n- **De-duplication**: In `multipleAnswers` mode, remember to handle arrays of choices. Every time a user checks or unchecks a box, a new event is triggered reflecting the *entire current state* of that user's selections.\n\n### 3. Contextual Follow-ups\nDon't let a vote be the end of the conversation.\n- **Workflow**: When your webhook receives a vote for Option A, have your system automatically trigger a [`/v2/send/text`](/v2/send/text) or [`/v2/send/image`](/v2/send/image) that specifically addresses that choice. This \"Decision-Tree\" automation makes the bot feel intelligent and responsive.\n\n---\n\n## 🧩 Advanced Use Cases\n\n### Real-Time Event Scheduling\nSend a poll with time slots for a meeting: \"When are you free? 1) 10 AM, 2) 2 PM, 3) 4 PM.\" As users vote, your system can see which slot has the most votes in real-time and send a confirmation once a consensus is reached.\n\n### Customer Satisfaction (CSAT) Surveys\nInstead of asking \"Rate us 1 to 5,\" send a poll with descriptive stars or labels: \"⭐ Poor\" to \"⭐⭐⭐⭐⭐ Excellent.\" The visual feedback of the \"Voted\" indicator on the user's screen provides a sense of closure that a text-based reply cannot match.\n\n---\n\n## 🛠️ Common Pitfalls and Solutions\n\n- **Duplicate Options**: Sending a poll with two identical option strings will cause the WhatsApp network to reject the message. Always ensure your options are unique in your backend logic.\n- **The \"Lost Vote\" Trap**: Unlike text messages, votes are binary updates. If a user votes while your webhook server is down, you may miss the event. We recommend using our **Polling Logs** or a robust message queue to process delayed webhook deliveries.\n- **Question Length**: A question that is too long can be truncated on the chat preview. Keep your `name` concise and put the detailed context in a preceding text message.\n\n---\n\n## Summary of Capabilities:\n- Deliver native, interactive WhatsApp polls with up to 12 custom options.\n- Support for Single-Choice (Radio) and Multi-Choice (Checkbox) modes.\n- Real-time vote tracking via consistent `poll_vote` Webhook events.\n- Advanced threading support using the `reply_to` parameter.\n- High-fidelity synchronization between poll question and selectable choice indices.\n",
      "tips": [
        {
          "type": "positive",
          "title": "Engagement Booster",
          "content": "Polls have the highest response rate for customer feedback surveys."
        },
        {
          "type": "warning",
          "title": "Option Limit",
          "content": "Keep options under 5 for the best mobile experience. Too many choices can lead to \"decision fatigue\"."
        }
      ],
      "recommendations": [
        "Use \"reply_to\" to maintain conversation context.",
        "Handle distinct message types (text, image, video) appropriately.",
        "Implement a robust retry mechanism for failed sends."
      ],
      "translations": {
        "ar": {
          "title": "إرسال استطلاع رأي (Poll)",
          "description": "إرسال استطلاع رأي تفاعلي بخيارات متعددة.",
          "recommendations": [
            "أضف تأخيرات عشوائية بين الرسائل لمحاكاة السلوك البشري.",
            "تحقق من أرقام الهواتف قبل الإرسال لضمان التسليم."
          ],
          "extraInfo": "\n# الديمقراطية في الدردشة: إتقان محرك استطلاعات الرأي التفاعلية\n\nتعد استطلاعات الرأي (`/v2/send/poll`) المعيار الذهبي لجمع الملاحظات المنظمة في بيئة حوارية. فهي تقضي على \"إجهاد اتخاذ القرار\" المرتبط بكتابة الردود النصية وتوفر طريقة مرئية نظيفة للمستخدمين للتعبير عن تفضيلاتهم. في تطبيقات Wawp، تعمل استطلاعات الرأي كنقاط إدخال بيانات تفاعلية يمكنها إطلاق سير عمل خلفي معقد بناءً على اختيار المستخدم.\n\n---\n\n## 🏗️ مسار مزامنة الخيارات المتعددة\n\nعندما تستدعي نقطة النهاية `/send/poll`، يبدأ Wawp تدفق مزامنة متخصص:\n1. **التحقق من المخطط (Schema)**: يتحقق المحرك من أن مصفوفة الخيارات (`options`) تحتوي على خيارين على الأقل ولا تتجاوز الحد الأقصى لواتساب وهو **12 خياراً**. كما يضمن أن طول كل خيار أقل من 255 حرفاً.\n2. **اتساق البيانات الوصفية**: يتم تسلسل `name` (سؤالك) و `options` في حزمة استطلاع واتساب أصلية. يحافظ Wawp على تعيين بين خيارات النصوص هذه ومعرفات فهرسها الداخلية، مما يضمن أنه عندما يصوت المستخدم، تحصل على قيمة نظيفة ويمكن التنبؤ بها في Webhook الخاص بك.\n3. **منطق الإجابات المتعددة (MultipleAnswers)**: يؤدي تعيين `multipleAnswers: true` إلى توجيه شبكة واتساب لعرض مربعات اختيار (Checkboxes) بدلاً من أزرار الاختيار (Radio buttons). هذا يغير طبيعة التفاعل من \"اختيار واحد\" إلى \"استطلاع رأي متكامل\"، مما يسمح بجمع بيانات أكثر تعقيداً.\n\n---\n\n## 🛡️ أفضل الممارسات الاستراتيجية للتفاعل مع الملاحظات\n\n### 1. قاعدة \"قوة الخمسة\"\nبينما يمكنك إرسال 12 خياراً، تشير الأبحاث إلى أن معدل التحويل ينخفض بشكل ملحوظ بعد الخيار الخامس.\n- **تأثير تجربة المستخدم**: على شاشات الجوال، تتطلب استطلاعات الرأي الطويلة التمرير، مما يؤدي إلى تخلي المستخدمين عنها. ابقِ خياراتك الأكثر أهمية في المراكز الثلاثة الأولى.\n- **الوضوح**: استخدم الرموز التعبيرية في نصوص الخيارات (مثل \"✅ نعم\"، \"❌ لا\") لتوفير إشارات مرئية فورية تتجاوز حواجز اللغة.\n\n### 2. تتبع التصويت بدقة عالية\nقيمة استطلاع الرأي تكمن في البيانات التي ينتجها.\n- **المراقبة**: استخدم دائماً **Webhooks** (`poll.vote`) لالتقاط تفاعل المستخدم. عندما يغير المستخدم تصويته، يرسل واتساب حدثاً جديداً. يجب أن يكون نظامك الخلفي قادراً على التعامل مع التكرار، وتحديث اختيار المستخدم بناءً على أحدث طابع زمني لـ `poll_vote`.\n- **التعامل مع الإجابات المتعددة**: في وضع `multipleAnswers`، تذكر معالجة مصفوفات الخيارات. في كل مرة يقوم فيها المستخدم بتحديد أو إلغاء تحديد مربع، يتم إطلاق حدث جديد يعكس *الحالة الحالية الكاملة* لاختيارات ذلك المستخدم.\n\n### 3. المتابعات السياقية\nلا تجعل التصويت نهاية المحادثة.\n- **سير العمل**: عندما يتلقى مشروع الـ Webhook الخاص بك تصويتاً للخيار (أ)، اجعل نظامك يطلق تلقائياً رسالة نصية عبر [`/v2/send/text`](/v2/send/text) أو صورة عبر [`/v2/send/image`](/v2/send/image) تتناول هذا الاختيار تحديداً. هذا النوع من \"شجرة القرار\" المؤتمتة يجعل البوت يبدو ذكياً ومتجاوباً.\n\n---\n\n## 🧩 حالات استخدام متقدمة\n\n### جدولة الأحداث في الوقت الفعلي\nأرسل استطلاعاً بفتحات زمنية لاجتماع: \"متى وقتكم المفضل؟ 1) 10 صباحاً، 2) 2 ظهراً، 3) 4 عصراً\". مع تصويت المستخدمين، يمكن لنظامك رؤية الفتحة التي حصلت على أكبر عدد من الأصوات في الوقت الفعلي وإرسال تأكيد بمجرد التوصل إلى إجماع.\n\n### استطلاعات رضا العملاء (CSAT)\nبدلاً من السؤال \"قيمنا من 1 إلى 5\"، أرسل استطلاعاً برؤوس وصفية أو نجوم: \"⭐ ضعيف\" إلى \"⭐⭐⭐⭐⭐ ممتاز\". توفر الملاحظات المرئية لمؤشر \"تم التصويت\" على شاشة المستخدم شعوراً بالإغلاق لا يمكن للرد النصي مضاهاته.\n\n---\n\n## 🛠️ المزالق الشائعة والحلول\n\n- **خيار مكرر**: إرسال استطلاع رأي بخيارين متطابقين سيؤدي لرفض الرسالة من قبل شبكة واتساب. تأكد دائماً من فرادة خياراتك في منطق نظامك الخلفي.\n- **فخ \"التصويت المفقود\"**: على عكس الرسائل النصية، التصويتات هي تحديثات ثنائية. إذا قام المستخدم بالتصويت بينما كان خادم الـ Webhook الخاص بك معطلاً، فقد تفقد الحدث. نوصي باستخدام **سجلات استطلاعات الرأي** الخاصة بنا أو طابور رسائل قوي لمعالجة عمليات تسليم الـ Webhook المتأخرة.\n- **طول السؤال**: قد يتم اقتطاع السؤال الطويل جداً في معاينة الدردشة. ابقِ `name` موجزاً وضع السياق التفصيلي في رسالة نصية سابقة.\n\n---\n\n## ملخص الإمكانيات:\n- تقديم استطلاعات رأي واتساب أصلية وتفاعلية مع ما يصل إلى 12 خياراً مخصصاً.\n- دعم وضع الخيار الواحد (راديو) والخيارات المتعددة (مربعات اختيار).\n- تتبع التصويت في الوقت الفعلي عبر أحداث `poll_vote` المتسقة في Webhook.\n- دعم متقدم للخيوط والردود باستخدام معلمة `reply_to`.\n- مزامنة عالية الدقة بين سؤال الاستطلاع وفهارس الخيارات القابلة للتحديد.\n",
          "args": {
            "instance_id": {
              "description": "المعرف الفريد لجلسة واتساب"
            },
            "access_token": {
              "description": "رمز وصول API الخاص بك"
            },
            "chatId": {
              "description": "رقم الهاتف المستهدف أو معرف المجموعة"
            },
            "poll": {
              "description": "هيكل استطلاع الرأي الذي يحتوي على الاسم والخيارات."
            },
            "reply_to": {
              "description": "معرف الرسالة التي تقوم بالرد عليها"
            }
          },
          "tips": [
            {
              "title": "معزز التفاعل",
              "content": "استطلاعات الرأي لديها أعلى معدل استجابة لاستطلاعات رأي العملاء."
            },
            {
              "title": "حد الخيارات",
              "content": "ابقِ الخيارات أقل من 5 للحصول على أفضل تجربة جوال. كثرة الخيارات قد تؤدي إلى 'إجهاد القرار'."
            }
          ]
        }
      }
    },
    {
      "path": "/v2/send/poll/vote",
      "methods": [
        "POST"
      ],
      "title": "Send Poll Vote",
      "category": "Send Messages",
      "description": "Programmatically vote on a WhatsApp poll.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Target phone number or group ID",
          "example": "447441429009@c.us"
        },
        "messageId": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the poll message",
          "example": "ABC123456789"
        },
        "votes": {
          "required": true,
          "type": "array",
          "description": "Array of selected option names or indices",
          "example": "[\"Awesome!\"]"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Message Sent Successfully",
          "contentType": "application/json",
          "example": {
            "_data": {
              "id": {
                "fromMe": true,
                "remote": "000000000000@c.us",
                "id": "MSG_ID_123456",
                "_serialized": "true_000000000000@c.us_MSG_ID_123456"
              },
              "viewed": false,
              "body": "BASE64_IMAGE_DATA",
              "type": "image",
              "t": 1759108866,
              "from": {
                "server": "c.us",
                "user": "111111111111",
                "_serialized": "111111111111@c.us"
              },
              "to": {
                "server": "c.us",
                "user": "000000000000",
                "_serialized": "000000000000@c.us"
              },
              "ack": 0,
              "isNewMsg": true,
              "star": false,
              "kicNotified": false,
              "caption": "Here's your requested image.",
              "deprecatedMms3Url": "https://example.com/media-url",
              "directPath": "/media/direct/path/example",
              "mimetype": "image/jpeg",
              "filehash": "FILE_HASH_PLACEHOLDER",
              "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
              "size": 192487,
              "mediaKey": "MEDIA_KEY_PLACEHOLDER",
              "mediaKeyTimestamp": 1759108865,
              "streamable": false,
              "mediaHandle": null,
              "isFromTemplate": false,
              "pollInvalidated": false,
              "isSentCagPollCreation": false,
              "latestEditMsgKey": null,
              "latestEditSenderTimestampMs": null,
              "mentionedJidList": [],
              "groupMentions": [],
              "isEventCanceled": false,
              "eventInvalidated": false,
              "isVcardOverMmsDocument": false,
              "isForwarded": false,
              "isQuestion": false,
              "questionReplyQuotedMessage": null,
              "questionResponsesCount": 0,
              "readQuestionResponsesCount": 0,
              "labels": [],
              "hasReaction": false,
              "disappearingModeInitiator": "chat",
              "disappearingModeTrigger": "chat_settings",
              "productHeaderImageRejected": false,
              "lastPlaybackProgress": 0,
              "isDynamicReplyButtonsMsg": false,
              "isCarouselCard": false,
              "parentMsgId": null,
              "callSilenceReason": null,
              "isVideoCall": false,
              "callDuration": null,
              "callCreator": null,
              "callParticipants": null,
              "isCallLink": null,
              "callLinkToken": null,
              "isMdHistoryMsg": false,
              "stickerSentTs": 0,
              "lastUpdateFromServerTs": 0,
              "invokedBotWid": null,
              "bizBotType": null,
              "botResponseTargetId": null,
              "botPluginType": null,
              "botPluginReferenceIndex": null,
              "botPluginSearchProvider": null,
              "botPluginSearchUrl": null,
              "botPluginSearchQuery": null,
              "botPluginMaybeParent": false,
              "botReelPluginThumbnailCdnUrl": null,
              "botMessageDisclaimerText": null,
              "botMsgBodyType": null,
              "requiresDirectConnection": false,
              "bizContentPlaceholderType": null,
              "hostedBizEncStateMismatch": false,
              "senderOrRecipientAccountTypeHosted": false,
              "placeholderCreatedWhenAccountIsHosted": false,
              "galaxyFlowDisabled": false,
              "links": []
            },
            "mediaKey": "MEDIA_KEY_PLACEHOLDER",
            "id": {
              "fromMe": true,
              "remote": "000000000000@c.us",
              "id": "MSG_ID_123456",
              "_serialized": "true_000000000000@c.us_MSG_ID_123456"
            },
            "ack": 0,
            "hasMedia": true,
            "body": "Here's your requested image.",
            "type": "image",
            "timestamp": 1759108866,
            "from": "111111111111@c.us",
            "to": "000000000000@c.us",
            "deviceType": "android",
            "isForwarded": false,
            "forwardingScore": 0,
            "isStatus": false,
            "isStarred": false,
            "fromMe": true,
            "hasQuotedMsg": false,
            "hasReaction": false,
            "vCards": [],
            "mentionedIds": [],
            "groupMentions": [],
            "isGif": false,
            "links": []
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Egypt)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Egypt mobile numbers must be 11 digits (national format).",
            "details": {
              "provided": "20114520282",
              "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
              "info": {
                "country": "EG",
                "type": "MOBILE"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Saudi Arabia)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for SA.",
            "details": {
              "provided": "96655555",
              "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
              "info": {
                "country": "SA"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Unknown)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for Unknown.",
            "details": {
              "provided": "01145202826",
              "recommendation": "Ensure individual numbers are in international format (starting with country code).",
              "info": {
                "country": "Unknown"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 429,
          "description": "Too Many Requests - Rate Limit Exceeded",
          "contentType": "application/json",
          "example": {
            "code": "rate_limit_exceeded",
            "message": "Too many requests. Please slow down.",
            "details": {
              "retryAfter": 60,
              "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
              "upstream": {
                "error": "Rate limit",
                "statusCode": 429
              }
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "extraInfo": "\n# Programmatic Participation: Mastering the Poll Vote Engine\n\nIn highly automated environments, bots often need to participate in the decision-making process alongside human users. The `/v2/send/poll/vote` endpoint provides the capability to cast, change, or rescind votes on existing WhatsApp polls programmatically. This enables complex \"Bot-in-the-Loop\" scenarios where an AI agent can express its findings, preferences, or status via the native interactive poll UI.\n\n---\n\n## 🏗️ The Programmatic Voting Architecture\n\nDynamic voting via an API requires a precise understanding of the poll's state machine:\n1. **Target Attachment**: The engine requires a valid `messageId` of a previously sent poll. This ensures the vote is anchored to the correct interactive context.\n2. **Option Indexing**: Wawp allows you to vote using either the literal string name of an option (e.g., `\"Awesome!\"`) or its 0-indexed position within the poll. Our engine automatically resolves these to the internal binary IDs required by the WhatsApp network, preventing \"Ghost Vote\" errors.\n3. **State Overwriting**: WhatsApp follows an \"Overwrite\" model for voting. When you call this endpoint, your new `votes` array completely replaces your previous selection for that poll. If you send an empty array `[]`,\n  tips: [\n        {\n            type: 'info',\n            title: 'Mechanism',\n            content: 'Casts a vote on an existing poll message.'\n        },\n        {\n            type: 'warning',\n            title: 'Validation',\n            content: 'Fails if the poll is closed or the option ID is invalid.'\n        }\n    ],\n  recommendations: [\n        \"Verify the Poll Message ID before attempting to vote.\",\n        \"Use this for automated testing of poll workflows.\"\n    ]\n  \n   your previous vote is retracted entirely.\n\n---\n\n## 🛡️ Strategic Best Practices for Bot Participation\n\n### 1. Verification Before Voting\nTo ensure high reliability, your system should verify the poll exists and is still \"active.\"\n- **Implementation**: Before voting, check your local database or use a listener to confirm the poll hasn't been deleted. Programmatically voting on a non-existent or expired poll will return a `Message Not Found` error.\n- **Timing**: Avoid voting immediately (within milliseconds) after a poll is created by another user. Adding a small delay (1–2 seconds) mimics natural processing time and ensures the poll has fully propagated across the WhatsApp WebSocket mesh.\n\n### 2. Managing Multi-Answer Logic\nThe `votes` parameter is an array for a reason. \n- **Checkboxes vs. Radio Buttons**: If the original poll was created with `multipleAnswers: true`, your array can contain multiple indices (e.g., `[0, 2]`). If it was a single-choice poll, provided arrays with more than one element will typically result in only the *last* item being counted by the WhatsApp client UI.\n- **UX Consistency**: Ensure your bot's votes align with any previous text-based statements it made to avoid confusing human participants.\n\n### 3. The Power of Selective Retraction\nProgrammatic voting allows for \"Temporary Consensus.\"\n- **Scenario**: Your bot can vote for an option while it's \"investigating\" a problem, and then retract its vote or switch to a \"Success\" option once the investigation is complete. This provides a visual progress indicator that is much more subtle and professional than spamming the chat with status messages.\n\n---\n\n## 🧩 Advanced Use Cases\n\n### Automated Consensus Building\nBuild a \"Moderator Bot\" that monitors a group poll. Once a specific option reaches a threshold (e.g., 5 votes), the bot can cast its own vote for that option to \"Seal the Deal\" and then automatically trigger a coordination message or calendar invite.\n\n### Sentiment Re-alignment\nIn an AI-driven support flow, if a user starts a poll to rate their experience, the bot can programmatically vote for the \"Neutral\" option initially. As the conversation improves and sentiment analysis scores rise, the bot can update its vote to \"Positive,\" providing the human agent with a visual cue of the AI's current assessment of the interaction.\n\n---\n\n## 🛠️ Common Pitfalls and Solutions\n\n- **License Barriers**: Ensure your instance is correctly provisioned before integrating programmatic voting into your production workflow.\n- **Case Sensitivity**: When voting via string names, ensured your strings match the poll options *exactly* (including case and trailing spaces). A mismatch will cause the vote to be ignored or return an error. Using **Indices** (integers) is the recommended best practice for high-reliability systems.\n- **Race Conditions**: If multiple instances of your bot attempt to update a vote on the same poll simultaneously, the last request received by the Wawp proxy will define the final state. Use a centralized queue or locking mechanism in your backend if you have multiple bot clusters interacting with the same chat.\n\n---\n\n## Summary of Capabilities:\n- Programmatically cast, update, or retract votes on native WhatsApp polls.\n- Support for voting by literal option strings or numeric indices.\n- Exclusive for advanced automation and AI integration.\n- Full support for multi-choice (checkbox) and single-choice (radio) poll architectures.\n- Real-time synchronization with the WhatsApp network for instantaneous UI updates on recipient devices.\n",
      "translations": {
        "ar": {
          "title": "إرسال تصويت (Poll Vote)",
          "description": "التصويت برمجياً على استطلاع رأي في واتساب.",
          "tips": [
            {
              "title": "الآلية",
              "content": "يدلي بصوت على رسالة استطلاع موجودة."
            },
            {
              "title": "التحقق",
              "content": "يفشل إذا تم إغلاق الاستطلاع أو إذا كان معرف الخيار غير صالح."
            }
          ],
          "recommendations": [
            "تحقق من معرف رسالة الاستطلاع قبل محاولة التصويت.",
            "استخدم هذا للاختبار الآلي لتدفقات عمل الاستطلاع."
          ],
          "extraInfo": "\n# المشاركة البرمجية: إتقان محرك تصويت الاستطلاعات\n\nفي البيئات عالية الأتمتة، غالباً ما تحتاج البوتات إلى المشاركة في عملية اتخاذ القرار جنباً إلى جنب مع المستخدمين البشريين. توفر نقطة نهاية `/v2/send/poll/vote` القدرة على الإدلاء بالأصوات أو تغييرها أو سحبها من استطلاعات واتساب الحالية برمجياً. يتيح ذلك سيناريوهات معقدة حيث يمكن لوكيل الذكاء الاصطناعي التعبير عن استنتاجاته أو تفضيلاته أو حالته عبر واجهة استطلاع الرأي الأصلية التفاعلية.\n\n---\n\n## 🏗️ بنية التصويت البرمجي\n\nيتطلب التصويت الديناميكي عبر API فهماً دقيقاً لنظام حالة الاستطلاع:\n1. **ارتباط الهدف**: يتطلب المحرك `messageId` صالحاً لاستطلاع تم إرساله مسبقاً. يضمن ذلك تثبيت التصويت في السياق التفاعلي الصحيح.\n2. **فهرسة الخيارات**: يتيح لك Wawp التصويت باستخدام إما الاسم النصي الصريح للخيار (مثلاً `\"رائع!\"`) أو موقعه المفهرس (بدءاً من 0) داخل الاستطلاع. يقوم محركنا تلقائياً بتحويل هذه الخيارات إلى المعرفات الثنائية الداخلية التي تتطلبها شبكة واتساب، مما يمنع أخطاء \"التصويت الشبح\".\n3. **تجاوز الحالة**: يتبع واتساب نموذج \"التجاوز\" (Overwrite) للتصويت. عندما تستدعي نقطة النهاية هذه، فإن مصفوفة `votes` الجديدة الخاصة بك تحل تماماً محل اختيارك السابق لهذا الاستطلاع. إذا أرسلت مصفوفة فارغة `[]`، يتم سحب تصويتك السابق بالكامل.\n\n---\n\n## 🛡️ أفضل الممارسات الاستراتيجية لمشاركة البوت\n\n### 1. التحقق قبل التصويت\nلضمان موثوقية عالية، يجب على نظامك التحقق من وجود الاستطلاع وأنه لا يزال \"نشطاً\".\n- **التنفيذ**: قبل التصويت، تحقق من قاعدة بياناتك المحلية أو استخدم مستمعاً (Listener) للتأكد من عدم حذف الاستطلاع. سيؤدي التصويت البرمجي على استطلاع غير موجود أو منتهي الصلاحية إلى إرجاع خطأ `Message Not Found`.\n- **التوقيت**: تجنب التصويت فوراً (في غضون أجزاء من الثانية) بعد إنشاء استطلاع بواسطة مستخدم آخر. إضافة تأخير بسيط (1-2 ثانية) يحاكي وقت المعالجة الطبيعي ويضمن انتشار الاستطلاع بالكامل عبر شبكة واتساب.\n\n### 2. إدارة منطق الإجابات المتعددة\nمعلمة `votes` هي مصفوفة لسبب وجيه.\n- **مربعات الاختيار مقابل أزرار الاختيار**: إذا تم إنشاء الاستطلاع الأصلي مع `multipleAnswers: true`، يمكن أن تحتوي مصفوفتك على عدة فهارس (مثلاً `[0, 2]`). أما إذا كان استطلاعاً بخيار واحد، فإن المصفوفات التي تحتوي على أكثر من عنصر ستؤدي عادةً إلى احتساب العنصر *الأخير* فقط من قبل واجهة واتساب.\n- **اتساق تجربة المستخدم**: تأكد من أن تصويتات البوت الخاصة بك تتماشى مع أي تصريحات نصية سابقة أدلى بها لتجنب الخلط لدى المشاركين البشريين.\n\n### 3. قوة السحب الانتقائي\nيسمح التصويت البرمجي بـ \"الإجماع المؤقت\".\n- **سيناريو**: يمكن للبوت الخاص بك التصويت لخيار ما أثناء \"تحقيقه\" في مشكلة، ثم سحب تصويته أو التبديل إلى خيار \"النجاح\" بمجرد انتهاء التحقيق. يوفر هذا مؤشراً مرئياً للتقدم يكون أكثر دقة واحترافية من إغراق الدردشة برسائل الحالة المتكررة.\n\n---\n\n## 🧩 حالات استخدام متقدمة\n\n### بناء الإجماع المؤتمت\nقم ببناء \"بوت مدير\" (Moderator Bot) يراقب استطلاعاً جماعياً. بمجرد وصول خيار محدد إلى حد معين (مثلاً 5 أصوات)، يمكن للبوت الإدلاء بتصويته لهذا الخيار لـ \"إتمام الصفقة\" ثم إطلاق رسالة تنسيق أو دعوة تقويم تلقائياً.\n\n### إعادة محاذاة المشاعر\nفي تدفق دعم مدفوع بالذكاء الاصطناعي، إذا بدأ المستخدم استطلاعاً لتقييم تجربته، يمكن للبوت التصويت برمجياً لخيار \"محايد\" في البداية. مع تحسن المحادثة وارتفاع درجات تحليل المشاعر، يمكن للبوت تحديث تصويته إلى \"إيجابي\"، مما يوفر للوكيل البشري إشارة مرئية لتقييم الذكاء الاصطناعي الحالي للتفاعل.\n\n---\n\n## 🛠️ المزالق الشائعة والحلول\n\n- **عوائق الترخيص**: تأكد دائماً من تهيئة مثيلك بشكل صحيح قبل دمج التصويت البرمجي في سير عمل الإنتاج الخاص بك.\n- **حساسية حالة الأحرف**: عند التصويت عبر أسماء الخيارات النصية، تأكد من مطابقة السلاسل لخيارات الاستطلاع *تمائاً* (بما في ذلك حالة الأحرف والمسافات الزائدة). سيؤدي عدم التطابق إلى تجاهل التصويت أو إرجاع خطأ. استخدام **الفهارس** (أرقام صحيحة) هو أفضل ممارسة موصى بها للأنظمة عالية الموثوقية.\n- **ظروف السباق (Race Conditions)**: إذا حاولت عدة مثيلات من البوت الخاص بك تحديث تصويت في نفس الاستطلاع في وقت واحد، فإن آخر طلب يستلمه بروكسي Wawp هو الذي سيحدد الحالة النهائية. استخدم طابوراً مركزياً أو آلية قفل في نظامك الخلفي إذا كان لديك عدة مجموعات بوت تتفاعل مع نفس الدردشة.\n\n---\n\n## ملخص الإمكانيات:\n- الإدلاء بالأصوات أو تحديثها أو سحبها برمجياً في استطلاعات واتساب الأصلية.\n- دعم التصويت عبر سلاسل الخيارات الحرفية أو الفهارس الرقمية.\n- حصري للأتمتة المتقدمة وتكامل الذكاء الاصطناعي.\n- دعم كامل لبنيات استطلاعات الرأي متعددة الخيارات (checkbox) والخيارات الفردية (radio).\n- مزامنة في الوقت الفعلي مع شبكة واتساب لتحديثات واجهة المستخدم الفورية على أجهزة المستلمين.\n",
          "args": {
            "instance_id": {
              "description": "المعرف الفريد لجلسة واتساب"
            },
            "access_token": {
              "description": "رمز وصول API الخاص بك"
            },
            "chatId": {
              "description": "رقم الهاتف المستهدف أو معرف المجموعة"
            },
            "messageId": {
              "description": "المعرف الفريد لرسالة الاستطلاع"
            },
            "votes": {
              "description": "مصفوفة من أسماء الخيارات المختارة أو فهارسها"
            }
          }
        }
      }
    },
    {
      "path": "/v2/send/contact",
      "methods": [
        "POST"
      ],
      "title": "Send Contact Vcard",
      "category": "Send Messages",
      "description": "Send professional contact cards (vCards) to a chat. Supports single or multiple contacts in one bubble.",
      "modifiedAt": "Just now",
      "bodyEditor": true,
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Unique ID of the WhatsApp session",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API access token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Recipient's WhatsApp number",
          "example": "447441429009"
        },
        "contacts": {
          "required": true,
          "type": "array",
          "description": "Array of contact objects containing name and phone info.",
          "example": "[\n  {\n    \"fullName\": \"Wawp Support\",\n    \"organization\": \"Wawp HQ\",\n    \"phoneNumber\": \"+201111111111\",\n    \"whatsappId\": \"201111111111\"\n  }\n]"
        },
        "reply_to": {
          "required": false,
          "type": "string",
          "description": "The ID of the message you are replying to",
          "example": "false_111...AAAA"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Message Sent Successfully",
          "contentType": "application/json",
          "example": {
            "_data": {
              "id": {
                "fromMe": true,
                "remote": "000000000000@c.us",
                "id": "MSG_ID_123456",
                "_serialized": "true_000000000000@c.us_MSG_ID_123456"
              },
              "viewed": false,
              "body": "BASE64_IMAGE_DATA",
              "type": "image",
              "t": 1759108866,
              "from": {
                "server": "c.us",
                "user": "111111111111",
                "_serialized": "111111111111@c.us"
              },
              "to": {
                "server": "c.us",
                "user": "000000000000",
                "_serialized": "000000000000@c.us"
              },
              "ack": 0,
              "isNewMsg": true,
              "star": false,
              "kicNotified": false,
              "caption": "Here's your requested image.",
              "deprecatedMms3Url": "https://example.com/media-url",
              "directPath": "/media/direct/path/example",
              "mimetype": "image/jpeg",
              "filehash": "FILE_HASH_PLACEHOLDER",
              "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
              "size": 192487,
              "mediaKey": "MEDIA_KEY_PLACEHOLDER",
              "mediaKeyTimestamp": 1759108865,
              "streamable": false,
              "mediaHandle": null,
              "isFromTemplate": false,
              "pollInvalidated": false,
              "isSentCagPollCreation": false,
              "latestEditMsgKey": null,
              "latestEditSenderTimestampMs": null,
              "mentionedJidList": [],
              "groupMentions": [],
              "isEventCanceled": false,
              "eventInvalidated": false,
              "isVcardOverMmsDocument": false,
              "isForwarded": false,
              "isQuestion": false,
              "questionReplyQuotedMessage": null,
              "questionResponsesCount": 0,
              "readQuestionResponsesCount": 0,
              "labels": [],
              "hasReaction": false,
              "disappearingModeInitiator": "chat",
              "disappearingModeTrigger": "chat_settings",
              "productHeaderImageRejected": false,
              "lastPlaybackProgress": 0,
              "isDynamicReplyButtonsMsg": false,
              "isCarouselCard": false,
              "parentMsgId": null,
              "callSilenceReason": null,
              "isVideoCall": false,
              "callDuration": null,
              "callCreator": null,
              "callParticipants": null,
              "isCallLink": null,
              "callLinkToken": null,
              "isMdHistoryMsg": false,
              "stickerSentTs": 0,
              "lastUpdateFromServerTs": 0,
              "invokedBotWid": null,
              "bizBotType": null,
              "botResponseTargetId": null,
              "botPluginType": null,
              "botPluginReferenceIndex": null,
              "botPluginSearchProvider": null,
              "botPluginSearchUrl": null,
              "botPluginSearchQuery": null,
              "botPluginMaybeParent": false,
              "botReelPluginThumbnailCdnUrl": null,
              "botMessageDisclaimerText": null,
              "botMsgBodyType": null,
              "requiresDirectConnection": false,
              "bizContentPlaceholderType": null,
              "hostedBizEncStateMismatch": false,
              "senderOrRecipientAccountTypeHosted": false,
              "placeholderCreatedWhenAccountIsHosted": false,
              "galaxyFlowDisabled": false,
              "links": []
            },
            "mediaKey": "MEDIA_KEY_PLACEHOLDER",
            "id": {
              "fromMe": true,
              "remote": "000000000000@c.us",
              "id": "MSG_ID_123456",
              "_serialized": "true_000000000000@c.us_MSG_ID_123456"
            },
            "ack": 0,
            "hasMedia": true,
            "body": "Here's your requested image.",
            "type": "image",
            "timestamp": 1759108866,
            "from": "111111111111@c.us",
            "to": "000000000000@c.us",
            "deviceType": "android",
            "isForwarded": false,
            "forwardingScore": 0,
            "isStatus": false,
            "isStarred": false,
            "fromMe": true,
            "hasQuotedMsg": false,
            "hasReaction": false,
            "vCards": [],
            "mentionedIds": [],
            "groupMentions": [],
            "isGif": false,
            "links": []
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Egypt)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Egypt mobile numbers must be 11 digits (national format).",
            "details": {
              "provided": "20114520282",
              "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
              "info": {
                "country": "EG",
                "type": "MOBILE"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Saudi Arabia)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for SA.",
            "details": {
              "provided": "96655555",
              "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
              "info": {
                "country": "SA"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Unknown)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for Unknown.",
            "details": {
              "provided": "01145202826",
              "recommendation": "Ensure individual numbers are in international format (starting with country code).",
              "info": {
                "country": "Unknown"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 429,
          "description": "Too Many Requests - Rate Limit Exceeded",
          "contentType": "application/json",
          "example": {
            "code": "rate_limit_exceeded",
            "message": "Too many requests. Please slow down.",
            "details": {
              "retryAfter": 60,
              "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
              "upstream": {
                "error": "Rate limit",
                "statusCode": 429
              }
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "extraInfo": "\n# Professional Identity: Mastering the Contact Card (vCard) Engine\n\nIn a professional ecosystem, sharing contact information shouldn't be about typing out phone numbers. The `/v2/send/contact` endpoint allows you to share digital business cards (vCards) that are interactive, easy to save, and high-fidelity. By automating the sharing of contact cards, you can streamline the \"Agent Handoff\" process, provide instant access to emergency helplines, or share specialized technician details with a single API call.\n\n![send contact.png](https://api.apidog.com/api/v1/projects/1017306/resources/369243/image-preview)\n\n---\n\n## 🏗️ The VCard Serialization Pipeline\n\nSharing a contact via Wawp is more than just sending a name. Our engine manages a sophisticated serialization process to ensure compatibility with both Android and iOS contact managers:\n1. **vCard Specification Encoding**: Wawp takes your JSON contact array and transcribes it into the standard **vCard (VCF) v3.0** format. This format is universally recognized by mobile operating systems, ensuring that when the user clicks \"Save,\" the fields map correctly to their local address book.\n2. **Identity Verification**: The `whatsappId` field is critical. Our engine uses this to link the vCard directly to a WhatsApp profile. This allows the recipient to immediately see the contact's profile picture and start a one-click message thread without even saving the number first.\n3. **Multi-Contact Batching**: Wawp supports sending multiple contacts in a single \"Message Bubble.\" This is handled by concatenating the serialized VCF blocks into a single payload, providing a clean \"Team\" or \"Directory\" view for the user.\n\n---\n\n## 🛡️ Strategic Best Practices for Digital Identity\n\n### 1. The \"Wholesale Profile\" Strategy\nA bare-bones contact card looks suspicious to users. To build brand authority:\n- **Rich Metadata**: Always provide the `organization` and `fullName`. \n- **Professionalism**: If the contact is an agent, include their department (e.g., \"Sarah - Senior Consultant\"). \n- **Formatting**: Ensure `phoneNumber` includes the international `+` prefix. This is distinct from the `whatsappId`,\n  tips: [\n        {\n            type: 'info',\n            title: 'Format',\n            content: 'Sends a vCard (VCF) file that can be saved directly to contacts.'\n        },\n        {\n            type: 'info',\n            title: 'Fields',\n            content: 'Supports multiple phone numbers, emails, and addresses.'\n        }\n    ],\n  recommendations: [\n        \"Include a properly formatted name (N, FN properties) for best compatibility.\",\n        \"Use this to share support line numbers efficiently.\"\n    ]\n  \n   which is just the numeric digits used for network routing.\n\n### 2. Streamlining the Agent Handoff\nIn a bot-to-human transition:\n- **Implementation**: Instead of the bot saying \"Now talking to Mark, his number is 123,\" have the system automatically trigger a `/v2/send/contact` call for Mark's vCard. \n- **UX Impact**: This gives the customer a clear \"Professional Point of Contact\" bubble that they can refer back to later, increasing the transparency of your support flow.\n\n### 3. Validation and Filename Integrity\n- **Character Limits**: Keep the `fullName` under **40 characters**. Longer names can be truncated in the chat preview or result in messy address book entries.\n- **Emoji Usage**: While emojis are supported in the name field, use them sparingly. Excessive emojis in a vCard name can sometimes interfere with search indexing in a user's local contact app.\n\n---\n\n## 🧩 Advanced Use Cases\n\n### Corporate Staff Directories\nSend a \"Support Directory\" message containing three distinct contact cards: \"Billing Support,\" \"Technical Desk,\" and \"Human Resources.\" By sending these as a single array, the user receives one clean interactive list rather than three separate messages.\n\n### Referral and Loyalty Programs\nAutomate your referral system. When a user qualifies for a partner offer, send the partner's professional contact card via Wawp. The `reply_to` parameter can be used to link this contact card to the specific \"Reward Earned\" text message, making the context immediately clear.\n\n---\n\n## 🛠️ Common Pitfalls and Solutions\n\n- **Malformed WhatsApp IDs**: If the `whatsappId` doesn't match a real account, the \"Message\" button on the vCard will be disabled on the recipient's phone. Always verify your agent IDs before sharing.\n- **Header Discrepancies**: If you provide a `vcard` string directly (via the legacy fields), ensure it starts with `BEGIN:VCARD` and ends with `END:VCARD`. Wawp will return a `Serialization Error` if the block is malformed.\n- **Phone Number Confusion**: Users often forget the `+` in the `phoneNumber` field. While Wawp attempts to normalize this, provide it explicitly to ensure the user's phone recognizes it as a clickable dialer link.\n\n---\n\n## Summary of Capabilities:\n- Deliver interactive, native-style WhatsApp contact cards (vCards).\n- Support for batching multiple contacts (Staff/Directory) in a single message.\n- One-click \"Save Contact\" and \"Message\" functionality for the end-user.\n- Automated VCF v3.0 serialization for universal iOS/Android compatibility.\n- Seamless integration with threading/replies via the `reply_to` parameter.\n- High-fidelity identity sharing with full support for Organization and Job Title fields.\n",
      "image": "https://api.apidog.com/api/v1/projects/1017306/resources/369243/image-preview",
      "translations": {
        "ar": {
          "title": "إرسال بطاقة جهة اتصال",
          "description": "إرسال بطاقات اتصال احترافية (vCards) إلى الدردشة. يدعم جهات اتصال فردية أو متعددة في فقاعة واحدة.",
          "tips": [
            {
              "title": "التنسيق",
              "content": "يرسل ملف vCard (VCF) يمكن حفظه مباشرة في جهات الاتصال."
            },
            {
              "title": "الحقول",
              "content": "يدعم أرقام هواتف، ورسائل بريد إلكتروني، وعناوين متعددة."
            }
          ],
          "recommendations": [
            "قم بتضمين اسم منسق بشكل صحيح (خصائص N, FN) للحصول على أفضل توافق.",
            "استخدم هذا لمشاركة أرقام خطوط الدعم بكفاءة."
          ],
          "extraInfo": "\n# الهوية المهنية: إتقان محرك بطاقة الاتصال (vCard)\n\nفي المنظومة المهنية، لا ينبغي أن تتعلق مشاركة معلومات الاتصال بكتابة أرقام الهواتف. تتيح لك نقطة النهاية `/v2/send/contact` مشاركة بطاقات العمل الرقمية (vCards) التفاعلية وسهلة الحفظ وعالية الدقة. من خلال أتمتة مشاركة بطاقات الاتصال، يمكنك تبسيط عملية \"تسليم الوكيل\"، أو توفير وصول فوري لخطوط المساعدة في حالات الطوارئ، أو مشاركة تفاصيل الفنيين المتخصصين باستدعاء API واحد.\n\n![إرسال بطاقة اتصال](https://api.apidog.com/api/v1/projects/1017306/resources/369243/image-preview)\n\n---\n\n## 🏗️ مسار تسلسل VCard\n\nمشاركة جهة اتصال عبر Wawp هي أكثر من مجرد إرسال اسم. يدير محركنا عملية تسلسل متطورة لضمان التوافق مع مديري جهات الاتصال في كل من Android و iOS:\n1. **ترميز مواصفات vCard**: يأخذ Wawp مصفوفة JSON لجهات الاتصال الخاصة بك وينسخها إلى تنسيق **vCard (VCF) v3.0** القياسي. هذا التنسيق معترف به عالميًا من قبل أنظمة تشغيل الأجهزة المحمولة، مما يضمن أنه عندما ينقر المستخدم على \"حفظ\"، يتم تعيين الحقول بشكل صحيح في دفتر عناوينهم المحلي.\n2. **التحقق من الهوية**: حقل `whatsappId` بالغ الأهمية. يستخدم محركنا هذا لربط vCard مباشرة بملف تعريف واتساب. يتيح ذلك للمستلم رؤية صورة الملف الشخصي لجهة الاتصال فورًا وبدء خيط رسائل بنقرة واحدة حتى دون حفظ الرقم أولاً.\n3. **تجميع جهات اتصال متعددة**: يدعم Wawp إرسال عدة جهات اتصال في \"فقاعة رسالة\" واحدة. يتم ذلك عن طريق ربط كتل VCF المتسلسلة في حمولة واحدة، مما يوفر عرض \"فريق\" أو \"دليل\" نظيف للمستخدم.\n\n---\n\n## 🛡️ أفضل الممارسات الاستراتيجية للهوية الرقمية\n\n### 1. استراتيجية \"الملف الشخصي المتكامل\"\nبطاقة الاتصال المختصرة للغاية تبدو مشبوهة للمستخدمين. لبناء سلطة العلامة التجارية:\n- **بيانات وصفية غنية**: قدم دائمًا `organization` (المنظمة) و `fullName` (الاسم الكامل).\n- **الاحترافية**: إذا كانت جهة الاتصال وكيلاً، فقم بتضمين قسمه (مثلاً \"سارة - استشاري أول\").\n- **التنسيق**: تأكد من أن `phoneNumber` يتضمن البادئة الدولية `+`. هذا يختلف عن `whatsappId` الذي هو مجرد الأرقام الرقمية المستخدمة لتوجيه الشبكة.\n\n### 2. تبسيط تسليم الوكيل\nفي الانتقال من البوت إلى البشر:\n- **التنفيذ**: بدلاً من أن يقول البوت \"تتحدث الآن مع مارك، رقمه هو 123\"، اجعل النظام يستدعي تلقائياً `/v2/send/contact` لبطاقة اتصال مارك.\n- **تأثير تجربة المستخدم**: يعطي هذا العميل فقاعة \"نقطة اتصال مهنية\" واضحة يمكنه الرجوع إليها لاحقاً، مما يزيد من شفافية تدفق الدعم الخاص بك.\n\n### 3. التحقق وسلامة أسماء الملفات\n- **حدود الأحرف**: ابقِ `fullName` أقل من **40 حرفاً**. الأسماء الأطول قد تقتطع في معاينة الدردشة أو تؤدي إلى إدخالات غير مرتبة في دفتر العناوين.\n- **استخدام الرموز التعبيرية**: بينما الرموز التعبيرية مدعومة في حقل الاسم، استخدمها باعتدال. الرموز التعبيرية المفرطة في اسم vCard يمكن أن تتداخل أحياناً مع أرشفة البحث في تطبيق جهات الاتصال المحلي للمستخدم.\n\n---\n\n## 🧩 حالات استخدام متقدمة\n\n### أدلة الموظفين في الشركات\nأرسل رسالة \"دليل الدعم\" تحتوي على ثلاث بطاقات اتصال متميزة: \"دعم الفواتير\"، \"المكتب الفني\"، و\"الموارد البشرية\". بإرسالها كمصفوفة واحدة، يتلقى المستخدم قائمة تفاعلية واحدة نظيفة بدلاً من ثلاث رسائل منفصلة.\n\n### برامج الإحالة والولاء\nقم بأتمتة نظام الإحالة الخاص بك. عندما يتأهل مستخدم لعرض شريك، أرسل بطاقة الاتصال المهنية للشريك عبر Wawp. يمكن استخدام معلمة `reply_to` لربط بطاقة الاتصال هذه برسالة نصية محددة \"تم الحصول على المكافأة\"، مما يجعل السياق واضحاً على الفور.\n\n---\n\n## 🛠️ المزالق الشائعة والحلول\n\n- **معرفات واتساب مشوهة**: إذا كان `whatsappId` لا يتطابق مع حساب حقيقي، فسيتم تعطيل زر \"رسالة\" في vCard على هاتف المستلم. تحقق دائمًا من معرفات وكلائك قبل المشاركة.\n- **تضارب الرؤوس**: إذا قدمت سلسلة `vcard` مباشرة (عبر الحقول القديمة)، فتأكد من أنها تبدأ بـ `BEGIN:VCARD` وتنتهي بـ `END:VCARD`. سيعيد Wawp خطأ `Serialization Error` إذا كانت الكتلة مشوهة.\n- **ارتباك رقم الهاتف**: ينسى المستخدمون غالباً `+` في حقل `phoneNumber`. بينما يحاول Wawp تطبيع ذلك، قدمه صراحة لضمان أن هاتف المستخدم يتعرف عليه كرابط اتصال قابل للنقر.\n\n---\n\n## ملخص الإمكانيات:\n- تقديم بطاقات اتصال واتساب (vCards) أصلية وتفاعلية.\n- دعم لتجميع جهات اتصال متعددة (موظفين/دليل) في رسالة واحدة.\n- وظيفة \"حفظ جهة الاتصال\" و \"رسالة\" بنقرة واحدة للمستخدم النهائي.\n- تسلسل تلقائي لـ VCF v3.0 للتوافق العالمي مع iOS/Android.\n- تكامل سلس مع الخيوط/الردود عبر معلمة `reply_to`.\n- مشاركة هوية عالية الدقة مع دعم كامل لحقول المنظمة والمسمى الوظيفي.\n",
          "args": {
            "instance_id": {
              "description": "المعرف الفريد لجلسة واتساب"
            },
            "access_token": {
              "description": "رمز وصول API"
            },
            "chatId": {
              "description": "رقم واتساب للمستلم"
            },
            "contacts": {
              "description": "مصفوفة من كائنات جهات الاتصال التي تحتوي على معلومات الاسم والهاتف."
            },
            "reply_to": {
              "description": "معرف الرسالة التي تقوم بالرد عليها"
            }
          }
        }
      }
    },
    {
      "path": "/v2/send/seen",
      "methods": [
        "POST"
      ],
      "title": "Mark message(s) as seen",
      "category": "Send Messages",
      "description": "Mark specific messages or an entire chat as seen/read (Blue Ticks).",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Target phone number or group ID",
          "example": "447441429009@c.us"
        },
        "messageIds": {
          "required": true,
          "type": "array",
          "description": "Array of message IDs to mark as seen.",
          "example": "[\"false_447441429009@c.us_AAAAAAAAAAAAAAAAAAAA\"]"
        },
        "participant": {
          "required": false,
          "type": "string",
          "description": "The participant who sent the message (for groups).",
          "example": "null"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Message Sent Successfully",
          "contentType": "application/json",
          "example": {
            "_data": {
              "id": {
                "fromMe": true,
                "remote": "000000000000@c.us",
                "id": "MSG_ID_123456",
                "_serialized": "true_000000000000@c.us_MSG_ID_123456"
              },
              "viewed": false,
              "body": "BASE64_IMAGE_DATA",
              "type": "image",
              "t": 1759108866,
              "from": {
                "server": "c.us",
                "user": "111111111111",
                "_serialized": "111111111111@c.us"
              },
              "to": {
                "server": "c.us",
                "user": "000000000000",
                "_serialized": "000000000000@c.us"
              },
              "ack": 0,
              "isNewMsg": true,
              "star": false,
              "kicNotified": false,
              "caption": "Here's your requested image.",
              "deprecatedMms3Url": "https://example.com/media-url",
              "directPath": "/media/direct/path/example",
              "mimetype": "image/jpeg",
              "filehash": "FILE_HASH_PLACEHOLDER",
              "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
              "size": 192487,
              "mediaKey": "MEDIA_KEY_PLACEHOLDER",
              "mediaKeyTimestamp": 1759108865,
              "streamable": false,
              "mediaHandle": null,
              "isFromTemplate": false,
              "pollInvalidated": false,
              "isSentCagPollCreation": false,
              "latestEditMsgKey": null,
              "latestEditSenderTimestampMs": null,
              "mentionedJidList": [],
              "groupMentions": [],
              "isEventCanceled": false,
              "eventInvalidated": false,
              "isVcardOverMmsDocument": false,
              "isForwarded": false,
              "isQuestion": false,
              "questionReplyQuotedMessage": null,
              "questionResponsesCount": 0,
              "readQuestionResponsesCount": 0,
              "labels": [],
              "hasReaction": false,
              "disappearingModeInitiator": "chat",
              "disappearingModeTrigger": "chat_settings",
              "productHeaderImageRejected": false,
              "lastPlaybackProgress": 0,
              "isDynamicReplyButtonsMsg": false,
              "isCarouselCard": false,
              "parentMsgId": null,
              "callSilenceReason": null,
              "isVideoCall": false,
              "callDuration": null,
              "callCreator": null,
              "callParticipants": null,
              "isCallLink": null,
              "callLinkToken": null,
              "isMdHistoryMsg": false,
              "stickerSentTs": 0,
              "lastUpdateFromServerTs": 0,
              "invokedBotWid": null,
              "bizBotType": null,
              "botResponseTargetId": null,
              "botPluginType": null,
              "botPluginReferenceIndex": null,
              "botPluginSearchProvider": null,
              "botPluginSearchUrl": null,
              "botPluginSearchQuery": null,
              "botPluginMaybeParent": false,
              "botReelPluginThumbnailCdnUrl": null,
              "botMessageDisclaimerText": null,
              "botMsgBodyType": null,
              "requiresDirectConnection": false,
              "bizContentPlaceholderType": null,
              "hostedBizEncStateMismatch": false,
              "senderOrRecipientAccountTypeHosted": false,
              "placeholderCreatedWhenAccountIsHosted": false,
              "galaxyFlowDisabled": false,
              "links": []
            },
            "mediaKey": "MEDIA_KEY_PLACEHOLDER",
            "id": {
              "fromMe": true,
              "remote": "000000000000@c.us",
              "id": "MSG_ID_123456",
              "_serialized": "true_000000000000@c.us_MSG_ID_123456"
            },
            "ack": 0,
            "hasMedia": true,
            "body": "Here's your requested image.",
            "type": "image",
            "timestamp": 1759108866,
            "from": "111111111111@c.us",
            "to": "000000000000@c.us",
            "deviceType": "android",
            "isForwarded": false,
            "forwardingScore": 0,
            "isStatus": false,
            "isStarred": false,
            "fromMe": true,
            "hasQuotedMsg": false,
            "hasReaction": false,
            "vCards": [],
            "mentionedIds": [],
            "groupMentions": [],
            "isGif": false,
            "links": []
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Egypt)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Egypt mobile numbers must be 11 digits (national format).",
            "details": {
              "provided": "20114520282",
              "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
              "info": {
                "country": "EG",
                "type": "MOBILE"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Saudi Arabia)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for SA.",
            "details": {
              "provided": "96655555",
              "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
              "info": {
                "country": "SA"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Unknown)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for Unknown.",
            "details": {
              "provided": "01145202826",
              "recommendation": "Ensure individual numbers are in international format (starting with country code).",
              "info": {
                "country": "Unknown"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 429,
          "description": "Too Many Requests - Rate Limit Exceeded",
          "contentType": "application/json",
          "example": {
            "code": "rate_limit_exceeded",
            "message": "Too many requests. Please slow down.",
            "details": {
              "retryAfter": 60,
              "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
              "upstream": {
                "error": "Rate limit",
                "statusCode": 429
              }
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "extraInfo": "\n# State Synchronization: Mastering the Read Receipt Engine\n\nThe `/v2/send/seen` endpoint is the primary mechanism for managing \"Presence and Attention\" within a WhatsApp conversation. In the WhatsApp ecosystem, the transition from grey ticks (delivered) to blue ticks (read) is a high-signal event that dictates user expectation. By programmatically marking messages as seen, you can synchronize your custom CRM, dashboard, or bot state with the native WhatsApp interface, ensuring the customer feels heard and the agent's workspace remains organized.\n\n---\n\n## 🏗️ The Read-Receipt Pipeline\n\nMarking a message as \"Seen\" is a two-way synchronization event handled by Wawp:\n1. **Target Identification**: The engine accepts an array of `messageIds`. These IDs are the unique cryptographic hashes generated when the message was first sent or received. Wawp locates these specific entries within the session's local message store.\n2. **The Blue-Tick Broadcast**: Once identified, Wawp sends a specialized \"Read Acknowledgment\" packet over the WhatsApp WebSocket. This packet is then propagated to the original sender's device, where the delivery ticks instantly turn blue.\n3. **Internal Unread Clearing**: Simultaneously, Wawp instructs the WhatsApp network to clear the \"Unread Count\" badge for that specific chat on all linked devices (e.g., if you have WhatsApp Web or Desktop open alongside your API instance).\n\n---\n\n## 🛡️ Strategic Best Practices for Read Management\n\n### 1. The \"Human-in-the-Loop\" Sync\nAutomating seen receipts requires careful alignment with actual agent activity.\n- **Workflow**: Only trigger `/v2/send/seen` when an agent actually *opens* the chat in your custom dashboard. \n- **UX Impact**: If you mark everything as seen automatically, the customer expects an immediate reply. If an agent isn't actually there, you create a \"Response Gap\" that leads to customer frustration. \n\n### 2. High-Efficiency Batching\nWawp supports batching multiple messages in a single API call for a reason.\n- **Implementation**: If a user sends five messages (Text, Image, then more Text) while your agent is away, do not call the seen endpoint five times. Instead, collect all five `messageIds` and send them in a single array. \n- **Performance**: Batching reduces the number of WebSocket transmissions, preserving your instance's bandwidth and reducing the load on the WhatsApp network.\n\n### 3. Simulating Natural Reading (The Delay Strategy)\nBots that respond instantly and mark messages as seen in milliseconds can often feel \"Robotic\" and inhuman.\n- **Recommendation**: For automated bot flows, implement a small, random delay (e.g., 800ms to 2s) between receiving the message and marking it as seen. This mimics the human process of picking up a phone and reading a message, making the interaction feel more organic.\n\n---\n\n## 🧩 Advanced Use Cases\n\n### Native CRM \"Open\" Tracking\nIf you are building a custom CRM on top of Wawp, use the seen endpoint to track agent performance. By measuring the time between a `message.received` webhook and your system's `/v2/send/seen` call, you can calculate the \"Average Time to View,\" a critical KPI for support teams.\n\n### Bot Flow \"Triage\"\nIn a complex multi-stage bot, you can use read receipts to signal milestones. For example, mark the user's initial inquiry as seen only after the bot has successfully categorized the intent. This provides the user with a visual confirmation that the system has \"Understood\" the input and is now processing the result.\n\n---\n\n## 🛠️ Common Pitfalls and Solutions\n\n- **The Participant ID (Groups)**: In group chats, marking a message as seen requires the `chatId` of the group AND optionally the `participant` ID of the original sender. If you omit the participant ID in high-concurrency group environments, some engine versions may fail to identify the specific message hash, resulting in a `Receipt Error`.\n- **Already-Read Loops**: Avoid calling the seen endpoint for messages that you yourself sent. While harmless, it's a wasted API call. Most CRM logic should focus exclusively on incoming (unread) messages.\n- **Security Key Resync**: In rare cases, if a session is under heavy load, a \"Seen\" packet might time out. Wawp provides an `acknowledged: true` flag in the response to confirm the proxy has forwarded the request to the network. If you receive a failure, verify the session status via [`/v2/session/status`](/v2/session/status).\n\n---\n\n## Summary of Capabilities:\n- Programmatically trigger the native WhatsApp \"Blue Ticks\" (Read Receipts).\n- Support for batch-marking multiple messages as seen in a single API call.\n- Synchronization of unread counters across all linked WhatsApp devices.\n- Native support for individual, group, and channel read receipting.\n- High-fidelity integration with CRM dashboards for agent activity tracking.\n- Reliable delivery confirmation via the Wawp proxy acknowledged delivery mesh.\n",
      "tips": [
        {
          "type": "positive",
          "title": "Customer Experience",
          "content": "Marking messages as seen shows your customers that you are active and attending to their needs."
        }
      ],
      "recommendations": [
        "Use this when a human agent opens a conversation to keep your CRM in sync with WhatsApp.",
        "Batch multiple message IDs in a single call to save API resources."
      ],
      "translations": {
        "ar": {
          "title": "تحديد الرسائل كمقروءة (Seen)",
          "description": "تحديد رسائل محددة أو دردشة كاملة كمقروءة (العلامات الزرقاء).",
          "extraInfo": "\n# مزامنة الحالة: إتقان محرك إيصالات القراءة\n\nتعد نقطة النهاية `/v2/send/seen` الآلية الأساسية لإدارة \"التواجد والانتباه\" داخل محادثة واتساب. في نظام واتساب البيئي، يعد الانتقال من العلامات الرمادية (تم التسليم) إلى العلامات الزرقاء (تمت القراءة) حدثاً عالي الأهمية يحدد توقعات المستخدم. من خلال تحديد الرسائل كمقروءة برمجياً، يمكنك مزامنة CRM المخصص الخاص بك، أو لوحة التحكم، أو حالة البوت مع واجهة واتساب الأصلية، مما يضمن شعور العميل بأنه مسموع وبقاء مساحة عمل الوكيل منظمة.\n\n---\n\n## 🏗️ مسار إيصالات القراءة\n\nتحديد الرسالة كـ \"مقروءة\" هو حدث مزامنة ثنائي الاتجاه يتعامل معه Wawp:\n1. **تحديد الهدف**: يستقبل المحرك مصفوفة من `messageIds`. هذه المعرفات هي تجزئات تشفيرية فريدة يتم إنشاؤها عند إرسال الرسالة أو استلامها لأول مرة. يقوم Wawp بتحديد مكان هذه الإدخالات المحددة داخل مخزن الرسائل المحلي للجلسة.\n2. **بث العلامات الزرقاء**: بمجرد تحديد الهوية، يرسل Wawp حزمة \"تأكيد قراءة\" متخصصة عبر WhatsApp WebSocket. يتم بعد ذلك نشر هذه الحزمة إلى جهاز المرسل الأصلي، حيث تتحول علامات التسليم فوراً إلى اللون الأزرق.\n3. **مسح الرسائل غير المقروءة داخلياً**: بالتزامن مع ذلك، يوجه Wawp شبكة واتساب لمسح شارة \"عدد الرسائل غير المقروءة\" لتلك الدردشة المحددة على جميع الأجهزة المرتبطة (مثلاً، إذا كان لديك WhatsApp Web أو Desktop مفتوحاً بجانب مثيل API الخاص بك).\n\n---\n\n## 🛡️ أفضل الممارسات الاستراتيجية لإدارة القراءة\n\n### 1. مزامنة \"الإنسان في الحلقة\" (Human-in-the-Loop)\nتتطلب أتمتة إيصالات القراءة مواءمة دقيقة مع نشاط الوكيل الفعلي.\n- **سير العمل**: لا تقم بتشغيل `/v2/send/seen` إلا عندما يقوم الوكيل *بفتح* الدردشة فعلياً في لوحة التحكم المخصصة الخاصة بك.\n- **تأثير تجربة المستخدم**: إذا قمت بتحديد كل شيء كمقروء تلقائياً، يتوقع العميل رداً فورياً. إذا لم يكن الوكيل موجوداً بالفعل، فإنك تخلق \"فجوة استجابة\" تؤدي إلى إحباط العميل.\n\n### 2. التجميع عالي الكفاءة (Batching)\nيدعم Wawp تجميع رسائل متعددة في استدعاء API واحد لسبب وجيه.\n- **التنفيذ**: إذا أرسل المستخدم خمس رسائل (نص، صورة، ثم مزيد من النصوص) أثناء غياب وكيلك، فلا تستدعي نقطة نهاية seen خمس مرات. بدلاً من ذلك، اجمع المعرفات الخمسة `messageIds` وأرسلها في مصفوفة واحدة.\n- **الأداء**: يقلل التجميع من عدد عمليات نقل WebSocket، مما يحافظ على عرض النطاق الترددي لمثيلك ويقلل الحمل على شبكة واتساب.\n\n### 3. محاكاة القراءة الطبيعية (استراتيجية التأخير)\nالبوتات التي تستجيب فوراً وتحدد الرسائل كمقروءة في أجزاء من الثانية غالباً ما تبدو \"روبوتية\" وغير بشرية.\n- **توصية**: لتدفقات البوت المؤتمتة، قم بتنفيذ تأخير بسيط وعشوائي (مثلاً من 800 ملي ثانية إلى ثانيتين) بين استلام الرسالة وتحديدها كمقروءة. يحاكي هذا العملية البشرية لالتقاط الهاتف وقراءة الرسالة، مما يجعل التفاعل يبدو أكثر طبيعية.\n\n---\n\n## 🧩 حالات استخدام متقدمة\n\n### تتبع \"الفتح\" في CRM الأصلي\nإذا كنت تقوم ببناء CRM مخصص فوق Wawp، استخدم نقطة نهاية seen لتتبع أداء الوكلاء. من خلال قياس الوقت بين الـ Webhook الخاص بـ `message.received` واستدعاء نظامك لـ `/v2/send/seen`، يمكنك حساب \"متوسط وقت العرض\"، وهو مؤشر أداء رئيسي (KPI) حاسم لفرق الدعم.\n\n### \"فرز\" تدفق البوت\nفي بوت متعدد المراحل، يمكنك استخدام إيصالات القراءة للإشارة إلى مراحل معينة. على سبيل المثال، حدد استفسار المستخدم الأولي كمقروء فقط بعد أن ينجح البوت في تصنيف القصد. يوفر هذا للمستخدم تأكيداً مرئياً بأن النظام قد \"فهم\" المدخلات وهو الآن يعالج النتيجة.\n\n---\n\n## 🛠️ المزالق الشائعة والحلول\n\n- **معرف المشارك (في المجموعات)**: في الدردشات الجماعية، يتطلب تحديد الرسالة كمقروءة `chatId` للمجموعة واختيارياً معرف المشارك `participant` للمرسل الأصلي. إذا أغفلت معرف المشارك في البيئات الجماعية عالية التزامن، قد تفشل بعض إصدارات المحرك في تحديد تجزئة الرسالة المحددة، مما يؤدي إلى خطأ في الإيصال.\n- **حلقات \"المقروء بالفعل\"**: تجنب استدعاء نقطة النهاية seen للرسائل التي أرسلتها أنت بنفسك. على الرغم من أنها غير ضارة، إلا أنها استدعاء API ضائع. يجب أن يركز معظم منطق CRM حصرياً على الرسائل الواردة (غير المقروءة).\n- **مزامنة مفاتيح الأمان**: في حالات نادرة، إذا كان الجلسة تحت حمل ثقيل، قد تنتهي مهلة حزمة \"Seen\". يوفر Wawp علامة `acknowledged: true` في الاستجابة للتأكيد على أن البروكسي قد مرر الطلب للشبكة. إذا تلقيت فشلاً، تحقق من حالة الجلسة عبر [`/v2/session/status`](/v2/session/status).\n\n---\n\n## ملخص الإمكانيات:\n- تشغيل علامات واتساب الزرقاء (إيصالات القراءة) برمجياً.\n- دعم تحديد رسائل متعددة كمقروءة في استدعاء API واحد.\n- مزامنة عدادات الرسائل غير المقروءة عبر جميع أجهزة واتساب المرتبطة.\n- دعم أصلي لإيصالات القراءة للفرد، المجموعات، والقنوات.\n- تكامل عالي الدقة مع لوحات تحكم CRM لتتبع نشاط الوكلاء.\n- تأكيد تسليم موثوق عبر شبكة تسليم بروكسي Wawp.\n",
          "args": {
            "instance_id": {
              "description": "المعرف الفريد لجلسة واتساب"
            },
            "access_token": {
              "description": "رمز وصول API الخاص بك"
            },
            "chatId": {
              "description": "رقم الهاتف المستهدف أو معرف المجموعة"
            },
            "messageIds": {
              "description": "مصفوفة من معرفات الرسائل لتحديدها كمقروءة."
            },
            "participant": {
              "description": "المشارك الذي أرسل الرسالة (للمجموعات)."
            }
          },
          "tips": [
            {
              "title": "تجربة العملاء",
              "content": "يظهر تحديد الرسائل كمقروءة لعملائك أنك نشط وتهتم باحتياجاتهم."
            }
          ]
        }
      }
    },
    {
      "path": "/v2/send/start-typing",
      "methods": [
        "POST"
      ],
      "title": "Start Typing",
      "category": "Send Messages",
      "description": "Show the 'typing...' or 'recording audio...' status in a chat.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Target phone number or group ID",
          "example": "447441429009@c.us"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Message Sent Successfully",
          "contentType": "application/json",
          "example": {
            "_data": {
              "id": {
                "fromMe": true,
                "remote": "000000000000@c.us",
                "id": "MSG_ID_123456",
                "_serialized": "true_000000000000@c.us_MSG_ID_123456"
              },
              "viewed": false,
              "body": "BASE64_IMAGE_DATA",
              "type": "image",
              "t": 1759108866,
              "from": {
                "server": "c.us",
                "user": "111111111111",
                "_serialized": "111111111111@c.us"
              },
              "to": {
                "server": "c.us",
                "user": "000000000000",
                "_serialized": "000000000000@c.us"
              },
              "ack": 0,
              "isNewMsg": true,
              "star": false,
              "kicNotified": false,
              "caption": "Here's your requested image.",
              "deprecatedMms3Url": "https://example.com/media-url",
              "directPath": "/media/direct/path/example",
              "mimetype": "image/jpeg",
              "filehash": "FILE_HASH_PLACEHOLDER",
              "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
              "size": 192487,
              "mediaKey": "MEDIA_KEY_PLACEHOLDER",
              "mediaKeyTimestamp": 1759108865,
              "streamable": false,
              "mediaHandle": null,
              "isFromTemplate": false,
              "pollInvalidated": false,
              "isSentCagPollCreation": false,
              "latestEditMsgKey": null,
              "latestEditSenderTimestampMs": null,
              "mentionedJidList": [],
              "groupMentions": [],
              "isEventCanceled": false,
              "eventInvalidated": false,
              "isVcardOverMmsDocument": false,
              "isForwarded": false,
              "isQuestion": false,
              "questionReplyQuotedMessage": null,
              "questionResponsesCount": 0,
              "readQuestionResponsesCount": 0,
              "labels": [],
              "hasReaction": false,
              "disappearingModeInitiator": "chat",
              "disappearingModeTrigger": "chat_settings",
              "productHeaderImageRejected": false,
              "lastPlaybackProgress": 0,
              "isDynamicReplyButtonsMsg": false,
              "isCarouselCard": false,
              "parentMsgId": null,
              "callSilenceReason": null,
              "isVideoCall": false,
              "callDuration": null,
              "callCreator": null,
              "callParticipants": null,
              "isCallLink": null,
              "callLinkToken": null,
              "isMdHistoryMsg": false,
              "stickerSentTs": 0,
              "lastUpdateFromServerTs": 0,
              "invokedBotWid": null,
              "bizBotType": null,
              "botResponseTargetId": null,
              "botPluginType": null,
              "botPluginReferenceIndex": null,
              "botPluginSearchProvider": null,
              "botPluginSearchUrl": null,
              "botPluginSearchQuery": null,
              "botPluginMaybeParent": false,
              "botReelPluginThumbnailCdnUrl": null,
              "botMessageDisclaimerText": null,
              "botMsgBodyType": null,
              "requiresDirectConnection": false,
              "bizContentPlaceholderType": null,
              "hostedBizEncStateMismatch": false,
              "senderOrRecipientAccountTypeHosted": false,
              "placeholderCreatedWhenAccountIsHosted": false,
              "galaxyFlowDisabled": false,
              "links": []
            },
            "mediaKey": "MEDIA_KEY_PLACEHOLDER",
            "id": {
              "fromMe": true,
              "remote": "000000000000@c.us",
              "id": "MSG_ID_123456",
              "_serialized": "true_000000000000@c.us_MSG_ID_123456"
            },
            "ack": 0,
            "hasMedia": true,
            "body": "Here's your requested image.",
            "type": "image",
            "timestamp": 1759108866,
            "from": "111111111111@c.us",
            "to": "000000000000@c.us",
            "deviceType": "android",
            "isForwarded": false,
            "forwardingScore": 0,
            "isStatus": false,
            "isStarred": false,
            "fromMe": true,
            "hasQuotedMsg": false,
            "hasReaction": false,
            "vCards": [],
            "mentionedIds": [],
            "groupMentions": [],
            "isGif": false,
            "links": []
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Egypt)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Egypt mobile numbers must be 11 digits (national format).",
            "details": {
              "provided": "20114520282",
              "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
              "info": {
                "country": "EG",
                "type": "MOBILE"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Saudi Arabia)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for SA.",
            "details": {
              "provided": "96655555",
              "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
              "info": {
                "country": "SA"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Unknown)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for Unknown.",
            "details": {
              "provided": "01145202826",
              "recommendation": "Ensure individual numbers are in international format (starting with country code).",
              "info": {
                "country": "Unknown"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 429,
          "description": "Too Many Requests - Rate Limit Exceeded",
          "contentType": "application/json",
          "example": {
            "code": "rate_limit_exceeded",
            "message": "Too many requests. Please slow down.",
            "details": {
              "retryAfter": 60,
              "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
              "upstream": {
                "error": "Rate limit",
                "statusCode": 429
              }
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "extraInfo": "\n# Organic Presence: Mastering the Start Typing Engine\n\nThe `/v2/send/start-typing\", endpoint is a non-visual, high-impact tool for managing user psychology and conversational expectations. In a world where instant bot replies can often feel robotic and impersonal, the \"typing...\" indicator serves as a bridge of human mimicry. By explicitly signaling that a response is in progress, you reduce user anxiety, prevent \"double-texting\" from impatient customers, and create a premium, \"Human-in-the-Loop\" experience for your automated flows.\n\n---\n\n## 🏗️ The Presence and Attention Pipeline\n\nWhen you trigger the `/start-typing` endpoint, Wawp initiates a \"Presence Broadcast\" across the WhatsApp network:\n1. **Signaling Initialization**: The engine sends a specialized `COMPOSE` packet to the chat identified by `chatId`. This packet instructs the recipient's phone to render the \"typing...\" text in the top bar of the chat window and the animated bubble in the message thread.\n2. **Ephemeral Persistence**: Unlike a message, this status is ephemeral. WhatsApp naturally clears it after approximately 10–20 seconds if no further activity is detected. However, Wawp allows you to maintain this status for longer durations by periodically re-calling the endpoint.\n3. **Multi-Platform Sync**: The \"typing...\" indicator is synchronized across the recipient's entire account—appearing on their mobile phone, WhatsApp Web, and Desktop apps simultaneously.\n\n---\n\n## 🛡️ Strategic Best Practices for Organic Simulation\n\n### 1. The \"Think Time\" Strategy\nInstantaneous text replies from a bot are a clear giveaway that no human is present. \n- **Implementation**: When your backend receives a `message.received` webhook, call `/v2/send/start-typing` immediately. Then, calculate your AI response or perform your database query, and wait a minimum of 2–3 seconds before sending the final [`/v2/send/text`](/v2/send/text).\n- **UX Impact**: This brief pause with a \"typing...\" status makes the interaction feel like a considered reply from an attentive agent, significantly increasing user satisfaction and trust.\n\n### 2. Managing impetuous Users\nUsers often send several messages in a row (\"Hello?\", \"Are you there?\", \"I have a question\").\n- **Best Practice**: As soon as you detect any activity, trigger `/start-typing`. This visual feedback often stops a user from sending follow-up messages, as they can see a response is already being formulated.\n\n### 3. Coordinate with Media Prep\nLarge videos or PDFs can take a few seconds to process and upload.\n- **Workflow**: If you are about to send a high-resolution image or a long video, start the \"typing...\" indicator during the file-fetch phase. This fills the dead air and ensures the user doesn't close the chat thinking the bot has crashed.\n\n---\n\n## 🧩 Advanced Use Cases\n\n### High-Fidelity Bot Mimicry\nBuild a \"Humanized AI\" by varying the duration of the typing status based on the length of the predicted response. If the AI is about to send a 500-word explanation, show \"typing...\" for 4 seconds. If it's a simple \"Yes,\" show it for only 1 second. This level of detail makes the bot virtually indistinguishable from a human agent at first glance.\n\n### Interactive Voice Preparation\nIf your bot is about to send a Voice Note (`/v2/send/voice`), you can actually signal that you are \"recording audio...\" (on supported engine versions). This alerts the user to turn up their volume and prepare for a non-textual interaction, smoothing the transition between media types.\n\n---\n\n## 🛠️ Common Pitfalls and Solutions\n\n- **The \"Stuck Typing\" Bug**: If you call `/start-typing` but then your backend crashes before sending the message, the user might see \"typing...\" for a long time only for it to disappear without a response. **Solution**: Use a `try...finally` block in your code to ensure that a [`/v2/send/stop-typing`](/v2/send/stop-typing) or a final message is always sent.\n- **Over-Scheduling**: Calling the start-typing endpoint every 100ms is unnecessary and can be flagged as \"Abusive Behavior\" by the WhatsApp network. We recommend a frequency of no more than once every 5–10 seconds if you need to sustain the indicator for a long-duration task.\n- **Group Chaos**: In very large groups, excessive typing indicators from a bot can become distracting. Use this feature sparingly in group environments, focusing primarily on 1-on-1 customer support situations.\n\n---\n\n## Summary of Capabilities:\n- Explicitly trigger the native WhatsApp \"typing...\" or \"recording audio...\" indicators.\n- High-fidelity organic simulation for bot and human-agent flows.\n- Real-time presence broadcasting to individual, group, and channel recipients.\n- Ephemeral state management with automatic network-level timeouts.\n- Essential tool for managing user expectations and reducing conversational friction.\n- Seamless coordination with text, media, and document delivery endpoints.\n",
      "tips": [
        {
          "type": "info",
          "title": "Bot Strategy",
          "content": "Using typing status increases trust as it mimics a human agent preparing a response."
        }
      ],
      "recommendations": [
        "Call this 2-3 seconds before sending the actual text message.",
        "Use webhooks to detect when a user starts typing to your bot as well."
      ],
      "translations": {
        "ar": {
          "title": "بدء الكتابة (Start Typing)",
          "description": "إظهار حالة 'يكتب الآن...' أو 'يسجل مقطعاً صوتياً...' في الدردشة.",
          "extraInfo": "\n# التواجد العضوي: إتقان محرك \"بدء الكتابة\"\n\nتعد نقطة النهاية `/v2/send/start-typing` أداة غير مرئية لكنها عالية التأثير لإدارة نفسية المستخدم وتوقعات الحوار. في عالم يمكن أن تبدو فيه ردود البوت الفورية آلية وغير شخصية، تبرز ميزة \"يكتب الآن...\" كجسر للمحاكاة البشرية. من خلال الإشارة صراحة إلى أن الرد قيد التحضير، يمكنك تقليل قلق المستخدم، ومنع \"المراسلة المزدوجة\" من العملاء غير الصبورين، وخلق تجربة متميزة تشعره بوجود \"إنسان في الحلقة\" حتى في تدفقاتك المؤتمتة.\n\n---\n\n## 🏗️ مسار التواجد والانتباه\n\nعندما تقوم بتشغيل نقطة النهاية `/start-typing`، يبدأ Wawp \"بث تواجد\" عبر شبكة واتساب:\n1. **بدء الإشارة**: يرسل المحرك حزمة `COMPOSE` متخصصة إلى الدردشة المحددة بواسطة `chatId`. توجه هذه الحزمة هاتف المستلم لعرض نص \"يكتب الآن...\" في الشريط العلوي لنافذة الدردشة والفقاعة المتحركة في خيط الرسائل.\n2. **الاستمرارية المؤقتة**: على عكس الرسالة، هذه الحالة مؤقتة بطبيعتها. يقوم واتساب بمسحها تلقائياً بعد حوالي 10-20 ثانية إذا لم يتم اكتشاف أي نشاط إضافي. ومع ذلك، يتيح لك Wawp الحفاظ على هذه الحالة لفترات أطول من خلال استدعاء نقطة النهاية بشكل دوري.\n3. **المزامنة متعددة المنصات**: يتم مزامنة مؤشر \"يكتب الآن...\" عبر حساب المستلم بالكامل—فيظهر على هاتفه المحمول، WhatsApp Web، وتطبيقات سطح المكتب في وقت واحد.\n\n---\n\n## 🛡️ أفضل الممارسات الاستراتيجية للمحاكاة العضوية\n\n### 1. استراتيجية \"وقت التفكير\"\nالردود النصية الفورية من البوت هي دليل واضح على عدم وجود إنسان.\n- **التنفيذ**: عندما يتلقى نظامك الخلفي Webhook لـ `message.received`، استدعِ `/v2/send/start-typing` فوراً. ثم، احسب رد الذكاء الاصطناعي أو قم بإجراء استعلام قاعدة البيانات، وانتظر ما لا يقل عن 2-3 ثوانٍ قبل إرسال الرسالة النهائية عبر [`/v2/send/text`](/v2/send/text).\n- **تأثير تجربة المستخدم**: هذا التوقف القصير مع حالة \"يكتب الآن...\" يجعل التفاعل يبدو وكأنه رد مدروس من وكيل مهتم، مما يزيد بشكل كبير من رضا المستخدم وثقته.\n\n### 2. إدارة المستخدمين المندفعين\nغالباً ما يرسل المستخدمون عدة رسائل متتالية (\"مرحباً؟\"، \"هل أنت هناك؟\"، \"لدي سؤال\").\n- **أفضل ممارسة**: بمجرد اكتشاف أي نشاط، قم بتشغيل `/start-typing`. هذه الملاحظة المرئية غالباً ما توقف المستخدم عن إرسال رسائل متابعة، حيث يمكنه رؤية أن الرد يتم صياغته بالفعل.\n\n### 3. التنسيق مع تحضير الوسائط\nيمكن أن تستغرق ملفات الفيديو الكبيرة أو ملفات PDF بضع ثوانٍ للمعالجة والرفع.\n- **سير العمل**: إذا كنت على وشك إرسال صورة عالية الدقة أو فيديو طويلاً، فابدأ مؤشر \"يكتب الآن...\" أثناء مرحلة جلب الملف. يملأ هذا وقت الفراغ ويضمن عدم إغلاق المستخدم للدردشة ظناً منه أن البوت قد تعطل.\n\n---\n\n## 🧩 حالات استخدام متقدمة\n\n### المحاكاة البشرية عالية الدقة\nقم ببناء \"ذكاء اصطناعي مؤنس\" من خلال تنويع مدة حالة الكتابة بناءً على طول الرد المتوقع. إذا كان الذكاء الاصطناعي على وشك إرسال شرح من 500 كلمة، أظهر حالة \"يكتب الآن...\" لمدة 4 ثوانٍ. إذا كان مجرد رد \"نعم\" بسيط، أظهرها لمدة ثانية واحدة فقط. هذا المستوى من التفاصيل يجعل البوت غير قابل للتمييز تقريباً عن الوكيل البشري للوهلة الأولى.\n\n### تحضير الصوت التفاعلي\nإذا كان البوت الخاص بك على وشك إرسال ملاحظة صوتية (`/v2/send/voice`)، يمكنك بالفعل الإشارة إلى أنك \"يسجل مقطعاً صوتياً...\" (في إصدارات المحرك المدعومة). ينبه هذا المستخدم لرفع مستوى الصوت والاستعداد لتفاعل غير نصي، مما يسهل الانتقال بين أنواع الوسائط.\n\n---\n\n## 🛠️ المزالق الشائعة والحلول\n\n- **خطأ \"الكتابة العالقة\"**: إذا استدعيت `/start-typing` ولكن نظامك الخلفي تعطل قبل إرسال الرسالة، فقد يرى المستخدم \"يكتب الآن...\" لفترة طويلة ثم تختفي دون رد. **الحل**: استخدم كتلة `try...finally` في كودك لضمان إرسال [`/v2/send/stop-typing`](/v2/send/stop-typing) أو رسالة نهائية دائماً.\n- **الجدولة المفرطة**: استدعاء نقطة النهاية start-typing كل 100 ملي ثانية غير ضروري ويمكن اعتباره \"سلوكاً مسيئاً\" من قبل شبكة واتساب. نوصي بتردد لا يزيد عن مرة واحدة كل 5-10 ثوانٍ إذا كنت بحاجة للحفاظ على المؤشر لمهمة طويلا الأمد.\n- **الفوضى في المجموعات**: في المجموعات الكبيرة جداً، يمكن أن تصبح مؤشرات الكتابة المفرطة من البوت مشتتة للانتباه. استخدم هذه الميزة بحذر في البيئات الجماعية، مع التركيز بشكل أساسي على حالات دعم العملاء الفردية.\n\n---\n\n## ملخص الإمكانيات:\n- تشغيل مؤشرات واتساب الأصلية لـ \"يكتب الآن...\" أو \"يسجل مقطعاً صوتياً...\" صراحة.\n- محاكاة عضوية عالية الدقة لتدفقات البوت والوكيل البشري.\n- بث التواجد في الوقت الفعلي للمستلمين الأفراد، المجموعات، والقنوات.\n- إدارة حالة مؤقتة مع مهلات تلقائية على مستوى الشبكة.\n- أداة أساسية لإدارة توقعات المستخدم وتقليل الاحتكاك الحواري.\n- تنسيق سلس مع نقاط نهاية تسليم النصوص والوسائط والمستندات.\n",
          "args": {
            "instance_id": {
              "description": "المعرف الفريد لجلسة واتساب"
            },
            "access_token": {
              "description": "رمز وصول API الخاص بك"
            },
            "chatId": {
              "description": "رقم الهاتف المستهدف أو معرف المجموعة"
            }
          },
          "tips": [
            {
              "title": "استراتيجية البوت",
              "content": "استخدام حالة الكتابة يزيد من الثقة لأنها تحاكي وكيلاً بشرياً يحضر الرد."
            }
          ]
        }
      }
    },
    {
      "path": "/v2/send/stop-typing",
      "methods": [
        "POST"
      ],
      "title": "Stop Typing",
      "category": "Send Messages",
      "description": "Remove the 'typing...' or 'recording audio...' status from a chat.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Target phone number or group ID",
          "example": "447441429009@c.us"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Message Sent Successfully",
          "contentType": "application/json",
          "example": {
            "_data": {
              "id": {
                "fromMe": true,
                "remote": "000000000000@c.us",
                "id": "MSG_ID_123456",
                "_serialized": "true_000000000000@c.us_MSG_ID_123456"
              },
              "viewed": false,
              "body": "BASE64_IMAGE_DATA",
              "type": "image",
              "t": 1759108866,
              "from": {
                "server": "c.us",
                "user": "111111111111",
                "_serialized": "111111111111@c.us"
              },
              "to": {
                "server": "c.us",
                "user": "000000000000",
                "_serialized": "000000000000@c.us"
              },
              "ack": 0,
              "isNewMsg": true,
              "star": false,
              "kicNotified": false,
              "caption": "Here's your requested image.",
              "deprecatedMms3Url": "https://example.com/media-url",
              "directPath": "/media/direct/path/example",
              "mimetype": "image/jpeg",
              "filehash": "FILE_HASH_PLACEHOLDER",
              "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
              "size": 192487,
              "mediaKey": "MEDIA_KEY_PLACEHOLDER",
              "mediaKeyTimestamp": 1759108865,
              "streamable": false,
              "mediaHandle": null,
              "isFromTemplate": false,
              "pollInvalidated": false,
              "isSentCagPollCreation": false,
              "latestEditMsgKey": null,
              "latestEditSenderTimestampMs": null,
              "mentionedJidList": [],
              "groupMentions": [],
              "isEventCanceled": false,
              "eventInvalidated": false,
              "isVcardOverMmsDocument": false,
              "isForwarded": false,
              "isQuestion": false,
              "questionReplyQuotedMessage": null,
              "questionResponsesCount": 0,
              "readQuestionResponsesCount": 0,
              "labels": [],
              "hasReaction": false,
              "disappearingModeInitiator": "chat",
              "disappearingModeTrigger": "chat_settings",
              "productHeaderImageRejected": false,
              "lastPlaybackProgress": 0,
              "isDynamicReplyButtonsMsg": false,
              "isCarouselCard": false,
              "parentMsgId": null,
              "callSilenceReason": null,
              "isVideoCall": false,
              "callDuration": null,
              "callCreator": null,
              "callParticipants": null,
              "isCallLink": null,
              "callLinkToken": null,
              "isMdHistoryMsg": false,
              "stickerSentTs": 0,
              "lastUpdateFromServerTs": 0,
              "invokedBotWid": null,
              "bizBotType": null,
              "botResponseTargetId": null,
              "botPluginType": null,
              "botPluginReferenceIndex": null,
              "botPluginSearchProvider": null,
              "botPluginSearchUrl": null,
              "botPluginSearchQuery": null,
              "botPluginMaybeParent": false,
              "botReelPluginThumbnailCdnUrl": null,
              "botMessageDisclaimerText": null,
              "botMsgBodyType": null,
              "requiresDirectConnection": false,
              "bizContentPlaceholderType": null,
              "hostedBizEncStateMismatch": false,
              "senderOrRecipientAccountTypeHosted": false,
              "placeholderCreatedWhenAccountIsHosted": false,
              "galaxyFlowDisabled": false,
              "links": []
            },
            "mediaKey": "MEDIA_KEY_PLACEHOLDER",
            "id": {
              "fromMe": true,
              "remote": "000000000000@c.us",
              "id": "MSG_ID_123456",
              "_serialized": "true_000000000000@c.us_MSG_ID_123456"
            },
            "ack": 0,
            "hasMedia": true,
            "body": "Here's your requested image.",
            "type": "image",
            "timestamp": 1759108866,
            "from": "111111111111@c.us",
            "to": "000000000000@c.us",
            "deviceType": "android",
            "isForwarded": false,
            "forwardingScore": 0,
            "isStatus": false,
            "isStarred": false,
            "fromMe": true,
            "hasQuotedMsg": false,
            "hasReaction": false,
            "vCards": [],
            "mentionedIds": [],
            "groupMentions": [],
            "isGif": false,
            "links": []
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Egypt)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Egypt mobile numbers must be 11 digits (national format).",
            "details": {
              "provided": "20114520282",
              "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
              "info": {
                "country": "EG",
                "type": "MOBILE"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Saudi Arabia)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for SA.",
            "details": {
              "provided": "96655555",
              "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
              "info": {
                "country": "SA"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Unknown)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for Unknown.",
            "details": {
              "provided": "01145202826",
              "recommendation": "Ensure individual numbers are in international format (starting with country code).",
              "info": {
                "country": "Unknown"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 429,
          "description": "Too Many Requests - Rate Limit Exceeded",
          "contentType": "application/json",
          "example": {
            "code": "rate_limit_exceeded",
            "message": "Too many requests. Please slow down.",
            "details": {
              "retryAfter": 60,
              "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
              "upstream": {
                "error": "Rate limit",
                "statusCode": 429
              }
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "extraInfo": "\n# State Cleanup: Mastering the Stop Typing Engine\n\nThe `/v2/send/stop-typing` endpoint is the essential \"Cleanup Crew\" of the Wawp presence system. While simple in its objective—to remove the \"typing...\" or \"recording audio...\" indicators—it plays a critical role in maintaining the professional polish of your WhatsApp integration. In a high-stakes customer support or sales environment, a \"typing...\" indicator that lingers indefinitely without a resulting message is a significant UX failure that signals system malfunction or agent indecision.\n\n---\n\n## 🏗️ The Presence Termination Pipeline\n\nWhen you explicitly call `/stop-typing`, Wawp executes a coordinated cleanup across the WhatsApp stack:\n1. **The PAUSE Signal**: The engine transmits a specialized `PAUSE` packet to the target `chatId`. This packet instructs the recipient's WhatsApp client to immediately hide all presence indicators.\n2. **Override of Implicit Timeouts**: While WhatsApp has a native timeout (usually 10–20 seconds), explicit calls to `/stop-typing` provide instant feedback. This is crucial for fast-paced, multi-step conversational flows where states change rapidly.\n3. **Internal Buffer Clearance**: Wawp clears the local session's presence-tracking buffer to ensure that subsequent typing requests are treated as fresh starts, preventing \"Presence Stuttering\" on the recipient's UI.\n\n---\n\n## 🛡️ Strategic Best Practices for Presence Hygiene\n\n### 1. The \"Message-Sent\" Auto-Stop\nIt is a common misconception that you must call `/stop-typing` immediately before sending a message.\n- **Fact**: Sending *any* message (Text, Image, PDF, etc.) to a chat automatically triggers the \"Stop Typing\" behavior on the WhatsApp network.\n- **Optimization**: To save API calls and reduce latency, **do not** call `/v2/send/stop-typing` before or after sending your final message. The message delivery itself is the most efficient way to clear the status.\n\n### 2. Handling Workflow Cancellations\nThis is the most critical use case for the explicit stop endpoint.\n- **Scenario**: An agent starts a response in your CRM but then decides the inquiry belongs to a different department. They close the chat tab or transfer the ticket.\n- **Best Practice**: Your CRM should automatically trigger `/v2/send/stop-typing` whenever an agent's focus leaves a chat that was previously in a \"Typing\" state. This prevents the \"Phantom Agent\" effect where a customer sees someone typing for minutes with no result.\n\n### 3. Graceful AI Failure Recovery\nIf your AI backend (e.g., GPT-4 or Claude) times out or returns an error while a \"typing...\" indicator is active, your system must handle the cleanup.\n- **Implementation**: Wrap your AI generation logic in a `try...catch...finally` block. In the `finally` section, if no message was successfully sent, trigger `/v2/send/stop-typing`. This ensures that even in the event of a crash, the customer isn't left staring at a perpetual typing status.\n\n---\n\n## 🧩 Advanced Use Cases\n\n### The \"Search Transition\" UX\nIn complex bot flows where a user requests a search (e.g., \"Find my order\"), you can use [`/v2/send/start-typing`](/v2/send/start-typing) to show work is in progress. If the search returns 0 results, trigger `/v2/send/stop-typing` before sending the \"No results found\" text. This momentary clearing of the status creates a distinct visual \"Beat\" in the conversation, signaling that one phase of logic has ended and another (the error message) has begun.\n\n### Agent Transfer Synchronization\nWhen transferring a chat between human agents, the secondary agent may want to \"Pick up\" the thread quietly. Triggering `stop-typing` during the handoff ensures the transition is visually seamless for the customer, with no overlapping or conflicting indicators from two different sessions.\n\n---\n\n## 🛠️ Common Pitfalls and Solutions\n\n- **Double-Counting Latency**: If your network is slow, calling `/stop-typing` followed immediately by a message might cause the message to arrive before the stop signal is processed, leading to a brief flicker. **Solution**: Rely on the \"Auto-Stop\" property of messages whenever possible.\n- **Rate Limit Caution**: While presence signals are lightweight, WhatsApp still tracks the frequency of these specialized packets. Avoid sending more than 3 `stop-typing` calls per second to the same chat to ensure your instance maintains a high trust score.\n- **Group Environment Noise**: In group chats with 200+ participants, presence indicators can be noisy. Use `/stop-typing` only when an agent was definitely \"Active\" and now definitely is \"Not.\"\n\n---\n\n## Summary of Capabilities:\n- Explicitly terminate the \"typing...\" or \"recording audio...\" presence indicators.\n- Native integration with WhatsApp PAUSE signaling for instant recipient feedback.\n- Essential for cleaning up states after agent transfers or workflow cancellations.\n- Zero-latency override of standard 20-second network-level timeouts.\n- Foundation for reliable \"Try/Finally\" error handling in automated AI bot systems.\n- Ensures a polished, professional conversational aesthetic by preventing \"Phantom Typing.\"\n",
      "tips": [
        {
          "type": "warning",
          "title": "Auto-Stop",
          "content": "WhatsApp will naturally stop the typing indicator after ~10 seconds of inactivity even if you do not call this."
        }
      ],
      "recommendations": [
        "Consult the official documentation for detailed parameter descriptions.",
        "Test endpoints in a sandbox environment before production.",
        "Keep your API client library up to date."
      ],
      "translations": {
        "ar": {
          "title": "إيقاف الكتابة (Stop Typing)",
          "description": "إزالة حالة 'يكتب الآن...' أو 'يسجل مقطعاً صوتياً...' من الدردشة.",
          "extraInfo": "\n# تنظيف الحالة: إتقان محرك \"إيقاف الكتابة\"\n\nتعد نقطة النهاية `/v2/send/stop-typing` \"فريق التنظيف\" الأساسي في نظام تواجد Wawp. برغم بساطة هدفها—وهو إزالة مؤشرات \"يكتب الآن...\" أو \"يسجل مقطعاً صوتياً...\"—إلا أنها تلعب دوراً حاسماً في الحفاظ على الاحترافية في تكاملك مع واتساب. في بيئة دعم عملاء أو مبيعات عالية المخاطر، يعد مؤشر \"يكتب الآن...\" الذي يستمر لفترة طويلة دون رسالة ناتجة فشلاً كبيراً في تجربة المستخدم يشير إلى تعطل النظام أو تردد الوكيل.\n\n---\n\n## 🏗️ مسار إنهاء التواجد\n\nعندما تستدعي `/stop-typing` صراحة، يقوم Wawp بتنفيذ عملية تنظيف منسقة:\n1. **إشارة الإيقاف (PAUSE)**: يرسل المحرك حزمة `PAUSE` متخصصة إلى المستهدف `chatId`. توجه هذه الحزمة عميل واتساب الخاص بالمستلم لإخفاء جميع مؤشرات التواجد فوراً.\n2. **تجاوز المهلات التلقائية**: بينما تمتلك واتساب مهلة تلقائية (عادة من 10 إلى 20 ثانية)، توفر الاستدعاءات الصريحة لـ `/stop-typing` استجابة فورية. هذا أمر بالغ الأهمية للتدفقات الحوارية سريعة الوتيرة حيث تتغير الحالات بسرعة.\n3. **مسح التخزين المؤقت الداخلي**: يقوم Wawp بمسح مخزن تتبع التواجد للجلسة المحلية لضمان معاملة طلبات الكتابة اللاحقة كبدايات جديدة، مما يمنع \"تأتأة التواجد\" على واجهة مستخدم المستلم.\n\n---\n\n## 🛡️ أفضل الممارسات الاستراتيجية لنظام التواجد\n\n### 1. الإيقاف التلقائي عند إرسال رسالة\nمن المفاهيم الخاطئة الشائعة أنه يجب عليك استدعاء `/stop-typing` مباشرة قبل إرسال رسالة.\n- **حقيقة**: إرسال *أي* رسالة (نص، صورة، PDF، إلخ) إلى دردشة يؤدي تلقائياً إلى إطلاق سلوك \"إيقاف الكتابة\" على شبكة واتساب.\n- **تحسين**: لتوفير استدعاءات API وتقليل التأخير، **لا تستدعِ** `/v2/send/stop-typing` قبل أو بعد إرسال رسالتك النهائية. تسليم الرسالة نفسها هو الطريقة الأكثر كفاءة لمسح الحالة.\n\n### 2. التعامل مع إلغاء سير العمل\nهذه هي حالة الاستخدام الأكثر أهمية لنقطة النهاية الصريحة للإيقاف.\n- **سيناريو**: يبدأ الوكيل في كتابة رد في CRM الخاص بك ولكنه يقرر بعد ذلك أن الاستفسار ينتمي إلى قسم آخر. يغلق علامة تبويب الدردشة أو ينقل التذكرة.\n- **أفضل ممارسة**: يجب أن يقوم CRM الخاص بك تلقائياً بتشغيل `/v2/send/stop-typing` كلما غادر تركيز الوكيل دردشة كانت في حالة \"كتابة\" سابقاً. هذا يمنع تأثير \"الوكيل الوهمي\" حيث يرى العميل شخصاً يكتب لعدة دقائق دون نتيجة.\n\n### 3. التعافي من فشل الذكاء الاصطناعي\nإذا تعطل نظام الذكاء الاصطناعي الخلفي الخاص بك أو أرجع خطأً أثناء تفعيل مؤشر \"يكتب الآن...\"، يجب على نظامك التعامل مع التنظيف.\n- **التنفيذ**: غلف منطق توليد الذكاء الاصطناعي في كتلة `try...catch...finally`. في قسم `finally`، إذا لم يتم إرسال أي رسالة بنجاح، قم بتشغيل `/v2/send/stop-typing`. يضمن ذلك أنه حتى في حالة حدوث عطل، لن يظل العميل محدقاً في حالة كتابة أبدية.\n\n---\n\n## 🧩 حالات استخدام متقدمة\n\n### تجربة مستخدم \"ما بعد البحث\"\nفي تدفقات البوت المعقدة حيث يطلب المستخدم بحثاً (مثل \"ابحث عن طلبي\")، يمكنك استخدام [`/v2/send/start-typing`](/v2/send/start-typing) لإظهار أن العمل جارٍ. إذا أرجع البحث 0 نتيجة، قم بتشغيل `/v2/send/stop-typing` قبل إرسال نص \"لم يتم العثور على نتائج\". يخلق هذا المسح اللحظي للحالة \"نبضة\" بصرية متميزة في المحادثة، مما يشير إلى انتهاء مرحلة من المنطق وبدء مرحلة أخرى (رسالة الخطأ).\n\n### مزامنة نقل الوكيل\nعند نقل دردشة بين وكلاء بشريين، قد يرغب الوكيل الثاني في \"استلام\" الخيط بهدوء. يضمن تشغيل `stop-typing` أثناء التسليم أن يكون الانتقال سلساً بصرياً للعميل، دون وجود مؤشرات متداخلة أو متضاربة من جلستين مختلفتين.\n\n---\n\n## 🛠️ المزالق الشائعة والحلول\n\n- **تأخير العد المزدوج**: إذا كانت شبكتك بطيئة، فإن استدعاء `/stop-typing` متبوعاً برسالة مباشرة قد يتسبب في وصول الرسالة قبل معالجة إشارة التوقف، مما يؤدي إلى ارتعاش بصري بسيط. **الحل**: اعتمد على خاصية \"الإيقاف التلقائي\" للرسائل كلما أمكن ذلك.\n- **الحذر من حدود المعدل**: بينما إشارات التواجد خفيفة الوزن، لا تزال واتساب تتبع وتيرة هذه الحزم المتخصصة. تجنب إرسال أكثر من 3 استدعاءات `stop-typing` في الثانية إلى نفس الدردشة لضمان محافظة مثيلك على درجة ثقة عالية.\n- **الضوضاء في بيئة المجموعات**: في المجموعات التي تضم أكثر من 200 مشارك، يمكن أن تكون مؤشرات التواجد مزعجة. استخدم `/stop-typing` فقط عندما كان الوكيل \"نشطاً\" بالتأكيد والآن هو \"غير نشط\" بالتأكيد.\n\n---\n\n## ملخص الإمكانيات:\n- إنهاء مؤشرات التواجد \"يكتب الآن...\" أو \"يسجل مقطعاً صوتياً...\" صراحة.\n- تكامل أصلي مع إشارات PAUSE في واتساب لردود فعل فورية للمستلم.\n- ضروري لتنظيف الحالات بعد نقل الوكلاء أو إلغاء سير العمل.\n- تجاوز فوري لمهلات الشبكة القياسية التي تبلغ 20 ثانية.\n- أساس للتعامل الموثوق مع الأخطاء (Try/Finally) في أنظمة بوت الذكاء الاصطناعي المؤتمتة.\n- يضمن جمالية حوارية مصقولة واحترافية من خلال منع \"الكتابة الوهمية\".\n",
          "args": {
            "instance_id": {
              "description": "المعرف الفريد لجلسة واتساب"
            },
            "access_token": {
              "description": "رمز وصول API الخاص بك"
            },
            "chatId": {
              "description": "رقم الهاتف المستهدف أو معرف المجموعة"
            }
          },
          "tips": [
            {
              "title": "إيقاف تلقائي",
              "content": "ستتوقف واتساب طبيعياً عن عرض مؤشر الكتابة بعد حوالي 10 ثوانٍ من عدم النشاط حتى لو لم تستدعِ هذه النقطة."
            }
          ]
        }
      }
    },
    {
      "path": "/v2/send/reaction",
      "methods": [
        "PUT"
      ],
      "title": "Reaction",
      "category": "Send Messages",
      "description": "React to a specific message with an emoji (👍, ❤️, 😂, etc.).",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Recipient's WhatsApp ID (JID). Supports Individuals (@c.us), Groups (@g.us), and Newsletters (@newsletter).",
          "example": "447441429009@c.us"
        },
        "messageId": {
          "required": true,
          "type": "string",
          "description": "The ID of the message you want to react to.",
          "example": "false_20123456789@c.us_3F351BFA105BA281C054"
        },
        "reaction": {
          "required": true,
          "type": "string",
          "description": "The emoji reaction. Use an empty string to remove.",
          "example": "👍"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Message Sent Successfully",
          "contentType": "application/json",
          "example": {
            "_data": {
              "id": {
                "fromMe": true,
                "remote": "000000000000@c.us",
                "id": "MSG_ID_123456",
                "_serialized": "true_000000000000@c.us_MSG_ID_123456"
              },
              "viewed": false,
              "body": "BASE64_IMAGE_DATA",
              "type": "image",
              "t": 1759108866,
              "from": {
                "server": "c.us",
                "user": "111111111111",
                "_serialized": "111111111111@c.us"
              },
              "to": {
                "server": "c.us",
                "user": "000000000000",
                "_serialized": "000000000000@c.us"
              },
              "ack": 0,
              "isNewMsg": true,
              "star": false,
              "kicNotified": false,
              "caption": "Here's your requested image.",
              "deprecatedMms3Url": "https://example.com/media-url",
              "directPath": "/media/direct/path/example",
              "mimetype": "image/jpeg",
              "filehash": "FILE_HASH_PLACEHOLDER",
              "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
              "size": 192487,
              "mediaKey": "MEDIA_KEY_PLACEHOLDER",
              "mediaKeyTimestamp": 1759108865,
              "streamable": false,
              "mediaHandle": null,
              "isFromTemplate": false,
              "pollInvalidated": false,
              "isSentCagPollCreation": false,
              "latestEditMsgKey": null,
              "latestEditSenderTimestampMs": null,
              "mentionedJidList": [],
              "groupMentions": [],
              "isEventCanceled": false,
              "eventInvalidated": false,
              "isVcardOverMmsDocument": false,
              "isForwarded": false,
              "isQuestion": false,
              "questionReplyQuotedMessage": null,
              "questionResponsesCount": 0,
              "readQuestionResponsesCount": 0,
              "labels": [],
              "hasReaction": false,
              "disappearingModeInitiator": "chat",
              "disappearingModeTrigger": "chat_settings",
              "productHeaderImageRejected": false,
              "lastPlaybackProgress": 0,
              "isDynamicReplyButtonsMsg": false,
              "isCarouselCard": false,
              "parentMsgId": null,
              "callSilenceReason": null,
              "isVideoCall": false,
              "callDuration": null,
              "callCreator": null,
              "callParticipants": null,
              "isCallLink": null,
              "callLinkToken": null,
              "isMdHistoryMsg": false,
              "stickerSentTs": 0,
              "lastUpdateFromServerTs": 0,
              "invokedBotWid": null,
              "bizBotType": null,
              "botResponseTargetId": null,
              "botPluginType": null,
              "botPluginReferenceIndex": null,
              "botPluginSearchProvider": null,
              "botPluginSearchUrl": null,
              "botPluginSearchQuery": null,
              "botPluginMaybeParent": false,
              "botReelPluginThumbnailCdnUrl": null,
              "botMessageDisclaimerText": null,
              "botMsgBodyType": null,
              "requiresDirectConnection": false,
              "bizContentPlaceholderType": null,
              "hostedBizEncStateMismatch": false,
              "senderOrRecipientAccountTypeHosted": false,
              "placeholderCreatedWhenAccountIsHosted": false,
              "galaxyFlowDisabled": false,
              "links": []
            },
            "mediaKey": "MEDIA_KEY_PLACEHOLDER",
            "id": {
              "fromMe": true,
              "remote": "000000000000@c.us",
              "id": "MSG_ID_123456",
              "_serialized": "true_000000000000@c.us_MSG_ID_123456"
            },
            "ack": 0,
            "hasMedia": true,
            "body": "Here's your requested image.",
            "type": "image",
            "timestamp": 1759108866,
            "from": "111111111111@c.us",
            "to": "000000000000@c.us",
            "deviceType": "android",
            "isForwarded": false,
            "forwardingScore": 0,
            "isStatus": false,
            "isStarred": false,
            "fromMe": true,
            "hasQuotedMsg": false,
            "hasReaction": false,
            "vCards": [],
            "mentionedIds": [],
            "groupMentions": [],
            "isGif": false,
            "links": []
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Egypt)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Egypt mobile numbers must be 11 digits (national format).",
            "details": {
              "provided": "20114520282",
              "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
              "info": {
                "country": "EG",
                "type": "MOBILE"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Saudi Arabia)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for SA.",
            "details": {
              "provided": "96655555",
              "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
              "info": {
                "country": "SA"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Number (Unknown)",
          "contentType": "application/json",
          "example": {
            "code": "invalid_chat_id",
            "message": "Invalid phone number format for Unknown.",
            "details": {
              "provided": "01145202826",
              "recommendation": "Ensure individual numbers are in international format (starting with country code).",
              "info": {
                "country": "Unknown"
              }
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 429,
          "description": "Too Many Requests - Rate Limit Exceeded",
          "contentType": "application/json",
          "example": {
            "code": "rate_limit_exceeded",
            "message": "Too many requests. Please slow down.",
            "details": {
              "retryAfter": 60,
              "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
              "upstream": {
                "error": "Rate limit",
                "statusCode": 429
              }
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "extraInfo": "\n# Micro-Interactions: Mastering the Message Reaction Engine\n\nReactions (`/v2/send/reaction`) are one of the most powerful micro-interactions in a modern messaging ecosystem. They allow users and bots to acknowledge information, express sentiment, or provide feedback without the friction of a full text reply. In a Wawp-powered application, reactions aren't just cosmetic; they are structural signals that can be used to track engagement, build interactive voting systems, or simplify bot-to-user acknowledgements.\n\n---\n\n## 🏗️ The Reaction Lifecycle Architecture\n\nUnlike full messages, reactions are additive metadata attached to an existing message. Wawp’s reaction engine manages this attachment with high precision:\n1. **Target Identification**: The engine uses the `messageId` to locate the specific message on the WhatsApp backend. This must be the unique ID of an existing message in the chat identified by `chatId`.\n2. **Emoji Normalization**: While you can send any emoji, Wawp ensures the character is correctly encoded for the WhatsApp WebSocket. If you send an empty string (`\"\"`), the engine interprets this as a \"Delete Reaction\" command, instructing the WhatsApp network to remove your previous sentiment from that particular message.\n3. **Atomic Delivery**: Reactions are delivered as light-weight, high-priority packets. This ensures that a reaction appears almost instantaneously on the recipient's phone, making the chat feel \"Live\" and responsive.\n\n---\n\n## 🛡️ Strategic Best Practices for Sentiment Engagement\n\n### 1. The \"Standard Set\" Strategy\nWhile WhatsApp supports any emoji as a reaction, users are most accustomed to the \"Standard Quick Actions\": 👍 (Acknowledgement), ❤️ (Love/Quality), 😂 (Laughter), 😮 (Surprise), 😢 (Sympathy), and 🙏 (Thanks).\n- **UX Impact**: By sticking to these standards, you match the user's muscle memory. \n- **Compatibility**: Rare or complex combined emojis (like multi-colored family units) can sometimes render inconsistently across older Android or Desktop versions. Standard emojis are universally safe.\n\n### 2. Automated Acknowledgements\nModern bots shouldn't always respond with text.\n- **Example**: If a user says \"Got it!\" or \"Thanks!\", instead of the bot replying with \"You're welcome!\" (another message for the user to clear), have the bot react with a 👍 or 💙.\n- **Value**: This keeps the chat history clean while still providing the user with positive reinforcement that their input was received.\n\n### 3. Removal and Cleanup\nDon't let outdated sentiments linger.\n- **Workflow**: If your bot reacts with a ⏳ (Processing) while it’s working on a long task, make sure to call the endpoint again with an empty string `\"\"` to remove the ⏳ once the task is finished, or replace it with a ✅ (Done). This prevents the UI from becoming cluttered with conflicting status emojis.\n\n---\n\n## 🧩 Advanced Use Cases\n\n### Lightweight Interactive Voting\nYou can build a low-friction voting system by asking a question and having users react with different emojis for different options. \n- **Logic**: Use your **Webhooks** (`message.reaction`) للاستماع إلى التفاعلات الواردة من المستخدمين. Your backend then tallies the counts for each emoji type, enabling \"Reactions-as-Votes\" functionality without a single line of extra UI code.\n\n### Sentiment Monitoring for Human Agents\nWhen an automated flow is running, have your system monitor the emojis users react with. If a user consistently reacts with 😢 or 😠 to bot messages, your system can interpret this as a \"Frustration Signal\" and automatically escalate the chat to a human agent.\n\n---\n\n## 🛠️ Common Pitfalls and Solutions\n\n- **The \"Missing ID\" Error**: If you provide a correctly formatted `messageId` but the message was sent too long ago (typically several weeks), the reaction may fail. Reactions are most reliable when applied to recent (active) conversation history.\n- **Rapid Re-Reaction**: Sending five different reactions to the same message in one second can be flagged as \"Suspicious Scripting.\" Implement a small jitter or debounce (at least 200ms) between reaction updates to the same target message.\n- **Encryption Resync**: In rare cases, if a session's security keys are out of sync, a reaction might fail while standard text succeeds. A quick [`/v2/session/restart`](/v2/session/restart) usually resolves these synchronization edge cases.\n\n---\n\n## Summary of Capabilities:\n- Apply and remove native WhatsApp reactions (emojis) to any existing message.\n- Support for \"Delete Reaction\" via empty string payloads.\n- High-concurrency support for voting and acknowledgement systems.\n- Real-time event tracking through `message.reaction` Webhooks.\n- Lightweight and low-priority execution to minimize chat-history clutter.\n",
      "image": "https://api.apidog.com/api/v1/projects/1017306/resources/369244/image-preview",
      "tips": [
        {
          "type": "positive",
          "title": "Modern UI",
          "content": "Reactions keep chat history clean and are significantly faster to process for the user than text replies."
        }
      ],
      "recommendations": [
        "Use \"reply_to\" to maintain conversation context.",
        "Handle distinct message types (text, image, video) appropriately.",
        "Implement a robust retry mechanism for failed sends."
      ],
      "translations": {
        "ar": {
          "title": "إرسال تفاعل (Reaction)",
          "description": "التفاعل مع رسالة محددة باستخدام رمز تعبيري (👍، ❤️، 😂، إلخ).",
          "extraInfo": "\n# التفاعلات الصغيرة: إتقان محرك تفاعلات الرسائل\n\nتعد التفاعلات (`/v2/send/reaction`) واحدة من أقوى التفاعلات الصغيرة في نظام المراسلة الحديث. فهي تتيح للمستخدمين والبوتات تأكيد المعلومات، أو التعبير عن المشاعر، أو تقديم ملاحظات دون عبء الرد النصي الكامل. في تطبيقات Wawp، ليست التفاعلات مجرد لمسة تجميلية؛ بل هي إشارات هيكلية يمكن استخدامها لتتبع التفاعل، أو بناء أنظمة تصويت تفاعلية، أو تبسيط تأكيدات البوت للمستخدمين.\n\n---\n\n## 🏗️ بنية دورة حياة التفاعل\n\nعلى عكس الرسائل الكاملة، التفاعلات هي بيانات وصفية إضافية مرتبطة برسالة موجودة. يدير محرك تفاعلات Wawp هذا الارتباط بدقة عالية:\n1. **تحديد الهدف**: يستخدم المحرك `messageId` لتحديد موقع الرسالة المحددة على خادم واتساب. يجب أن يكون هذا هو المعرف الفريد لرسالة موجودة في الدردشة المحددة بواسطة `chatId`.\n2. **تطبيع الرموز التعبيرية**: بينما يمكنك إرسال أي رمز تعبيري، يضمن Wawp تشفير الحرف بشكل صحيح لـ WhatsApp WebSocket. إذا أرسلت سلسلة فارغة (`\"\"`)، يفسر المحرك ذلك كأمر \"حذف التفاعل\"، مما يوجه شبكة واتساب لإزالة تفاعلك السابق من تلك الرسالة المحددة.\n3. **التسليم السريع**: يتم تسليم التفاعلات كحزم خفيفة الوزن وعالية الأولوية. هذا يضمن ظهور التفاعل فورًا تقريبًا على هاتف المستلم، مما يجعل الدردشة تبدو \"حية\" وتفاعلية.\n\n---\n\n## 🛡️ أفضل الممارسات الاستراتيجية للتفاعل مع المشاعر\n\n### 1. استراتيجية \"المجموعة القياسية\"\nبينما يدعم واتساب أي رمز تعبيري كتفاعل، فإن المستخدمين أكثر اعتيادًا على \"إجراءات الرد السريع القياسية\": 👍 (تأكيد/موافقة)، ❤️ (حب/جودة)، 😂 (ضحك)، 😮 (مفاجأة)، 😢 (تعاطف)، و 🙏 (شكر).\n- **تأثير تجربة المستخدم**: من خلال الالتزام بهذه المعايير، فإنك تطابق الذاكرة العضلية للمستخدم.\n- **التوافق**: الرموز التعبيرية النادرة أو المعقدة (مثل الوحدات العائلية متعددة الألوان) قد تظهر أحيانًا بشكل غير متسق عبر إصدارات الأندرويد أو سطح المكتب القديمة. الرموز القياسية آمنة عالميًا.\n\n### 2. التأكيدات المؤتمتة\nلا ينبغي للبوتات الحديثة الرد دائماً بالنصوص.\n- **مثال**: إذا قال المستخدم \"فهمت!\" أو \"شكراً!\"، بدلاً من رد البوت بـ \"على الرحب والسعة!\" (وهي رسالة أخرى يجب على المستخدم مسحها)، اجعل البوت يتفاعل بـ 👍 أو 💙.\n- **القيمة**: يحافظ هذا على نظافة سجل الدردشة مع الاستمرار في تزويد المستخدم بتعزيز إيجابي بأنه تم استلام مدخلاته.\n\n### 3. الإزالة والتنظيف\nلا تترك المشاعر القديمة باقية.\n- **سير العمل**: إذا تفاعل البوت الخاص بك بـ ⏳ (جاري المعالجة) أثناء عمله على مهمة طويلة، فتأكد من استدعاء نقطة النهاية مرة أخرى بسلسلة فارغة `\"\"` لإزالة الرمز بمجرد انتهاء المهمة، أو استبدله بـ ✅ (تم). هذا يمنع واجهة المستخدم من أن تصبح مزدحمة برموز حالة متضاربة.\n\n---\n\n## 🧩 حالات استخدام متقدمة\n\n### التصويت التفاعلي خفيف الوزن\nيمكنك بناء نظام تصويت منخفض الاحتكاك عن طريق طرح سؤال وجعل المستخدمين يتفاعلون برموز تعبيرية مختلفة لخيارات مختلفة.\n- **المنطق**: استخدم **Webhooks** (`message.reaction`) للاستماع إلى التفاعلات الواردة من المستخدمين. يقوم نظامك الخلفي بعد ذلك بحساب الأعداد لكل نوع رمز تعبيري، مما يتيح وظيفة \"التفاعلات كأصوات\" دون سطر واحد من كود الواجهة الإضافي.\n\n### مراقبة المشاعر للوكلاء البشريين\nعند تشغيل تدفق مؤتمت، اجعل نظامك يراقب الرموز التعبيرية التي يتفاعل بها المستخدمون. إذا كان المستخدم يتفاعل باستمرار بـ 😢 أو 😠 مع رسائل البوت، يمكن لنظامك تفسير ذلك كـ \"إشارة إحباط\" وتصعيد الدردشة تلقائيًا إلى وكيل بشري.\n\n---\n\n## 🛠️ المزالق الشائعة والحلول\n\n- **خطأ \"المعرف المفقود\"**: إذا قدمت `messageId` بشكل صحيح ولكن الرسالة تم إرسالها منذ فترة طويلة (عادةً عدة أسابيع)، فقد يفشل التفاعل. التفاعلات تكون أكثر موثوقية عند تطبيقها على تاريخ حواري حديث (نشط).\n- **إعادة التفاعل السريع**: إرسال خمسة تفاعلات مختلفة لنفس الرسالة في ثانية واحدة يمكن اعتباره \"برمجة مشبوهة\". قم بتنفيذ تأخير بسيط (200 ملي ثانية على الأقل) بين تحديثات التفاعل لذات الرسالة المستهدفة.\n- **مزامنة التشفير**: في حالات نادرة، إذا كانت مفاتيح الأمان للجلسة غير متزامنة، قد يفشل التفاعل بينما ينجح النص العادي. عادةً ما يؤدي [`/v2/session/restart`](/v2/session/restart) السريع إلى حل هذه الحالات الحدودية للمزامنة.\n\n---\n\n## ملخص الإمكانيات:\n- تطبيق وإزالة تفاعلات واتساب الأصلية (الرموز التعبيرية) على أي رسالة موجودة.\n- دعم \"حذف التفاعل\" عبر حمولات السلسلة فارغة.\n- دعم عالي التزامن لأنظمة التصويت والتأكيد.\n- تتبع الأحداث في الوقت الفعلي من خلال Webhooks لـ `message.reaction`.\n- تنفيذ خفيف الوزن ومنخفض الأولوية لتقليل فوضى سجل الدردشة.\n",
          "args": {
            "instance_id": {
              "description": "المعرف الفريد لجلسة واتساب"
            },
            "access_token": {
              "description": "رمز وصول API الخاص بك"
            },
            "chatId": {
              "description": "معرف واتساب للمستلم (JID). يدعم الأفراد (@c.us)، المجموعات (@g.us)، والقنوات (@newsletter)."
            },
            "messageId": {
              "description": "معرف الرسالة التي تريد التفاعل معها."
            },
            "reaction": {
              "description": "الرمز التعبيري للتفاعل. استخدم سلسلة فارغة للإزالة."
            }
          },
          "tips": [
            {
              "title": "واجهة حديثة",
              "content": "تحافظ التفاعلات على نظافة سجل الدردشة وهي أسرع بكثير في المعالجة للمستخدم من الردود النصية."
            }
          ]
        }
      }
    },
    {
      "path": "/v2/chat-overview",
      "methods": [
        "GET"
      ],
      "category": "Chat Actions",
      "isArticle": true,
      "title": "Chat Management",
      "description": "Manage chat history, message states, and advanced conversation controls.",
      "extraInfo": "\n# Chat Management\n\n**Go beyond simple messaging with advanced conversation controls.**\n\nThe Chat Actions API allows you to maintain clean, organized conversation histories and interact with specific messages in a granular way.\n\n---\n\n## 🛠️ Advanced Controls\n\n| Feature | Description |\n| :--- | :--- |\n| **History Control** | Delete messages, clear entire chats, or archive conversations. |\n| **State Management** | Mark chats as 'Read' or 'Unread' and retrieve unread counts. |\n| **Message Retrieval** | Fetch specific messages by ID or download chat history logs. |\n| **Interaction** | Edit sent messages or pinpoint specific items in a conversation. |\n\n---\n\n## 🛡️ Best Practices\n\n*   **Message Editing**: You can usually only edit messages within a specific time window (approx. 15 minutes). Always check the `modifiedAt` timestamp.\n*   **Media Handling**: When fetching history, set `downloadMedia` to `false` by default. Only download media when explicitly requested to save bandwidth.\n*   **Archiving**: Use the archive feature for conversations that are \"Closed\" to keep your primary inbox focused on active users.\n*   **Pinning**: Important messages or FAQ links can be pinned to ensure they are always visible (if supported by your engine version).\n\n---\n\n## 💡 Usage Ideas\n\n*   **Audit Trail**: Periodically fetch and store chat histories in your own database for compliance and legal records.\n*   **CRM Sync**: Mark a WhatsApp message as \"Read\" automatically as soon as an agent opens the ticket in your internal dashboard.\n*   **Disappearing Messages**: Create temporary support channels by automatically deleting messages after the customer's issue is resolved.\n# Mastering Conversation Flow: The Chat Management Lifecycle\n\nIn a high-scale messaging environment, \"sending a message\" is only the beginning. Professional-grade WhatsApp integrations require a sophisticated strategy for **Chat Management**. This involves maintaining account hygiene, synchronizing local database states with real-time network events, and providing a seamless UX that mirrors the native WhatsApp experience while adding business-layer intelligence.\n\nThe Wawp Chat Actions API provides the toolkit needed to transform a simple message stream into a structured, manageable, and legally compliant communication system.\n\n---\n\n## 🏗️ The \"State Machine\" of a WhatsApp Chat\n\nUnderstanding the lifecycle of a conversation is critical for building reliable automation. A chat in WhatsApp is not a static object; it is an evolving state machine:\n\n1.  **Creation (Ephemeral vs. Persistent)**: A chat \"exists\" as soon as a message is sent or received. However, in Wawp, a chat object is fully hydrated only when metadata (like profile pictures or group descriptions) is successfully fetched.\n2.  **Activity States**:\n    *   **Active**: Regular incoming/outgoing traffic.\n    *   **Idle**: No messages for a set period. Best practice is to **Archive** these to keep the engine's memory footprint low.\n    *   **Blocked/Restricted**: User-level or system-level blocks. Your system must listen for `presence` or `delivery_failure` events to update these states locally.\n3.  **Termination**: Deleting a chat is a permanent destructive action at the engine level. We recommend \"Soft Deletes\" (Archiving) for 30-90 days before a permanent \"Hard Delete\" for compliance.\n\n---\n\n## 🛡️ Synchronizing Your Local Database (The Source of Truth)\n\nOne of the biggest challenges for developers is keeping their internal CRM or database in sync with the WhatsApp state. We recommend the **Event-First Architecture**:\n\n### 1. The ID Correlation Strategy\nEvery chat has a unique `chatId` (e.g., `123456789@c.us` for individuals, `987654321@g.us` for groups). \n- **Database Indexing**: Always index your `conversations` table by this ID.\n- **Message Anchoring**: Store the `messageId` of the *last successful message* to prevent duplicate processing during engine restarts.\n\n### 2. Handling the \"Unread\" Paradox\nNative WhatsApp keeps track of unread counts, but if you have multiple agents, whose \"view\" is the source of truth?\n- **Wawp Solution**: Use [`/v2/chat/read`](/v2/chat/read) to sync the blue ticks.\n- **Automation Tip**: If an AI bot handles the first 3 messages, mark them as read immediately so the human agent doesn't see a \"false alert\" for a solved query.\n\n---\n\n## ⚖️ Privacy, Policy, and Compliance (GDPR/Data Retention)\n\nWhatsApp data often contains PII (Personally Identifiable Information). Effective chat management is a legal requirement in many jurisdictions.\n\n*   **Data Retention**: Implement an automated cleanup script using [`/v2/message/delete`](/v2/message/delete) or [`/v2/chats/list`](/v2/chats/list) based on your company's retention policy (e.g., \"Delete all messages older than 2 years\").\n*   **The \"Right to be Forgotten\"**: If a customer requests data deletion, use our bulk delete endpoints to ensure every trace of the conversation is removed from the Wawp engine and your local cache.\n*   **Media Erasure**: Remember that deleting a message text does not always delete the media from the underlying storage. Use specific media management calls if storage optimization is your goal.\n\n---\n\n## 💡 Advanced UX Strategies\n\n### 1. Archive vs. Delete: The Performance Angle\nThe Wawp engine performs better when the \"Active Inbox\" is lean.\n- **Strategy**: Move any chat with no activity for > 48 hours to **Archive**. This keeps the `/v2/chats/overview` response snappy and fast for your agents.\n- **Auto-Unarchive**: Wawp automatically unarchives a chat when a new message arrives, allowing for a \"Zero-Inbox\" philosophy without losing history.\n\n### 2. Message Editing for Brand Integrity\nTypos happen. In a professional setting, a typo in a price or a meeting link can be costly.\n- **The Correction Loop**: Implement a 2-minute \"buffer\" in your agent UI. If the agent notices a mistake, use [`/v2/message/edit`](/v2/message/edit) instead of deleting and re-sending. This maintains the flow and looks significantly more professional.\n\n---\n\n## ⚠️ Critical Operation Notes\n\n*   **Engine Isolation**: Chat management actions are processed in a dedicated worker thread. While they are fast, bulk actions (like deleting 1,000 messages) should be rate-limited to 1 request per second to avoid internal database locks.\n*   **Group Admin Privileges**: You cannot \"manage\" (clear/delete) messages in a group unless the instance is an **Admin**. Always check the participant status via [`/v2/groups/participants`](/v2/groups/participants) before attempting administrative chat actions.\n*   **Message Recovery**: **WARNING:** Once a chat or message is deleted via the API, it cannot be recovered from the Wawp engine. Ensure you have a backup in your own database if historical auditing is required.\n\n---\n\n## Summary of Capabilities:\n- Full CRUD operations on chat history and metadata.\n- Real-time synchronization of \"Read/Unread\" states.\n- Support for message editing and \"Delete for Everyone\" logic.\n- Optimized overview fetching for high-performance dashboards.\n- Seamless integration with Webhooks for proactive event handling.\n    ",
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "Clean Inbox",
          "content": "Archiving old conversations keeps your instance performing optimally and your agents focused."
        }
      ],
      "recommendations": [
        "Store important Message IDs for future editing or deletion.",
        "Use the 'Mark as Read' feature to manage user expectations about response times.",
        "Always handle media downloads asynchronously to avoid blocking your main logic."
      ],
      "responses": [],
      "translations": {
        "ar": {
          "title": "إدارة الدردشة",
          "description": "إدارة سجل الدردشة، وحالات الرسائل، وعناصر التحكم المتقدمة في المحادثة.",
          "tips": [
            {
              "title": "تنسيق المستلم",
              "content": "استخدم @c.us لجهات الاتصال و @g.us للمجموعات."
            },
            {
              "title": "التعامل مع الوسائط",
              "content": "تأكد من أن روابط الوسائط متاحة للعامة وهي روابط مباشرة."
            }
          ],
          "recommendations": [
            "أضف تأخيرات عشوائية بين الرسائل لمحاكاة السلوك البشري.",
            "تحقق من أرقام الهواتف قبل الإرسال لضمان التسليم."
          ],
          "extraInfo": "\n# إتقان تدفق المحادثة: دورة حياة إدارة الدردشة\n\nفي بيئة المراسلة واسعة النطاق، \"إرسال رسالة\" هو مجرد البداية. تتطلب تكاملات واتساب الاحترافية استراتيجية متطورة لـ **إدارة الدردشة**. يتضمن ذلك الحفاظ على نظافة الحساب، ومزامنة حالات قاعدة البيانات المحلية مع أحداث الشبكة في الوقت الفعلي، وتقديم تجربة مستخدم سلسة تعكس تجربة واتساب الأصلية مع إضافة ذكاء على مستوى الأعمال.\n\nتوفر واجهة برمجة تطبيقات إجراءات الدردشة في Wawp مجموعة الأدوات اللازمة لتحويل تدفق رسائل بسيط إلى نظام اتصالات منظم وقابل للإدارة ومتوافق قانونيًا.\n\n---\n\n## 🏗️ \"آلة الحالة\" لدردشة واتساب\n\nفهم دورة حياة المحادثة أمر بالغ الأهمية لبناء أتمتة موثوقة. الدردشة في واتساب ليست كائنًا ثابتًا؛ بل هي آلة حالة تتطور:\n\n1.  **الإنشاء (مؤقت مقابل دائم)**: الدردشة \"توجد\" بمجرد إرسال رسالة أو استلامها. ومع ذلك، في Wawp، يتم ترطيب كائن الدردشة بالكامل فقط عند جلب البيانات الوصفية بنجاح (مثل صور الملف الشخصي أو أوصاف المجموعات).\n2.  **حالات النشاط**:\n    *   **نشط**: حركة مرور واردة/صادرة منتظمة.\n    *   **خامل**: لا توجد رسائل لفترة محددة. أفضل ممارسة هي **أرشفة** هذه الدردشات للحفاظ على انخفاض بصمة ذاكرة المحرك.\n    *   **محظور/مقيد**: حظر على مستوى المستخدم أو النظام. يجب أن يستمع نظامك لأحداث `presence` أو `delivery_failure` لتحديث هذه الحالات محليًا.\n3.  **الإنهاء**: حذف الدردشة هو إجراء تخريبي دائم على مستوى المحرك. نوصي بـ \"الحذف الناعم\" (الأرشفة) لمدة 30-90 يومًا قبل \"الحذف الصعب\" الدائم للامتثال.\n\n---\n\n## 🛡️ مزامنة قاعدة بياناتك المحلية (مصدر الحقيقة)\n\nأحد أكبر التحديات للمطورين هو الحفاظ على مزامنة CRM أو قاعدة البيانات الداخلية مع حالة واتساب. نوصي بـ **بنية الحدث أولاً**:\n\n### 1. استراتيجية ربط المعرفات\nكل دردشة لها `chatId` فريد (مثلاً، `123456789@c.us` للأفراد، `987654321@g.us` للمجموعات).\n- **فهرسة قاعدة البيانات**: قم دائمًا بفهرسة جدول `conversations` الخاص بك بهذا المعرف.\n- **تثبيت الرسائل**: قم بتخزين `messageId` لآخر رسالة ناجحة لمنع المعالجة المزدوجة أثناء إعادة تشغيل المحرك.\n\n### 2. التعامل مع مفارقة \"غير المقروء\"\nيحتفظ واتساب الأصلي بتتبع أعداد الرسائل غير المقروءة، ولكن إذا كان لديك وكلاء متعددون، فمن هو \"عرضه\" هو مصدر الحقيقة؟\n- **حل Wawp**: استخدم [`/v2/chat/read`](/v2/chat/read) لمزامنة العلامات الزرقاء.\n- **نصيحة الأتمتة**: إذا كان بوت الذكاء الاصطناعي يتعامل مع أول 3 رسائل، فقم بتمييزها كمقروءة فورًا حتى لا يرى الوكيل البشري \"تنبيهًا كاذبًا\" لاستفسار تم حله.\n\n---\n\n## ⚖️ الخصوصية والسياسة والامتثال (GDPR)\n\nغالبًا ما تحتوي بيانات واتساب على معلومات تحديد الهوية الشخصية (PII). تعد الإدارة الفعالة للدردشة مطلبًا قانونيًا في العديد من الولايات القضائية.\n\n*   **الاحتفاظ بالبيانات**: قم بتنفيذ نص برمجي للتنظيف الآلي باستخدام [`/v2/message/delete`](/v2/message/delete) أو [`/v2/chats/list`](/v2/chats/list) بناءً على سياسة الاحتفاظ في شركتك.\n*   **\"الحق في النسيان\"**: إذا طلب عميل حذف البيانات، استخدم نقاط نهاية الحذف الجماعي لضمان إزالة كل أثر للمحادثة من محرك Wawp وذاكرة التخزين المؤقت المحلية.\n*   **مسح الوسائط**: تذكر أن حذف نص الرسالة لا يؤدي دائمًا إلى حذف الوسائط من التخزين الأساسي. استخدم استدعاءات إدارة الوسائط المحددة إذا كان تحسين التخزين هو هدفك.\n\n---\n\n## 💡 استراتيجيات تجربة المستخدم المتقدمة\n\n### 1. الأرشفة مقابل الحذف: زاوية الأداء\nيعمل محرك Wawp بشكل أفضل عندما يكون \"صندوق الوارد النشط\" رشيقًا.\n- **الاستراتيجية**: انقل أي دردشة لا يوجد بها نشاط لأكثر من 48 ساعة إلى **الأرشيف**. هذا يحافظ على استجابة [`/v2/chats/overview`](/v2/chats/overview) سريعة لوكلائك.\n- **إلغاء الأرشفة التلقائي**: يقوم Wawp تلقائيًا بإلغاء أرشفة الدردشة عند وصول رسالة جديدة، مما يسمح بفلسفة \"صندوق الوارد الصفري\" دون فقدان التاريخ.\n\n---\n\n## ⚠️ ملاحظات تشغيلية حرجة\n\n*   **عزل المحرك**: يتم معالجة إجراءات إدارة الدردشة في خيط عامل مخصص. بينما هي سريعة، يجب تحديد معدل الإجراءات الجماعية (مثل حذف 1000 رسالة) ليكون طلبًا واحدًا في الثانية لتجنب أقفال قاعدة البيانات الداخلية.\n*   **امتيازات مسؤول المجموعة**: لا يمكنك \"إدارة\" (مسح/حذف) الرسائل في مجموعة ما لم يكن المثيل **مسؤولاً**. تحقق دائمًا من حالة المشارك عبر [`/v2/groups/participants`](/v2/groups/participants).\n*   **استعادة الرسائل**: **تحذير:** بمجرد حذف دردشة أو رسالة عبر واجهة برمجة التطبيقات، لا يمكن استعادتها من محرك Wawp. تأكد من وجود نسخة احتياطية في قاعدة بياناتك الخاصة.\n            "
        }
      }
    },
    {
      "path": "/v2/chats",
      "methods": [
        "GET",
        "POST"
      ],
      "title": "Chats list & overview",
      "category": "Chat Actions",
      "description": "Get a list of all active chats (individuals and groups) with pagination support.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "sortBy": {
          "required": false,
          "type": "string",
          "description": "Field to sort by (e.g., id)",
          "example": "id"
        },
        "sortOrder": {
          "required": false,
          "type": "string",
          "description": "Sort direction (ASC or DESC)",
          "example": "DESC"
        },
        "limit": {
          "required": false,
          "type": "number",
          "description": "Number of chats to return",
          "example": "20"
        },
        "offset": {
          "required": false,
          "type": "number",
          "description": "Number of chats to skip",
          "example": "0"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "قائمة المحادثات ونظرة عامة",
          "description": "احصل على قائمة بجميع المحادثات النشطة (الأفراد والمجموعات) مع دعم الترقيم (Pagination).",
          "tips": [
            {
              "title": "نظرة عامة",
              "content": "يعيد ملخصًا لجميع الدردشات النشطة (القائمة)."
            },
            {
              "title": "مزامنة",
              "content": "ضروري لتهيئة الشريط الجانبي لتطبيقك."
            }
          ],
          "recommendations": [
            "رتب حسب 'last_message_time' لإظهار الدردشات الأكثر نشاطًا في الأعلى.",
            "قم بتصفية الدردشات المؤرشفة إذا كانت تسبب فوضى في العرض."
          ],
          "args": {
            "sortBy": {
              "description": "الحقل الذي سيتم الفرز بناءً عليه (مثل id)"
            },
            "sortOrder": {
              "description": "اتجاه الفرز (ASC أو DESC)"
            },
            "limit": {
              "description": "عدد المحادثات المراد استرجاعها"
            },
            "offset": {
              "description": "عدد المحادثات المراد تخطيها"
            }
          },
          "extraInfo": "\n# إدارة وقائمة المحادثات\n\nاسترجع نظرة عامة على جميع المحادثات المتاحة حالياً في مثيل واتساب الخاص بك.\n\n### 🛡️ أفضل الممارسات\n# احتراف البريد الوارد: استرجاع المحادثات ومزامنتها على نطاق واسع\n\nتعد نقطة النهاية `/v2/chats` هي البوابة الإدارية لتاريخ مثيل واتساب الخاص بك. بخلاف نقطة نهاية \"نظرة عامة\"، التي توفر لقطة سريعة، تم تصميم واجهة برمجة تطبيقات قائمة المحادثات لـ **الاكتشاف الشامل** و **المزامنة العميقة**. سواء كنت تقوم بنقل البيانات إلى نظام CRM جديد أو بناء أرشيف قابل للبحث، فإن إتقان تفاصيل هذه النقطة أمر ضروري لتكاملات واتساب الاحترافية.\n\n---\n\n## 🏗️ آليات اكتشاف المحادثات\n\nعندما تطلب قائمة المحادثات، يتفاعل محرك Wawp مع قاعدة بياناته المشفرة الداخلية لإعادة بناء رسم المحادثات. تتضمن هذه العملية:\n1.  **الإرواء (Hydration)**: ربط معرفات JIDs الخام (مثل `447441429009@c.us`) بأسماء العرض الخاصة بها وأحدث حالة.\n2.  **تصنيف الحالة**: تحديد المحادثات \"المثبتة\" أو \"المؤرشفة\" أو \"المكتومة\".\n3.  **معالجة الترقيم**: حساب منطق الإزاحة (offset) والحد (limit) لتقديم مجموعة فرعية محددة من النتائج.\n\n---\n\n## 🚀 استراتيجيات الترقيم والفهرسة المتقدمة\n\nفي الحسابات ذات الحجم الكبير (أكثر من 5000 محادثة)، يعد طلب \"القائمة الكاملة\" نمطاً خاطئاً يؤدي إلى طفرات في استخدام الذاكرة وزيادة زمن انتقال الشبكة. اتبع هذه الإرشادات الاحترافية:\n\n### 1. مزامنة \"النافذة المنزلقة\"\nإذا كنت تقوم بمزامنة قاعدة بياناتك المحلية مع Wawp لأول مرة:\n- **المرحلة الأولى**: جلب أول 50 نتيجة (`limit=50, offset=0`) للحصول على أحدث نشاط.\n- **المرحلة الثانية**: استخدام حلقة تكرارية لجلب الصفحات التالية (`offset=50, 100, ...`) حتى تصبح مصفوفة الاستجابة فارغة.\n- **المرونة تجاه الانقطاع**: قم بتخزين آخر `offset` ناجح في قاعدة بياناتك المحلية حتى تتمكن من استئناف المزامنة في حال انقطاع الاتصال.\n\n### 2. الفرز الاستراتيجي\n- **`sortBy=id`**: مفيد للفهرسة الأبجدية أو فحوصات الاتساق.\n- **`sortOrder=DESC`**: الإعداد الافتراضي والأكثر توصية. يضمن عودة أحدث السلاسل — تلك التي من المرجح أن تتطلب اهتماماً فورياً — أولاً.\n\n---\n\n## 🛡️ أفضل الممارسات للمراقبة الفعالة\n\nبينما تعد **الويب هوك (Webhooks)** هي الطريقة المفضلة لاستلام الرسائل *الجديدة*، تظل نقطة النهاية `/v2/chats` هي المصدر الحقيقي لـ *تغييرات حالة المحادثة* (مثل تغيير المستخدم لاسم المجموعة أو أرشفة سلسلة محادثات).\n\n*   **المزامنة الفرقية (Delta Sync)**: بدلاً من مراقبة القائمة الكاملة، قم بمراقبة الصفحة الأولى فقط (`limit=20`) كل ساعة. إذا اكتشفت تغييراً في `chatId` لم يكن نظامك يعرفه، فقم بإطلاق عملية جلب عميقة لتلك المحادثة المحددة.\n*   **سياسة الأرشفة**: للحفاظ على هذه القائمة قابلة للإدارة، قم بتنفيذ سكربت للأرشفة التلقائية. استخدم قائمة المحادثات لتحديد المحادثات \"الخاملة\" (لا توجد رسائل لمدة 90 يوماً) واستدعِ نقطة نهاية الأرشفة لنقلها خارج القائمة \"النشطة\".\n\n---\n\n## 🧩 حالات استخدام متقدمة\n\n### بناء \"مستكشف واتساب\"\nأنشئ واجهة بحث مخصصة لفريقك.\n- **المنطق**: جلب قائمة المحادثات بالكامل (بناءً على الترقيم) وفهرسة حقول `name` و `id` في مثيل ElasticSearch أو Meilisearch. يتيح ذلك لوكلاء الدعم العثور على أي عميل فوراً دون انتظار استجابة المحرك.\n\n### التدقيق الذاتي للبوت\nفي بيئة متعددة البوتات، استخدم نقطة النهاية هذه للتأكد من أن البوت الخاص بك لم يتم \"تركه\" في مجموعات لا ينبغي أن يكون فيها. قم بمسح القائمة بانتظام بحثاً عن معرفات مجموعات غير معروفة (`@g.us`) وغادرها برمجياً.\n\n---\n\n## ⚠️ اعتبارات هامة\n\n*   **إعادة تشغيل المحرك**: أثناء \"الإقلاع البارد\" للمحرك، قد تستغرق قائمة المحادثات بضع ثوانٍ لتظهر حيث يعيد المزامنة مع التخزين المشفر للهاتف. تعامل مع استجابات `202 Accepted` أو القوائم الفارغة بلباقة خلال أول 30 ثانية من الجلسة.\n*   **أذونات المجموعات**: بالنسبة للمجموعات، تعيد نقطة النهاية هذه البيانات الوصدية للمجموعة المتاحة لمثيلك. إذا تمت إزالتك من مجموعة، فقد تظل تظهر في القائمة لـ \"فترة سماح\" قصيرة قبل أن تختفي.\n*   **إدارة الذاكرة**: يشغل كل كائن محادثة في الاستجابة قدراً صغيراً من الذاكرة. في الطلبات الكبيرة جداً (مثل `limit=500`)، تأكد من أن طبقة التطبيق لديك (Node.js/Python) لديها مساحة كافية لمعالجة بيانات JSON.\n            "
        }
      },
      "extraInfo": "\n# Chat List & Management\n\nRetrieve an overview of all conversations currently available in your WhatsApp instance.\n\n### 🛡️ Best Practices\n# Mastering the Inbox: High-Scale Chat Retrieval and Synchronization\n\nThe `/v2/chats` endpoint is the administrative gateway to your WhatsApp instance's history. Unlike the overview endpoint, which provides a snapshot, the Chats List API is designed for **exhausive discovery** and **deep synchronization**. Whether you are migrating data to a new CRM or building a searchable archive, mastering the nuances of this endpoint is essential for professional WhatsApp integrations.\n\n---\n\n## 🏗️ The Mechanics of Chat Discovery\n\nWhen you request the chat list, the Wawp engine interfaces with its internal encrypted database to reconstruct the conversation graph. This process involves:\n1.  **Hydration**: Associating the raw JIDs (e.g., `447441429009@c.us`) with their display names and latest status.\n2.  **State Categorization**: Identifying which chats are \"Pinned,\" \"Archived,\" or \"Muted.\"\n3.  **Pagination Processing**: Calculating the offset and limit logic to deliver a deterministic subset of results.\n\n---\n\n## 🚀 Advanced Pagination and Indexing Strategies\n\nIn high-volume accounts (5,000+ chats), requesting the \"full list\" is an anti-pattern that leads to memory spikes and network latency. Follow these professional guidelines:\n\n### 1. The \"Sliding Window\" Sync\nIf you are synchronizing your local database with Wawp for the first time:\n- **Phase 1**: Fetch the first 50 results (`limit=50, offset=0`) to get the most recent activity.\n- **Phase 2**: Use a recursive loop to fetch subsequent pages (`offset=50, 100, ...`) until the response array is empty.\n- **Interrupt Resilience**: Store the last successful `offset` in your local database so you can resume the sync if the connection drops.\n\n### 2. Strategic Sorting\n- **`sortBy=id`**: Useful for alphabetical indexing or consistency checks.\n- **`sortOrder=DESC`**: The default and most recommended setting. It ensures that the newest threads — those most likely to require immediate attention — are returned first.\n\n---\n\n## 🛡️ Best Practices for Efficient Polling\n\nWhile **Webhooks** are the preferred way to receive *new* messages, the `/v2/chats` endpoint remains the source of truth for *chat state changes* (like a user changing their group name or archiving a thread).\n\n*   **The Delta Sync**: Instead of polling the whole list, poll only the first page (`limit=20`) every hour. If you detect a change in a `chatId` that your system didn't know about, trigger a deep dive for that specific conversation.\n*   **Archiving Policy**: To keep this list manageable, implement an auto-archiving script. Use the chat list to identify \"Zombie\" chats (no messages for 90 days) and call the archive endpoint to move them out of the \"Active\" list.\n\n---\n\n## 🧩 Advanced Use Cases\n\n### Building a \"WhatsApp Explorer\"\nCreate a custom search interface for your team.\n- **Logic**: Fetch the entire chat list (paginated) and index the `name` and `id` fields in an ElasticSearch or Meilisearch instance. This allows your support agents to find any customer instantly without waiting for the engine to respond.\n\n### Bot \"Self-Audit\"\nIn a multi-bot environment, use this endpoint to ensure that your bot hasn't been \"orphaned\" in groups it shouldn't be in. Regularly scan the list for unknown group IDs (`@g.us`) and programmatically leave them.\n\n---\n\n## ⚠️ Important Considerations\n\n*   **Engine Restarts**: During an engine \"Cold Boot,\" the chat list may take a few seconds to populate as it re-syncs with the phone's encrypted storage. Handle `202 Accepted` or `empty` responses gracefully during the first 30 seconds of a session.\n*   **Group Permissions**: For groups, this endpoint returns the group metadata available to your instance. If you were removed from a group, it may still appear in the list for a short \"grace period\" before disappearing.\n*   **Memory Management**: Each chat object in the response occupies a small amount of memory. In very large requests (e.g., `limit=500`), ensure your application layer (Node.js/Python) has sufficient heap space to parse the JSON payload.\n\n---\n\n## Summary of Capabilities:\n- Exhaustive retrieval of all chat threads (Individuals and Groups).\n- Deterministic pagination for large-scale data migrations.\n- Support for custom sorting to prioritize active conversations.\n- Reliable metadata retrieval for CRM and Database indexing.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Rate Limits",
          "content": "Be mindful of API rate limits to act responsibly."
        },
        {
          "type": "warning",
          "title": "Error Handling",
          "content": "Always handle potential API errors."
        }
      ],
      "recommendations": [
        "Consult the official documentation for detailed parameter descriptions.",
        "Test endpoints in a sandbox environment before production.",
        "Keep your API client library up to date."
      ]
    },
    {
      "path": "/v2/chats/overview",
      "methods": [
        "GET"
      ],
      "title": "Get Chats Overview",
      "category": "Chat Actions",
      "description": "Retrieve a summary of all active chats and messages metadata.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "extraInfo": "\n# The Pulse of the Inbox: Mastering Chat Overviews\n\nThe `/v2/chats/overview` endpoint is the most efficient way to build a high-performance messaging dashboard. Instead of fetching the full history of every chat, this endpoint provides a \"snapshot\" of your entire inbox, allowing you to display active conversations, unread sharded counts, and the most recent message fragments in a single, lightweight API call.\n\nFor developers building CRMs, helpdesk software, or monitoring tools, this endpoint is the primary source of truth for the user's \"Inbox View.\"\n\n---\n\n## 🏗️ Architecture of an Overview\n\nThe response is an array of objects, each representing a single conversation. Each object includes critical metadata:\n1.  **Identity (`id`, `name`)**: The JID and the display name (as seen by the Wawp engine).\n2.  **Unread Count (`unreadCount`)**: A real-time shard of messages that have not yet been marked as \"seen.\"\n3.  **Last Message Fragment (`lastMessage`)**: A preview of the latest interaction, including its content, timestamp, and unique ID.\n\n---\n\n## 🚀 Performance Optimization Strategies\n\nWhen your Wawp instance manages thousands of chats, fetching the overview can become a heavy operation. Follow these strategies to maintain sub-second response times:\n\n### 1. Client-Side Virtualization\nDo not attempt to render all chats at once if the user has hundreds of active threads.\n- **Implementation**: Fetch the overview, store it in a local state (Redux/Vuex), and use a \"Virtual List\" component to render only the visible rows.\n- **Update Logic**: Instead of re-fetching the entire overview every time a message arrives, use the **Webhooks** (`message.any`) to update only the specific row in your local cache.\n\n### 2. Handling Large Pagination\nWhile `/chats/overview` is built for speed, very large inboxes (10,000+ chats) should be managed proactively.\n- **The \"Warm Cache\" Approach**: Periodically fetch the overview in the background (e.g., every 5 minutes) and store it in your own Redis cache. Your UI should then query your Redis store for instant loading.\n\n---\n\n## 🛡️ Best Practices for Inbox Management\n\n### 1. The \"Read Sync\" Loop\nThe `unreadCount` returned by this endpoint is dynamically updated. To clear a red badge in your UI:\n- Call [`/v2/chat/read`](/v2/chat/read) for that specific chat ID.\n- The next call to `/chats/overview` will return `unreadCount: 0`.\n\n### 2. Differentiating Groups vs. Individuals\nUse the JID suffix to format your UI:\n- **`@c.us`**: Individual chat. Use a user avatar.\n- **`@g.us`**: Group chat. Use a group icon and potentially prefix the last message with the sender's name for clarity.\n\n---\n\n## 🧩 Advanced Use Cases\n\n### Priority Inboxing\nBuild a \"Priority\" tab by filtering the overview array on your backend.\n- **Logic**: Sort by `lastMessage.timestamp` (descending) and highlight any row where `unreadCount > 0`.\n- **SLA Tracking**: If a last message timestamp is older than 2 hours and still \"Unread,\" trigger an internal escalation to a human agent.\n\n---\n\n## ⚠️ Important Considerations\n\n*   **JID Consistency**: Always use the full JID (e.g., `447441429009@c.us`) when cross-referencing this data with other endpoints.\n*   **Archived Chats**: By default, the overview includes active chats. To see archived threads, you may need to use specific filter flags (if available in your version) or use the full [`/v2/chats/list`](/v2/chats/list) endpoint for exhaustive searching.\n*   **Media Previews**: The `lastMessage.body` will show a truncated text version of media messages (e.g., \"📷 Photo\" or \"📄 Document\"). Your UI should handle these strings gracefully by adding corresponding icons.\n\n---\n\n## Summary of Capabilities:\n- Lightweight snapshot of the entire WhatsApp inbox.\n- Real-time unread count synchronization.\n- Last message previews for context-aware dashboards.\n- Optimal for building \"Inbox View\" sidebars in CRMs.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Performance Tip",
          "content": "Use the overview for the initial load, then use Webhooks to patch the UI state. Avoid constant polling for the entire list."
        }
      ],
      "recommendations": [
        "Store the overview in a local cache (like Redux or a Map) for instant UI transitions.",
        "Sort the results client-side by timestamp to ensure the most recent conversations are always at the top.",
        "Use the unreadCount to drive 'Notification Badges' in your system's navigation."
      ],
      "responses": [
        {
          "status": 200,
          "description": "Overview retrieved successfully.",
          "example": [
            {
              "id": "447441429009@c.us",
              "name": "John Doe",
              "unreadCount": 5,
              "lastMessage": {
                "id": "ABC123",
                "body": "Hello!",
                "timestamp": 1722170400
              }
            }
          ]
        },
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "الحصول على نظرة عامة للمحادثات",
          "description": "استرجع ملخصاً لجميع المحادثات النشطة والبيانات الوصفية للرسائل.",
          "extraInfo": "\n# نبض البريد الوارد: إتقان نظرة عامة على المحادثات\n\nتعد نقطة النهاية `/v2/chats/overview` الطريقة الأكثر كفاءة لبناء لوحة تحكم رسائل عالية الأداء. بدلاً من جلب التاريخ الكامل لكل محادثة، توفر هذه النقطة \"لقطة\" لصندوق الوارد بالكامل، مما يسمح لك بعرض المحادثات النشطة، وعدد الرسائل غير المقروءة، وأحدث أجزاء الرسائل في استدعاء واحد خفيف للواجهة البرمجية.\n\nبالنسبة للمطورين الذين يبنون أنظمة CRM، أو برامج مساعدة، أو أدوات مراقبة، تعد هذه النقطة المصدر الأساسي للحقيقة لـ \"عرض صندوق الوارد\" للمستخدم.\n\n---\n\n## 🏗️ هيكلية نظرة عامة\n\nالاستجابة هي مصفوفة من الكائنات، يمثل كل منها محادثة واحدة. يتضمن كل كائن بيانات وصفية حاسمة:\n1.  **الهوية (`id`, `name`)**: معرف JID واسم العرض.\n2.  **عدد غير المقروء (`unreadCount`)**: عدد الرسائل التي لم يتم وضع علامة \"تمت رؤيتها\" عليها بعد.\n3.  **جزء من آخر رسالة (`lastMessage`)**: معاينة لأحدث تفاعل، بما في ذلك محتواه وطابعه الزمني ومعرفه الفريد.\n\n---\n\n## 🚀 استراتيجيات تحسين الأداء\n\nعندما يدير مثيل Wawp آلاف المحادثات، يمكن أن يصبح جلب نظرة عامة عملية ثقيلة. اتبع هذه الاستراتيجيات للحفاظ على أوقات استجابة تقل عن الثانية:\n\n### 1. المحاكاة الافتراضية من جهة العميل\nلا تحاول عرض جميع المحادثات مرة واحدة إذا كان لدى المستخدم المئات من السلاسل النشطة.\n- **التنفيذ**: جلب نظرة عامة، وتخزينها في حالة محلية (Redux/Vuex)، واستخدام مكون \"قائمة افتراضية\" لعرض الصفوف المرئية فقط.\n- **منطق التحديث**: بدلاً من إعادة جلب نظرة عامة بالكامل في كل مرة تصل فيها رسالة، استخدم **الويب هوك** (`message.any`) لتحديث الصف المحدد فقط في ذاكرتك المحلية.\n\n---\n\n## 🛡️ أفضل الممارسات لإدارة صندوق الوارد\n\n### 1. حلقة \"مزامنة القراءة\"\nيتم تحديث `unreadCount` بشكل ديناميكي. لمسح شارة التنبيه في واجهتك:\n- استدعِ [`/v2/chat/read`](/v2/chat/read) لمعرف المحادثة المحدد.\n- الاستدعاء التالي لـ `/chats/overview` سيعيد `unreadCount: 0`.\n\n### 2. التمييز بين المجموعات والأفراد\nاستخدم لاحقة JID لتنسيق واجهتك:\n- **`@c.us`**: محادثة فردية. استخدم صورة رمزية للمستخدم.\n- **`@g.us`**: محادثة جماعية. استخدم أيقونة مجموعة وربما ابدأ الرسالة الأخيرة باسم المرسل للوضوح.\n\n---\n\n## 🧩 حالات استخدام متقدمة\n\n### صندوق الوارد ذو الأولوية\nابحث عن علامة تبويب \"الأولوية\" عن طريق تصفية مصفوفة النظرة العامة في خلفيتك البرمجية.\n- **المنطق**: الفرز حسب `lastMessage.timestamp` (تنازلياً) وتمييز أي صف يكون فيه `unreadCount > 0`.\n\n---\n\n## ⚠️ اعتبارات هامة\n\n*   **اتساق JID**: استخدم دائماً معرف JID كاملاً عند الربط بين هذه البيانات ونقاط النهاية الأخرى.\n*   **المحادثات المؤرشفة**: بشكل افتراضي، تتضمن النظرة العامة المحادثات النشطة. لرؤية السلاسل المؤرشفة، قد تحتاج إلى استخدام [`/v2/chats/list`](/v2/chats/list) للبحث الشامل.\n*   **معاينات الوسائط**: سيظهر `lastMessage.body` نسخة نصية مختصرة لرسائل الوسائط (مثل \"📷 صورة\" أو \"📄 مستند\"). يجب أن تتعامل واجهتك مع هذه السلاسل بجمالية من خلال إضافة الأيقونات المقابلة.\n            "
        }
      }
    },
    {
      "path": "/v2/chats/picture",
      "methods": [
        "GET"
      ],
      "title": "Get chat picture",
      "category": "Chat Actions",
      "description": "Retrieve the profile picture URL of a chat (individual or group).",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Target Chat ID (phone@c.us or group@g.us)",
          "example": "447441429009@c.us"
        },
        "refresh": {
          "required": false,
          "type": "boolean",
          "description": "Force refresh (bypass 24h cache)",
          "example": "true"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "extraInfo": "\n# Chat Profile Picture\n\nIdentify your contacts visually by fetching their latest WhatsApp profile picture.\n# Visual Identity: Mastering Chat Profile Picture Retrieval\n\nIn a professional messaging environment, visual context is key to reducing agent fatigue and improving response accuracy. The `/v2/chats/picture` endpoint allows you to programmatically fetch the latest high-resolution profile picture for any individual (`@c.us`) or group (`@g.us`). This ensures your internal CRM or dashboard feels integrated and up-to-date with the user's WhatsApp presence.\n\n---\n\n## 🏗️ The Lifecycle of a Profile Picture Fetch\n\nWhen you call this endpoint, the Wawp engine handles a complex multi-step process:\n1.  **Cache Verification**: The engine checks its local 24-hour cache for an existing URL.\n2.  **Privacy Check**: It queries the WhatsApp network. If the user's privacy settings (e.g., \"Profile Photo: My Contacts\") restrict your instance from seeing the image, the network returns a `null` or `restricted` response.\n3.  **High-Res Acquisition**: If the image is available, Wawp attempts to fetch the highest resolution thumbnail provided by the network.\n4.  **Base64/URL Delivery**: The final result is returned as a direct URL (valid for a limited time) or can be cached locally by your system for persistence.\n\n---\n\n## 🚀 Performance and Cache Management\n\nTo maintain a responsive UI while respecting WhatsApp's rate limits, we implement a **24-Hour Smart Cache**.\n\n### 1. The \"Bypass\" Flag (`refresh`)\n*   **Default Behavior**: Calling the endpoint without `refresh: true` will always prioritize the locally cached URL if it's less than 24 hours old. This is lightning fast and prevents unnecessary network round-trips.\n*   **Forced Update**: Only use `refresh: true` if your user explicitly triggers a \"Refresh Profile\" action in your UI. Overusing this flag can lead to temporary \"Visual Rate Limiting\" where the network returns empty images to save bandwidth.\n\n### 2. Strategic UI Placeholders (The \"Initials\" Fallback)\nBecause profile pictures can be restricted by privacy settings or deleted by the user, your UI must be resilient.\n- **Pattern**: \n    1. Try to fetch the URL via Wawp.\n    2. If the response is null, render a fallback avatar with the contact's initials (e.g., \"JD\" for John Doe) on a colored background.\n    3. Update the avatar only when a successful response is received.\n\n---\n\n## 🛡️ Best Practices for Identity Sync\n\n*   **Group vs. Individual**: Group icons are usually easier to fetch because they use the \"Public\" group visibility. Individual pictures are more likely to be hidden by privacy settings.\n*   **Resolution Awareness**: The returned URL usually points to a square thumbnail (e.g., 640x640). This is perfect for list views but may look pixelated in full-screen \"About\" sections. Always design your UI around a square aspect ratio.\n*   **CDN Validity**: The URLs returned are often hosted on WhatsApp's CDNs and have a limited lifespan (TTL). **Do not** store these URLs permanently in your own database. Instead, store the binary image data or re-fetch the URL every time the user session starts.\n\n---\n\n## 🧩 Advanced Use Case: Contact Enricher\n\nBuild a routine that scans your \"Top 50 Active Conversations\" every morning.\n- **Logic**: Use [`/v2/chats/overview`](/v2/chats/overview) to identify active users, then call `/v2/chats/picture` for each. Store the images locally on your own server (S3/GCS) to ensure they are available even if the user changes their privacy settings later. This creates a permanent \"Face-to-ID\" mapping for your agents.\n\n---\n\n## ⚠️ Important Considerations\n\n*   **JID Precision**: You must use the full JID. For groups, this is the ID ending in `@g.us`. If you use only the phone number without the suffix, the engine will fail to resolve the entity.\n*   **Privacy Walls**: If a user has blocked your instance, you will **never** be able to see their profile picture. An empty response is often the first technical indicator of a block.\n*   **Engine State**: Like other metadata endpoints, this works best when the session is in the `WORKING` state. If the session is `STOPPED`,\n  tips: [\n        {\n            type: 'info',\n            title: 'Scope',\n            content: 'Works for both Group chats and Private chats.'\n        },\n        {\n            type: 'warning',\n            title: 'Privacy',\n            content: 'May fail if the user's privacy settings hide their picture.'\n        }\n    ],\n  recommendations: [\n        \"Use 'contacts-profile-picture' for individual contacts.\",\n        \"Handle 404/401 errors gracefully in your UI.\"\n    ]\n  \n   the engine cannot query the network for fresh images.\n\n---\n\n## Summary of Capabilities:\n- High-resolution retrieval of contact and group avatars.\n- Integrated 24-hour caching for sub-second performance.\n- Support for forced refreshes to ensure visual data integrity.\n- Privacy-aware responses that respect user-level WhatsApp settings.\n    ",
      "translations": {
        "ar": {
          "title": "الحصول على صورة المحادثة",
          "description": "استرجع رابط صورة الملف الشخصي لمحادثة (فرد أو مجموعة).",
          "tips": [
            {
              "title": "النطاق",
              "content": "يعمل لكل من الدردشات الجماعية والدردشات الخاصة."
            },
            {
              "title": "الخصوصية",
              "content": "قد يفشل إذا كانت إعدادات خصوصية المستخدم تخفي صورته."
            }
          ],
          "recommendations": [
            "استخدم 'contacts-profile-picture' لجهات الاتصال الفردية.",
            "تعامل مع أخطاء 404/401 بمرونة في واجهة المستخدم الخاصة بك."
          ],
          "args": {
            "refresh": {
              "description": "فرض التحديث (تجاوز ذاكرة التخزين المؤقت لمدة 24 ساعة)"
            }
          },
          "extraInfo": "\n# صورة ملف المحادثة\n\nتعرف على جهات اتصالك بصرياً من خلال جلب أحدث صورة لملفهم الشخصي على واتساب.\n\n# الهوية البصرية: إتقان استرجاع صورة ملف المحادثة\n\nفي بيئة المراسلة المهنية، يعد السياق البصري مفتاحاً لتقليل إجهاد الوكيل وتحسين دقة الاستجابة. تسمح لك نقطة النهاية `/v2/chats/picture` بجلب أحدث صورة ملف شخصي عالية الدقة لأي فرد (`@c.us`) أو مجموعة (`@g.us`). يضمن ذلك أن يبدو نظام CRM أو لوحة التحكم الخاصة بك متكاملاً ومحدثاً مع تواجد المستخدم على واتساب.\n\n---\n\n## 🏗️ دورة حياة جلب صورة الملف الشخصي\n\nعندما تستدعي هذه النقطة، يتعامل محرك Wawp مع عملية معقدة متعددة الخطوات:\n1.  **التحقق من التخزين المؤقت**: يتحقق المحرك من التخزين المؤقت المحلي لمدة 24 ساعة بحثاً عن رابط موجود.\n2.  **فحص الخصوصية**: يستعلم المحرك من شبكة واتساب. إذا كانت إعدادات خصوصية المستخدم (مثل \"صورة الملف الشخصي: جهات اتصالي\") تمنع مثيلك من رؤية الصورة، فستعيد الشبكة استجابة `null`.\n3.  **الاستحواذ عالي الدقة**: إذا كانت الصورة متاحة، يحاول Wawp جلب أعلى دقة توفرها الشبكة.\n\n---\n\n## 🚀 الأداء وإدارة التخزين المؤقت\n\nللحفاظ على واجهة مستخدم سريعة الاستجابة مع احترام حدود معدل طلبات واتساب، نقوم بتنفيذ **تخزين مؤقت ذكي لمدة 24 ساعة**.\n\n### 1. علامة التجاوز (`refresh`)\n*   **السلوك الافتراضي**: استدعاء النقطة بدون `refresh: true` سيعطي الأولوية دائماً للرابط المخزن محلياً إذا كان عمره أقل من 24 ساعة. هذا سريع جداً ويمنع رحلات الشبكة غير الضرورية.\n*   **تحديث قسري**: استخدم `refresh: true` فقط إذا قام المستخدم يدوياً بالضغط على زر \"تحديث الملف الشخصي\" في واجهتك. الإفراط في استخدام هذه العلامة قد يؤدي إلى \"حد معدل بصري\" مؤقت حيث تعيد الشبكة صوراً فارغة لتوفير عرض النطاق الترددي.\n\n---\n\n## 🛡️ أفضل الممارسات لمزامنة الهوية\n\n*   **المجموعات مقابل الأفراد**: عادة ما تكون أيقونات المجموعات أسهل في الجلب لأنها تستخدم رؤية المجموعة العمومية. صور الأفراد أكثر عرضة للإخفاء بسبب إعدادات الخصوصية.\n*   **صلاحية CDN**: الروابط التي يتم إرجاعها غالباً ما تستضيفها CDNs واتساب ولها عمر محدود (TTL). **لا تقم** بتخزين هذه الروابط بشكل دائم في قاعدة بياناتك. بدلاً من ذلك، قم بتخزين بيانات الصورة الثنائية أو أعد جلب الرابط في كل مرة تبدأ فيها جلسة المستخدم.\n            "
        }
      }
    },
    {
      "path": "/v2/chats/messages",
      "methods": [
        "GET"
      ],
      "title": "Get messages in chat",
      "category": "Chat Actions",
      "description": "Retrieve messages from a specific chat with filtering and pagination.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Target Chat ID (phone@c.us or group@g.us)",
          "example": "447441429009@c.us"
        },
        "limit": {
          "required": false,
          "type": "number",
          "description": "Number of messages to retrieve",
          "example": "50"
        },
        "offset": {
          "required": false,
          "type": "number",
          "description": "Number of messages to skip",
          "example": "0"
        },
        "downloadMedia": {
          "required": false,
          "type": "boolean",
          "description": "Whether to download and return media content",
          "example": "true"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "الحصول على الرسائل في المحادثة",
          "description": "استرجع الرسائل من محادثة معينة مع تصفية وترقيم.",
          "tips": [
            {
              "title": "تقسيم الصفحات",
              "content": "يجلب الرسائل بترتيب زمني عكسي (الأحدث أولاً)."
            },
            {
              "title": "الحدود",
              "content": "قد يؤدي جلب عدد كبير جدًا من الرسائل في وقت واحد إلى انتهاء المهلة."
            }
          ],
          "recommendations": [
            "استخدم معلمة 'limit' لجلب ما هو مطلوب فقط لمنفذ العرض.",
            "قم بتخزين الرسائل القديمة مؤقتًا محليًا لتقليل حمل API."
          ],
          "args": {
            "limit": {
              "description": "عدد الرسائل المراد استرجاعها"
            },
            "offset": {
              "description": "عدد الرسائل المراد تخطيها"
            },
            "downloadMedia": {
              "description": "ما إذا كان سيتم تنزيل وإرجاع محتوى الوسائط"
            }
          },
          "extraInfo": "\n# جلب سجل المحادثة\n\nاسترجع الرسائل السابقة لبناء عرض كامل للمحادثة في تطبيقك.\n\n# سياق عميق: إتقان استرجاع الرسائل وإرواء الوسائط\n\nتعد نقطة النهاية `/v2/chats/messages` القلب التقني لأي نظام CRM أو لوحة تحكم دعم تعتمد على واتساب. إنها تسمح لتطبيقك بـ \"النظر إلى الماضي\"، وإعادة بناء التدفق الحواري بدقة. تتعامل هذه النقطة مع كل شيء من تاريخ النصوص البسيط إلى الاستحواذ المعقد على الوسائط، مما يجعلها أداة قوية ولكنها تتطلب استهلاكاً للموارد يستوجب استراتيجية تنفيذ مدروسة.\n\n---\n\n## 🏗️ الهيكلية التقنية للاسترجاع\n\nعند الاستعلام عن الرسائل، يقوم محرك Wawp بعدة عمليات:\n1.  **دقة JID**: يتحقق من `chatId` ويحدد قسم التخزين المحلي لتلك المحادثة المحددة.\n2.  **إدارة المؤشرات**: باستخدام `limit` و `offset`، يتنقل في مخزن الرسائل المفهرس لاسترجاع شريحة محددة من التاريخ.\n3.  **\"التحميل الكسول\" للوسائط**: إذا تم تفعيل `downloadMedia`، يحاول المحرك جلب البيانات الثنائية الإقليمية من شبكة توصيل المحتوى (CDN) الخاصة بواتساب، وفك تشفيرها باستخدام مفاتيح الجلسة، وإعادتها كحمولة Base64.\n\n---\n\n## 🚀 استراتيجيات تحسين مزامنة السجل\n\nبالنسبة للمطورين الذين يبنون أرشيفاً محلياً للرسائل، نوصي بنمط **الردمي التكراري (Recursive Backfill)**:\n\n### 1. تنفيذ \"التمرير اللانهائي\"\nفي واجهتك، عندما ينتقل المستخدم إلى أعلى المحادثة:\n- **المحفز**: رصد حدث التمرير واستدعاء `/v2/chats/messages` مع الـ `offset` التالي.\n- **حالة التحميل**: اظهر مؤشر تحميل خفيف. بمجرد وصول الرسائل، أضفها إلى بداية مصفوفتك المحلية.\n- **إزالة التكرار**: تحقق دائماً من وجود معرفات `messageId` مكررة لتجنب \"الرسائل الشبحية\".\n\n### 2. التعامل الاستراتيجي مع الوسائط (نموذج \"الدفع حسب الاستخدام\")\nيعد تنزيل الوسائط لكل رسالة في جلب السجل أمراً غير فعال وقد يسبب تأخيراً كبيراً في الشبكة.\n- **أفضل الممارسات**: اضبط دائماً `downloadMedia: false` عند استرجاع القوائم.\n- **الإرواء عند الطلب**: يجب أن تظهر واجهتك أيقونة مؤقتة لرسائل الوسائط. فقط عندما ينقر المستخدم على تلك الرسالة المحددة، استدعِ [`/v2/message/get`](/v2/message/get) مع ضبط `downloadMedia: true`.\n\n---\n\n## 🛡️ أفضل الممارسات لسلامة البيانات\n\n*   **أنواع الرسائل**: يحتوي واتساب على عشرات الأنواع من الرسائل. تأكد من أن مكون \"الرسالة\" في واجهتك مرن بما يكفي لعرض هذه الهياكل المختلفة بناءً على حقل `type`.\n*   **مزامنة الطابع الزمني**: يعيد Wawp الطوابع الزمنية بتنسيق Unix Epoch. قم دائماً بتحويلها إلى المنطقة الزمنية المحلية للمستخدم.\n\n---\n\n## 🧩 حالات استخدام متقدمة\n\n### ذاكرة الذكاء الاصطناعي الحواري (RAG)\nإذا كنت تبني بوت ذكاء اصطناعي، استخدم هذه النقطة لتوفير سياق آخر 20 رسالة للنموذج اللغوي (LLM).\n\n### تدقيق ضمان الجودة (QA)\nيمكن للمديرين مراجعة أداء الوكيل من خلال جلب سجل \"التذاكر المغلقة\" لحساب زمن الحل وتقييم نبرة الاستجابات ودقتها.\n            "
        }
      },
      "extraInfo": "\n# Fetch Chat History\n\nRetrieve previous messages to build a complete conversation view in your application.\n# Deep Context: Mastering Message Retrieval and Media Hydration\n\nThe `/v2/chats/messages` endpoint is the technical core of any WhatsApp-based CRM or Support Dashboard. It allows your application to \"look back in time,\" reconstructing the conversational flow with precision. This endpoint handles everything from simple text history to complex media acquisition, making it a powerful but resource-intensive tool that requires a thoughtful implementation strategy.\n\n---\n\n## 🏗️ Technical Architecture of Retrieval\n\nWhen you query for messages, the Wawp engine performs several operations:\n1.  **JID Resolution**: It verifies the `chatId` and identifies the local storage partition for that specific conversation.\n2.  **Pointer Management**: Using `limit` and `offset`,\n  tips: [\n    {\n        \"type\": \"info\",\n        \"title\": \"Rate Limits\",\n        \"content\": \"Be mindful of API rate limits to act responsibly.\"\n    },\n    {\n        \"type\": \"warning\",\n        \"title\": \"Error Handling\",\n        \"content\": \"Always handle potential API errors.\"\n    }\n],\n  recommendations: [\n    \"Consult the official documentation for detailed parameter descriptions.\",\n    \"Test endpoints in a sandbox environment before production.\",\n    \"Keep your API client library up to date.\"\n],\n  \n   it navigates the indexed message store to retrieve a deterministic slice of history.\n3.  **Media \"Lazy Loading\"**: If `downloadMedia` is enabled, the engine actively attempts to fetch regional binary data from WhatsApp's CDN, decrypt it using the session's keys, and return it as a Base64 payload.\n\n---\n\n## 🚀 Optimized History Synchronization Strategies\n\nFor developers building a local message archive, we recommend the **Recursive Backfill** pattern:\n\n### 1. The \"Infinite Scroll\" Implementation\nIn your UI, when a user scrolls to the top of the chat:\n- **Trigger**: Detact the scroll event and call `/v2/chats/messages` with the next `offset`.\n- **Loading State**: Show a subtle spinner. Once the messages arrive, prepend them to your local array.\n- **Deduplication**: Always check for duplicate `messageId` strings before updating your UI to avoid \"Ghost Messages\" during fast scrolling.\n\n### 2. Strategic Media Handling (The \"Pay-As-You-Go\" Model)\nDownloading media for every message in a history fetch is inefficient and can cause significant network lag.\n- **The Best Practice**: Always set `downloadMedia: false` when retrieving lists.\n- **Hydration on Demand**: Your UI should show a placeholder icon (e.g., a \"Download\" button) for media messages. Only when the user clicks that specific message should you call [`/v2/message/get`](/v2/message/get) with `downloadMedia: true`.\n\n---\n\n## 🛡️ Best Practices for Data Integrity\n\n*   **Message Types**: WhatsApp has dozens of message types (text, image, video, document, link-preview, location, contact). Ensure your frontend \"Message Component\" is flexible enough to render these different structures based on the `type` field in the response.\n*   **Timestamp Synchronization**: Wawp returns timestamps in Unix Epoch format. Always convert these to the user's local timezone on the client-side to ensure conversational context.\n*   **The \"Forwarded\" Flag**: Pay attention to the `isForwarded` metadata. In security-sensitive applications, this helps agents identify if a customer is sharing original content or potentially circulating spam/template information.\n\n---\n\n## 🧩 Advanced Use Cases\n\n### Conversational AI Memory (RAG)\nIf you are building an AI bot using RAG (Retrieval-Augmented Generation), use this endpoint to provide the LLM with the last 20 messages of context.\n- **Logic**: Fetch the messages without media, concatenate the text bodies, and pass them as \"Context\" to your AI prompt. This ensures the bot \"remembers\" what was said earlier in the session.\n\n### Quality Assurance (QA) Auditing\nManagers can use this endpoint to review agent performance. By fetching the history of \"Closed Tickets,\" you can calculate \"Time to Resolution\" and evaluate the tone/accuracy of responses.\n\n---\n\n## ⚠️ Important Considerations\n\n*   **Temporary Files**: When `downloadMedia` is true, the engine uses temporary disk space to decrypt the file. Ensure your hosting environment has sufficient temporary storage if you expect high-volume media downloads.\n*   **Expired Media**: WhatsApp's CDN eventually deletes older media files (usually after 30-60 days). If a message is very old, the download may fail with a `Media Not Found` error even if the message metadata exists.\n*   **Group Context**: In groups, the message object includes the `author` (the JID of the participant who sent the message). Use this to identify who said what within a group thread.\n\n---\n\n## Summary of Capabilities:\n- Robust retrieval of conversational history for individuals and groups.\n- Granular control over media downloading to optimize bandwidth.\n- Native support for all WhatsApp message types and metadata.\n- Integrated pagination logic for seamless infinite-scroll interfaces.\n    "
    },
    {
      "path": "/v2/chats/read",
      "methods": [
        "POST"
      ],
      "title": "Mark as read",
      "category": "Chat Actions",
      "description": "Mark unread messages as read for a specific chat.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Recipient's WhatsApp ID (JID). Supports Individuals (@c.us), Groups (@g.us), and Newsletters (@newsletter).",
          "example": "447441429009@c.us"
        },
        "messages": {
          "required": false,
          "type": "number",
          "description": "How many latest to read",
          "example": "10"
        },
        "days": {
          "required": false,
          "type": "number",
          "description": "How many latest days to read",
          "example": "1"
        }
      },
      "extraInfo": "\n# The Art of the Blue Tick: Mastering Read States\n\nIn WhatsApp, the transition from grey ticks (delivered) to blue ticks (read) is a high-stakes psychological event. The `/v2/chats/read` endpoint allows your application to programmatically trigger this state change. Whether you are building an automated helpdesk or a synchronized multi-agent CRM, managing \"Read Receipts\" correctly is critical for maintaining user trust and professional responsiveness.\n\n---\n\n## 🏗️ Technical Workflow of a Read Event\n\nWhen you mark a chat as read via Wawp, the engine performs a specialized \"Acknowledgment Handshake\":\n1.  **Selection**: Based on your `messages` or `days` parameters, the engine identifies the unread message cluster in the specified `chatId`.\n2.  **Network Broadcast**: A \"Seen\" packet is transmitted via the WhatsApp WebSocket.\n3.  **UI Synchronization**: This event ripples across all other devices linked to the account (WhatsApp Web, Mobile, Desktop), instantly clearing the unread badges and turning the sender's ticks blue.\n\n---\n\n## 🚀 Strategic Implementation Patterns\n\n### 1. The \"Human-Agent\" Sync\nIf you are building a custom dashboard for agents:\n- **Trigger**: Detact when an agent clicks on a chat thread to open it.\n- **Action**: Immediately call `/v2/chats/read` for that JID. This signals to the customer that \"Someone is looking at your message,\" which drastically improves the perceived quality of service.\n\n### 2. The \"Bot-First\" Approach\nIf an AI bot handles the initial triage:\n- **Best Practice**: Mark the messages as read as soon as the bot processes them. This keeps the agent's \"Unread\" list clean, ensuring they only focus on chats where the bot needs human escalation.\n- **Tip**: Use the `messages: 1` parameter if you only want to acknowledge the most recent interaction.\n\n---\n\n## 🛡️ Best Practices for UX Management\n\n*   **Avoid \"Ghost Reading\"**: High-scale automation should be careful not to mark every incoming message as read instantly. This creates a \"Responsiveness Gap\"—the user sees the blue ticks and expects a reply in seconds. If your bot isn't ready to reply, consider delaying the \"read\" action until the processing is complete.\n*   **Batching reads**: Use the `days` parameter for \"Inbox Cleanup\" routines. For example, mark all messages from the last 7 days as read for any chat you are about to archive.\n*   **JID Accuracy**: Ensure you use the full JID (`@c.us` or `@g.us`). Marking a group as read will clear the sharded unread count for every participant's message within that group.\n\n---\n\n## 🧩 Advanced Use Case: Session Completion Logic\n\nWhen an agent resolves a support ticket:\n1. Call `/v2/chats/read` to ensure everything is marked as seen.\n2. Send a \"Thank you\" closing message.\n3. Archive the chat.\nThis three-step flow represents the gold standard of professional WhatsApp chat management.\n\n---\n\n## ⚠️ Important Considerations\n\n*   **Privacy Settings**: If the *sender* of the message has turned off \"Read Receipts\" in their WhatsApp settings, your blue ticks will not show for them, but your unread counts inside Wawp will still be cleared.\n*   **Engine State**: This endpoint requires the session to be in the `WORKING` state. If the engine is starting or stopped, the \"Read\" packet cannot be transmitted to the WhatsApp network.\n*   **Irreversibility**: Once a message is marked as read, it cannot be \"un-read\" (turning the ticks back to grey) on the sender's device. While Wawp has a [`/v2/chats/unread`](/v2/chats/unread) endpoint, that only affects the *local* badge on your side, not the sender's blue ticks.\n\n---\n\n## Summary of Capabilities:\n- Programmatic triggering of WhatsApp blue ticks (Read Receipts).\n- Global synchronization across all linked devices (Web/Mobile/Desktop).\n- Granular control via message count or time-based (days) selection.\n- Critical for building professional agent Dashboards and CRM integrations.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Pro-Tip: Blue Tick Delay",
          "content": "To make bots feel more human, add a random 1-2 second delay before marking a message as read."
        }
      ],
      "recommendations": [
        "Store the read state in your own CRM database to avoid redundant API calls.",
        "Use the 'days' parameter to bulk-clear old unread messages for inactive customers.",
        "Use this endpoint to restore visibility to conversations that were accidentally opened."
      ],
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "وضع علامة كمقروء",
          "description": "وضع علامة على الرسائل غير المقروءة كمقروءة لمحادثة معينة.",
          "tips": [
            {
              "title": "تنسيق المستلم",
              "content": "استخدم @c.us لجهات الاتصال و @g.us للمجموعات."
            },
            {
              "title": "التعامل مع الوسائط",
              "content": "تأكد من أن روابط الوسائط متاحة للعامة وهي روابط مباشرة."
            }
          ],
          "recommendations": [
            "أضف تأخيرات عشوائية بين الرسائل لمحاكاة السلوك البشري.",
            "تحقق من أرقام الهواتف قبل الإرسال لضمان التسليم."
          ],
          "args": {
            "messages": {
              "description": "عدد أحدث الرسائل المراد قراءتها"
            },
            "days": {
              "description": "عدد أحدث الأيام المراد قراءتها"
            }
          },
          "extraInfo": "\n# فن العلامة الزرقاء: إتقان حالات القراءة\n\nفي واتساب، يعد الانتقال من الرموز الرمادية (تم التسليم) إلى الرموز الزرقاء (تمت القراءة) حدثاً نفسياً هاماً. تسمح نقطة النهاية `/v2/chats/read` لتطبيقك بإطلاق هذا التغيير برمجياً. سواء كنت تبني مكتب مساعدة آلياً أو نظام CRM متزامناً متعدد الوكلاء، فإن إدارة \"إيصالات القراءة\" بشكل صحيح أمر بالغ الأهمية للحفاظ على ثقة المستخدم والاستجابة المهنية.\n\n---\n\n## 🏗️ سير العمل التقني لحدث القراءة\n\nعندما تضع علامة على محادثة كمقروءة عبر Wawp، يقوم المحرك بـ \"مصافحة إقرار\" متخصصة:\n1.  **الاختيار**: بناءً على بارامترات `messages` أو `days`، يحدد المحرك مجموعة الرسائل غير المقروءة في `chatId` المحدد.\n2.  **بث الشبكة**: يتم إرسال حزمة \"تمت الرؤية\" عبر WhatsApp WebSocket.\n3.  **مزامنة واجهة المستخدم**: ينتشر هذا الحدث عبر جميع الأجهزة الأخرى المرتبطة بالحساب (واتساب ويب، الهاتف، سطح المكتب)، مما يؤدي فوراً إلى مسح شارات \"غير المقروء\" وتحويل علامات الصح لدى المرسل إلى اللون الأزرق.\n\n---\n\n## 🚀 أنماط التنفيذ الاستراتيجي\n\n### 1. مزامنة \"الوكيل البشري\"\nإذا كنت تبني لوحة تحكم مخصصة للوكلاء:\n- **المحفز**: رصد متى ينقر الوكيل على سلسلة محادثات لفتحها.\n- **الإجراء**: استدعاء `/v2/chats/read` فوراً لهذا المعرف JID. يرسل هذا إشارة للعميل بأن \"شخصاً ما ينظر إلى رسالتك\"، مما يحسن بشكل كبير الجودة المتصورة للخدمة.\n\n### 2. نهج \"البوت أولاً\"\nإذا كان بوت الذكاء الاصطناعي يتعامل مع الفرز الأولي:\n- **أفضل الممارسات**: ضع علامة على الرسائل كمقروءة بمجرد معالجة البوت لها. هذا يحافظ على نظافة قائمة \"غير المقروء\" لدى الوكيل، مما يضمن تركيزهم فقط على المحادثات التي تحتاج إلى تصعيد بشري.\n\n---\n\n## 🛡️ أفضل الممارسات لإدارة تجربة المستخدم\n\n*   **تجنب \"القراءة الشبحية\"**: يجب أن تكون الأتمتة واسعة النطاق حذرة من عدم وضع علامة \"مقروء\" على كل رسالة واردة فوراً. هذا يخلق \"فجوة استجابة\" — يرى المستخدم العلامات الزرقاء ويتوقع رداً في ثوانٍ. إذا لم يكن البوت جاهزاً للرد، ففكر في تأجيل إجراء \"القراءة\" حتى تكتمل المعالجة.\n*   **القراءة على دفعات**: استخدم بارامتر `days` لروتين \"تنظيف صندوق الوارد\". على سبيل المثال، ضع علامة على جميع الرسائل من آخر 7 أيام كمقروءة لأي محادثة توشك على أرشفتها.\n\n---\n\n## 🧩 حالة استخدام متقدمة: منطق إكمال الجلسة\n\nعندما يقوم وكيل بحل تذكرة دعم:\n1. استدعِ `/v2/chats/read` للتأكد من وضع علامة \"تمت الرؤية\" على كل شيء.\n2. أرسل رسالة إغلاق \"شكراً لك\".\n3. أرشفة المحادثة.\n\n---\n\n## ⚠️ اعتبارات هامة\n\n*   **إعدادات الخصوصية**: إذا قام *مرسل* الرسالة بإيقاف \"إيصالات القراءة\" في إعدادات واتساب الخاصة به، فلن تظهر علاماتك الزرقاء له، ولكن سيتم مسح عدد الرسائل غير المقروءة داخل Wawp.\n*   **حالة المحرك**: تتطلب هذه النقطة أن تكون الجلسة في حالة `WORKING`.\n*   **عدم القابلية للتراجع**: بمجرد وضع علامة على الرسالة كمقروءة، لا يمكن جعلها \"غير مقروءة\" (إعادتها للون الرمادي) على جهاز المرسل.\n            "
        }
      }
    },
    {
      "path": "/v2/messages/get",
      "methods": [
        "POST"
      ],
      "title": "Get message by id",
      "category": "Chat Actions",
      "description": "Retrieve a specific message by its ID.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Target Chat ID (phone@c.us or group@g.us)",
          "example": "447441429009@c.us"
        },
        "messageId": {
          "required": true,
          "type": "string",
          "description": "Unique ID of the message",
          "example": "true_..._..."
        },
        "downloadMedia": {
          "required": false,
          "type": "boolean",
          "description": "Whether to download and return media content",
          "example": "true"
        }
      },
      "extraInfo": "\n# Precision Access: Mastering Pinpoint Message Retrieval\n\nThe `/v2/messages/get` endpoint is the most granular tool in the Wawp Chat Actions suite. While other endpoints handle lists and overviews, this endpoint is designed for **high-fidelity retrieval** of a single interaction. It is the primary mechanism for fetching message metadata, tracking status history, and performing \"on-demand\" media hydration without overloading your network with unnecessary binary data.\n\n---\n\n## 🏗️ Technical Workflow: The \"Deep Probe\" Logic\n\nWhen you request a message by ID, the Wawp engine performs a targeted index lookup:\n1.  **Identity Verification**: The engine uses the `messageId` (a unique cryptographic hash) to locate the exact entry in the local sharded database for the given `chatId`.\n2.  **State Reconstruction**: It gathers not just the body text, but all associated metadata, including sender JID, timestamps, forwarding flags, and current ACK status (Delivered vs. Read).\n3.  **Media Decryption (Optional)**: If `downloadMedia` is enabled, the engine performs an \"Active Fetch.\" It connects to the WhatsApp CDN, downloads the encrypted blob, decrypts it using the keys stored in your session, and returns the result as a Base64 string.\n\n---\n\n## 🚀 Optimized Strategic Patterns\n\n### 1. The \"Media on Click\" Pattern\nFor high-performance dashboards, downloading media for every message is a significant performance bottleneck.\n- **Workflow**: \n    1. Fetch the conversation history using [`/v2/chats/messages`](/v2/chats/messages) with `downloadMedia: false`.\n    2. Render the message list. For images/videos, show a \"Download\" icon.\n    3. When the user clicks the icon, call `/v2/messages/get` with `downloadMedia: true`.\n- **Benefit**: This \"Lazy Hydration\" approach minimizes bandwidth and CPU usage for both your server and the client's browser.\n\n### 2. Post-Sent Verification\nUse this endpoint to verify exactly what reached the WhatsApp network.\n- **Logic**: After sending a complex message (like a list or a template), capture the returned `messageId`. Call `/v2/messages/get` a few seconds later to verify that the structure was hdyrated correctly and check the current `ack` status.\n\n---\n\n## 🛡️ Best Practices for Identification\n\n*   **Handling Non-Existent IDs**: If a `messageId` is incorrect or has been deleted from the phone's local database, the API will return a `404 Not Found`. Ensure your application handles this gracefully by showing a \"Message no longer available\" state.\n*   **Media TTL (Time To Live)**: Remember that media files on WhatsApp's CDN are ephemeral (typically 30-90 days). If you try to fetch an old message with `downloadMedia: true`, the fetch might fail even if the text data is still available.\n*   **JID Scoping**: Always provide the `chatId`. While message IDs are globally unique, providing the JID allows the engine to narrow its search to the correct conversation partition, improving response speed.\n\n---\n\n## 🧩 Advanced Use Cases\n\n### Message Interaction Tracking\nBuild an analytics dashboard.\n- **Logic**: Periodically call `/v2/messages/get` for important marketing messages to track the progression of the `ack` field (from 1=Sent to 2=Delivered to 3=Read). This allows you to calculate \"Time to Open\" metrics for your campaigns.\n\n### Forensic Auditing\nIn support scenarios where a customer claims a message contained specific info, use this endpoint to fetch the *original* record from the Wawp engine, bypassing any potential UI-level caching or local database inaccuracies. This ensures your audit trail is 100% consistent with the WhatsApp network state.\n\n---\n\n## ⚠️ Important Considerations\n\n*   **Base64 Payload Size**: When downloading media, the JSON response can become quite large (e.g., several megabytes for a high-res video). Ensure your application layer can handle large JSON buffers.\n*   **Engine state**: The instance must be in the `WORKING` state to perform network-level media downloads. Metadata retrieval from the local cache may work in other states but is most reliable when active.\n*   **Forwarded Messages**: Pay attention to the `contextInfo` block in the response. It tells you if a message was a reply to another message or if it was forwarded, providing critical context for AI processing.\n\n---\n\n## Summary of Capabilities:\n- Pinpoint retrieval of any message using its unique ID.\n- On-demand high-speed media downloading and decryption.\n- Comprehensive metadata access (timestamps, sender identity, status).\n- Essential for implementing efficient \"Lazy Loading\" in CRM UIs.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Performance Optimization",
          "content": "Always use lazy loading for media. Use this endpoint only when the user explicitly needs to view an image or video."
        }
      ],
      "recommendations": [
        "Store the messageId in your own database as the primary key for all interactions.",
        "Check the 'ack' field to track exactly when a message was delivered and read.",
        "Use the 'downloadMedia' flag carefully to manage bandwidth and storage costs."
      ],
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "الحصول على رسالة بالمعرف",
          "description": "استرجع رسالة معينة باستخدام معرفها الفريد.",
          "tips": [
            {
              "title": "تنسيق المستلم",
              "content": "استخدم @c.us لجهات الاتصال و @g.us للمجموعات."
            },
            {
              "title": "التعامل مع الوسائط",
              "content": "تأكد من أن روابط الوسائط متاحة للعامة وهي روابط مباشرة."
            }
          ],
          "recommendations": [
            "أضف تأخيرات عشوائية بين الرسائل لمحاكاة السلوك البشري.",
            "تحقق من أرقام الهواتف قبل الإرسال لضمان التسليم."
          ],
          "args": {
            "downloadMedia": {
              "description": "ما إذا كان سيتم تنزيل وإرجاع محتوى الوسائط"
            }
          },
          "extraInfo": "\n# الوصول الدقيق: إتقان استرجاع الرسائل المحددة\n\nتعد نقطة النهاية `/v2/messages/get` الأداة الأكثر دقة في مجموعة إجراءات المحادثة في Wawp. بينما تتعامل نقاط النهاية الأخرى مع القوائم ونظرات العامة، تم تصميم هذه النقطة لـ **الاسترجاع عالي الدقة** لتفاعل واحد. إنها الآلية الأساسية لجلب البيانات الوصفية للرسالة، وتتبع تاريخ الحالة، والقيام بـ \"إرواء\" الوسائط عند الطلب دون إثقال شبكتك ببيانات ثنائية غير ضرورية.\n\n---\n\n## 🏗️ سير العمل التقني: منطق \"المسبار العميق\"\n\nعند طلب رسالة بالمعرف، يقوم محرك Wawp بعملية بحث فهرس مستهدفة:\n1.  **تحقق الهوية**: يستخدم المحرك `messageId` لتحديد المدخل الدقيق في قاعدة البيانات المحلية.\n2.  **إعادة بناء الحالة**: يجمع المحرك النص الأساسي وكل البيانات الوصفية المرتبطة، بما في ذلك JID المرسل، والطوابع الزمنية، وعلامات التوجيه، وحالة ACK الحالية.\n3.  **فك تشفير الوسائط (اختياري)**: إذا تم تفعيل `downloadMedia`، يقوم المحرك بـ \"جلب نشط\"، حيث يحمل الملف من CDN واتساب، ويفك تشفيره باستخدام مفاتيح الجلسة، ويعيده كـ Base64.\n\n---\n\n## 🚀 أنماط استراتيجية محسنة\n\n### 1. نمط \"الوسائط عند النقر\"\nبالنسبة للوحات التحكم عالية الأداء، يعد تنزيل الوسائط لكل رسالة عقبة كبيرة في الأداء.\n- **سير العمل**:\n    1. جلب سجل المحادثة باستخدام [`/v2/chats/messages`](/v2/chats/messages) مع `downloadMedia: false`.\n    2. عرض قائمة الرسائل. للصور/الفيديوهات، أظهر أيقونة \"تنزيل\".\n    3. عندما ينقر المستخدم على الأيقونة، استدعي `/v2/messages/get` مع `downloadMedia: true`.\n- **الفائدة**: يقلل نهج \"الإرواء الكسول\" هذا من عرض النطاق الترددي واستخدام المعالج لكل من خادمك ومتصفح العميل.\n\n---\n\n## 🛡️ أفضل الممارسات للتعرف على الهوية\n\n*   **التعامل مع المعرفات غير الموجودة**: إذا كان `messageId` غير صحيح أو تم حذفه من قاعدة البيانات المحلية للهاتف، فستعيد الواجهة البرمجية `404 Not Found`. تأكد من أن تطبيقك يتعامل مع هذا بلباقة.\n*   **TTL للوسائط (وقت الحياة)**: تذكر أن ملفات الوسائط على CDN واتساب مؤقتة (عادة 30-90 يوماً). إذا حاولت جلب رسالة قديمة جداً مع `downloadMedia: true`، فقد يفشل الجلب حتى لو كانت بيانات النص لا تزال متاحة.\n\n---\n\n## 🧩 حالات استخدام متقدمة\n\n### تتبع التفاعل مع الرسائل\nبناء لوحة تحكم تحليلية لتتبع تطور حقل `ack` (من 1=تم الإرسال إلى 2=تم التسليم إلى 3=تمت القراءة). يتيح لك ذلك حساب مقاييس \"وقت الفتح\" لحملاتك.\n\n### التدقيق الجنائي\nفي سيناريوهات الدعم حيث يدعي العميل أن الرسالة كانت تحتوي على معلومات معينة، استخدم هذه النقطة لجلب السجل *الأصلي* من محرك Wawp، متجاوزاً أي تخزين مؤقت محتمل في واجهة المستخدم.\n            "
        }
      }
    },
    {
      "path": "/v2/messages/delete",
      "methods": [
        "DELETE"
      ],
      "title": "Delete a message",
      "category": "Chat Actions",
      "description": "Delete a specific message by its ID.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Target Chat ID (phone@c.us or group@g.us)",
          "example": "447441429009@c.us"
        },
        "messageId": {
          "required": true,
          "type": "string",
          "description": "Unique ID of the message",
          "example": "true_..._..."
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "حذف رسالة",
          "description": "احذف رسالة معينة باستخدام معرفها.",
          "tips": [
            {
              "title": "إلغاء",
              "content": "يحذف الرسالة للجميع (إلغاء) إذا تم إرسالها مؤخرًا."
            },
            {
              "title": "محلي",
              "content": "يتم حذف الرسائل القديمة فقط من جهازك الخاص."
            }
          ],
          "recommendations": [
            "قم بإلغاء الرسائل فقط في حالة حدوث أخطاء أو تسرب بيانات حساسة.",
            "أبلغ المستخدم بأنه سيظهر 'تم حذف هذه الرسالة'."
          ],
          "extraInfo": "\n# المحو المنضبط: إتقان دورة حياة حذف الرسائل\n\nفي نظام المراسلة المهني، تعد القدرة على إزالة المحتوى بنفس أهمية القدرة على إرساله. توفر نقطة النهاية `/v2/messages/delete` طريقة برمجية لاستدعاء بروتوكولات الحذف في واتساب. ومع ذلك، فإن الحذف ليس مجرد أمر \"إزالة\" بسيط؛ إنه تفاوض معقد بين مثيلك، وشبكة واتساب، وحالات جهاز المستلم.\n\n---\n\n## 🏗️ المنطق التقني: \"الحذف للجميع\" مقابل \"الحذف لدي\"\n\nيميز واتساب بين الحذف المحلي والحذف عبر الشبكة. يحاول Wawp تنفيذ الحذف الأكثر فعالية بناءً على السياق:\n\n1.  **الحذف لدى الجميع (عبر الشبكة)**:\n    *   **التوقيع**: يتم استبدال الرسالة الأصلية بتنبيه من النظام: *\"تم حذف هذه الرسالة\"*.\n    *   **المصافحة**: يرسل مثيلك حزمة \"إلغاء\" (Revocation). يقوم خادم واتساب بعد ذلك ببث هذا إلى جميع المستلمين النشطين.\n    *   **القيد**: يعمل هذا فقط إذا كانت الرسالة مرسلة من قبل مثيل وقبل مرور **~48 ساعة**.\n2.  **الحذف لدي (تنظيف محلي)**:\n    *   إذا انتهت المهلة الزمنية، أو إذا كنت تحذف رسالة أرسلها شخص آخر (ولست مشرف مجموعة)، فإن الحذف يكون محلياً. تختفي الرسالة من مثيل Wawp الخاص بك والأجهزة المرتبطة، ولكنها تظل مرئية للمرسل والمستلمين الآخرين.\n\n---\n\n## 🚀 حالات استخدام استراتيجية للحذف\n\n### 1. الامتثال وخصوصية البيانات (GDPR)\nإذا مارس العميل \"حقه في النسيان\"، يجب عليك إزالة رسائله.\n- **سير العمل**: حدد جميع معرفات `messageId` المرتبطة بمعرف JID للعميل في قاعدة بياناتك المحلية وقم بالحذف من خلال هذه النقطة لضمان إزالتها من مخزن محرك Wawp.\n\n### 2. تصحيح هلسنات البوت\nإذا أرسل بوت الذكاء الاصطناعي معلومات غير صحيحة (مثل سعر خاطئ أو بيانات خاصة):\n- **إجراء فوري**: استدعِ نقطة حذف هذا المعرف `messageId` خلال ثوانٍ. حتى لو رأى المستخدم التنبيه، فإن إزالة المحتوى تمنع أرشفته أو استخدامه كمرجع لاحقاً.\n\n### 3. إشراف المجموعات\nبصفتك مشرفاً على المجموعة، يمتلك مثيل Wawp الخاص بك القدرة على \"الحذف للجميع\" بغض النظر عمن أرسل الرسالة.\n- **التنفيذ**: بناء \"فلتر بذاءات\". عندما يكتشف الويب هوك رسالة تحتوي على كلمات محظورة، قم بتشغيل الحذف تلقائياً للحفاظ على مهنية وسلامة المجموعة.\n\n---\n\n## 🛡️ أفضل الممارسات للتنظيف الفعال\n\n*   **عتبة الـ 48 ساعة**: قم دائماً بتسجيل الطابع الزمني للرسائل الصادرة. لا تحاول إجراء \"حذف للجميع\" إذا كانت الرسالة أقدم من 48 ساعة.\n*   **عقود الوسائط**: يؤدي حذف رسالة تحتوي على وسائط عادةً إلى إزالة المؤشر لتلك الوسائط. ومع ذلك، إذا قفل المستلم \"التنزيل التلقائي إلى المعرض\" في هاتفه، فقد يظل الملف موجوداً في تخزين هاتفه الفعلي حتى بعد \"الحذف للجميع\".\n\n---\n\n## ⚠️ اعتبارات هامة\n\n*   **متطلبات المشرف**: **يجب** أن تكون مشرفاً لتتمكن من حذف رسائل أرسلها الآخرون في المجموعة. استخدم [`/v2/groups/participants`](/v2/groups/participants) للتحقق من حالتك.\n*   **مزامنة الأجهزة المرتبطة**: عمليات الحذف هي أحداث مزامنة ذات أولوية عالية. ستنتشر إلى واتساب ويب ومثيلات الموبايل لديك بشكل شبه فوري.\n*   **لا يوجد \"تراجع\"**: بمجرد حذف الرسالة للجميع، لا يوجد إجراء \"إلغاء الحذف\". قم دائماً بتنفيذ خطوة \"تأكيد الحذف\" في واجهة الوكيل البشري.\n            "
        }
      },
      "extraInfo": "\n# Controlled Erasure: Mastering the Message Deletion Lifecycle\n\nIn a professional messaging ecosystem, the ability to remove content is just as important as the ability to send it. The `/v2/messages/delete` endpoint provides a programmatic way to invoke WhatsApp's deletion protocols. However, deletion is not a simple \"remove\" command; it is a complex negotiation between your instance, the WhatsApp network, and the recipient's device states.\n\n---\n\n## 🏗️ Technical Logic: \"Delete for Everyone\" vs. \"Delete for Me\"\n\nWhatsApp distinguishes between local and network-wide deletion. Wawp attempts to execute the most effective deletion based on the context:\n\n1.  **Delete for Everyone (Network-Wide)**:\n    *   **The Signature**: The original message is replaced by a system placeholder: *\"This message was deleted\"*.\n    *   **The Handshake**: Your instance sends a \"Revocation\" packet. The WhatsApp server then broadcasts this to all active recipients.\n    *   **Constraint**: This only works if the message was sent by *your* instance and is within the **~48-hour window**.\n2.  **Delete for Me (Local Cleanup)**:\n    *   If the time limit has passed, or if you are deleting a message sent by someone else (and you are not a group admin), the deletion is local. The message disappears from your Wawp instance and linked devices, but remains visible to the sender and other recipients.\n\n---\n\n## 🚀 Strategic Use Cases for Deletion\n\n### 1. Compliance and Data Privacy (GDPR)\nIf a customer exercises their \"Right to Erasure,\" you must remove their messages.\n- **Workflow**: Identify all `messageId` strings associated with the customer's JID in your local database and iterate through them using this endpoint to ensure they are removed from the Wawp engine's storage.\n\n### 2. Correcting Bot Hallucinations\nIf an AI bot sends incorrect information (e.g., a wrong price or private data):\n- **Immediate Action**: Call the delete endpoint for that `messageId` within seconds. Even if the user saw the notification, removing the content prevents it from being archived or used as a reference point later.\n\n### 3. Group Moderation\nAs a Group Admin, your Wawp instance has the power to \"Delete for Everyone\" regardless of who sent the message.\n- **Implementation**: Build a \"Profanity Filter.\" When a webhook detects a message with blacklisted words, automatically trigger a deletion to keep the group professional and safe.\n\n---\n\n## 🛡️ Best Practices for Effective Cleanup\n\n*   **The 48-Hour Threshold**: Always log the `timestamp` of outgoing messages. Do not attempt a \"Delete for Everyone\" UI action if the message is older than 48 hours, as the API will likely fallback to a local delete, which might confuse your agents.\n*   **Handle \"Ghost\" Messages**: Occasionally, a deletion packet might reach a recipient's phone while it's offline. When they reconnect, the message might briefly appear before being deleted. This is a network-level behavior; your system should handle the `message.revoked` webhook to update your local CRM UI.\n*   **Media Persistence**: Deleting a message that contained media typically removes the pointer to that media. However, if the recipient has \"Auto-Download to Gallery\" enabled on their phone, the file may still exist in their physical phone storage even after being \"deleted for everyone.\"\n\n---\n\n## 🧩 Advanced Use Case: The \"Secret\" Handover\n\nIn high-security support scenarios, you might need to send a temporary credential or link.\n- **Logic**: Send the message, wait for the `message.ack` (blue tick), and then automatically call the delete endpoint after 60 seconds. This ensures the data is only available during the active interaction window.\n\n---\n\n## ⚠️ Important Considerations\n\n*   **Admin Requirements**: You **MUST** be an admin to delete messages sent by others in a group. Use [`/v2/groups/participants`](/v2/groups/participants) to verify your status.\n*   **Linked Devices Sync**: Deletions are high-priority sync events. They will propagate to your WhatsApp Web and Mobile instances almost instantly.\n*   **No \"Undo\"**: Once a message is deleted for everyone, there is no \"undelete\" action. Always implement a \"Confirm Deletion\" step in your human-agent UI.\n\n---\n\n## Summary of Capabilities:\n- Programmatic \"Delete for Everyone\" (within the WhatsApp time window).\n- Local \"Delete for Me\" for history management and hygiene.\n- Administrative deletion of participant messages in group chats.\n- Full integration with Webhooks to track revocation status.\n    ",
      "tips": [
        {
          "type": "warning",
          "title": "Time Limit",
          "content": "Delete for Everyone is usually only available for about 48 hours after the message was sent."
        }
      ],
      "recommendations": [
        "Store the message timestamp locally to check if 'Delete for Everyone' is still feasible.",
        "Use deletion to maintain group safety by removing spam or inappropriate content automatically.",
        "Always handle the 'message.revoked' webhook to keep your external CRM in sync with deletions."
      ]
    },
    {
      "path": "/v2/messages/edit",
      "methods": [
        "PUT"
      ],
      "title": "Edit a text message",
      "category": "Chat Actions",
      "description": "Edit the content of a previously sent text message.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Target Chat ID (phone@c.us or group@g.us)",
          "example": "447441429009@c.us"
        },
        "messageId": {
          "required": true,
          "type": "string",
          "description": "Unique ID of the message",
          "example": "true_..._..."
        },
        "text": {
          "required": true,
          "type": "string",
          "description": "New text content for the message",
          "example": "Updated message text"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "تعديل رسالة نصية",
          "description": "قم بتعديل محتوى رسالة نصية تم إرسالها مسبقاً.",
          "tips": [
            {
              "title": "النافذة",
              "content": "يمكن تعديل الرسائل فقط في غضون 15 دقيقة من الإرسال."
            },
            {
              "title": "تسمية",
              "content": "ستظهر الرسائل المعدلة علامة 'معدلة' للمستلمين."
            }
          ],
          "recommendations": [
            "استخدم هذا لإصلاح الأخطاء المطبعية دون إرسال رسالة جديدة.",
            "حافظ على السياق الأصلي سليمًا لتجنب الارتباك."
          ],
          "args": {
            "text": {
              "description": "المحتوى النصي الجديد للرسالة"
            }
          },
          "extraInfo": "\n# التصحيح الدقيق: إتقان دورة حياة تعديل الرسائل\n\nتسمح نقطة النهاية `/v2/messages/edit` لتطبيقك بالحفاظ على مستوى عالٍ من التواصل المهني من خلال تصحيح الأخطاء بعد الإرسال. في سياق الأعمال، يعد وسم \"معدلة\" أكثر مهنية بكثير من حذف الرسالة وإعادة إرسالها، حيث يحافظ على تسلسل المحادثة مع ضمان دقة البيانات. ومع ذلك، يعد التعديل عملية مقيدة بالوقت والنوع تتطلب تنسيقاً دقيقاً.\n\n---\n\n## 🏗️ المنطق التقني لعملية التعديل\n\nعند تقديم طلب تعديل، يبدأ محرك Wawp تحديثاً متخصصاً للحالة:\n1.  **فحص النزاهة**: يتحقق المحرك من أن `messageId` أُرسلت من المثيل الحالي وأن الوقت الحالي ضمن النافذة المسموح بها.\n2.  **بث التحديث**: يتم إرسال حزمة \"تعديل الرسالة\" إلى شبكة واتساب.\n3.  **تحديث جانب المستلم**: يتلقى جهاز المستلم التحديث ويستبدل النص القديم بالنص الجديد، مع إضافة تنويه \"معدلة\" بجانب الطابع الزمني.\n\n---\n\n## 🚀 تنفيذ استراتيجي متقدم\n\n### 1. تصحيح البوت \"صفر توقف\"\nإذا أرسل بوت الذكاء الاصطناعي رسالة تحتوي على خطأ حقيقي (مثل تاريخ موعد خاطئ أو سعر غير صحيح):\n- **السيناريو**: يكتشف البوت الخطأ بعد 5 ثوانٍ من الإرسال عبر فحص داخلي.\n- **تجربة مستخدم أفضل**: بدلاً من حذف الرسالة (مما يترك مكاناً لرسالة محذوفة)، استدعِ `/v2/messages/edit` فوراً. بالنسبة للمستخدم، يبدو الأمر كأنه تحديث سلس.\n\n### 2. تحديثات الأسعار والحالة الحية\nلتكاملات التجارة الإلكترونية، يمكنك استخدام التعديلات لإظهار الحالة \"في الوقت الفعلي\" في رسالة واحدة.\n- **سير العمل**: أرسل رسالة مثل: \"حالة الدفع: قيد الانتظار...\". بمجرد إتمام المعاملة، قم بتعديل *نفس* الرسالة لتصبح \"حالة الدفع: ✅ نجحت\". هذا يمنع فوضى الدردشة ويوفر \"مصدراً واحداً للحقيقة\" للعميل.\n\n---\n\n## 🛡️ أفضل الممارسات لنزاهة الرسائل\n\n*   **قاعدة الـ 15 دقيقة**: يسمح واتساب عادةً بالتعديلات فقط لمدة **15 دقيقة** بعد إرسال الرسالة الأصلية. يجب أن يتتبع نظامك الطابع الزمني `sentAt` ويخفي أزرار \"التعديل\" في واجهة الوكيل بمجرد إغلاق هذه النافذة.\n*   **قيود تعليق الوسائط**: حالياً، الدعم الأساسي هو للرسائل **النصية فقط**. قد تسمح بعض إصدارات المحرك بتعديل تعليقات الصور/الفيديوهات، ولكن لأقصى درجات الموثوقية، افترض أن الرسائل من نوع `text` فقط هي القابلة للتعديل.\n\n---\n\n## ⚠️ اعتبارات هامة\n\n*   **سلوك التنبيهات**: لاحظ أن الرسائل المعدلة عادة لا تطلق تنبيهاً ثانياً كـ \"رسالة جديدة\" على هاتف المستلم.\n*   **تاريخ المراجعات**: بينما يظهر تطبيق واتساب الرسمي النسخة المعدلة \"الحالية\" فقط، قد تحتوي بعض الواجهات غير الرسمية أو سجلات المحفوظات على النص الأصلي. لا تستخدم التعديلات \"لإخفاء\" معلومات حساسة أُرسلت بالخطأ — استخدم [`/v2/messages/delete`](/v2/messages/delete) للإزالة المتعلقة بالأمان.\n            "
        }
      },
      "extraInfo": "\n# Precision Correction: Mastering the Message Editing Lifecycle\n\nThe `/v2/messages/edit` endpoint allows your application to maintain a high standard of professional communication by correcting errors post-transmission. In a business context, an \"Edited\" label is significantly more professional than deleting a message and re-sending it, as it preserves the conversational thread while ensuring data accuracy. However, editing is a time-bound and type-constrained operation that requires careful orchestration.\n\n---\n\n## 🏗️ Technical Logic of an Edit Operation\n\nWhen you submit an edit request, the Wawp engine initiates a specialized state update:\n1.  **Integrity Check**: The engine verifies that the `messageId` was sent by the current instance and that the current time is within the allowed window.\n2.  **Update Broadcast**: A \"Message Edit\" packet is sent to the WhatsApp network.\n3.  **Client-Side Hydration**: The recipient's device receives the update and replaces the old body with the new one, adding the mandatory \"Edited\" disclaimer next to the timestamp.\n\n---\n\n## 🚀 Advanced Strategic Implementation\n\n### 1. The \"Zero-Downtime\" Bot Correction\nIf your AI bot sends a message that contains a factual error (e.g., a wrong appointment date or pricing):\n- **Scenario**: The bot detects the error 5 seconds after sending via an internal validation check.\n- **Improved UX**: Instead of deleting the message (which creates a \"deleted\" placeholder), call `/v2/messages/edit` immediately. For the user, it looks like a seamless update, maintaining the flow of the interaction.\n\n### 2. Live Pricing and Status Updates\nFor e-commerce integrations, you can use edits to show \"Real-Time\" status in a single message.\n- **Workflow**: Send a message like: \"Payment Status: Pending...\". Once the transaction clears, edit the *same* message to say \"Payment Status: ✅ Success\". This prevents chat clutter and provides a single \"Source of Truth\" for the customer.\n\n---\n\n## 🛡️ Best Practices for Message Integrity\n\n*   **The 15-Minute Rule**: WhatsApp typically allows edits for only **15 minutes** after the original message was sent. Your system should track the `sentAt` timestamp and hide \"Edit\" buttons in your agent UI once this window closes.\n*   **Media Caption Constraints**: Currently, the primary support is for **Text-only** messages. Some engine versions may allow editing captions of images/videos, but for maximum reliability, assume that only the `type: text` messages can be modified.\n*   **Avoid Substantial Semantic Changes**: Use edits for typos, formatting, and minor data corrections. Avoid changing the \"intent\" of a message significantly (e.g., changing \"Yes, I agree\" to \"No, I disagree\") as this can confuse users and undermine conversational trust.\n\n---\n\n## 🧩 Advanced Use Case: The \"Thinking\" Indicator\n\nBuild a sophisticated AI interaction:\n1.  **Initial Message**: Send \"Please wait, I am generating your report... ⏳\".\n2.  **Process**: Run your background AI logic.\n3.  **Final Edit**: Once the result is ready, edit the initial message to contain the full report text. This creates a \"dynamic\" feeling in the interaction and keeps the history clean.\n\n---\n\n## ⚠️ Important Considerations\n\n*   **Notification Behavior**: Note that edited messages usually do not trigger a second \"New Message\" notification or ping on the recipient's phone. If the user isn't currently looking at the chat, they might miss the correction unless you send a follow-up.\n*   **Revision History**: While the official WhatsApp app only shows the \"current\" edited version, some unofficial clients or historical logs might still contain the original text. Never use edits to \"hide\" sensitive information that was accidentally sent—use [`/v2/messages/delete`](/v2/messages/delete) for security-related removals.\n*   **Read State Persistence**: Editing a message does not affect its \"Seen\" (blue tick) status. If it was already read, it remains read.\n\n---\n\n## Summary of Capabilities:\n- Programmatic editing of previously sent text messages.\n- seamless UI updates via the \"Edited\" label protocol.\n- Preserves conversation thread continuity without deletion artifacts.\n- Ideal for bot self-correction and real-time status updates.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "15-Minute Window",
          "content": "You can usually only edit messages within 15 minutes of sending. Plan your correction logic accordingly."
        }
      ],
      "recommendations": [
        "Store the 'sentAt' timestamp to proactively manage the 15-minute edit window in your UI.",
        "Use edits to update 'Status' messages instead of sending new messages for every state change.",
        "Always handle 'message.edited' webhooks to keep your local CRM synced with the latest version of the text."
      ]
    },
    {
      "path": "/v2/chats/unread",
      "methods": [
        "POST"
      ],
      "title": "Mark chat as unread",
      "category": "Chat Actions",
      "description": "Explicitly mark a chat as having unread messages.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Recipient's WhatsApp ID (JID). Supports Individuals (@c.us), Groups (@g.us), and Newsletters (@newsletter).",
          "example": "447441429009@c.us"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "وضع علامة كغير مقروء",
          "description": "ضع علامة على محادثة بشكل صريح بأنها تحتوي على رسائل غير مقروءة.",
          "extraInfo": "\n# علم التذكير: إتقان حالة \"غير المقروء\"\n\nتعد نقطة النهاية `/v2/chats/unread` أداة أساسية لتنظيم صندوق الوارد وإدارة سير العمل. على عكس وضع العلامة \"مقروء\"، الذي يرسل إشارة عبر الشبكة للطرف الآخر، فإن وضع العلامة \"غير مقروء\" هو **إجراء محلي للهوية**. يضع نقطة \"غير مقروء\" مرئية بجوار المحادثة في مثيل Wawp والأجهزة المرتبطة، ليكون بمثابة علامة \"مهام\" (To-Do) قوية للوكلاء الذين يحتاجون للعودة إلى المحادثة لاحقاً.\n\n---\n\n## 🏗️ التأثير التقني لـ \"وضع علامة كغير مقروء\"\n\nعند استدعاء هذه النقطة، يقوم محرك Wawp بتغيير الحالة داخل قاعدة البيانات الداخلية للجلسة:\n1.  **تبديل الحالة**: يتم ضبط `unreadCount` لمعرف `chatId` المحدد إلى حالة \"مُشار إليها\".\n2.  **تسوية العرض**: في واتساب ويب والموبايل، تظهر نقطة خضراء/زرقاء بجوار المحادثة.\n3.  **لا يؤثر على علامات الصح**: من المهم فهم أن هذا الإجراء **لا يحول** علامات الصح الزرقاء لدى المرسل إلى اللون الرمادي. يظل المرسل يرى الرسالة كمقروءة إذا تم تأكيدها مسبقاً.\n\n---\n\n## 🚀 أنماط التنفيذ الاستراتيجي\n\n### 1. \"علم التصعيد\"\nفي سيناريو مكتب المساعدة، قد يفتح الوكيل محادثة، ويدرك أنها تنتمي لقسم آخر، ويحتاج لنقلها.\n- **سير العمل**: ينقر الوكيل على \"نقل\"، ويقوم نظامك تلقائياً باستدعاء `/v2/chats/unread`. يضمن هذا أن يرى القسم الجديد المحادثة كعنصر \"جديد/عاجل\".\n\n### 2. حلقة \"التذكير\"\nإذا كان البوت يتعامل مع طلب ولكنه يحتاج إلى إنسان للتحقق من البيانات النهائية:\n- **أفضل الممارسات**: بعد انتهاء البوت من عمله، اجعله يستدعي `/v2/chats/unread`. هذا يبقي المحادثة في أعلى قائمة \"يجب قراءتها\" للمشرف البشري.\n\n---\n\n## 🛡️ أفضل الممارسات لفرز صندوق الوارد\n\n*   **بنية جاهزة للتصفية**: عند جلب قائمة المحادثات، استخدم حالة غير المقروء لتشغيل علامة التبويب \"إجراء مطلوب\". يجب معاملة أي محادثة موسومة كغير مقروءة كتذكرة مفتوحة.\n*   **المسح قبل الوسم**: إذا كنت تريد استخدام نقطة \"غير المقروء\" كتذكير نظيف، فمن الأفضل غالباً استدعاء [`/v2/chats/read`](/v2/chats/read) أولاً لمسح أي عد غير مقروء حقيقي، ثم استدعاء `/v2/chats/unread` فوراً لضبط \"نقطة التذكير\" الواحدة.\n\n---\n\n## ⚠️ اعتبارات هامة\n\n*   **واجهة مستخدم محلية فقط**: هذا إجراء غير تدميري ولا يتم بثه. وهو \"إجراء المحادثة\" الوحيد الذي لا يؤثر بشكل كبير على رؤية العميل للمحادثة.\n*   **سلوك التجاوز**: إذا كانت المحادثة تحتوي بالفعل على رسائل غير مقروءة حقيقية، فقد لا يغير استدعاء هذه النقطة الحالة المرئية بشكل كبير.\n            "
        }
      },
      "extraInfo": "\n# The Reminder Flag: Mastering the \"Unread\" State\n\nThe `/v2/chats/unread` endpoint is an essential tool for inbox organization and workflow management. Unlike marking as read, which sends a network-wide signal to the other party, marking as unread is a **Local Identity Action**. It places a visual \"Unread\" dot next to a conversation in your Wawp instance and linked devices, serving as a powerful \"To-Do\" flag for agents who need to return to a conversation later.\n\n---\n\n## 🏗️ Technical Impact of \"Marking as Unread\"\n\nWhen you invoke this endpoint, the Wawp engine performs a state mutation within the session's internal database:\n1.  **State Toggle**: The `unreadCount` for the specified `chatId` is set to an \"indicated\" state (usually representing at least 1 unread item).\n2.  **Display Leveling**: On WhatsApp Web and Mobile, a green/blue dot appears next to the conversation.\n3.  **Does NOT Affect Ticks**: It is crucial to understand that this action **does not** turn the sender's blue ticks back to grey. The sender still sees the message as read if it was previously acknowledged.\n\n---\n\n## 🚀 Strategic Implementation Patterns\n\n### 1. The \"Escalation Flag\"\nIn a helpdesk scenario, an agent might open a chat, realize it belongs to a different department, and need to hand it off.\n- **Workflow**: The agent clicks \"Transfer,\" and your system automatically calls `/v2/chats/unread`. This ensures the heart of the new department sees the chat as a \"New/Urgent\" item in their filtered inbox.\n\n### 2. The \"Reminder\" Loop\nIf a bot handles a request but requires a human to verify the final data:\n- **Best Practice**: After the bot finishes its work, have it call `/v2/chats/unread`. This keeps the conversation at the top of the \"To-Read\" queue for the human supervisor.\n\n---\n\n## 🛡️ Best Practices for Inbox Triage\n\n*   **Filter-Ready Architecture**: When fetching your chat list via [`/v2/chats/overview`](/v2/chats/overview), use the unread state to drive your \"Pending Action\" tab. Any chat marked as unread should be treated as an open ticket.\n*   **Clear Before Unread**: If you want to use the unread dot as a clean \"Reminder,\" it's often best to call [`/v2/chats/read`](/v2/chats/read) first to clear any *real* unread counts, and then immediately call `/v2/chats/unread` to set the single \"Reminder Dot.\"\n*   **JID Precision**: Ensure you are targeting the correct conversation. Marking a group as unread is a common way for moderators to flag messages that need a policy review later.\n\n---\n\n## 🧩 Advanced Use Case: Multi-Agent Synchronization\n\nBuild a \"Bookmark\" feature in your CRM.\n- **Logic**: When an agent clicks \"Follow Up Later,\" the CRM calls the unread endpoint. Because this state syncs via the WhatsApp WebSocket, every other agent on that same Wawp instance will also see the unread indicator, preventing the conversation from being forgotten during shift changes.\n\n---\n\n## ⚠️ Important Considerations\n\n*   **Local UI Only**: This is a non-destructive, non-broadcast action. It is the only \"Chat Action\" that doesn't significantly impact the customer's view of the conversation.\n*   **Engine State**: Requires the session to be in the `WORKING` state to synchronize the indicator with linked devices.\n*   **Overwrite Behavior**: If the chat already has real unread messages (e.g., 5 unread), calling this endpoint might not change the visual state significantly, as it's already \"Unread.\" It is most effective when moving a conversation from a \"Read/Processed\" state back to \"Attention Required.\"\n\n---\n\n## Summary of Capabilities:\n- Explicitly setting of the \"Unread\" visual indicator for any chat.\n- Synchronized bookmarking across all linked devices.\n- Powerful tool for agent handoffs and \"Follow Up\" reminders.\n- Non-impactful to the customer experience (does not change blue ticks).\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Internal Workflow",
          "content": "Use 'Mark as Unread' as a lightweight ticketing system inside WhatsApp without needing external software."
        }
      ],
      "recommendations": [
        "Include an 'Unread' filter in your dashboard to help agents find flagged conversations instantly.",
        "Combined with Archiving, this can help create a 'Snooze' feature for support tickets.",
        "Use this endpoint to restore visibility to conversations that were accidentally opened."
      ]
    },
    {
      "path": "/v2/profile-overview",
      "methods": [
        "GET"
      ],
      "category": "Whatsapp Profile info",
      "isArticle": true,
      "title": "Profile & Identity",
      "description": "Manage your WhatsApp brand identity, including display name, about status, and profile picture.",
      "extraInfo": "\n# Profile & Identity\n\n**Control how your business appears to the WhatsApp world.**\n\nYour WhatsApp profile is your digital business card. Wawp gives you full control over your public identity, ensuring your brand looks consistent and professional across all interactions.\n\n---\n\n## 🛠️ Identity Management\n\n| Feature | Description |\n| :--- | :--- |\n| **Display Name** | Update the name shown to users who haven't saved your contact. |\n| **About (Bio)** | Set your descriptive \"About\" status (e.g., \"Available 9 AM - 5 PM\"). |\n| **Profile Picture** | Programmatically update or delete your profile icon. |\n| **Self-Discovery** | Fetch your own profile data to verify current public settings. |\n\n---\n\n## 🛡️ Best Practices\n\n*   **Consistency**: Use the same profile picture and display name across all your social platforms to maintain brand recognition.\n*   **Picture Quality**: Use a high-quality square (1:1) JPEG image (at least 640x640px). Circle-cropping is common, so keep your logo centered.\n*   **Helpful Bio**: Use the \"About\" field to manage expectations, such as listing your support hours or current service status.\n*   **Limit Changes**: Frequent changes to your profile name (multiple times a day) can be flagged by WhatsApp as bot-like behavior.\n\n---\n\n## 💡 Usage Ideas\n\n*   **Campaign Branding**: Temporarily update your profile picture and \"About\" status during major holiday sales or product launches.\n*   **Status Management**: Automatically set your \"About\" to \"Currently Closed - Back at 9 AM\" when your business hours end.\n# Profile & Identity: Digital Brand Architecture\n\nIn the conversational economy, your WhatsApp profile is your digital **storefront, business card, and ID badge** combined. Unlike a traditional website where users browse anonymously, every interaction on WhatsApp is anchored to your identity. The **Profile & Identity** endpoints give you programmatic control over how your business is perceived, allowing you to synchronize your WhatsApp presence with your broader brand strategy.\n\n---\n\n## 🛠️ The Three Pillars of WhatsApp Identity\n\nYour presence on the network is defined by three mutable attributes. Wawp allows you to update these dynamically to reflect your business's current state.\n\n### 1. Display Name (The \"Push\" Identity)\n*   **What it is**: The text string shown to users in their notification shade and chat list *before* they save your contact.\n*   **Strategic Use**: It must be recognizable. Avoid cryptic abbreviations.\n*   **API Control**: [`/v2/profile/name`](/v2/profile/name)\n*   **Constraints**: Subject to WhatsApp's strict \"Business Name Guidelines.\" Frequent changes can trigger flagged reviews.\n\n### 2. Profile Picture (The Visual Anchor)\n*   **What it is**: The icon associated with your JID. Use a high-density, centralized logo.\n*   **Strategic Use**: Change it seasonally (e.g., \"Holiday Theme\") or to highlight a major campaign, but keep the core logo recognizable.\n*   **API Control**: [`/v2/profile/picture`](/v2/profile/picture)\n*   **Specs**: Recommended 640x640px minimum. Remember that WhatsApp circle-crops this image in most UI views.\n\n### 3. About Status (The Context Signal)\n*   **What it is**: The text line (formerly \"Status\") visible under your name.\n*   **Strategic Use**: Use this for **Service Availability Signaling**.\n    *   *Examples*: \"🕒 Support: 9AM-5PM EST\" | \"⚠️ Experiencing high delays\" | \"🚀 Launch Day Sale is Live!\"\n*   **API Control**: [`/v2/profile/status`](/v2/profile/status)\n\n---\n\n## 🚀 Dynamic Branding Stategies\n\nStateless profiles are missed opportunities. Use the API to make your profile \"alive.\"\n\n### The \"Operating Hours\" Automation\nDon't just leave your \"About\" text static.\n- **Morning Routine**: At 9:00 AM, a cron job calls `/v2/profile/status` to set: *\"🟢 Online | Replies typically in 5 mins\"*.\n- **Evening Routine**: At 5:00 PM, the system updates it to: *\"🌙 Offline | Back at 9:00 AM\"*.\n- **Impact**: This drastically reduces customer frustration when they don't get an immediate reply during off-hours.\n\n### The \"Campaign Takeover\"\nCoordinate your WhatsApp profile with your marketing calendar.\n- **Workflow**: On the morning of your \"Black Friday\" sale, update your **Profile Picture** to a variant with a \"Sale\" badge and change your **Display Name** to append a suffix (if allowed by your verification level), e.g., \"Wawp Support 🛍️\".\n\n---\n\n## 🛡️ Trust & Verification\n\n### The \"Green Tick\" (Official Business Account)\n*   **Myth**: \"I can buy a green tick via the API.\"\n*   **Reality**: Verification is a manual vetting process by Meta. The API *cannot* request verification directly. However, maintaining a consistent API-managed profile (Name matching legal entity, high-resolution logo) is a **prerequisite** for approval.\n*   **Pro Tip**: Ensure your `Display Name` matches exactly what is on your Facebook Business Manager verification documents.\n\n### Consistency Checks\nIn distributed systems, your profile might accidentally be changed by a rogue test script.\n- **Audit Pattern**: Regularly call [`/v2/profile`](/v2/profile) (Get Info) to verify that your live public data matches your internal CRM configuration. If a mismatch is found (e.g., an old logo remains), trigger a self-healing update.\n\n---\n\n## ⚠️ Important Considerations\n\n*   **Rate Limiting**: Profile updates are low-frequency actions. Updating your name or status more than **10 times a day** may cause WhatsApp to temporarily lock your profile settings to prevent spam.\n*   **Propagation Delay**: While the API returns \"Success\" instantly, it may take up to **5-10 minutes** for your new picture or status to reflect on all user devices due to WhatsApp's aggressive caching.\n*   **Privacy Settings**: The API respects the phone's privacy settings. If the physical device is set to *Privacy > Profile Photo > Nobody*, your API uploads will succeed but **no one will see the picture**. You must verify the phone's privacy configuration manually.\n\n---\n\n## Summary of Capabilities:\n- Programmatic updates of Name, Status, and Picture.\n- Synchronization of \"About\" text with business operating hours.\n- Audit capabilities to verify public-facing identity.\n- Support for detailed privacy and compliance management.\n    ",
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "Circle Crop",
          "content": "Remember that WhatsApp crops images into a circle. Keep your logo's critical elements in the center 50% of the canvas."
        }
      ],
      "recommendations": [
        "Automate your 'About' status to reflect real-time support availability.",
        "Audit your public profile weekly using the GET endpoint to ensure consistency.",
        "Avoid changing your Display Name frequently to prevent flagging."
      ],
      "responses": [],
      "translations": {
        "ar": {
          "title": "الملف الشخصي والهوية",
          "description": "إدارة هوية علامتك التجارية على واتساب، بما في ذلك اسم العرض، وحالة 'حول'، وصورة الملف الشخصي.",
          "tips": [
            {
              "title": "حدود معدل API",
              "content": "احترم حدود معدل API لتجنب الحظر المؤقت."
            },
            {
              "title": "العمليات غير المتزامنة",
              "content": "معظم العمليات غير متزامنة. استخدم Webhooks للتحديثات في الوقت الفعلي."
            }
          ],
          "recommendations": [
            "استخدم متغيرات البيئة لبيانات الاعتماد الحساسة مثل رموز الوصول.",
            "قم بتنفيذ معالجة قوية للأخطاء ومنطق إعادة المحاولة."
          ],
          "extraInfo": "\n# الملف الشخصي والهوية: بنية العلامة التجارية الرقمية\n\nفي الاقتصاد القائم على المحادثة، يعد ملفك الشخصي على واتساب بمثابة **واجهة متجر، وبطاقة عمل، وشارة هوية** مجتمعة. على عكس الموقع التقليدي حيث يتصفح المستخدمون دون الكشف عن هويتهم، فإن كل تفاعل على واتساب يرتكز على هويتك. تمنحك نقاط نهاية **الملف الشخصي والهوية** تحكمًا برمجياً في كيفية إدراك عملك، مما يسمح لك بمزامنة وجودك على واتساب مع استراتيجية علامتك التجارية الأوسع.\n\n---\n\n## 🛠️ الأركان الثلاثة لهوية واتساب\n\nيتم تحديد وجودك على الشبكة من خلال ثلاث سمات قابلة للتغيير. يتيح لك Wawp تحديث هذه السمات ديناميكيًا لتعكس الحالة الحالية لعملك.\n\n### 1. اسم العرض (الهوية الظاهرة)\n*   **ما هو**: سلسلة النص المعروضة للمستخدمين في إشعاراتهم وقائمة الدردشة *قبل* حفظهم لجهة اتصالك.\n*   **الاستخدام الاستراتيجي**: يجب أن يكون قابلاً للتمييز. تجنب الاختصارات الغامضة.\n*   **التحكم في API**: [`/v2/profile/name`](/v2/profile/name)\n*   **القيود**: يخضع لإرشادات \"اسم النشاط التجاري\" الصارمة من واتساب. التغييرات المتكررة يمكن أن تؤدي إلى مراجعات محظورة.\n\n### 2. صورة الملف الشخصي (المرساة البصرية)\n*   **ما هي**: الأيقونة المرتبطة بـ JID الخاص بك. استخدم شعارًا عالي الدقة ومركزيًا.\n*   **الاستخدام الاستراتيجي**: قم بتغييرها موسميًا (مثل \"سمة العيد\") أو لتسليط الضوء على حملة رئيسية، ولكن حافظ على قابلية التعرف على الشعار الأساسي.\n*   **التحكم في API**: [`/v2/profile/picture`](/v2/profile/picture)\n\n### 3. حالة \"حول\" (إشارة السياق)\n*   **ما هي**: سطر النص (المعروف سابقًا باسم \"الحالة\") المرئي تحت اسمك.\n*   **الاستخدام الاستراتيجي**: استخدم هذا لـ **إشارة توفر الخدمة**.\n    *   *أمثلة*: \"🕒 الدعم: 9ص - 5م\" | \"⚠️ نواجه تأخيرات كبيرة\" | \"🚀 تخفيضات يوم الإطلاق بدأت!\"\n*   **التحكم في API**: [`/v2/profile/status`](/v2/profile/status)\n\n---\n\n## 🚀 استراتيجيات العلامة التجارية الديناميكية\n\nالملفات الشخصية الثابتة هي فرص ضائعة. استخدم واجهة برمجة التطبيقات لجعل ملفك الشخصي \"حيًا\".\n\n### أتمتة \"ساعات العمل\"\nلا تترك نص \"حول\" ثابتًا.\n- **الروتين الصباحي**: في الساعة 9:00 صباحًا، يقوم نص برمجي بتحديث الحالة إلى: *\"🟢 متصل | الردود عادة خلال 5 دقائق\"*.\n- **الروتين المسائي**: في الساعة 5:00 مساءً، يقوم النظام بتحديثها إلى: *\"🌙 غير متصل | نعود في الساعة 9:00 صباحًا\"*.\n- **الأثر**: هذا يقلل بشكل كبير من إحباط العملاء عندما لا يتلقون ردًا فوريًا خلال ساعات خارج العمل.\n\n---\n\n## 🛡️ الثقة والتحقق\n\n### \"العلامة الخضراء\" (حساب رسمي)\n*   **خرافة**: \"يمكنني شراء علامة خضراء عبر API.\"\n*   **الحقيقة**: التحقق هو عملية فحص يدوية من قبل Meta. لا يمكن لـ API طلب التحقق مباشرة. ومع ذلك، فإن الحفاظ على ملف شخصي متسق مدار عبر API هو **متطلب مسبق** للموافقة.\n\n### فحص الاتساق\nفي الأنظمة الموزعة، قد يتغير ملفك الشخصي عن طريق الخطأ بواسطة نص برمجي لاختبار عشوائي.\n- **نمط التدقيق**: اتصل بانتظام بـ [`/v2/profile`](/v2/profile) (الحصول على المعلومات) للتحقق من أن بياناتك العامة المباشرة تتوافق مع تكوين CRM الداخلي الخاص بك.\n\n---\n\n## ⚠️ اعتبارات هامة\n\n*   **تحديد المعدل**: تحديثات الملف الشخصي هي إجراءات منخفضة التردد. قد يؤدي تحديث اسمك أو حالتك أكثر من **10 مرات في اليوم** إلى قيام واتساب بقفل إعدادات ملفك الشخصي مؤقتًا لمنع البريد العشوائي.\n*   **تأخير الانتشار**: بينما تعيد API \"النجاح\" فورًا، قد يستغرق الأمر ما يصل إلى **5-10 دقائق** حتى تنعكس صورتك أو حالتك الجديدة على جميع أجهزة المستخدمين بسبب ذاكرة التخزين المؤقت القوية لـ واتساب.\n            "
        }
      }
    },
    {
      "path": "/v2/profile",
      "methods": [
        "GET"
      ],
      "title": "Get profile",
      "category": "Whatsapp Profile info",
      "description": "Retrieve your own WhatsApp profile information (name, status, etc.).",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "الحصول على الملف الشخصي",
          "description": "استرجع معلومات ملفك الشخصي على واتساب (الاسم، الحالة، إلخ).",
          "extraInfo": "\n# انعكاس الذات: تدقيق ملفك الشخصي العام\n\nتعتبر نقطة النهاية `/v2/profile` بمثابة \"مرآة\" لحسابك على واتساب. فهي تسمح لنظامك برؤية ما يراه الجمهور بالضبط عندما ينظرون إلى ملفك الشخصي لنشاطك التجاري. وهذا أمر بالغ الأهمية للحفاظ على اتساق العلامة التجارية في البيئات الموزعة حيث قد يقوم العديد من المسؤولين أو النصوص البرمجية المؤتمتة بتحديث هويتك.\n\n---\n\n## 🏗️ هيكل البيانات التقني\n\nعند الاستعلام عن نقطة النهاية هذه، يجلب محرك Wawp أحدث البيانات المتزامنة من شبكة واتساب:\n1.  **اسم العرض (Push Name)**: الاسم المعروض حالياً لجهات الاتصال الجديدة.\n2.  **JID**: معرف واتساب الأساسي الخاص بك (على سبيل المثال، `123456789@s.whatsapp.net`).\n3.  **حول (About)**: نص السيرة الذاتية الحالي.\n4.  **رابط صورة الملف الشخصي**: الرابط العام لأفاتارك الحالي (إذا كان متاحاً).\n\n---\n\n## 🚀 أنماط التدقيق الاستراتيجية\n\n### 1. مراقب \"فحص الحالة\"\nإذا كنت تدير حسابات مؤسسية، فقم بإجراء هذا الفحص مرة واحدة يومياً.\n- **السبب**: أحياناً، قد يقوم مسؤول بشري بتغيير اسم الملف الشخصي عن طريق الخطأ عبر تطبيق الهاتف، أو قد يقوم نص برمجي بتحديث الحالة بشكل غير متوقع.\n- **سير العمل**:\n    1.  استدعِ `/v2/profile`.\n    2.  قارن `name` و `status` المعادة مقابل \"الإعدادات الذهبية\" في قاعدة بياناتك.\n    3.  إذا تم العثور على عدم تطابق، فقم بتفعيل تنبيه أو استعادة تلقائية.\n\n### 2. ما قبل التحقق\nقبل التقدم بطلب للحصول على \"العلامة الخضراء\" (حساب نشاط تجاري رسمي)، استخدم نقطة النهاية هذه للتأكد من أن بياناتك مثالية.\n- **قائمة التحقق**:\n    - هل يتطابق `pushName` مع مستندات كيانك القانوني *تماماً*؟\n    - هل صورة الملف الشخصي عالية الدقة ومهنية؟\n    - هل قسم \"حول\" يحتوي على معلومات مفيدة؟\n\n---\n\n## 🛡️ الخصوصية والوصول\n\n*   **كاشف \"الحظر الخفي\" (Shadow Ban)**: في حالات نادرة، إذا وضع واتساب علامة \"سبام\" على حساب، فقد يقومون بصمت بإزالة معلومات ملفك الشخصي العام (إخفاء صورتك ومعلومات \"حول\" عن الجميع).\n    - **الكشف**: إذا أعادت نقطة النهاية هذه بيانات صالحة ولكن أفاد المستخدمون برؤية ملف شخصي فارغ، فتحقق من *إعدادات الخصوصية* في الهاتف. إذا كانت الإعدادات صحيحة ولكن الملف الشخصي لا يزال فارغاً للآخرين، فقد يكون رقمك محظوراً.\n\n---\n\n## ⚠️ اعتبارات هامة\n\n*   **التخزين المؤقت**: قد يقوم محرك Wawp بتخزين بيانات الملف الشخصي مؤقتاً لتحسين الأداء. إذا قمت للتو بتحديث صورتك عبر تطبيق الهاتف، فقد تظهر نقطة النهاية هذه الرابط القديم لبضع دقائق.\n*   **انتهاء صلاحية رابط الصورة**: رابط `pictureUrl` المعاد هو رابط مباشر لـ CDN واتساب. وهو رابط **مؤقت**. لا تقم بتخزين هذه السلسلة في قاعدة بياناتك للاستخدام طويل الأمد؛ قم دائماً بإعادة جلبها أو تنزيل ملف الصورة.\n            "
        }
      }
    },
    {
      "path": "/v2/profile/name",
      "methods": [
        "PUT"
      ],
      "title": "Set Profile Name",
      "category": "Whatsapp Profile info",
      "description": "Update your WhatsApp display name (push name).",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "name": {
          "required": true,
          "type": "string",
          "description": "New display name",
          "example": "Wawp Support"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "ضبط اسم الملف الشخصي",
          "description": "قم بتحديث اسم العرض على واتساب (اسم الدفع).",
          "tips": [
            {
              "title": "اسم الدفع",
              "content": "هذا هو الاسم الذي يظهر في الإشعارات الفورية لجهات الاتصال الجديدة."
            },
            {
              "title": "الحد",
              "content": "الطول محدود بـ 25 حرفًا."
            }
          ],
          "recommendations": [
            "استخدم اسم عملك الرسمي أو اختصارًا واضحًا.",
            "تجنب الرموز التعبيرية إذا كنت تريد أن تبدو محترفًا تمامًا."
          ],
          "args": {
            "name": {
              "description": "اسم العرض الجديد"
            }
          },
          "extraInfo": "\n# الهوية في الجوهر: إدارة اسم عرض واتساب الخاص بك\n\nيعد اسم العرض (المعروف أيضاً باسم \"Push Name\") أهم خاصية نصية لحساب واتساب الخاص بنشاطك التجاري. وهو ما يراه المستخدمون في إشعاراتهم عندما تراسلهم لأول مرة، *قبل* أن يفتحوا الدردشة الخاصة بك. تمنحك نقطة النهاية `/v2/profile/name` القدرة على تحديث هذه الخاصية برمجياً، ولكنها تأتي مع مسؤوليات امتثال كبيرة.\n\n---\n\n## 🏗️ القيود التقنية والامتثال\n\nعلى عكس سمات الملف الشخصي الأخرى، يخضع اسم العرض لرقابة آلية صارمة من قبل أنظمة النزاهة في Meta.\n\n1.  **حد الطول**: يجب أن يتراوح الاسم بين **3 و 25 حرفاً**.\n2.  **مجموعة الأحرف**: يمكن أن يحتوي على رموز تعبيرية ونصوص محلية (العربية، السيريلية، إلخ) ولكنه لا يمكن أن يحتوي على روابط URL أو أرقام هواتف أو أحرف خاصة تُستخدم لانتحال شخصية كيانات واتساب الرسمية (على سبيل المثال، \"WhatsApp Support\" محظور).\n3.  **تنبيه المراجعة**: قد يؤدي تغيير اسمك بشكل متكرر (على سبيل المثال، أكثر من 3 مرات في 24 ساعة) إلى تفعيل علامة \"نشاط مشبوه\"، مما يتسبب في تقييد رقمك مؤقتاً من إرسال قوالب التسويق.\n\n---\n\n## 🚀 أنماط التسمية الاستراتيجية\n\n### 1. التنسيق \"المحقق\"\nإذا كنت تهدف للحصول على حساب نشاط تجاري رسمي (العلامة الخضراء) في المستقبل:\n- **القاعدة**: يجب أن يتطابق اسم العرض الخاص بك مع اسم عملك القانوني *تماماً*.\n- **التأثير**: لا تستخدم تنويعات \"لطيفة\". إذا كان كيانك القانوني هو \"شركة أكمي المحدودة\"، فاجعل اسم العرض \"أكمي\".\n\n### 2. اللاحقة القسمية (للحسابات غير المحققة)\nإذا كنت تدير مثيلات متعددة لفرق مختلفة:\n- **النمط**: \"أكمي - الدعم\"، \"أكمي - المبيعات\".\n- **الفائدة**: يساعد هذا المستخدمين على التمييز بين البوتات التي يتحدثون إليها، مما يحسن تجربة المستخدم بشكل كبير.\n\n---\n\n## 🛡️ أفضل الممارسات لتحديد المعدل\n\n*   **اضبطه وانسه**: عامل اسم العرض كإعداد \"تكوين\"، وليس قناة \"تسويق\". لا تحاول تغيير اسمك يومياً لجذب الانتباه.\n*   **فترة \"التهدئة\"**: بعد تغيير اسمك، انتظر **30 ثانية** على الأقل قبل إرسال الرسالة التالية. يسمح هذا للاسم الجديد بالانتشار عبر خوادم واتساب.\n\n---\n\n## 🧩 حالة استخدام متقدمة: العلامة التجارية المحلية\n\nللشركات العالمية التي تعمل في مناطق متعددة:\n- **الاستراتيجية**: استخدم أرقاماً (مثيلات) مميزة لكل سوق واضبط اسم العرض باللغة المحلية.\n    - *المثيل أ (السعودية)*: \"شركة الدعم\"\n    - *المثيل ب (أمريكا)*: \"Support Co.\"\n\n---\n\n## ⚠️ اعتبارات هامة\n\n*   **المستخدمين**: بمجرد أن يحفظ المستخدم رقم هاتفك في دفتر عناوينهم الشخصي باسم معين، فإن هذا الاسم المحلي سيمثل دوماً **تجاوزاً** لاسم العرض الذي حددته عبر API في عرضهم. لا يمكنك فرض تحديث على قائمة جهات اتصال المستخدم.\n            "
        }
      }
    },
    {
      "path": "/v2/profile/status",
      "methods": [
        "PUT"
      ],
      "title": "Set 'About' status",
      "category": "Whatsapp Profile info",
      "description": "Update your WhatsApp 'About' (bio) status.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "status": {
          "required": true,
          "type": "string",
          "description": "New status text",
          "example": "Available for support"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "ضبط حالة 'حول'",
          "description": "قم بتحديث حالة 'حول' (السيرة الذاتية) الخاصة بك على واتساب.",
          "tips": [
            {
              "title": "معلومات الحول",
              "content": "يقوم بتحديث الحالة النصية (سابقًا 'حول') في ملفك الشخصي."
            },
            {
              "title": "الحد",
              "content": "بحد أقصى 139 حرفًا."
            }
          ],
          "recommendations": [
            "قم بتضمين ساعات عملك أو موقع الدعم هنا.",
            "استخدم هذه المساحة لشعار قصير."
          ],
          "args": {
            "status": {
              "description": "نص الحالة الجديد"
            }
          },
          "extraInfo": "\n# لافتة المتجر الرقمية: إدارة نص \"حول\" الخاص بك\n\nيعد حقل \"حول\" (المعروف سابقاً باسم \"الحالة\") عبارة عن سطر نصي بطول 139 حرفاً يظهر تحت اسم نشاطك التجاري في قائمة جهات اتصال المستخدم. على الرغم من تجاهله غالباً، إلا أنه **مؤشر مستوى خدمة** قوي. تسمح لك نقطة النهاية `/v2/profile/status` بمعاملة هذا الحقل كلوحة تحكم ديناميكية، تبث حالتك التشغيلية الحالية لأي شخص يعرض ملفك الشخصي.\n\n---\n\n## 🏗️ المواصفات التقنية\n\nتعد هذه واحدة من أكثر نقاط النهاية خفة في مجموعة Wawp، ولكن لها قيود محددة:\n1.  **حد الطول**: الحد الأقصى **139 حرفاً**. سيقوم API باقتطاع أو رفض السلاسل الأطول.\n2.  **الظهور**: افتراضياً، يكون هذا مرئياً للجميع ما لم تقيد إعدادات الخصوصية في الهاتف ظهور \"حول\" لـ \"جهات اتصالي\" أو \"لا أحد\".\n3.  **لا يوجد نص منسق**: على عكس الرسائل، لا يمكنك استخدام تنسيق عريض/مائل هنا. ومع ذلك، فإن **الرموز التعبيرية (Emojis)** مدعومة بالكامل ويوصى بها بشدة للتدرج البصري.\n\n---\n\n## 🚀 أنماط الحالة الديناميكية\n\n### 1. لافتة \"مفتوح/مغلق\"\nقم بأتمتة ساعات عملك مباشرة على ملفك الشخصي.\n- **سير العمل**: ربط نقطة النهاية هذه بنظام الجدولة الداخلي الخاص بك.\n- **الحالة أ (9 صباحاً - 5 مساءً)**: \"🟢 متصل | الرد المعتاد: أقل من 5 دقائق\"\n- **الحالة ب (5 مساءً - 9 صباحاً)**: \"🌙 غير متصل | اترك رسالة، وسنرد في الساعة 9 صباحاً.\"\n\n### 2. إدارة الحوادث\nأثناء انقطاع الخدمة، يمتلئ فريق الدعم بأسئلة \"هل النظام متعطل؟\".\n- **تشتيت استباقي**: قم بتحديث حالتك إلى: \"⚠️ صيانة النظام جارية. التحديثات على status.acme.com\".\n- **الفائدة**: سيرى المستخدمون الذين يتحققون من ملفك الشخصي ذلك فوراً، مما قد يمنع إنشاء تذكرة دعم.\n\n---\n\n## 🛡️ أفضل الممارسات للتفاعل\n\n*   **أضف لمسة إنسانية للبوت**: إذا كان رقمك مؤتمتاً بشكل أساسي، فاذكر ذلك بوضوح.\n    *   *مثال*: \"🤖 بوت حجز مؤتمت | اكتب 'مساعدة' للتحدث مع إنسان.\"\n*   **تجنب \"متوفر\"**: الحالة الافتراضية في واتساب هي \"متوفر\" (Available). إن تغييرها إلى شيء محدد (حتى مجرد شعارك) يجعل عملك يبدو فوراً أكثر نشاطاً ومهنية.\n\n---\n\n## 🧩 حالة استخدام متقدمة: تعاقب الوكلاء\n\nلرقم دعم مشترك بين عدة وكلاء:\n- **المنطق**: عندما يسجل وكيل دخوله إلى لوحة التحكم، قم بإضافة اسمه إلى الحالة.\n    *   *مثال*: \"الدعم | في الخدمة: سارة ومايك 👥\"\n\n---\n\n## ⚠️ اعتبارات هامة\n\n*   **مدة التخزين المؤقت**: يقوم واتساب بتخزين نص الحالة مؤقتاً وبقوة على أجهزة العملاء. قد يستغرق التغيير الذي تجريه عبر API **ما يصل إلى 10 دقائق** لينعكس على هاتف المستخدم إذا قام بالتحقق من ملفك الشخصي مؤخراً.\n            "
        }
      }
    },
    {
      "path": "/v2/profile/picture",
      "methods": [
        "PUT"
      ],
      "title": "Upload Whatsapp picture",
      "category": "Whatsapp Profile info",
      "description": "Upload a new profile picture for your WhatsApp account.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "file[url]": {
          "required": true,
          "type": "string",
          "description": "Direct URL to the image",
          "example": "https://wawp.net/logo.jpg"
        },
        "file[filename]": {
          "required": true,
          "type": "string",
          "description": "Name of the file",
          "example": "logo.jpg"
        },
        "file[mimetype]": {
          "required": true,
          "type": "string",
          "description": "MIME type of the image (image/jpeg recommended)",
          "example": "image/jpeg"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "رفع صورة واتساب",
          "description": "قم برفع صورة ملف شخصي جديدة لحساب واتساب الخاص بك.",
          "tips": [
            {
              "title": "المواصفات",
              "content": "أفضل النتائج مع صور JPEG بدقة 640×640 بكسل."
            },
            {
              "title": "القص",
              "content": "يتم قص الصور إلى دائرة؛ حافظ على المحتوى في المنتصف."
            }
          ],
          "recommendations": [
            "استخدم شعارًا عالي التباين يكون مرئيًا في الصور المصغرة.",
            "قم بتحديث صورتك للعطلات أو الحملات الخاصة."
          ],
          "args": {
            "file[url]": {
              "description": "رابط مباشر للصورة"
            },
            "file[filename]": {
              "description": "اسم الملف"
            },
            "file[mimetype]": {
              "description": "نوع MIME للصورة (يوصى بـ image/jpeg)"
            }
          },
          "extraInfo": "\n# الهوية البصرية: إتقان صورة الملف الشخصي\n\nصورة ملفك الشخصي هي أول ما يراه المستخدمون عندما يتلقون إشعاراً منك. الشعار الاحترافي عالي الدقة يبني ثقة فورية. تسمح لك نقطة النهاية `/v2/profile/picture` بتحديث هذا الأصل برمجياً، مما يتيح استراتيجيات علامة تجارية ديناميكية (على سبيل المثال، \"شعارات الأعياد\").\n\n---\n\n## 🏗️ المتطلبات التقنية وإرشادات الأصول\n\nلضمان ظهور علامتك التجارية بشكل واضح على جميع الأجهزة، التزم بهذه المواصفات الصارمة:\n\n1.  **التنسيق**: **JPEG** هو التنسيق الأصلي لواتساب. ملفات PNG مدعومة ولكن سيتم تحويلها، مما يؤدي غالباً إلى زيادة حجم الملف أو تغييرات طفيفة في الألوان.\n2.  **الأبعاد**:\n    *   **الحد الأدنى**: 192x192 بكسل.\n    *   **الموصى به**: **640x640 بكسل** أو أعلى.\n    *   **نسبة العرض إلى الارتفاع**: **1:1 (مربع)** حصرياً. سيتم قص الصور غير المربعة من المركز أو رفضها.\n3.  **حجم الملف**: حافظ على حجم الرفع أقل من **2 ميجابايت**.\n\n---\n\n## 🚀 تحذير \"المنطقة الآمنة\"\nيطبق واتساب **قناعاً دائرياً** على صورتك المربعة في قائمة الدردشة وشريط الإشعارات.\n*   **الخطر**: إذا وضعت نصاً أو شعارات في زوايا صورتك المربعة، فسيتم قصها.\n*   **الحل**: عامل **الدائرة المركزية بنسبة 70%** كـ \"منطقة آمنة\". تأكد من أن أيقونة شعارك متمركزة تماماً ولديها مساحة كافية (مساحة سلبية) حولها.\n\n---\n\n## 🛡️ سلوك المزامنة\n\n*   **سرعة الانتشار**: على عكس الرسائل التي تصل فوراً، تنتقل صور الملف الشخصي عبر بنية تحتية مختلفة لـ CDN. قد يستغرق الأمر **ما يصل إلى 5 دقائق** لتظهر صورتك الجديدة على جميع أجهزة عملائك.\n*   **إعدادات الخصوصية**: يحترم API قواعد الخصوصية العالمية لجهازك. لخطوط الأعمال، اضبط هذا دائماً على **\"الجميع\"**.\n\n---\n\n## ⚠️ اعتبارات هامة\n\n*   **إمكانية الوصول للرابط**: يجب أن يكون الرابط `file[url]` الذي تقدمه متاحاً للجمهور. يحتاج محرك Wawp إلى تنزيل الصورة من هذا الرابط قبل إعادة رفعها إلى واتساب.\n*   **حدود المعدل**: تغيير صورتك بشكل متكرر (على سبيل المثال، كل دقيقة) سيؤدي إلى حظر سبام. حدد التحديثات بحد أقصى **5 مرات في اليوم**.\n*   **الحذف مقابل الاستبدال**: لست بحاجة إلى حذف الصورة القديمة قبل رفع واحدة جديدة. الرفع الجديد يستبدل الأصل الحالي تلقائياً.\n            "
        }
      }
    },
    {
      "path": "/v2/profile/picture-delete",
      "realPath": "/v2/profile/picture",
      "methods": [
        "DELETE"
      ],
      "title": "Delete profile picture",
      "category": "Whatsapp Profile info",
      "description": "Remove your current WhatsApp profile picture.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "حذف صورة الملف الشخصي",
          "description": "قم بإزالة صورة ملفك الشخصي الحالية على واتساب.",
          "tips": [
            {
              "title": "الافتراضي",
              "content": "يعيد صورة ملفك الشخصي إلى الصورة الظلية الرمادية الافتراضية."
            },
            {
              "title": "الظهور",
              "content": "ستري جهات الاتصال التغيير فورًا."
            }
          ],
          "recommendations": [
            "احذف فقط إذا كان شعارك الحالي قديمًا أو غير صحيح.",
            "من الناحية المثالية، استبدل الصورة مباشرة بدلاً من الحذف أولاً."
          ],
          "extraInfo": "\n# الصمت البصري: إدارة حذف صورة الملف الشخصي\n\nهناك أوقات يكون فيها \"غياب العلامة التجارية\" هو أفضل استراتيجية. تسمح لك نقطة النهاية `/v2/profile/picture` بدعوة DELETE بالعودة فوراً إلى الأفاتار الافتراضي لواتساب. وهذا مفيد للتحكم في الخصوصية، أو إنهاء خدمة الوكلاء، أو الإشارة إلى حالة \"التخفي\".\n\n---\n\n## 🏗️ السلوك التقني\n\nعند استدعاء نقطة النهاية هذه، يقوم محرك Wawp بـ:\n1.  **إرسال حزمة إزالة**: يأمر خادم واتساب بإلغاء ربط ملف الصورة الحالي بـ JID الخاص بك.\n2.  **مسح التخزين المؤقت**: يبطل الرابط العام المرتبط بملفك الشخصي.\n3.  **النتيجة**: سيرى المستخدمون الذين يشاهدون ملفك الشخصي \"الأفاتار الرمادي\" العام (👤) على الفور.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. وضع \"خارج الخدمة\"\nللخطوط الشخصية للوكلاء:\n- **سير العمل**: عندما يذهب وكيل في إجازة، قم بحذف صورة ملفه الشخصي تلقائياً.\n- **الإشارة**: تخبر هذه الإشارة البصرية اللطيفة العملاء الدائمين أن \"هذا الشخص غير نشط حالياً\"، مما يقلل من توقعاتهم بالرد الفوري.\n\n---\n\n## ⚠️ اعتبارات هامة\n\n*   **عدم القابلية للتراجع**: بمجرد حذفها، تختفي الصورة القديمة من خوادم واتساب. لا يمكنك \"التراجع\" عن هذا. لاستعادتها، يجب إعادة رفع الملف الأصلي باستخدام نقطة نهاية رفع الصورة.\n*   **تحديد المعدل**: مثل عمليات الرفع، فإن عمليات الحذف تخضع لتحديد المعدل. لا تقم بتبديل صورتك بين الظهور والاختفاء بشكل سريع جداً.\n            "
        }
      }
    },
    {
      "path": "/v2/presence-overview",
      "methods": [
        "GET"
      ],
      "category": "Presence information",
      "isArticle": true,
      "title": "Presence & Availability",
      "description": "Manage your online status and check the availability of your contacts.",
      "extraInfo": "\n# The Ghost in the Machine: Mastering WhatsApp Presence\n\nPresence information—the delicate dance of \"Online\", \"Typing...\", and \"Last Seen\"—is the heartbeat of real-time communication. In the context of the Wawp API, managing presence is not just about vanity metrics; it is a critical component of **Trust Engineering** and **Session Health**.\n\nThe `/v2/presence-overview` category encompasses the tools you need to signal your bot's availability to the world and, conversely, to understand the availability of your users.\n\n---\n\n## 🧠 The Psychology of \"Online\"\n\nBefore diving into code, it is essential to understand how humans perceive presence on WhatsApp.\n\n### 1. The Expectation of Immediacy\nWhen a user sees your business account is **Online**, they expect a reply within *seconds*.\n*   **The Risk**: If your bot marks itself as online continuously (24/7) but takes 5 minutes to process a request due to queueing, users will perceive the service as \"broken\" or \"ignoring them.\"\n*   **The Strategy**: Use the **Set Presence** endpoint to toggle your state to `available` *only* when your webhook consumer is healthy and processing at full speed. If your backend is under maintenance, explicitly set your presence to `unavailable`.\n\n### 2. The Provenance of \"Last Seen\"\nFor personal accounts, \"Last Seen\" is a casual privacy feature. For business automation, it is a **Liveness Probe**.\n*   **Trust Signal**: A business account that was \"Last seen today at 10:00 AM\" feels active. An account \"Last seen Dec 12, 2023\" feels abandoned/dead.\n*   **Automation**: You can use a scheduled job to momentarily toggle your presence to online and back to offline once every few hours. This updates your \"Last Seen\" timestamp, reassuring users that the line is still active even if no messages are being sent.\n\n---\n\n## 🏗️ Technical Architecture of Presence\n\nWhatsApp's presence system is built on a **Publish-Subscribe (PubSub)** model, which differs significantly from the standard Request-Response HTTP model.\n\n### 1. The Subscription Model (`/subscribe`)\nYou cannot simply \"GET\" the status of any random number on WhatsApp. That would be a massive privacy breach and a technical impossibility given the billions of users.\n*   **The Mechanism**: To receiving presence updates for a specific user (e.g., to know when they come online), your device must explicitly **Subscribe** to their presence feed.\n*   **duration**: These subscriptions are *ephemeral*. They typically last about **20-60 seconds**. After that, the WhatsApp server stops sending you updates to save bandwidth.\n*   **Implication**: You must implement a \"Heartbeat\" loop if you need to track a user continuously during a live support session.\n\n### 2. The Reciprocity Rule\nIn strict privacy settings, a user may not share their status with you unless you share yours with them.\n*   **API Behavior**: If you force your own presence to `offline` (ghost mode), you might find that the API returns `null` or outdated data when you try to query users.\n*   **Best Practice**: Maintain a \"Title-for-Tat\" configuration. If you want to see them, let them see you.\n\n### 3. The \"Typing\" Indicator\nWhile not strictly a \"Presence\" state (it's an ephemeral event), the \"Typing...\" indicator is closely related.\n*   **Gap Filling**: It bridges the gap between \"Read\" (Double Blue Checks) and \"Response\".\n*   **UX Tip**: Always trigger `/v2/send/start-typing` *before* your bot begins a long processing task (like generating an AI image). This buys you 5-10 seconds of user patience.\n\n---\n\n## 🛡️ Anti-Ban & Rate Limiting\n\nScanning for presence is one of the most dangerous activities for a WhatsApp bot.\n\n### Why is it risky?\nMalicious actors use \"Presence Checking\" to build databases of active phone numbers (e.g., checking 1 million random numbers to see which ones are registered). WhatsApp's AI defenses are extremely aggressive against this pattern.\n\n### The Golden Rules:\n1.  **Never Check Strangers**: Only query the presence of users who have *messaged you first*.\n2.  **No Bulk Scanning**: Never loop through your entire contacts database checking status.\n3.  **Context Aware**: Only subscribe to presence when a conversation is *active* (i.e., within the 24-hour service window).\n4.  **Rate Limits**: The API will return `429 Too Many Requests` if you subscribe to more than ~50 users per minute.\n\n---\n\n## 🚀 Strategic Implementation Patterns\n\n### Pattern A: The \"Live Agent\" Handoff\nWhen a user asks to speak to a human:\n1.  **Check User**: Call `/v2/presence/{chatId}` to see if the user is currently looking at the chat.\n2.  **Route**:\n    *   **If Online**: Route to a Priority Queue for immediate pickup.\n    *   **If Offline**: Route to a standard ticket system and send an email notification instead.\n\n### Pattern B: The \"Optimistic\" Blast\nMarketing messages have higher conversion rates when delivered while the phone is in the user's hand.\n1.  **Monitor**: For a small cohort of VIP users, listen for valid `presence_update` webhook events.\n2.  **Trigger**: If a VIP comes online, trigger the pending offer message immediately.\n3.  **Result**: The notification arrives while they are already unlocking their phone, maximizing visibility.\n\n### Pattern C: The \"Ghost\" Admin\nStartups often want to monitor groups without being noticed.\n1.  **Set Status**: Call `/v2/presence` with `status: unavailable`.\n2.  **Disable Read Receipts**: Update privacy settings.\n3.  **Result**: Your bot can read every message and log data, but to the group members, it appears completely offline and silent, reducing the \"Big Brother\" effect.\n\n---\n\n## 🧩 Integration with Webhooks\n\nWhile these HTTP endpoints allow you to *act*, the primary way to *consume* presence data is via Webhooks.\n\n*   **Event**: `presence_update`\n*   **Payload**: Contains `id` (Subject) and `status` (available/unavailable).\n*   **Note**: You will *only* receive these webhooks for users you have recently subscribed to or currently have an open chat with. You will not get a firehose of the entire world's activity. (See the [Webhooks Documentation](/docs/webhooks) for payload examples).\n    ",
      "args": {},
      "tips": [
        {
          "type": "warning",
          "title": "Polling Risk",
          "content": "Repeatedly polling other users' presence is the #1 cause of bot account bans. Use it sparingly."
        }
      ],
      "recommendations": [
        "Use 'online' presence mainly during active support hours.",
        "Combine presence data with read receipts for a full view of user activity.",
        "Respect the 'Offline' state as it often indicates a user is busy or sleeping."
      ],
      "responses": [],
      "translations": {
        "ar": {
          "title": "التواجد والتوفر",
          "description": "إدارة حالة اتصالك بالإنترنت والتحقق من توفر جهات الاتصال الخاصة بك.",
          "tips": [
            {
              "title": "حدود معدل API",
              "content": "احترم حدود معدل API لتجنب الحظر المؤقت."
            },
            {
              "title": "العمليات غير المتزامنة",
              "content": "معظم العمليات غير متزامنة. استخدم Webhooks للتحديثات في الوقت الفعلي."
            }
          ],
          "recommendations": [
            "استخدم متغيرات البيئة لبيانات الاعتماد الحساسة مثل رموز الوصول.",
            "قم بتنفيذ معالجة قوية للأخطاء ومنطق إعادة المحاولة."
          ],
          "extraInfo": "\n# الشبح في الآلة: إتقان التواجد على واتساب\n\nمعلومات التواجد — الرقصة الدقيقة بين \"متصل\"، \"يكتب...\"، و \"آخر ظهور\" — هي نبض الاتصال في الوقت الفعلي. في سياق واجهة برمجة تطبيقات Wawp، لا تتعلق إدارة التواجد بمجرد مقاييس الغرور؛ بل هي مكون حاسم في **هندسة الثقة** و **صحة الجلسة**.\n\nتتضمن فئة `/v2/presence-overview` الأدوات التي تحتاجها للإشارة إلى مدى توفر البوت الخاص بك للعالم، وبالعكس، لفهم مدى توفر مستخدميك.\n\n---\n\n## 🧠 سيكولوجية \"متصل الآن\"\n\nقبل الغوص في الأكواد، من الضروري فهم كيفية إدراك البشر للتواجد على واتساب.\n\n### 1. توقع الفورية\nعندما يرى المستخدم أن حساب عملك **متصل**، فإنه يتوقع رداً في غضون *ثوانٍ*.\n*   **الخطر**: إذا ميز البوت نفسه كمتصل بشكل مستمر (24/7) ولكنه يستغرق 5 دقائق لمعالجة الطلب بسبب الانتظار، فسيشعر المستخدمون أن الخدمة \"معطلة\" أو \"تتجاهلهم\".\n*   **الاستراتيجية**: استخدم نقطة نهاية **تعيين التواجد** لتبديل حالتك إلى `available` *فقط* عندما يكون استهلاك الويب هوك الخاص بك سليماً ويعمل بأقصى سرعة. إذا كان نظامك تحت الصيانة، فقم بتعيين تواجدك صراحةً على `unavailable`.\n\n### 2. أهمية \"آخر ظهور\"\nبالنسبة للحسابات الشخصية، يعد \"آخر ظهور\" ميزة خصوصية عادية. أما بالنسبة لأتمتة الأعمال، فهو **اختبار حياة (Liveness Probe)**.\n*   **إشارة الثقة**: حساب الأعمال الذي \"شوهد آخر مرة اليوم الساعة 10:00 صباحاً\" يشعر المستخدم أنه نشط. أما الحساب الذي \"شوهد آخر مرة في 12 ديسمبر 2023\" فيبدو مهجوراً أو ميتاً.\n*   **الأتمتة**: يمكنك استخدام مهمة مجدولة لتبديل تواجدك للحظات إلى متصل ثم العودة إلى غير متصل مرة كل بضع ساعات. هذا يحدث طابع \"آخر ظهور\" الخاص بك، مما يطمئن المستخدمين بأن الخط لا يزال نشطاً حتى لو لم يتم إرسال أي رسائل.\n\n---\n\n## 🏗️ البنية التقنية للتواجد\n\nيعتمد نظام التواجد في واتساب على نموذج **النشر والاشتراك (Publish-Subscribe)**، والذي يختلف بشكل كبير عن نموذج HTTP القياسي (طلب-استجابة).\n\n### 1. نموذج الاشتراك (`/subscribe`)\nلا يمكنك ببساطة \"جلب\" حالة أي رقم عشوائي على واتساب. سيكون ذلك انتهاكاً كبيراً للخصوصية ومستحيلاً تقنياً بالنظر إلى مليارات المستخدمين.\n*   **الآلية**: لتلقي تحديثات التواجد لمستخدم معين (مثلاً، لمعرفة متى يصبح متصلاً)، يجب على جهازك **الاشتراك** صراحةً في موجز تواجده.\n*   **المدة**: هذه الاشتراكات *مؤقتة*. تستمر عادةً لمدة تتراوح بين **20-60 ثانية**. بعد ذلك، يتوقف خادم واتساب عن إرسال التحديثات لتقليل استهلاك البيانات.\n*   **النتيجة**: يجب عليك تنفيذ حلقة \"نبضات القلب\" إذا كنت بحاجة إلى تتبع مستخدم بشكل مستمر خلال جلسة دعم مباشرة.\n\n### 2. قاعدة المعاملة بالمثل\nفي إعدادات الخصوصية الصارمة، قد لا يشارك المستخدم حالته معك ما لم تشارك حالتك معه.\n*   **سلوك الواجهة**: إذا قمت بفرض حالة تواجدك على `offline` (وضع التخفي)، فقد تجد أن واجهة برمجة التطبيقات تعيد `null` أو بيانات قديمة عندما تحاول الاستعلام عن المستخدمين.\n*   **أفضل ممارسة**: حافظ على تكوين \"واحدة بواحدة\". إذا كنت تريد رؤيتهم، فاجعلهم يروك.\n\n### 3. مؤشر \"يكتب الآن\"\nعلى الرغم من أنه ليس حالة \"تواجد\" بالمعنى الدقيق (فهو حدث مؤقت)، إلا أن مؤشر \"يكتب...\" مرتبط به وثيقاً.\n*   **سد الفجوة**: إنه يربط الفجوة بين \"تمت القراءة\" (العلامات الزرقاء المزدوجة) والرد الفعلي.\n*   **نصيحة تجربة المستخدم**: قم دائماً بتشغيل `/v2/send/start-typing` *قبل* أن يبدأ البوت الخاص بك في مهمة معالجة طويلة (مثل إنشاء صورة بالذكاء الاصطناعي). هذا يمنحك 5-10 ثوانٍ من صبر المستخدم.\n\n---\n\n## 🛡️ مكافحة الحظر وتحديد المعدل\n\nيعد المسح بحثاً عن التواجد أحد أخطر الأنشطة لبوت واتساب.\n\n### لماذا هو خطر؟\nيستخدم الفاعلون الخبثاء \"التحقق من التواجد\" لبناء قواعد بيانات لأرقام الهواتف النشطة. تستخدم الدفاعات الذكية لواتساب عدوانية شديدة ضد هذا النمط.\n\n### القواعد الذهبية:\n1.  **لا تتحقق من الغرباء**: قم فقط بالاستعلام عن تواجد المستخدمين الذين *راسلواك أولاً*.\n2.  **لا للمسح الجماعي**: لا تقم أبداً بالمرور عبر قاعدة بيانات جهات الاتصال بالكامل للتحقق من الحالة.\n3.  **مراعاة السياق**: اشترك في التواجد فقط عندما تكون المحادثة *نشطة* (أي خلال نافذة الخدمة لمدة 24 ساعة).\n4.  **حدود المعدل**: ستعيد واجهة برمجة التطبيقات الخطأ `429 Too Many Requests` إذا قمت بالاشتراك في أكثر من ~50 مستخدماً في الدقيقة.\n\n---\n\n## 🚀 أنماط التنفيذ الاستراتيجية\n\n### النمط أ: تسليم \"العميل المباشر\"\nعندما يطلب مستخدم التحدث إلى إنسان:\n1.  **التحقق من المستخدم**: استدعِ `/v2/presence/{chatId}` لمعرفة ما إذا كان المستخدم ينظر حالياً إلى الدردشة.\n2.  **التوجيه**:\n    *   **إذا كان متصلاً**: وجهه إلى زمام الأولوية القصوى للاستلام الفوري.\n    *   **إذا كان غير متصل**: وجهه إلى نظام التذاكر القياسي وأرسل إشعاراً بالبريد الإلكتروني بدلاً من ذلك.\n\n### النمط ب: التنبيه المتفائل\nتكون معدلات تحويل الرسائل التسويقية أعلى عندما يتم تسليمها بينما يكون الهاتف في يد المستخدم.\n1.  **المراقبة**: لمجموعة صغيرة من كبار العملاء (VIPs)، استمع إلى أحداث الويب هوك الصالحة لـ `presence_update`.\n2.  **التشغيل**: إذا أصبح العميل متصلاً، فقم بتشغيل رسالة العرض المعلقة فوراً.\n\n---\n\n## 🧩 التكامل مع الويب هوك\n\nبينما تسمح لك نقاط نهاية HTTP هذه بـ *القيام بفعل*، فإن الطريقة الأساسية لـ *استهلاك* بيانات التواجد هي عبر الويب هوك.\n\n*   **الحدث**: `presence_update`\n*   **الحمولة**: تحتوي على `id` (الموضوع) و `status` (متوفر/غير متوفر).\n*   **ملاحظة**: ستتلقى هذه الويب هوكات *فقط* للمستخدمين الذين اشتقت فيهم مؤخراً أو لديك دردشة مفتوحة معهم حالياً. لن تحصل على تدفق نشاط للعالم أجمع. (راجع [توثيق الويب هوك](/docs/webhooks) للحصول على أمثلة للحمولات).\n            "
        }
      }
    },
    {
      "path": "/v2/presence",
      "methods": [
        "POST"
      ],
      "title": "Set session presence",
      "category": "Presence information",
      "description": "Sets the presence for the current session (online/offline).",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "presence": {
          "required": true,
          "type": "string",
          "description": "Presence state: online or offline",
          "example": "online"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "تعيين تواجد الجلسة",
          "description": "يحدد التواجد للجلسة الحالية (متصل/غير متصل).",
          "tips": [
            {
              "title": "الأتمتة",
              "content": "تقوم المكتبة تلقائيًا بمعالجة 'متاح' عند الاتصال."
            },
            {
              "title": "إضفاء الطابع الإنساني",
              "content": "اضبط على 'unavailable' عندما يكون الروبوت الخاص بك قيد الصيانة."
            }
          ],
          "recommendations": [
            "لا تقم بتبديل هذا بسرعة لتجنب الإبلاغ عنك.",
            "طابق حضورك مع ساعات عملك."
          ],
          "args": {
            "presence": {
              "description": "حالة التواجد: online أو offline"
            }
          },
          "extraInfo": "\n# الظهور للآخرين: التحكم في هويتك الافتراضية\n\nتمنحك نقطة النهاية `/v2/presence` تحكماً برمجياً في مؤشر **\"متصل\"** الذي يظهر تحت اسمك في محادثات واتساب. على الرغم من بساطته، إلا أن هذا المفتاح أداة قوية لإدارة توقعات المستخدمين وثقتهم.\n\n---\n\n## 🎭 الحالتان\n\nيسمح لك هذا التطبيق بفرض جلستك في إحدى حالتين:\n\n### 1. `available` (متصل)\n*   **بصرياً**: يرى المستخدمون \"متصل\" تحت اسمك.\n*   **المعنى**: \"أنا هنا، التطبيق مفتوح، وأنا مستعد للرد.\"\n*   **سلوك النظام**: يحافظ هاتفك/جلستك على اتصال socket نشط. تعطي خادومات واتساب الأولوية لتسليم الرسائل إليك فوراً.\n\n### 2. `unavailable` (غير متصل)\n*   **بصرياً**: يرى المستخدمون \"آخر ظهور في...\" (أو لا شيء، حسب الخصوصية).\n*   **المعنى**: \"أنا بعيد عن هاتفي.\"\n*   **سلوك النظام**: لا تزال تتلقى الرسائل عبر الويب هوك! تعيين نفسك كغير متصل لا يوقف استلام البيانات، بل يغير فقط الإشارة التي يراها العالم الخارجي.\n\n---\n\n## 🏗️ التنفيذ الاستراتيجي\n\n### السيناريو أ: بوت \"ساعات العمل\"\nإذا كنت تبني بوت دعم عملاء لعيادة أسنان تفتح من 9 صباحاً إلى 5 مساءً.\n*   **في الساعة 09:00**: تقوم مهمة مجدولة باستدعاء `presence: available`.\n*   **في الساعة 17:00**: تقوم مهمة مجدولة باستدعاء `presence: unavailable`.\n    *   *النتيجة*: يرى العملاء \"آخر ظهور اليوم الساعة 17:00\". إذا أرسلوا رسالة، فإنهم يتوقعون لاشعورياً رداً متأخراً، مما يقلل الإحباط.\n\n### السيناريو ب: المحلل \"المتخفي\"\nأنت تشغل بوتاً يسجل الرسائل لأغراض الامتثال في أحد البنوك. لا ينبغي له أبداً التفاعل مع المستخدمين.\n*   **الاستراتيجية**: اضبط التواجد دائماً على `presence: unavailable`.\n*   **السبب**: إذا ظهر بوت الامتثال \"متصلاً\" في الساعة 3 صباحاً، فقد يحاول المستخدمون الدردشة معه. من خلال البقاء غير مرئي، فإنك تقلل الضجيج.\n            "
        }
      }
    },
    {
      "path": "/v2/presence/{chatId}",
      "methods": [
        "GET"
      ],
      "title": "Get the presence for the chat id",
      "category": "Presence information",
      "description": "Retrieves the current presence information for a specific chat ID.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "The chatId to check presence for",
          "example": "123456789@c.us"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "الحصول على تواجد الدردشة",
          "description": "يسترجع معلومات التواجد الحالية لمعرف دردشة معين.",
          "tips": [
            {
              "title": "الوقت الحقيقي",
              "content": "يجلب حالة الاتصال/عدم الاتصال الحالية لجهة اتصال."
            },
            {
              "title": "الخصوصية",
              "content": "يعيد 'unavailable' إذا قام المستخدم بإخفاء آخر ظهور له."
            }
          ],
          "recommendations": [
            "استخدم هذا باعتدال؛ الاقتراع المستمر محدود المعدل.",
            "اشترك في تحديثات الحضور بدلاً من الاقتراع."
          ],
          "args": {
            "chatId": {
              "description": "معرف الدردشة للتحقق من التواجد له"
            }
          },
          "extraInfo": "\n# رؤية الأشباح: التحقق من تواجد المستخدم\n\nتسمح نقطة النهاية `/v2/presence/{chatId}` لنظامك بالاستعلام عن حالة \"متصل\" لمستخدم أو جهة اتصال معينة على واتساب. عند استخدامها بشكل صحيح، فإنها تحول البوت الخاص بك من \"مجيب آلي بسيط\" إلى \"مساعد مدرك للسياق\".\n\n---\n\n## 🎯 فلسفة \"اللقطة\"\n\nمن الضروري فهم أن نقطة النهاية هذه توفر **لقطة في الوقت الحالي**، وليست تدفقاً مستمراً.\n*   **الاستجابة**: \"المستخدم 12345 متصل *الآن*.\"\n*   **الواقع**: قد يغلقون التطبيق بعد ثانية واحدة.\n*   **أفضل ممارسة**: تعامل مع حالة `online` كإشارة قوية بأن المستخدم يمسك بهاتفه، ولكن ليس كضمان للرد.\n\n---\n\n## 🏗️ سير العمل التقني\n\n### 1. التحقق قبل الإرسال\nقبل إرسال رسالة عالية القيمة (مثل رمز التحقق أو تنبيه زمني)، استدعِ نقطة النهاية هذه.\n*   **إذا كان \"متصل\"**: أرسلها عبر واتساب فوراً. احتمالية قراءة عالية في غضون 10 ثوانٍ.\n*   **إذا كان \"غير متصل\"**:\n    *   **الخيار أ**: أرسلها على أي حال (تسليم قياسي).\n    *   **الخيار ب (ذكي)**: أرسلها عبر SMS كبديل إذا كانت الرسالة حرجة.\n\n### 2. حاجز الخصوصية\nتحترم نقطة النهاية هذه **إعدادات الخصوصية للمستخدم** على هاتفه.\n*   **النتيجة**: إذا كان المستخدم يخفي حالته، فستتلقى دائماً `offline` حتى لو كان يدردش معك الآن.\n\n### 3. حدود المعدل ومنع الحظر\n**تحذير**: هذه هي النقطة الأكثر حساسية في مجموعة واجهة برمجة التطبيقات بأكملها.\n*   **النمط الممنوع**: إذا قمت بالمرور على 1000 رقم للتحقق من \"هل أنت متصل؟\"، فسيقوم ذكاء واتساب الاصطناعي **بحظر حسابك**.\n*   **الحد الآمن**: تحقق واحد لكل مستخدم كل 5 دقائق.\n            "
        }
      }
    },
    {
      "path": "/v2/presence",
      "realPath": "/v2/presence/get",
      "methods": [
        "GET"
      ],
      "title": "Get General Presence",
      "category": "Presence",
      "description": "Get the current presence status (online/offline) for the authenticated session.",
      "extraInfo": "\n# Mirror, Mirror: Checking Your Own Reflection\n\nThe `/v2/presence` (GET) endpoint allows you to programmatically verify how your WhatsApp session appears to the outside world. While you can *set* your status using the POST method, this GET method is crucial for auditing and synchronization.\n\n---\n\n## 🏗️ State Verification\n\nWhy check your own status?\n\n### 1. Audit Loops\nIf you manage a fleet of 50 support bots, you need a dashboard to see which ones are currently \"Online\" and accepting chats.\n*   **Workflow**: Central Monitor calls `/v2/presence` on each instance every minute.\n*   **Alert**: If a bot is supposed to be Online but returns `offline`,\n  tips: [\n    {\n        \"type\": \"positive\",\n        \"title\": \"User Experience\",\n        \"content\": \"Show \"typing...\" status to make the bot feel more human-like.\"\n    },\n    {\n        \"type\": \"info\",\n        \"title\": \"Status\",\n        \"content\": \"Online status updates can trigger automation flows.\"\n    }\n],\n  recommendations: [\n    \"Do not keep \"typing\" status active for too long without sending a message.\",\n    \"Respect user privacy regarding online presence.\",\n    \"Use presence webhooks to trigger immediate responses.\"\n],\n  \n   trigger a slack alert to the engineering team. The session might have crashed or been manually toggled by a human using the mobile app.\n\n### 2. UI Synchronization\nIf you are building a custom CRM with a \"Go Online\" toggle button:\n*   **Problem**: You don't know the *initial* state of the button when the page loads.\n*   **Solution**: Call this endpoint on page load. If it returns `available`, render the toggle as green (Active). If `unavailable`, render it as grey (Inactive).\n\n### 3. Debugging \"Ghost\" Issues\nSometimes users complain: \"I see you online but you aren't replying!\"\n*   **Debugger**: Call this endpoint. content:\n    *   Result: `offline`.\n    *   Conclusion: The user is seeing a *cached* state on their device, or you have privacy settings hiding your real status. The API confirms you are effectively invisible.\n\n---\n\n## 🔄 The Feedback Loop\n\n### The \"Auto-Correction\" Pattern\nWhatsApp sessions can sometimes drift. For example, if the physical phone loses internet connection for 10 minutes, WhatsApp might automatically mark the session as `unavailable`.\n*   **Script**:\n    1.  Cron job runs every 5 minutes.\n    2.  Step A: Call `GET /v2/presence`.\n    3.  Step B: If result is `offline` AND expected state is `online` -> Call `POST /v2/presence` to force it back.\n    4.  Result: Self-healing availability.\n\n---\n\n## ⚠️ Limitations\n\n*   **Internal State Only**: This endpoint only returns what the *WhatsApp Web* protocol thinks your status is. It does not strictly guarantee that your phone is reachable (e.g., if the battery died 30 seconds ago, the server might still think you are online for another minute).\n*   **Privacy Masks**: If your privacy settings are set to \"Nobody\", this endpoint might still return `available` (because *you* know you are online), but external users will see nothing. Usage of this data must be combined with an understanding of your privacy configuration.\n    ",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Presence status retrieved",
          "example": {
            "presence": "online"
          }
        },
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "الحصول على التواجد العام",
          "description": "احصل على حالة التواجد الحالية (متصل/غير متصل) للجلسة المصرح بها.",
          "extraInfo": "\n# مرآتي يا مرآتي: التحقق من انعكاسك الخاص\n\nتسمح لك نقطة النهاية `/v2/presence` (بواسطة GET) بالتحقق برمجياً من كيفية ظهور جلسة واتساب الخاصة بك للعالم الخارجي. في حين يمكنك *تعيين* حالتك باستخدام طريقة POST، فإن طريقة GET هذه حاسمة للتدقيق والمزامنة.\n\n---\n\n## 🏗️ التحقق من الحالة\n\nلماذا تتحقق من حالتك الخاصة؟\n\n### 1. حلقات التدقيق\nإذا كنت تدير أسطولاً من 50 بوت دعم، فأنت بحاجة إلى لوحة تحكم لمعرفة أي منها \"متصل\" حالياً ويقبل الدردشات.\n*   **تنبيه**: إذا كان من المفترض أن يكون البوت متصلاً ولكنه يعيد `offline`، فقم بتشغيل تنبيه لفريق الهندسة. قد تكون الجلسة قد توقفت أو تم تبديلها يدوياً بواسطة إنسان باستخدام تطبيق الهاتف.\n\n### 2. مزامنة واجهة المستخدم\nإذا كنت تبني نظام CRM مخصصاً مع زر تبديل \"انتقل إلى وضع الاتصال\":\n*   **الحل**: استدعِ نقطة النهاية هذه عند تحميل الصفحة. إذا أعادت `available`، فاجعل الزر باللون الأخضر (نشط).\n\n---\n\n## 🔄 حلقة الملاحظات\n\n### نمط \"التصحيح التلقائي\"\nيمكن أن تنحرف جلسات واتساب أحياناً. على سبيل المثال، إذا فقد الهاتف الفعلي الاتصال بالإنترنت لمدة 10 دقائق، فقد يتم تمييز الجلسة تلقائياً كـ `unavailable`.\n1.  مهمة مجدولة تعمل كل 5 دقائق.\n2.  الخطوة أ: استدعاء `GET /v2/presence`.\n3.  الخطوة ب: إذا كانت النتيجة `offline` والحالة المتوقعة هي `online` -> استدعاء `POST /v2/presence` لفرض العودة للوضع النشط.\n            "
        }
      }
    },
    {
      "path": "/v2/presence/{chatId}/subscribe",
      "methods": [
        "POST"
      ],
      "title": "Subscribe to Presence",
      "category": "Presence",
      "description": "Subscribe to real-time presence updates (online/offline) for a specific contact.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "The identifier for the contact (@c.us)",
          "example": "447441429009@c.us"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "الاشتراك في التواجد",
          "description": "اشترك في تحديثات التواجد في الوقت الفعلي (متصل/غير متصل) لجهة اتصال معينة.",
          "tips": [
            {
              "title": "الآلية",
              "content": "يخبر واتساب بدفع أحداث الحضور لمستخدم معين."
            },
            {
              "title": "انتهاء الصلاحية",
              "content": "تنتهي الاشتراكات بعد فترة قصيرة؛ قم بتجديدها إذا لزم الأمر."
            }
          ],
          "recommendations": [
            "اشترك فقط عندما يكون المستخدم في نافذة دردشة نشطة.",
            "قم بإلغاء الاشتراك عندما يتم إلغاء تحميل مكون واجهة المستخدم لتوفير النطاق الترددي."
          ],
          "args": {
            "chatId": {
              "description": "المعرف الخاص بجهة الاتصال (@c.us)"
            }
          },
          "extraInfo": "\n# النبض الرقمي: الاشتراك في التواجد في الوقت الفعلي\n\nتعد نقطة النهاية `/v2/presence/{chatId}/subscribe` هي \"السلك الحي\" لواجهة برمجة التطبيقات. على عكس طريقة \"اللقطة\"، يصدر هذا الأمر تعليمات لمحرك واتساب لفتح تدفق بيانات مستمر لمستخدم معين.\n\n---\n\n## ⚡ ميكانيكا الاشتراك\n\n### كيف يعمل؟\nعندما تستدعي نقطة النهاية هذه لهدف معين (مثل `12345@c.us`):\n1.  **المصافحة**: يرسل مثيلك بروتوكولاً إلى خوادم واتساب يقول \"أنا مهتم بـ 12345\".\n2.  **التدفق**: تبدأ خوادم واتساب في دفع أحداث `presence.update` إلى الـ socket الخاص بك.\n3.  **المدة**: هذا التدفق **ليس دائماً**. يستمر عادةً لمدة تتراوح بين **20 إلى 60 ثانية** بعد آخر تفاعل أو تجديد للاشتراك.\n\n---\n\n## 🏗️ بنية التنفيذ\n\nلبناء ميزة \"حالة مباشرة\" قوية (مثل نقطة \"متصل\" في واجهة الدردشة)، تحتاج إلى **حلقة نبضات القلب (Heartbeat Loop)**.\n\n### حلقة نبضات القلب\n1.  **حدث الواجهة**: الوكيل يفتح نافذة الدردشة للمستخدم أ.\n2.  **الواجهة**: ترسل حدث \"تركيز\" إلى نظامك الخلفي.\n3.  **النظام الخلفي**: يستدعي `/v2/presence/UserA/subscribe`.\n4.  **الحلقة**: كل **30 ثانية** طالما نافذة الدردشة مفتوحة، يكرر النظام الخلفي استدعاء الاشتراك.\n5.  **التوقف**: عندما يغلق الوكيل نافذة الدردشة، يوقف النظام الخلفي الحلقة. ينتهي الاشتراك تلقائياً بعد 30 ثانية.\n\n---\n\n## 🛡️ القيود الاستراتيجية\n\n*   **حدود التزامن**: عادةً لا يمكنك الاشتراك في أكثر من **~50-100 مستخدم فريد** في نفس الوقت.\n*   **حالة الاستخدام**: تم تصميم هذه الميزة لـ \"الدعم الفردي\" (رؤية الوكيل للأعضاء النشطين)، وليس لـ \"المراقبة الجماعية\" لجميع عملائك في وقت واحد.\n            "
        }
      },
      "tips": [
        {
          "type": "positive",
          "title": "Monitoring",
          "content": "Great for CRM systems that need to know when a customer is active to initiate a chat."
        }
      ]
    },
    {
      "path": "/v2/status-overview",
      "methods": [
        "GET"
      ],
      "category": "24 Hour Status",
      "isArticle": true,
      "title": "WhatsApp Status (Stories)",
      "description": "Learn how to post text, image, and video updates that disappear after 24 hours.",
      "extraInfo": "\n# WhatsApp Status (Stories): The Ephemeral Engagement Engine\n\n\"Status\" is WhatsApp's take on the \"Stories\" format popularised by Instagram and Snapchat. It allows users to share text, photo, video, and GIF updates that disappear after 24 hours.\n\nFor businesses and developers using the Wawp API, Status is not just a social feature—it is a **High-Bandwidth Broadcast Channel** that bypasses the friction of direct messaging.\n\n---\n\n## 🚀 Why Use Programmatic Status?\n\n### 1. The \"Non-Intrusive\" Nudge\nSending a Direct Message (DM) to a user's phone triggers a push notification, a sound, and a vibration. It demands attention. If you do this too often for marketing, users will block you.\n*   **The Status Advantage**: Posting a status update is **silent**. It appears in the \"Updates\" tab with a small dot. Users view it *voluntarily* when they are bored or browsing.\n*   **Retention**: This allows you to stay \"Top of Mind\" daily without being annoying.\n\n### 2. High-Fidelity Showcasing\nA text message limit is 4096 characters. A Status video can be 30 seconds of 1080p video.\n*   **Show, Don't Tell**: Instead of sending a PDF catalog, post a 30-second video tour of your new real estate listing.\n*   **Engagement**: Statuses are consumed in a full-screen, immersive format.\n\n### 3. The \"FOMO\" Effect\nThe 24-hour expiration creates natural urgency (\"Fear Of Missing Out\").\n*   **Flash Sales**: \"Scan this QR code in the next 4 hours for 50% off.\"\n*   **Behind the Scenes**: Raw, unpolished clips from your warehouse or office build authenticity that polished marketing emails cannot match.\n\n---\n\n## 🛠️ Supported Formats\n\nThe Wawp API gives you full control over all 5 status types:\n\n| Type | Endpoint | Best For | Technical Specs |\n| :--- | :--- | :--- | :--- |\n| **TEXT** | `/v2/status/text` | Announcements, Coupons, Quotes | Custom background colors, fonts, and URLs. |\n| **IMAGE** | `/v2/status/image` | Product Photos, Flyers, Menus | JPEG/PNG. Max 5MB. Aspect Ratio 9:16 recommended. |\n| **VIDEO** | `/v2/status/video` | Demos, Tours, Vlog updates | MP4. Max 30 seconds (hard limit by WhatsApp). |\n| **VOICE** | `/v2/status/voice` | Personal greetings, Podcasting | OGG/MP3. Max 30 seconds. Audio waveform visualisation. |\n| **DELETE** | `/v2/status/delete` | Correction, Removing expired offers | Removes the status from viewers' phones immediately. |\n\n---\n\n## 🏗️ Technical Architecture\n\n### Peer-to-Peer Distribution\nPosting a Status is technically similar to sending a broadcast message, but with a different routing flag.\n*   **Delivery**: When you post a status via API, your instance encrypts the media and uploads it to the WhatsApp Blob Server.\n*   **Distribution**: The node then pushes a \"Status Notification\" entry to the devices of all your contacts who have your number saved.\n*   **Privacy Barrier**: Users will **ONLY** see your status if:\n    1.  You have their number saved in your contacts.\n    2.  **AND** they have your number saved in their contacts.\n    3.  **AND** neither party has blocked the other.\n*   **Implication**: You cannot use Status to spam random numbers. It is strictly a tool for **Retention**, not **Acquisition**.\n\n### The \"New Message ID\" System\nUnlike normal messages where you get an ID *after* sending, Statuses often require a pre-generated ID for complex operations (like tracking viewers).\n*   **Endpoint**: `/v2/status/new-message-id`\n*   **Usage**: Generate an ID -> Post Status with that ID -> Listen to `status.view` webhooks with that ID.\n\n---\n\n## 🔮 Strategic Implementation Workflows\n\n### Workflow A: The \"Daily Digest\" Bot\nFor a News Agency or Stock Market Tracker.\n1.  **08:00 AM**: Generate 3 images (Top Headlines).\n2.  **API Call**: Post Image 1, Image 2, Image 3.\n3.  **API Call**: Post Text \"Tap reply to get full articles!\".\n4.  **Result**: Users wake up to a curated story reel.\n\n### Workflow B: The \"E-Commerce Countdown\"\nFor a Flash Sale.\n1.  **10:00 AM**: Post Video teaser \"Sale starts in 2 hours\".\n2.  **12:00 PM**: Post Image \"SALE LIVE! Link in bio\".\n3.  **11:59 PM**: Call `/v2/status/delete` to remove the offer so no one sees it after it expires.\n\n### Workflow C: The \"Influencer\" Mode\nFor Personal Branding bots.\n1.  **Trigger**: New Blog Post published on WordPress.\n2.  **Action**: Bot takes the featured image and the excerpt.\n3.  **API Call**: `/v2/status/text` with `backgroundColor: #FF0000` and the URL.\n4.  **Result**: Automated cross-posting to WhatsApp.\n\n---\n\n## 🛡️ Best Practices & Limits\n\n### 1. Aspect Ratios Matter\nWhatsApp Stories are viewed vertically on mobile phones.\n*   **Do**: Use **9:16** (1080x1920 pixels). It fills the screen.\n*   **Don't**: Use **16:9** (Landscape). It will look tiny with massive black bars, effectively ruining the immersion.\n\n### 2. The 30-Second Rule\nWhatsApp strictly enforces a duration limit on videos.\n*   **Video**: Max 30 seconds. If you upload a 60s video, it will either be rejected or trimmed to the first 30s.\n*   **Split**: To post longer content, you must split your video into 30s chunks and post them sequentially as separate statuses.\n\n### 3. Privacy Settings\nYour bot's privacy settings (controlled via the mobile app) determine who sees these API-posted stories.\n*   **My Contacts**: The default. Visible to everyone you have saved.\n*   **My Contacts Except...**: Useful for blacklisting competitors.\n*   **Only Share With...**: Useful for creating a \"Close Friends\" list for VIP content. The API respects these settings strictly.\n\n---\n\n## ❓ FAQ\n\n**Q: Can I see who viewed my status via API?**\nA: **Partially.** If you have read receipts enabled, you may receive `status.view` events via webhook. However, this data is often unreliable at scale and depends heavily on the privacy settings of the *viewers*.\n\n**Q: Can I tag people in a status?**\nA: **Yes.** Use the `contacts` array in `text` or `image` endpoints. Mentioned users will get a specific notification.\n\n**Q: Does posting a status count towards my message limit?**\nA: **No.** Status updates are free and do not consume \"Conversation\" quotas for WhatsApp Business API (Cloud API), but for Wawp (Web Automation), they are just normal actions. However, posting 100 statuses in 1 minute is spam behavior and triggers bans. Keep it to < 10 per day.\n    ",
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "Disappearing Content",
          "content": "Status updates are the best way to share time-sensitive info without cluttering your chat history."
        }
      ],
      "recommendations": [
        "Include a 'Call to Action' in your image captions.",
        "Use high-contrast colors for text statuses to ensure readability.",
        "Monitor your own status using a secondary device to verify layout."
      ],
      "responses": [],
      "translations": {
        "ar": {
          "title": "حالة واتساب (القصص)",
          "description": "تعرف على كيفية نشر تحديثات النصوص والصور والفيديو التي تختفي بعد 24 ساعة.",
          "tips": [
            {
              "title": "حدود معدل API",
              "content": "احترم حدود معدل API لتجنب الحظر المؤقت."
            },
            {
              "title": "العمليات غير المتزامنة",
              "content": "معظم العمليات غير متزامنة. استخدم Webhooks للتحديثات في الوقت الفعلي."
            }
          ],
          "recommendations": [
            "استخدم متغيرات البيئة لبيانات الاعتماد الحساسة مثل رموز الوصول.",
            "قم بتنفيذ معالجة قوية للأخطاء ومنطق إعادة المحاولة."
          ],
          "extraInfo": "\n# حالة واتساب (القصص): محرك التفاعل المؤقت\n\n\"الحالة\" (Status) هي رؤية واتساب لتنسيق \"القصص\" (Stories) الذي شاع في إنستغرام وسناب شات. تتيح للمستخدمين مشاركة تحديثات النصوص والصور والفيديو وGIF التي تختفي بعد 24 ساعة.\n\nبالنسبة للشركات والمطورين الذين يستخدمون واجهة برمجة تطبيقات Wawp، فإن الحالة ليست مجرد ميزة اجتماعية؛ بل هي **قناة بث عالية النطاق** تتجاوز احتكاك المراسلة المباشرة وتصل لجمهورك بطريقة غير اقتحامية.\n\n---\n\n## 🚀 لماذا تستخدم الحالة البرمجية؟\n\n### 1. لفت الانتباه \"غير المزعج\"\nإرسال رسالة مباشرة (DM) يؤدي إلى إطلاق إشعار وصوت واهتزاز، مما يتطلب انتباهاً فورياً. إذا قمت بذلك بشكل متكرر لأغراض التسويق، فقد يحظرك المستخدمون.\n*   **ميزة الحالة**: نشر تحديث الحالة **صامت**. يظهر في علامة تبويب \"المستجدات\" بنقطة صغيرة. يشاهده المستخدمون *طوعياً* عندما يرغبون في ذلك.\n*   **الاحتفاظ بالعملاء**: يتيح لك هذا البقاء في \"ذاكرة\" العميل يومياً دون أن تكون مزعجاً.\n\n### 2. العرض عالي الدقة\nالرسالة النصية تقتصر على 4096 حرفاً. أما فيديو الحالة فيمكن أن يكون 30 ثانية من فيديو بدقة 1080p.\n*   **اعرض، لا تخبر**: بدلاً من إرسال كتالوج PDF، انشر جولة فيديو مدتها 30 ثانية لعقاراتك الجديدة أو عرضاً لمنتجك.\n*   **التفاعل**: يتم استهلاك الحالات بتنسيق ملء الشاشة الذي يوفر تجربة غامرة.\n\n### 3. تأثير \"الخوف من الضياع\" (FOMO)\nانتهاء الصلاحية بعد 24 ساعة يخلق إلحاحاً طبيعياً.\n*   **عروض فلاش**: \"امسح رمز QR هذا في الساعات الأربع القادمة للحصول على خصم 50%.\"\n*   **خلف الكواليس**: اللقطات العفوية وغير المصقولة من مستودعك أو مكتبك تبني أصالة لا يمكن لرسائل التسويق المصقولة بالبريد الإلكتروني مضاهاتها.\n\n---\n\n## 🛠️ الصيغ المدعومة\n\nتمنحك واجهة برمجة تطبيقات Wawp تحكماً كاملاً في جميع أنواع القصة الخمسة:\n\n| النوع | نقطة النهاية | الأنسب لـ | المواصفات التقنية |\n| :--- | :--- | :--- | :--- |\n| **النص** | `/v2/status/text` | الإعلانات، الكوبونات، الاقتباسات | ألوان خلفية مخصصة، خطوط، وروابط. |\n| **الصورة** | `/v2/status/image` | صور المنتجات، المنشورات الدعائية | JPEG/PNG. بحد أقصى 5 ميجابايت. يوصى بنسبة 9:16. |\n| **الفيديو** | `/v2/status/video` | العروض التجريبية، الجولات | MP4. بحد أقصى 30 ثانية (حد صارم من واتساب). |\n| **الصوت** | `/v2/status/voice` | التحيات الشخصية، البودكاست | OGG/MP3. بحد أقصى 30 ثانية. تشكيل موجي للصوت. |\n| **الحذف** | `/v2/status/delete` | التصحيح، إزالة العروض المنتهية | يزيل الحالة من هواتف المشاهدين فوراً. |\n\n---\n\n## 🏗️ البنية التقنية\n\n### التوزيع بين النظراء (P2P)\nنشر الحالة تقنياً يشبه إرسال رسالة بث، ولكن بعلامة توجيه مختلفة.\n*   **حاجز الخصوصية**: سيرى المستخدمون حالتك **فقط** إذا:\n    1.  كان رقمهم محفوظاً في جهات اتصالك.\n    2.  **و** لديهم رقمك محفوظاً في جهات اتصالهم.\n    3.  **و** لم يقم أي طرف بحظر الآخر.\n*   **الخلاصة**: لا يمكنك استخدام الحالة لإرسال رسائل عشوائية (Spam) لأرقام غريبة. إنها أداة لـ **الاحتفاظ بالعملاء**، وليس لـ **الاستحواذ عليهم**.\n\n---\n\n## 🛡️ أفضل الممارسات والحدود\n\n### 1. نسب الجوانب مهمة\nيتم عرض قصص واتساب عمودياً على الهواتف المحمولة.\n*   **افعل**: استخدم نسبة **9:16** (1080x1920 بكسل). فهي تملأ الشاشة بالكامل.\n*   **لا تفعل**: استخدم نسبة **16:9** (العرضي). ستبدو القصة صغيرة جداً مع أشرطة سوداء ضخمة.\n\n### 2. قاعدة الـ 30 ثانية\nيفرض واتساب بصرامة حداً زمنياً للمقاطع.\n*   **الفيديو**: كحد أقصى 30 ثانية. إذا قمت بتحميل فيديو مدته 60 ثانية، فسيتم قصه إلى أول 30 ثانية. لنشر محتوى أطول، يجب تقسيم الفيديو يدوياً إلى أجزاء مدة كل منها 30 ثانية.\n\n### 3. إعدادات الخصوصية\nتحدد إعدادات خصوصية البوت (التي يتم التحكم فيها عبر تطبيق الهاتف المحمول) من يرى هذه القصص المنشورة عبر API. يمكنك تحديد \"جهات اتصالي\" أو \"جهات اتصالي باستثناء...\" أو \"المشاركة فقط مع...\".\n            "
        }
      }
    },
    {
      "path": "/v2/status/text",
      "methods": [
        "POST"
      ],
      "title": "Text status",
      "category": "24 Hour Status",
      "description": "Post a text-based status (story) to WhatsApp.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "text": {
          "required": true,
          "type": "string",
          "description": "Text content for the status",
          "example": "Have a look! https://github.com/"
        },
        "backgroundColor": {
          "required": true,
          "type": "string",
          "description": "Background color in #RRGGBB format",
          "example": "#38b42f"
        },
        "font": {
          "required": true,
          "type": "number",
          "description": "Font ID (0-5 mostly)",
          "example": "0"
        },
        "linkPreview": {
          "required": true,
          "type": "boolean",
          "description": "Enable link preview",
          "example": "true"
        },
        "linkPreviewHighQuality": {
          "required": true,
          "type": "boolean",
          "description": "High quality link preview",
          "example": "false"
        },
        "contacts": {
          "required": true,
          "type": "string",
          "description": "Optional contacts to mention or target",
          "example": "null"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "حالة نصية",
          "description": "انشر حالة نصية (قصة) على واتساب.",
          "tips": [
            {
              "title": "التنسيق",
              "content": "يدعم الخطوط وألوان الخلفية."
            },
            {
              "title": "الظهور",
              "content": "القصص النصية مرئية للغاية بسبب ألوانها الزاهية."
            }
          ],
          "recommendations": [
            "استخدم هذا للإعلانات القصيرة (مثل، 'نحن مفتوحون!').",
            "اجعل النص قصيرًا ومقروءًا."
          ],
          "args": {
            "text": {
              "description": "المحتوى النصي للحالة"
            },
            "backgroundColor": {
              "description": "لون الخلفية بتنسيق #RRGGBB"
            },
            "font": {
              "description": "معرف الخط (0-5 غالباً)"
            },
            "linkPreview": {
              "description": "تمكين معاينة الرابط"
            },
            "linkPreviewHighQuality": {
              "description": "معاينة رابط عالية الجودة"
            },
            "contacts": {
              "description": "جهات اتصال اختيارية للإشارة إليها"
            }
          },
          "extraInfo": "\n# فن الحالة النصية\n\nتسمح لك نقطة النهاية `/v2/status/text` بنشر تحديثات نصية ملونة تمثل **حوالي 40% من إجمالي التفاعل مع الحالات** على واتساب. على عكس حالات الوسائط، يتم عرض الحالات النصية محلياً على جهاز المستخدم، مما يضمن خطوطاً واضحة وتحميلاً فورياً حتى على الشبكات الضعيفة.\n\n---\n\n## 🎨 التنسيق والجماليات\n\n### ألوان الخلفية (`backgroundColor`)\nيجب تقديم كود لون سداسي عشري (Hex). ومع ذلك، لا يدعم واتساب *كل* كود عشوائي.\n*   **أفضل ممارسة**: التزم بلوحة ألوان واتساب الرسمية أو ألوان التصميم المادي (Material Design) الآمنة.\n*   **قاعدة \"الوضع الداكن\"**: تجنب الخلفيات البيضاء النقية (`#FFFFFF`) أو السوداء النقية (`#000000`) لأنها ترهق العين. استخدم نغمات هادئة مثل الأخضر (`#38b42f`) أو التيل (`#008069`) أو الأرجواني (`#6f4c9c`).\n*   **التباين**: النص دائماً باللون **الأبيض**. تأكد من أن خلفيتك توفر تبايناً جيداً.\n\n### الخطوط (`font`)\nيوفر واتساب 5 أنواع خطوط مدمجة:\n*   `0`: **Monitor** (Sans Serif قياسي) - نظيف واحترافي.\n*   `1`: **Script** (متصل) - جيد للرسائل الشخصية والتحيات.\n*   `2`: **Bold** (نمط Impact) - جيد للعناوين العريضة أو التنزيلات.\n*   `3`: **Typewriter** (Monospace) - جيد للأكواد التقنية.\n*   `4`: **Norican** (مزخرف) - مشابه للخط المتصل ولكنه أعرض.\n\n---\n\n## 🔗 قوة معاينات الروابط\n\nهذه هي الميزة الأقوى في الحالة النصية. إذا قمت بتضمين رابط URL في نص الحالة، فلديك خياران:\n\n### 1. رابط بسيط\n*   **النتيجة**: الرابط قابل للنقر، لكنه يظهر كنص عادي.\n*   **معدل النقر (CTR)**: منخفض (~2-3%).\n\n### 2. معاينة غنية (`linkPreview: true`)\n*   **النتيجة**: تقوم الواجهة بجلب معلومات OpenGraph من الموقع المستهدف.\n    *   **الصورة**: تعرض الصورة البارزة للموقع.\n    *   **العنوان**: يظهر عنوان الصفحة بخط عريض.\n    *   **الوصف**: يظهر الوصف التعريفي (Meta Description).\n*   **معدل النقر (CTR)**: مرتفع (~15-20%).\n\n---\n\n## ⚠️ القيود المعروفة\n\n### حد الحروف\nعلى الرغم من أن الحد النظري مرتفع، إلا أن واتساب يقتطع الحالات الطويلة جداً.\n*   **منطقة الأمان**: حافظ على نصك أقل من **700 حرف**.\n*   **الاقتطاع**: إذا كتبت نصاً طويلاً جداً، سيرى المستخدمون زر \"قراءة المزيد\"، مما قد يقلل من جاذبية القصة.\n\n### معاينة الرابط \"الشبح\"\nأحياناً، حتى مع تفعيل المعاينة، لا تظهر.\n*   **السبب**: الموقع الهدف بطيء (>5 ثوانٍ) أو يفتقر إلى وسوم `og:image`.\n*   **التراجع**: ستراجع الواجهة تلقائياً إلى رابط نصي عادي إذا فشل إنشاء المعاينة.\n            "
        }
      }
    },
    {
      "path": "/v2/status/image",
      "methods": [
        "POST"
      ],
      "title": "Image status",
      "category": "24 Hour Status",
      "description": "Post an image status (story) to WhatsApp.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "file[url]": {
          "required": true,
          "type": "string",
          "description": "Direct URL to the image",
          "example": "https://wawp.net/samples/cat.jpg"
        },
        "file[filename]": {
          "required": true,
          "type": "string",
          "description": "Name of the file",
          "example": "image.jpg"
        },
        "file[mimetype]": {
          "required": true,
          "type": "string",
          "description": "MIME type of the image",
          "example": "image/jpeg"
        },
        "caption": {
          "required": true,
          "type": "string",
          "description": "Caption for the image",
          "example": "Check our new menu!"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "حالة صورة",
          "description": "انشر حالة صورة (قصة) على واتساب.",
          "tips": [
            {
              "title": "التفاعل",
              "content": "القصص رائعة للمحتوى غير الرسمي وخلف الكواليس."
            },
            {
              "title": "الجمهور",
              "content": "مرئي لجهات الاتصال التي حفظت رقمك."
            }
          ],
          "recommendations": [
            "انشر إعلانات تشويقية للمنتج أو عروض لفترة محدودة.",
            "استخدم التسميات التوضيحية لإضافة سياق إلى الصورة."
          ],
          "args": {
            "file[url]": {
              "description": "رابط مباشر للصورة"
            },
            "file[filename]": {
              "description": "اسم الملف"
            },
            "file[mimetype]": {
              "description": "نوع MIME للصورة"
            },
            "caption": {
              "description": "تعليق نصي للصورة"
            }
          },
          "extraInfo": "\n# السرد القصصي البصري: حالة الصورة\n\nتعد نقطة النهاية `/v2/status/image` أداة التواصل البصري عالية الدقة. على عكس المنصات الأخرى، تحافظ حالة واتساب على جودة الملف الأصلي بشكل كبير إذا التزمت بالمواصفات الصحيحة.\n\n---\n\n## 📐 النسبة الذهبية: 9:16\n\nحالة واتساب هي تجربة ملء الشاشة **للهواتف المحمولة أولاً**.\n*   **الدقة المستهدفة**: **1080x1920 بكسل**.\n*   **لماذا؟**: هذه الدقة تملأ شاشة معظم الهواتف الحديثة تماماً دون أشرطة سوداء.\n*   **مناطق الأمان**:\n    *   **الأعلى (100 بكسل)**: محجوز لشريط التقدم واسم الملف الشخصي.\n    *   **الأسفل (150 بكسل)**: محجوز لسهم الرد وتراكب التعليق.\n*   **الاستراتيجية**: حافظ على النصوص والشعارات المهمة في **الوسط (1080x1670 بكسل)** لتجنب تغطيتها بعناصر الواجهة.\n\n---\n\n## 🎨 جودة الصورة والضغط\n\nواتساب وقح في ضغط الصور لتوفير البيانات لملياري مستخدم.\n*   **المحرك**: يستخدم واتساب مشفر JPEG يقوم بإزالة البيانات الميتا ويقلل الجودة إلى ~70%.\n*   **التحسين المسبق**:\n    *   **افعل**: ارفع صوراً محسنة بالفعل (مثلاً باستخدام TinyJPG).\n    *   **لا تفعل**: ترسل صوراً مشوشة؛ فآثار الضغط ستظهر بشكل أكبر على الشاشات عالية الدقة.\n*   **التنسيق**: استخدم **JPEG** أو **PNG**.\n\n---\n\n## 📝 التعليقات: الخطاف الخفي\n\nحقل `caption` ليس مجرد نص بديل؛ بل هو تراكب تفاعلي.\n*   **الظهور**: يظهر في أسفل الشاشة.\n*   **السلوك**: إذا كان التعليق طويلاً، فسيتم اقتطاعه. أي شيء يتجاوز **100 حرف** سيتطلب من المستخدم الضغط على \"قراءة المزيد\".\n*   **الاستراتيجية**: استخدم التعليق لـ **طلب إجراء (CTA)**.\n    *   *مثال*: \"اضغط على رد للحصول على جدول المقاسات! 👇\"\n\n---\n\n## 🚀 التنفيذ الاستراتيجي\n\n### 1. تأثير \"الكاروسيل\" (Carousel)\nيمكنك نشر عدة صور بتتابع سريع لإنشاء عرض شرائح.\n*   **الطريقة**: استدعِ الواجهة 3 مرات مع تأخير 0.5 ثانية بين الاستدعاءات.\n\n### 2. حيلة رمز QR\nبما أنه لا يمكنك وضع رابط قابل للنقر *على* الصورة نفسها، يقوم البعض بدمج رمز QR في تصميم الصورة.\n*   **الإجراء**: \"خذ لقطة شاشة لمسح الرمز لاحقاً!\"\n\n---\n\n## 🧩 ملاحظات البروتوكول\n\n### انتهاء الصلاحية\nيتم حذف الصور من الخادم بعد 24 ساعة. إذا كنت تريد \"تثبيت\" حالة (مثل المميزات في إنستغرام)، فهذه الميزة **غير موجودة** في واتساب حالياً. يجب إعادة النشر يومياً إذا أردت بقاء المحتوى دائماً (مثل قائمة الأسعار).\n            "
        }
      }
    },
    {
      "path": "/v2/status/voice",
      "methods": [
        "POST"
      ],
      "title": "Voice status",
      "category": "24 Hour Status",
      "description": "Post a voice status (story) to WhatsApp.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "file[url]": {
          "required": true,
          "type": "string",
          "description": "URL to the audio file (ogg/opus recommended)",
          "example": "https://wawp.net/samples/file_example_OOG_1MG.ogg"
        },
        "file[filename]": {
          "required": true,
          "type": "string",
          "description": "Name of the file",
          "example": "note.ogg"
        },
        "file[mimetype]": {
          "required": true,
          "type": "string",
          "description": "MIME type",
          "example": "audio/ogg; codecs=opus"
        },
        "convert": {
          "required": true,
          "type": "boolean",
          "description": "Enable auto-conversion",
          "example": "true"
        },
        "caption": {
          "required": true,
          "type": "string",
          "description": "Caption for the voice status",
          "example": "Listen to this!"
        }
      },
      "extraInfo": "\n# The Personal Touch: Voice Status\n\nThe `/v2/status/voice` endpoint allows you to post audio recordings directly to your Status feed. Users see an audio player with a waveform visualization, making it distinct from standard video or music files.\n\n---\n\n## 🎙️ Why Voice?\n\n### 1. Intimacy at Scale\nVoice notes are the most personal form of digital communication. Hearing a founder's voice explaining a delay or wishing a \"Happy New Year\" creates a connection that text cannot replicate.\n*   **Trust**: It proves there is a human behind the automation.\n*   **Nuance**: Tone, excitement, and empathy are lost in text but preserved in voice.\n\n### 2. High Accessibility\n*   **Passive Consumption**: Users can listen while driving or walking.\n*   **Literacy**: Great for markets where oral communication is preferred over reading long text blocks.\n\n---\n\n## 🎧 Technical Requirements\n\nWhatsApp is extremely strict about audio formats for Voice Status.\n\n### The \"Opus in OGG\" Rule\nTo get the authentic \"Voice Note\" look (with the waveform), you cannot just upload an MP3.\n*   **Container**: **OGG**.\n*   **Codec**: **Opus**.\n*   **Channels**: **Mono** (1 channel). Stereo often causes the waveform to look flat.\n*   **Sample Rate**: **16000 Hz** or **48000 Hz**.\n\n### How to Convert using FFmpeg\nIf you have an MP3 file, use this command before uploading:\n```bash\nffmpeg -i input.mp3 -c:a libopus -b:a 64k -vbr on -compression_level 10 output.ogg\n```\n\n### The `convert` Solution\nIf you don't want to handle FFmpeg, set `convert: true` in your API call.\n*   **Mechanism**: The API will take your MP3/WAV/AAC and transcode it to OGG/Opus.\n*   **Trade-off**: Adds latency.\n\n---\n\n## 🎨 Visual Customization\n\nUnlike Video (which fills the screen with pixels), a Voice Status is essentially an audio player on top of a colored background.\n\n### Background Colors\nJust like Text Status, you can (and should) strictly define a `backgroundColor`.\n*   **Default**: If you don't specify one, WhatsApp picks a random color (often a garish purple or green).\n*   **Branding**: Use your brand's hex code to maintain visual consistency.\n    *   *Example*: A Red background (`#FF0000`) for urgent alerts.\n    *   *Example*: A Blue background (`#0000FF`) for calm updates.\n\n---\n\n## 🚀 Use Case Ideas\n\n### 1. The \"Morning Briefing\"\n*   **Concept**: A 30-second summary of the stock market or daily news.\n*   **Execution**:\n    1.  Text-to-Speech (TTS) engine generates audio.\n    2.  FFmpeg converts to OGG.\n    3.  API Call: Upload with `backgroundColor: #000000`.\n*   **User Value**: Users get a mini-podcast in their Status feed.\n\n### 2. The \"Pronunciation Guide\"\n*   **Concept**: An educational bot teaching languages.\n*   **Execution**:\n    1.  Image Status: Shows the word \"Bonjour\".\n    2.  Voice Status (Immediately after): Plays the correct pronunciation.\n*   **Result**: A multi-modal verified lesson.\n\n### 3. Music Teasers\n*   **Concept**: An artist dropping a new track.\n*   **Execution**: Upload the 30-second \"hook\" of the song.\n*   **Note**: Ensure `convert: true` is on if uploading MP3 snippets.\n\n---\n\n## ⚠️ Limitations\n\n### The 30-Second Limit (Again)\nJust like video, Voice Statuses are capped at **30 seconds**.\n*   **Truncation**: If you upload a 5-minute podcast, only the first 30 seconds will play. The rest is discarded silently.\n*   **Splitting**: You generally *cannot* split audio as elegantly as video because the pause between statuses breaks the flow of speech. Keep it succinct.\n\n### No \"Seek\" Bar\nVoice Statuses do not always have a seek bar (scrubber) depending on the user's OS version. Users expect to listen from start to finish.\n\n### Privacy\nVoice Statuses obey the same privacy rules (My Contacts, etc.) as the rest of the ecosystem.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Background",
          "content": "Voice statuses allow you to share audio updates with contacts."
        },
        {
          "type": "warning",
          "title": "Duration",
          "content": "Limited to 30 seconds, similar to video status."
        }
      ],
      "recommendations": [
        "Use clear audio; background noise can be distracting.",
        "Add a background color that matches your brand."
      ],
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "حالة صوتية",
          "description": "انشر حالة صوتية (قصة) على واتساب.",
          "tips": [
            {
              "title": "الخلفية",
              "content": "تسمح لك حالات الصوت بمشاركة تحديثات صوتية مع جهات الاتصال."
            },
            {
              "title": "المدة",
              "content": "محدودة بـ 30 ثانية، مشابهة لحالة الفيديو."
            }
          ],
          "recommendations": [
            "استخدم صوتًا واضحًا؛ يمكن أن تكون ضوضاء الخلفية مشتتة للانتباه.",
            "أضف لون خلفية يطابق علامتك التجارية."
          ],
          "args": {
            "file[url]": {
              "description": "رابط ملف الصوت (يوصى بـ ogg/opus)"
            },
            "file[filename]": {
              "description": "اسم الملف"
            },
            "file[mimetype]": {
              "description": "نوع MIME"
            },
            "convert": {
              "description": "تمكين التحويل التلقائي"
            },
            "caption": {
              "description": "تعليق نصي للحالة الصوتية"
            }
          },
          "extraInfo": "\n# اللمسة الشخصية: الحالة الصوتية\n\nتسمح لك نقطة النهاية `/v2/status/voice` بنشر تسجيلات صوتية مباشرة في موجز الحالة الخاص بك. يرى المستخدمون مشغل صوت مع تشكيل موجي (Waveform)، مما يجعلها مختلفة عن ملفات الفيديو أو الموسيقى القياسية.\n\n---\n\n## 🎙️ لماذا الصوت؟\n\n### 1. الحميمية على نطاق واسع\nالملاحظات الصوتية هي أكثر أشكال التواصل الرقمي خصوصية. سماع صوت مؤسس الشركة وهو يوضح سبباً للتأخير أو يهنئ بـ \"عام جديد سعيد\" يخلق اتصالاً لا يمكن للنص محاكاته.\n*   **الثقة**: يثبت وجود إنسان خلف الأتمتة.\n*   **الفروق الدقيقة**: نبرة الصوت والحماس والتعاطف تُفقد في النص ولكنها تُحفظ في الصوت.\n\n---\n\n## 🎧 المتطلبات التقنية\n\nواتساب صارم للغاية بشأن صيغ الصوت للحالة الصوتية.\n\n### قاعدة \"Opus inside OGG\"\nللحصول على مظهر \"الملاحظة الصوتية\" الحقيقي (مع التشكيل الموجي)، لا يمكنك مجرد رفع ملف MP3.\n*   **الحاوية**: **OGG**.\n*   **الترميز**: **Opus**.\n*   **القنوات**: **Mono** (قناة واحدة). القنوات الستيريو تجعل التشكيل الموجي يبدو مسطحاً.\n*   **معدل العينة**: **16000 هرتز** أو **48000 هرتز**.\n\n### حل `convert`\nإذا كنت لا تريد التعامل مع التحويل يدوياً، اضبط `convert: true` في استدعاء الواجهة. ستقوم الواجهة بتحويل ملفات MP3/WAV/AAC إلى OGG/Opus نيابة عنك، مع زيادة طفيفة في وقت الاستجابة.\n\n---\n\n## 🎨 التخصيص البصري\n\nعلى عكس الفيديو، الحالة الصوتية هي في الأساس مشغل صوت فوق خلفية ملونة.\n*   **ألوان الخلفية**: يمكنك (ويجب عليك) تحديد `backgroundColor` بدقة.\n*   **الهوية**: استخدم كود اللون السداسي (Hex) الخاص بعلامتك التجارية للحفاظ على الاتساق البصري.\n\n---\n\n## ⚠️ القيود\n\n### حد الـ 30 ثانية (مرة أخرى)\nتماماً مثل الفيديو، الحالات الصوتية محدودة بـ **30 ثانية**.\n*   **الاقتطاع**: إذا رفعت بودكاست مدته 5 دقائق، سيتم تشغيل أول 30 ثانية فقط، وسيتم تجاهل الباقي بصمت.\n*   **توصية**: ابقَ موجزاً ومركزاً في رسالتك الصوتية.\n            "
        }
      }
    },
    {
      "path": "/v2/status/video",
      "methods": [
        "POST"
      ],
      "title": "Video status",
      "category": "24 Hour Status",
      "description": "Post a video status (story) to WhatsApp.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "file[url]": {
          "required": true,
          "type": "string",
          "description": "URL to the video file",
          "example": "https://wawp.net/samples/file_example_MP4_480_1_5MG.mp4"
        },
        "file[filename]": {
          "required": true,
          "type": "string",
          "description": "Name of the file",
          "example": "video.mp4"
        },
        "file[mimetype]": {
          "required": true,
          "type": "string",
          "description": "MIME type",
          "example": "video/mp4"
        },
        "convert": {
          "required": true,
          "type": "boolean",
          "description": "Enable auto-conversion",
          "example": "true"
        },
        "asNote": {
          "required": true,
          "type": "boolean",
          "description": "Send as video note",
          "example": "false"
        },
        "caption": {
          "required": true,
          "type": "string",
          "description": "Caption for the video",
          "example": "Watch this clip"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "حالة فيديو",
          "description": "انشر حالة فيديو (قصة) على واتساب.",
          "tips": [
            {
              "title": "المدة",
              "content": "تحديثات فيديو الحالة محدودة بـ 30 ثانية."
            },
            {
              "title": "النطاق الترددي",
              "content": "يمكن أن تكون التحميلات ثقيلة؛ قم بتحسين حجم الفيديو قبل الإرسال."
            }
          ],
          "recommendations": [
            "استخدم الفيديو العمودي (نسبة العرض إلى الارتفاع 9:16) للحصول على أفضل مشاهدة.",
            "قم بقص مقاطع الفيديو إلى أكثر 30 ثانية جاذبية."
          ],
          "args": {
            "file[url]": {
              "description": "رابط ملف الفيديو"
            },
            "file[filename]": {
              "description": "اسم الملف"
            },
            "file[mimetype]": {
              "description": "نوع MIME"
            },
            "convert": {
              "description": "تمكين التحويل التلقائي"
            },
            "asNote": {
              "description": "إرسال كملاحظة فيديو دائرية"
            },
            "caption": {
              "description": "تعليق نصي للفيديو"
            }
          },
          "extraInfo": "\n# الحركة والعاطفة: حالة الفيديو\n\nتسمح لك نقطة النهاية `/v2/status/video` بنشر مقاطع قصيرة وجذابة. الفيديو هو التنسيق الأكثر تفاعلاً على واتساب، وغالباً ما يحقق **ثلاثة أضعاف معدل الاحتفاظ** مقارنة بالصور الثابتة.\n\n---\n\n## ⏱️ حد الـ 30 ثانية الصارم\n\nهذا هو القيد الأكثر حرجاً في بروتوكول حالة واتساب.\n*   **المدة القصوى**: **30 ثانية**.\n*   **السلوك**: إذا رفعت فيديو مدته 60 ثانية، فسيقوم واتساب إما **بفشل الرفع** أو قصه بشكل حاد.\n*   **أفضل ممارسة**: قم دائماً بقص مقاطعك مسبقاً إلى 29.5 ثانية باستخدام `ffmpeg` قبل إرسالها.\n\n### كيف تنشر فيديوهات أطول؟\nيجب استخدام **استراتيجية \"التقطيع\" (Slicing)**. إذا كان لديك مقطع مدته دقيقتان، قم بقطعه إلى أربعة أجزاء مدة كل منها 30 ثانية، وارفعها بالتتابع. سيقوم واتساب بتشغيلها تباعاً لتوفير تجربة تشغيل سلسة.\n\n---\n\n## 🎞️ المواصفات التقنية\n\nلضمان التشغيل الفوري وتجنب \"عجلة التخمين\" (Buffering):\n*   **الحاوية**: MP4 (حصرياً).\n*   **ترميز الفيديو**: **H.264 (AVC)**. لا تستخدم H.265 (HEVC).\n*   **ترميز الصوت**: **AAC**.\n*   **الدقة**: **720x1280** (720p عمودي) هي النقطة المثالية.\n*   **معدل البت (Bitrate)**: حافظ عليه أقل من **2.5 ميجابت في الثانية**؛ أي معدل أعلى سيقوم واتساب بضغطه وتدميره.\n\n---\n\n## 🔄 علامة `convert`\n\nتتضمن نقطة النهاية هذه أداة قوية: `convert: true`.\n*   **الوظيفة**: إذا أرسلت ملف MOV أو AVI أو MKV، ستحاول الواجهة تحويله إلى MP4 متوافق مع واتساب أثناء المعالجة.\n*   **تحذير**: التحويل يستهلك وقتاً من المعالج، مما سيزيد وقت استجابة الواجهة بمقدار 5-10 ثوانٍ.\n\n---\n\n## 🎬 استراتيجيات إبداعية\n\n### 1. \"سينيماغراف\" (Cinemagraph)\nبدلاً من فيديو كامل، انشر حلقة مكررة حيث يتحرك عنصر واحد فقط (مثل بخار يتصاعد من فنجان قهوة). يتميز هذا بجاذبية صورية عالية وحجم ملف صغير جداً.\n\n### 2. نمط \"ملاحظة الفيديو\" (`asNote`)\nهناك وضع سري يدعى `asNote: true`.\n*   **التأثير**: ينسق الفيديو كملاحظة فيديو دائرية فورية. يشعر هذا النمط بأنه أقل \"إنتاجية\" وأكثر \"واقعية\".\n\n### 3. الترجمة ضرورية\n**80% من المستخدمين يشاهدون حالات واتساب في وضع الصمت.**\n*   **قاعدة**: إذا كان الفيديو يعتمد على التعليق الصوتي، **يجب** عليك حرق الترجمة (Subtitles) داخل الفيديو. إذا لم تفعل، سيتخطى 80% من جمهورك الفيديو فوراً.\n            "
        }
      }
    },
    {
      "path": "/v2/status/new-message-id",
      "methods": [
        "GET"
      ],
      "title": "Get New Status ID",
      "category": "Status",
      "description": "Generate a new message ID for a status update. Useful for idempotent status updates.",
      "extraInfo": "\n# The Architect's Tool: Pre-Generating IDs\n\nThe `/v2/status/new-message-id` endpoint is a utility for advanced developers building high-reliability systems. It allows you to reserve a valid WhatsApp Message ID *before* you actually send the content.\n\n---\n\n## 🏗️ The Problem: The \"Lost Response\"\n\nIn a typical API flow:\n1.  You call `POST /v2/status/image`.\n2.  The server processes it and sends it to WhatsApp.\n3.  The server returns `200 OK` with `{ id: \"ABC\" }`.\n4.  **Failure**: Your internet cuts out *after* sending the request but *before* receiving the response.\n\n**Outcome**: The status was posted, but your database doesn't know the ID. You try to post it again -> **Duplicate Content**.\n\n---\n\n## 🛡️ The Solution: Idempotency with Proper IDs\n\nBy generating the ID first, you invert the control flow.\n\n### Step 1: Generate & Store\nCall `GET /v2/status/new-message-id`.\n*   Response: `{ id: \"3EB0...123\" }`\n*   Action: Save to DB: `{ status_id: \"3EB0...123\", state: \"pending_upload\" }`\n\n### Step 2: The Upload\nCall `POST /v2/status/image` but include the ID in the payload (if supported) or simply map it internally.\n*   *Note*: Currently, the Wawp API auto-assigns IDs on send. However, this endpoint is crucial for **correlation**.\n\n### Use Case: Tracking Viewers\nIf you want to track who viewed a specific status:\n1.  You need the ID *immediately* to set up your webhook listener.\n2.  By generating it first (conceptually), you can prepare your analytics system:\n    ```javascript\n    const nextId = await api.getNewId();\n    analytics.subscribeTo(nextId); // Ready to listen\n    await api.postStatus(image, { id: nextId }); // Send\n    ```\n\n---\n\n## 🔮 Implementation Details\n\n### Format\nThe ID returned is a standard WhatsApp Message ID (e.g., `3EB0...`).\n*   It is unique to your session.\n*   It implies \"From Me\" (key.fromMe = true).\n\n### Collision Safety\nWhatsApp IDs are time-based and random. The chance of collision is astronomically low. You can safely generate 100 IDs in parallel without conflict.\n\n---\n\n## ⚠️ Limitations\n\n*   **Ephemeral**: Generating an ID does not \"reserve\" it on WhatsApp servers. It just gives you a string that *will be valid* if used.\n*   **Scope**: This ID is for **Status Updates** only. Do not try to use it for sending text messages to chats, as the ID structure might differ slightly in future protocol versions.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Format",
          "content": "Generates a hexadecimal ID required for creating new status updates."
        },
        {
          "type": "info",
          "title": "Uniqueness",
          "content": "Ensures your status update doesn't collide with others."
        }
      ],
      "recommendations": [
        "Generate a new ID for every single status post.",
        "Do not reuse IDs; it will cause sync errors."
      ],
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "New ID generated",
          "example": {
            "id": "3EB0BCB2E3D4"
          }
        },
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "الحصول على معرف حالة جديد",
          "description": "أنشئ معرف رسالة جديداً لتحديث الحالة. مفيد لتجنب التكرار وضمان تطابق البيانات.",
          "extraInfo": "\n# أداة المعماري: توليد المعرفات مسبقاً\n\nتعد نقطة النهاية `/v2/status/new-message-id` أداة للمطورين المتقدمين الذين يبنون أنظمة عالية الموثوقية. فهي تتيح لك حجز معرف رسالة واتساب صالح *قبل* إرسال المحتوى فعلياً.\n\n---\n\n## 🏗️ المشكلة: \"الاستجابة المفقودة\"\n\nفي تدفق الواجهة التقليدي:\n1.  تقوم باستدعاء `POST /v2/status/image`.\n2.  يقوم الخادم بمعالجتها وإرسالها إلى واتساب.\n3.  ينقطع اتصال الإنترنت لديك *بعد* إرسال الطلب ولكن *قبل* تلقي الاستجابة التي تحتوي على المعرف.\n**النتيجة**: تم نشر الحالة، لكن قاعدة بياناتك لا تعرف المعرف. إذا حاولت النشر مرة أخرى، ستحصل على **محتوى مكرر**.\n\n---\n\n## 🛡️ الحل: ضمان العمليات (Idempotency)\n\nمن خلال توليد المعرف أولاً، يمكنك التحكم في سير العمل:\n1.  **التوليد والحفظ**: استدعِ `GET /v2/status/new-message-id` واحفظ المعرف في قاعدة بياناتك بحالة \"قيد الرفع\".\n2.  **الرفع**: قم برفع الحالة، وإذا فشل الاتصال، يمكنك دائماً الرجوع لقاعدة بياناتك لمعرفة ما إذا كان هذا المعرف قد استخدم بنجاح.\n\n### حالة استخدام: تتبع المشاهدين\nإذا كنت تريد تتبع من شاهد حالة معينة:\n1.  تحتاج إلى المعرف *فوراً* لإعداد مستمع الويب هوك الخاص بك.\n2.  من خلال توليده أولاً، يمكنك تجهيز نظام التحليلات الخاص بك ليبدأ الاستماع حتى قبل إتمام عملية الرفع.\n            "
        }
      }
    },
    {
      "path": "/v2/status/delete",
      "methods": [
        "POST"
      ],
      "title": "Delete status",
      "category": "24 Hour Status",
      "description": "Delete a specific status (story) by ID.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "API Access Token",
          "example": "YOUR_ACCESS_TOKEN"
        },
        "id": {
          "required": true,
          "type": "string",
          "description": "The status message ID to delete",
          "example": "status-msg-id"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "حذف الحالة",
          "description": "احذف حالة معينة (قصة) عن طريق المعرف (ID).",
          "tips": [
            {
              "title": "النطاق",
              "content": "يحذف تحديث حالة معين (قصة) بواسطة معرف."
            },
            {
              "title": "المزامنة",
              "content": "تنتشر الإزالة إلى المشاهدين في النهاية، ولكن ليس فورًا."
            }
          ],
          "recommendations": [
            "احذف المنشورات العرضية فورًا.",
            "قم بأتمتة الحذف إذا أصبح المحتوى غير ذي صلة (مثل انتهاء بيع فلاش)."
          ],
          "args": {
            "id": {
              "description": "معرف رسالة الحالة المراد حذفها"
            }
          },
          "extraInfo": "\n# زر التراجع: حذف الحالة\n\nتسمح لك نقطة النهاية `/v2/status/delete` بإزالة تحديث الحالة برمجياً *قبل* انتهاء صلاحيتها التي تستمر 24 ساعة. هذه أداة حيوية لإدارة السمعة وتصحيح الأخطاء.\n\n---\n\n## 🚨 بروتوكولات الطوارئ\n\n### الحالة 1: خطأ في التسعير\n*   **الموقف**: قام البوت بنشر كود خصم \"99%\" بدلاً من \"9%\".\n*   **الإجراء**: استدعِ `/v2/status/delete` فوراً.\n*   **التأثير**: تختفي الحالة من تبويب \"المستجدات\" لدى جميع المستخدمين.\n\n### الحالة 2: العرض المنتهي\n*   **الموقف**: نشرت \"عرض فلاش\" ينتهي في الساعة 2 ظهراً.\n*   **المشكلة**: في الساعة 4 ظهراً، لا يزال المستخدمون يرون القصة ويغضبون لأن الكود لا يعمل.\n*   **الحل**: جدول أمر الحذف في اللحظة التي ينتهي فيها العرض تماماً.\n\n---\n\n## 🏗️ السلوك التقني\n\n### هل يتم \"الحذف\" فعلياً؟\nنعم، ولكن مع بعض الملاحظات:\n1.  **جهة الخادم (Server-Side)**: يتم وضع علامة على الوسائط للحذف فوراً على خوادم واتساب. لا يمكن للأجهزة الجديدة تحميلها.\n2.  **جهة العميل (Online)**: تتلقى الأجهزة المتصلة إشارة \"سحب\" (Revoke) وتخفي الحالة فجأة.\n3.  **جهة العميل (Offline)**: إذا كان هاتف المستخدم في \"وضع الطيران\"، فسيظل يرى الحالة حتى يعيد الاتصال بالإنترنت. **لا يمكنك فرض حذف المحتوى من جهاز غير متصل.**\n\n---\n\n## ❓ الأسئلة الشائعة\n\n**س: هل يمكنني تعديل الحالة بدلاً من حذفها؟**\nج: **لا.** بروتوكول واتساب لا يدعم تعديل تحديثات الحالة. يجب حذف القديمة ونشر أخرى جديدة.\n\n**س: هل سيعرف المستخدمون أنني حذفتها؟**\nج: **لا.** على عكس رسائل الدردشة التي تترك أثراً (\"تم حذف هذه الرسالة\")، تختفي الحالات المحذوفة دون ترك أي أثر.\n            "
        }
      }
    },
    {
      "path": "/v2/channels-overview",
      "methods": [
        "GET"
      ],
      "category": "Channels Control",
      "isArticle": true,
      "title": "Channels Management",
      "description": "Learn how to create, manage, and search for WhatsApp Channels using Wawp.",
      "extraInfo": "\n# The Modern Broadcast: Mastering WhatsApp Channels\n\nWhatsApp Channels represent a paradigm shift in how businesses and influencers communicate on the platform. Unlike Groups (many-to-many) or Broadcast Lists (one-to-many but personal), Channels are a **public, one-to-many broadcast tool** designed for unlimited audiences. They are built for privacy, discoverability, and scale.\n\nThis section of the API allows you to fully automate the lifecycle of a Channel administrator or a Channel follower. Whether you are building a dashboard for media publishing or a tool for market intelligence, understanding the Channels ecosystem is critical.\n\n---\n\n## 🌍 The Ecosystem Architecture\n\nThe Channels ecosystem is divided into two distinct sides: **Publishing** and **Consumption**. The Wawp API provides endpoints to handle both.\n\n### 1. The Publisher (Admin) Role\nAs a creator, your primary goal is distribution. You perform actions such as:\n*   **Creation**: Initializing a new Channel with a name, description, and picture.\n*   **Broadcasting**: Sending text, images, videos, and polls to your subscribers.\n*   **Management**: Updating metadata to keep the channel relevant in search results.\n\n### 2. The Consumer (Follower) Role\nAs a user, your primary goal is consumption and discovery. You perform actions such as:\n*   **Discovery**: Searching the Global Directory by country, category, or keyword.\n*   **Subscription**: Following channels to receive updates in the distinct \"Updates\" tab.\n*   **Consumption**: Reading messages without revealing your phone number to the admin or other followers.\n\n---\n\n## 🚀 Strategic Implementation Patterns\n\n### Pattern A: The \"Content Aggregator\"\nIf you run a news agency or a content platform, you can use Wawp to automatically mirror your content to WhatsApp.\n*   **Workflow**:\n    1.  **Create**: Use [`/v2/channels/create`](/v2/channels/create) to establish your brand presence.\n    2.  **Sync**: Connect your CMS (WordPress, RSS) to the Wawp API.\n    3.  **Publish**: Every time a new article goes live, script a call to post a link and summary to your Channel.\n    4.  **Growth**: Use the \"Invite Link\" returned during creation to drive traffic from your website to WhatsApp.\n\n### Pattern B: The \"Market Intelligence\" Bot\nChannels are public. This means you can use Wawp to monitor *other* channels, not just your own.\n*   **Workflow**:\n    1.  **Search**: Use [`/v2/channels/search/text`](/v2/channels/search/text) to find competitors or influencers in your niche.\n    2.  **Follow**: Programmatically follow these channels using [`/v2/channels/{id}/follow`](/v2/channels/{id}/follow).\n    3.  **Listen**: Periodically poll for new messages using [`/v2/channels/{id}/messages`](/v2/channels/{id}/messages).\n    4.  **Analyze**: Feed the text updates into an LLM (Large Language Model) to generate daily summaries of industry trends.\n\n---\n\n## 🔒 Privacy & Security Model\n\nChannels operate on a different privacy model than standard WhatsApp chats:\n*   **Hidden Numbers**: Admins cannot see the full phone number of subscribers, and subscribers cannot see the admin's phone number unless they are saved contacts. This separation encourages users to follow without fear of spam calls.\n*   **History**: Channel history is stored on the server for up to 30 days. New followers can see history *before* they followed, unlike Groups where history starts upon joining (depending on settings, but Channels are designed for \"catch-up\").\n*   **Interaction Limits**: Followers cannot reply with text. They can only react with emojis. This prevents spam and keeps the channel focused on the broadcaster's voice.\n\n**Developer Note**: When you use the API to \"Follow\" a channel, the Wawp instance behaves exactly like a real user. The channel owner will see +1 follower count but will not see your instance's phone number.\n\n---\n\n## 🛠️ Key Technical Concepts\n\n### The Channel ID (JID)\nEvery Channel is identified by a unique JID ending in `@newsletter` (e.g., `1234567890@newsletter`). This is distinct from `@g.us` (Groups) or `@s.whatsapp.net` (Users).\n*   **Persistence**: Note this ID immediately upon creation or search. It is required for all subsequent operations like posting or unfollowing.\n\n### Metadata & Search\nWhatsApp maintains a global directory. To make your Channel discoverable:\n*   **Category**: You must categorize your channel (e.g., specific to your region or topic).\n*   **Verification**: \"Green Tick\" channels rank higher in search. Wawp cannot grant verification (that is a Meta policy), but it can help you display verified channels correctly in your UI.\n\n### Rate Limiting\nWhile Channels are \"unlimited,\" broadcasting too rapidly (e.g., 60 messages/minute) may trigger spam filters or temporary blocks from WhatsApp.\n*   **Recommendation**: Space out your updates. Quality over quantity. 1-5 high-value updates per day perform better than 50 micro-updates.\n\n---\n\n## 🧭 Navigating the API\n\n1.  **Start Here**: [`/v2/channels/search/text`](/v2/channels/search/text) to find interesting channels.\n2.  **Take Action**: [`/v2/channels/{id}/follow`](/v2/channels/{id}/follow) to subscribe.\n3.  **Create Your Own**: [`/v2/channels/create`](/v2/channels/create) to become a broadcaster.\n4.  **Stay Updated**: [`/v2/channels/{id}/messages`](/v2/channels/{id}/messages) to fetch the latest feed.\n\nThis documentation section covers the full spectrum of Channel mastery, giving you the tools to both Broadcast and Listen at scale.\n    ",
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "Subscriber Privacy",
          "content": "Channel owners cannot see the phone numbers of their subscribers, ensuring high-privacy broadcasting."
        }
      ],
      "recommendations": [
        "Include a 'Follow' link in your email newsletters to grow your channel audience.",
        "Use the screenshot API to monitor how your channel looks to others.",
        "Post exclusive content to your channel to give users a reason to follow."
      ],
      "responses": [],
      "translations": {
        "ar": {
          "title": "إدارة القنوات",
          "description": "تعرف على كيفية إنشاء وإدارة والبحث عن قنوات واتساب باستخدام Wawp.",
          "tips": [
            {
              "title": "تحديثات القناة",
              "content": "قد تستغرق تحديثات معلومات القناة وقتًا للانتشار."
            },
            {
              "title": "تعديل الرسالة",
              "content": "رسائل القناة لها نافذة محدودة للتعديل."
            }
          ],
          "recommendations": [
            "تحقق من أذونات إنشاء القناة.",
            "استخدم صورًا عالية الجودة لأيقونات القناة."
          ],
          "extraInfo": "\n# البث الحديث: إتقان قنوات واتساب\n\nتمثل قنوات واتساب تحولاً جذريًا في كيفية تواصل الشركات والمؤثرين على المنصة. على عكس المجموعات (متعدد لمتعدد) أو قوائم البث (واحد لمتعدد ولكن شخصي)، فإن القنوات هي **أداة بث عامة من واحد لمتعدد** مصممة لجماهير غير محدودة. تم بناؤها من أجل الخصوصية وقابلية الاكتشاف والنطاق.\n\nيسمح لك هذا القسم من واجهة برمجة التطبيقات بأتمتة دورة حياة مشرف القناة أو متابع القناة بالكامل. سواء كنت تبني لوحة تحكم للنشر الإعلامي أو أداة لاستخبارات السوق، فإن فهم منظومة القنوات أمر بالغ الأهمية.\n\n---\n\n## 🌍 بنية المنظومة التقنية\n\nتنقسم منظومة القنوات إلى جانبين متميزين: **النشر** و **الاستهلاك**. توفر واجهة برمجة تطبيقات Wawp نقاط نهاية للتعامل مع كليهما.\n\n### 1. دور الناشر (المشرف)\nبصفتك منشئًا، فإن هدفك الأساسي هو الانتشار. تقوم بإجراءات مثل:\n*   **الإنشاء**: تهيئة قناة جديدة باسم ووصف وصورة.\n*   **البث**: إرسال النصوص والصور ومقاطع الفيديو والاستطلاعات إلى المشتركين.\n*   **الإدارة**: تحديث البيانات الوصفية للحفاظ على صلة القناة في نتائج البحث.\n\n### 2. دور المستهلك (المتابع)\nبصفتك مستخدمًا، فإن هدفك الأساسي هو الاستهلاك والاكتشاف. تقوم بإجراءات مثل:\n*   **الاكتشاف**: البحث في الدليل العالمي حسب البلد أو الفئة أو الكلمة الرئيسية.\n*   **الاشتراك**: متابعة القنوات لتلقي التحديثات في علامة تبويب \"المستجدات\" المنفصلة.\n*   **الاستهلاك**: قراءة الرسائل دون الكشف عن رقم هاتفك للمشرف أو المتابعين الآخرين.\n\n---\n\n## 🔒 نموذج الخصوصية والأمان\n\nتعمل القنوات بنموذج خصوصية مختلف عن دردشات واتساب القياسية:\n*   **الأرقام المخفية**: لا يمكن للمشرفين رؤية رقم الهاتف الكامل للمشتركين، ولا يمكن للمشتركين رؤية رقم هاتف المشرف ما لم يكونوا جهات اتصال محفوظة. هذا الفصل يشجع المستخدمين على المتابعة دون خوف من مكالمات البريد العشوائي.\n*   **السجل**: يتم تخزين سجل القناة على الخادم لمدة تصل إلى 30 يومًا. يمكن للمتابعين الجدد رؤية السجل *قبل* متابعتهم.\n*   **قيود التفاعل**: لا يمكن للمتابعين الرد بالنصوص. يمكنهم فقط التفاعل باستخدام الرموز التعبيرية. هذا يمنع البريد العشوائي ويحافظ على تركيز القناة على صوت المذيع.\n\n---\n\n## 🛠️ المفاهيم التقنية الرئيسية\n\n### معرف القناة (JID)\nيتم تحديد كل قناة بواسطة JID فريد ينتهي بـ `@newsletter` (مثلاً، `1234567890@newsletter`). هذا يختلف عن `@g.us` (المجموعات) أو `@s.whatsapp.net` (المستخدمون).\n\n### البيانات الوصفية والبحث\nيحتفظ واتساب بدليل عالمي. لجعل قناتك قابلة للاكتشاف:\n*   **الفئة**: يجب عليك تصنيف قناتك (مثلاً، محددة لمنطقتك أو موضوعك).\n*   **التحقق**: القنوات ذات \"العلامة الخضراء\" تحتل مرتبة أعلى في البحث.\n\n---\n\n## 🧭 التنقل في واجهة برمجة التطبيقات\n\n1.  **ابدأ هنا**: [`/v2/channels/search/text`](/v2/channels/search/text) للعثور على قنوات مثيرة للاهتمام.\n2.  **اتخذ إجراءً**: [`/v2/channels/{id}/follow`](/v2/channels/{id}/follow) للاشتراك.\n3.  **أنشئ قناتك الخاصة**: [`/v2/channels/create`](/v2/channels/create) لتصبح مذيعًا.\n4.  **ابقَ على اطلاع**: [`/v2/channels/{id}/messages`](/v2/channels/{id}/messages) لجلب أحدث التحديثات.\n            "
        }
      }
    },
    {
      "path": "/v2/channels",
      "methods": [
        "GET"
      ],
      "title": "Get Channels List",
      "category": "Channels Control",
      "description": "Retrieve a list of WhatsApp channels known to the instance, filtered by role if specified.",
      "extraInfo": "\n# The Inventory: Listing Your Channels\n\nThe `/v2/channels` endpoint acts as your personal registry. It returns a list of all channels that your Wawp instance interacts with, whether as a Creator (Owner) or a Follower (Subscriber).\n\n---\n\n## 📋 Understanding Channel Roles\n\nThe response includes a `role` field for each channel, which dictates your permissions.\n\n### 1. OWNER\n*   **Definition**: You created this channel.\n*   **Capabilities**: \n    *   Post updates (Text, Media, Polls).\n    *   Change settings (Name, Picture, Description).\n    *   Delete the channel.\n\n### 2. ADMIN\n*   **Definition**: You were promoted to admin by the Owner (Note: Admin promotion via API is currently limited).\n*   **Capabilities**: similar to owner but usually cannot delete the channel.\n\n### 3. SUBSCRIBER (GUEST)\n*   **Definition**: You followed this channel from the directory.\n*   **Capabilities**: \n    *   Read messages.\n    *   React with emojis.\n    *   Mute/Unmute.\n    *   **Cannot** post updates.\n\n---\n\n## 🛠️ Sync Strategies\n\n### The Startup Sync\nWhen your application boots up, you should call this endpoint to populate your local state.\n1.  **Fetch**: Call `GET /v2/channels`.\n2.  **Filter**: Separate the list into \"My Channels\" (`role=OWNER`) and \"Subscriptions\" (`role=SUBSCRIBER`).\n3.  **Display**: \n    *   Show \"My Channels\" in a \"Broadcast Dashboard\".\n    *   Show \"Subscriptions\" in a \"News Feed\" view.\n\n### The \"Stale Data\" Problem\nChannel metadata (like name or picture) changes rarely.\n*   **Optimization**: Do not call this endpoint on every page load. Cache the result for 10-60 minutes.\n*   **Invalidation**: If you perform a `create` or `follow` action, manually add that new item to your local cache instead of re-fetching the entire list.\n\n---\n\n## 🔍 Advanced Filtering\n\nYou can server-side filter the results to save bandwidth.\n\n*   **`role=OWNER`**: Useful for \"Creator Studios\" where you only want to see channels you can post to.\n*   **`role=SUBSCRIBER`**: Useful for \"Reader Apps\" where you only want to see content consumption sources.\n\n---\n\n## ⚠️ Common Pitfalls\n\n*   **Missing Channels**: If you just followed a channel but it doesn't appear here immediately, give it 1-2 seconds. The sync between the WhatsApp server and the Wawp instance is asynchronous.\n*   **Duplicate Names**: Remember that multiple channels can have the name \"Test Channel\". Always use the `id` (`@newsletter`) as the unique key in your UI.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Scope",
          "content": "Returns channels you follow or own."
        },
        {
          "type": "warning",
          "title": "Pagination",
          "content": "This list can be long. Use pagination cursors if available."
        }
      ],
      "recommendations": [
        "Filter the list to show only channels where you have admin rights.",
        "Refresh this list periodically to sync with phone-initiated actions."
      ],
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "role": {
          "required": false,
          "type": "string",
          "description": "Filter by role. Available values: OWNER, ADMIN, SUBSCRIBER",
          "example": "OWNER"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "List of channels retrieved successfully",
          "example": [
            {
              "id": "1234567890@newsletter",
              "name": "Wawp Updates",
              "role": "OWNER",
              "description": "Official updates from Wawp"
            }
          ]
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Parameter Format",
          "contentType": "application/json",
          "example": {
            "code": "invalid_param",
            "message": "Invalid format for one or more parameters.",
            "details": {
              "param": "text",
              "value": "too_long",
              "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "الحصول على قائمة القنوات",
          "description": "استرجع قائمة بقنوات واتساب المعروفة للمثيل، مصفاة حسب الدور إذا تم تحديده.",
          "tips": [
            {
              "title": "النطاق",
              "content": "يعيد القنوات التي تتابعها أو تمتلكها."
            },
            {
              "title": "تقسيم الصفحات",
              "content": "يمكن أن تكون هذه القائمة طويلة. استخدم مؤشرات الصفحات إذا كانت متاحة."
            }
          ],
          "recommendations": [
            "قم بتصفية القائمة لإظهار القنوات التي لديك حقوق مسؤول فيها فقط.",
            "قم بتحديث هذه القائمة بشكل دوري للمزامنة مع الإجراءات التي بدأت من الهاتف."
          ],
          "args": {
            "role": {
              "description": "تصفية حسب الدور. القيم المتاحة: OWNER, ADMIN, SUBSCRIBER"
            }
          },
          "extraInfo": "\n# المخزن: سرد قنواتك\n\nتعمل نقطة النهاية `/v2/channels` كسجل شخصي لك. وهي تعيد قائمة بجميع القنوات التي يتفاعل معها مثيل Wawp الخاص بك، سواء كنت منشئاً (مالكاً) أو متابعاً (مشتركاً).\n\n---\n\n## 📋 فهم أدوار القناة\n\nتتضمن الاستجابة حقل `role` لكل قناة، والذي يحدد صلاحياتك.\n\n### 1. مالك (OWNER)\n*   **التعريف**: أنت من أنشأت هذه القناة.\n*   **الصلاحيات**: \n    *   نشر التحديثات (نص، ميديا، استطلاعات).\n    *   تغيير الإعدادات (الاسم، الصورة، الوصف).\n    *   حذف القناة.\n\n### 2. مشترك (SUBSCRIBER)\n*   **التعريف**: قمت بمتابعة هذه القناة من الدليل.\n*   **الصلاحيات**: \n    *   قراءة الرسائل والتفاعل معها.\n    *   كتم/إلغاء كتم التنبيهات.\n    *   **لا يمكنك** نشر تحديثات.\n\n---\n\n## 🛠️ استراتيجيات المزامنة\n\n### مزامنة بدء التشغيل\nعند بدء تشغيل تطبيقك، يجب عليك استدعاء نقطة النهاية هذه لملء حالتك المحلية.\n1.  **الجلب**: استدعِ `GET /v2/channels`.\n2.  **التصفية**: افصل القائمة إلى \"قنواتي\" (`role=OWNER`) و \"الاشتراكات\" (`role=SUBSCRIBER`).\n\n### مشكلة \"البيانات القديمة\"\nتتغير البيانات الوصفية للقناة (مثل الاسم أو الصورة) نادراً.\n*   **التحسين**: لا تستدعي نقطة النهاية هذه عند كل تحميل للصفحة. قم بتخزين النتيجة مؤقتاً لمدة 10-60 دقيقة.\n*   **الإبطال**: إذا قمت بإجراء عملية `create` أو `follow`، فقم بإضافة هذا العنصر الجديد يدوياً إلى مخزنك المؤقت بدلاً من إعادة جلب القائمة بالكامل.\n\n---\n\n## ⚠️ عثرات شائعة\n\n*   **القنوات المفقودة**: إذا قمت بمتابعة قناة للتو ولكنها لا تظهر هنا فوراً، انتظر ثانية أو ثانيتين. المزامنة بين خادم واتساب ومثيل Wawp غير متزامنة.\n*   **الأسماء المكررة**: تذكر أن قنوات متعددة يمكن أن تحمل نفس الاسم. استخدم دائماً المعرف `id` (`@newsletter`) كمفتاح فريد في واجهة المستخدم الخاصة بك.\n            "
        }
      }
    },
    {
      "path": "/v2/channels/create",
      "realPath": "/v2/channels",
      "methods": [
        "POST"
      ],
      "title": "Create Channel",
      "category": "Channels Control",
      "description": "Create a new WhatsApp channel with a name, description, and profile picture.",
      "extraInfo": "\n# The Genesis Block: Programmatic Channel Creation\n\nThe `/v2/channels/create` endpoint is your gateway to becoming a broadcaster on WhatsApp. Unlike Groups, which require adding phone numbers one by one, a Channel is a public entity that users choose to follow. This endpoint allows you to instantly provision a new broadcasting outlet for your brand, topic, or community.\n\n---\n\n## 🏗️ Anatomy of a Channel\n\nWhen you create a channel, you are defining three key public-facing attributes. Getting these right is crucial for subscriber growth.\n\n### 1. The Name (`name`)\n*   **Constraint**: Maximum ~100 characters (though WhatsApp recommends < 25 for visibility).\n*   **Strategy**: This is the searchable title. If you are a news agency, include your brand name. If you are a niche bot, include the topic (e.g., \"Daily Crypto Alerts\").\n*   **Uniqueness**: Names are *not* unique. You can have multiple channels with the same name, but they will have different JIDs.\n\n### 2. The Description (`description`)\n*   **Constraint**: Supports text and emojis.\n*   **SEO Value**: This field is indexed by WhatsApp's directory search. Include keywords here.\n    *   *Bad*: \"Updates from us.\"\n    *   *Good*: \"Daily alerts for **Bitcoin**, **Ethereum**, and **DeFi** market trends. Official channel for CryptoNews.\"\n*   **Trust**: Use this space to link to your official website or privacy policy to establish legitimacy.\n\n### 3. The Picture (`picture`)\n*   **Format**: JPG or PNG.\n*   **Dimensions**: Recommended 640x640 pixels (square).\n*   **Behavior**: If omitted, the channel will have a default generic icon. It is **highly recommended** to set this during creation to increase click-through rates from the directory.\n\n---\n\n## 🚀 Post-Creation Workflow\n\nOnce you receive a `201 Created` response, your channel is live on the network, but it has 0 followers.\n\n### Step 1: Capture the JID\nThe response will contain an `id` ending in `@newsletter` (e.g., `123456789@newsletter`).\n*   **Action**: Store this permanently in your database. You cannot send messages without it.\n\n### Step 2: Get the Invite Link\nWhile not always returned in the creation response (depending on API version), you can usually construct a deep link or fetch channel info to get the `invite_link`.\n*   **Format**: `https://whatsapp.com/channel/...`\n*   **Distribution**: Embed this link in your email footers, website banners, and SMS campaigns.\n\n### Step 3: The \"First Post\"\nA empty channel looks abandoned.\n*   **Best Practice**: Immediately after creation, use [`/v2/channels/{id}/messages`](/v2/channels/{id}/messages) to post a \"Welcome\" message explaining what subscribers can expect.\n\n---\n\n## ⚠️ Limits & Restrictions\n\n*   **Rate Limits**: You can usually create a limited number of channels per phone number per day (e.g., 1-10 depending on trust score) to prevent spam.\n*   **Admin Rights**: The Wawp instance that creates the channel is the **Sole Admin**. Currently, the API may not support adding other admins programmatically. Ensure you do not lose access to this session.\n*   **Compliance**: Channel content is moderated by Meta. Creating channels for illegal topics or hate speech can result in an instant ban of your entire Wawp instance.\n\n---\n\n## 💡 Advanced: Dynamic Channel Provisioning\n\nIf you are a SaaS platform (e.g., a Real Estate CRM), you can automate this:\n1.  Real Estate Agent signs up on your site.\n2.  Your system calls `/v2/channels/create` with name \"Home Listings: [Agent Name]\".\n3.  Your system stores the JID.\n4.  Every time the agent adds a new property to your CRM, your system automatically broadcasts the photo and price to their specific Channel.\n\nThis turns every user of your software into a micro-broadcaster.\n    ",
      "tips": [
        {
          "type": "warning",
          "title": "Visibility",
          "content": "Channels are public by default. Anyone can search and find them."
        },
        {
          "type": "info",
          "title": "Broadcast",
          "content": "Channels are one-way broadcast tools; followers cannot reply with text."
        }
      ],
      "recommendations": [
        "Use clear, descriptive titles for better discoverability.",
        "Prepare a content calendar before launching to keep followers engaged.",
        "Verify your local region supports channel creation."
      ],
      "args": {
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "name": {
          "required": true,
          "type": "string",
          "description": "The name of the channel",
          "example": "Channel Name"
        },
        "description": {
          "required": false,
          "type": "string",
          "description": "A brief description of the channel",
          "example": "Channel Description"
        },
        "picture": {
          "required": false,
          "type": "object",
          "description": "Channel profile picture details",
          "example": "{\n  \"mimetype\": \"image/jpeg\",\n  \"filename\": \"filename.jpg\",\n  \"url\": \"https://wawp.net/wp-content/uploads/2025/08/icon-256x256-1.jpg\"\n}"
        },
        "type": {
          "required": false,
          "type": "string",
          "description": "Channel type",
          "example": "string"
        }
      },
      "responses": [
        {
          "status": 201,
          "description": "Channel created successfully",
          "example": {
            "id": "1234567890@newsletter",
            "status": "success",
            "message": "Channel created successfully"
          }
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Parameter Format",
          "contentType": "application/json",
          "example": {
            "code": "invalid_param",
            "message": "Invalid format for one or more parameters.",
            "details": {
              "param": "text",
              "value": "too_long",
              "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "إنشاء قناة",
          "description": "أنشئ قناة واتساب جديدة مع اسم ووصف وصورة ملف شخصي.",
          "tips": [
            {
              "title": "الظهور",
              "content": "القنوات عامة بشكل افتراضي. يمكن لأي شخص البحث عنها والعثور عليها."
            },
            {
              "title": "البث",
              "content": "القنوات هي أدوات بث أحادية الاتجاه؛ لا يمكن للمتابعين الرد بالنصوص."
            }
          ],
          "recommendations": [
            "استخدم عناوين واضحة ووصفية لتحسين إمكانية الاكتشاف.",
            "قم بإعداد تقويم للمحتوى قبل الإطلاق للحفاظ على تفاعل المتابعين.",
            "تحقق مما إذا كانت منطقتك المحلية تدعم إنشاء القنوات."
          ],
          "args": {
            "name": {
              "description": "اسم القناة"
            },
            "description": {
              "description": "وصف موجز للقناة"
            },
            "picture": {
              "description": "تفاصيل صورة ملف تعريف القناة"
            },
            "type": {
              "description": "نوع القناة"
            }
          },
          "extraInfo": "\n# الكتلة الأولى: إنشاء القنوات برمجياً\n\nتعد نقطة النهاية `/v2/channels/create` بوابتك لتصبح مذيعاً على واتساب. على عكس المجموعات، التي تتطلب إضافة أرقام هواتف واحداً تلو الآخر، فإن القناة هي كيان عام يختار المستخدمون متابعته. تسمح لك نقطة النهاية هذه بإنشاء منصة بث جديدة لعلامتك التجارية أو تخصصك أو مجتمعك على الفور.\n\n---\n\n## 🏗️ تشريح القناة\n\nعند إنشاء قناة، فإنك تحدد ثلاث سمات رئيسية تواجه الجمهور. الحصول على هذه السمات بشكل صحيح أمر بالغ الأهمية لنمو المشتركين.\n\n### 1. الاسم (`name`)\n*   **القيد**: بحد أقصى حوالي 100 حرف (على الرغم من أن واتساب يوصي بأقل من 25 حرفاً لسهولة الظهور).\n*   **الاستراتيجية**: هذا هو العنوان القابل للبحث. إذا كنت وكالة أنباء، فتضمن اسم علامتك التجارية.\n\n### 2. الوصف (`description`)\n*   **SEO**: يتم أرشفة هذا الحقل بواسطة بحث دليل واتساب. تضمن الكلمات الرئيسية هنا.\n    *   *مثال*: \"تنبيهات يومية لأسواق **البيتكوين** و **العملات الرقمية**. القناة الرسمية لـ CryptoNews.\"\n\n### 3. الصورة (`picture`)\n*   **الأبعاد**: يوصى بـ 640x640 بكسل (مربع).\n*   **السلوك**: يوصى بشدة بضبط هذه الصورة أثناء الإنشاء لزيادة معدلات النقر من الدليل.\n\n---\n\n## 🚀 سير العمل بعد الإنشاء\n\nبمجرد تلقي استجابة `201 Created`، ستصبح قناتك مباشرة على الشبكة، ولكن بـ 0 متابعين.\n\n### الخطوة 1: حفظ الـ JID\nستحتوي الاستجابة على معرف `id` ينتهي بـ `@newsletter`.\n*   **الإجراء**: قم بتخزين هذا المعرف بشكل دائم في قاعدة بياناتك. لا يمكنك إرسال رسائل بدونه.\n\n### الخطوة 2: رابط الدعوة\nيمكنك عادةً الحصول على رابط الدعوة (`invite_link`) بجلب معلومات القناة.\n*   **التوزيع**: قم بتضمين هذا الرابط في توقيع بريدك الإلكتروني، ولافتات موقعك، وحملات SMS الخاصة بك.\n\n---\n\n## ⚠️ القيود والضوابط\n\n*   **حدود المعدل**: يمكنك عادةً إنشاء عدد محدود من القنوات لكل رقم هاتف يومياً.\n*   **الامتثال**: يتم الإشراف على محتوى القناة من قبل Meta. قد يؤدي إنشاء قنوات لمواضيع غير قانونية إلى حظر فوري لمثيل Wawp الخاص بك بالكامل.\n            "
        }
      }
    },
    {
      "path": "/v2/channels/{id}",
      "methods": [
        "GET"
      ],
      "title": "Get Channel Info",
      "category": "Channels Control",
      "description": "Get detailed information about a specific channel.",
      "extraInfo": "\n# Deep Dive: Channel Metadata\n\nThe `/v2/channels/{id}` endpoint allows you to retrieve the full profile of any public channel, provided you have its ID (JID). This is useful for refreshing metadata like subscriber counts or profile pictures.\n\n---\n\n## 🏗️ The Data Payload\n\nBeyond the basic name, this endpoint returns critical fields for integration:\n\n### 1. `invite_link`\n*   **Usage**: The `https://whatsapp.com/channel/...` URL.\n*   **Strategy**: If you are building a directory, display this link to let users open the channel directly in their native WhatsApp app.\n\n### 2. `subscribers` (Count)\n*   **Accuracy**: This is an approximate count (e.g., 1.2M), not an exact integer down to the last digit for large channels.\n*   **Analytics**: Track this over time to measure growth or campaign effectiveness.\n\n### 3. `verified`\n*   **Green Tick**: Indicates if the channel belongs to an authentic, notable brand.\n*   **UI Tip**: Always display a verification badge next to the name if this is `true`. It builds trust with your users.\n\n---\n\n## 🔄 Refresh Strategy\n\n### When to call this?\nChannel metadata is static for long periods.\n*   **Do**: Call this when a user clicks on a channel to view its details.\n*   **Don't**: Call this in a loop for every channel in your list. Use [`/v2/channels`](/v2/channels) for bulk retrieval.\n\n### Handling 404s\nIf this endpoint returns a `404 Session not found` or similar error regarding the channel ID:\n*   **Meaning**: The channel may have been deleted by the owner or banned by WhatsApp.\n*   **Action**: Automatically remove this channel from your local database or mark it as \"Inactive\".\n\n---\n\n## 🔒 Privacy Note\nFetching channel info is a public action. The channel owner does not know you requested this data. It is similar to loading a public web page.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Verification",
          "content": "Returns verification status (Green checkmark)."
        },
        {
          "type": "info",
          "title": "Stats",
          "content": "Includes subscriber count and channel creation date."
        }
      ],
      "recommendations": [
        "Cache channel metadata to reduce API usage.",
        "Monitor subscriber growth trends over time."
      ],
      "args": {
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the channel",
          "example": "1234567890@newsletter"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Channel info retrieved successfully",
          "example": {
            "id": "1234567890@newsletter",
            "name": "Channel Name",
            "description": "Channel Description",
            "subscribers": 1500
          }
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "الحصول على معلومات القناة",
          "description": "احصل على معلومات مفصلة حول قناة معينة.",
          "extraInfo": "\n# تعمق: البيانات الوصفية للقناة\n\nتسمح لك نقطة النهاية `/v2/channels/{id}` باستعادة الملف الشخصي الكامل لأي قناة عامة. هذا مفيد لتحديث البيانات الوصفية مثل عدد المشتركين أو صور الملف الشخصي.\n\n---\n\n## 🏗️ حمولة البيانات\n\nبالإضافة إلى الاسم الأساسي، تعيد نقطة النهاية هذه حقولاً هامة:\n\n### 1. رابط الدعوة (`invite_link`)\n*   **الاستخدام**: رابط `https://whatsapp.com/channel/...`.\n*   **الاستراتيجية**: إذا كنت تبني دليلاً، فاعرض هذا الرابط للسماح للمستخدمين بفتح القناة مباشرة في تطبيق واتساب الرسمي.\n\n### 2. المشتركون (`subscribers`)\n*   **الدقة**: هذا عدد تقريبي للمشتركين للقنوات الكبيرة (مثلاً: 1.2M).\n\n### 3. التوثيق (`verified`)\n*   **العلامة الخضراء**: تشير إلى ما إذا كانت القناة تنتمي إلى علامة تجارية أصلية ومعروفة.\n*   **نصيحة**: اعرض دائماً شارة التوثيق بجانب الاسم إذا كانت هذه القيمة `true`.\n\n---\n\n## 🔒 ملاحظة الخصوصية\nجلب معلومات القناة هو إجراء عام. لا يعرف مالك القناة أنك طلبت هذه البيانات.\n            "
        }
      }
    },
    {
      "path": "/v2/channels/{invite}/messages/preview",
      "methods": [
        "GET"
      ],
      "title": "Preview Channel Messages",
      "category": "Channels Control",
      "description": "Preview messages from a public channel using an invite code or link. (Wawp PLUS Feature)",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "invite": {
          "required": true,
          "type": "string",
          "description": "Channel invite code or full link",
          "example": "https://whatsapp.com/channel/..."
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Messages previewed",
          "example": [
            {
              "id": "123",
              "body": "Welcome to our channel!",
              "timestamp": 1722170400
            }
          ]
        },
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "معاينة رسائل القناة",
          "description": "قم بمعاينة الرسائل من قناة عامة باستخدام كود دعوة أو رابط. (ميزة Wawp PLUS)",
          "tips": [
            {
              "title": "تحديثات القناة",
              "content": "قد تستغرق تحديثات معلومات القناة وقتًا للانتشار."
            },
            {
              "title": "تعديل الرسالة",
              "content": "رسائل القناة لها نافذة محدودة للتعديل."
            }
          ],
          "recommendations": [
            "تحقق من أذونات إنشاء القناة.",
            "استخدم صورًا عالية الجودة لأيقونات القناة."
          ],
          "args": {
            "invite": {
              "description": "كود دعوة القناة أو الرابط الكامل"
            }
          },
          "extraInfo": "\n# نظرة خاطفة: معاينة محتوى القناة\n\nتعد نقطة النهاية `/v2/channels/{invite}/messages/preview` أداة اكتشاف قوية تسمح لتطبيقك بجلب السجل الأخير للقناة **دون الاشتراك فيها**.\n\n---\n\n## 🕵️ مقارنة: المعاينة مقابل المتابعة\n\n| الميزة | واجهة برمجة تطبيقات المتابعة | واجهة برمجة تطبيقات المعاينة |\n| :--- | :--- | :--- |\n| **الالتزام** | عالي (يتم إنشاء إدخال في قاعدة البيانات) | لا يوجد (جلب بدون حالة) |\n| **الوقت الفعلي** | نعم (ويب هوك للأبد) | لا (لقطة للوقت الحالي) |\n| **الخصوصية** | يرى المشرف زيادة في عدد المتابعين | لا يرى المشرف شيئاً |\n\n---\n\n## 🎯 حالات الاستخدام الاستراتيجي\n\n### 1. واجهة \"جرب قبل الشراء\"\nإذا كنت تبني دليلاً للقنوات لمستخدميك:\n*   **الحل**: عندما يحوم المستخدم فوق بطاقة قناة في واجهتك، استدعِ نقطة النهاية هذه لعرض آخر 3 رسائل. هذا يزيد من معدلات التحويل بشكل كبير.\n\n### 2. المراقبة الخفيفة\nإذا كنت بحاجة إلى التحقق مما إذا كان المنافس قد نشر اليوم، ولكنك لا تريد تلويث قائمة \"المتابعة\" بحسابك الرئيسي بمئات عمليات التحقق المؤقتة.\n            "
        }
      }
    },
    {
      "path": "/v2/channels/{id}/follow",
      "methods": [
        "POST"
      ],
      "title": "Follow Channel",
      "category": "Channels Control",
      "description": "Start following a WhatsApp channel to receive its updates.",
      "extraInfo": "\n# The Subscription Model: Following Channels\n\nThe `/v2/channels/{id}/follow` endpoint establishes a subscription relationship between your Wawp instance and a public Channel. This is the programmatic equivalent of pressing the \"Follow\" button in the WhatsApp app.\n\n---\n\n## 🔗 How Subscriptions Work\n\n### 1. Privacy First\nThe \"Follow\" action is designed with privacy at its core.\n*   **Anonymity**: The Channel Admin (creator) **cannot see your phone number**. They only see an increment in their follower count.\n*   **Safety**: You cannot be messaged directly by the admin or other followers. The communication is strictly one-way (Admin -> You).\n\n### 2. The Data Flow\nOnce you successfully follow a channel:\n*   **Updates**: New messages posted by the admin will arrive in your webhook stream (usually under the `message` event with `from: \"123...@newsletter\"`).\n*   **History**: You immediately gain access to the channel's recent history, which you can fetch using [`/v2/channels/{id}/messages`](/v2/channels/{id}/messages).\n\n### 3. Mute Status\nBy default, following a channel *may* mute it depending on your account settings.\n*   **Recommendation**: If you are building a real-time monitor, follow up this call with [`/v2/channels/{id}/unmute`](/v2/channels/{id}/unmute) to ensure you receive push notifications for every update.\n\n---\n\n## 🤖 Automating Market Intelligence\n\nThis endpoint is the cornerstone of \"Listening\" strategies.\n\n### Scenario: The Industry Dashboard\nYou want to track 50 competing news outlets.\n1.  **Ingest**: Load a list of Channel JIDs into your database.\n2.  **Loop**: Iterate through them and call `/follow`.\n3.  **Listen**: Set up a webhook listener for `message` events where `remoteJid` ends in `@newsletter`.\n4.  **Process**: When a message comes in, analyze the text/media and display it on your internal dashboard.\n\n### Scenario: The Fan Engagement Bot\nYou run a fan club for a sports team.\n1.  **Proxy Follow**: Your bot follows the official team channel.\n2.  **Relay**: When the team posts a \"Goal!\" update, your bot instantly forwards that text to a private Group Chat of your paying members.\n\n---\n\n## ⚠️ Limits & Etiquette\n\n*   **Follow Limit**: A single WhatsApp account can follow up to ~2,000 channels (subject to change by Meta).\n*   **Rate Limiting**: Do not follow 100 channels in 1 second. WhatsApp may flag this as \"automated behavior\" (spam). Use a randomized delay of 5-15 seconds between follows.\n*   **Unfollowing**: If you no longer need updates, always use [`/v2/channels/{id}/unfollow`](/v2/channels/{id}/unfollow) to clean up your state and respect the network resources.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Privacy",
          "content": "Channel admins cannot see the phone numbers of followers."
        },
        {
          "type": "positive",
          "title": "Updates",
          "content": "Following ensures updates appear in the Updates tab."
        }
      ],
      "recommendations": [
        "Encourage users to turn on notifications (bell icon) after following.",
        "Do not force-follow users; trust is essential for retention."
      ],
      "args": {
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the channel",
          "example": "1234567890@newsletter"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Followed channel successfully",
          "example": {
            "status": "success",
            "message": "Now following the channel"
          }
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "متابعة القناة",
          "description": "ابدأ في متابعة قناة واتساب لتلقي تحديثاتها.",
          "extraInfo": "\n# نموذج الاشتراك: متابعة القنوات\n\nتنشئ نقطة النهاية `/v2/channels/{id}/follow` علاقة اشتراك بين مثيل Wawp الخاص بك وقناة عامة. هذا هو المعادل البرمجي للضغط على زر \"متابعة\" في تطبيق واتساب.\n\n---\n\n## 🔗 كيف تعمل الاشتراكات\n\n### 1. الخصوصية أولاً\nتم تصميم إجراء \"المتابعة\" مع مراعاة الخصوصية في جوهرها.\n*   **إخفاء الهوية**: لا يمكن لمدير القناة رؤية رقم هاتفك. يرون فقط زيادة في عدد متابعيهم.\n*   **الأمان**: لا يمكن للمسؤول أو المتابعين الآخرين مراسلتك مباشرة. التواصل هو بث في اتجاه واحد (مدير -> أنت).\n\n### 2. تدفق البيانات\nبمجرد متابعة القناة بنجاح:\n*   **التحديثات**: ستصل الرسائل الجديدة التي ينشرها المسؤول في تيار الويب هوك الخاص بك.\n*   **السجل**: ستحصل فوراً على حق الوصول إلى السجل الأخير للقناة.\n\n---\n\n## ⚠️ القيود والآداب\n\n*   **حد المتابعة**: يمكن لحساب واتساب واحد متابعة ما يصل إلى حوالي 2,000 قناة.\n*   **تحديد المعدل**: لا تتابع 100 قناة في ثانية واحدة. قد يضع واتساب علامة \"سلوك مؤتمت\" على ذلك. استخدم تأخيراً عشوائياً بين عمليات المتابعة.\n            "
        }
      }
    },
    {
      "path": "/v2/channels/{id}/unfollow",
      "methods": [
        "POST"
      ],
      "title": "Unfollow Channel",
      "category": "Channels Control",
      "description": "Stop following a WhatsApp channel.",
      "extraInfo": "\n# Breaking Up: Unfollowing Channels\n\nThe `/v2/channels/{id}/unfollow` endpoint terminates your subscription to a channel. This is the \"Cleanup\" operation of the Channels lifecycle.\n\n---\n\n## 🛑 Why Unfollow?\n\n### 1. Reducing Noise\nEvery channel you follow sends messages to your webhook. If you follow 1,000 active news channels, your server might receive 50+ messages per second.\n*   **Best Practice**: Periodically audit your subscriptions using [`/v2/channels`](/v2/channels) and unfollow inactive or low-relevance channels to save bandwidth.\n\n### 2. Privacy & Opt-Out\nIf you are building a \"User Proxy\" service (where your users ask your bot to follow channels for them), you **must** provide an Unsubscribe mechanism. When a user says \"Stop,\" you must call this endpoint to respect their choice and the channel owner's analytics.\n\n---\n\n## ⚙️ Technical Behavior\n\n*   **Webhook Cessation**: The moment this call returns `200 OK`,\n  tips: [\n        {\n            type: 'info',\n            title: 'Cleanup',\n            content: 'Removes the channel from your updates list.'\n        },\n        {\n            type: 'warning',\n            title: 'Analytics',\n            content: 'You will no longer receive view metrics for this channel.'\n        }\n    ],\n  recommendations: [\n        \"Ask for feedback upon unfollowing to improve your content recommendation engine.\",\n        \"Confirm the action if it's accidental.\"\n    ]\n  \n   your instance will stop receiving `message` events from this JID.\n*   **History Retention**: You will still retain access to the messages you *already* received and stored in your own database, but you may lose access to fetch *historical* messages from the WhatsApp server for this channel.\n*   **Idempotency**: If you call this on a channel you are not following, it will likely return a success or a harmless error. It is safe to retry.\n\n---\n\n## ⚠️ The \"Zombie\" State\nIn rare cases, if you unfollow a channel but still have it cached locally in your app as \"Active,\" you might try to send reactions/messages to it. These will fail with `403 Forbidden`.\n*   **Action**: Always update your local \"Inventory\" immediately after calling this endpoint.\n    ",
      "args": {
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the channel",
          "example": "1234567890@newsletter"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Unfollowed channel successfully",
          "example": {
            "status": "success",
            "message": "No longer following the channel"
          }
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "إلغاء متابعة القناة",
          "description": "توقف عن متابعة قناة واتساب.",
          "extraInfo": "\n# إنهاء الاشتراك: إلغاء متابعة القنوات\n\nتنهي نقطة النهاية `/v2/channels/{id}/unfollow` اشتراكك في القناة.\n\n---\n\n## 🛑 لماذا تلغي المتابعة؟\n\n### 1. تقليل الضوضاء\nترسل كل قناة تتابعها رسائل إلى الويب هوك الخاص بك. إذا كنت تتابع 1,000 قناة إخبارية نشطة، فقد يتلقى خادمك عدداً كبيراً من الرسائل في الثانية.\n*   **أفضل ممارسة**: قم بمراجعة اشتراكاتك بانتظام وألغِ متابعة القنوات غير النشطة لتوفير الباندويث.\n\n---\n\n## ⚙️ السلوك التقني\n\n*   **توقف الويب هوك**: في اللحظة التي تعيد فيها هذه الدعوة `200 OK`، سيتوقف مثيلك عن تلقي أحداث الرسائل من هذا المعرف (JID).\n*   **الاحتفاظ بالسجل**: ستظل تحتفظ بالوصول إلى الرسائل التي استلمتها وخزنتها بالفعل في قاعدة بياناتك الخاصة.\n            "
        }
      }
    },
    {
      "path": "/v2/channels/{id}/mute",
      "methods": [
        "POST"
      ],
      "title": "Mute Channel",
      "category": "Channels Control",
      "description": "Mute notifications for a specific channel.",
      "extraInfo": "\n# Silence is Golden: Muting Channels\n\nThe `/v2/channels/{id}/mute` endpoint allows you to programmatically silence notifications for a specific channel. This corresponds to the \"Mute\" action in the mobile app.\n\n---\n\n## 🔇 What Does \"Mute\" Actually Do?\n\nIt is important to understand the distinction between \"Muting\" and \"Unfollowing\".\n\n### 1. Webhook delivery \n**Muting does NOT stop webhooks.**\n*   Even if a channel is muted, your Wawp instance will still receive every new message via the `message` webhook event.\n*   **Why?** The API assumes that if you are following a channel programmatically, you want the data for processing, regardless of whether you want the phone to ring.\n\n### 2. Device Behavior\n*   **Notifications**: The connected physical phone (if any) will **stop vibrating/ringing** for new updates from this channel.\n*   **Badge Count**: New messages will not increment the unread badge count on the main \"Updates\" tab icon, reducing visual clutter.\n*   **Sorting**: Muted channels are often pushed to the bottom of the list in the mobile UI.\n\n---\n\n## 🎯 Use Cases\n\n### The \"Silent Collector\" Bot\nYou are building a market research tool that follows 500 news channels.\n*   **Problem**: If you don't mute them, the phone connected to the Wawp instance will crash or drain its battery due to thousands of push notifications per hour.\n*   **Solution**: Immediately after calling `/follow`,\n  tips: [\n        {\n            type: 'info',\n            title: 'User Experience',\n            content: 'Muting stops push notifications but keeps the channel in the list.'\n        },\n        {\n            type: 'info',\n            title: 'Default',\n            content: 'New follows are often muted by default unless the user opts in.'\n        }\n    ],\n  recommendations: [\n        \"Respect user preference; do not auto-unmute.\",\n        \"Suggest muting for high-volume channels to prevent notification fatigue.\"\n    ]\n  \n   call `/mute`. This keeps the phone cool while your server happily ingests the data stream.\n    ",
      "args": {
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the channel",
          "example": "1234567890@newsletter"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Channel muted successfully",
          "example": {
            "status": "success",
            "message": "Channel muted"
          }
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "كتم القناة",
          "description": "كتم التنبيهات لقناة معينة.",
          "extraInfo": "\n# الصمت من ذهب: كتم القنوات\n\nتسمح لك نقطة النهاية `/v2/channels/{id}/mute` بإسكات التنبيهات برمجياً لقناة معينة. هذا يعادل إجراء \"كتم\" في تطبيق الهاتف.\n\n---\n\n## 🔇 ماذا يفعل \"الكتم\" فعلياً؟\n\nمن المهم فهم الفرق بين \"الكتم\" و \"إلغاء المتابعة\".\n\n### 1. تسليم الويب هوك \n**الكتم لا يوقف الويب هوك.**\n*   حتى إذا كانت القناة مكتومة، سيستمر مثيل Wawp في تلقي كل رسالة جديدة عبر أحداث الويب هوك.\n\n### 2. سلوك الجهاز\n*   **التنبيهات**: سيتوقف الهاتف الفعلي المتصل عن الاهتزاز أو الرنين عند وصول تحديثات جديدة من هذه القناة.\n*   **عداد الشارات**: لن تزيد الرسائل الجديدة من عداد الرسائل غير المقروءة على أيقونة تبويب \"المستجدات\"، مما يقلل من الفوضى البصرية.\n            "
        }
      }
    },
    {
      "path": "/v2/channels/{id}/unmute",
      "methods": [
        "POST"
      ],
      "title": "Unmute Channel",
      "category": "Channels Control",
      "description": "Unmute notifications for a specific channel.",
      "extraInfo": "\n# Loud and Clear: Unmuting Channels\n\nThe `/v2/channels/{id}/unmute` endpoint restores the notification privileges for a channel. This corresponds to the \"Unmute\" action in the mobile app.\n\n---\n\n## 🔊 Restoring Priority\n\nWhen you unmute a channel, you are elevating its status in the user's perception.\n\n### Behavior Changes:\n*   **Push Notifications**: The connected phone will now vibrate/ring for every new post.\n*   **Badge Count**: New messages will increment the unread counter.\n*   **Visibility**: The channel will likely move to the top of the \"Updates\" list when new content arrives.\n\n---\n\n## 💡 Strategic Usage\n\n### 1. The \"VIP\" Subscription\nIf your application allows users to follow many topics, you might offer a \"VIP Alert\" feature.\n*   **Workflow**:\n    1.  User follows 50 channels (all muted by default or by script).\n    2.  User marks \"Breaking News\" as a Priority in your UI.\n    3.  Your backend calls `/unmute` specifically for that channel.\n    4.  Result: The user gets buzzes *only* for what matters most, while still having access to the broad feed of other data.\n    ",
      "tips": [
        {
          "type": "positive",
          "title": "Engagement",
          "content": "Enables push notifications for new updates."
        },
        {
          "type": "info",
          "title": "Volume",
          "content": "Ensure you want notifications for every broadcast."
        }
      ],
      "recommendations": [
        "Unmute mainly for time-sensitive channels like News or Alerts.",
        "Monitor notification volume to ensure it's manageable."
      ],
      "args": {
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the channel",
          "example": "1234567890@newsletter"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Channel unmuted successfully",
          "example": {
            "status": "success",
            "message": "Channel unmuted"
          }
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "إلغاء كتم القناة",
          "description": "إلغاء كتم التنبيهات لقناة معينة.",
          "extraInfo": "\n# بصوت عالٍ وواضح: إلغاء كتم القنوات\n\nتستعيد نقطة النهاية `/v2/channels/{id}/unmute` امتيازات التنبيه للقناة. هذا يعادل إجراء \"إلغاء الكتم\" في تطبيق الهاتف.\n\n---\n\n## 🔊 استعادة الأولوية\n\nعندما تقوم بإلغاء كتم قناة، فإنك ترفع من شأنها في تصور المستخدم.\n\n### تغييرات السلوك:\n*   **تنبيهات الدفع**: سيهتز/يرن الهاتف المتصل الآن عند وصول كل منشور جديد.\n*   **عداد الشارات**: ستزيد الرسائل الجديدة من عداد الرسائل غير المقروءة.\n*   **الرؤية**: من المحتمل أن تنتقل القناة إلى أعلى قائمة \"المستجدات\" عند وصول محتوى جديد.\n            "
        }
      }
    },
    {
      "path": "/v2/channels/search/view",
      "methods": [
        "GET"
      ],
      "title": "Search Channels by View",
      "category": "Channels Control",
      "description": "Search for channels based on views like RECOMMENDED.",
      "extraInfo": "\n# Discovering Trends: Search by View\n\nThe `/v2/channels/search/view` endpoint allows you to tap into WhatsApp's curated lists. Instead of searching for a specific keyword, you are asking: \"What is popular right now?\"\n\n---\n\n## 🔭 Available Views\n\nThe `view` parameter controls the ranking algorithm:\n\n### 1. **RECOMMENDED**\n*   **Algorithm**: Based on the phone number's region and general popularity.\n*   **Use Case**: The default \"Discovery\" feed for a new user.\n\n### 2. **POPULAR**\n*   **Algorithm**: Strictly ranked by subscriber count (highest to lowest).\n*   **Use Case**: Finding the \"Giants\" of the platform.\n\n### 3. **NEW**\n*   **Algorithm**: Recently created channels that are gaining traction.\n*   **Use Case**: Finding emerging creators.\n\n---\n\n## 🌍 Geo-Targeting\n\nYou can combine a View with a Country Code.\n*   **Example**: `view=POPULAR` + `countries=EG` (Egypt)\n*   **Result**: Returns the most followed channels specifically within Egypt, rather than global celebrities.\n\n---\n\n## 💡 Implementation Tip\nIf you are building a \"Channel Browser\" in your app:\n1.  **Tab 1 (Trending)**: Call `view=RECOMMENDED`.\n2.  **Tab 2 (Top Charts)**: Call `view=POPULAR`.\n3.  **Tab 3 (Local)**: Call `view=POPULAR` + `country={User's Country}`.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Visuals",
          "content": "Optimized for rendering search result cards."
        },
        {
          "type": "info",
          "title": "Badges",
          "content": "Includes verification badge status in the response."
        }
      ],
      "recommendations": [
        "Always display the Verified badge if present to build trust.",
        "Show the follower count to indicate popularity."
      ],
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "view": {
          "required": true,
          "type": "string",
          "description": "The view to search by (e.g. RECOMMENDED, POPULAR, NEW)",
          "example": "RECOMMENDED"
        },
        "countries": {
          "required": true,
          "type": "array[string]",
          "description": "Filter by countries (comma separated). e.g. EG,US,SA",
          "example": "US"
        },
        "categories": {
          "required": true,
          "type": "array[string]",
          "description": "Filter by categories. e.g. ENTERTAINMENT,SPORTS",
          "example": "ENTERTAINMENT"
        },
        "limit": {
          "required": true,
          "type": "number",
          "description": "Maximum number of results",
          "example": "10"
        },
        "startCursor": {
          "required": true,
          "type": "string",
          "description": "Cursor for pagination. Leave as empty string for the first page.",
          "example": ""
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Channels retrieved successfully",
          "example": {
            "channels": [],
            "nextCursor": "cursor_456"
          }
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "البحث عن القنوات حسب العرض",
          "description": "ابحث عن القنوات بناءً على طرق عرض مثل RECOMMENDED.",
          "tips": [
            {
              "title": "المرئيات",
              "content": "محسن لعرض بطاقات نتائج البحث."
            },
            {
              "title": "الشارات",
              "content": "يتضمن حالة شارة التحقق في الاستجابة."
            }
          ],
          "recommendations": [
            "اعرض دائمًا الشارة الموثقة إذا كانت موجودة لبناء الثقة.",
            "اعرض عدد المتابعين للإشارة إلى الشعبية."
          ],
          "args": {
            "view": {
              "description": "نوع العرض للبحث من خلاله (مثل RECOMMENDED, POPULAR, NEW)"
            },
            "countries": {
              "description": "التصفية حسب الدول (مفصولة بفاصلة). مثل EG, US, SA"
            },
            "categories": {
              "description": "التصفية حسب الفئات. مثل ENTERTAINMENT, SPORTS"
            },
            "limit": {
              "description": "أقصى عدد من النتائج"
            },
            "startCursor": {
              "description": "المؤشر للترقيم. اتركه كسلسلة فارغة للصفحة الأولى."
            }
          },
          "extraInfo": "\n# اكتشاف الاتجاهات: البحث حسب العرض\n\nتسمح لك نقطة النهاية `/v2/channels/search/view` بالاستفادة من قوائم واتساب المنسقة. بدلاً من البحث عن كلمة رئيسية محددة، أنت تسأل: \"ما هو الشائع الآن؟\"\n\n---\n\n## 🔭 طرق العرض المتاحة\n\nتتحكم معلمة `view` في خوارزمية الترتيب:\n\n### 1. **RECOMMENDED** (موصى به)\n*   تعتمد على منطقة رقم الهاتف والشعبية العامة.\n\n### 2. **POPULAR** (شائع)\n*   مرتبة حسب عدد المشتركين (من الأعلى إلى الأقل).\n\n### 3. **NEW** (جديد)\n*   القنوات التي تم إنشاؤها مؤخراً والتي تكتسب زخماً.\n\n---\n\n## 🌍 الاستهداف الجغرافي\n\nيمكنك دمج \"العرض\" مع كود الدولة.\n*   **مثال**: `view=POPULAR` + `countries=EG` (مصر)\n*   **النتيجة**: تعيد القنوات الأكثر متابعة في مصر تحديداً.\n            "
        }
      }
    },
    {
      "path": "/v2/channels/search/text",
      "methods": [
        "GET"
      ],
      "title": "Search Channels by Text",
      "category": "Channels Control",
      "description": "Search for channels using a text query.",
      "extraInfo": "\n# The Global Directory: Searching WhatsApp Channels\n\nThe `/v2/channels/search/text` endpoint provides programmatic access to WhatsApp's global directory of public channels. This is the same search engine used by the WhatsApp mobile app in the \"Updates\" tab.\n\n---\n\n## 🔍 How Search Works\n\nThe search engine performs a fuzzy match against the **Channel Name** and **Description**. It uses an internal relevance score to rank results, prioritizing Verified (Green Tick) channels and those with high follower counts in the requested region.\n\n### The \"Cursor\" Pagination Model\nUnlike SQL databases that use `OFFSET/LIMIT`,\n  tips: [\n        {\n            type: 'info',\n            title: 'Keywords',\n            content: 'Searches channel titles and descriptions.'\n        },\n        {\n            type: 'positive',\n            title: 'Filters',\n            content: 'Combine with country or category filters for better results.'\n        }\n    ],\n  recommendations: [\n        \"Debounce search inputs to avoid hitting rate limits.\",\n        \"Highlight matching keywords in the search results UI.\",\n        \"Cache common search terms locally.\"\n    ]\n  \n   WhatsApp Search uses an opaque cursor string for pagination to handle millions of records efficiently.\n\n**The Workflow:**\n1.  **First Request**: Send `startCursor=\"\"` (empty string).\n2.  **Response**: You receive a list of channels and a `nextCursor` string (e.g., `\"cursor_Au9s...\"`).\n3.  **Next Page**: Send the *exact* `nextCursor` string as the `startCursor` parameter in your next request.\n4.  **End of Results**: When `nextCursor` is `null` or empty, you have reached the end of the query results.\n\n---\n\n## 🎯 Filtering Strategies\n\nRefine your search to cut through the noise.\n\n### 1. By Category (`categories`)\nYou can filter results to specific topics. This is useful for building niche discovery tools.\n*   **Available Values**:\n    *   `ENTERTAINMENT`: Celebrity and media channels.\n    *   `SPORTS`: Teams, leagues, and athletes.\n    *   `LIFESTYLE`: Fashion, cooking, and hobbies.\n    *   `BUSINESS`: Companies and brands.\n    *   `NEWS`: Global and local news outlets.\n    *   `ORGANIZATIONS`: Non-profits and government bodies.\n\n### 2. By Text Query (`text`)\n*   **Broad Match**: Searching \"Foo\" will return \"Foo Fighters\", \"Foodies\", and \"Football\".\n*   **No Wildcards**: You do not need `*` characters; the fuzzy matching is automatic.\n\n---\n\n## 💡 Use Case: The \"Trend Watcher\" Bot\n\nImagine you want to monitor the cryptocurrency market sentiment on WhatsApp.\n\n1.  **Script Loop**: Run a cron job every 24 hours.\n2.  **Search**: Query for terms like \"Bitcoin\", \"Crypto\", \"Trading\".\n3.  **Filter**: Iterate through the results and check the `subscribers_count`.\n4.  **Action**: If a new channel appears with >10,000 followers, automatically trigger the [`Follow API`](/v2/channels/{id}/follow) and alert your team via Slack.\n\nThis allows you to detect emerging influencers *before* they become mainstream.\n\n---\n\n## ⚠️ Important Notes\n\n*   **Region Locking**: The results are global but may be biased towards the region of the phone number connected to the instance.\n*   **Rate Limits**: Searching is expensive. Do not use this endpoint for high-frequency autocomplete (typing) features. Debounce your requests by at least 1-2 seconds.\n    ",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "text": {
          "required": true,
          "type": "string",
          "description": "The search query text",
          "example": "Tesla"
        },
        "categories": {
          "required": true,
          "type": "array[string]",
          "description": "Filter by categories. e.g. ENTERTAINMENT,SPORTS",
          "example": "ENTERTAINMENT"
        },
        "limit": {
          "required": true,
          "type": "number",
          "description": "Maximum number of results",
          "example": "10"
        },
        "startCursor": {
          "required": true,
          "type": "string",
          "description": "Cursor for pagination. Leave as empty string for the first page.",
          "example": ""
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Channels retrieved successfully",
          "example": {
            "channels": [],
            "nextCursor": "cursor_456"
          }
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "البحث عن القنوات بالنص",
          "description": "ابحث عن القنوات باستخدام استعلام نصي.",
          "tips": [
            {
              "title": "الكلمات المفتاحية",
              "content": "يبحث في عناوين القنوات والأوصاف."
            },
            {
              "title": "الفلاتر",
              "content": "ادمج مع مرشحات البلد أو الفئة للحصول على نتائج أفضل."
            }
          ],
          "recommendations": [
            "قم بتأخير مدخلات البحث (Debounce) لتجنب تجاوز حدود المعدل.",
            "قم بتمييز الكلمات الرئيسية المتطابقة في واجهة نتائج البحث.",
            "قم بتخزين مصطلحات البحث الشائعة مؤقتًا محليًا."
          ],
          "args": {
            "text": {
              "description": "نص استعلام البحث"
            },
            "categories": {
              "description": "التصفية حسب الفئات. مثل ENTERTAINMENT, SPORTS"
            },
            "limit": {
              "description": "أقصى عدد من النتائج"
            },
            "startCursor": {
              "description": "المؤشر للترقيم. اتركه كسلسلة فارغة للصفحة الأولى."
            }
          },
          "extraInfo": "\n# الدليل العالمي: البحث في قنوات واتساب\n\nتوفر نقطة النهاية `/v2/channels/search/text` وصولاً برمجياً إلى دليل واتساب العالمي للقنوات العامة. هذا هو نفس محرك البحث المستخدم في تطبيق واتساب.\n\n---\n\n## 🔍 كيف يعمل البحث\n\nيقوم محرك البحث بمطابقة تقريبية مقابل **اسم القناة** و **الوصف**. يعطي الأولوية للقنوات الموثقة (العلامة الخضراء) وتلك ذات أعداد المتابعين العالية.\n\n### نموذج \"المؤشر\" للترقيم (Cursor)\nيستخدم بحث واتساب سلسلة مؤشر مبهمة للترقيم للتعامل مع ملايين السجلات بكفاءة.\n\n**سير العمل:**\n1.  **الطلب الأول**: أرسل `startCursor=\"\"`.\n2.  **الاستجابة**: ستتلقى قائمة بالقنوات وسلسلة `nextCursor`.\n3.  **الصفحة التالية**: أرسل سلسلة `nextCursor` كمعلمة `startCursor` في طلبك التالي.\n\n---\n\n## 🎯 استراتيجيات التصفية\n\n### 1. حسب الفئة (`categories`)\nيمكنك تصفية النتائج لمواضيع محددة.\n*   **القيم المتاحة**:\n    *   `ENTERTAINMENT`: الترفيه.\n    *   `SPORTS`: الرياضة.\n    *   `NEWS`: الأخبار.\n    *   `BUSINESS`: الأعمال والشركات.\n\n---\n\n## ⚠️ ملاحظات هامة\n\n*   **تحديد المعدل**: البحث عملية مكلفة. لا تستخدم نقطة النهاية هذه لميزات الإكمال التلقائي عالية التردد.\n            "
        }
      }
    },
    {
      "path": "/v2/channels/search/views",
      "methods": [
        "GET"
      ],
      "title": "Get Channel Views",
      "category": "Channels Control",
      "description": "Retrieve available view types for searching channels (e.g. RECOMMENDED, MOST_ACTIVE).",
      "extraInfo": "\n# Filter Keys: View Types\n\nThe `/v2/channels/search/views` endpoint returns the valid sorting algorithms you can use in the Main Search API.\n\n---\n\n## 🏗️ Dynamic Sorting\n\nThe WhatsApp algorithm provides different lenses to view the channel directory.\n\n### Key Views:\n*   **`RECOMMENDED`**: The default \"For You\" experience.\n*   **`POPULAR`**: Highest subscriber count.\n*   **`NEW`**: Recently created channels.\n*   **`MOST_ACTIVE`**: Channels with high posting frequency (useful for finding bots/news).\n\n### Usage\nPass any of these strings to the [`/v2/channels/search/view`](/v2/channels/search/view) endpoint as the `view` parameter.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Analytics",
          "content": "Returns view counts and interaction metrics."
        },
        {
          "type": "warning",
          "title": "Privacy",
          "content": "Metrics are aggregated and approximate to protect user privacy."
        }
      ],
      "recommendations": [
        "Track these metrics to optimize your content strategy.",
        "Compare view counts against follower counts to measure active engagement."
      ],
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Views retrieved successfully",
          "example": [
            "RECOMMENDED",
            "MOST_ACTIVE",
            "POPULAR"
          ]
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "الحصول على طرق عرض القنوات",
          "description": "استرجع أنواع العرض المتاحة للبحث عن القنوات (مثل RECOMMENDED, MOST_ACTIVE).",
          "extraInfo": "\n# مفاتيح التصفية: أنواع العرض\n\nتعيد نقطة النهاية `/v2/channels/search/views` خوارزميات الترتيب الصالحة التي يمكنك استخدامها في واجهة برمجة تطبيقات البحث الرئيسية.\n\n---\n\n## 🏗️ الترتيب الديناميكي\n\nتوفر خوارزمية واتساب عدسات مختلفة لعرض دليل القنوات.\n\n### العروض الرئيسية:\n*   **`RECOMMENDED`**: تجربة \"لك\" الافتراضية.\n*   **`POPULAR`**: أعلى عدد مشتركين.\n*   **`NEW`**: القنوات المنشأة حديثاً.\n*   **`MOST_ACTIVE`**: القنوات ذات وتيرة النشر العالية.\n            "
        }
      }
    },
    {
      "path": "/v2/channels/search/countries",
      "methods": [
        "GET"
      ],
      "title": "Get Channel Countries",
      "category": "Channels Control",
      "description": "Retrieve available country filters for searching channels.",
      "extraInfo": "\n# Filter Keys: Country Codes\n\nThe `/v2/channels/search/countries` endpoint returns the list of ISO 3166-1 alpha-2 country codes supported by WhatsApp Search.\n\n---\n\n## 🌍 Implementation Strategy\n\n### Localization\nWhen building a \"Trends\" tab:\n1.  **Detect User Location**: Use the user's IP or profile settings to guess their country (e.g., `BR` for Brazil).\n2.  **Validate**: Check if `BR` exists in this list.\n3.  **Search**: if valid, call `search/view?view=POPULAR&country=BR`.\n\n### Common Codes\n*   `US`: United States\n*   `IN`: India\n*   `ID`: Indonesia\n*   `BR`: Brazil\n*   `EG`: Egypt\n    ",
      "tips": [
        {
          "type": "info",
          "title": "ISO Codes",
          "content": "Uses standard ISO 3166-1 alpha-2 country codes."
        },
        {
          "type": "info",
          "title": "Localization",
          "content": "Channels are often region-locked or ranked by country."
        }
      ],
      "recommendations": [
        "Default to the user's current IP-based country.",
        "Allow users to manually change regions to see international content."
      ],
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Countries retrieved successfully",
          "example": [
            "US",
            "EG",
            "SA",
            "AE"
          ]
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "الحصول على دول القنوات",
          "description": "استرجع مرشحات الدول المتاحة للبحث عن القنوات.",
          "extraInfo": "\n# مفاتيح التصفية: أكواد الدول\n\nتعيد نقطة النهاية `/v2/channels/search/countries` قائمة بأكواد الدول التي يدعمها بحث واتساب.\n\n---\n\n## 🌍 استراتيجية التنفيذ\n\n### التوطين\nعند بناء تبويب \"الاتجاهات\":\n1.  **اكتشاف موقع المستخدم**: استخدم IP المستخدم لتخمين دولته (مثلاً `SA` للسعودية).\n2.  **التحقق**: تأكد من وجود الكود في هذه القائمة.\n3.  **البحث**: اتصل بـ `search/view?view=POPULAR&country=SA`.\n            "
        }
      }
    },
    {
      "path": "/v2/channels/search/categories",
      "methods": [
        "GET"
      ],
      "title": "Get Channel Categories",
      "category": "Channels Control",
      "description": "Retrieve available channel categories for searching.",
      "extraInfo": "\n# Filter Keys: Channel Categories\n\nThe `/v2/channels/search/categories` endpoint returns the official list of topic filters supported by the WhatsApp directory.\n\n---\n\n## 🎯 Implementation Strategy\n\n### Dynamic Dropdowns\nDo not hardcode these values in your frontend code. WhatsApp may add new categories (e.g., \"Gaming\" or \"Science\") in the future.\n*   **Best Practice**: Fetch this list once on app load and populate your \"Filter by Topic\" dropdown dynamically.\n\n### Standard Values\nCommon categories include:\n*   `ENTERTAINMENT`\n*   `SPORTS`\n*   `LIFESTYLE`\n*   `BUSINESS`\n*   `NEWS`\n*   `ORGANIZATIONS`\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Directory",
          "content": "Lists available categories (e.g., News, Sports, Entertainment)."
        },
        {
          "type": "positive",
          "title": "Discovery",
          "content": "Use correct categories to improve your channel's visibility."
        }
      ],
      "recommendations": [
        "Cache this list; categories rarely change.",
        "Display these categories in your UI to help users filter searches."
      ],
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Categories retrieved successfully",
          "example": [
            "Entertainment",
            "News",
            "Technology"
          ]
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "الحصول على فئات القنوات",
          "description": "استرجع فئات القنوات المتاحة للبحث.",
          "extraInfo": "\n# مفاتيح التصفية: فئات القنوات\n\nتعيد نقطة النهاية `/v2/channels/search/categories` القائمة الرسمية لمرشحات المواضيع التي يدعمها دليل واتساب.\n\n---\n\n## 🎯 استراتيجية التنفيذ\n\n### القوائم المنسدلة الديناميكية\nلا تضع هذه القيم بشكل ثابت في كود واجهتك الأمامية. قد يضيف واتساب فئات جديدة في المستقبل.\n*   **أفضل ممارسة**: اجلب هذه القائمة مرة واحدة عند تحميل التطبيق وقم بملء قائمة التصفية ديناميكياً.\n            "
        }
      }
    },
    {
      "path": "/v2/contacts-overview",
      "methods": [
        "GET"
      ],
      "category": "Contacts",
      "isArticle": true,
      "title": "Contacts Management",
      "description": "Overview of how to manage WhatsApp contacts, check existence, and handle blocks.",
      "extraInfo": "\n# Mastering Relationships: Contacts Management\n\nIn the WhatsApp Protocol, a \"Contact\" is more than just a phone number. It is a cryptographic identity with privacy settings, profile metadata, and a persistent session state. The **Contacts API** gives you the tools to manage these relationships programmatically.\n\n---\n\n## 🆔 The Anatomy of an Identity\n\nTo work with WhatsApp, you must understand the two types of IDs.\n\n### 1. JID (Jabber ID) - The Standard\nThis is possibly the most important concept in the entire API.\n*   **Format**: `[country_code][phone_number]@c.us`\n*   **Example**: `15551234567@c.us`\n*   **Usage**: Used for 99% of operations (sending messages, checking presence, blocking).\n*   **Persistence**: If a user changes their phone number, their JID **changes**.\n\n### 2. LID (Lookup ID) - The Future\nIntroduced recently by Meta to support username-based privacy.\n*   **Format**: `[random_integer]@lid`\n*   **Example**: `123456789012345@lid`\n*   **Usage**: Currently required only for specific advanced features (like hidden group members).\n*   **Persistence**: If a user changes their phone number, their LID **stays the same**. This allows for long-term tracking of a user identity across phone number swaps.\n\n---\n\n## 📖 The \"Address Book\" Philosophy\n\nWhatsApp interacts with two distinct lists of people:\n\n### A. The \"Saved\" List (True Contacts)\nThese are people whose numbers you have explicitly saved in your phone's address book (or pushed via API).\n*   **Privilege**: They can see your Profile Picture and Status (if your privacy is set to \"My Contacts\").\n*   **Route**: `/v2/contacts/all`\n\n### B. The \"Interaction\" List\nThese are people who have messaged you, but you haven't saved them.\n*   **Visual**: In the app, they appear as just a phone number (no name).\n*   **Privilege**: Restricted. They might not see your bio or photo.\n\n**Best Practice**: For a business bot, you rarely need to \"Save\" contacts. You mostly interact with incoming JIDs dynamically. Saving is only necessary if you want to bypass a user's \"My Contacts Only\" privacy filter to show them your profile photo.\n\n---\n\n## 🔍 Discovery & Verification\n\nOne of the most powerful features is **Existence Checking**.\n\n### The \"Is this a WhatsApp number?\" Problem\nMarketing databases are full of landlines and dead numbers. Sending messages to them will lower your quality score.\n*   **Solution**: Use `/v2/contacts/check-exists`.\n*   **Logic**:\n    1.  Input: `+1 (555) 000-0000`\n    2.  API Action: Pings WhatsApp Directory Server.\n    3.  Result: `true` (It's a valid WhatsApp account) or `false`.\n*   **Cost**: This operation is rate-limited. Checking 10,000 numbers in an hour looks like \"Scraping\" and will trigger a ban.\n*   **Strategy**: Check numbers *lazily* (just before sending the first message), not in bulk.\n\n---\n\n## 🛡️ Privacy & Blocking\n\n### The Blocklist\nBlocking is a functional tool, not just an emotional one.\n*   **Spam Defense**: If a user spams your bot with \"hi hi hi hi\", automatically call `/v2/contacts/block`.\n*   **Opt-Out Compliance**: If a user types \"STOP\", you must stop messaging them. Blocking them ensures your system *physically cannot* message them again, providing a fail-safe against logic bugs.\n\n### Profile Visibility\nWhen you fetch contact info (`/v2/contacts/[id]`), you might see `profilePic: null` or `about: null`.\n*   **This is not a bug.**\n*   It means the user has set their privacy to **\"Nobody\"** or **\"My Contacts\"** (and they haven't saved your bot).\n*   **Respect**: Do not attempt to bypass this. If the data is hidden, it is private.\n\n---\n\n## 🔮 Strategic Workflows\n\n### Workflow A: The \"CRM Sync\"\nKeep your Salesforce/HubSpot database up to date.\n1.  **Trigger**: User messages your bot.\n2.  **Action**: Call `/v2/contacts/[id]`.\n3.  **Data**: Extract their `pushName` (the name they set for themselves) and `profilePicUrl`.\n4.  **Save**: Update your CRM card with their real face and name.\n5.  **Benefit**: Your support agents feel like they are talking to a real person, not a number.\n\n### Workflow B: The \"Number Migration\" Handler\n1.  **Event**: You know a user by their JID `123@c.us`.\n2.  **Action**: Store their LID `999@lid` alongside it.\n3.  **Future**: User changes number to `456@c.us`.\n4.  **Recovery**: If they message you again, verify the LID. If `999@lid` matches, you know it's the same person. Merge the chat history.\n\n---\n\n## ⚠️ Limits & Quotas\n\n*   **15MB**: The maximum size of valid contact photos you can download.\n*   **Sync Frequency**: WhatsApp syncs contacts periodically. If you add a contact on your phone, it might take ~30 seconds to show up in the `/v2/contacts/all` API response.\n*   **Legacy Groups**: Some very old groups use LIDs as participant IDs. Modern integration should always prefer JIDs unless explicitly stated otherwise.\n    ",
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "WhatsApp Existence",
          "content": "Always check if a number exists before sending your first message to avoid 'Invalid Recipient' errors."
        }
      ],
      "recommendations": [
        "Store the `@c.us` ID in your database as the primary key for users.",
        "Implement a cooldown period for existence checks on the same number.",
        "Use the profile picture URL for a more personalized user experience in your dashboard."
      ],
      "responses": [],
      "translations": {
        "ar": {
          "title": "إدارة جهات الاتصال",
          "description": "نظرة عامة على كيفية إدارة جهات اتصال واتساب، والتحقق من الوجود، والتعامل مع الحظر.",
          "extraInfo": "\n# إتقان العلاقات: إدارة جهات الاتصال\n\nفي بروتوكول واتساب، \"جهة الاتصال\" هي أكثر من مجرد رقم هاتف. إنها هوية تشفيرية مع إعدادات خصوصية، وبيانات ملف شخصي وصفية، وحالة جلسة مستمرة. تمنحك **واجهة برمجة تطبيقات جهات الاتصال** الأدوات لإدارة هذه العلاقات برمجياً.\n\n---\n\n## 🆔 تشريح الهوية\n\nللعمل مع واتساب، يجب أن تفهم نوعي المعرفات:\n\n### 1. JID (معرف جابر) - المعيار\nهذا هو المفهوم الأهم في الواجهة بأكملها.\n*   **الصيغة**: `[كود_الدولة][رقم_الهاتف]@c.us`\n*   **مثال**: `966500000000@c.us`\n*   **الاستخدام**: يستخدم لـ 99% من العمليات (إرسال الرسائل، التحقق من التواجد، الحظر).\n*   **الاستمرارية**: إذا قام المستخدم بتغيير رقم هاتفه، يتغير JID الخاص به.\n\n### 2. LID (معرف البحث) - المستقبل\nتم إدخاله مؤخراً لدعم الخصوصية القائمة على اسم المستخدم.\n*   **الصيغة**: `[رقم_عشوائي]@lid`\n*   **الاستمرارية**: إذا قام المستخدم بتغيير رقم هاتفه، يظل LID الخاص به **كما هو**. هذا يسمح بتتبع هوية المستخدم على المدى الطويل حتى لو تغير الرقم.\n\n---\n\n## 🔍 الاكتشاف والتحقق\n\nواحدة من أقوى الميزات هي **التحقق من وجود الحساب**.\n\n### مشكلة \"هل هذا الرقم مسجل في واتساب؟\"\nقواعد بيانات التسويق مليئة بالأرقام الأرضية والميتة. إرسال رسائل إليها سيقلل من درجة جودة حسابك وقد يؤدي لحظره.\n*   **الحل**: استخدم `/v2/contacts/check-exists`.\n*   **المنطق**: يقوم النظام بالاستعلام من خوادم واتساب عما إذا كان الرقم يمتلك حساباً نشطاً.\n*   **الاستراتيجية**: لا تقم بمسح أعداد كبيرة من الأرقام دفعة واحدة؛ فهذا قد يؤدي لحظر الحساب. تحقق من الأرقام \"بشكل كسول\" (قبيل إرسال الرسالة الأولى مباشرة).\n\n---\n\n## 🛡️ الخصوصية والحظر\n\nالحظر هو أداة وظيفية، وليس مجرد أداة عاطفية.\n*   **الدفاع ضد السبام**: إذا قام مستخدم بإزعاج البوت الخاص بك، فاستدعِ `/v2/contacts/block`.\n*   **الامتثال لطلب التوقف**: إذا كتب المستخدم \"STOP\" أو \"توقف\"، يجب عليك التوقف عن مراسلته. حظرهم يضمن أن نظامك *مادياً* لا يمكنه مراسلتهم مرة أخرى، مما يوفر صمام أمان ضد أخطاء المنطق البرمجي.\n\n### ظهور الملف الشخصي\nعند جلب معلومات جهة اتصال، قد تجد قيم `null` للصور أو \"حول\" (About). هذا ليس خطأ برمجي، بل يعني أن المستخدم ضبط إعدادات خصوصيته على \"لا أحد\" أو \"جهات اتصالي فقط\". احترم هذه الخصوصية دائماً.\n\n---\n\n## 🔮 سيناريوهات استراتيجية\n\n### سيناريو أ: مزامنة CRM\nحافظ على تحديث قاعدة بيانات Salesforce أو HubSpot.\n1.  يرسل المستخدم رسالة للبوت.\n2.  يستدعي البوت `GET /v2/contacts/[id]`.\n3.  يستخرج الاسم (`pushName`) وصورة الملف الشخصي.\n4.  يحدّث سجل العميل في نظامك، مما يجعل موظفي الدعم يشعرون أنهم يتحدثون مع شخص حقيقي وليس مجرد رقم.\n\n---\n\n## ⚠️ القيود والحصص\n\n*   **15 ميجابايت**: الحجم الأقصى لصور جهات الاتصال التي يمكنك تحميلها.\n*   **تواتر المزامنة**: قد يستغرق ظهور جهة اتصال جديدة أضفتها على هاتفك حوالي 30 ثانية لتظهر في واجهة برمجة التطبيقات.\n            ",
          "tips": [
            {
              "title": "وجود واتساب",
              "content": "تحقق دائماً من وجود الرقم على واتساب قبل إرسال الرسالة الأولى لتجنب أخطاء 'المستلم غير صالح'."
            }
          ],
          "recommendations": [
            "خزن معرف `@c.us` في قاعدة بياناتك كمفتاح أساسي للمستخدمين.",
            "قم بتنفيذ فترة انتظار (Cooldown) لعمليات التحقق من وجود الرقم لتجنب الحظر.",
            "استخدم رابط صورة الملف الشخصي لتوفير تجربة مستخدم أكثر تخصيصاً في لوحة التحكم الخاصة بك."
          ]
        }
      }
    },
    {
      "path": "/v2/contacts/all",
      "methods": [
        "GET"
      ],
      "title": "Get All Contacts",
      "category": "Contacts",
      "description": "Retrieves a list of all known contacts from the connected WhatsApp account's address book and chat history.",
      "extraInfo": "\n# Digging for Gold: Retrieving Your Address Book\n\nThe `/v2/contacts/all` endpoint is the heavy lifter of the Contacts API. It downloads, filters, and paginates the entire list of entities your WhatsApp account knows about.\n\n---\n\n## 🏗️ What is \"All\"?\n\nWhen you ask for \"All Contacts\", WhatsApp doesn't just return your saved address book. It returns a mix of:\n1.  **Saved Contacts**: People in your phone's address book (with names).\n2.  **Unsaved Interactions**: People who messaged you, but you never saved properly.\n3.  **Business Identities**: Official Business Accounts (OBAs) you have interacted with.\n4.  **Legacy Groups**: Occasionally, old group metadata might appear here (though usually filtered).\n\n### The ID Mix\nYou will see two types of IDs in the response:\n*   **@c.us** (Standard): `123456789@c.us`. This is a normal phone number.\n*   **@lid** (Lookup ID): `123456789@lid`. This is a privacy-preserving identifier used by some modern WhatsApp features.\n    *   *Advice*: If you see an @lid, store it alongside the @c.us if possible, but your UI should primarily index on the phone number (@c.us) for human readability.\n\n---\n\n## ⚡ Pagination & Performance\n\nIf your bot has been running for 5 years, this list could contain 50,000 entries.\n*   **Default Limit**: The API defaults to returning a manageable chunk (e.g., 50 or 100).\n*   **Max Limit**: You can request up to `1000` contacts per call, but this increases latency.\n\n### The Pagination Loop\nTo fetch *everything*, use a `while` loop:\n```javascript\nlet allContacts = [];\nlet offset = 0;\nwhile (true) {\n    const batch = await api.getContacts({ limit: 1000, offset: offset });\n    if (batch.length === 0) break;\n    allContacts.push(...batch);\n    offset += 1000;\n}\n```\n\n---\n\n## 🔍 Filtering & Sorting\n\nThe API provides server-side utilities to help you find what you need without downloading the whole world.\n\n### Sorting\n*   **ByName**: `sortBy=name`. Helpful for building an A-Z contact picker UI.\n*   **ByPushName**: `sortBy=pushname`. Useful if your address book is empty and you rely on user-set names.\n\n### Filtering (Implicit)\nCurrently, the API returns *valid* contacts. It automatically filters out invalid JIDs or malformed entries that might exist in the raw database, ensuring you get a clean list.\n\n---\n\n## 🛡️ Best Practices\n\n### 1. Don't Poll This\n*   **Bad**: Calling `/v2/contacts/all` every 5 minutes \"just in case\".\n*   **Why**: It's an expensive database scan.\n*   **Good**: Call it **once** on startup to hydrate your cache. Then, listen for `message.upsert` and `contact.update` events to incrementally update your local state.\n\n### 2. Matching Names\n*   **Scenario**: You have a number `+12345`.\n*   **Goal**: Find the name.\n*   **Method**: Do *not* call `/v2/contacts/all` and search the array. That's O(N).\n*   **Method**: Call `/v2/contacts/+12345@c.us` directly. That's O(1). Use the list endpoint only for \"Directory\" views.\n\n### 3. Privacy Respect\n*   **Data Minimization**: If you are building a dashboard for your agents, do not display the raw @lid or internal IDs. Show `name || pushname || number`.\n*   **Staleness**: Be aware that `pushname` changes. A user might change their name from \"John\" to \"Crypto King\" overnight. Your local cache will be outdated until you refresh.\n\n---\n\n## ❓ FAQ\n\n**Q: Why are some names null?**\nA: `name` is the *Address Book Name*. If you haven't saved the number in Google/Apple Contacts (or the bot's virtual address book), `name` is null. `pushname` is what the user calls themselves.\n\n**Q: Can I add a contact via this API?**\nA: **No.** This is a read-only view. To \"add\" a contact, you technically just need to message them. To \"save\" them with a name, you would need to interact with the host OS's address book, which this API assumes is managed externally or virtually.\n\n**Q: I see duplicates!**\nA: You might get the same human returned as both `@c.us` and `@lid`. This is rare in the list view (we try to merge them), but if it happens, treat the `@c.us` as the master record.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Sync",
          "content": "Returns all contacts sync'd from the phone's address book."
        },
        {
          "type": "warning",
          "title": "Performance",
          "content": "Can be slow for accounts with thousands of contacts. Use caching."
        }
      ],
      "recommendations": [
        "Call this only on startup to bootstrap your local database.",
        "Filter out contacts without WhatsApp accounts (isWAContact: false)."
      ],
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "limit": {
          "required": false,
          "type": "string",
          "description": "Maximum number of contacts to return (1-1000)",
          "example": "50"
        },
        "offset": {
          "required": false,
          "type": "string",
          "description": "Number of contacts to skip",
          "example": "0"
        },
        "sortBy": {
          "required": false,
          "type": "string",
          "description": "Field to sort by (e.g., name)",
          "example": "name"
        },
        "sortOrder": {
          "required": false,
          "type": "string",
          "description": "Sort order (ASC or DESC)",
          "example": "ASC"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "List of contacts retrieved successfully",
          "example": [
            {
              "id": "1234567890@c.us",
              "name": "John Doe",
              "pushname": "John"
            },
            {
              "id": "0987654321@lid",
              "name": "Business Contact",
              "pushname": "Business"
            }
          ]
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Parameter Format",
          "contentType": "application/json",
          "example": {
            "code": "invalid_param",
            "message": "Invalid format for one or more parameters.",
            "details": {
              "param": "text",
              "value": "too_long",
              "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "جلب جميع جهات الاتصال",
          "description": "يسترجع قائمة بجميع جهات الاتصال المعروفة من دفتر عناوين حساب واتساب المتصل وسجل الدردشة.",
          "tips": [
            {
              "title": "المزامنة",
              "content": "يعيد جميع جهات الاتصال المتزامنة مع دفتر عناوين الهاتف."
            },
            {
              "title": "الأداء",
              "content": "يمكن أن يكون بطيئًا للحسابات التي تحتوي على آلاف جهات الاتصال. استخدم التخزين المؤقت."
            }
          ],
          "recommendations": [
            "اتصل بهذا فقط عند بدء التشغيل لتمهيد قاعدة بياناتك المحلية.",
            "قم بتصفية جهات الاتصال التي ليس لديها حسابات واتساب (isWAContact: false)."
          ],
          "args": {
            "limit": {
              "description": "أقصى عدد من جهات الاتصال للإرجاع (1-1000)"
            },
            "offset": {
              "description": "عدد جهات الاتصال التي سيتم تخطيها"
            },
            "sortBy": {
              "description": "الحقل المراد الفرز حسبه (مثلاً name)"
            },
            "sortOrder": {
              "description": "ترتيب الفرز (ASC أو DESC)"
            }
          },
          "extraInfo": "\n# البحث عن الذهب: استرجاع دفتر عناوينك\n\nنقطة النهاية `/v2/contacts/all` هي الأداة الأقوى في واجهة جهات الاتصال. فهي تقوم بتحميل وتصفية وتقسيم قائمة الكيانات التي يعرفها حسابك على واتساب.\n\n---\n\n## 🏗️ ماذا تعني \"الكل\"؟\n\nعندما تطلب \"جميع جهات الاتصال\"، لا يعيد واتساب فقط دفتر العناوين المحفوظ، بل مزيجاً من:\n1.  **جهات الاتصال المحفوظة**: الأشخاص في دفتر عناوين هاتفك (مع أسمائهم).\n2.  **تفاعلات غير محفوظة**: الأشخاص الذين راسلوك ولكن لم تقم بحفظهم رسمياً.\n3.  **هويات الأعمال**: حسابات الأعمال الرسمية التي تفاعلت معها.\n\n### المعرفات المختلطة\nسترى نوعين من المعرفات في الاستجابة:\n*   **@c.us** (قياسي): رقم هاتف عادي.\n*   **@lid** (معرف بحث): معرف يحافظ على الخصوصية تستخدمه ميزات واتساب الحديثة.\n    *   *نصيحة*: إذا رأيت @lid، فخزنه بجانب @c.us إذا أمكن، ولكن اجعل واجهتك تعتمد أساساً على رقم الهاتف (@c.us) لسهولة القراءة البشرية.\n\n---\n\n## ⚡ التقسيم (Pagination) والأداء\n\nإذا كان البوت الخاص بك يعمل لسنوات، فقد تحتوي هذه القائمة على 50,000 إدخال.\n*   **الحد الافتراضي**: تعيد الواجهة مجموعة صغيرة (مثلاً 50 أو 100).\n*   **الحد الأقصى**: يمكنك طلب ما يصل إلى `1000` جهة اتصال في كل استدعاء، لكن هذا يزيد من وقت الاستجابة.\n\n---\n\n## 🛡️ أفضل الممارسات\n\n### 1. لا تكرر الاستدعاء دون داعٍ\n*   **خطأ**: استدعاء `/v2/contacts/all` كل 5 دقائق \"للاحتياط\".\n*   **لماذا**: هو إجراء مكلف برمجياً.\n*   **صح**: استدعِها **مرة واحدة** عند التشغيل لتعبئة الذاكرة المؤقتة (Cache)، ثم استمع لأحداث التحديث (`contact.update`) لتحديث حالتك المحلية تدريجياً.\n\n### 2. مطابقة الأسماء\n*   **الهدف**: معرفة اسم صاحب الرقم `+12345`.\n*   **الطريقة**: **لا** تستدعِ `/v2/contacts/all` وتبحث في القائمة الكبيرة؛ فهذا بطيئ.\n*   **الطريقة**: استدعِ `/v2/contacts/+12345@c.us` مباشرة؛ فهو أسرع بكثير. استخدم قائمة \"الكل\" فقط لبناء \"دليل\" كامل.\n            "
        }
      }
    },
    {
      "path": "/v2/contacts",
      "methods": [
        "GET"
      ],
      "title": "Get Contact Info",
      "category": "Contacts",
      "description": "Get basic information about a specific contact.",
      "extraInfo": "\n# Who is this? Get Contact Details\n\nThe `/v2/contacts/[chatId]` endpoint retrieves the public metadata for any valid WhatsApp user. This is your primary tool for \"enriching\" user profiles in your application.\n\n---\n\n## 🧩 Understanding the Data Fields\n\nWhen you fetch a contact, you receive several fields that might seem redundant but serve very different purposes.\n\n### 1. `id._serialized` (The Key)\n*   **Value**: `15551234567@c.us`\n*   **Usage**: This is the immutable primary key. Always store this in your database. Do not try to parse the phone number manually; treat the whole string as the ID.\n\n### 2. `pushname` (The Public Name)\n*   **Value**: \"Alice\"\n*   **Source**: This is the name the user set for *themselves* in WhatsApp Settings.\n*   **Reliability**: High. It is what the user *wants* to be called.\n*   **Verification**: This name is **NOT** verified. A user can set their pushname to \"Bank of America Support\" to scam people. Never use this for identity verification.\n\n### 3. `name` (The Local Name)\n*   **Value**: \"Alice from Gym\"\n*   **Source**: This is the name *you* saved in your phone's address book for this number.\n*   **Availability**: If you haven't saved the number, this field will be `undefined` or `null`.\n*   **Priority**: In a UI, you should usually display `name` (if available) aliased over `pushname` (fallback), because `name` is your private note.\n\n### 4. `number` (The Clean Phone)\n*   **Value**: `15551234567`\n*   **Usage**: The raw MSISDN without the `@c.us` suffix. Useful if you need to pass the number to an SMS gateway.\n\n---\n\n## 🏢 Business & Enterprise Flags\n\nThe API returns two boolean flags that help you categorize users:\n\n### `isBusiness`\n*   **True**: The user is using the \"WhatsApp Business App\" (SMB).\n*   **Implication**: They might have automated greeting messages or \"Away\" messages. They likely have a catalog.\n\n### `isEnterprise`\n*   **True**: The user is using the \"WhatsApp Business API\" (Cloud API/BSP).\n*   **Implication**: This is likely a bot or a large company.\n    *   *Warning*: Bots talking to bots can create infinite loops. If you detect `isEnterprise: true`,\n  tips: [\n        {\n            type: 'info',\n            title: 'Details',\n            content: 'Fetches stored contact details like Name and Notify Name.'\n        },\n        {\n            type: 'info',\n            title: 'Notify Name',\n            content: 'This is the name the user set for themselves in WhatsApp.'\n        }\n    ],\n  recommendations: [\n        \"Use the 'Notify Name' if the contact is not saved in your address book.\",\n        \"Update your local record if the contact's details change.\"\n    ]\n  \n   you might want to disable your own auto-responders for that chat to prevent a loop.\n\n---\n\n## 🔍 Privacy & \"Ghost\" Data\n\nIf you query a valid number but get limited data:\n*   **Scenario**: You fetch `12345@c.us` and get an ID, but `pushname` is `undefined`.\n*   **Cause**: The user has strict privacy settings.\n*   **Action**: Nothing. The API cannot force the data to appear. You should render a default placeholder (e.g., \"WhatsApp User\").\n\n---\n\n## ⚙️ Usage Patterns\n\n### Pattern A: The \"Welcome\" Personalization\n1.  User sends \"Hi\".\n2.  Bot calls `GET /v2/contacts/[id]`.\n3.  Bot retrieves `pushname: \"Sarah\"`.\n4.  Bot replies: \"Hello Sarah! How can I help?\"\n    *   *Effect*: High perceived personalization.\n\n### Pattern B: The Block Check\n1.  You suspect a user blocked you.\n2.  You call this endpoint.\n3.  If you can see their `pushname` but **cannot** see their `profilePic` or `about` status (via other endpoints), and messages are single-ticking, it is a strong indicator of being blocked. (Note: The API does not have an explicit `isBlockedByMe` flag for privacy reasons).\n\n---\n\n## ⚠️ Notes on Caching\n\nUser profiles change rarely.\n*   **Do Not**: Call this endpoint every time you render a chat message.\n*   **Do**: Cache the result for 24-48 hours.\n*   **Refresh**: Only aggressive fetch if the user interacts with you after a long period of silence.\n    ",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "contactId": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the contact (e.g., 123456789@c.us)",
          "example": "123456789@c.us"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Contact info retrieved successfully",
          "example": {
            "id": "123456789@c.us",
            "name": "John Doe",
            "pushname": "John",
            "isBusiness": false,
            "isEnterprise": false
          }
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Parameter Format",
          "contentType": "application/json",
          "example": {
            "code": "invalid_param",
            "message": "Invalid format for one or more parameters.",
            "details": {
              "param": "text",
              "value": "too_long",
              "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "جلب معلومات جهة الاتصال",
          "description": "الحصول على المعلومات الأساسية لجهة اتصال محددة.",
          "tips": [
            {
              "title": "التفاصيل",
              "content": "يجلب تفاصيل جهة الاتصال المخزنة مثل الاسم واسم الإشعار."
            },
            {
              "title": "اسم الإشعار",
              "content": "هذا هو الاسم الذي وضعه المستخدم لنفسه في واتساب."
            }
          ],
          "recommendations": [
            "استخدم 'اسم الإشعار' إذا لم تكن جهة الاتصال محفوظة في دفتر العناوين الخاص بك.",
            "قم بتحديث سجلك المحلي إذا تغيرت تفاصيل جهة الاتصال."
          ],
          "args": {
            "contactId": {
              "description": "المعرف الفريد لجهة الاتصال (مثال: 123456789@c.us)"
            }
          },
          "extraInfo": "\n# من هذا؟ الحصول على تفاصيل جهة الاتصال\n\nتسترجع نقطة النهاية `/v2/contacts/[chatId]` البيانات العامة لأي مستخدم واتساب صالح. هذه أداتك الأساسية \"لإثراء\" ملفات تعريف المستخدمين في تطبيقك.\n\n---\n\n## 🧩 فهم حقول البيانات\n\nعند جلب جهة اتصال، تتلقى عدة حقول قد تبدو زائدة عن الحاجة ولكنها تخدم أغراضاً مختلفة تماماً.\n\n### 1. `id._serialized` (المفتاح)\n*   **القيمة**: `15551234567@c.us`\n*   **الاستخدام**: هذا هو المفتاح الأساسي غير القابل للتغيير. قم دائماً بتخزين هذا في قاعدة بياناتك. لا تحاول معالجة رقم الهاتف يدوياً؛ تعامل مع السلسلة بأكملها كمعرف.\n\n### 2. `pushname` (الاسم العام)\n*   **القيمة**: \"Alice\"\n*   **المصدر**: هذا هو الاسم الذي وضعه المستخدم *لنفسه* في إعدادات واتساب. هي المرجعية للأشخاص الذين لم يسبق لك تخزينهم.\n\n### 3. `name` (الاسم المحلي)\n*   **القيمة**: \"Alice from Gym\"\n*   **المصدر**: هذا هو الاسم الذي قمت *أنت* بحفظه في دفتر عناوين هاتفك لهذا الرقم.\n*   **الأولوية**: في واجهة المستخدم، يجب عليك عادةً عرض `name` (إذا كان متاحاً) كبديل لـ `pushname`.\n\n### 4. `number` (رقم الهاتف النظيف)\n*   **القيمة**: `15551234567`\n*   **الاستخدام**: رقم MSISDN الخام بدون لاحقة `@c.us`.\n\n---\n\n## 🏢 علامات الأعمال والشركات\n\nترجع الواجهة علامتين تساعدانك في تصنيف المستخدمين:\n\n*   **`isBusiness`**: إذا كانت `true` تعني أن المستخدم يستخدم تطبيق \"واتساب للأعمال\".\n*   **`isEnterprise`**: إذا كانت `true` تعني أن المستخدم يستخدم \"واجهة برمجة تطبيقات واتساب للأعمال\" (Cloud API). هذا يعني غالباً أنه بوت أو شركة كبيرة. قد ترغب في تعطيل ردودك التلقائية في هذه الحالة لتجنب الحلقات اللانهائية.\n\n---\n\n## 🔍 الخصوصية وبيانات \"الشبح\"\n\nإذا استعلمت عن رقم صالح وحصلت على بيانات محدودة:\n*   **السبب**: المستخدم لديه إعدادات خصوصية صارمة.\n*   **الإجراء**: لا شيء، لا يمكن للواجهة إجبار البيانات على الظهور. يجب عليك عرض قيمة افتراضية (مثلاً \"مستخدم واتساب\").\n            "
        }
      }
    },
    {
      "path": "/v2/contacts/check-exists",
      "methods": [
        "GET"
      ],
      "title": "Check Phone on WhatsApp",
      "category": "Contacts",
      "description": "Check if a phone number is registered on WhatsApp.",
      "extraInfo": "\n# The Gatekeeper: Validating Phone Numbers\n\nThe `/v2/contacts/check-exists` endpoint is your first line of defense against low-quality data. It queries the WhatsApp Global Directory to verify if a specific MSISDN (phone number) corresponds to an active WhatsApp account.\n\n---\n\n## 🏗️ Why is this Critical?\n\nSending messages to invalid numbers is one of the fastest ways to get your bot banned.\n*   **The Signal**: If you try to message `+12345` and it fails because the user doesn't exist, WhatsApp's spam algorithms flag your account as \"Blindly Broadcasting\".\n*   **The Threshold**: A high failure rate indicates you bought a low-quality lead list.\n*   **The Fix**: Validate **100%** of new numbers using this endpoint before queuing your first message.\n\n---\n\n## 🧹 Input Sanitization\n\nWhatsApp requires a clean format for verification: `[CountryCode][Number]`.\n*   **Supported Input**: `15551234567`\n*   **Supported Input**: `+15551234567` (The API strips the plus)\n*   **Unsupported**: `(555) 123-4567` (You must strip symbols)\n*   **Unsupported**: `0015551234567` (Do not use 00 prefix)\n\n### The Brazil/Mexico Rule\nSome countries have variable number lengths.\n*   **Mexico**: Mobile numbers need a `1` after the country code `+52`.\n*   **Brazil**: Numbers might have an extra `9`.\n*   **Auto-Correction**: The Wawp API attempts to auto-correct common formatting errors for these regions, but it is best if you provide the E.164 standard format.\n\n---\n\n## 🚦 Rate Limits & Safety\n\nThis endpoint performs a real-time network lookup.\n*   **The Limit**: You should not exceed **1 verification per second** per instance.\n*   **The \"Scraping\" Risk**: If you feed a sequential list (e.g., `+15550001`,\n  tips: [\n        {\n            type: 'info',\n            title: 'Validation',\n            content: 'Verifies if a phone number is registered on WhatsApp.'\n        },\n        {\n            type: 'warning',\n            title: 'Anti-Scraping',\n            content: 'Excessive checks on random numbers may flag your account as a scraper.'\n        }\n    ],\n  recommendations: [\n        \"Validate numbers before sending your first message to improve delivery rates.\",\n        \"Do not use this to 'warm up' numbers; use it strictly for verification.\"\n    ]\n  \n   `+15550002`, `+15550003`) into this API, WhatsApp will detect pattern recognition scraping and **permanently ban** your number.\n*   **Best Practice**: Only check numbers that users have explicitly provided to you (e.g., via a signup form). Do not use this to \"clean\" a bought database.\n\n---\n\n## 🔮 Integration Patterns\n\n### Pattern A: The Registration Form\n1.  User signs up on your website.\n2.  Backend calls `/v2/contacts/check-exists`.\n3.  **Result**:\n    *   `exists: true`: Show \"WhatsApp\" logo next to their number on the confirmation page.\n    *   `exists: false`: Disable the \"Send via WhatsApp\" button or fallback to SMS.\n\n### Pattern B: The CRM Cleaner\n1.  You have a list of 10,000 stale leads.\n2.  **Wrong Way**: Loop through all 10,000 now.\n3.  **Right Way**:\n    *   Wait until you *need* to message one.\n    *   Check existence JIT (Just-In-Time) 1 second before sending.\n    *   If invalid, mark as \"Bad Data\" in CRM and skip.\n    *   If valid, send and cache the result.\n\n---\n\n## ❓ FAQ\n\n**Q: Does the user know I checked them?**\nA: **No.** This is a silent directory lookup. It does not trigger a notification, blue tick, or \"online\" status.\n\n**Q: Can I get their profile picture here?**\nA: **No.** This endpoint is purely boolean (Exists/Not Exists) involved with the basic JID. To get the photo, you must first confirm existence, then call `/v2/contacts/profile-picture`.\n\n**Q: What if the API returns false but I know they have WhatsApp?**\nA: Ensure you are using the correct Country Code. In 99% of cases, it's a formatting error (e.g., missing a digit or adding an extra '0' prefix).\n    ",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "phone": {
          "required": true,
          "type": "string",
          "description": "Phone number to check (digits only)",
          "example": "1234567890"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Check completed",
          "example": {
            "exists": true,
            "jid": "1234567890@c.us"
          }
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Parameter Format",
          "contentType": "application/json",
          "example": {
            "code": "invalid_param",
            "message": "Invalid format for one or more parameters.",
            "details": {
              "param": "text",
              "value": "too_long",
              "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "التحقق من رقم على واتساب",
          "description": "التحقق مما إذا كان رقم الهاتف مسجلاً في واتساب.",
          "tips": [
            {
              "title": "التحقق",
              "content": "يتحقق مما إذا كان رقم الهاتف مسجلاً على واتساب."
            },
            {
              "title": "مكافحة الكشط",
              "content": "قد تؤدي الشيكات المفرطة على أرقام عشوائية إلى الإبلاغ عن حسابك ككاشط."
            }
          ],
          "recommendations": [
            "تحقق من صحة الأرقام قبل إرسال رسالتك الأولى لتحسين معدلات التسليم.",
            "لا تستخدم هذا 'لإحماء' الأرقام؛ استخدامه بصرامة للتحقق."
          ],
          "args": {
            "phone": {
              "description": "رقم الهاتف المراد التحقق منه (أرقام فقط)"
            }
          },
          "extraInfo": "\n# حارس البوابة: التحقق من أرقام الهواتف\n\nنقطة النهاية `/v2/contacts/check-exists` هي خط دفاعك الأول ضد البيانات منخفضة الجودة. فهي تستعلم من دليل واتساب العالمي للتحقق مما إذا كان رقم الهاتف يوافق حساب واتساب نشطاً.\n\n---\n\n## 🏗️ لماذا هذا أمر بالغ الأهمية؟\n\nإرسال رسائل إلى أرقام غير صالحة هو أحد أسرع الطرق لتعرض الحساب للحظر.\n*   **الإشارة**: إذا حاولت مراسلة رقم غير موجود وفشلت، فإن خوارزميات واتساب تصنف حسابك كـ \"مرسل عشوائي\".\n*   **الحل**: تحقق من **100%** من الأرقام الجديدة باستخدام هذه الواجهة قبل إرسال رسالتك الأولى.\n\n---\n\n## 🚦 حدود المعدل والأمان\n\nتجري هذه الواجهة عملية بحث في الشبكة في الوقت الفعلي.\n*   **الحد**: يجب ألا تتجاوز **عملية تحقق واحدة في الثانية** لكل مثيل.\n*   **خطر \"المسح\" (Scraping)**: إذا قمت بإدخال قائمة تسلسلية (مثل `+15550001`, `+15550002`...)، فسيقوم واتساب باكتشاف نمط المسح و**حظر رقمك نهائياً**.\n*   **أفضل ممارسة**: تحقق فقط من الأرقام التي قدمها المستخدمون لك صراحة. لا تستخدم هذا \"لتنظيف\" قاعدة بيانات مشتراة.\n\n---\n\n## 🔮 أنماط التكامل\n\n### النمط أ: نموذج التسجيل\n1.  يسجل المستخدم في موقعك.\n2.  يستدعي النظام `/v2/contacts/check-exists`.\n3.  **النتيجة**: إذا كان الرقم موجوداً، أظهر شعار \"واتساب\" بجانب رقمه، وإذا لم يكن موجوداً، قم بتعطيل زر \"إرسال عبر واتساب\" أو استخدم SMS كبديل.\n\n### النمط ب: منظف CRM\nإذا كان لديك 10,000 رقم قديم، لا تفحصها جميعاً الآن. انتظر حتى يحين وقت مراسلة أحدهم، وافحصه \"في الوقت المناسب\" (JIT) قبل ثانية واحدة من الإرسال.\n\n---\n\n## ❓ الأسئلة الشائعة\n\n**س: هل يعرف المستخدم أنني تحققت من رقمه؟**\nأ: **لا.** هذه عملية بحث صامتة في الدليل. لا تسبب إشعاراً أو أي ظهور لدى المستخدم.\n\n**س: هل يمكنني الحصول على صورته هنا؟**\nأ: **لا.** هذه الواجهة تعيد نتيجة منطقية (موجود/غير موجود) فقط. للحصول على الصورة، يجب أولاً تأكيد الوجود ثم استدعاء `/v2/contacts/profile-picture`.\n            "
        }
      }
    },
    {
      "path": "/v2/contacts/profile-picture",
      "methods": [
        "GET"
      ],
      "title": "Get Contact Profile Picture",
      "category": "Contacts",
      "description": "Get the profile picture URL of a contact.",
      "extraInfo": "\n# The Face of the User: Profile Pictures\n\nThe `/v2/contacts/profile-picture` endpoint allows you to retrieve the high-resolution avatar of a WhatsApp user, group, or business.\n\n---\n\n## 🖼️ Image Logic\n\nWhen you request a picture, WhatsApp doesn't send the binary data directly. It provides a signed URL hosted on their CDN (Content Delivery Network).\n\n### The Response Format\n```json\n{\n  \"id\": \"12345@c.us\",\n  \"url\": \"https://pps.whatsapp.net/v/t61.24694-24/...\"\n}\n```\n\n*   **URL Expiry**: These URLs are **temporary**. They expire after a certain period (usually 24-48 hours) or if the user changes their photo.\n*   **Best Practice**: Do not just store the URL string in your database.\n    *   *Option A (Lazy)*: Re-fetch the URL from this API every time you need to display it.\n    *   *Option B (Robust)*: Download the image buffer and store it in your own S3 bucket.\n\n---\n\n## 🛡️ Privacy & \"Missing\" Photos\n\nYou will often get a `404 Not Found` or an empty URL.\n\n### Reason 1: Privacy Settings (Most Common)\nThe user has set \"Profile Photo\" to **\"My Contacts\"** or **\"Nobody\"**.\n*   If you are not saved in their phone's address book, you are not a \"Contact\". Therefore, WhatsApp refuses to serve the image.\n*   **Correction**: There is no workaround. You must respect the user's choice.\n\n### Reason 2: No Photo\nThe user simply hasn't set a photo. They see the default grey silhouette.\n\n### Reason 3: It's You\nYou cannot fetch your *own* profile picture via this endpoint (use `/v2/profile/me` instead).\n\n---\n\n## 🔄 Caching & Refresh\n\nFetch operations are expensive networking calls.\n*   **Default Behavior**: The Wawp API caches the profile picture URL for 24 hours to speed up subsequent requests.\n*   **Forcing a Refresh**: If you suspect the user just changed their photo and you need the new one immediately, pass `refresh=true`.\n    *   *Cost*: This bypasses the local cache and hits WhatsApp servers directly. Use sparingly.\n\n---\n\n## 📸 Resolution & Quality\n\n*   **Standard**: The API attempts to fetch the \"Preview\" size (roughly 96x96 or 640x640 depending on availability).\n*   **Full HD**: WhatsApp only serves the full-resolution uncompressed image (e.g., 1920x1920) if the user is in your contact list or you are in a chat with them.\n*   **Groups**: Group icons work the same way. The `contactId` would be `123456@g.us`.\n\n---\n\n## ❓ FAQ\n\n**Q: Can I set the contact's photo?**\nA: **No.** You cannot change another user's profile picture. You can only change *your* own (via `/v2/profile/picture`) or a Group's icon (if you are an admin).\n\n**Q: Why does the URL stop working after a day?**\nA: All `pps.whatsapp.net` links are signed with a time-limited token for security. If you try to load an old URL, you will get a 403 Forbidden.\n\n**Q: Can I get the photo of a business?**\nA: Yes. Official Business Accounts (OBA) usually have public profile photos visible to everyone, regardless of \"My Contacts\" settings.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Privacy",
          "content": "You will get a 404 or placeholder if the user hides their photo."
        },
        {
          "type": "positive",
          "title": "Caching",
          "content": "URLs are temporary; download the image immediately."
        }
      ],
      "recommendations": [
        "Do not use profile pictures for identity verification.",
        "Display a generic avatar if the fetch fails."
      ],
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "contactId": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the contact",
          "example": "123456789@c.us"
        },
        "refresh": {
          "required": false,
          "type": "boolean",
          "description": "Whether to bypass cache and refresh the picture",
          "example": "true"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Profile picture retrieved",
          "example": {
            "id": "123456789@c.us",
            "url": "https://pps.whatsapp.net/v/t61.24694-24/..."
          }
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Parameter Format",
          "contentType": "application/json",
          "example": {
            "code": "invalid_param",
            "message": "Invalid format for one or more parameters.",
            "details": {
              "param": "text",
              "value": "too_long",
              "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "جلب صورة الملف الشخصي",
          "description": "الحصول على رابط صورة الملف الشخصي لجهة اتصال.",
          "tips": [
            {
              "title": "الخصوصية",
              "content": "ستحصل على 404 أو عنصر نائب إذا قام المستخدم بإخفاء صورته."
            },
            {
              "title": "التخزين المؤقت",
              "content": "الروابط مؤقتة؛ قم بتنزيل الصورة فورًا."
            }
          ],
          "recommendations": [
            "لا تستخدم صور الملف الشخصي للتحقق من الهوية.",
            "اعرض أفاتار عام إذا فشل الجلب."
          ],
          "args": {
            "contactId": {
              "description": "المعرف الفريد لجهة الاتصال"
            },
            "refresh": {
              "description": "ما إذا كان سيتم تجاوز الذاكرة المؤقتة وتحديث الصورة"
            }
          },
          "extraInfo": "\n# وجه المستخدم: صور الملف الشخصي\n\nتسمح لك نقطة النهاية `/v2/contacts/profile-picture` باسترداد الصورة الشخصية بدقة عالية لأي مستخدم واتساب أو مجموعة أو نشاط تجاري.\n\n---\n\n## 🖼️ منطق الصور\n\nعندما تطلب صورة، لا يرسل واتساب البيانات الثنائية مباشرة، بل يقدم رابطاً موقعاً (Signed URL) مستضافاً على شبكة توصيل المحتوى (CDN) الخاصة بهم.\n\n*   **صلاحية الرابط**: هذه الروابط **مؤقتة**. تنتهي صلاحيتها بعد فترة معينة (عادةً 24-48 ساعة) أو إذا قام المستخدم بتغيير صورته.\n*   **أفضل ممارسة**: لا تقم بتخزين سلسلة الرابط فقط في قاعدة بياناتك. إما أن تعيد جلب الرابط عند الحاجة، أو قم بتحميل الصورة وتخزينها في خادمك الخاص.\n\n---\n\n## 🛡️ الخصوصية والصور \"المفقودة\"\n\nغالباً ما ستحصل على خطأ `404 Not Found` أو رابط فارغ.\n\n### السبب 1: إعدادات الخصوصية (الأكثر شيوعاً)\nقام المستخدم بضبط \"صورة الملف الشخصي\" على **\"جهات اتصالي\"** أو **\"لا أحد\"**.\n*   إذا لم تكن مسجلاً في دفتر عناوين هواتفهم، فلن تظهر لك الصورة. لا يوجد حل بديل، يجب احترام اختيار المستخدم.\n\n### السبب 2: لا توجد صورة\nالمستخدم لم يقم ببساطة بوضع صورة شخصية.\n\n---\n\n## 🔄 التخزين المؤقت والتحديث\n\nعمليات الجلب مكلفة برمجياً.\n*   **السلوك الافتراضي**: تقوم الواجهة بتخزين رابط الصورة مؤقتاً لمدة 24 ساعة لتسريع الطلبات اللاحقة.\n*   **فرض التحديث**: إذا شككت في أن المستخدم غير صورته للتو، مرر `refresh=true` لتجاوز الذاكرة المؤقتة.\n\n---\n\n## 📸 الدقة والجودة\n\n*   **المعيار**: تحاول الواجهة جلب حجم \"المعاينة\" (حوالي 96x96 أو 640x640 حسب التوفر).\n*   **المجمواعات**: تعمل أيقونات المجموعات بنفس الطريقة؛ المعرف سيكون `123456@g.us`.\n            "
        }
      }
    },
    {
      "path": "/v2/contacts/{chatId}",
      "methods": [
        "PUT"
      ],
      "title": "Create/Update Contact",
      "category": "Contacts",
      "description": "Create or update a contact in the phone's address book.",
      "extraInfo": "\n# Managing Your Digital Rolodex\n\nThe `/v2/contacts/update` endpoint allows you to modify the **local** name of a contact in your WhatsApp address book.\n\n---\n\n## 📖 The Name Game: Private vs Public\n\nIt is vital to distinguish between the two types of names in WhatsApp.\n\n### 1. `pushname` (Public)\n*   **What**: The name Alice chose for herself (\"Alice 🌸\").\n*   **Editable**: **NO**. You cannot change this. Only Alice can.\n\n### 2. `name` (Private)\n*   **What**: The name *you* saved Alice as in your phone (\"Alice from Accounting\").\n*   **Editable**: **YES**. This endpoint changes this value.\n*   **Visibility**: Only *you* (the bot owner) see this. Alice does not know you saved her as \"Alice from Accounting\".\n\n---\n\n## 🛠️ Use Cases\n\n### 1. CRM Synchronization\nIf you have a CRM like Salesforce, you want your WhatsApp chat list to reflect your CRM data.\n*   **Scenario**: A new lead messages you. Their pushname is \"User123\".\n*   **Action**: Your agent asks for their name. They say \"Bob Smith\".\n*   **API Call**: Update contact `123@c.us` with `firstName: \"Bob\", lastName: \"Smith\"`.\n*   **Result**: In your chat list, they now appear as \"Bob Smith\".\n\n### 2. Funnel Tracking\nYou can append tags to names to visualize where a user is in your funnel.\n*   **Example**: \"Bob [Lead]\" -> \"Bob [Customer]\" -> \"Bob [VIP]\".\n*   **Benefit**: Agents can instantly see the user's status just by looking at the chat header.\n\n---\n\n## 🏗️ Technical Nuances\n\n### The Virtual Address Book\nSince Wawp is a cloud-based system, we emulate the behavior of a mobile OS address book.\n*   **Persistence**: Updates are stored in the session's internal database.\n*   **Sync**: If you are using a multi-device session, this change *might* sync to your physical phone (if connected), but it is primarily for the API session's context.\n\n### \"Creating\" a Contact\nThis endpoint is idempotent.\n*   **If the contact exists**: It updates the name.\n*   **If the contact is new**: It \"adds\" them to your address book. This resolves the `name: null` issue when fetching contact details later.\n\n---\n\n## ❓ FAQ\n\n**Q: Will the user see the name I gave them?**\nA: **No.** This is private data on your end.\n\n**Q: Can I update the profile picture too?**\nA: **No.** You cannot change another user's photo.\n\n**Q: What if I only provide a firstName?**\nA: The API will set the full name to just the `firstName`.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Local Sync",
          "content": "Updates the contact name in the phone's address book."
        },
        {
          "type": "warning",
          "title": "Permissions",
          "content": "Requires 'Write Contacts' permission on the host device."
        }
      ],
      "recommendations": [
        "Keep the contact name aligned with your CRM's customer name.",
        "Use formatted names (e.g., 'Alice - Support') for clarity."
      ],
      "args": {
        "chatId": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the contact",
          "example": "123456789@c.us"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "firstName": {
          "required": false,
          "type": "string",
          "description": "First name of the contact",
          "example": "John"
        },
        "lastName": {
          "required": false,
          "type": "string",
          "description": "Last name of the contact",
          "example": "Doe"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Contact updated successfully",
          "example": {
            "ok": true
          }
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Parameter Format",
          "contentType": "application/json",
          "example": {
            "code": "invalid_param",
            "message": "Invalid format for one or more parameters.",
            "details": {
              "param": "text",
              "value": "too_long",
              "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "إنشاء/تحديث جهة اتصال",
          "description": "إنشاء أو تحديث جهة اتصال في دفتر عناوين الهاتف.",
          "tips": [
            {
              "title": "مزامنة محلية",
              "content": "يقوم بتحديث اسم جهة الاتصال في دفتر عناوين الهاتف."
            },
            {
              "title": "الأذونات",
              "content": "يتطلب إذن 'كتابة جهات الاتصال' على الجهاز المضيف."
            }
          ],
          "recommendations": [
            "ابقِ اسم جهة الاتصال متوافقًا مع اسم العميل في نظام إدارة علاقات العملاء (CRM).",
            "استخدم أسماء منسقة (مثل 'أليس - دعم') للوضوح."
          ],
          "args": {
            "chatId": {
              "description": "المعرف الفريد لجهة الاتصال"
            },
            "firstName": {
              "description": "الاسم الأول لجهة الاتصال"
            },
            "lastName": {
              "description": "اسم العائلة لجهة الاتصال"
            }
          },
          "extraInfo": "\n# إدارة دفتر العناوين الرقمي\n\nتسمح لك نقطة النهاية `/v2/contacts/update` بتعديل الاسم **المحلي** لجهة اتصال في دفتر عناوين واتساب الخاص بك.\n\n---\n\n## 📖 لعبة الأسماء: الخاص مقابل العام\n\nمن الضروري التمييز بين نوعي الأسماء في واتساب:\n\n### 1. `pushname` (عام)\n*   **ما هو**: الاسم الذي اختاره المستخدم لنفسه (مثلاً \"أحمد 🌸\").\n*   **قابل للتعديل**: **لا**. لا يمكنك تغيير هذا، أحمد فقط من يمكنه ذلك.\n\n### 2. `name` (خاص)\n*   **ما هو**: الاسم الذي حفظت به أحمد في هاتفك (مثلاً \"أحمد - المحاسب\").\n*   **قابل للتعديل**: **نعم**. هذه الواجهة تقوم بتعديل هذه القيمة.\n*   **الظهور**: أنت فقط (صاحب البوت) من يرى هذا الاسم. أحمد لا يعرف أنك حفظته باسم \"أحمد - المحاسب\".\n\n---\n\n## 🛠️ حالات الاستخدام\n\n### 1. مزامنة CRM\nإذا كان لديك نظام CRM، فأنت تريد أن تعكس قائمة دردشات واتساب بياناتك.\n*   **مثال**: عميل جديد يراسلك، اسمه العام \"User123\". يخبر الموظف أن اسمه \"خالد علي\".\n*   **الإجراء**: قم بتحديث جهة الاتصال بالاسم الحقيقي، ليظهر في قائمة الدردشة لديك باسم \"خالد علي\".\n\n### 2. تتبع مراحل البيع\nيمكنك إضافة وسوم للأسماء لتعرف مكان المستخدم في قمع المبيعات.\n*   **مثال**: \"علي [مهتم]\" -> \"علي [عميل]\" -> \"علي [VIP]\".\n\n---\n\n## 🏗️ تفاصيل تقنية\n\n### دفتر العناوين الافتراضي\nبما أن Wawp نظام سحابي، فنحن نحاكي سلوك دفتر عناوين الهاتف.\n*   **الاستمرارية**: يتم تخزين التحديثات في قاعدة البيانات الداخلية للجلسة.\n*   **المزامنة**: إذا كنت تستخدم جلسة متعددة الأجهزة، فقد يظهر هذا التغيير على هاتفك الفعلي، ولكنه مخصص أساساً لسياق جلسة الواجهة.\n\n---\n\n## ❓ الأسئلة الشائعة\n\n**س: هل سيرى المستخدم الاسم الذي وضعته له؟**\nأ: **لا.** هذه بيانات خاصة بك فقط.\n\n**س: هل يمكنني تحديث صورة الملف الشخصي أيضاً؟**\nأ: **لا.** لا يمكنك تغيير صورة مستخدم آخر.\n            "
        }
      }
    },
    {
      "path": "/v2/lids",
      "methods": [
        "GET"
      ],
      "title": "Get LIDs Mapping",
      "category": "Contacts",
      "description": "Retrieves all known LID to phone number mappings.",
      "extraInfo": "\n# The Future of Identity: Lookup IDs (LID)\n\nThe `/v2/lids` endpoint exposes the mapping layer between the old world (Phone Numbers) and the new world (Privacy-Preserving IDs).\n\n---\n\n## 🆔 What is an LID?\n\nLID stands for **Lookup ID**.\n*   **Format**: `123456789012345@lid` (A long integer + @lid suffix).\n*   **Purpose**: To allow users to interact **without revealing their phone number**.\n\n### The Shift\n*   **Classic WhatsApp**: Your ID is your phone number (`1555...@c.us`). To talk to you, I need your number.\n*   **Modern WhatsApp**: You might have a username, or you might be in a \"Community\" where your number is hidden. In these cases, WhatsApp uses your **LID** to route messages.\n\n---\n\n## 🗺️ The Mapping Problem\n\nIf a user messages you from a hidden-number community, you will receive a message from `@lid`.\n*   **Challenge**: Your CRM expects a phone number.\n*   **Solution**: You need a translation layer.\n    *   `@lid` -> `@c.us` (If you are authorized to see it).\n    *   `@c.us` -> `@lid` (To find their stable ID).\n\nThis endpoint dumps the entire known cache of these mappings.\n\n---\n\n## 🛡️ Privacy Constraints\n\nYou cannot just \"reverse lookup\" any LID to get a phone number.\n*   **Authorization**: You can only resolve an LID to a phone number if the user has **shared their number with you** or if you are in a specific trust relationship (e.g., mutual contact).\n*   **Community Members**: If you are in a Community Announcement Group, you might see 5,000 members, but their IDs will be LIDs. You **cannot** get their phone numbers via API. This is intentional privacy design by Meta.\n\n---\n\n## 🚀 Use Cases for LIDs\n\n### 1. Stable Identity\n*   **Scenario**: User changes their phone number from `+1...` to `+44...`.\n*   **Old Way**: New JID. New Chat. History lost.\n*   **New Way**: Their `@lid` remains the same. You can link the new phone number to the old account record in your database using the LID as the primary key.\n\n### 2. Hidden Group Participants\n*   **Scenario**: You scrape a group's participant list.\n*   **Result**: You see a mix of `@c.us` (people who don't hide their number) and `@lid` (people who do).\n*   **Action**: Use this endpoint to see if you have the phone number cached for any of those LIDs.\n\n---\n\n## 🚦 Performance\n\n*   **Cache Size**: This list can grow large.\n*   **Pagination**: Always use `limit` and `offset`.\n*   **Refresh**: The mapping is static unless a user re-registers directly.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Dump",
          "content": "Returns all LID mappings stored on the device."
        },
        {
          "type": "warning",
          "title": "Size",
          "content": "Payload can be large. Parse efficiently."
        }
      ],
      "recommendations": [
        "Run this periodically to ensure your ID map is consistent.",
        "Use background workers to process the list."
      ],
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "limit": {
          "required": false,
          "type": "string",
          "description": "Maximum number of mappings to return",
          "example": "100"
        },
        "offset": {
          "required": false,
          "type": "string",
          "description": "Number of mappings to skip",
          "example": "0"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "LIDs mapped successfully",
          "example": [
            {
              "lid": "1234567890@lid",
              "number": "1234567890"
            }
          ]
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Parameter Format",
          "contentType": "application/json",
          "example": {
            "code": "invalid_param",
            "message": "Invalid format for one or more parameters.",
            "details": {
              "param": "text",
              "value": "too_long",
              "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "جلب خريطة LIDs",
          "description": "يسترجع جميع خرائط LID لأرقام الهاتف المعروفة.",
          "tips": [
            {
              "title": "تفريغ",
              "content": "يعيد جميع تعيينات LID المخزنة على الجهاز."
            },
            {
              "title": "الحجم",
              "content": "يمكن أن تكون الحمولة كبيرة. قم بالتحليل بكفاءة."
            }
          ],
          "recommendations": [
            "قم تشغيل هذا بشكل دوري للتأكد من أن خريطة الهوية الخاصة بك متسقة.",
            "استخدم عمال الخلفية لمعالجة القائمة."
          ],
          "args": {
            "limit": {
              "description": "أقصى عدد من الخرائط للإرجاع"
            },
            "offset": {
              "description": "عدد الخرائط التي سيتم تخطيها"
            }
          },
          "extraInfo": "\n# مستقبل الهوية: معرفات البحث (LID)\n\nتكشف نقطة النهاية `/v2/lids` عن طبقة الربط بين العالم القديم (أرقام الهواتف) والعالم الجديد (المعرفات التي تحافظ على الخصوصية).\n\n---\n\n## 🆔 ما هو الـ LID؟\n\nLID هو اختصار لـ **Lookup ID** (معرف البحث).\n*   **الصيغة**: `123456789012345@lid` (رقم طويل + لاحقة @lid).\n*   **الغرض**: السماح للمستخدمين بالتفاعل **دون الكشف عن أرقام هواتفهم**.\n\n### التحول التقني\n*   **واتساب الكلاسيكي**: هويتك هي رقم هاتفك (`1555...@c.us`). للتحدث معك، أحتاج لرقمك.\n*   **واتساب الحديث**: قد يكون لديك اسم مستخدم، أو قد تكون في \"مجتمع\" حيث رقمك مخفي. في هذه الحالات، يستخدم واتساب الـ **LID** لتوجيه الرسائل.\n\n---\n\n## 🛡️ قيود الخصوصية\n\nلا يمكنك ببساطة إجراء \"بحث عكسي\" لأي LID للحصول على رقم هاتف.\n*   **التفويض**: يمكنك فقط تحويل LID إلى رقم هاتف إذا كان المستخدم قد **شارك رقمه معك** أو إذا كانت هناك علاقة ثقة مسبقة (مثل جهة اتصال متبادلة).\n*   **أعضاء المجتمعات**: إذا كنت في مجموعة إعلان مجتمعي، فقد ترى 5000 عضو، لكن هوياتهم ستكون LIDs. **لا يمكنك** الحصول على أرقام هواتفهم عبر الواجهة؛ هذا تصميم مقصود للخصوصية من Meta.\n\n---\n\n## 🚀 حالات الاستخدام\n\n### 1. الهوية المستقرة\nإذا قام المستخدم بتغيير رقم هاتفه من رقم أمريكي إلى رقم بريطاني، فإن هويته (`@c.us`) ستتغير، لكن الـ `@lid` الخاص به يظل كما هو. يمكنك استخدام الـ LID كتمثيل دائم للمستخدم في قاعدة بياناتك.\n\n### 2. المشاركون المخفيون\nعند سحب قائمة المشاركين في مجموعة، ستجد مزيجاً من أرقام الهواتف والـ LIDs. استخدم هذه الواجهة لمعرفة ما إذا كان رقم الهاتف مخزناً لديك مسبقاً لأي من تلك المعرفات.\n            "
        }
      }
    },
    {
      "path": "/v2/lids/pn/{number}",
      "methods": [
        "GET"
      ],
      "title": "Get LID by Phone",
      "category": "Contacts",
      "description": "Convert a phone number to its corresponding WhatsApp LID.",
      "extraInfo": "\n# The Stable Anchor: Phone to LID\n\nThe `/v2/lids/pn/{number}` endpoint performs a forward lookup, converting a traditional phone number into its corresponding privacy-preserving Lookup ID (LID).\n\n---\n\n## 🔮 Why This Matters\n\nIn the modern WhatsApp ecosystem, phone numbers are ephemeral but identities should be persistent.\n*   **The Problem**: A user changes their number from `+1-555-1234` to `+44-7700-900000`.\n*   **Old System**: You lose track of them. Their chat history is orphaned.\n*   **New System**: You query their LID using the old number, store it, then when they message you from the new number, you query the LID again and realize it's the same person.\n\n---\n\n## 🛠️ Implementation Pattern\n\n### The \"Identity Merge\" Workflow\n1.  **User A** messages you from `15551234567@c.us`.\n2.  You call `/v2/lids/pn/15551234567`.\n3.  Response: `{ lid: \"999888777@lid\", number: \"15551234567\" }`.\n4.  You store in DB: `user_id = 999888777@lid, current_phone = 15551234567`.\n5.  **6 months later**: User A changes their number to `447700900000`.\n6.  They message you again from `447700900000@c.us`.\n7.  You call `/v2/lids/pn/447700900000`.\n8.  Response: `{ lid: \"999888777@lid\", number: \"447700900000\" }`.\n9.  **Match Found**: The LID is the same! You update `current_phone` but keep the same `user_id`.\n10. **Result**: Chat history, preferences, and purchase records are preserved.\n\n---\n\n## ⚠️ Availability\n\nNot every phone number has an LID.\n*   **Modern Accounts**: Created after 2023 usually have LIDs.\n*   **Legacy Accounts**: Very old accounts might return `null`.\n*   **Best Practice**: Always handle the case where this endpoint returns no LID. Fall back to using the `@c.us` JID as the primary key if necessary.\n\n---\n\n## 🚦 Performance\n\n*   **Caching**: The mapping is relatively stable. Cache the result for at least 7 days.\n*   **Latency**: ~100-300ms for a fresh lookup.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Resolution",
          "content": "Resolves a Phone Number to its corresponding LID."
        },
        {
          "type": "warning",
          "title": "Availability",
          "content": "Not all accounts have LIDs yet; depends on rollout phase."
        }
      ],
      "recommendations": [
        "Call this when onboarding a new contact to complete your database record.",
        "Gracefully handle cases where no LID is returned."
      ],
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "number": {
          "required": true,
          "type": "string",
          "description": "The phone number without @c.us (e.g. 447441429009)",
          "example": "447441429009"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "LID found",
          "example": {
            "lid": "1234567890@lid",
            "number": "447441429009"
          }
        },
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "جلب الـ LID عبر الهاتف",
          "description": "تحويل رقم هاتف إلى معرف البحث (LID) المقابل له على واتساب.",
          "tips": [
            {
              "title": "الحل",
              "content": "يحل رقم هاتف إلى معرف LID المقابل له."
            },
            {
              "title": "التوفر",
              "content": "ليس كل الحسابات لديها LIDs بعد؛ يعتمد على مرحلة الطرح."
            }
          ],
          "recommendations": [
            "اتصل بهذا عند إعداد جهة اتصال جديدة لإكمال سجل قاعدة البيانات الخاصة بك.",
            "تعامل بملطف مع الحالات التي لا يتم فيها إرجاع أي LID."
          ],
          "args": {
            "number": {
              "description": "رقم الهاتف بدون @c.us (مثال: 447441429009)"
            }
          },
          "extraInfo": "\n# المرساة المستقرة: من الهاتف إلى LID\n\nتجري نقطة النهاية `/v2/lids/pn/{number}` بحثاً أمامياً، لتحويل رقم هاتف تقليدي إلى معرف البحث المقابل له (LID) الذي يحافظ على الخصوصية.\n\n---\n\n## 🔮 لماذا يهم هذا؟\n\nفي نظام واتساب الحديث، أرقام الهواتف مؤقتة ولكن الهويات يجب أن تكون مستمرة.\n*   **المشكلة**: يغير المستخدم رقمه من رقم أمريكي إلى رقم بريطاني.\n*   **النظام القديم**: تفقد تتبعه، وتصبح سجلات الدردشة الخاصة به معزولة.\n*   **النظام الجديد**: تستعلم عن الـ LID الخاص به باستخدام الرقم القديم وتخزنه. عندما يراسلك من الرقم الجديد، تستعلم عن الـ LID مرة أخرى وتكتشف أنه نفس الشخص!\n\n---\n\n## 🛠️ نمط التنفيذ: سير عمل \"دمج الهوية\"\n\n1.  يراسلك **المستخدم أ** من الرقم `15551234567@c.us`.\n2.  تستدعي `/v2/lids/pn/15551234567`.\n3.  تحصل على الـ LID: `999888777@lid`.\n4.  تخزن في قاعدة بياناتك: `user_id = 999888777@lid`.\n5.  **بعد 6 أشهر**: يغير المستخدم رقمه ويوجه لك رسالة من الرقم الجديد.\n6.  تستعلم عن الـ LID للرقم الجديد فتجده هو نفسه `999888777@lid`.\n7.  **تم التطابق**: الـ LID هو نفسه! يمكنك الحفاظ على جيس سجل الدردشة والتفضيلات وسجلات الشراء.\n\n---\n\n## ⚠️ التوفر\n\nليس لكل رقم هاتف LID. الحسابات الحديثة (بعد 2023) تمتلك LIDs غالباً، أما الحسابات القديمة جداً فقد تعيد `null`. تعامل مع هذه الحالة باستخدام الـ JID التقليدي (`@c.us`) كمفتاح أساسي إذا لزم الأمر.\n            "
        }
      }
    },
    {
      "path": "/v2/lids/{lid}",
      "methods": [
        "GET"
      ],
      "title": "Get Phone by LID",
      "category": "Contacts",
      "description": "Convert a WhatsApp LID to its corresponding phone number.",
      "extraInfo": "\n# Unmasking the Identity: LID to Phone\n\nThe `/v2/lids/{lid}` endpoint performs a reverse lookup, attempting to find the canonical phone number (`@c.us`) associated with a given Lookup ID.\n\n---\n\n## 🔒 Privacy Barriers\n\nA common misconception is that this endpoint can \"dox\" any user. **It cannot.**\n*   **Success**: The API returns the phone number *only if* your account has **already established a trust relationship** with that user (e.g., they are in your contacts, or you share a group where numbers are visible).\n*   **Failure**: If the user is a stranger in a hidden community, this endpoint will likely return `null` or the same LID, because the phone number is cryptographically sealed from your view.\n\n---\n\n## 🛠️ Use Case: \"One Identity\"\n\nIf you support users moving across phone numbers:\n1.  **Storage**: You store the LID as the user's primary key.\n2.  **Display**: When you need to send an SMS fallback, you call this endpoint.\n3.  **Result**: You get the *current* phone number associated with that LID, ensuring your SMS goes to the right device.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Architecture",
          "content": "LID (Ledger ID) is a privacy-preserving identifier."
        },
        {
          "type": "info",
          "title": "Usage",
          "content": "Required for some advanced features like username lookup."
        }
      ],
      "recommendations": [
        "Store mapping of LID to Phone Number (PN) securely.",
        "Use LIDs internally if you plan to support PNH (Phone Number Hiding)."
      ],
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "lid": {
          "required": true,
          "type": "string",
          "description": "The unique LID (@lid)",
          "example": "1234567890@lid"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Phone number found",
          "example": {
            "lid": "1234567890@lid",
            "number": "447441429009"
          }
        },
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "جلب الهاتف عبر الـ LID",
          "description": "تحويل معرف بحث (LID) على واتساب إلى رقم الهاتف المقابل له.",
          "tips": [
            {
              "title": "البنية",
              "content": "معرف السجل (LID) هو معرف يحافظ على الخصوصية."
            },
            {
              "title": "الاستخدام",
              "content": "مطلوب لبعض الميزات المتقدمة مثل البحث عن اسم المستخدم."
            }
          ],
          "recommendations": [
            "قم بتخزين تعيين معرف LID إلى رقم الهاتف (PN) بشكل آمن.",
            "استخدم LIDs داخليًا إذا كنت تخطط لدعم PNH (إخفاء رقم الهاتف)."
          ],
          "args": {
            "lid": {
              "description": "معرف البحث الفريد (@lid)"
            }
          },
          "extraInfo": "\n# كشف الهوية: من LID إلى هاتف\n\nتجري نقطة النهاية `/v2/lids/{lid}` بحثاً عكسياً، محاولةً العثور على رقم الهاتف الأساسي (`@c.us`) المرتبط بمعرف بحث معين.\n\n---\n\n## 🔒 حواجز الخصوصية\n\nهناك اعتقاد خاطئ بأن هذه الواجهة يمكنها \"كشف\" أي مستخدم. **لا يمكنها ذلك.**\n*   **النجاح**: تعيد الواجهة رقم الهاتف *فقط إذا* كان حسابك قد **أنشأ بالفعل علاقة ثقة** مع ذلك المستخدم (مثلاً: هم في جهات اتصالك، أو تشتركان في مجموعة تكون فيها الأرقام مرئية).\n*   **الفشل**: إذا كان المستخدم غريباً في مجتمع مخفي، فستعود هذه الواجهة غالباً بـ `null` أو نفس الـ LID، لأن رقم الهاتف مغلق تشفيرياً عن رؤيتك.\n\n---\n\n## 🛠️ حالة استخدام: \"هوية واحدة\"\n\nإذا كنت تدعم المستخدمين الذين ينتقلون عبر أرقام هواتف مختلفة:\n1.  **التخزين**: قمت بتخزين الـ LID كمفتاح أساسي للمستخدم.\n2.  **العرض**: عندما تحتاج لإرسال رسالة SMS كبديل، تستدعي هذه الواجهة.\n3.  **النتيجة**: تحصل على رقم الهاتف *الحالي* المرتبط بذلك الـ LID، مما يضمن وصول رسالتك للجهاز الصحيح.\n            "
        }
      }
    },
    {
      "path": "/v2/lids/count",
      "methods": [
        "GET"
      ],
      "title": "Get LIDs Count",
      "category": "Contacts",
      "description": "Returns the number of known LIDs.",
      "extraInfo": "\n# Measuring Your Identity Graph: LID Count\n\nThe `/v2/lids/count` endpoint returns a simple integer: the total number of LID-to-Phone mappings your session has cached.\n\n---\n\n## 📊 What This Number Means\n\nThis is **not** the number of contacts you have. It is the number of **privacy-aware identities** your bot has encountered.\n\n### Interpretation\n*   **Count = 0**: Your account is very new or you only interact with legacy users.\n*   **Count = 50**: You have interacted with 50 users who have modern WhatsApp accounts with LIDs.\n*   **Count = 10,000**: You run a large-scale bot that has processed thousands of unique users.\n\n---\n\n## 🛠️ Use Cases\n\n### 1. Pagination Planning\nBefore calling `/v2/lids` to fetch the full list, check the count.\n*   If `count < 100`: Fetch everything in one call.\n*   If `count > 10,000`: Use aggressive pagination (`limit=1000, offset=0...10000`).\n\n### 2. Analytics Dashboard\nDisplay this metric to your operations team.\n*   **Metric**: \"Unique Privacy-Aware Users\".\n*   **Trend**: If this number grows faster than your total contact count, it means more users are adopting WhatsApp's privacy features.\n\n### 3. Cache Warming\nIf you are migrating to a new server, you can use this count to estimate how long it will take to rebuild your LID cache.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Stats",
          "content": "Returns the number of LID-based contacts known to the device."
        },
        {
          "type": "positive",
          "title": "Health",
          "content": "Zero count might indicate LIDs are not enabled for this session."
        }
      ],
      "recommendations": [
        "Use this for debugging synchronization issues.",
        "Monitor this count to track migration to the new architecture."
      ],
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Success",
          "example": {
            "count": 42
          }
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "جلب عدد الـ LIDs",
          "description": "يعيد عدد معرفات البحث (LIDs) المعروفة.",
          "extraInfo": "\n# قياس رسم الهوية البياني: عدد الـ LID\n\nتعيد نقطة النهاية `/v2/lids/count` رقماً صحيحاً بسيطاً: إجمالي عدد خرائط \"LID إلى هاتف\" المخزنة في جلستك.\n\n---\n\n## 📊 ماذا يعني هذا الرقم؟\n\nهذا **ليس** عدد جهات الاتصال لديك، بل هو عدد **الهويات الواعية بالخصوصية** التي واجهها البوت الخاص بك.\n\n### التفسير\n*   **العدد = 0**: حسابك جديد جداً أو أنك تتفاعل فقط مع مستخدمين قدامى.\n*   **العدد = 50**: لقد تفاعلت مع 50 مستخدماً لديهم حسابات واتساب حديثة تدعم الـ LID.\n\n---\n\n## 🛠️ حالات الاستخدام\n\n### 1. تخطيط التقسيم (Pagination)\nقبل استدعاء `/v2/lids` لجلب القائمة الكاملة، تحقق من العدد. إذا كان كبيراً جداً (أكثر من 10,000)، استخدم التقسيم بشكل مكثف.\n\n### 2. لوحة تحكم التحليلات\nاعرض هذا المقياس لفريق العمليات كـ \"مستخدمين فريدين واعين بالخصوصية\". إذا كان هذا الرقم ينمو أسرع من إجمالي جهات الاتصال، فهذا يعني أن المزيد من المستخدمين يعتمدون ميزات خصوصية واتساب.\n            "
        }
      }
    },
    {
      "path": "/v2/labels-guide",
      "methods": [
        "GET"
      ],
      "title": "Labels API Guide",
      "category": "Labels",
      "isArticle": true,
      "description": "Comprehensive guide to mastering WhatsApp Labels for organizational excellence and automation.",
      "extraInfo": "\n# Mastering the Taxonomy of Engagement: The WhatsApp Labels Ecosystem\n\nIn the high-speed world of digital commerce, information overload is the primary silent killer of conversion. WhatsApp Labels are not merely \"tags\"; they represent the high-performance organizational layer of the WhatsApp Business ecosystem. By centralizing metadata directly onto the conversational thread, Wawp’s Labels API transforms raw chat logs into a structured, actionable CRM pipeline. This guide provides an architectural deep-dive into how to leverage labels to build resilient, automated, and hyper-organized customer journeys.\n\n![WhatsApp Labels Guide](https://api.apidog.com/api/v1/projects/1017306/resources/362672/image-preview)\n\n---\n\n## 🏗️ Architectural Philosophy: Metadata at the Edge\n\nA **Label** is a colored, action-oriented tag attached to a chat (individual or group). Unlike \"Folders\" in traditional email, which move content out of sight, Labels are **non-destructive metadata**. They exist alongside the message stream, providing instant visual and programmatic context without altering the underlying data structure.\n\n### The Strategic Value Proposition\n1. **Visual Triage**: Agents can instantly identify \"VIP\" or \"Urgent\" cases via the sidebar in the WhatsApp Business app.\n2. **State Management**: Labels act as the \"Current State\" in your sales funnel (e.g., *Lead* → *Proposal* → *Closed*).\n3. **Automated Routing**: Use Webhooks to trigger external system actions when a label is applied (e.g., Applying \"Support\" triggers a Zendesk ticket).\n4. **Retention Analytics**: Track the velocity of chats moving between labels to measure your team's efficiency.\n\n---\n\n## 🎨 The 20-Color Ecosystem: Semantic Consistency\n\nWhatsApp provides a strictly defined palette of **20 predefined colors** (indexed 0-19). While these colors have default hex codes, the Wawp platform abstracts these into a robust numbering system. \n\n> [!IMPORTANT]\n> **Engineering Tip**: Always program your logic around the **Color Index (0-19)** rather than the Hex Code. Meta reserves the right to adjust hex shades between versions, but the index mapping remains the immutable source of truth.\n\n### Current Color Map & Suggested Taxonomy\n\n| Index | Color Preview | Standard Hex | Recommended Strategic Use Case |\n| :--- | :--- | :--- | :--- |\n| **0** | 🔴 Red | `#ff9485` | **Critical/Urgent**: SLAs near breach, payment failure, high-risk churn. |\n| **1** | 🔵 Light Blue | `#64c4ff` | **New Pipeline**: Inbound leads, first-time inquiries, cold outreach. |\n| **2** | 🟡 Yellow | `#ffd429` | **Pending External**: Waiting for customer reply, pending document upload. |\n| **3** | 💜 Purple | `#dfaef0` | **Soft Priority**: Information requests, non-commercial technical queries. |\n| **4** | ⚪ Grey | `#99b6c1` | **Archive/Quiet**: Completed inquiries, newsletter sub-only, low priority. |\n| **5** | 🟢 Teal | `#55ccb3` | **Financial**: Invoice generated, quoting phase, billing clarification. |\n| **6** | 🌸 Pink | `#ff9dff` | **Marketing**: Campaign participants, discount seekers, seasonal leads. |\n| **7** | 🏅 Brown | `#d3a91d` | **High Value**: VIP customers, wholesale accounts, repeat buyers. |\n| **8** | 🟣 Dark Purple | `#6d7cce` | **Internal Routing**: Assigned to Team A, awaiting supervisor review. |\n| **9** | ✅ Lime | `#d7e752` | **Success**: Order confirmed, onboarding complete, issue resolved. |\n| **10** | 🛠️ Cyan | `#00d0e2` | **Technical Support**: Bug reported, feature request, dev-team needed. |\n| **11** | 💌 Peach | `#ffc5c7` | **Personalized**: Birthday greetings sent, loyalty program member. |\n| **12** | 🌱 Sage | `#93ceac` | **Retention**: Re-engagement campaign, feedback loop initiated. |\n| **13** | 🚨 Dark Red | `#f74848` | **Escalation**: Manager intervention required, threat of legal action. |\n| **14** | 📘 Sky Blue | `#00a0f2` | **Active Flow**: Mid-conversation, actively being handled by an agent. |\n| **15** | ✔️ Bright Green | `#83e422` | **Verification**: KYC passed, identity verified, secure link clicked. |\n| **16** | ⏰ Orange | `#ffaf04` | **Follow-up**: Promised a callback, scheduled check-in for next week. |\n| **17** | 🧊 Ice Blue | `#b5ebff` | **Nurturing**: Drip campaign stage, educational content delivery. |\n| **18** | 🔮 Lavender | `#9ba6ff` | **Misc/Tagging**: Temporary metadata, experimental categories. |\n| **19** | 🗂️ Deep Grape | `#9368cf` | **General Category**: Catch-all for undefined business categories. |\n\n---\n\n## 🔄 The Lifecycle of a Label: A Developer’s Workflow\n\nTo build a truly automated organizational system, you must master the four pillars of the Labels API:\n\n### 1. Provisioning the Workspace ([Create Label](/v2/labels/create))\nBefore you can tag a chat, the label must exist in the account’s directory. We recommend an **Idempotent Bootstrapping Pattern**: On application startup, fetch existing labels via [`GET /v2/labels`](/v2/labels), compare against your required taxonomy, and create missing entries.\n\n### 2. Strategic Attachment ([Link to Chat](/v2/labels/{id}/chats/{chatId}))\nThe power of Wawp lies in **Multi-Labeling**. A single chat can simultaneously be \"VIP\" (Index 7), \"Payment Pending\" (Index 2), and \"Assigned to Bob\" (Index 8). Use the `PUT` endpoint to link labels. Note that this operation is additive—it does not remove existing labels.\n\n### 3. State Transitions ([Remove from Chat](/v2/labels/{id}/chats/{chatId}))\nWhen a customer moves from \"Pending\" to \"Completed,\" orphans of old metadata can confuse agents. Part of a clean automation workflow is explicitly calling the `DELETE` link endpoint to prune old states as the user progresses through your CRM.\n\n### 4. Discovery and Sync ([Get Labels](/v2/labels))\nRegularly sync your internal CRM tags with Wawp to ensure the visual state in the WhatsApp app matches your backend records exactly. Listen for [`label.upsert`](/v2/webhooks/label-upsert) webhooks to capture manual changes made by agents in the WhatsApp app.\n\n---\n\n## 📡 Advanced Automation: Event-Driven Organization\n\nThe true ROI of labeling is found in **Event-Based Tagging**. You should never rely solely on agents to tag chats.\n\n### Scenario: The AI-Driven Funnel\n1. **Ingest**: A message arrives. Your LLM detects \"refund\" intent.\n2. **Action**: Automatically [`Link Label`](/v2/labels/{id}/chats/{chatId}) \"Critical\" (Index 0).\n3. **Notify**: Your backend sees the [`label.chat.added`](/v2/webhooks/label-chat-added) event and pushes a high-priority Slack alert to the head of support.\n4. **Resolution**: Once the refund is processed, the system [`Removes Label`](/v2/labels/{id}/chats/{chatId}) \"Critical\" and adds \"Success\" (Index 9).\n\n### Scenario: High-Volume Retention\nUse the [`Get Chats by Label`](/v2/labels/chats) endpoint to identify \"stale\" leads. For example, fetch all chats tagged with \"Pending Follow-up\" (Index 16) where the last message was >48 hours ago, and trigger a proactive [`sendText`](/v2/send/text) re-engagement.\n\n---\n\n## 🛡️ Operational Safeguards & Constraints\n\nWhatsApp Business API imposes specific guardrails to maintain system performance:\n*   **Capacity**: Maximum of **20 labels** per account. Use them wisely by keeping them high-level.\n*   **Length**: Names should be kept under **25 characters**. Longer names may be truncated in the mobile UI.\n*   **Account Type**: Labels are strictly **WhatsApp Business** features. Personal accounts will return a `403 Forbidden` or `405 Method Not Allowed` when attempting label operations.\n*   **Idempotency**: Adding the same Label ID to the same Chat ID multiple times is safe and will not produce duplicate tags or errors.\n\n---\n\n## 🎯 Best Practices for Scale\n\n1.  **Semantic Naming**: Use action-oriented names. \"To Call\" is better than \"Phone\". \"Lead-Hot\" is better than \"Important\".\n2.  **Color Psychology**: Leverage the natural urgency of colors. Use Reds for problems, Greens for completions, and Blues for general information.\n3.  **Webhook Mastery**: Treat Labels as the \"Source of Truth\" for your UI. Instead of polling for state, update your dashboard when you receive a Label Webhook.\n4.  **Batch Cleanup**: Periodically fetch all labels and ensure your account hasn't hit the 20-label limit with \"zombie\" tags from old campaigns.\n\nBy treating Labels as the logical backbone of your communication strategy, you move beyond \"Chatting\" and start \"Orchestrating\" success.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Events",
          "content": "Listen for 'label.create' and 'label.delete' webhooks."
        },
        {
          "type": "positive",
          "title": "Real-time",
          "content": "Ensures your UI is always in sync with the mobile app."
        }
      ],
      "recommendations": [
        "Handle lifecycle events robustly to prevent ghost labels.",
        "Log all lifecycle changes for audit trails."
      ],
      "args": {},
      "translations": {
        "ar": {
          "title": "دليل واجهة برمجة تطبيقات التصنيفات (Labels)",
          "description": "دليل شامل لإتقان تصنيفات واتساب للتميز التنظيمي والأتمتة.",
          "extraInfo": "\n# إتقان تصنيف التفاعل: منظومة تصنيفات واتساب\n\nفي عالم التجارة الرقمية سريع الوتيرة، يعد تراكم المعلومات القاتل الصامت للتحويل. تصنيفات واتساب (Labels) ليست مجرد \"تاغات\"؛ إنها تمثل الطبقة التنظيمية عالية الأداء لمنظومة واتساب بيزنس.\n\n---\n\n## 🏗️ الفلسفة المعمارية: البيانات الوصفية في المقدمة\n\n**التصنيف** هو علامة ملونة موجهة نحو العمل مرتبطة بدردشة (فردية أو مجموعة).\n1. **الفرز البصري**: يمكن للوكلاء التعرف فورًا على الحالات \"المهمة\" أو \"العاجلة\".\n2. **إدارة الحالة**: تعمل التصنيفات كـ \"حالة حالية\" في قمع المبيعات الخاص بك (مثلاً: *عميل محتمل* ← *مرحلة العرض* ← *تم الإغلاق*).\n3. **التوجيه الآلي**: استخدم الويب هوك لإطلاق إجراءات في أنظمة خارجية عند تطبيق تصنيف معين.\n\n---\n\n## 🎨 منظومة الـ 20 لوناً: الاتساق الدلالي\n\nيوفر واتساب لوحة محددة بصرامة من **20 لونًا محددًا مسبقًا** (مفهرسة من 0 إلى 19).\n\n| الفهرس | اللون | الاستخدام الاستراتيجي الموصى به |\n| :--- | :--- | :--- |\n| **0** | 🔴 أحمر | **حرج/عاجل**: حالات خرق SLA، فشل الدفع، مخاطر عالية. |\n| **1** | 🔵 أزرق فاتح | **خط أنابيب جديد**: عملاء محتملون جدد، استفسارات لأول مرة. |\n| **2** | 🟡 أصفر | **انتظار طرف خارجي**: انتظار رد العميل، انتظار رفع المستندات. |\n| **5** | 🟢 تيل | **مالي**: تم إصدر فاتورة، مرحلة التسعير، توضيح الفواتير. |\n| **9** | ✅ أخضر ليموني | **نجاح**: تأكيد الطلب، اكتمال التهيئة، حل المشكلة. |\n| **13** | 🚨 أحمر غامق | **تصعيد**: تتطلب تدخل المدير، تهديد بإجراء قانوني. |\n\n---\n\n## 🛡️ الضمانات والقيود التشغيلية\n\n*   **السعة**: كحد أقصى **20 تصنيفاً** لكل حساب.\n*   **الطول**: يجب أن تظل الأسماء أقل من **25 حرفًا**.\n*   **نوع الحساب**: التصنيفات هي ميزة حصرية لحسابات **WhatsApp Business**. الحسابات الشخصية لن تدعم هذه العمليات.\n      ",
          "tips": [
            {
              "title": "الأحداث",
              "content": "استمع إلى خطافات 'label.create' و 'label.delete'."
            },
            {
              "title": "الوقت الحقيقي",
              "content": "يضمن أن واجهة المستخدم الخاصة بك متزامنة دائمًا مع تطبيق الهاتف المحمول."
            }
          ],
          "recommendations": [
            "تعامل مع أحداث دورة الحياة بقوة لمنع الملصقات الوهمية.",
            "سجل جميع تغييرات دورة الحياة لمسارات التدقيق."
          ]
        }
      }
    },
    {
      "path": "/v2/labels",
      "methods": [
        "GET"
      ],
      "title": "Get All Labels",
      "category": "Labels",
      "description": "Retrieve all WhatsApp labels available in your WhatsApp Business account.",
      "extraInfo": "\n# The Label Directory: Master Inventory Management\n\nThe **Get All Labels** endpoint acts as the central directory for your WhatsApp Business account's organizational metadata. It is the primary tool for auditing your existing taxonomy and synchronizing your external systems with the reality of your WhatsApp environment.\n\n---\n\n## 🏗️ Core Concept: The Source of Truth\n\nThis endpoint provides a snapshot of every label currently configured on your account. Because labels are global resources, this list is common across all agents and automated systems connected to your instance.\n\n### Key Data Architecture\nEach entry in the returned array represents a unique organizational category, defined by a persistent ID and a visual signature (Color Index). While name changes are frequent, the **ID** remains the immutable reference point for your database.\n\n---\n\n## 🚀 Strategic Operational Use Cases\n\n### 1. Global State Synchronization\nThe most common use for this endpoint is \"Directory Hydration.\" On system startup or agent login, your application should fetch the full directory to build a local map of names to IDs. This prevents your system from having to \"guess\" which ID corresponds to \"VIP\" or \"New Lead\" during high-volume operations.\n\n### 2. CRM Taxonomy Mapping\nIf you are integrating WhatsApp with an external CRM (like Salesforce, HubSpot, or a custom ERP), this endpoint allows you to run a \"Taxonomy Audit.\" By comparing your WhatsApp labels with your CRM tags, you can identify naming discrepancies or missing categories and programmatically reconcile them.\n\n### 3. Analytics & Resource Distribution\nBy combining this endpoint with [`Get Chats with Label`](/v2/labels/{id}/chats), you can generate a \"Volume Heatmap.\" This allows management to see exactly how many conversations are sitting in \"Pending\" versus \"In Progress,\" enabling better resource allocation across your agent pool.\n\n---\n\n## ⚡ Performance Engineering: Advanced Caching Strategies\n\nSince labels are established during account setup and rarely change in real-time, fetching the entire list for every message would be inefficient.\n\n### The \"Pulse & Probe\" Caching Pattern\nInstead of high-frequency polling, we recommend a \"Warm Cache\" approach:\n*   **Initial Fetch**: Pull all labels during the \"Warm-up\" phase of your worker or server.\n*   **In-Memory Store**: Keep these labels in a global object or a Redis store.\n*   **Invalidation Hooks**: Instead of a time-based TTL (Time to Live), use **Webhooks**. Your system should only invalidate the cache when it receives a [`label.upsert`](/v2/webhooks/label-upsert) or [`label.deleted`](/v2/webhooks/label-deleted) event. This ensures your data is always 100% current without redundant API overhead.\n\n---\n\n## 🛠️ Integration Patterns: UI & UX Excellence\n\n### Responsive Label Rendering\nWhen building a custom dashboard, use the data from this endpoint to pre-calculate your CSS variables. By mapping the **Color Index (0-19)** to your design system's theme, you ensure that the \"VIP\" badge in your CRM looks identical to the \"VIP\" badge in the official WhatsApp app, providing a seamless multi-channel experience for your agents.\n\n### The \"Smart Dropdown\" Experience\nDon't just show a list of names; use the color metadata to group labels logically in your UI. For example, placing all \"Red\" urgency labels at the top of a selection menu can significantly reduce agent response times during critical escalations.\n\n---\n\n## ⚠️ State Consistency & Error Resilience\n\n### Handling \"The Empty State\"\nIf this endpoint returns an empty array, it indicates a \"Clean Slate\" account. This is a critical trigger for your system to run its \"Bootstrapping\" logic—programmatically creating the default taxonomy (e.g., Marketing, Sales, Support) required for your business logic to function.\n\n### Handling \"The Deleted ID\"\nIf your local database still references a Label ID that no longer appears in this list, your system should proactively \"prune\" those references. Continuing to attempt tagging with a deleted ID will result in API errors and broken workflow automations.\n\n---\n\n## 🎯 Best Practices\n\n1.  **Audits Over Polling**: Run a full directory fetch periodically (e.g., once a day) to catch any manual changes made by agents in the WhatsApp mobile app.\n2.  **Case-Insensitive Searching**: When looking for a label by name in this list, always use case-insensitive matching to prevent duplicate creation errors.\n3.  **Fallback Logic**: If the API is temporarily unreachable, your system should fall back to its last known cached state rather than failing the entire request.\n4.  **Security Scoping**: Limit who can view this full directory in your own application, as label names can sometimes reveal sensitive internal project names or campaign strategies.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Catalog",
          "content": "Returns a list of all defined labels on the account."
        },
        {
          "type": "info",
          "title": "Sync",
          "content": "Use this on startup to build your local label map."
        }
      ],
      "recommendations": [
        "Poll this endpoint occasionally to detect labels created on the phone.",
        "Display available labels in a dropdown for your agents."
      ],
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "List of labels retrieved successfully",
          "example": [
            {
              "id": "1",
              "name": "New Customer",
              "color": 0,
              "colorHex": "#ff9485"
            },
            {
              "id": "2",
              "name": "Favorites",
              "color": 1,
              "colorHex": "#64c4ff"
            }
          ]
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "جلب جميع التصنيفات",
          "description": "استرجاع جميع تصنيفات واتساب المتاحة في حساب واتساب بيزنس الخاص بك.",
          "extraInfo": "\n# دليل التصنيفات: إدارة المخزون الرئيسي\n\nتعمل نقطة النهاية **جلب جميع التصنيفات** كدليل مركزي للبيانات الوصفية التنظيمية لحساب واتساب بيزنس الخاص بك. إنها الأداة الأساسية لتدقيق تصنيفك الحالي ومزامنة أنظمتك الخارجية مع واقع بيئة واتساب الخاصة بك.\n\n---\n\n## 🏗️ المفهوم الأساسي: مصدر الحقيقة\n\nتوفر هذه الواجهة لقطة لكل تصنيف معد حالياً على حسابك. بما أن التصنيفات هي موارد عالمية، فإن هذه القائمة مشتركة بين جميع الوكلاء والأنظمة الآلية المتصلة بمثليلك.\n\n### بنية البيانات الرئيسية\nيمثل كل إدخال في المصفوفة المسترجعة فئة تنظيمية فريدة، محددة بمعرف دائم (ID) وتوقيع مرئي (فهرس اللون). بينما تتكرر تغييرات الأسماء، يظل **المعرف (ID)** نقطة المرجع الثابتة لقاعدة بياناتك.\n\n---\n\n## 🚀 حالات الاستخدام التشغيلية الاستراتيجية\n\n### 1. مزامنة الحالة العامة\nالاستخدام الأكثر شيوعاً هو \"تغذية الدليل\". عند بدء تشغيل النظام أو تسجيل دخول الوكيل، يجب أن يسحب تطبيقك الدليل الكامل لبناء خريطة محلية للأسماء والمعرفات. هذا يمنع نظامك من الاضطرار إلى \"تخمين\" المعرف الذي يقابل \"كبار الشخصيات\" أو \"عميل جديد\".\n\n### 2. تخطيط تصنيف CRM\nإذا كنت تقوم بدمج واتساب مع نظام CRM خارجي (مثل Salesforce أو HubSpot)، فإن هذه الواجهة تتيح لك إجراء \"تدقيق للتصنيفات\" ومطابقتها برمجياً.\n\n---\n\n## ⚡ هندسة الأداء: استراتيجيات التخزين المؤقت المتقدمة\n\nبما أن التصنيفات يتم إنشاؤها نادراً ما تتغير في الوقت الفعلي، فإن جلب القائمة الكاملة لكل رسالة سيكون غير فعال. نوصي بنهج \"التخزين المؤقت الدافئ\":\n* **الجلب الأولي**: اسحب جميع التصنيفات أثناء مرحلة بدء تشغيل المتصفح أو الخادم.\n* **تحديث التخزين**: لا تستخدم وقت انتهاء صلاحية ثابت (TTL)، بل اعتمد على **الويب هوك**. يجب أن يقوم نظامك بتحديث التخزين المؤقت فقط عند تلقي حدث [تحديث تصنيف](/v2/webhooks/label-upsert) أو [حذف تصنيف](/v2/webhooks/label-deleted).\n            ",
          "tips": [
            {
              "title": "الكتالوج",
              "content": "يعيد قائمة بجميع الملصقات المعرفة في الحساب."
            },
            {
              "title": "المزامنة",
              "content": "استخدم هذا عند بدء التشغيل لبناء خريطة الملصقات المحلية الخاصة بك."
            }
          ],
          "recommendations": [
            "استطلع نقطة النهاية هذه من حين لآخر لاكتشاف الملصقات التي تم إنشاؤها على الهاتف.",
            "اعرض الملصقات المتاحة في قائمة منسدلة لوكلائك."
          ]
        }
      }
    },
    {
      "path": "/v2/labels/{id}",
      "methods": [
        "GET"
      ],
      "title": "Get Label",
      "category": "Labels",
      "description": "Retrieve details of a specific WhatsApp label.",
      "extraInfo": "\n# Precise Discovery: Fetching a Specific Label\n\nWhile fetching all labels is useful for initializing a broad dashboard, the **Get Label by ID** endpoint is designed for high-precision synchronization and real-time state verification. it allows you to retrieve the name, color index, and hex code of a single, specific label using its unique identifier.\n\n---\n\n## 🏗️ Core Concept: High-Precision Verification\n\nThis endpoint acts as a **Single Source of Truth (SSoT)** for a specific piece of your organizational taxonomy. It is primarily used when your system already knows a Label ID (perhaps from a webhook event or a database record) and needs to verify its current properties on the WhatsApp Business account without fetching the entire account directory.\n\n### Key Operational Advantages:\n1.  **Low Latency Discovery**: Fetching a single record is significantly faster and consumes less bandwidth than fetching the entire list of 20 labels, making it ideal for event-driven microservices.\n2.  **State Integrity**: Confirms if a label still exists before your system attempts to apply it to a chat, preventing high-volume API errors during automated tagging cycles.\n3.  **Visual Hydration**: Provides the exact visual metadata (Color Index and Hex) needed to render a specific tag in a contact's profile or a message notification.\n\n---\n\n## 🚀 Strategic Operational Use Case\n\n### The \"Hydration-on-Event\" Strategy\nWhen a new activity occurs (e.g., a [`label.chat.added`](/v2/webhooks/label-chat-added) webhook arrives), Meta only provides the Label ID. For your frontend system to display a meaningful \"Sales\" or \"VIP\" badge, it must \"hydrate\" that ID with its display name and color. This endpoint is the primary bridge for that hydration process.\n\n### Intelligent Resource Allocation\nIn high-volume scenarios, you can use this endpoint to check the \"Urgency Index\" of a label before prioritizing a message. For example, if the color index returned is 0 (Red), your system can immediately route the inquiry to a senior supervisor.\n\n---\n\n## 🛡️ Security & Scalable Access Control\n\nAccess to individual label metadata is protected by the same security layer as your core message history. \n\n*   **Instance Isolation**: You can only fetch labels belonging to the specific `instance_id` provided in the request. Attempting to fetch a Label ID from another instance will return a `404 Not Found`,\n  tips: [\n        {\n            type: 'info',\n            title: 'Lookup',\n            content: 'Retrieves the numeric ID for a given label ID string.'\n        },\n        {\n            type: 'info',\n            title: 'Format',\n            content: 'Useful when mapping between GUIDs and internal IDs.'\n        }\n    ],\n  recommendations: [\n        \"Cache this mapping to avoid redundant calls.\",\n        \"Use this to validate external IDs before processing.\"\n    ]\n  \n   ensuring data privacy between different WhatsApp Business accounts.\n*   **Token-Based Scoping**: Your API access token must have the appropriate permissions to view account metadata. This ensures that even if a Label ID is leaked, it cannot be queried without proper authorization.\n\n---\n\n## ⚡ Performance Engineering: The Hybrid Caching Model\n\nFetching a label ID is lightweight, but repeating it for every message in a busy thread is inefficient. We recommend a \"Demand-Driven Cache\":\n\n1.  **Check Local Store**: Always look for the Label ID in your internal memory or Redis first.\n2.  **Just-In-Time Fetch**: If the ID is missing (potentially because it was recently created), call this endpoint to fetch and store the details.\n3.  **Proactive Refresh**: Update your local record only when a [`label.update`](/v2/webhooks/label-upsert) webhook for that specific ID is received. This minimizes API overhead while maintaining 100% accuracy.\n\n---\n\n## ⚠️ Important Behaviors & Edge Cases\n\n*   **ID Persistence**: A Label ID is a persistent reference. However, if a label is deleted and later recreated with the exact same name, it will receive a **new unique ID**. Your systems should never hardcode ID strings; they should treat them as dynamic variables fetched from the account directory.\n*   **Color Index Stability**: While the `colorHex` might shift slightly across different device themes or Meta updates, the `color` index (0-19) is immutable. Use the index for your internal logic and the hex only for your UI rendering.\n\n---\n\n## 🔍 Debugging & Troubleshooting\n\n### Handling the 404 \"Ghost\" State\nIf this endpoint returns a 404 for a previously known ID, it indicates that the label was deleted—either via the API or manually by an agent in the WhatsApp Business app. Your system should handle this by gracefully removing the ID from its internal store and updating any active UI components to a neutral \"Uncategorized\" state.\n\n---\n\n## 🎯 Best Practices\n\n1.  **Graceful Fallbacks**: If a label fetch fails, default to a neutral grey badge in your UI to avoid breaking the layout.\n2.  **Index-Centric Themes**: Build your custom dashboard themes around the 20 standard indices to ensure a \"native\" feel for agents familiar with the WhatsApp mobile experience.\n3.  **Store Mapping Locally**: Save the returned metadata alongside the ID in your system to avoid redundant fetches during high-traffic periods.\n    ",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the label",
          "example": "1"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Label info retrieved",
          "example": {
            "id": "1",
            "name": "New Customer",
            "color": 0,
            "colorHex": "#ff9485"
          }
        },
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "جلب تصنيف محدد",
          "description": "استرجاع تفاصيل تصنيف واتساب محدد.",
          "args": {
            "id": {
              "description": "المعرف الفريد للتصنيف"
            }
          },
          "extraInfo": "\n# الاكتشاف الدقيق: جلب تصنيف محدد\n\nبينما يعد جلب جميع التصنيفات مفيداً لتهيئة لوحة تحكم عامة، تم تصميم نقطة نهاية **جلب التصنيف حسب المعرف** للمزامنة الدقيقة والتحقق من الحالة في الوقت الفعلي. تتيح لك استرداد الاسم وفهرس اللون والرمز الست عشري لتصنيف واحد محدد باستخدام معرفه الفريد.\n\n---\n\n## 🏗️ المفهوم الأساسي: التحقق عالي الدقة\n\nتعمل هذه الواجهة كـ **مصدر وحيد للحقيقة (SSoT)** لقطعة محددة من تصنيفك التنظيمي. تُستخدم بشكل أساسي عندما يعرف نظامك بالفعل معرف التصنيف (ربما من حدث ويب هوك أو سجل قاعدة بيانات) ويحتاج إلى التحقق من خصائصه الحالية دون جلب دليل الحساب بالكامل.\n\n---\n\n## 🚀 حالات الاستخدام التشغيلية الاستراتيجية\n\n### استراتيجية \"الإماهة عند الحدث\"\nعندما يصل ويب هوك [إضافة تصنيف لدردشة](/v2/webhooks/label-chat-added)، يوفر واتساب فقط معرف التصنيف (Label ID). لكي يعرض نظامك الأمامي شارة مفيدة مثل \"مبيعات\" أو \"VIP\"، يجب \"إماهة\" هذا المعرف باسمه الظاهر ولونه. هذه الواجهة هي الجسر الأساسي لعملية الإماهة تلك.\n\n### توزيع الموارد الذكي\nيمكنك استخدام هذه الواجهة للتحقق من \"مؤشر الاستعجال\" للتصنيف قبل تحديد أولوية الرسالة. مثلاً إذا كان فهرس اللون المسترجع هو 0 (أحمر)، يمكن لنظامك توجيه الاستفسار فوراً إلى مشرف كبير.\n\n---\n\n## 🛡️ الأمان وضبط الوصول\nالوصول إلى البيانات الوصفية للتصنيفات الفردية محمي بنفس طبقة الأمان الخاصة بسجل رسائلك الأساسي. لا يمكنك جلب إلا التصنيفات التابعة لمثيلك المحدد، مما يضمن خصوصية البيانات بين حسابات واتساب بيزنس المختلفة.\n\n---\n\n## ⚡ هندسة الأداء: نموذج التخزين المؤقت المختلط\n\nجلب معرف التصنيف خفيف، لكن تكراره لكل رسالة في محادثة مزدحمة غير فعال. نوصي بـ \"التخزين المؤقت عند الطلب\":\n1. **فحص المخزن المحلي**: ابحث دائماً عن معرف التصنيف في ذاكرة نظامك أولاً.\n2. **الجلب في الوقت المناسب**: إذا كان المعرف مفقوداً، استدعِ هذه الواجهة لتخزين التفاصيل.\n3. **التحديث الاستباقي**: قم بتحديث سجلك المحلي فقط عند استلام ويب هوك [تحديث تصنيف](/v2/webhooks/label-upsert) لهذا المعرف المحدد.\n            ",
          "tips": [
            {
              "title": "بحث",
              "content": "يسترجع المعرف الرقمي لسلسلة معرف ملصق معينة."
            },
            {
              "title": "التنسيق",
              "content": "مفيد عند التعيين بين GUIDs والمعرفات الداخلية."
            }
          ],
          "recommendations": [
            "قم بتخزين هذا التعيين مؤقتًا لتجنب الاستدعاءات المتكررة.",
            "استخدم هذا للتحقق من صحة المعرفات الخارجية قبل المعالجة."
          ]
        }
      }
    },
    {
      "path": "/v2/labels/create",
      "realPath": "/v2/labels",
      "methods": [
        "POST"
      ],
      "title": "Create Label",
      "category": "Labels",
      "description": "Create a new WhatsApp label with a name and optional color.",
      "extraInfo": "\n# Building Your Taxonomy: Creating Labels\n\nEstablishing a robust labeling system is the first step toward transforming your WhatsApp Business account from a simple messaging tool into a structured, metadata-driven customer service platform. The **Create Label** endpoint serves as the fundamental architect for this transformation, allowing you to define the semantic categories that will govern your conversational workflows.\n\n---\n\n## 🏗️ Architectural Philosophy: Designing a Scalable Taxonomy\n\nWhen you create a label, you are not just naming a folder; you are defining a **State** or **Attribute** that a conversation can possess. Because WhatsApp limits each account to **20 labels**, every entry in your taxonomy must be strategic, versatile, and high-impact.\n\n### The \"Label Blueprint\" Strategy\nA well-designed label system should focus on three core pillars:\n1.  **Workflow Stage**: Indicating where the customer is in their journey (e.g., \"New Lead\", \"In Negotiation\").\n2.  **Visual Urgency**: Using the color system to signal the need for immediate action.\n3.  **Ownership & Responsibility**: Defining who or what (e.g., a specific department or bot) is currently managing the thread.\n\n---\n\n## 🎨 The Color System: Visual Intelligence for Agents\n\nThe WhatsApp labeling interface is a highly visual environment. The 20-color palette (indexed 0-19) is designed to minimize cognitive load for agents who are managing dozens of simultaneous threads.\n\n### The Strategic Color Map\n*   **Indices 0 & 13 (High Urgency Reds)**: Reserved for critical escalations, potential churn risks, or time-sensitive breaches.\n*   **Indices 1 & 14 (Operational Blues)**: Ideal for active workstreams, informational updates, or mid-funnel leads that require consistent but not immediate engagement.\n*   **Indices 9 & 15 (Positive Greens)**: Used for \"Closed Won\" status, verified payments, or successfully resolved support tickets.\n*   **Index 2 (Yellow)**: Represents a \"Pending\" or \"Waiting\" state—usually where the ball is in the customer's or a third-party's court.\n*   **Index 4 (Grey)**: Best for \"Cold\" leads, \"Nurture\" campaigns, or archived threads that shouldn't distract the agent's main focus.\n\n> [!IMPORTANT]\n> **Engineering Tip**: While the API returns a `colorHex`,\n  tips: [\n        {\n            type: 'info',\n            title: 'Color',\n            content: 'Supports standard WhatsApp color indices (0-19).'\n        },\n        {\n            type: 'info',\n            title: 'Limits',\n            content: 'You can create up to 20 unique labels per account.'\n        }\n    ],\n  recommendations: [\n        \"Establish a naming convention across your organization.\",\n        \"Use distinct colors for high-priority vs low-priority items.\"\n    ]\n  \n   your system should rely exclusively on the **Color Index (0-19)** for logic. The hex values may shift slightly across different device versions or WhatsApp themes, but the index mapping is the immutable link to Meta's UI.\n\n---\n\n## 📏 Naming Conventions & Standardizations\n\nTo ensure your labels are as effective in the mobile app as they are in your custom CRM, follow these naming standards:\n\n1.  **Character Economy**: WhatsApp enforces a ~25 character limit. Names like \"High Priority Support Request Assigned to Alice\" will be truncated in the UI, rendering them useless. Use \"Urgent: Alice\" instead.\n2.  **Action-Oriented Naming**: Use labels that describe a state or a needed action. \"Invoice\" is a noun; \"Invoice Sent\" or \"Pay Pending\" are actionable states.\n3.  **Semantic Consistency**: Avoid using \"Label\" in the name. \"VIP Label\" is redundant when the UI already places the name in a colored badge.\n\n---\n\n## 🚀 Advanced Operational Use Cases\n\n### 1. Sales Funnel Orchestration\nInstead of manual tracking, use label creation to build a dynamic funnel. You might define stages starting from \"Initial Inquiry\" through \"Discovery Call\" and \"Proposal\" down to \"Closed.\" By programmatically maintaining these labels, your reporting systems can calculate conversion rates simply by counting chat distribution across these IDs.\n\n### 2. Team & Department Routing\nIn large organizations, labels act as the \"Routing Meta\" for incoming threads. You can create specialized labels for \"Technical Support,\" \"Billing,\" and \"Sales.\" When a customer hits a specific branch in your IVR/Bot, your system ensures the correct label exists and applies it, instantly notifying the correct department's monitoring team.\n\n### 3. Campaign & Event Tracking\nFor seasonal events (e.g., \"Black Friday Sale\" or \"Product Launch X\"), temporary labels allow you to isolate performance data. Once the campaign is over, these labels can be archived or deleted to free up space for the next cycle.\n\n---\n\n## ⚠️ Scaling Beyond the 20-Label Limit\n\nThe 20-label limit is a frequent challenge for high-growth businesses. If your system requires more than 20 categories, we recommend the following \"Expansion Patterns\":\n\n*   **The \"Tag Prefix\" Pattern**: Use a single label called \"Campaign\" and store the specific campaign ID in your internal database, linked to the chat ID.\n*   **The \"Rolling Archive\" Pattern**: Implement a cleanup script that deletes labels for campaigns or events that have been inactive for more than 90 days.\n*   **Dynamic Lifecycle**: Only create labels when they are actively needed for the current month's goals, and rotate them as business priorities shift.\n\n---\n\n## 🔄 Idempotency & Conflict Resolution\n\nWhatsApp allows for **Duplicate Label Names**. This can lead to significant confusion if your system creates a new \"New Lead\" label every time a lead arrives.\n\n### The \"Verify-Before-Create\" Pattern\nYour integration should always implement a \"Check and Bridge\" logic. Before attempting to create a label, fetch the current global list. If a label with the target name (case-insensitive) already exists, your system should use that existing ID instead of creating a new one. This preserves the 20-label quota and maintains a single source of truth for each category.\n\n---\n\n## 🛠️ Performance & Integration Principles\n\n### Bootstrapping Your Primary Taxonomy\nWe recommend creating your core \"Mission Critical\" labels during your application's initial setup or \"Warm-up\" phase. Creating labels \"on-the-fly\" during high-traffic message bursts can introduce unnecessary latency and risk hitting Meta's undocumented rate limits for metadata changes.\n\n### Webhook Synergy\nThe creation of a label triggers the [`label.upsert`](/v2/webhooks/label-upsert) webhook. Your backend should listen for this event to keep your local database synchronized with the WhatsApp account, especially if users are also creating labels manually via the mobile app.\n\n---\n\n## 🎯 Best Practices Summary\n\n1.  **Think Statefully**: Labels should represent the current state of a conversation, not just the customer's identity.\n2.  **Optimize Visuals**: Group similar departments into color clusters (e.g., all Sales-related labels use shades of Blue).\n3.  **Store Mapping Locally**: Always save the returned `id` alongside the `name` in your system for high-speed cross-referencing.\n4.  **Audit the Sidebar**: Periodically review your labels in the native WhatsApp app to ensure they remain legible and meaningful for your frontline agents.\n    ",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "name": {
          "required": true,
          "type": "string",
          "description": "The name of the new label",
          "example": "Urgent"
        },
        "color": {
          "required": false,
          "type": "number",
          "description": "Internal color number (0-19). E.g., 0=#ff9485, 1=#64c4ff, ... 19=#9368cf",
          "example": "0"
        }
      },
      "responses": [
        {
          "status": 201,
          "description": "Label created successfully",
          "example": {
            "id": "3",
            "name": "Urgent",
            "color": 0,
            "colorHex": "#ff9485"
          }
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Parameter Format",
          "contentType": "application/json",
          "example": {
            "code": "invalid_param",
            "message": "Invalid format for one or more parameters.",
            "details": {
              "param": "text",
              "value": "too_long",
              "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "إنشاء تصنيف",
          "description": "إنشاء تصنيف واتساب جديد مع اسم ولون اختياري.",
          "args": {
            "name": {
              "description": "اسم التصنيف الجديد"
            },
            "color": {
              "description": "رقم اللون الداخلي (0-19). مثلاً: 0=#ff9485"
            }
          },
          "extraInfo": "\n# بناء بنية التصنيف: إنشاء التصنيفات\n\nيعد إنشاء نظام تصنيف قوي هو الخطوة الأولى نحو تحويل حساب واتساب بيزنس الخاص بك من مجرد أداة مراسلة بسيطة إلى منصة خدمة عملاء منظمة تعتمد على البيانات الوصفية.\n\n---\n\n## 🏗️ الفلسفة المعمارية: تصميم بنية قابلة للتوسع\n\nعندما تنشئ تصنيفاً، فأنت لا تقوم فقط بتسمية مجلد؛ بل تحدد **حالة** أو **سمة** يمكن للمحادثة أن تمتلكها. نظرًا لأن واتساب يحدد كل حساب بـ **20 تصنيفاً** فقط، يجب أن يكون كل إدخال استراتيجياً وفعالاً.\n\n### استراتيجية \"مخطط التصنيف\"\nيجب أن يركز نظام التصنيف المصمم جيداً على ثلاث ركائز أساسية:\n1. **مرحلة سير العمل**: توضيح مكان العميل في رحلته (مثلاً: \"عميل جديد\"، \"في مرحلة التفاوض\").\n2. **الاستعجال البصري**: استخدام نظام الألوان للإشارة إلى الحاجة لاتخاذ إجراء فوري.\n3. **الملكية والمسؤولية**: تحديد من (مثلاً قسم معين أو بوت) يدير المحادثة حالياً.\n\n---\n\n## 🎨 نظام الألوان: ذكاء بصري للوكلاء\n\nواجهة تصنيفات واتساب هي بيئة بصرية للغاية. تم تصميم لوحة الألوان المكونة من 20 لوناً لتقليل العبء المعرفي على الوكلاء الذين يديرون عشرات المحادثات المتزامنة.\n\n*   **الفهارس 0 و 13 (الأحمر عالي الاستعجال)**: محجوزة للتصعيد الحرج أو مخاطر خسارة العملاء.\n*   **الفهارس 1 و 14 (الأزرق التشغيلي)**: مثالية لسير العمل النشط أو التحديثات المعلوماتية.\n*   **الفهارس 9 و 15 (الأخضر الإيجابي)**: تستخدم لحالات \"تم الإغلاق بنجاح\" أو الدفعات المؤكدة.\n*   **الفهرس 2 (الأصفر)**: يمثل حالة \"قيد الانتظار\" — عادةً عندما تكون الكرة في ملعب العميل.\n\n---\n\n## 📏 قواعد التسمية والمعايير\n\nلضمان فعالية تصنيفاتك في تطبيق الهاتف وسياق CRM الخاص بك، اتبع هذه المعايير:\n\n1. **اقتصاد الأحرف**: يفرض واتساب حداً يبلغ حوالي 25 حرفاً. الأسماء الطويلة سيتم اقتطاعها في الواجهة، مما يجعلها غير مفيدة. استخدم \"عاجل: أحمد\" بدلاً من \"طلب دعم عالي الأولوية محال إلى أحمد\".\n2. **تسمية موجهة نحو العمل**: استخدم التصنيفات التي تصف حالة أو إجراءً مطلوباً. \"فاتورة\" هي اسم؛ أما \"تم إرسال الفاتورة\" فهي حالة قابلة للتنفيذ.\n\n---\n\n## ⚠️ التوسع بما يتجاوز حد الـ 20 تصنيفاً\n\nيمثل حد الـ 20 تصنيفاً تحدياً متكرراً للشركات سريعة النمو. إذا كان نظامك يتطلب أكثر من 20 فئة، نوصي بالأنماط التالية:\n* **نمط سابقة الوسم (Tag Prefix)**: استخدم تصنيفاً واحداً يسمى \"حملة\" وقم بتخزين معرف الحملة المحدد في قاعدة بياناتك الداخلية.\n* **نمط الأرشفة الدورية**: قم بتنفيذ نص برمجى للتنظيف يحذف التصنيفات غير النشطة لأكثر من 90 يوماً.\n      ",
          "tips": [
            {
              "title": "اللون",
              "content": "يدعم مؤشرات ألوان واتساب القياسية (0-19)."
            },
            {
              "title": "الحدود",
              "content": "يمكنك إنشاء ما يصل إلى 20 ملصقًا فريدًا لكل حساب."
            }
          ],
          "recommendations": [
            "أنشئ اتفاقية تسمية عبر مؤسستك.",
            "استخدم ألوانًا مميزة للعناصر ذات الأولوية العالية مقابل العناصر ذات الأولوية المنخفضة."
          ]
        }
      }
    },
    {
      "path": "/v2/labels/{labelId}/update",
      "realPath": "/v2/labels/{labelId}",
      "methods": [
        "PUT"
      ],
      "title": "Update Label",
      "category": "Labels",
      "description": "Update an existing WhatsApp label's name or color.",
      "extraInfo": "\n# Label Evolution: Navigating Taxonomy Changes\n\nAs your business grows and your sales or support funnels mature, your organizational requirements will inevitably shift. The **Update Label** endpoint is designed to facilitate this evolution, allowing you to refine your terminology and visual hierarchy without severing existing conversation links.\n\n---\n\n## 🏗️ Core Concept: Non-Destructive Refinement\n\nUnlike deleting and recreating a category—which would strip all metadata from your active chats—updating a label is a **state-preserving operation**. When you modify a label's name or color, every chat currently tagged with that record is instantly updated across the entire WhatsApp Business ecosystem.\n\n### The Power of Partial Updates\nThis endpoint follows a \"Flexible Schema\" approach. You are not required to provide both the name and the color for every request. \n*   **Terminological Shift**: Use this to rename \"Lead\" to \"Prospect\" across 500+ chats in a single API call.\n*   **Priority Escalation**: Keep the name \"Follow-up\" but change its color from Yellow to Red to instantly signal a high-priority state to your manual agent pool.\n\n---\n\n## 🚀 Strategic Operational Use Cases\n\n### 1. Rebranding & Terminology Alignment\nOrganizations often settle on specific internal buzzwords that eventually change. Whether you are moving from a \"Trial\" based model to \"Freemium\" or simply correcting a typo in a high-visibility tag, the Update endpoint ensures your frontline agents always see the most professional and current terminology.\n\n### 2. Visual Urgency Dynamic\nA label's color is a powerful subconscious trigger. During peak periods (like a holiday sale), you might temporarily update the color of your \"Shipping\" label to a more aggressive index (e.g., Red or Orange) to ensure it stands out in the chat list. Once the peak passes, you can revert it to a more neutral blue or green.\n\n### 3. Funnel Progression & Consolidation\nIf you find that two categories (e.g., \"Web lead\" and \"App lead\") have become redundant, you can rename one to \"Digital Lead\" and begin migrating the other's chats. This ensures a clean transition without losing historical context.\n\n---\n\n## ⚠️ Critical Behaviors & Atomic Logic\n\n### The \"Stable ID\" Principle\nEven when a label's name changes from \"Bug A\" to \"Fixed,\" its underlying **ID** never changes. This is critical for your internal reporting systems and databases. Your backend should always link metadata to the Label ID, allowing the name to remain a flexible \"Display Attribute.\"\n\n### Duplicate Name Tolerance\nWhatsApp allows for multiple labels to share the same name. If you update a label to match the name of an existing one, the system will not prevent the change. While this provides flexibility, it can lead to \"UI Confusion.\"\n*   **Recommendation**: Before executing an update, fetch your global label list and verify that the target name is not already in use by another ID. This maintains a clean and unique sidebar for your agents.\n\n---\n\n## 🛡️ Reliability & Webhook Orchestration\n\nAny change to a label's metadata triggers the [`label.upsert`](/v2/webhooks/label-upsert) webhook. \n\n### Synchronization Strategies\nYour integration should use this webhook as a \"Sync Trigger.\" When an agent renames a label manually in the WhatsApp Business app, your local database will receive the update event. This ensures that your CRM's \"Tag View\" always matches what the agent sees on their mobile device or desktop.\n\n### Managing Rate Limits\nWhile metadata updates are lightweight, we recommend avoiding high-frequency \"flapping\" (e.g., changing a label's color 10 times a minute). Maintain a stable taxonomy to avoid hitting Meta's undocumented rate limits for account-wide metadata modifications.\n\n---\n\n## 🛠️ Integration Patterns: Enterprise Compliance\n\n### The Audit Blueprint\nIn regulated industries (like Finance or Healthcare), changing the meaning of a tag can have legal implications. We recommend logging the \"Before\" and \"After\" state of any update in your own audit logs, capturing the timestamp and the identity of the agent who initiated the change.\n\n### The \"Maintenance Window\" Rollout\nWhen performing a large-scale re-architecture of your labels, perform the updates during low-traffic periods. This allows the changes to propagate through WhatsApp's global servers and ensures your local caches can be refreshed without impacting active conversation flows.\n\n---\n\n## 🎯 Best Practices\n\n1.  **Favor Consistency**: Avoid frequent renames, as agents build \"muscle memory\" based on the text and position of labels in their sidebar.\n2.  **Color Hierarchy**: Reserves Red indices for \"Negative/Urgent\" states and Green for \"Success\" states. Don't flip these meanings during an update.\n3.  **Invalidate Caches**: After a successful update, instantly clear any local or Redis-based label caches to prevent your UI from showing stale terminology.\n4.  **Character Awareness**: Always verify the new name is under the ~25 character limit to prevent truncation in the official WhatsApp app.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Modification",
          "content": "Allows renaming or changing the color of an existing label."
        },
        {
          "type": "warning",
          "title": "Consistency",
          "content": "Updates are pushed to all devices immediately."
        }
      ],
      "recommendations": [
        "Notify agents if a common label changes meaning (e.g., 'Red' becomes 'Low Priority').",
        "Update the updated timestamp in your local database."
      ],
      "args": {
        "labelId": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the label to update",
          "example": "3"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "name": {
          "required": false,
          "type": "string",
          "description": "New name for the label",
          "example": "Very Urgent"
        },
        "color": {
          "required": false,
          "type": "number",
          "description": "New internal color number (0-19). E.g., 0=#ff9485, 1=#64c4ff, ... 19=#9368cf",
          "example": "0"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Label updated successfully",
          "example": {
            "id": "3",
            "name": "Very Urgent",
            "color": 0,
            "colorHex": "#ff0000"
          }
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Parameter Format",
          "contentType": "application/json",
          "example": {
            "code": "invalid_param",
            "message": "Invalid format for one or more parameters.",
            "details": {
              "param": "text",
              "value": "too_long",
              "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "تحديث تصنيف",
          "description": "تحديث اسم أو لون تصنيف واتساب موجود.",
          "args": {
            "labelId": {
              "description": "المعرف الفريد للتصنيف المراد تحديثه"
            },
            "name": {
              "description": "الاسم الجديد للتصنيف"
            },
            "color": {
              "description": "رقم اللون الداخلي الجديد (0-19). مثلاً: 0=#ff9485"
            }
          },
          "extraInfo": "\n# تطور التصنيفات: التنقل في تغييرات البنية\n\nمع نمو عملك ونضوج أقماع المبيعات أو الدعم، ستتغير متطلباتك التنظيمية حتماً. تم تصميم نقطة نهاية **تحديث تصنيف** لتسهيل هذا التطور، مما يتيح لك تحسين مصطلحاتك وتدرجك البصري دون قطع روابط المحادثات الموجودة.\n\n---\n\n## 🏗️ المفهوم الأساسي: التحسين غير التدميري\n\nعلى عكس حذف فئة وإعادة إنشائها — مما سيجرد كل البيانات الوصفية من دردشاتك النشطة — يعد تحديث التصنيف **عملية تحافظ على الحالة**. عند تعديل اسم التصنيف أو لونه، يتم تحديث كل دردشة موسومة بهذا السجل فوراً عبر كامل منظومة واتساب بيزنس.\n\n### قوة التحديثات الجزئية\n* **التحول الاصطلاحي**: استخدم هذا لتغيير اسم \"عميل محتمل\" إلى \"فرصة بيع\" عبر أكثر من 500 دردشة في استدعاء واحد للواجهة.\n* **تصعيد الأولوية**: حافظ على اسم \"متابعة\" ولكن غيّر لونه من الأصفر إلى الأحمر للإشارة فوراً إلى حالة عالية الأولوية لفريق وكلائك.\n\n---\n\n## ⚠️ السلوكيات الحرجة والمنطق الذري\n\n### مبدأ \"المعرف المستقر\"\nحتى عندما يتغير اسم التصنيف من \"خطأ أ\" إلى \"تم الإصلاح\"، فإن **المعرف (ID)** الأساسي لا يتغير أبداً. هذا أمر بالغ الأهمية لأنظمة التقارير الداخلية وقواعد البيانات الخاصة بك. يجب أن يربط نظامك الخلفي دائماً البيانات الوصفية بمعرف التصنيف، مما يسمح للاسم بأن يظل \"سمة عرض\" مرنة.\n\n### تحمل الأسماء المكررة\nيسمح واتساب لمصنفات متعددة بمشاركة نفس الاسم. إذا قمت بتحديث تصنيف ليتطابق مع اسم تصنيف موجود، فلن يمنع النظام التغيير. بينما يوفر هذا مرونة، إلا أنه قد يؤدي إلى \"ارتباك في الواجهة\".\n**التوصية**: قبل تنفيذ التحديث، جلب قائمة التصنيفات العالمية وتأكد من أن الاسم المستهدف ليس مستخدماً بالفعل بواسطة معرف آخر.\n\n---\n\n## 🎯 أفضل الممارسات\n\n1. **تفضيل الاتساق**: تجنب تغيير الأسماء بشكل متكرر، حيث يبني الوكلاء \"ذاكرة عضلية\" بناءً على النص وموقع التصنيفات في شريطهم الجانبي.\n2. **التسلسل الهرمي للألوان**: احتفظ بفهارس اللون الأحمر للحالات \"السلبية/العاجلة\" والأخضر لحالات \"النجاح\". لا تقلب هذه المعاني أثناء التحديث.\n3. **إبطال التخزين المؤقت**: بعد تحديث ناجح، امسح فوراً أي تخزين مؤقت محلي للتصنيفات لمنع واجهتك من عرض مصطلحات قديمة.\n4. **الوعي بعدد الأحرف**: تأكد دائماً أن الاسم الجديد أقل من 25 حرفاً لتجنب الاقتطاع في تطبيق واتساب الرسمي.\n            ",
          "tips": [
            {
              "title": "تعديل",
              "content": "يسمح بإعادة تسمية أو تغيير لون ملصق موجود."
            },
            {
              "title": "الاتساق",
              "content": "يتم دفع التحديثات إلى جميع الأجهزة فورًا."
            }
          ],
          "recommendations": [
            "أخطر الوكلاء إذا تغير معنى ملصق شائع (مثل 'أحمر' أصبح 'أولوية منخفضة').",
            "قم بتحديث الطابع الزمني المحدث في قاعدة بياناتك المحلية."
          ]
        }
      }
    },
    {
      "path": "/v2/labels/{labelId}/delete",
      "realPath": "/v2/labels/{labelId}",
      "methods": [
        "DELETE"
      ],
      "title": "Delete Label",
      "category": "Labels",
      "description": "Permanently delete a WhatsApp label.",
      "extraInfo": "\n# Lifecycle Management: The Deletion Protocol\n\nThe **Delete Label** endpoint is the final stage in a category's lifecycle. It allows you to prune obsolete categories from your global taxonomy, ensuring that your WhatsApp Business account remains focused and high-performing.\n\n---\n\n## ⚠️ The Gravity of Deletion: Irreversible Consequences\n\nDeleting a label is one of the few truly destructive actions in the WhatsApp ecosystem. It is critical to understand the cascading effects before execution:\n\n*   **Global Taxonomy Removal**: The label is purged from the account's directory. It will no longer appear in the [`Get All Labels`](/v2/labels) response.\n*   **Automatic Untagging (The Cascade)**: Every conversation currently carrying this label will be stripped of it. This happens at the server level; you do not need to manually remove the label from individual chats before deleting the category.\n*   **Zero Recovery**: There is no \"Trash\" or \"Recycle Bin.\" Once a Label ID is deleted, it cannot be recovered. Recreating a label with the same name will result in a **new ID**, and previous chat associations will not be restored.\n\n---\n\n## 🚀 Strategic Operational Use Cases\n\n### 1. Post-Campaign Decommissioning\nMarketing efforts often use high-visibility labels (e.g., \"Holiday Sale 2024\") to track conversion. Once the campaign window closes and follow-ups are completed, deleting the label keeps the agent's sidebar clean and reduces cognitive load during daily operations.\n\n### 2. Taxonomy Consolidation\nAs business processes evolve, you may find that multiple labels (e.g., \"Web-Inquiry\" and \"Form-Inquiry\") are essentially redundant. Deleting the surplus categories encourages agents to use a centralized, standardized \"Digital Lead\" tag instead.\n\n### 3. Cleanup of Experimental Categories\nWhen testing new automation flows or bot behaviors, you may create temporary labels for internal routing. Deleting these once testing is complete prevents your 20-label quota from being exhausted by \"zombie\" tags.\n\n---\n\n## 🛡️ The \"Safe Decommissioning\" Pattern\n\nTo avoid accidental data loss or workflow disruption, the following architectural steps should be taken before calling the Delete endpoint:\n\n1.  **Usage Auditing**: Always query [`Get Chats with Label`](/v2/labels/{id}/chats) to determine the volume of active threads currently relying on the tag.\n2.  **Meta-Migration**: If a label still has active threads, use a batch process to re-tag those chats with a replacement label (e.g., moving \"Old Campaign\" chats to \"Generic Lead\") before deleting the old category.\n3.  **Cross-System Verification**: Ensure that no external CRM filters or automated Slack notifications are exclusively triggered by the ID you are about to remove.\n\n---\n\n## ⚡ Integration Engineering & Webhooks\n\n### Orchestrating the \"Untag\" Flood\nA single deletion event can trigger a massive number of state changes if the label was applied to thousands of chats.\n*   **Webhook Behavior**: WhatsApp will fire the [`label.deleted`](/v2/webhooks/label-deleted) event once. However, your system must be prepared for the fact that those chats no longer possess the metadata.\n*   **UI Reflex**: Your application should immediately invalidate its label cache. If an agent's dashboard shows a \"Deleted Label\" badge, it may lead to confusion when they try to interact with that metadata and receive 404 errors from subsequent API calls.\n\n---\n\n## 🏗️ Enterprise Hygiene: Maximizing the 20-Label Limit\n\nBecause WhatsApp enforces a hard limit of 20 labels, deletion is a vital tool for \"Metadata Grooming.\" \n\n*   **The \"Garbage Collection\" Rule**: Develop a standard operating procedure (SOP) to review your labels every 30-90 days. Labels with zero active associations should be prioritized for deletion to make room for new initiatives.\n*   **Selective Lifecycle**: Instead of creating permanent labels for every small event, reserve your IDs for high-level \"Lifecycle States\" (e.g., Lead, Customer, Escalated). Use deletion to rotate campaign-specific tags in and out of the available 20 slots.\n\n---\n\n## 🎯 Best Practices Summary\n\n1.  **Read-Check-Delete**: Always verify the label exists and check its usage count before pulling the trigger.\n2.  **Inform Your Team**: Deleting a label can be jarring for agents who rely on it for their daily triage. Coordinate with your support or sales leads before making taxonomy changes.\n3.  **Update CRM References**: Ensure your internal database is cleaned of any references to the deleted ID to prevent \"Ghost Metadata\" from appearing in your reports.\n4.  **Favor Renaming (If Unsure)**: If you might need the label again, consider using the [Update](/v2/labels/{id}/update) endpoint to rename it to \"[DEPRECATED] Name\" instead of deleting it immediately. This preserves the chat associations while signaling that the tag is out of rotation.\n    ",
      "tips": [
        {
          "type": "warning",
          "title": "Cascade",
          "content": "Deleting a label removes it from ALL associated chats."
        },
        {
          "type": "warning",
          "title": "Irreversibility",
          "content": "This action cannot be undone."
        }
      ],
      "recommendations": [
        "Consider renaming instead of deleting if the purpose changes slightly.",
        "Merge chats into a new label before deleting the old one."
      ],
      "args": {
        "labelId": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the label to delete",
          "example": "3"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Label deleted successfully",
          "example": {
            "ok": true
          }
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "حذف تصنيف",
          "description": "حذف تصنيف واتساب بشكل نهائي.",
          "args": {
            "labelId": {
              "description": "المعرف الفريد للتصنيف المراد حذفه"
            }
          },
          "extraInfo": "\n# إدارة دورة الحياة: بروتوكول الحذف\n\nتعد نقطة النهاية **حذف تصنيف** المرحلة الأخيرة في دورة حياة الفئة. تتيح لك إزالة الفئات القديمة من تصنيفك العالمي، مما يضمن بقاء حساب واتساب بيزنس الخاص بك مركزاً وعالي الأداء.\n\n---\n\n## ⚠️ خطورة الحذف: عواقب لا يمكن التراجع عنها\n\nيعد حذف التصنيف أحد الإجراءات التدميرية القليلة في منظومة واتساب. من الضروري فهم الآثار المترتبة قبل التنفيذ:\n\n*   **إزالة التصنيف العالمي**: يتم حذف التصنيف من دليل الحساب. لن يظهر بعد الآن في استجابة [جلب جميع التصنيفات](/v2/labels).\n*   **إلغاء الوسم التلقائي**: سيتم تجريد كل محادثة تحمل هذا التصنيف حالياً منه. يحدث هذا على مستوى الخادم؛ لا تحتاج لإزالة التصنيف يدوياً من الدردشات الفردية قبل حذف الفئة.\n*   **عدم إمكانية الاسترداد**: لا توجد \"سلة محذوفات\". بمجرد حذف معرف التصنيف، لا يمكن استعادته. سيؤدي إعادة إنشاء تصنيف بنفس الاسم إلى **معرف جديد**، ولن يتم استعادة ارتباطات الدردشة السابقة.\n\n---\n\n## 🚀 حالات الاستخدام التشغيلية الاستراتيجية\n\n### 1. إيقاف تشغيل ما بعد الحملة\nغالبًا ما تستخدم الجهود التسويقية تصنيفات عالية الوضوح (مثلاً: \"تنزيلات رمضان 2024\") لتتبع التحويل. بمجرد انتهاء نافذة الحملة واكتمال المتابعات، يؤدي حذف التصنيف إلى الحفاظ على نظافة شريط الوكيل وتقليل الحمل المعرفي.\n\n### 2. دمج التصنيفات\nمع تطور العمليات التجارية، قد تجد أن تصنيفات متعددة زائدة عن الحاجة. يشجع حذف الفئات الفائضة الوكلاء على استخدام وسم مركزي وموحد بدلاً من ذلك.\n\n---\n\n## 🛡️ نمط \"إيقاف التشغيل الآمن\"\n\nلتجنب فقدان البيانات العرضي أو تعطل سير العمل، يجب اتخاذ الخطوات المعمارية التالية قبل حذف التصنيف:\n\n1. **تدقيق الاستخدام**: استعلم دائماً عن [الدردشات التي تحمل التصنيف](/v2/labels/{id}/chats) لتحديد حجم المحادثات النشطة التي تعتمد حالياً على هذا الوسم.\n2. **ترحيل الميتا**: إذا كان التصنيف لا يزال يحتوي على محادثات نشطة، استخدم عملية دفعة لإعادة وسم تلك الدردشات بتصنيف بديل قبل حذف الفئة القديمة.\n            ",
          "tips": [
            {
              "title": "تسلسل",
              "content": "حذف الملصق يزيله من جميع الدردشات المرتبطة به."
            },
            {
              "title": "لا رجعة فيه",
              "content": "لا يمكن التراجع عن هذا الإجراء."
            }
          ],
          "recommendations": [
            "فكر في إعادة التسمية بدلاً من الحذف إذا تغير الغرض قليلاً.",
            "دمج الدردشات في ملصق جديد قبل حذف القديم."
          ]
        }
      }
    },
    {
      "path": "/v2/labels/{labelId}/chats",
      "methods": [
        "GET"
      ],
      "title": "Get Chats with Label",
      "category": "Labels",
      "description": "Get a list of chats associated with a specific label.",
      "extraInfo": "\n# Targeted Retrieval: Mastering Category-Based Filtering\n\nThe **Get Chats with Label** endpoint is the primary bridge between your organizational taxonomy and your communication workflow. It allows you to filter your entire conversation history by a specific Label ID, returning a lean list of chat identifiers and names that belong to that category.\n\n---\n\n## 🏗️ Core Concept: Category-Based Batch Processing\n\nThis endpoint enables high-efficiency retrieval by offloading the filtering logic to Wawp's core servers. Instead of your system iterating through thousands of individual chat logs to identify \"Stale Leads\" or \"VIPs,\" you can retrieve a pre-filtered list in a single, optimized API request.\n\n### Key Strategic Capabilities:\n1.  **Mass Outreach Orchestration**: Instantly identify all participants in a specific marketing campaign or product launch for targeted broadcasts.\n2.  **Workflow Throughput Auditing**: Measure the \"State Density\" of your funnel—such as how many chats are currently bottlenecked in the \"Payment Failure\" or \"Escalated\" states.\n3.  **CRM State Synchronization**: Pull segmented lists of contacts to ensure your external CRM dashboards reflect the real-time visual categorization seen by your WhatsApp agents.\n\n---\n\n## 🚀 Priority Operational Use Cases\n\n### 1. The Proactive Retention Cycle\nBy regularly querying labels like \"Pending Follow-up\" or \"Day 3 Trial,\" your system can identify users who have entered a period of inactivity. This allows you to trigger automated re-engagement messages or move them to a different \"Nurture\" category to prevent lead decay.\n\n### 2. Segmented Sentiment Analysis\nIn high-volume accounts, auditing every message is impossible. This endpoint allows you to focus your analytical resources on the most critical segments. By fetching only the chats tagged \"Dissatisfied\" or \"Urgent,\" you can run targeted sentiment analysis to identify systemic issues before they escalate.\n\n### 3. Queue Management & Load Balancing\nIf you use labels to assign chats to specific departments (e.g., \"Sales Queue,\" \"Support Tier 2\"), this endpoint provides the headcount per queue. This data is essential for dynamic resource allocation, allowing you to move agents between departments based on real-time conversation volume.\n\n---\n\n## ⚖️ Scalability & Big Data Architecture\n\nFor enterprise accounts with tens of thousands of conversations, the management of label lists requires an optimized approach to prevent memory exhaustion and timeout errors.\n\n### Managing High-Volume Lists\nWhile this endpoint is designed for speed, retrieving a list of 5,000+ chats can be tax the CPU of smaller server instances.\n*   **The Cursor-Free Pattern**: This endpoint returns the full current list for a label. To maintain performance, we recommend immediately streaming this data into a background processing queue (such as Redis or RabbitMQ) rather than attempting to process it inside the main HTTP request loop.\n*   **Memory Hygiene**: If you are operating in a resource-constrained environment (like a Lambda function or an Edge Worker), avoid storing the entire array in memory; process the results as a stream of IDs to minimize your memory footprint.\n\n---\n\n## 🛡️ Data Integrity & Compliance\n\n### PII Sensitivity & GDPR\nThe names returned by this endpoint are the contact names as they appear in the WhatsApp account's address book.\n*   **Data Minimization**: Never fetch full chat lists and store them indefinitely. Retrieve the list only when you have an immediate action to perform, and dispose of the identifiers once the operation is complete.\n*   **Real-Time Reflection**: The list is a snapshot of the *current* state. Because agents can add/remove labels in the WhatsApp mobile app at any time, treat the data as highly transient.\n\n---\n\n## 🎯 Best Practices\n\n1.  **Webhook-Triggered Audits**: Avoid high-frequency polling. Instead of checking this endpoint every 5 minutes, use the [`label.chat.added`](/v2/webhooks/label-chat-added) webhook to keep a local, incremental list of chat associations.\n2.  **Verify Label Vitality**: Before querying for chats, ensure the Label ID is still active. Querying a deleted ID will result in an empty list, which your system might incorrectly interpret as \"Zero active leads.\"\n3.  **Hybrid Enrichment**: Use the lean IDs returned here as a \"Filter Key.\" If you need more data (like profile pictures or BIOs), pass these IDs to the [`Get Contact Info`](/v1/get-contact-info) endpoint in small batches to build a rich, visual dashboard.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Aggregation",
          "content": "Often used to get a count of chats per label."
        },
        {
          "type": "positive",
          "title": "Dashboard",
          "content": "Great for visualizing workload (e.g., 'Pending Support Tickets')."
        }
      ],
      "recommendations": [
        "Cache the counts and update only when webhook events occur.",
        "Use charts to display label distribution for supervisors."
      ],
      "args": {
        "labelId": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the label",
          "example": "1"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "List of chats retrieved successfully",
          "example": [
            {
              "id": "123456789@c.us",
              "name": "John Doe"
            }
          ]
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "جلب الدردشات التي تحمل التصنيف",
          "description": "الحصول على قائمة بالدردشات المرتبطة بتصنيف محدد.",
          "args": {
            "labelId": {
              "description": "المعرف الفريد للتصنيف"
            }
          },
          "extraInfo": "\n# الاسترجاع المستهدف: إتقان التصفية القائمة على الفئات\n\nنقطة نهاية **جلب الدردشات التي تحمل التصنيف** هي الجسر الأساسي بين تصنيفك التنظيمي وسير عمل الاتصال الخاص بك. تتيح لك تصفية كامل سجل محادثاتك حسب معرف تصنيف محدد، مما يعيد قائمة خفيفة من معرفات الدردشة وأسمائها التي تنتمي إلى تلك الفئة.\n\n---\n\n## 🏗️ المفهوم الأساسي: المعالجة الدفعية القائمة على الفئات\n\nتتيح هذه الواجهة استرجاعاً عالي الكفاءة من خلال نقل منطق التصفية إلى خوادم Wawp المركزية. بدلاً من قيام نظامك بالمرور عبر آلاف سجلات الدردشة الفردية لتحديد \"العملاء القدامى\" أو \"كبار الشخصيات\"، يمكنك استرداد قائمة مصفاة مسبقاً في طلب واحد محسن للواجهة.\n\n### القدرات الاستراتيجية الرئيسية:\n1. **تنسيق التواصل الجماعي**: حدد فوراً جميع المشاركين في حملة تسويقية محددة لإرسال رسائل بث مستهدفة.\n2. **تدقيق تدفق سير العمل**: قياس \"كثافة الحالة\" لقمع المبيعات الخاص بك — مثل عدد الدردشات العالقة حالياً في حالات \"فشل الدفع\" أو \"مصعدة للمدير\".\n3. **مزامنة حالة CRM**: سحب قوائم مجزأة من جهات الاتصال لضمان أن لوحات تحكم CRM الخارجية تعكس التصنيف المرئي في الوقت الفعلي.\n\n---\n\n## 🚀 حالات الاستخدام ذات الأولوية\n\n### 1. دورة الاحتفاظ الاستباقية\nمن خلال الاستعلام المنتظم عن تصنيفات مثل \"انتظار المتابعة\"، يمكن لنظامك تحديد المستخدمين الذين دخلوا في فترة من الخمول، مما يسمح لك بإطلاق رسائل إعادة تفاعل مؤتمتة.\n\n### 2. تحليل المشاعر المجزأ\nفي الحسابات ذات الأداء العالي، يستحيل تدقيق كل رسالة. تتيح لك هذه الواجهة تركيز مواردك التحليلية على الأجزاء الأكثر أهمية من خلال جلب الدردشات الموسومة بـ \"غير راضٍ\" أو \"عاجل\" فقط.\n\n---\n\n## ⚖️ القابلية للتوسع ومعالجة البيانات الكبيرة\nبالنسبة لحسابات الشركات التي تضم عشرات الآلاف من المحادثات، تتطلب إدارة قوائم التصنيفات نهجاً محسناً لمنع استنزاف الذاكرة وأخطاء المهلة.\n* تعيد هذه الواجهة القائمة الحالية الكاملة للتصنيف. للحفاظ على الأداء، نوصي ببث هذه البيانات فوراً إلى طابور معالجة خلفي بدلاً من محاولة معالجتها داخل دورة طلب HTTP الرئيسية.\n* إذا كنت تعمل في بيئة ذات موارد محدودة، تجنب تخزين المصفوفة الكاملة في الذاكرة؛ قم بمعالجة النتائج كتدفق من المعرفات.\n\n---\n\n## 🎯 أفضل الممارسات\n\n1. **عمليات التدقيق المحفزة بالويب هوك**: تجنب الاستعلام المتكرر. بدلاً من فحص هذه الواجهة كل 5 دقائق، استخدم ويب هوك [إضافة تصنيف لدردشة](/v2/webhooks/label-chat-added) لتحديث قائمة محلية.\n2. **التحقق من حيوية التصنيف**: قبل الاستعلام عن الدردشات، تأكد من أن معرف التصنيف لا يزال نشطاً. الاستعلام عن معرف محذوف سيؤدي إلى قائمة فارغة، والتي قد يفسرها نظامك بشكل خاطئ على أنها \"صفر عملاء نشطين\".\n            ",
          "tips": [
            {
              "title": "التجميع",
              "content": "غالبًا ما يستخدم للحصول على عدد الدردشات لكل ملصق."
            },
            {
              "title": "لوحة القيادة",
              "content": "رائع لتصور عبء العمل (مثل 'تذاكر الدعم المعلقة')."
            }
          ],
          "recommendations": [
            "قم بتخزين الأعداد مؤقتًا وتحديثها فقط عند حدوث أحداث Webhook.",
            "استخدم الرسوم البيانية لعرض توزيع الملصقات للمشرفين."
          ]
        }
      }
    },
    {
      "path": "/v2/labels/{id}/chats/{chatId}",
      "methods": [
        "PUT"
      ],
      "title": "Link Label to Chat",
      "category": "Labels",
      "description": "Assign a specific label to a chat or contact.",
      "extraInfo": "\n# Tagging Conversations: Mastering Semantic Orchestration\n\nThe **Link Label to Chat** endpoint is the primary mechanism for attaching strategic metadata to individual or group conversations. This is not merely a \"visual tag\"; it is a programmatic state-marker that allows your CRM, bots, and agents to interact with conversations based on their current business value or urgency.\n\n---\n\n## 🏗️ Core Concept: Metadata at the Conversation Edge\n\nThink of labels as ** dynamic attributes ** that move a chat through your internal processing pipeline. \n\n### Key Architectural Principles:\n*   ** Additive Metadata **: A single chat can carry multiple labels simultaneously(e.g., \"VIP\" + \"Pending Payment\" + \"Assigned to Team A\").This allows for multi - dimensional filtering.\n*   ** Idempotency by Design **: Linking the same label to the same chat multiple times has zero side effects.This makes it safe to include tagging calls in high - frequency event loops without fear of duplication or errors.\n*   ** Silent Context **: Tagging is a purely internal operation.The customer never sees the labels, and no notification is sent to their device.It is a \"Private Channel\" for your organizational logic.\n\n---\n\n## 🚀 Strategic Operational Use Cases\n\n### 1. Funnel State Management\nUse this endpoint to move contacts through your sales funnel.As a user progresses from an \"Inbound Lead\" to a \"Qualified Prospect,\" your system should link the relevant labels to reflect their increasing value.This allows your sales team to instantly prioritize their inbox based on funnel depth.\n\n### 2. Auto - Tagging Intelligence\nBy integrating your messaging history with a sentiment analysis engine or a keyword detector, you can programmatically tag chats. \n*   ** Urgency Detection **: Automatically link an \"Urgent\" label if a user mentions \"ASAP\" or \"Help.\"\n  *   ** Intent Categorization **: Tag conversations as \"Billing,\" \"Support,\" or \"Sales\" based on the initial inbound message, ensuring they are routed to the correct department immediately.\n\n### 3. CRM & System Synchronization\nMirror the state of your external CRM.If a lead's status is updated in Salesforce or HubSpot, use this endpoint to ensure that the agent looking at the WhatsApp app sees the exact same status in real-time. This \"Side-by-Side Synchronization\" prevents data silos and agent confusion.\n\n---\n\n## 🛠️ Integration Patterns: Orchestrating Clean Transitions\n\n### The \"Step-Up\" Transition\nWhen moving a chat to a new state(e.g., from \"Pending\" to \"Approved\"), we recommend a \"Link then Prune\" pattern.First, link the new \"Approved\" label, then use the[Unlink endpoint](/v2/labels / { id } / chats / { chatId }) to remove the old \"Pending\" state.This ensures the chat is never without a category during the transition.\n\n### Event - Driven Tagging\nTrigger tagging based on external business events.For example, when a payment is processed in your billing system, instantly link the \"Paid\" label to the customer's WhatsApp chat. This provides immediate visual confirmation to any agent who might be interacting with that customer.\n\n---\n\n## 🧪 Advanced Operational Safeguards\n\n### Scalability with Groups\nThis endpoint fully supports WhatsApp Group Chats(`@g.us`). This is powerful for B2B workflows where you might tag an entire project room as \"Active\" or \"On Hold.\" \n\n### Handling the \"ID Drift\"\nAlways verify that the Label ID you are attempting to link is active in your global account directory. If a label has been deleted from the account, attempts to link it will result in a 404 error. Your system should listen for [`label.deleted`](/v2/webhooks/label-deleted) events to prevent \"Ghost Tagging\" attempts.\n\n---\n\n## ⚡ Webhook Orchestration\n\nEvery successful link operation triggers a [`label.chat.added`](/v2/webhooks/label-chat-added) event. You can use this to:\n*   **Trigger Notifications**: Push a high-priority browser notification to an agent's dashboard.\n*   **Launch Automations**: Start a specific drip campaign or bot sequence when a \"Warm Lead\" label is applied.\n\n---\n\n## 🎯 Best Practices\n\n1.  **Action-Oriented Taxonomy**: Use names like \"To Follow Up\" or \"Needs Manager\" instead of passive nouns. Labels should imply an action.\n2.  **Visual Consistency**: Leverage the color indices to create an urgency hierarchy. Reserve Reds for high-priority tagging.\n3.  **Batching at Scale**: When tagging a large segment of users (e.g., after a mass broadcast), implement a slight delay or use a background queue to ensure smooth propagation across Meta's servers.\n4.  **Prune Redundancy**: Don't let chats accumulate 10+ labels. Maintain \"Metadata Hygiene\" by removing old stage labels as new ones are added.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Capacity",
          "content": "A chat can have multiple labels (up to 20)."
        },
        {
          "type": "positive",
          "title": "Automation",
          "content": "Labels are excellent triggers for automated workflows."
        }
      ],
      "recommendations": [
        "Add a 'Bot Handled' label to chats your bot is managing.",
        "Use labels to track the customer journey (e.g., Lead, Qualified, Closed)."
      ],
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the label",
          "example": "1"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Target phone number or group ID (@c.us, @g.us)",
          "example": "447441429009@c.us"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "ربط تصنيف بالدردشة",
          "description": "تعيين تصنيف محدد لدردشة أو جهة اتصال.",
          "args": {
            "id": {
              "description": "المعرف الفريد للتصنيف"
            },
            "chatId": {
              "description": "رقم الهاتف المستهدف أو معرف المجموعة (@c.us, @g.us)"
            }
          },
          "extraInfo": "\n# وسم المحادثات: إتقان التنسيق الدلالي\n\nنقطة نهاية **ربط تصنيف بالدردشة** هي الآلية الأساسية لإرفاق بيانات وصفية استراتيجية بالمحادثات الفردية أو الجماعية. هذا ليس مجرد \"وسم مرئي\"؛ بل هو علامة حالة برمجية تتيح لنظام CRM والبوتات والوكلاء التفاعل مع المحادثات بناءً على قيمتها التجارية أو مدى استعجالها.\n\n---\n\n## 🏗️ المفهوم الأساسي: البيانات الوصفية في المقدمة\n\nفكر في التصنيفات كـ **سمات ديناميكية** تنقل الدردشة عبر خط المعالجة الداخلي الخاص بك. \n\n### المبادئ المعمارية الرئيسية:\n* **بيانات إضافية**: يمكن لدردشة واحدة حمل عدة تصنيفات في وقت واحد (مثلاً: \"VIP\" + \"دفع معلق\"). وهذا يتيح التصفية متعددة الأبعاد.\n* **التماثل**: ربط نفس التصنيف بنفس الدردشة عدة مرات ليس له آثار جانبية، مما يجعله آمناً للاستخدام في العمليات المؤتمتة دون خوف من التكرار.\n* **سياق صامت**: عملية الوسم داخلية تماماً. لا يرى العميل التصنيفات، ولا يتم إرسال أي إشعار لجهازه.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجية\n\n### 1. إدارة حالة القمع\nاستخدم هذه الواجهة لنقل جهات الاتصال عبر قمع المبيعات الخاص بك. مع تقدم المستخدم، يقوم نظامك بربط التصنيفات ذات الصلة لتعكس قيمته المتزايدة، مما يسمح لفريق المبيعات بتحديد الأولويات فوراً.\n\n### 2. ذكاء الوسم التلقائي\nمن خلال دمج سجل الرسائل مع محرك تحليل أو كاشف كلمات دلالية، يمكنك وسم الدردشات برمجياً.\n* **كشف الاستعجال**: ربط تصنيف \"عاجل\" تلقائياً إذا ذكر المستخدم كلمات مثل \"بأسرع ما يمكن\" أو \"مساعدة\".\n* **تصنيف النية**: وسم المحادثات كـ \"فاتورة\" أو \"دعم\" بناءً على الرسالة الأولى، لضمان توجيهها للقسم الصحيح فوراً.\n\n---\n\n## ⚡ تنسيق الويب هوك\n\nيؤدي كل ربط ناجح إلى إطلاق حدث [إضافة تصنيف لدردشة](/v2/webhooks/label-chat-added). يمكنك استخدام هذا من أجل:\n* **إطلاق التنبيهات**: إرسال تنبيه في المتصفح للوكيل.\n* **بدء الأتمتة**: بدء حملة تنقيط معينة أو تسلسل بوت عند تطبيق تصنيف \"عميل مهتم\".\n      ",
          "tips": [
            {
              "title": "السعة",
              "content": "يمكن أن تحتوي الدردشة على ملصقات متعددة (تصل إلى 20)."
            },
            {
              "title": "الأتمتة",
              "content": "الملصقات هي محفزات ممتازة لتدفقات العمل الآلية."
            }
          ],
          "recommendations": [
            "أضف ملصق 'تم التعامل معه بواسطة الروبوت' إلى الدردشات التي يديرها الروبوت الخاص بك.",
            "استخدم الملصقات لتتبع رحلة العميل (مثل: عميل محتمل، مؤهل، مغلق)."
          ]
        }
      }
    },
    {
      "path": "/v2/labels/{id}/chats/{chatId}",
      "methods": [
        "DELETE"
      ],
      "title": "Unlink Label from Chat",
      "category": "Labels",
      "description": "Remove a specific label from a chat or contact.",
      "extraInfo": "\n# Untagging Conversations: Mastering Taxonomy Pruning\n\nThe **Unlink Label from Chat** endpoint is the critical counterpart to the tagging process. It allows you to prune obsolete or resolved metadata from a conversation, ensuring that your agents' inbox remains clutter-free and that your automation engines are operating on the most current state of the relationship.\n\n---\n\n## 🏗️ Core Concept: State De - escalation\n\nRemoving a label is the programmatic equivalent of ** resolving a state ** or ** transitioning a stage **. \n\n### Key Operational Characteristics:\n*   ** Non - Destructive Association **: Unlinking a label from a chat only removes the relationship.The label itself remains untouched in your global account directory, ready to be applied to other conversations.\n*   ** Targeted State Removal **: Unlike a broad \"Clear All,\" this endpoint allows for surgical removal of a specific attribute(e.g., removing \"Urgent\" while keeping \"Assigned to Bob\").\n*   ** Idempotency & Silent Execution **: Attempting to remove a label that isn't currently linked to the chat will result in a success response with no side effects. No notification is ever sent to the customer, maintaining the privacy of your internal organizational logic.\n\n---\n\n## 🚀 Strategic Operational Use Cases\n\n### 1. Funnel Progression Hygiene\nAs a customer moves deeper into your sales or support funnel, their previous stages often become irrelevant.For example, once a \"New Lead\" becomes a \"Qualified Prospect,\" the \"New Lead\" label should be unlinked.This keeps the visual interface focused on the * next required action * rather than the conversation's history.\n\n### 2. Auto - Cleanup of \"Stale\" Metadata\nIn high - volume accounts, labels can accumulate over time, leading to \"Metadata Bloat.\" Use this endpoint in conjunction with a background cron job to automatically unlink \"Temporary\" or \"Inquiry\" labels after a set period of inactivity(e.g., 7 days).This ensures that only active, high - priority conversations carry visual markers.\n\n### 3. User - Triggered Opt - Outs\nIf you use labels to manage internal broadcast segments(e.g., \"Marketing Opt-In\"), use this endpoint to honor customer requests to stop communications.When a user sends a \"Stop\" message, your bot can instantly unlink the marketing label, immediately removing them from any future automated outreach lists.\n\n---\n\n## 🛠️ Integration Patterns: Orchestrating Move Sequences\n\n### The \"Link-then-Prune\" Strategy\nWhen a conversation state changes(e.g., from \"Billing Inquiry\" to \"Resolved\"), we recommend a two - step orchestration:\n1. ** Add the Destination State **: Link the \"Resolved\" label.\n2. ** Remove the Origin State **: Unlink the \"Billing Inquiry\" label.\nThis ensures that the chat always carries at least one visual marker during the transition period, preventing the conversation from \"disappearing\" from filtered views in the agent dashboard.\n\n### Mass Decategorization\nAfter a specific campaign or event(e.g., \"Webinar Q3\") is concluded, you can use this endpoint to clear the campaign markers from thousands of chats.By unlinking the campaign label, you effectively reset those conversations for the next cycle without deleting the record of the interaction itself.\n\n---\n\n## 🛡️ Data Integrity & Reliability\n\n### Handling ID Sensitivity\nAlways ensure that the Label ID you are unlinking is a valid string from your current account directory.If you attempt to unlink an ID that has been globally deleted, the API will return a 404 error.We recommend listening for [`label.deleted`](/v2/webhooks/label-deleted) webhooks to keep your internal ID mappings clean.\n\n---\n\n## 🎯 Best Practices\n\n1.  **Avoid Label Overload**: Maintain a \"Strict Limit\" policy for your chats. If a chat has more than 3 labels, it usually indicates that the previous stage markers haven't been properly unlinked.\n2.  **State-Driven Transitions**: Make unlinking a core part of your bot's logic. If a bot finishes a collection flow, it should unlink the \"Collecting Info\" label as its final act.\n3.  **Real-Time Synchronization**: Ensure your CRM's \"Delete Tag\" event or \"Status Change\" trigger is mapped to this endpoint. This keeps the agent's view in WhatsApp perfectly synchronized with the source of truth in your business database.\n4.  **Audit the Removal**: Log every unlinking operation in your internal audit trails to track how long conversations typically spend in a specific \"Labeled State.\"\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Cleanup",
          "content": "Removes a specific label relationship, not the label itself."
        },
        {
          "type": "warning",
          "title": "Sync",
          "content": "Changes are reflected instantly across all devices."
        }
      ],
      "recommendations": [
        "Remove 'New' labels as soon as an agent replies.",
        "Periodically audit old chats to remove stale labels."
      ],
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the label",
          "example": "1"
        },
        "chatId": {
          "required": true,
          "type": "string",
          "description": "Target phone number or group ID (@c.us, @g.us)",
          "example": "447441429009@c.us"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "translations": {
        "ar": {
          "title": "إلغاء ربط تصنيف بالدردشة",
          "description": "إزالة تصنيف محدد من دردشة أو جهة اتصال.",
          "args": {
            "id": {
              "description": "المعرف الفريد للتصنيف"
            },
            "chatId": {
              "description": "رقم الهاتف المستهدف أو معرف المجموعة (@c.us, @g.us)"
            }
          },
          "extraInfo": "\n# إلغاء وسم المحادثات: إتقان تهذيب التصنيفات\n\nنقطة نهاية **إلغاء ربط تصنيف بالدردشة** هي المكمل الحاسم لعملية الوسم. تتيح لك إزالة البيانات الوصفية القديمة أو التي تم حلها من المحادثة، مما يضمن بقاء صندوق وارد وكلائك خالياً من الفوضى وأن محركات الأتمتة تعمل على أحدث حالة للعلاقة.\n\n---\n\n## 🏗️ المفهوم الأساسي: خفض تصعيد الحالة\n\nإزالة التصنيف هي المعادل البرمجي لـ **حل حالة** أو **الانتقال لمرحلة جديدة**.\n\n### الخصائص التشغيلية الرئيسية:\n* **ارتباط غير تدميري**: إلغاء ربط التصنيف من الدردشة يزيل العلاقة فقط. يظل التصنيف نفسه دون تغيير في دليل حسابك العالمي، جاهزاً للتطبيق على محادثات أخرى.\n* **إزالة حالة مستهدفة**: على عكس عملية \"مسح الكل\" الشاملة، تتيح هذه الواجهة إزالة سمة محددة جراحياً (مثلاً: إزالة \"عاجل\" مع الحفاظ على \"محال للموظف سامي\").\n* **التماثل والتنفيذ الصامت**: محاولة إزالة تصنيف غير موجود بالفعل في الدردشة ستؤدي إلى استجابة نجاح دون آثار جانبية. لا يتم إرسال أي إشعار للعميل أبداً.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجية\n\n### 1. نظافة انتقال القمع\nمع تعمق العميل في قمع المبيعات أو الدعم، تصبح مراحله السابقة غالباً غير ذات صلة. على سبيل المثال، بمجرد أن يصبح \"عميل جديد\" \"فرصة مؤهلة\"، يجب إلغاء ربط وسم \"عميل جديد\". هذا يبقي الواجهة البصرية مركزة على *الإجراء المطلوب التالي*.\n\n### 2. التنظيف التلقائي للبيانات \"القديمة\"\nفي الحسابات ذات المجلدات الكبيرة، يمكن أن تتراكم التصنيفات بمرور الوقت. استخدم هذه الواجهة مع وظيفة مجدولة لإلغاء ربط التصنيفات \"المؤقتة\" بعد فترة محددة من الخمول (مثلاً 7 أيام).\n\n---\n\n## 🎯 أفضل الممارسات\n\n1. **تجنب تكدس التصنيفات**: حافظ على سياسة \"الحد الصارم\" لدردشاتك. إذا كان للدردشة أكثر من 3 تصنيفات، فهذا يشير عادةً إلى أن علامات المرحلة السابقة لم يتم إلغاء ربطها بشكل صحيح.\n2. **انتقالات مدفوعة بالحالة**: اجعل إلغاء الربط جزءاً أساسياً من منطق البوت الخاص بك. إذا أنهى البوت تدفق جمع المعلومات، يجب عليه إلغاء ربط تصنيف \"جاري جمع المعلومات\" كإجراء نهائي.\n3. **المزامنة في الوقت الفعلي**: تأكد من ربط حدث \"حذف الوسم\" في نظام CRM الخاص بك بهذه الواجهة، لبقاء رؤية الوكيل في واتساب متزامنة تماماً مع مصدر الحقيقة في قاعدة بيانات عملك.\n      ",
          "tips": [
            {
              "title": "تنظيف",
              "content": "يزيل علاقة ملصق محددة، وليس الملصق نفسه."
            },
            {
              "title": "مزامنة",
              "content": "تنعكس التغييرات فورًا عبر جميع الأجهزة."
            }
          ],
          "recommendations": [
            "قم بإزالة ملصقات 'جديد' بمجرد رد الوكيل.",
            "قم بمراجعة الدردشات القديمة بشكل دوري لإزالة الملصقات القديمة."
          ]
        }
      }
    },
    {
      "path": "/v2/labels/chats/{chatId}",
      "methods": [
        "GET"
      ],
      "title": "Get Chat Labels",
      "category": "Labels",
      "description": "Get all labels assigned to a specific chat.",
      "extraInfo": "\n# Reading the Thread Metadata: Fetch All Labels for a Chat\n\nIndividual conversations often wear many hats. A single chat with a customer might simultaneously be a \"VIP,\" have a \"Pending Payment,\" and be \"Assigned to Alice.\" The **Get Chat Labels** endpoint allows you to retrieve the full array of labels currently attached to a specific chat identifier.\n\n---\n\n## 🏗️ Core Concept\n\nThis endpoint is the primary tool for **Conversational Discovery**. It answers the question: \"What is the current business context of this specific thread?\"\n\n### Key Capabilities:\n1.  **UI Hydration**: Populate the \"tags\" or \"labels\" section of your custom agent dashboard when a chat is selected.\n2.  **Conditional Logic**: Trigger different bot responses or agent alerts based on the chat's existing labels.\n3.  **State Audit**: Verify if a chat has correctly transitioned through your workflow stages (e.g., ensuring \"Lead\" was removed before \"Customer\" was added).\n\n---\n\n## 🚀 Priority Use Cases\n\n### 1. Smart Auto-Replies\nAdjust your bot's tone or logic based on the user's current categories.\n```javascript\nconst labels = await api.getLabelsForChat('123456789@c.us');\nconst isVIP = labels.some(l => l.name === 'VIP');\n\nif (isVIP) {\n  await api.sendText(chatId, \"Hello VIP! We've prioritized your request for immediate agent review.\");\n} else {\n  await api.sendText(chatId, \"Thanks for your message. We'll get back to you soon!\");\n}\n```\n\n### 2. CRM \"State Refresh\"\nWhen an agent opens a contact in your CRM, fetch the latest WhatsApp labels to ensure the external CRM state matches the reality of the WhatsApp thread.\n\n### 3. Preventing Duplicate Tags\nBefore adding a label, check if it's already present to avoid redundant API calls (though the add-label operation is idempotent).\n\n---\n\n## 🔄 State Consistency & Synchronization\n\nIn a multi-agent environment, ensuring that every agent sees the same labels at the same time is critical for preventing duplicated work.\n\n### The \"Stale Data\" Challenge\nIf Agent A adds a \"Processing\" label while Agent B is looking at the same chat, Agent B's dashboard may still show \"Unassigned.\" \n*   **The Check-Before-Action Rule**: Before an agent clicks \"Send Invoice,\" your backend should call this endpoint to verify the chat hasn't already been tagged with \"Invoice Sent\" by another automated process or agent.\n*   **Websocket Pushing**: Listen to [`label.chat.added`](/v2/webhooks/label-chat-added) and [`label.chat.removed`](/v2/webhooks/label-chat-removed) webhooks. When they arrive, use this endpoint to fetch the *full current state* and push it via Websockets to all active agent browsers.\n\n---\n\n## 🛡️ Audit Logging & Compliance\n\nLabels are often used to trigger significant business events (e.g., tagging a chat \"Refund Approved\" to trigger a payment gateway).\n\n### Building an Audit Trail\nWhatsApp does not natively store a history of *who* applied a label and *when*. We recommend:\n1.  **Intercepting API Calls**: Every time your system calls [`PUT /v2/labels/{id}/chats/{chatId}`](/v2/labels/{id}/chats/{chatId}), log the user ID of the agent who initiated it.\n2.  **Snapshotting States**: Periodically use this **Get Chat Labels** endpoint to take a snapshot of high-value chats to track their journey through your funnel.\n\n---\n\n## 🛠️ Integration Patterns: Visual Feedback Systems\n\n### The \"Label Badge\" Hydration\n1.  **Fetch List**: Call this endpoint for the active chat.\n2.  **Map Styles**: Cross-reference the `color` index with your local CSS theme.\n3.  **Render**: Display a horizontal list of badges in your sidebar.\n\n```javascript\nasync function renderChatMetadata(chatId) {\n  const currentLabels = await api.getLabelsForChat(chatId);\n  \n  return currentLabels.map(label => ({\n     text: label.name,\n     bgcolor: label.colorHex,\n     isUrgent: label.color === 0 // Red index\n  }));\n}\n```\n\n---\n\n## ⚠️ Important Behaviors & Edge Cases\n\n*   **Multi-Label Support**: WhatsApp supports multiple labels per chat. This endpoint always returns an **array**, which may be empty if no labels are applied.\n*   **Id/Name/Color Trio**: Each label in the response includes its unique ID, name, current color index, and hex code.\n*   **Performance**: This is a lightweight call. However, if building a high-volume dashboard, consider caching the results until a webhook is received.\n\n---\n\n## 🤖 Advanced Integration: Bot Interaction Patterns\n\nWhen building an automated assistant, the labels attached to a chat act as a \"Contextual Memory.\"\n\n### The \"Label-Aware\" Bot\nYour bot can query this endpoint at the start of a session to determine the user's tier or status.\n1.  **Incoming Message**: User says \"Price check.\"\n2.  **Lookup**: Bot calls this endpoint.\n3.  **Branching logic**:\n    *   If label \"Wholesale\" (ID 5) exists → Give bulk pricing.\n    *   If label \"Retail\" (ID 2) exists → Give standard pricing.\n    *   If no labels exist → Ask the user for their customer type.\n\n```javascript\nasync function getBotResponse(chatId, message) {\n  const meta = await api.getLabelsForChat(chatId);\n  const isWholesale = meta.some(l => l.id === '5');\n  \n  if (message.includes('price')) {\n    return isWholesale ? getBulkPriceList() : getStandardPriceList();\n  }\n}\n```\n\n---\n\n## 🎯 Best Practices\n\n1.  **Don't Over-Poll**: Use [Webhooks](/v2/webhooks) to keep your local database in sync instead of calling this every time a message is received.\n2.  **Handle Empty States**: Gracefully render your UI when the response is an empty array `[]`.\n3.  **Cross-Reference with Global Directory**: Use the results here alongside the [`Get All Labels`](/v2/labels) list to provide a full \"Label Picker\" experience for agents.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Association",
          "content": "Returns all chats associated with a specific label ID."
        },
        {
          "type": "info",
          "title": "Pagination",
          "content": "Supports cursor-based pagination for large lists."
        }
      ],
      "recommendations": [
        "Use this to build 'Smart Views' in your custom CRM.",
        "Fetch only the necessary fields to optimize performance."
      ],
      "args": {
        "chatId": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the chat (e.g., 123456789@c.us)",
          "example": "123456789@c.us"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "List of labels for the chat",
          "example": [
            {
              "id": "1",
              "name": "New Customer",
              "color": 0,
              "colorHex": "#ff9485"
            }
          ]
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Parameter Format",
          "contentType": "application/json",
          "example": {
            "code": "invalid_param",
            "message": "Invalid format for one or more parameters.",
            "details": {
              "param": "text",
              "value": "too_long",
              "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "جلب تصنيفات الدردشة",
          "description": "الحصول على جميع التصنيفات المعينة لدردشة محددة.",
          "tips": [
            {
              "title": "الاقتران",
              "content": "يعيد جميع الدردشات المرتبطة بمعرف ملصق محدد."
            },
            {
              "title": "تقسيم الصفحات",
              "content": "يدعم تقسيم الصفحات المستند إلى المؤشر للقوائم الكبيرة."
            }
          ],
          "recommendations": [
            "استخدم هذا لبناء 'طرق عرض ذكية' في نظام إدارة علاقات العملاء (CRM) المخصص لديك.",
            "اجلب الحقول الضرورية فقط لتحسين الأداء."
          ],
          "args": {
            "chatId": {
              "description": "المعرف الفريد للدردشة (مثلاً: 123456789@c.us)"
            }
          },
          "extraInfo": "\n# قراءة بيانات المحادثة: جلب جميع تصنيفات دردشة محددة\n\nغالباً ما تحمل المحادثات الفردية سمات متعددة. قد يكون لدردشة واحدة مع عميل تصنيف \"VIP\"، ولديها \"دفع معلق\"، وتكون \"محالة للموظفة سارة\" في نفس الوقت. تتيح لك نقطة نهاية **جلب تصنيفات الدردشة** استرداد المجموعة الكاملة من التصنيفات المرفقة حالياً بمعرف دردشة معين.\n\n---\n\n## 🏗️ المفهوم الأساسي\n\nهذه الواجهة هي الأداة الأساسية لـ **الاكتشاف في المحادثة**. فهي تجيب على السؤال: \"ما هو سياق العمل الحالي لهذه المحادثة المحددة؟\"\n\n### القدرات الرئيسية:\n1. **إماهة الواجهة**: ملء قسم \"التصنيفات\" في لوحة تحكم الوكيل عند اختيار دردشة.\n2. **المنطق الشرطي**: إطلاق ردود بوت مختلفة أو تنبيهات وكلاء بناءً على تصنيفات الدردشة الموجودة.\n3. **تدقيق الحالة**: التحقق مما إذا كانت الدردشة قد انتقلت بشكل صحيح عبر مراحل سير العمل.\n\n---\n\n## 🚀 حالات الاستخدام ذات الأولوية\n\n### ردود تلقائية ذكية\nاضبط لهجة البوت أو منطقه بناءً على فئات المستخدم الحالية. يمكنك التحقق مما إذا كان المستخدم يحمل تصنيف \"VIP\" لتعطيه أولوية في الرد أو تحيله فوراً لوكيل بشري.\n\n### تحديث حالة CRM\nعندما يفتح وكيل جهة اتصال في نظام CRM الخاص بك، اسحب أحدث تصنيفات واتساب لضمان تطابق حالة CRM الخارجية مع واقع محادثة واتساب.\n\n---\n\n## 🔄 اتساق الحالة والمزامنة\nفي بيئة متعددة الوكلاء، يعد ضمان رؤية جميع الوكلاء لنفس التصنيفات في نفس الوقت أمراً حيوياً لمنع تكرار العمل.\n* **تحدي البيانات القديمة**: إذا أضاف الوكيل \"أ\" تصنيف \"قيد المعالجة\" بينما ينظر الوكيل \"ب\" إلى نفس الدردشة، فقد تظل لوحة الوكيل \"ب\" تظهر \"غير معين\".\n* **قاعدة التحقق قبل الإجراء**: قبل أن ينقر الوكيل على \"إرسال فاتورة\"، يجب على نظامك استدعاء هذه الواجهة للتحقق من أن الدردشة لم يتم وسمها بالفعل بـ \"تم إرسال الفاتورة\" من قبل وكيل آخر أو عملية آمنة.\n\n---\n\n## 🎯 أفضل الممارسات\n\n1. **لا تفرط في الاستعلام**: استخدم [الويب هوك](/v2/webhooks) للحفاظ على مزامنة قاعدة بياناتك المحلية بدلاً من استدعاء هذه الواجهة مع كل رسالة واردة.\n2. **التعامل مع الحالات الفارغة**: صمم واجهتك بحيث تتعامل بشكل لائق مع المصفوفة الفارغة `[]` عندما لا يكون هناك تصنيفات.\n3. **الربط بالدليل العالمي**: استخدم النتائج هنا مع قائمة [جلب جميع التصنيفات](/v2/labels) لتوفير تجربة \"اختيار تصنيفات\" كاملة للوكلاء.\n            "
        }
      }
    },
    {
      "path": "/v2/labels/chats/{chatId}",
      "methods": [
        "PUT"
      ],
      "title": "Set Chat Labels",
      "category": "Labels",
      "description": "Overwrite all labels for a specific chat.",
      "extraInfo": "\n# Decisive State Management: Overwriting All Chat Labels\n\nWhile adding and removing labels individually is useful for incremental updates, the **Set Chat Labels** endpoint is designed for **Atomic State Transitions**. It allows you to define the exact set of labels a chat should have, effectively overwriting any existing tags in a single operation.\n\n---\n\n## 🏗️ Core Concept\n\nThis endpoint is the primary tool for **Full State Sync**. Instead of calling \"Add\" three times and \"Remove\" twice to update a chat's context, you provide an array of all intended Label IDs (e.g., `[\"1\", \"2\"]`). WhatsApp will ensure those specific labels are applied and all others are removed.\n\n### Key Capabilities:\n1.  **Mass Migration**: Instantly move a chat from \"Outdated Campaign\" tags to a new set of \"Retention\" tags.\n2.  **State Synchronization**: Force the WhatsApp thread to match the exact state of your external CRM record.\n3.  **Atomic Updates**: Ensure that a chat is never in an inconsistent state (e.g., having both \"Active\" and \"Closed\" labels at the same time).\n\n---\n\n## 🚀 Priority Use Cases\n\n### 1. The CRM \"Master Sync\"\nEvery time a contact's status changes in your CRM, push the new reality to WhatsApp.\n```javascript\nasync function syncLabelsFromCRM(chatId, crmTags) {\n  // Map CRM tags to WhatsApp Label IDs\n  const labelIds = crmTags.map(tag => tagMap[tag]).filter(Boolean);\n  \n  // Force WhatsApp to match CRM exactly\n  await api.setChatLabels(chatId, labelIds);\n  console.log(`Synchronized labels for ${chatId}: ${labelIds.join(', ')}`);\n}\n```\n\n### 2. Funnel Stage Transitions\nWhen a user graduates from \"Trial\" to \"Paid subscriber,\" you want to clear all \"Trial-related\" metadata and apply \"Subscriber\" metadata.\n```javascript\n// Moving from Trial to Active\nawait api.setChatLabels(chatId, [subscriberLabelId, highValueLabelId]);\n// All previous tags like \"Trial Day 3\", \"Demo Scheduled\" are wiped.\n```\n\n---\n\n## ⚡ Technical Depth: Transactional Safety\n\nBecause this endpoint is **destructive** (it removes anything not mentioned), it should be treated with the same caution as a database `UPDATE` command.\n\n### The \"Get-Modify-Set\" Pattern\nIf you want to add a label while ensuring you strictly control the other labels, use this pattern:\n1.  **Get Current**: Call [`GET /v2/labels/chats/{chatId}`](/v2/labels/chats/{chatId}).\n2.  **Filter**: Locally add/remove the IDs you want.\n3.  **Set**: Call this endpoint with the final array.\n\nThis is safer than incremental calls in high-latency environments where multiple systems might be trying to tag the same chat.\n\n---\n\n## �️ Reliability & Webhook Orchestration\n\nEvery Label ID added or removed during this operation will trigger a corresponding webhook event. \n\n### Webhook Noise Management\nIf your system listens to [`label.chat.added`](/v2/webhooks/label-chat-added), setting 5 labels at once will fire **5 webhooks**. \n*   **Recommendation**: Disable automated logic for a specific chat ID for 5-10 seconds after calling this endpoint to allow the \"dust to settle\" on the remote WhatsApp account.\n*   **Idempotency**: If you set the same labels the chat already has, no webhooks will fire, making this a safe operation to run on a daily sync cron job.\n\n---\n\n## 🛠️ Integration Patterns: Advanced State Sync\n\n### Multi-Agent \"Locking\" System\nUse a specific \"Locked by [Agent Name]\" label. When an agent grabs a chat, use this endpoint to remove \"Unassigned\" and add \"Locked by Agent X\" in one atomic jump.\n\n### The \"Clean Slate\" Pattern\nTo remove **all** labels from a chat without deleting the labels themselves, simply send an empty array:\n```javascript\nawait api.setChatLabels(chatId, []);\n```\n\n---\n\n## ⚠️ Important Behaviors & Edge Cases\n\n*   **Destructive Overwrite**: Any Label ID **not** included in your request will be **removed** from the chat. Use with caution.\n*   **Array Limit**: While you can theoretically send many IDs, keep the array to a reasonable size (<20) as WhatsApp only supports a limited number of labels per account.\n*   **Validation**: If you provide a non-existent Label ID in the array, the entire request may fail with a `400 Bad Request`. Always verify your Label IDs before setting.\n\n---\n\n## � Disaster Recovery & Rollback Strategies\n\nBecause this endpoint is destructive, having a \"safety net\" is a recommended architectural pattern.\n\n### Implementing a \"Soft Delete\" Buffer\nBefore calling this endpoint to clear labels:\n1.  **Snapshot**: Store the current label IDs in a `previousLabels` field in your own database.\n2.  **Delay**: Wait 30 seconds.\n3.  **Rollback Option**: If an agent realized they made a mistake, they can click \"Undo,\" which calls this endpoint again with the `previousLabels` array.\n\n### Visual State Verification\nAfter every set operation, we recommend calling [`GET /v2/labels/chats/{chatId}`](/v2/labels/chats/{chatId}) one last time to verify the WhatsApp server has correctly applied the changes. This ensures your frontend is never out of sync with Meta's actual state.\n\n---\n\n## �🎯 Best Practices\n\n1.  **Read Before Write (If Unsure)**: If you only want to add a label without losing existing ones, use the [`Link Label to Chat`](/v2/labels/{id}/chats/{chatId}) endpoint instead.\n2.  **Webhook Awareness**: This operation will trigger both add and remove events for every change made. Ensure your webhook handlers can handle bursts of events.\n3.  **Use for \"Single View\" Dashboards**: This is the best endpoint for UIs that allow agents to select multiple tags from a list and click \"Save Changes.\"\n    ",
      "tips": [
        {
          "type": "warning",
          "title": "Overwrite",
          "content": "This REPLACES all existing labels on the chat with the new set."
        },
        {
          "type": "info",
          "title": "Bulk Action",
          "content": "Efficient for resetting a chat's categorization state."
        }
      ],
      "recommendations": [
        "Use 'add' endpoints instead if you want to preserve existing labels.",
        "Validate all label IDs before sending the request."
      ],
      "args": {
        "chatId": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the chat (e.g., 123456789@c.us)",
          "example": "123456789@c.us"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "labels": {
          "required": true,
          "type": "string[]",
          "description": "Array of label IDs to assign (overwrites existing ones)",
          "example": "[\"1\", \"2\"]"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Labels updated successfully",
          "example": {
            "ok": true
          }
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Parameter Format",
          "contentType": "application/json",
          "example": {
            "code": "invalid_param",
            "message": "Invalid format for one or more parameters.",
            "details": {
              "param": "text",
              "value": "too_long",
              "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "تعيين تصنيفات الدردشة",
          "description": "استبدال جميع التصنيفات لدردشة محددة.",
          "tips": [
            {
              "title": "استبدال",
              "content": "هذا يستبدل جميع الملصقات الموجودة في الدردشة بالمجموعة الجديدة."
            },
            {
              "title": "إجراء جماعي",
              "content": "فعال لإعادة تعيين حالة تصنيف الدردشة."
            }
          ],
          "recommendations": [
            "استخدم نقاط نهاية 'إضافة' بدلاً من ذلك إذا كنت تريد الحفاظ على الملصقات الموجودة.",
            "تحقق من صحة جميع معرفات الملصقات قبل إرسال الطلب."
          ],
          "args": {
            "chatId": {
              "description": "المعرف الفريد للدردشة (مثلاً: 123456789@c.us)"
            },
            "labels": {
              "description": "مصفوفة من معرفات التصنيفات للتعيين (تستبدل الموجودة)"
            }
          },
          "extraInfo": "\n# إدارة الحالة الحاسمة: استبدال جميع تصنيفات الدردشة\n\nبينما يعد إضافة وإزالة التصنيفات بشكل فردي مفيداً للتحديثات البسيطة، تم تصميم نقطة نهاية **تعيين تصنيفات الدردشة** لعمليات **انتقال الحالة الذرية**. تتيح لك تحديد المجموعة الدقيقة من التصنيفات التي يجب أن تحملها الدردشة، مما يؤدي فعلياً إلى استبدال أي وسوم موجودة في عملية واحدة.\n\n---\n\n## 🏗️ المفهوم الأساسي\n\nهذه الواجهة هي الأداة الأساسية لـ **المزامنة الكاملة للحالة**. بدلاً من استدعاء \"إضافة\" ثلاث مرات و \"إزالة\" مرتين لتحديث سياق الدردشة، يمكنك توفير مصفوفة لجميع المعرفات المقصودة. سيضمن واتساب تطبيق تلك التصنيفات المحددة وإزالة جميع التصنيفات الأخرى.\n\n### القدرات الرئيسية:\n1. **الهجرة الجماعية**: نقل الدردشة فوراً من وسوم \"حملة قديمة\" إلى مجموعة جديدة من وسوم \"الاحتفاظ\".\n2. **مزامنة الحالة**: إجبار محادثة واتساب على مطابقة الحالة الدقيقة لسجل CRM الخارجي الخاص بك.\n3. **التحديثات الذرية**: ضمان عدم وجود الدردشة في حالة غير متسقة (مثلاً: تحمل وسمي \"نشط\" و \"مغلق\" في آن واحد).\n\n---\n\n## ⚡ العمق التقني: سلامة المعاملات\n\nبما أن هذه الواجهة **تدميرية** (تزيل أي شيء غير مذكور)، يجب التعامل معها بحذر.\n**نمط \"الجلب-التعديل-التعيين\"**:\nإذا كنت تريد إضافة تصنيف مع الحفاظ على التحكم الصارم في التصنيفات الأخرى:\n1. جلب الحالة الحالية للمحادثة.\n2. أضف / أزل المعرفات التي تريدها محلياً.\n3. استدعِ هذه الواجهة بالمصفوفة النهائية.\n\n---\n\n## 🛡️ الموثوقية وتنسيق الويب هوك\n\nسيؤدي كل معرف تصنيف يتم إضافته أو إزالته خلال هذه العملية إلى إطلاق حدث ويب هوك مطابق.\n* **إدارة ضجيج الويب هوك**: إذا كان نظامك يستمع لحدث [إضافة تصنيف لدردشة](/v2/webhooks/label-chat-added)، فإن تعيين 5 تصنيفات في وقت واحد سيطلق 5 أحداث ويب هوك.\n* **التماثل**: إذا قمت بتعيين نفس التصنيفات التي تحملها الدردشة بالفعل، فلن تنطلق أي أحداث ويب هوك، مما يجعلها عملية آمنة للتشغيل في وظائف المزامنة الدورية.\n\n---\n\n## 🎯 أفضل الممارسات\n\n1. **القراءة قبل الكتابة (إذا لم تكن متأكداً)**: إذا كنت تريد فقط إضافة تصنيف دون فقدان التصنيفات الموجودة، استخدم نقطة نهاية [ربط تصنيف بدردشة](/v2/labels/{id}/chats/{chatId}) بدلاً من ذلك.\n2. **اعتبارات الويب هوك**: ستؤدي هذه العملية إلى إطلاق أحداث إضافة وإزالة لكل تغيير يتم إجراؤه. تأكد من أن معالجات الويب هوك لديك يمكنها التعامل مع دفعات من الأحداث.\n3. **تفريغ جميع التصنيفات**: لإزالة **جميع** التصنيفات من دردشة ما، ببساطة أرسل مصفوفة فارغة `[]`.\n            "
        }
      }
    },
    {
      "path": "/v2/groups-overview",
      "methods": [
        "GET"
      ],
      "category": "Groups",
      "isArticle": true,
      "title": "Groups Overview",
      "description": "Learn how to manage WhatsApp groups, participants, and settings using Wawp.",
      "extraInfo": "\n# Orchestrating Communities: The Architecture of WhatsApp Group Engagement\n\nIn the rapidly evolving landscape of digital business communication, the shift from 1:1 messaging to community-driven engagement has become a critical differentiator for high-growth enterprises. The **WhatsApp Groups Ecosystem** is not merely a collection of chat rooms; it is a sophisticated, high-velocity infrastructure for **shared state, collective awareness, and conversational orchestration**. By leveraging the Wawp Groups API, developers and business architects can transform a standard messaging app into a robust, metadata-driven community engine that serves as the backbone for customer onboarding, project coordination, and large-scale event management.\n\nThis guide provides an architectural deep-dive into the strategic value of WhatsApp Groups, outlining how to build resilient, governed, and hyper-efficient community workflows that scale alongside your business objectives.\n\n---\n\n## 🏗️ Architectural Philosophy: The Group as a Distributed State Object\n\nTo master the Groups API, one must first understand its fundamental departure from traditional messaging paradigms. In a standard 1:1 interaction, the state is decentralized and ephemeral, living only in the context of two individuals. A **WhatsApp Group**, however, is a **centralized, persistent State Object** that maintains a global \"Source of Truth\" across up to **1,024 participants**.\n\n### The Dynamics of Shared Context\nEvery group is defined by its metadata—its subject, its description, its icon, and its administrative settings. These are not merely visual flourishes; they are the \"Manifesto\" of the conversation. In an enterprise setting, your system doesn't just \"create a chat\"; it **provisions a context**.\n\n*   **Synchronized Metadata**: When your system updates a group description via the API, that change is instantly propagated to every participant's device. This allows you to use the description field as a dynamic \"Project Status Board\" or a \"Pinned FAQ\" that evolves in real-time as a case progresses.\n*   **Auditability & Persistence**: Because groups are persistent, the entire history of an onboarding flow or a technical escalation remains accessible to all authorized stakeholders. This creates a natural audit trail that is invaluable for compliance and performance review.\n*   **Semantic Segmentation**: Groups allow you to segment your audience not just by their identity (who they are), but by their **Current Objective** (what they are trying to achieve). This moves your communication strategy from \"Mass Broadcasting\" to \"Targeted Orchestration.\"\n\n---\n\n## 🎭 Governance Framework: The Three Pillars of Authority\n\nEffective community management at scale requires a rigorous governance model. The WhatsApp security architecture is built around three distinct tiers of authority, each serving a specific strategic purpose in your automated ecosystem.\n\n### 1. The Creator: The Immutable Anchor of Control\nThe instance that initializes a group is automatically granted **Creator** status. In the hierarchy of WhatsApp permissions, this is the most critical role because it is **irrevocable**. A creator cannot be demoted or removed by any other admin. For developers, this means that as long as your primary WhatsApp Business instance is the one calling the [Create Group](/v2/groups/create) endpoint, your system maintains an absolute \"Kill Switch\" and \"Master Override\" for that community. This prevents \"Hostile Takeovers\" where a participant might gain admin rights and attempt to lock out the business.\n\n### 2. Admins: The Modal Operators\nAdmins are the functional \"Moderators\" of the group state. In a sophisticated integration, your system will often PROMOTE human team members (e.g., account managers or support leads) to admin status. This allows these humans to manage the group natively on their own mobile devices, while your Wawp instance remains the \"Silent Super-Admin,\" handling background tasks like automated welcoming, metadata lockdowns, and security monitoring. Admins have the power to:\n*   Add and remove participants recursively.\n*   Promote or demote regular members to share administrative duties.\n*   Toggle \"Announcement Mode\" (restricting messages to admins only) to manage conversational noise during critical updates.\n\n### 3. Members: The Participation Layer\nMembers represent the audience and the primary objective of the group. Their power is intentionally limited to interaction and observation. Managing this layer requires a delicate balance of **Automated Engagement** and **Proactive Moderation**. Your system's role is to ensure that members feel valued and heard while preventing \"Community Drift\" where the conversation diverges from its intended business purpose.\n\n---\n\n## 🚀 The Managed Lifecycle: From Provisioning to Graceful Retirement\n\nA high-performance community strategy follows a defined, four-part lifecycle. Treating groups as \"Temporary Assets\" ensures that your WhatsApp account remains lean, high-performing, and free of \"Inertia Bloat.\"\n\n### Phase I: Precise Provisioning & Initialization\nCreation should never be an ad-hoc action. Every group should be the result of a specific business trigger—a new signup, a high-value purchase, or a project kick-off. During this phase, your system must define the initial \"Rules of Engagement.\" This includes choosing a highly descriptive subject (e.g., `[VIP-789] Cloud Migration Team`), setting a professional icon, and adding the core stakeholders (the customer and the dedicated agents).\n\n### Phase II: Strategic Hydration\nA new group is a blank canvas. To prevent confusion, your system must immediately \"Hydrate\" the group with context. This involves an automated welcome sequence that outlines the group's purpose, links to relevant resources in the description, and perhaps even uses the [Labels API](/v2/labels-guide) to tag the group internally for easier management in the agent's sidebar. A hydrated group is one where every participant feels the immediate value of being included.\n\n### Phase III: Dynamic State Orchestration\nAs the lifecycle progresses, the group's needs will shift. If a project enters a \"Critical Phase,\" your system might flip the settings to \"Admin Only\" to deliver one-way status updates without the distraction of participant replies. Once the crisis is over, it flips back to \"Collaborative Mode.\" By listening to [`group.participants.update`](/v2/webhooks/group-participants-update) webhooks, your system stays perfectly synchronized with the pulse of the community, reacting instantly when a key stakeholder joins or leaves.\n\n### Phase IV: The Decommissioning Protocol\nThe most common failure in group management is \"Infinite Persistence.\" Once a business objective is met (e.g., the warranty period ends or the project launches), the group should be decommissioned. This involves a graceful closure message followed by your system [leaving the group](/v2/groups/leave) and potentially [deleting it](/v2/groups/delete) to clear the metadata from Meta's servers. This \"Conversational Hygiene\" is essential for long-term account health and agent productivity.\n\n---\n\n## 🔐 Security, Privacy, and the \"Social Proof\" Mandate\n\nBecause groups expose the phone numbers of all participants to one another, they are intrinsically high-trust environments. Managing this \"Participant Visiblity\" is both your greatest branding asset and your largest security liability.\n\n### The Privacy Wall & The Invite Strategy\nWhatsApp enforces a strict \"Privacy Shield\" to protect users. If a user has restricted their privacy settings or if they have blocked your business instance, you cannot add them directly to a group via their phone number. For high-priority communities, you should always implement the **\"Invite-as-Fallback\" Pattern**. If the direct `add` call succeeds, the user is in. If it returns a privacy-related failure, your system should instantly send a 1:1 message to that user containing the [Group Invite Link](/v2/groups/invite-code). This shifts the burden of consent to the user, ensuring your business remains compliant with global privacy standards while still providing a path to join.\n\n### Safeguarding Account Reputation\nMeta's security heuristics are highly sensitive to \"Forced Grouping.\" Adding large numbers of strangers to groups without their prior 1:1 interaction is the fastest way to trigger a permanent account ban. We recommend a \"Social Warm-up\" policy:\n*   Only add users to groups who have already messaged your bot or business number within the last 24 hours.\n*   Keep \"Burst Creation\" to a minimum. Aim for a maximum of 5-10 group creations per hour per instance to stay under the radar of automated spam detectors.\n*   Always provide a clear \"Opt-out\" instruction in the group description, reminding users they can leave at any time.\n\n---\n\n## 🏭 Industry-Specific Orchestration Patterns\n\n### 1. Real Estate & Property Management\nIn large property developments, each unit or floor can have its own \"War Room\" group. When a maintenance request is filed, the system adds the tenant, the building manager, and the specific technician to the group. The technician takes photos of the fix, the tenant confirms satisfaction, and the system automatically leaves and archives the group once the ticket is closed in the CRM.\n\n### 2. High-Value Financial Services\nFor \"Wealth Management\" or \"VIP Banking,\" groups replace slow email chains. A group containing the client, their primary banker, and an analyst provides a space for high-fidelity discussion on market moves. The [Labels API](/v2/labels-guide) is used to track the \"Sentiment\" of the group, alerting senior management if a high-value client's tone in the group becomes frustrated.\n\n### 3. Education & Corporate Training\nFor seasonal courses, groups act as **Automated Learning Labs**. Your system creates a group for each cohort, sends daily lesson summaries, coordinates breakout sessions, and uses the [Participants List](/v2/groups/participants) to track which students are the most active \"Peer Leaders\" for potential future internships or roles.\n\n### 4. Healthcare Coordination\nIn post-operative care, a \"Recovery Group\" can include the patient, their family caregiver, and a nurse. The system sends automated \"Check-in\" prompts every 4 hours. If the patient replies with high-pain indicators, the system immediately promotes the nurse to admin so they can take manual control of the recovery conversation.\n\n---\n\n## 🛡️ Best Practices for Enterprise Success\n\n*   **Subject-Line Serialization**: Always include a unique internal database ID in the group subject (e.g., `PROJ-101 | [Subject]`). Since users can rename groups, this hidden \"Serial Number\" allows your system to re-identify the group during a `Get Groups` audit.\n*   **Description-as-Interface**: Treat the group description as a \"Command Console.\" Include the name of the assigned account manager, links to your customer portal, and a list of \"Keyword Commands\" (e.g., *Reply #STATUS for updates*) to empower users.\n*   **Webhook Resilience**: Communities are dynamic. Ensure your backend handles JOIN and LEAVE events with the same priority as incoming messages. A well-timed \"Goodbye\" message when a user leaves can be the difference between a neutral exit and a future referral.\n*   **Color-Coded Management**: Use the [Labels API](/v2/labels-guide) to visually categorize your groups in the agent's view. \"Sales-Led\" groups might be Blue, while \"Escalated-Support\" groups are Red. This minimizes cognitive load for your frontline staff.\n\nBy mastering the Groups API, you aren't just sending messages; you are building a **Conversational Infrastructure** that fosters trust, drives efficiency, and creates a sense of community that traditional communication channels simply cannot match.\n    ",
      "args": {},
      "tips": [
        {
          "type": "warning",
          "title": "Admin Requirement",
          "content": "Modification actions like 'Add Participant' or 'Set Admin Only' will fail if your instance is not a Group Admin."
        }
      ],
      "recommendations": [
        "Store the Group ID (`@g.us`) in your database for future interactions.",
        "Listen for group-related webhooks to track participant changes in real-time.",
        "Always provide a way for users to leave the group if they no longer wish to participate."
      ],
      "responses": [],
      "translations": {
        "ar": {
          "title": "نظرة عامة على المجموعات",
          "description": "تعرف على كيفية إدارة مجموعات واتساب، والمشاركين، والإعدادات باستخدام Wawp.",
          "extraInfo": "\n# إدارة المجتمعات: هندسة التفاعل في مجموعات واتساب\n\nتعد منظومة **مجموعات واتساب** أكثر من مجرد غرف دردشة؛ إنها بنية تحتية متطورة للحفاظ على حالة مشتركة، والوعي الجماعي. من خلال الاستفادة من واجهة برمجة تطبيقات المجموعات في Wawp، يمكن للمطورين تحويل تطبيق مراسلة عادي إلى محرك مجتمعي قوي.\n\n---\n\n## 🎭 إطار الحوكمة: الأركان الثلاثة للسلطة\n\nتتكون بنية الأمان في واتساب من ثلاثة مستويات متميزة من السلطة:\n\n### 1. المنشئ (The Creator): مرساة التحكم\nالمثيل الذي يقوم بإنشاء المجموعة يُمنح تلقائيًا حالة \"المنشئ\". في هرم صلاحيات واتساب، هذا هو الدور الأكثر حرجًا لأنه **غير قابل للإلغاء**. لا يمكن تخفيض رتبة المنشئ أو إزالته بواسطة أي مسؤول آخر.\n\n### 2. المسؤولون (Admins): المشغلون الوظيفيون\nالمسؤولون هم \"المشرفون\" على حالة المجموعة. يتمتع المسؤولون بصلاحيات تشمل:\n*   إضافة وإزالة المشاركين.\n*   ترقية الأعضاء الآخرين إلى رتبة مسؤول.\n*   تفعيل \"وضع الإعلانات\" (حصر المراسلة على المسؤولين فقط) لتقليل الضوضاء.\n\n### 3. الأعضاء: طبقة المشاركة\nالأعضاء يمثلون الجمهور والهدف الأساسي من المجموعة. تنحصر صلاحياتهم في التفاعل والمراقبة.\n\n---\n\n## 🚀 دورة الحياة المدارة: من التجهيز إلى التقاعد\n\nتتبع استراتيجية المجتمع عالية الأداء دورة حياة محددة لضمان بقاء حساب واتساب الخاص بك رشيقًا.\n\n- **المرحلة الأولى: التجهيز الدقيق**: يجب ألا يكون إنشاء المجموعة عشوائيًا، بل نتيجة لمحفز أعمال محدد (تسجيل جديد، شراء عملية، إلخ).\n- **المرحلة الثانية: التفعيل الاستراتيجي**: يجب فوراً تزويد المجموعة بالسياق عبر رسالة ترحيبية آلية توضح غرض المجموعة ووضع القواعد.\n- **المرحلة الثالثة: التنسيق الديناميكي**: مع تقدم دورة الحياة، ستتحول احتياجات المجموعة. قد يحولها النظام إلى \"للمسؤولين فقط\" لتقديم تحديثات هامة.\n- **المرحلة الرابعة: بروتوكول الإغلاق**: بمجرد تحقيق الغرض البزنس (انتهاء المشروع)، يجب إغلاق المجموعة بشكل لائق وإزالتها.\n\n---\n\n## 🛡️ الأمان والخصوصية\n\nنظرًا لأن المجموعات تكشف أرقام هواتف المشاركين لبعضهم البعض، فهي بيئات عالية الثقة.\n*   **حاجز الخصوصية واستراتيجية الدعوة**: إذا كانت إعدادات خصوصية المستخدم تمنع إضافته مباشرة، فيجب على نظامك إرسال رسالة 1:1 تحتوي على **رابط نص الدعوة**.\n*   **حماية سمعة الحساب**: إضافة أعداد كبيرة من الغرباء إلى المجموعات دون تفاعل سابق هو أسرع طريق لحظر الحساب.\n      ",
          "tips": [
            {
              "title": "حقوق المسؤول",
              "content": "تتطلب بعض الإجراءات أن يكون البوت مسؤولاً في المجموعة."
            },
            {
              "title": "حدود المشاركين",
              "content": "المجموعات لها حد أقصى للمشاركين. تحقق من الحدود الحالية في الوثائق."
            }
          ],
          "recommendations": [
            "قم بتخزين معرف المجموعة (@g.us) للرجوع إليه مستقبلاً.",
            "تعامل مع أحداث إضافة/إزالة المشاركين للحفاظ على تزامن الحالة المحلية.",
            "تجنب إضافة أعداد كبيرة من المستخدمين بسرعة لتجنب الحظر."
          ]
        }
      }
    },
    {
      "path": "/v2/groups",
      "methods": [
        "GET"
      ],
      "title": "Get All List groups",
      "category": "Groups",
      "description": "Retrieve a list of all groups the instance is a member of.",
      "extraInfo": "\n# Global Inventory: The Strategic Audit of Your Group Footprint\n\nIn a high-scale WhatsApp deployment, your business account doesn't just manage individual messages; it manages an entire ecosystem of communities. The **Get All Groups** endpoint is your primary tool for **Conversational Resource Management**. It provides a top-down, panoramic view of every shared state—every \"War Room,\" every \"Customer Onboarding Group,\" and every \"Marketing Cohort\"—that your instance is currently a part of. This endpoint is the foundation for ecosystem auditing, bulk state synchronization, and long-term conversational hygiene.\n\nFor developers and architects, \"Listing Groups\" is not just about showing a table of names; it is about **Inventorying Business Assets** and identifying where your automated presence is most active—and where it might be lingering beyond its useful life.\n\n---\n\n## 🏗️ Architectural Philosophy: The Macro-View of Shared State\n\nWhereas the [Get Group](/v2/groups/{id}) endpoint provides high-fidelity depth for a single community, the **Get All Groups** endpoint provides the breadth required for systemic management.\n\n### Key Architectural Objectives:\n*   **Contextual Inventory**: This endpoint returns an array of metadata for every group associated with the instance. This is critical for \"Bootstrapping\" your internal CRM. When you first connect a WhatsApp account to your platform, you use this endpoint to map the pre-existing reality of the account into your database, ensuring that no \"Legacy Group\" is left un-managed.\n*   **Orphaned Flow Detection**: In complex automation environments, a group might be created but, due to a bug or a missing business trigger, it might never be correctly linked to a customer record. By fetching the full list of groups, your system can perform a **\"Reconciliation Audit\"**—comparing the list of active WhatsApp groups against your internal database. Any group found on WhatsApp but not in your database is an \"Orphaned State\" that requires manual review or automated cleanup.\n*   **Permission Census**: This endpoint provides a quick snapshot of the instance's role in each community. By auditing the `participants` array across all groups, your system can identify which communities it still controls as an **Admin** and which ones it has been demoted in. This \"Permission Awareness\" is vital for prioritizing where your bots can execute governance and where they are restricted to mere observation.\n\n---\n\n## 🚀 Strategic Operational patterns: Ecosystem Hygiene\n\nA healthy WhatsApp account is one that is lean and purposeful. The Get All Groups endpoint is the engine behind your **Decommissioning Workflows**.\n\n### 1. The Rolling Archive Protocol\nProfessional enterprises implement a \"Rolling Audit\" every 7 to 30 days. Your system fetches the full list of groups and maps them to their last interaction timestamps. Any group that has had zero activity for more than 90 days—and is not marked as a \"Permanent VIP Channel\" in your CRM—becomes a candidate for the [Delete Group](/v2/groups/delete) endpoint. This \"Conversational Pruning\" keeps your agent's interface focused on active leads and reduces the long-term data footprint on your servers.\n\n### 2. Multi-Instance Load Balancing\nIf your enterprise uses multiple WhatsApp instances to manage a massive community (e.g., thousands of property tenants), the Get All Groups endpoint allows you to track the **Distribution of Responsibility**. By auditing the group counts across different instances, your system can decide which instance has the most \"headroom\" to create the next new group, preventing any single account from hitting Meta's undocumented saturation limits.\n\n### 3. Identity Resolution for Manual Creations\nAgents often create groups manually via the mobile WhatsApp app to handle ad-hoc customer requests. These groups are \"Invisible\" to your automation until identified. By periodically calling Get All Groups, your system can \"Discover\" these manually created communities, parse their names for Project IDs, and automatically import them into your official CRM flow, ensuring that manual agent work is captured in your high-level business analytics.\n\n---\n\n## 🔐 Security & Governance: Auditing the Membership List\n\nGroups are inherently high-trust, but they are also potential data leak points. The Get All Groups endpoint allows for **Global Compliance Auditing**.\n\n### Participant Sentiment & Prohibited Presence\nFor highly regulated industries (such as Banking or Insurance), your system must ensure that no unauthorized JIDs are present in your business groups. By fetching the participant list for all groups in bulk, you can run a \"Compliance Scan\" against your global blacklist. If an instance of an unauthorized number is found in *any* group, your system can trigger an immediate alert to your security team or execute an automated removal.\n\n### Tracking the \"Administrative Footprint\"\nManaging the number of admins in your ecosystem is a critical security task. Too many admins increases the risk of accidental group deletion or unauthorized settings changes. This endpoint allows you to audit the \"Admin Density\" across your entire account. If a regular project member has been promoted to admin without a corresponding approval in your internal HR system, your system can automatically demote them back to member status, maintaining a \"Strict Governance\" posture.\n\n---\n\n## ⚙️ Performance & Scaling: Batching vs. Real-Time Sync\n\nFetching all groups can be a relatively \"Expensive\" operation for accounts that are members of hundreds or thousands of communities. To maintain a high-performance system, follow these principles:\n\n1.  **Avoid Excessive Polling**: Never call this endpoint in a tight loop. Instead, use a scheduled background job (e.g., once every 6-24 hours) to perform the \"Global Reconciliation.\" \n2.  **Rely on Event-Driven Updates**: For real-time changes, always prioritize the [`group.update`](/v2/webhooks/group-update) and [`group.participants.update`](/v2/webhooks/group-participants-update) webhooks. The Get All Groups endpoint should be seen as the \"Self-Correction\" mechanism that runs periodically to catch any events that might have been missed due to network instability.\n3.  **Pagination & Metadata Filtering**: When processing the results, prioritize the `id` and `subject` fields first. Only dig into the full `participants` array for groups that your internal audit has flagged as \"High Priority\" or \"Compliance Vulnerable.\"\n\n---\n\n## 🎯 Conclusion: Mastering the Landscape of Shared State\n\nThe **Get All Groups** endpoint is your primary instrument for architectural discipline. It allows you to move beyond the management of individual threads and start managing the **Total Landscape of Your Presence**. By implementing robust reconciliation, decommissioning, and discovery workflows around this endpoint, you ensure that your WhatsApp infrastructure remains optimized, governed, and perfectly synchronized with your business's strategic objectives. You turn a crowded inbox into a highly structured, metadata-driven community engine.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Performance",
          "content": "Scanning thousands of groups can be slow. Use filters if available."
        },
        {
          "type": "positive",
          "title": "Sync",
          "content": "Use this to bootstrap your local database on startup."
        }
      ],
      "recommendations": [
        "Run this once at startup, then rely on webhooks for incremental updates.",
        "Filter out 'Announce' groups if your bot needs two-way communication.",
        "Periodically reconcile this list with your database to find 'Ghost Groups'."
      ],
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "List of groups retrieved successfully",
          "example": [
            {
              "id": "1234567890@g.us",
              "name": "Project Team",
              "participants": []
            }
          ]
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "جلب قائمة المجموعات",
          "description": "استرداد قائمة بجميع المجموعات التي يشترك فيها هذا المثيل.",
          "extraInfo": "\n# الجرد الشامل: التدقيق الاستراتيجي لانتشارك في المجموعات\n\nفي عمليات واتساب واسعة النطاق، لا تدير شركتك مجرد رسائل فردية، بل تدير منظومة كاملة من المجتمعات. واجهة **جلب جميع المجموعات** هي أداتك الأساسية لـ **إدارة موارد المحادثات**. إنها توفر رؤية شاملة لكل حالة مشتركة — سواء كانت \"غرفة طوارئ\" أو \"مجموعة استقبال عملاء\" — يشترك فيها مثيلك حالياً.\n\n---\n\n## 🏗️ الفلسفة المعمارية: النظرة الكلية للحالة المشتركة\n\nتوفر هذه الواجهة \"الاتساع\" المطلوب للإدارة النظامية لمجتمعاتك.\n*   **جرد السياق**: تُرجع هذه الواجهة مصفوفة من البيانات الوصفية لكل مجموعة، وهو أمر حيوي لـ \"ربط\" نظام CRM الخاص بك بالواقع الفعلي لحساب واتساب.\n*   **اكتشاف التدفقات المفقودة**: في الأتمتة المعقدة، قد يتم إنشاء مجموعة ولكن لا يتم ربطها بشكل صحيح بسجل العميل. من خلال جلب القائمة الكاملة، يمكن لنظامك إجراء **\"تدقيق مطابقة\"** للتأكد من أن كل مجموعة في واتساب لها مقابل في قاعدة بياناتك.\n\n---\n\n## 🚀 أنماط التشغيل الاستراتيجية\n\n### 1. بروتوكول الأرشفة الدورية\nتجري المؤسسات الاحترافية \"تدقيقاً دورياً\" كل 7 إلى 30 يوماً. يتم جلب القائمة الكاملة وتحديد المجموعات التي لا نشاط فيها لأكثر من 90 يوماً لإغلاقها، مما يحافظ على واجهة الوكلاء منظمة.\n### 2. اكتشاف المجموعات المنشأة يدوياً\nغالباً ما ينشئ الوكلاء مجموعات يدوياً عبر تطبيق واتساب. هذه المجموعات تكون \"غير مرئية\" للأتمتة حتى يتم اكتشافها عبر هذه الواجهة وربطها بسير عمل الـ CRM الرسمي.\n            ",
          "tips": [
            {
              "title": "الأداء",
              "content": "يمكن أن يكون مسح آلاف المجموعات بطيئًا. استخدم المرشحات إن وجدت."
            },
            {
              "title": "المزامنة",
              "content": "استخدم هذا لتمهيد قاعدة بياناتك المحلية عند بدء التشغيل."
            }
          ],
          "recommendations": [
            "قم بتشغيل هذا مرة واحدة عند بدء التشغيل، ثم اعتمد على Webhooks للتحديثات التزايدية.",
            "قم بتصفية مجموعات 'الإعلان' إذا كان الروبوت الخاص بك يحتاج إلى اتصال ثنائي الاتجاه.",
            "قم بتسوية هذه القائمة بشكل دوري مع قاعدة بياناتك للعثور على 'المجموعات الشبح'."
          ]
        }
      }
    },
    {
      "path": "/v2/groups/create",
      "realPath": "/v2/groups",
      "methods": [
        "POST"
      ],
      "title": "Create group",
      "category": "Groups",
      "description": "Create a new WhatsApp group with specified name and participants.",
      "extraInfo": "\n# Semantic Initialization: The Genesis of Distributed Communities\n\nThe **Create Group** endpoint sits at the very heart of your conversational architecture. It is far more than a simple technical request to allocate a new chat identifier; it is a strategic operation that establishes a **programmatic shared context** between your business and a specific set of participants. By moving the group creation process from the manual efforts of an agent to the precision of an API, you ensure that every new project, every VIP customer onboarding, and every internal coordination team begins its lifecycle with the correct branding, the exact stakeholders, and a strictly defined set of permissions.\n\nIn an enterprise environment, \"Creating a Group\" is the act of **Provisioning a Managed Asset**. This guide explores the architectural nuances and strategic imperatives of building communities through initialization.\n\n---\n\n## 🏗️ Architectural Philosophy: Atomic State Allocation\n\nFrom a system design perspective, creating a group is an **Atomic Operation**. In a single transaction, your system defines both the **Identity** of the community and its **Initial Population**. This synchronicity is critical for maintaining consistency between your backend CRM and the reality of the WhatsApp network.\n\n### The Dynamics of the Global-JID (G-JID)\nWhen a group is born through this endpoint, the WhatsApp network generates a unique, immutable identifier ending in `@g.us`. This \"G-JID\" is the most important piece of metadata your system will ever handle for that community.\n*   **Persistence & Mapping**: Unlike user phone numbers, which can occasionally change or be recycled, the group ID is permanent. Your system must treat this ID as the **Primary Key** in your internal database. All future interactions—sending messages, updating settings, or auditing participants—must be anchored to this specific ID.\n*   **Zero-Latency Inclusion**: The participants you define in the creation call are added to the state immediately. There is no invitation process or \"acceptance window\" required when adding users via this endpoint. They are instantly merged into the shared context, allowing your system to follow up the creation call with a welcome message that is seen by all members the very second they are joined.\n\n---\n\n## 🎭 The Creator’s Mandate: Establishing Permanent Governance\n\nThe most critical strategic outcome of using the Wawp API for group creation is the automatic assignment of **Creator** status to your instances. In the WhatsApp governance hierarchy, the Creator role is unique and powerful.\n\n### Irrevocable Authority\nAs the creator of the group, your instance holds a level of authority that no other admin can challenge. A creator cannot be demoted, and they cannot be removed by other administrators. This provides a \"Steel-Clad Safeguard\" for your business communications. Even if a participant is accidentally promoted to admin and attempts to \"take over\" the group, your system retains absolute control. This allows you to build high-trust collaborative environments while maintaining the peace of mind that your business owns the channel, the data, and the membership list.\n\n---\n\n## 🚀 Strategic Participant Management: Trust and the Privacy Wall\n\nManaging who enters a group is as important as the messages sent within it. Because groups expose the phone numbers of all participants to one another, initialization is a \"High-Sensitivity\" operation that must be balanced with user privacy.\n\n### Navigating the Privacy Shield\nWhatsApp provides robust privacy settings for individual users. If a user has restricted group adds to \"My Contacts Only,\" or if they have blocked your business instance, a direct `add` during the creation process will return a success signal from the API, but the user will **not** actually appear in the group list. \nFor mission-critical communities (like a project team), your system should implement an **\"Invite-as-Fallback\"** strategy. After the group is created, verify the participant list. If a key stakeholder is missing due to privacy restrictions, your system should automatically send a 1:1 message to that user containing the [Group Invite Link](/v2/groups/invite-code). This ensures that participation is both easy and consensual.\n\n### The \"Social Proof\" Requirement\nTo maintain a high account health score, avoid adding large numbers of stranger numbers to a single group. Meta's heuristics look for \"forced interaction.\" We recommend that your system only creates groups with participants who have had at least one 1:1 interaction with your business number in the past. This \"pre-existing relationship\" signals to the WhatsApp network that the group is a legitimate continuation of a business conversation, not a spam vector.\n\n---\n\n## 🎨 Optimizing the Group \"Manifesto\": Subjects, Descriptions, and Icons\n\nThe metadata defined during creation forms the \"First Impression\" for your participants. Every element of the group's visual identity should be optimized for clarity and professional branding.\n\n### The \"Subject Line\" Economy\nWhile technically flexible, group names should be treated like subject lines in a professional email. Use **Serialization and Prefixes** (e.g., `[VIP-2024] - Wawp Onboarding`). This makes it possible for agents to search their inbox effectively and ensures that users know exactly why they have been added to a new chat.\n\n### The Description as a Command Center\nThe group description is the only part of the group's metadata that can hold a significant amount of text. Use it wisely. We recommend using the description field to host:\n*   Standard Operating Procedures (SOPs) for the group.\n*   Links to external customer portals or support documentation.\n*   A list of \"Bot Commands\" that participants can use to interact with your system.\n\n---\n\n## 🛠️ Enterprise Workflow patterns: Automated War Rooms\nThe true power of the Create Group endpoint is realized when it is integrated into your broader business logic.\n\n### Scenario: The Automated Escalation War Room\nWhen your monitoring system detects a \"Severity 1\" incident for a client, it doesn't just send an alert. It instantly calls the Create Group endpoint. It builds a \"War Room\" containing the client's CTO, your assigned account manager, and the lead technical specialist. The group is named `INCIDENT-999 | Critical Alert`. Within seconds, all necessary stakeholders are in a single room, sharing screenshots and logs in real-time, drastically reducing the \"Mean Time to Resolution\" (MTTR).\n\n### Scenario: The Onsite Event Coordination Engine\nFor a physical conference, your system creates a \"Breakout Group\" for each seminar session. As users scan a QR code at the door, they are added to the group. This allows the speaker to share slides instantly and allows attendees to ask questions via the chat, which your bot can then aggregate and present to the speaker at the end of the session.\n\n---\n\n## 🛡️ Operational Guardrails & Rate Management\n\nInitialization is a \"Heavy\" operation on the WhatsApp infrastructure. To ensure long-term reliability and stay within Meta's undocumented rate limits, follow these engineering principles:\n\n1.  **Staggered Creation**: Avoid \"Creation Bursts\" (e.g., 100 groups in 60 seconds). If your system needs to provision many groups for a campaign, use a background worker to stagger the requests. A rate of 5-10 group creations per hour per instance is considered highly safe for enterprise-grade accounts.\n2.  **Social History Priming**: Ensure your instance has an \"Active Profile.\" An account that does nothing but create groups is often flagged for review. Ensure your instance is also sending 1:1 messages and participating in existing threads to maintain a natural \"Account Signature.\"\n3.  **Local Metadata Buffering**: Once a group is created, store the ID, name, and participant list in a high-speed local cache (like Redis). This allows your frontend to display group information instantly without hitting the API for every page load, improving user experience and reducing API overhead.\n\n---\n\n## 🎯 Conclusion: The Foundation of Community\n\nBy mastering the **Create Group** endpoint, you are building the logical foundation of your conversational enterprise. You are moving beyond the era of \"One-Way Alerts\" and into the era of **Collaborative Customer Success**. When used strategically, this endpoint turns WhatsApp into a dynamic, programmable, and highly governed environment where every shared context is an opportunity for a deeper, more meaningful business relationship.\n    ",
      "tips": [
        {
          "type": "warning",
          "title": "Admin Status",
          "content": "Your bot automatically becomes a Super Admin of the created group."
        },
        {
          "type": "info",
          "title": "Privacy Settings",
          "content": "Users with strict privacy settings may not be added directly; use Invite Links as a fallback."
        }
      ],
      "recommendations": [
        "Always store the returned @g.us ID immediately.",
        "Send a welcome message explaining the group's purpose as soon as it is created.",
        "Limit initial participants to known contacts to avoid spam reports."
      ],
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "name": {
          "required": true,
          "type": "string",
          "description": "Name of the group",
          "example": "New Project"
        },
        "participants": {
          "required": true,
          "type": "array",
          "description": "List of participant JIDs to add to the group",
          "example": "[{\"id\":\"1234567890@c.us\"}]"
        }
      },
      "responses": [
        {
          "status": 201,
          "description": "Group created successfully",
          "example": {
            "id": "1234567890@g.us",
            "name": "New Project"
          }
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request - Invalid Parameter Format",
          "contentType": "application/json",
          "example": {
            "code": "invalid_param",
            "message": "Invalid format for one or more parameters.",
            "details": {
              "param": "text",
              "value": "too_long",
              "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "إنشاء مجموعة",
          "description": "إنشاء مجموعة واتساب جديدة بالاسم والمشاركين المحددين.",
          "tips": [
            {
              "title": "حالة المسؤول",
              "content": "يصبح الروبوت الخاص بك تلقائيًا مسؤولاً متميزًا عن المجموعة التي تم إنشاؤها."
            },
            {
              "title": "إعدادات الخصوصية",
              "content": "قد لا تتم إضافة المستخدمين ذوي إعدادات الخصوصية الصارمة مباشرةً؛ استخدم روابط الدعوة كبديل."
            }
          ],
          "recommendations": [
            "قم دائمًا بتخزين معرف @g.us المرتجع فورًا.",
            "أرسل رسالة ترحيب تشرح الغرض من المجموعة بمجرد إنشائها.",
            "قتصر المشاركين الأوليين على جهات الاتصال المعروفة لتجنب بلاغات الرسائل العشوائية."
          ],
          "extraInfo": "\n# البداية البرمجية: تأسيس المجتمعات الرقمية\n\nتعد نقطة نهاية **إنشاء مجموعة** حجر الزاوية في بنيتك التحتية للمحادثات. إنها أكثر من مجرد طلب تقني؛ إنها عملية استراتيجية تؤسس لسياق مشترك بين عملك والمشاركين. من خلال تحويل عملية إنشاء المجموعات من الجهد اليدوي إلى دقة واجهة برمجة التطبيقات، تضمن أن كل عميل VIP جديد أو فريق تنسيق يبدأ دورة حياته بالهوية الصحيحة وأصحاب المصلحة المعنيين.\n\n---\n\n## 🏗️ الفلسفة المعمارية: تخصيص الحالة الذرية\n\nمن منظور تصميم النظام، يعد إنشاء المجموعة **عملية ذرية**. في معاملة واحدة، يحدد نظامك كلاً من **هوية** المجتمع و **سكانه الأوليين**.\n\n### ديناميكيات معرف المجموعة (G-JID)\nعند إنشاء مجموعة، ينشئ نظام واتساب معرفاً فريداً ينتهي بـ `@g.us`.\n*   **الاستمرارية والربط**: معرف المجموعة دائم ولا يتغير. يجب أن يعامله نظامك كـ **مفتاح أساسي** في قاعدة بياناتك الداخلية.\n*   **الإدراج الفوري**: يتم إضافة المشاركين المحددين فوراً. لا توجد عملية \"قبول دعوة\" مطلوبة عند الإضافة عبر هذه الواجهة، مما يسمح بإرسال رسالة تترحيبية يراها الجميع في اللحظة التي ينضمون فيها.\n\n---\n\n## 🎭 صلاحيات المنشئ: فرض الحوكمة الدائمة\n\nأهم نتيجة لاستخدام Wawp لإنشاء المجموعات هي التعيين التلقائي لصفة **المنشئ (Creator)** لمثيلك. في هرم صلاحيات واتساب، هذا الدور قوي وفريد.\nكـ \"منشئ\"، يمتلك مثيلك سلطة لا يمكن للمسؤولين الآخرين تحديها؛ فلا يمكن تخفيض رتبتك أو إزالتك، مما يضمن سيطرة شركتك الدائمة على القناة والبيانات.\n\n---\n\n## 🚀 الاستخدام الاستراتيجي والخصوصية\n\n### التعامل مع إعدادات الخصوصية\nإذا كان المستخدم قد قيد إضافته للمجموعات لـ \"جهات اتصالي فقط\"، فإن الإضافة المباشرة قد تظهر كنجاح تقني لكن العضو لن يظهر فعلياً في المجموعة. في هذه الحالة، يجب أن يتبع نظامك استراتيجية **\"الدعوة كبديل\"**، حيث يرسل رسالة 1:1 تحتوي على [رابط دعوة المجموعة](/v2/groups/invite-code).\n\n### حماية سمعة الحساب\nلتجنب حظر الحساب، تجنب إضافة أعداد كبيرة من الغرباء فجأة. نوصي بأن يقوم نظامك بإضافة المستخدمين الذين كان لهم تفاعل سابق (1:1) مع رقم عملك، مما يشير لواتساب أن المجموعة هي استمرار شرعي لمحادثة عمل.\n            ",
          "args": {
            "name": {
              "description": "اسم المجموعة المراد إنشاؤها"
            },
            "participants": {
              "description": "قائمة بمعرفات JIDs للمشاركين المراد إضافتهم للمجموعة"
            }
          }
        }
      }
    },
    {
      "path": "/v2/groups/join",
      "methods": [
        "GET",
        "POST"
      ],
      "title": "Join group / Get join info",
      "category": "Groups",
      "description": "Use GET to fetch information about a group before joining, or POST to join it. Accepts both direct invite codes and full WhatsApp group links.",
      "extraInfo": "\n# Dynamic Entry: The Strategic Orchestration of Accessible Communities\n\nIn the expansive world of WhatsApp ecosystem management, the **Join Group** endpoint is your primary tool for **Permissionless Scale and Community Self-Onboarding**. While the [Add Participants](/v2/groups/{id}/participants/add) endpoint allows a business to push users into a group, the Join API reverses this logic, allowing your automated instances (or your users' bots) to pull themselves into a conversation using a secure Invite Code. This endpoint is the architectural bridge between a public marketing link and a private, high-trust community space, enabling a seamless transition from discovery to interaction.\n\nFor enterprise architects, managing \"Entry Points\" is about **Scaling Accessibility without Sacrificing Governance**. This guide explores the strategic imperatives of invite-driven growth and the orchestration of dynamic community entry.\n\n---\n\n## 🏗️ Architectural Philosophy: The Bridge from Link to Membership\n\nFrom a technical perspective, the Join Group endpoint is a **State Resolution Engine**. It converts an ephemeral Invite Code into a permanent membership state.\n\n### Key Architectural Objectives:\n*   **The Power of the Invite Code**: The invite code (or the full `chat.whatsapp.com` URL) is a cryptographically secure token that represents a standing invitation to a specific Global-JID. By using this code, your instance can bypass the need for a direct administrator invitation, provided the code is still valid. This is essential for building \"Viral\" growth loops where communities expand through shared links rather than manual admin labor.\n*   **Permissionless Discovery (GET Info)**: A unique feature of this endpoint is the ability to use the `GET` method to **Probe the Group State** before joining. This allows your system to verify the group's name, its current member count, and its profile picture without committing to membership. This \"Pre-flight Verfication\" is critical for avoiding accidental entry into a non-compliant or irrelevant group.\n*   **Global Membership Propagation**: Once the `POST` call is executed, Meta's infrastructure instantly updates the group's membership list across all participant devices. Your instance's JID is now authorized to see the conversation history (from the moment of joining) and participate in active dialogue.\n\n---\n\n## 🚀 Strategic Use Cases: Marketing Funnels and Automated Scaling\n\nThe Join Group endpoint enables a \"Pull-Based\" community strategy that is highly effective for high-volume customer engagement.\n\n### 1. The \"Call-to-Action\" Marketing Funnel\nIn modern marketing, the \"WhatsApp Community\" is the new landing page. Your system can generate thousands of unique landing pages or emails featuring a \"Join our VIP Alert Group\" button. When the user clicks this button, your system can use the **Join Group** endpoint to ensure your official support bot or campaign instance is also present in that specific room to welcome the user. This creates a \"Managed Arrival\" experience where the user enters a room that already has a helpful assistant waiting for them.\n\n### 2. The \"Sub-Agent\" Distribution Model\nFor massive communities that exceed the 1,024-member limit of a single group, your system can use a \"Cellular Expansion\" model. When a group reaches capacity, the system creates a new group, generates an [Invite Code](/v2/groups/invite-code), and then uses the **Join Group** endpoint to move \"Squad Bots\" or specialized support instances into the new room. This allow your automation to scale horizontally across an unlimited number of groups, with each bot \"Joining\" its assigned cell programmatically.\n\n### 3. Cross-Instance Resilience and Recovery\nIf a primary WhatsApp account is lost or restricted, your system needs a way to \"Re-Colonize\" its existing communities with a backup account. By maintaining a database of your groups' Invite Codes, your system can programmatically instruct a new instance to **Join** all existing high-value groups. This \"Automated Recovery\" ensures that your business logic retains its presence in critical conversations even in the face of account-level interruptions.\n\n---\n\n## 🔐 Administrative Mandate: Authority and Permission Management\n\nJoining a group is a high-trust event. Your system must ensure that its entry into a room is both authorized and strategic.\n\n### Managing the \"Invite Code\" Lifecycle\nAn invite code is a permanent vulnerability if handled poorly. Anyone with the code can join the group. Your system should use the [Revoke Invite Code](/v2/groups/invite-code/revoke) endpoint periodically to disable legacy codes and generate new ones. The **Join Group** endpoint will always fail if the code has been revoked, providing a powerful gatekeeping mechanism for your automated communities.\n\n### Visibility and Legal Compliance\nWhen an instance joins a group, it becomes a \"Data Processor\" for that conversation. In regulated industries (like Healthcare or Finance), you must ensure that your system only joins groups where its presence is legally authorized. Use the `GET` probe to verify the group's identity against your internal \"Allowed Groups\" list before performing the `POST` join operation. This \"Sanity Check\" prevents accidental data exposure and ensures your platform remains compliant with privacy standards.\n\n---\n\n## 🛡️ Operational Best Practices: Consistency and Contextual Arrival\n\n*   **The \"Welcome Greeting\" Pattern**: Upon joining a group, your instance should immediately send a \"Service Identification\" message (e.g., *\"Support Assistant #4 has joined the room. Type /help for assistance.\"*). This prevents your system from appearing as a \"Ghost Participant\" and establishes its role from the first second.\n*   **Monitoring Member Count**: Use the `GET` probe to track the population of the group you are about to join. Joining a nearly-empty group requires a different introductory tone than joining a 500-member community hub.\n*   **Coordinate with CRM Logic**: Your internal database should update the group's status to `active` only after the API returns the confirmed Global-JID (`@g.us`). This JID is the primary key for all future interactions and must be carefully persisted.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Probe Before You Commit**: Always use the `GET` method first to verify the code is valid and the group belongs to your organization. This avoids \"Joining Errors\" and prevents your system from being added to malicious or spam groups.\n2.  **Rate Throttling for Mass Join Operations**: if your system is performing a recovery sequence (joining 100+ groups), stagger the joined calls. Joining too many groups in a single minute can trigger Meta's security heuristics, which might flag the account as a \"Bot Net.\" A rate of 2-5 joins per minute is recommended for large-scale operations.\n3.  **Webhook Integration**: Listen for the [`group.join`](/v2/webhooks/group-join) event. This confirms that the network has accepted your instance as a member. When this event arrives, you can trigger your \"Onboarding Workflow\" for that specific group.\n\n---\n\n## 🎯 Conclusion: Mastering the Art of the Accessible Community\n\nThe **Join Group** endpoint is the \"Gateway\" of your community architecture. It is your most powerful tool for building scalable, accessible, and resilient conversational networks. By treating the act of joining as a strategic, programmable event, you create a professional environment that is easy for your systems to enter and easy for your users to discover. You move beyond \"Push-Only\" messaging and into the world of **Dynamic Conversational Ecosystems**, where your authority is distributed through secure codes and your presence is always where it's needed most.\n    ",
      "tips": [
        {
          "type": "warning",
          "title": "Rate Limits",
          "content": "Joining too many groups rapidly can flag your account."
        },
        {
          "type": "info",
          "title": "Approval",
          "content": "Some groups require admin approval, which this endpoint does not bypass."
        }
      ],
      "recommendations": [
        "Only join groups relevant to your business purpose.",
        "Leave groups immediately if you joined by mistake to maintain account health.",
        "Ensure you have the valid 'invite_code' from the get-info endpoint."
      ],
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "code": {
          "required": true,
          "type": "string",
          "description": "Group invite code or full WhatsApp invite URL",
          "example": "FqkbDWXAIzvBwF04luAefz"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Successful operation",
          "example": {
            "id": "1234567890@g.us",
            "subject": "Community Group",
            "description": "Group for testing"
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "الانضمام للمجموعة / جلب معلومات الانضمام",
          "description": "استخدم GET لجلب معلومات حول المجموعة قبل الانضمام، أو POST للانضمام إليها. يقبل كلاً من أكواد الدعوة المباشرة وروابط مجموعات واتساب الكاملة.",
          "tips": [
            {
              "title": "حدود المعدل",
              "content": "الانضمام إلى عدد كبير جدًا من المجموعات بسرعة قد يؤدي إلى الإبلاغ عن حسابك."
            },
            {
              "title": "الموافقة",
              "content": "تتطلب بعض المجموعات موافقة المسؤول، ولا تتجاوز نقطة النهاية هذه ذلك."
            }
          ],
          "recommendations": [
            "انضم فقط إلى المجموعات ذات الصلة بغرض عملك.",
            "غادر المجموعات فورًا إذا انضممت عن طريق الخطأ للحفاظ على صحة الحساب.",
            "تأكد من أن لديك 'invite_code' صالح من نقطة نهاية معلومات الانضمام."
          ],
          "extraInfo": "\n# الدخول الديناميكي: التنسيق الاستراتيجي للمجتمعات المتاحة\n\nفي عالم إدارة منظومة واتساب، تعد واجهة **الانضمام للمجموعة** أداتك الأساسية لـ **النمو غير المقيد والتحاق المجتمعات ذاتياً**. بينما تسمح واجهة [إضافة مشاركين](/v2/groups/{id}/participants/add) للشركة \"بدفع\" المستخدمين إلى مجموعة، فإن واجهة الانضمام تعكس هذا المنطق، مما يسمح لمثيلك المؤتمت بسحب نفسه إلى محادثة باستخدام كود دعوة آمن.\n\n---\n\n## 🏗️ الفلسفة المعمارية: الجسر من الرابط إلى العضوية\n\nمن منظور تقني، واجهة الانضمام للمجموعة هي **محرك حل الحالة**. فهي تحول كود الدعوة المؤقت إلى حالة عضوية دائمة.\n\n### الأهداف المعمارية الرئيسية:\n*   **قوة كود الدعوة**: كود الدعوة (أو رابط `chat.whatsapp.com`) هو رمز آمن يمثل دعوة قائمة لمجموعة محددة. يتيح لمثيلك تجاوز الحاجة إلى دعوة مباشرة من المسؤول، وهو أمر حيوي لبناء حلقات نمو \"فيروسية\".\n*   **الاكتشاف بدون إذن (GET Info)**: ميزة فريدة تتيح لك استخدام طريقة `GET` لـ **معاينة حالة المجموعة** قبل الانضمام؛ حيث يمكنك التحقق من الاسم وعدد الأعضاء وصورة المجموعة دون الالتزام بالعضوية.\n*   **الانتشار العالمي للعضوية**: بمجرد تنفيذ طلب `POST`، يتم تحديث قائمة الأعضاء فوراً عبر جميع أجهزة المشاركين، وتخويل مثيلك لرؤية تاريخ المحادثة (منذ لحظة الانضمام) والمشاركة فيها.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي: قمع التسويق والتوسع الآلي\n\n### 1. قمع التسويق \"للمطالبة باتخاذ إجراء\"\nاجعل \"مجتمع واتساب\" هو صفحة الهبوط الجديدة. عند نقر المستخدم على زر \"انضم إلى مجموعة كبار الشخصيات\"، يمكن لنظامك استخدام واجهة **الانضمام للمجموعة** لضمان وجود بوت الدعم الخاص بك في الغرفة للترحيب بالمستخدم، مما يخلق تجربة \"وصول مدارة\".\n### 2. التعافي المرن عبر المثيلات\nإذا فقدت حساب واتساب أساسي، يمكنك استخدام هذه الواجهة لتوجيه حساب بديل لـ **الانضمام** إلى جميع المجموعات عالية القيمة الموجودة مسبقاً باستخدام أكواد الدعوة المخزنة في قاعدة بياناتك.\n\n---\n\n## 🛡️ أفضل الممارسات: الوصول السياقي\nنوصي بنمط **\"تحية الترحيب\"**؛ فبمجرد الانضمام، يجب على مثيلك إرسال رسالة تعريفية فوراً (مثل *\"انضم مساعد الدعم #4 للغرفة. اكتب /help للمساعدة\"*). يمنع هذا ظهور نظامك كـ \"مشارك شبحي\" ويثبت دوره منذ اللحظة الأولى.\n            ",
          "args": {
            "code": {
              "description": "كود دعوة المجموعة أو رابط الدعوة الكامل"
            }
          }
        }
      }
    },
    {
      "path": "/v2/groups/count",
      "methods": [
        "GET"
      ],
      "title": "Get the number of groups",
      "category": "Groups",
      "description": "Get the total number of groups the instance is a member of.",
      "extraInfo": "\n# Quantifying the Ecosystem: The Strategic Power of Demographic Density\n\nIn the world of massive conversational orchestration, your footprint is your reach. The **Get Groups Count** endpoint is your primary tool for **Strategic Portfolio Analysis and Capacity Planning**. It provides a high-level, aggregate view of your instance's presence across the WhatsApp network, returning the total number of communities where your business currently holds a seat. While individual [Group Retrieval](/v2/groups/{id}) provides depth, the Count API provides the \"Aerial View\" required to understand your ecological balance, your resource saturation, and your overall influence within the distributed network.\n\nFor enterprise architects, the group count is the **Primary Barometer of Scalability**. This guide explores the strategic imperatives of numerical auditing and the orchestration of managed growth.\n\n---\n\n## 🏗️ Architectural Philosophy: Aggregate State Retrieval Without Exposure\n\nFrom a technical perspective, the Groups Count endpoint is a **Low-Latency Metadata Aggregator**.\n\n### Key Architectural Objectives:\n*   **High-Speed Portfolio Verification**: Querying the full details of 500 groups via the [List API](/v2/groups) is a data-intensive operation. The Count endpoint provides a \"Fast-Path\" alternative during initialization or health checks. By retrieving a single integer, your system can quickly verify its \"Global Footprint\" without the overhead of parsing extensive JSON objects for every membership.\n*   **Decoupling Presence from Content**: This endpoint operates at the **Mebmership Layer**. It doesn't care about message volume or metadata changes; it simply reconciles the instance's Global-JID (`@g.us`) mapping. This makes it an ideal trigger for high-level dashboarding and operational monitoring.\n*   **Zero-Impact Auditing**: Because it doesn't fetch participant lists or media, the Count API is one of the most resource-efficient endpoints in the Wawp stack. You can call it frequently as part of a \"Warden\" process to detect sudden, unauthorized [Group Leavings](/v2/groups/{id}/leave) or un-tracked [Join Events](/v2/groups/join).\n\n---\n\n## 🚀 Strategic Use Case: Capacity Planning and Viral Load Balancing\n\nThe group count is the foundation of any \"Auto-Scaling\" conversational architecture.\n\n### 1. The \"Horizontal Expansion\" Trigger\nEvery WhatsApp account has practical limits on the number of active conversations it can effectively manage before webhook delivery or storage overhead becomes a concern. Your orchestration engine should monitor the **Get Groups Count** value. When an instance reaches a predefined \"Saturation Threshold\" (e.g., 500 active groups), the system should automatically initialize a **New Instance** to handle future group creations. This \"Cell-Based Growth\" ensures that no single account becomes a bottleneck for your entire organization.\n\n### 2. Viral Campaign Monitoring and Milestone Tracking\nIn marketing scenarios where you are using [Invite Codes](/v2/groups-invite-code) to drive organic growth, the Group Count is your primary KPI. It measures the number of distinct communities that have opted into your branded ecosystem. Rapid spikes in the group count can trigger automated \"Celebration Workflows\" or indicate a successful viral loop, while a plateauing count indicates that your acquisition funnels require strategic adjustment.\n\n### 3. \"Community Bloat\" Detection and Cleanup\nManaging an instance that is a member of 2,000 inactive groups is inefficient and increases the risk of metadata collisions. Your system can use the **Get Groups Count** endpoint as a starting point for its \"Pruning Cycle.\" If the count is significantly higher than your internal CRM's record of \"Active Projects,\" it triggers a deep audit to find and [Leave](/v2/groups/{id}/leave) zombie groups, keeping your instance's presence clean and professional.\n\n---\n\n## 🔐 Administrative Mandate: Visibility and Global Auditing\n\nIn a professional environment, visibility is the first step toward governance.\n\n### Reconciliation and Compliance\nFor businesses in regulated sectors, you must be able to report on your exact footprint at any time. The **Get Groups Count** endpoint provides the raw data for your **Global Compliance Report**. By comparing the API's count with your internal database's count, you can detect \"Shadow Communities\"—groups created by human agents from their phones that have not been registered with your central CRM. Reconciliation ensures that every interaction under your business's name is tracked and governed.\n\n### Identifying \"Instance Saturation\"\nIf your instance is near the service limits (WhatsApp occasionally enforces limits on the number of groups a single account can belong to), this endpoint is your early warning system. By proactively monitoring the count, your platform can gracefully stop new group creations or prompt an admin to decommission legacy projects before a hard network limit is reached, maintaining perfect service continuity.\n\n---\n\n## 🛡️ Operational Best Practices: Consistency and Performance\n\n*   **Dashboaring for Human Oversight**: Display the group count prominently in your agent's management UI. It provides instant context on the \"Scale of Management\" currently required.\n*   **Event-Driven Verification**: Don't rely solely on counting webhooks. Every 24 hours, perform a \"Hard Sync\" by calling the **Get Groups Count** endpoint to verify your state. This corrects any minor discrepancies caused by missed webhooks or edge-case network partitions.\n*   **Map Count to Resource Allocation**: If your backend processes webhooks differently for groups vs. 1:1 chats, use the count to scale your worker pool. A higher group count generally corresponds to a higher \"Bursty\" message volume during peak hours.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Fast Refresh for UI/UX**: Use this endpoint to provide instant feedback in your application's sidebar. It is much faster than loading a full list and gives the user an immediate sense of the account's scale.\n2.  **Cross-Reference with CRM State**: Your internal database should be the \"Source of Truth\" for what groups *should* exist. The API provides the \"Ground Truth\" of what *actually* exists. A mismatch between these two numbers is an indicator of an operational error or an unauthorized manual change.\n3.  **Synchronization after Batch Operations**: After performing a bulk creation or a bulk deletion, wait for the network to settle and then call the **Get Groups Count** endpoint. This confirms that all operations have been successfully finalized by Meta's infrastructure.\n\n---\n\n## 🎯 Conclusion: Mastering the Art of the Quantified Community\n\nThe **Get Groups Count** endpoint is the \"Pulse Monitor\" of your community architecture. It is your most direct tool for measuring scale, predicting resource needs, and enforcing compliance across the entire network. By treating the numerical state of your communities as a primary strategic motivator, you build a conversational ecosystem that is resilient to bloat and perfectly optimized for growth. You move beyond \"Managing Individual Chats\" and into the world of **Portfolio Orchestration**, where every group is a number in a well-oiled machine of customer engagement and operational excellence.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Caching",
          "content": "Cache this count locally to avoid frequent API calls."
        },
        {
          "type": "positive",
          "title": "Monitoring",
          "content": "Track group count trends to identify suspicious bulk-joining activity."
        }
      ],
      "recommendations": [
        "Use this endpoint for dashboard metrics rather than listing all groups.",
        "Compare the count against your CRM's expected active projects."
      ],
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Count retrieved",
          "example": {
            "count": 15
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "جلب عدد المجموعات",
          "description": "الحصول على العدد الإجمالي للمجموعات التي يشترك فيها هذا المثيل.",
          "extraInfo": "\n# قياس المنظومة: القوة الاستراتيجية للكثافة الديموغرافية\n\nواجهة **جلب عدد المجموعات** هي أداتك الأساسية لـ **التحليل الاستراتيجي وتخطيط السعة**. إنها توفر رؤية مجمعة وعالية المستوى لانتشار مثيلك عبر شبكة واتساب. بينما يوفر [جلب بيانات مجموعة](/v2/groups/{id}) العمق، توفر واجهة العدد \"الرؤية الجوية\" المطلوبة لفهم توازنك البيئي وتشبع مواردك.\n\n---\n\n## 🏗️ الفلسفة المعمارية: استرداد الحالة المجمعة\n\nمن منظور تقني، واجهة عدد المجموعات هي **مجمع بيانات وصفية منخفض التأخير**.\n*   **تحقق سريع من المحفظة**: الاستعلام عن تفاصيل 500 مجموعة هو عملية مكثفة للبيانات. توفر واجهة العدد بديلاً سريعاً أثناء الفحص الدوري للصحة، حيث يتم استرداد رقم واحد فقط.\n*   **تدقيق بدون تأثير**: لأنها لا تجلب قوائم المشاركين أو الوسائط، تعد هذه الواجهة واحدة من أكثر الواجهات كفاءة في استهلاك الموارد.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي: تخطيط السعة وتوازن الحمل\n\n### 1. محفز \"التوسع الأفقي\"\nكل حساب واتساب له حدود عملية. عندما يصل المثيل إلى \"حد التشبع\" (مثلاً 500 مجموعة نشطة)، يجب على نظامك تلقائياً تهيئة **مثيل جديد** للتعامل مع المجموعات الجديدة مستقبلاً. يضمن هذا الـ \"نمو الخلوي\" عدم تحول أي حساب إلى عنق زجاجة.\n### 2. اكتشاف التضخم وتنظيف المجتمع\nإدارة مثيل عضو في 2000 مجموعة غير نشطة هو أمر غير فعال. استخدم هذه الواجهة لبدء \"دورة الإيقاف\"؛ فإذا كان العدد أعلى بكثير من سجلات الـ CRM للمشاريع النشطة، فهذا يستدعي تدقيقاً عميقاً لمغادرة المجموعات الخاملة.\n            ",
          "tips": [
            {
              "title": "التخزين المؤقت",
              "content": "قم بتخزين هذا العدد محليًا لتجنب استدعاء API بشكل متكرر."
            },
            {
              "title": "المراقبة",
              "content": "تتبع اتجاهات عدد المجموعات لتحديد أي نشاط انضمام جماعي مشبوه."
            }
          ],
          "recommendations": [
            "استخدم هذه الواجهة لمقاييس لوحة التحكم بدلاً من سرد جميع المجموعات.",
            "قارن العدد مع المشاريع النشطة المتوقعة في نظام إدارة علاقات العملاء (CRM)."
          ]
        }
      }
    },
    {
      "path": "/v2/groups/{id}",
      "methods": [
        "GET"
      ],
      "title": "Get the group",
      "category": "Groups",
      "description": "Retrieve detailed information about a specific group.",
      "extraInfo": "\n# Real-Time Discovery: Mastering the State of Your Communities\n\nIn the dynamic environment of enterprise WhatsApp management, information is your most valuable asset. The **Get Group** endpoint is far more than a simple data retrieval tool; it is your primary mechanism for **Real-Time State Discovery and Verification**. In an ecosystem where a single group can be interacted with by dozens of participants, multiple automation bots, and human agents simultaneously, your internal records can quickly become de-synchronized from the ground truth of the WhatsApp network. This endpoint serves as your \"Source of Truth,\" providing the instantaneous metadata required to drive high-fidelity decision logic.\n\nSuccessful group orchestration requires a \"Verification-First\" mindset. This guide explores how to leverage the Get Group endpoint to build resilient, permission-aware, and metadata-driven workflows.\n\n---\n\n## 🏗️ Architectural Philosophy: The Validation Loop\n\nFrom a system architecture perspective, fetching group information is a **Pre-Conditioning Act**. Before your system attempts a high-sensitivity operation—such as adding a controversial participant, promoting a new admin, or dismantling a group—it must first validate the current configuration of the target community.\n\n### Key Architectural Benefits:\n*   **Permissions & Authority Auditing**: One of the most critical fields returned by this endpoint is the participation list, which includes administrative status indicators. Your system can use this to verify if the Wawp instance still possesses **Admin Rights**. Since admin status can be revoked manually by a human in the WhatsApp app, checking this *before* an automated action prevents downstream failures and ensures your error handling is proactive rather than reactive.\n*   **Metadata Synchronization**: Users have the power to change group subjects and icons at any time (depending on settings). The Get Group endpoint allows your system to \"Re-Synchronize\" its local dashboard with the latest visual identity of the group. This ensures that when an agent looks at your internal CRM, they see the same names and identifiers that the customer sees on their mobile device, minimizing cognitive dissonance and operational errors.\n*   **Structural Health Checks**: This endpoint allows you to verify if a group is still \"Active\" on the network. If a group has been deleted by another admin or if your instance has been \"Kicked,\" the API will return a 404 or 403 error. Incorporating this check into your \"Pre-Flight\" logic ensures that your automation queue doesn't attempt to process interactions for \"Ghost Communities.\"\n\n---\n\n## 🚀 Strategic Operational Patterns: Using Metadata to Drive Logic\n\nThe true power of the Get Group endpoint lies in using the returned metadata to feed your secondary automation engines.\n\n### 1. The Metadata-Driven Routing Engine\nImagine a scenario where your business manages 500 active groups. A user sends a message in a group that your system doesn't immediately recognize as a \"Priority\" channel. By calling the Get Group endpoint, you can pull the current **Group Description**. If your system detects a specific Project ID or Case Code embedded in that description, it can instantly route the incoming message to a specialized support tier. This turns a generic group interaction into a high-context, routed ticket without requiring the user to manually enter an ID.\n\n### 2. Identity Resolution & Naming Volatility\nGroup subjects are volatile; the Global-JID (`@g.us`) is immutable. Your system should never store the name of a group as its primary identifier. Instead, use the Get Group endpoint to maintain a **Mapping Table**. If your system notices that the subject returned by the API is different from the one in your database, it can automatically update the local record and even trigger a \"Name Change Detected\" alert to the project manager. This ensures the integrity of your reporting and archival systems even as the \"Human\" side of the group evolves.\n\n### 3. Verification of Participant Density\nFor compliance-heavy industries (like Finance or Healthcare), it is often a requirement that a group contains exactly one patient and one verified caregiver. This endpoint allows your system to perform a \"census\" of the group. If an unauthorized third party joins via an invite link, your system detects the membership change, verifies the new JID against its whitelist, and can automatically take action (such as an alert or a removal) if the group's \"Security Profile\" has been breached.\n\n---\n\n## 🎭 Administrative Auditing: Tracking the \"Creator\"\n\nAs detailed in the [Groups Overview](/v2/groups-overview), the group creator holds unique, irrevocable power. The Get Group endpoint provides the JID of the owner/creator. In environments where groups might be created by both your API and manually by field agents, tracking the \"Lineage\" of a group is essential for governance.\n*   **Auditing \"Shadow Groups\"**: By periodically scanning for all groups your instance is a member of and checking their source, you can identify \"Shadow Communities\" created by agents that haven't been linked to your official CRM. This allows for top-down governance of your brand's WhatsApp presence.\n\n---\n\n## 🛡️ Reliability & Performance: The Caching Strategy\n\nHitting the WhatsApp network for metadata is a \"Round-trip\" operation that introduces latency. To maintain a high-performance integration, we recommend a **\"Reactive Refresh\" Strategy**.\n\n1.  **Bootstrapping**: Call Get Group when a group is first identified or created to populate your local database.\n2.  **Webhook Synergy**: Instead of polling the endpoint, listen for [`group.update`](/v2/webhooks/group-update) webhooks. Only call the Get Group endpoint when you receive a signal that something has changed.\n3.  **The \"Stale-State\" Buffer**: For non-critical displays (like a list of groups in a footer), use cached data that is 5-10 minutes old. reserve the \"Live\" API call for high-stakes actions like participant management or settings changes.\n\n---\n\n## 🎯 Conclusion: The Intelligence Foundation\n\nThe **Get Group** endpoint is the bridge between the fluid, human-centric reality of WhatsApp and the structured, data-driven needs of your business system. By treating it as a **Validation and Intelligence Layer**, you ensure that your automation is built on a foundation of truth. You move beyond \"Blind Messaging\" and into the era of **Governance-Aware Orchestration**, where every action your system takes is informed by the most current reality of the conversational environment.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Metadata",
          "content": "This returns basic info (Subject, Owner, Creation Time)."
        },
        {
          "type": "warning",
          "title": "No Participants",
          "content": "This endpoint does NOT return the full participant list. Use '/groups/{id}/participants' for that."
        }
      ],
      "recommendations": [
        "Cache this metadata; it rarely changes.",
        "Use this to validate if a Group JID is still valid/accessible.",
        "Check the 'announce' property to see if only admins can send messages."
      ],
      "args": {
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the group (@g.us)",
          "example": "1234567890@g.us"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Group info retrieved",
          "example": {
            "id": "1234567890@g.us",
            "name": "Project Alpha",
            "description": "Main coordination group"
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "جلب بيانات المجموعة",
          "description": "استرداد معلومات مفصلة حول مجموعة محددة.",
          "tips": [
            {
              "title": "البيانات الوصفية",
              "content": "يعيد هذا المعلومات الأساسية (الموضوع، المالك، وقت الإنشاء)."
            },
            {
              "title": "لا يوجد مشاركون",
              "content": "لا تعيد نقطة النهاية هذه قائمة المشاركين الكاملة. استخدم '/groups/{id}/participants' لذلك."
            }
          ],
          "recommendations": [
            "قم بتخزين هذه البيانات الوصفية مؤقتًا؛ فهي نادراً ما تتغير.",
            "استخدم هذا للتحقق مما إذا كان معرّف مجموعة JID لا يزال صالحًا/يمكن الوصول إليه.",
            "تحقق من خاصية 'announce' لمعرفة ما إذا كان المسؤولون فقط هم من يمكنهم إرسال الرسائل."
          ],
          "extraInfo": "\n# الاكتشاف في الوقت الفعلي: إتقان حالة مجتمعاتك\n\nتعد واجهة **جلب بيانات المجموعة** أكثر من مجرد أداة لاسترداد البيانات؛ إنها آليتك الأساسية لـ **اكتشاف الحالة والتحقق منها في الوقت الفعلي**. في بيئة يمكن فيها لعشرات المشاركين وبوتات الأتمتة التفاعل مع مجموعة واحدة، قد تختلف سجلاتك الداخلية عن الواقع الفعلي لشبكة واتساب. تعمل هذه الواجهة كـ \"مصدر للحقيقة\" (Source of Truth).\n\n---\n\n## 🏗️ الفلسفة المعمارية: حلقة التحقق\n\nمن منظور هندسة النظام، جلب معلومات المجموعة هو **فعل تهيئة**. قبل أن يحاول نظامك إجراء عملية حساسة — مثل إضافة مشارك أو ترقية مسؤول — يجب عليه أولاً التحقق من التكوين الحالي للمجموعة.\n\n### الفوائد المعمارية الرئيسية:\n*   **تدقيق الصلاحيات**: يمكنك التحقق مما إذا كان مثيل Wawp لا يزال يمتلك **صلاحيات المسؤول (Admin)**. بما أنه يمكن سحب هذه الصلاحيات يدوياً من قبل إنسان، فإن التحقق المسبق يمنع فشل العمليات المؤتمتة.\n*   **مزامنة البيانات الوصفية**: يمكن للمستخدمين تغيير اسم المجموعة أو صورتها في أي وقت. تتيح لك هذه الواجهة إعادة مزامنة لوحة التحكم الخاصة بك مع آخر هوية بصرية للمجموعة.\n*   **فحص الصحة الهيكلية**: تتيح لك هذه الواجهة التحقق مما إذا كانت المجموعة لا تزال \"نشطة\". إذا تم حذف المجموعة أو طرد مثيلك، فستتلقى خطأ 404 أو 403، مما يضمن أن نظام الأتمتة لا يحاول معالجة تفاعلات لمجتمعات \"شبحية\".\n\n---\n\n## 🛡️ استراتيجية التخزين المؤقت (Caching)\nنوصي باستراتيجية **\"التحديث التفاعلي\"**:\n1. جلب البيانات عند تحديد المجموعة أو إنشائها لأول مرة.\n2. الاستماع لويب هوك [`group.update`](/v2/webhooks/group-update) بدلاً من الاستعلام المستمر.\n3. استخدام البيانات المخزنة مؤقتاً للعرض غير الحرج، واستخدام الواجهة الحية (Live API) للعمليات عالية الخطورة مثل إدارة المشاركين.\n            ",
          "args": {
            "id": {
              "description": "المعرف الفريد للمجموعة (@g.us)"
            }
          }
        }
      }
    },
    {
      "path": "/v2/groups/{id}/leave",
      "methods": [
        "POST"
      ],
      "title": "Leave the group",
      "category": "Groups",
      "description": "Leave a specific group.",
      "extraInfo": "\n# Graceful Withdrawal: The Strategic Lifecycle of Voluntary Presence\n\nIn the dynamic architecture of professional WhatsApp communities, knowing when to arrive is important, but knowing when to depart is critical for operational focus. The **Leave Group** endpoint is your primary tool for **Strategic Offboarding and Resource Reallocation**. Unlike [Deleting a Group](/v2/groups/delete)—which dismantle the shared state for everyone—\"Leaving\" is a graceful resignation of your instance's own participation. It allows the community to persist and continue its internal dialogues while freeing your instance from the \"Noise\" and data overhead of a conversation that has fulfilled its specific business purpose.\n\nFor enterprise architects, managing the \"Exit Phase\" of a bot's participation is a key component of **Inbox Hygiene**. This guide explores the architectural nuances of voluntary resignation and the enforcement of clean conversational lifecycles.\n\n---\n\n## 🏗️ Architectural Philosophy: The Resignation of Shared State\n\nFrom a technical perspective, leaving a group is a **Self-Revocation of Access**. You are severing the link between your instance's JID and the group's Global-JID.\n\n### Key Architectural Objectives:\n*   **Decoupling Without Destruction**: When your instance leaves a group, the group's identity (`@g.us`) remains active for all other participants. The message history, images, and other members are preserved. This is essential for scenarios where a bot provides initial setup (the \"Spark\") and then withdraws to allow human stakeholders to continue the project independently.\n*   **The Power of Autonomy**: Unlike restricted metadata changes, \"Leaving\" is a fundamental right. Any instance can leave any group at any time. There is no \"Lock\" that another admin can put on your instance to prevent you from departing. This ensures that your automation logic always retains absolute control over its own focus and resource consumption.\n*   **Structural Notification**: Every time your instance leaves, a system notification is generated in the chat (e.g., *\"Business Name left\"*). This is a public signal of your system's withdrawal, providing a transparent \"Closing Bracket\" for your automated involvement.\n\n---\n\n## 🚀 Strategic Use Cases: Automated Offboarding and Task Completion\n\nLeaving a group should be the final state in a well-defined state machine.\n\n### 1. The \"Setup and Withdraw\" Implementation Pattern\nIn a technical support or sales environment, your bot's role might be limited to the **Initialization Phase**. The bot creates the group, adds the customer, adds the assigned human expert, and populates the [Description](/v2/groups/{id}/description/set) with relevant case links. Once the human expert sends their first \"Welcome\" message, its work is done. By calling the **Leave Group** endpoint, the bot removes itself from the conversation, ensuring that future customer replies only alert the human agent, not the automation engine.\n\n### 2. The \"Resolution-Driven\" Quiet Exit\nFor a project-based community, the completion of a milestone (e.g., *\"Final Invoice Paid\"*) triggers the offboarding logic. While you might want the customer to keep the group for their own records, your business instance no longer needs to be a member. Leaving the group removes it from your instance's \"Active\" list, which lowers the overhead on your API webhooks and reduces the clutter in your agent's dashboard.\n\n### 3. Subscription Expiry for Support Access\nIf your business provides \"Premium WhatsApp Support\" as part of a subscription, the **Leave Group** endpoint is your primary mechanism for **Access Enforcement**. When a client's subscription expires, your system can automatically trigger a \"Global Resignation\" across all groups associated with that client. This maintains the group's history for the user while formally ending the business's active participation in the service level.\n\n---\n\n## 🔐 Administrative Mandate: Authority and Role Transitions\n\nLeaving a group has specific implications for your administrative authority.\n\n### The \"Transfer of Power\" Requirement\nIf your instance is the **Only Admin** in a group, WhatsApp's network logic will automatically promote another member to admin status upon your departure. This \"Succession Logic\" ensures that the group is never left in an un-governed state. However, to maintain professional control, your system should proactively [Promote](/v2/groups/{id}/admin/promote) a specific trusted human stakeholder before the instance leaves. This ensures that the \"Keys to the Room\" are handed over to the right person, rather than being assigned randomly by the network.\n\n### Preventing \"Zombie Presence\"\nLarge-scale accounts often suffer from \"Community Bloat\"—being a member of thousands of groups that are no longer active. This endpoint is the \"Cleanup Engine\" for this problem. Your system should periodically audit all groups using [Get All Groups](/v2/groups/list). Any group that hasn't seen activity for 180 days should be marked for \"Clean Resignation,\" keeping your instance's footprint lean and optimized.\n\n---\n\n## 🛡️ Operational Best Practices: Professionalism and Graceful Transitions\n\n*   **The \"Final Goodbye\" Pattern**: Never leave a group \"Cold.\" This can feel like a service interruption to the customer. We recommend sending a polite final message (e.g., *\"This case is now handled by our human team. Our automated assistant is leaving to keep the room focused. Thank you!\"*) before calling the endpoint.\n*   **Metadata Finalization**: Before leaving, ensure that the group's [Description](/v2/groups/{id}/description/set) contains any long-term resources the customer might need. Since you won't be able to update it once you've left, this is your last chance to \"Set the Context\" for the group's future.\n*   **Coordinate with CRM State**: Your internal database should mark the relationship for that group as \"Inactive - Withdrawn\" only after the API confirms a successful exit. This prevents \"Orphaned Logic\" where your system thinks it can still send messages to a group it no longer has access to.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Check Membership State**: You cannot leave a group you are not a member of. Attempting to do so will return a 404 or 400 error. Always perform a pre-flight check to ensure your instance is still present in the channel.\n2.  **Handle Re-Join Logic**: Professional systems should always store the group's [Invite Code](/v2/groups/invite-code) before leaving. If a customer manually adds your instance back into the group later, or if your system needs to re-enter for a specific task, having that code or the persistent JID allows for a smooth re-integration.\n3.  **Webhook Synchronization**: Listen for the [`group.leave`](/v2/webhooks/group-leave) event. This is the network's confirmation that your instance has successfully withdrawn. When this event arrives, you can safely purge the group's temporary data from your high-speed caches (like Redis).\n\n---\n\n## 🎯 Conclusion: Mastering the Art of the Strategic Exit\n\nThe **Leave Group** endpoint is the \"Closing Bracket\" of your community architecture. It allows you to build sophisticated, multi-phase conversational lifecycles that respect both the customer's need for persistent history and your system's need for operational focus. By treating the withdrawal of your presence as a deliberate, strategic act, you ensure that your WhatsApp infrastructure remains optimized and professional. You turn your business instance into a precise instrument that enters the room when it's needed and departs with grace when its work is done, maintaining a clean, high-fidelity environment for every stakeholder involved.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Clean Exit",
          "content": "You will be removed from the participant list, but the group persists."
        },
        {
          "type": "warning",
          "title": "History",
          "content": "You lose access to future messages but often keep local history."
        }
      ],
      "recommendations": [
        "Send a polite goodbye message before calling this endpoint.",
        "If you are the only admin, promote someone else before leaving to ensure continuity.",
        "Update your local database to mark this group as 'Inactive'."
      ],
      "args": {
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the group",
          "example": "1234567890@g.us"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Left group successfully",
          "example": {
            "ok": true
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "مغادرة المجموعة",
          "description": "مغادرة مجموعة محددة.",
          "tips": [
            {
              "title": "خروج نظيف",
              "content": "ستتم إزالتك من قائمة المشاركين، لكن المجموعة ستستمر."
            },
            {
              "title": "التاريخ",
              "content": "ستفقد الوصول إلى الرسائل المستقبلية ولكنك غالبًا ما تحتفظ بالسجل المحلي."
            }
          ],
          "recommendations": [
            "أرسل رسالة وداع مهذبة قبل استدعاء نقطة النهاية هذه.",
            "إذا كنت المسؤول الوحيد، قم بترقية شخص آخر قبل المغادرة لضمان الاستمرارية.",
            "قم بتحديث قاعدة بياناتك المحلية لتمييز هذه المجموعة كـ 'غير نشطة'."
          ],
          "extraInfo": "\n# الانسحاب اللائق: دورة الحياة الاستراتيجية للتواجد الطوعي\n\nتعد واجهة **مغادرة المجموعة** أداتك الأساسية لـ **إنهاء العلاقة الاستراتيجية وإعادة تخصيص الموارد**. بخلاف [حذف المجموعة](/v2/groups/delete) — الذي يفكك المجموعة للجميع — فإن \"المغادرة\" هي استقالة لائقة لمشاركة مثيلك فقط، مما يسمح للمجتمع بالبقاء والاستمرار في حواراته الداخلية مع تحرير مثيلك من \"ضوضاء\" المحادثة التي حققت غرضها التجاري.\n\n---\n\n## 🏗️ الفلسفة المعمارية: الاستقالة من الحالة المشتركة\n\nمن الناحية الفنية، مغادرة المجموعة هي **إلغاء ذاتي للوصول**. أنت تقطع الرابط بين JID مثيلك و JID المجموعة.\n\n### الأهداف المعمارية الرئيسية:\n*   **الفصل بدون تدمير**: عند مغادرة المجموعة، تظل هوية المجموعة (`@g.us`) نشطة لجميع المشاركين الآخرين. هذا ضروري في الحالات التي يقدم فيها البوت الإعداد الأولي ثم ينسحب للسماح للخبراء البشريين بمواصلة المشروع بشكل مستقل.\n*   **سلطة الاستقلالية**: \"المغادرة\" حق أساسي؛ يمكن لأي مثيل مغادرة أي مجموعة في أي وقت، ولا يمكن لأي مسؤول آخر منع مثيلك من المغادرة.\n*   **إشعار هيكلي**: يتم إنشاء إشعار نظام في المحادثة (مثل *\"غادر [اسم شركتك]\"*)، وهو إشارة شفافة لانتهاء تدخل نظامك المؤتمت.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. نمط \"الإرساء والانسحاب\"\nقد يقتصر دور البوت على **مرحلة التجهيز**: إنشاء المجموعة، إضافة العميل والخبير البشري، ثم المغادرة فور إرسال الخبير رسالة الترحيب الأولى، لضمان أن ردود العميل المستقبلية تنبه الوكيل البشري فقط.\n### 2. انتهاء صلاحية الاشتراك\nإذا كان عملك يقدم \"دعم واتساب مميز\" كجزء من اشتراك، فإن واجهة المغادرة هي آليتك لـ **فرض الوصول**. عند انتهاء الاشتراك، يغادر النظام جميع المجموعات المرتبطة بهذا العميل رسمياً.\n\n---\n\n## 🛡️ بروتوكول \"الوداع الأخير\"\nنوصي بإرسال رسالة نهائية مهذبة (مثلاً: *\"هذه الحالة يعالجها الآن فريقنا البشري. سيغادر مساعدنا الآلي لتظل الغرفة مركزة. شكراً لكم!\"*) قبل تنفيذ المغادرة، لضمان عدم شعور العميل بانقطاع مفاجئ في الخدمة.\n            ",
          "args": {
            "id": {
              "description": "المعرف الفريد للمجموعة (@g.us)"
            }
          }
        }
      }
    },
    {
      "path": "/v2/groups/{id}/picture",
      "methods": [
        "GET"
      ],
      "title": "Get group picture",
      "category": "Groups",
      "description": "Retrieve the current profile picture of the group.",
      "extraInfo": "\n# Visual Discovery: The Strategic Retrieval of Branded Identity\n\nIn the fast-paced world of mobile-first communication, recognition is the currency of trust. The **Get Group Picture** endpoint is your primary tool for **Strategic Visual Discovery and Brand Asset Verification**. It allows your automated systems to programmatically retrieve the current public-facing CDN URL of a specific group's profile image. While the group's subject provides the \"What,\" the picture providing the \"Who\"—the immediate visual anchor that tells a user they are in the right place. By retrieving this asset, your platform can enrich your CRM dashboards, synchronize your internal records, and verify that your communities are projecting the correct, professional image to the world.\n\nFor enterprise architects, the profile picture is the **Visual Signal** of the community's health. This guide explores the strategic imperatives of asset retrieval and the orchestration of visual identity.\n\n---\n\n## 🏗️ Architectural Philosophy: Mapping the CDN Entry Point\n\nFrom a technical perspective, the Get Group Picture endpoint is a **State Proxy for Meta's Content Delivery Network**.\n\n### Key Architectural Objectives:\n*   **Decoupled Asset Management**: The API returns a direct URL to Meta's high-speed image servers. This allows your frontend applications to display the group's icon without forcing your backend to proxy large binary data. This \"URL-First\" approach ensures that your dashboards remain fast and performant, even when managing thousands of distinct communities.\n*   **The Anchor of Real-Time Recognition**: Users navigate their WhatsApp chat list primarily by icon. By retrieving this same icon for your internal agent dashboard, you create a \"Visual Bridge\" between the customer's mobile experience and the agent's CRM experience. This symmetry reduces mental load and prevents mistakes in high-volume support environments.\n*   **Visibility Without Administrative Rights**: Any member of a group can retrieve its profile picture. This allows your monitoring instances to audit the visual state of external groups where your organization is a regular participant, providing a powerful tool for competitive intelligence or vendor management.\n\n---\n\n## 🚀 Strategic Use Case: CRM Enrichment and Monitoring Visual Compliance\n\nVisual data is a critical component of professional relationship management.\n\n### 1. The \"Branded Dashboard\" Enrichment\nA CRM list that only shows phone numbers or group subjects is anemic. By calling the **Get Group Picture** endpoint, your system can populate your internal management UI with the actual group icons. This turns a dry table of data into a rich, intuitive \"Command Center\" where agents can instantly locate the right group purely by its familiar branding. This visual speed is essential for teams handling overlapping project cohorts.\n\n### 2. Automated Brand Compliance Auditing\nIn large-scale franchise or partner operations, you may mandate that all official support groups use a specific, high-resolution brand logo. Your \"Global Warden\" logic can use this endpoint to periodically fetch the icon for every group. By running these images through a simple \"Perceptual Hashing\" algorithm, the system can detect if an unauthorized human admin has changed the group picture to a non-compliant image. The system can then automatically [Reset it](/v2/groups/{id}/picture/set) or alert a brand manager.\n\n### 3. \"Probe-and-Qualify\" Workflows\nWhen your system encounters a new [Invite Link](/v2/groups/join), it should use the `GET` probe (often integrated into the Join Info workflow) to retrieve the group's picture. A group named \"Official Billing\" that has a generic placeholder icon or an unprofessional image is a red flag for a phishing or social engineering attack. By exposing this visual data to your safety logic, you build a \"Visual Firewall\" that protects your agents from entering deceptive environments.\n\n---\n\n## 🔐 Administrative Mandate: Visibility and the Monitoring of Visual Truth\n\nA group without a picture is an incomplete environment. A group with the *wrong* picture is a liability.\n\n### Integrity of the Public Face\nThe group icon is often the first thing a user sees when they receive a [Join Link](/v2/groups/join). If your API retrieves a placeholder or an outdated image, it informs your system that a [Set Picture](/v2/groups/{id}/picture/set) operation is required. This \"Proactive Cleanup\" ensure that your customer's first impression of your organization's digital workspace is always premium and professional.\n\n### Mapping the \"Pulse\" of the Group\nFrequent changes to a group's picture can indicate a highly active—or highly chaotic—community environment. By monitoring the URL returned by this endpoint, your system can detect changes even if the [`group.update`](/v2/webhooks/group-update) webhook is delayed. If the URL changes ten times in a day, your system can flag the group for a human moderator to check for a \"Branding War\" between participants.\n\n---\n\n## 🛡️ Operational Best Practices: Consistency, Cache Management, and Placeholders\n\n*   **The \"Placeholder\" Strategy**: If the API returns a 404 or a null URL (indicating no picture set), your frontend should gracefully fall back to a high-quality, branded placeholder icon. Never show a broken image link or a generic browser error icon; it undermines your system's perceived quality.\n*   **CDN Cache Awareness**: Meta's CDN URLs are typically long-lived but can expire or change if the image is updated. Do not cache these URLs permanently in your own database. Instead, store them with a \"Time-to-Live\" (TTL) of 24 hours or re-fetch them whenever an agent opens the specific group's view.\n*   **Differentiate by Size**: Many implementations of the WhatsApp protocol support different image dimensions. The Wawp API returns the most versatile version for web display. Ensure your UI can handle both square and circular cropping to match the native WhatsApp aesthetics.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Map Logic to Asset Existence**: Your system should treat a \"Missing Picture\" as a \"Metadata Debt\" that needs to be paid. Use the result of this GET call to trigger an automated [Set Picture](/v2/groups/{id}/picture/set) call from your organization's central asset library.\n2.  **Handle Network Timeouts**: Retrieving a picture URL is generally fast, but the underlying network request to Meta's infrastructure can occasionally hang. Implement a sensible timeout (3-5 seconds) and use a local \"Generic Group\" icon if the API doesn't respond in time.\n3.  **Cross-Reference with Group Subject**: A mismatch between a group's name (e.g., `Red Team`) and its icon (e.g., a Blue Logo) can be detected by sophisticated vision-plus-text logic. This provides a deep layer of automated \"Identity Auditing\" for massive portfolios.\n\n---\n\n## 🎯 Conclusion: Mastering the Art of the Visualized Community\n\nThe **Get Group Picture** endpoint is the \"Lens\" of your community architecture. It is your most powerful tool for ensuring visual continuity, enforcing brand compliance, and enriching the human experience of managing a distributed network. By treating the group icon as a critical piece of operational intelligence to be verified and displayed, you build a conversational ecosystem that is intuitive, professional, and always aligned with your organization's visual standards. You move beyond \"Simple Text Chats\" and into the world of **Rich Asset Orchestration**, where every group has a face and every interaction is anchored in a verified, branded identity.\n    ",
      "tips": [
        {
          "type": "positive",
          "title": "Caching",
          "content": "Profile pictures are cached aggressively by WhatsApp."
        },
        {
          "type": "info",
          "title": "URL",
          "content": "Returns a temporary direct URL to the image file."
        }
      ],
      "recommendations": [
        "Download and host the image yourself; do not rely on the temporary URL.",
        "Check if the picture has changed before downloading again."
      ],
      "args": {
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the group",
          "example": "1234567890@g.us"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Picture URL retrieved",
          "example": {
            "url": "https://pps.whatsapp.net/..."
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "جلب صورة المجموعة",
          "description": "استرداد صورة الملف الشخصي الحالية للمجموعة.",
          "extraInfo": "\n# الاكتشاف المرئي: الاسترداد الاستراتيجي للهوية المدموغة\n\nفي عالم التواصل المتنقل، يعد التعرف المرئي هو عملة الثقة. تعد واجهة **جلب صورة المجموعة** أداة أساسية لـ **الاكتشاف المرئي الاستراتيجي والتحقق من أصول العلامة التجارية**. هي تتيح لأنظمتك المؤتمتة الحصول برمجياً على رابط CDN الحالي لصورة الملف الشخصي للمجموعة.\n\n---\n\n## 🏗️ الفلسفة المعمارية: رسم نقطة دخول CDN\n\nمن منظور تقني، هذه الواجهة هي **وكيل حالة لشبكة توصيل المحتوى (CDN) الخاصة بـ Meta**.\n*   **إدارة الأصول المنفصلة**: ترجع الواجهة رابطاً مباشراً لخوادم صور Meta عالية السرعة. يتيح ذلك لتطبيقاتك عرض أيقونة المجموعة دون إرهاق خادمك بالبيانات الثنائية الكبيرة، مما يحافظ على أداء لوحات التحكم الخاصة بك.\n*   **مرساة التعرف في الوقت الفعلي**: يتنقل مستخدمو واتساب في قائمة دردشاتهم بشكل أساسي عبر الأيقونات. من خلال جلب نفس الأيقونة للوحة تحكم الوكيل الداخلي، فإنك تخلق \"جسرًا مرئيًا\" يقلل الحمل الذهني ويمنع الأخطاء في بيئات الدعم عالية الضغط.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. إثراء لوحة تحكم CRM\nقائمة CRM التي تعرض فقط أرقام الهواتف هي قائمة جامدة. من خلال جلب صورة المجموعة، يمكنك إثراء واجهة الإدارة بأيقونات المجموعات الفعلية، مما يحول جدول البيانات الجاف إلى \"مركز قيادة\" مرئي يسهل على الوكلاء تحديد المجموعة الصحيحة بسرعة.\n### 2. تدقيق الامتثال للعلامة التجارية\nفي العمليات الكبيرة، قد تفرض استخدام شعار محدد لجميع مجموعات الدعم الرسمية. يمكن لنظامك جلب الأيقونات دورياً والتأكد من توافقها مع المعايير، و[إعادة تعيينها](/v2/groups/{id}/picture/set) تلقائياً إذا قام شخص ما بتغييرها لصورة غير مصرح بها.\n\n---\n\n## 🛡️ أفضل الممارسات التشغيلية\nنوصي باستراتيجية **\"الأيقونة البديلة\"**؛ إذا لم تكن هناك صورة للمجموعة (404)، يجب أن تعرض واجهتك أيقونة احترافية خاصة بعلامتك التجارية بدلاً من إظهار رابط مكسور. كما يجب مراعاة أن روابط CDN تكون طويلة الأجل ولكنها قد تتغير، لذا لا تخزنها بشكل دائم في قاعدة بياناتك بل بمدة صلاحية (TTL) محددة.\n            ",
          "tips": [
            {
              "title": "التخزين المؤقت",
              "content": "يتم تخزين صور الملف الشخصي مؤقتًا بشكل كبير بواسطة واتساب."
            },
            {
              "title": "الرابط",
              "content": "يعيد رابطًا مباشرًا مؤقتًا لملف الصورة."
            }
          ],
          "recommendations": [
            "قم بتنزيل الصورة واستضافتها بنفسك؛ لا تعتمد على الرابط المؤقت.",
            "تحقق مما إذا كانت الصورة قد تغيرت قبل التنزيل مرة أخرى."
          ]
        }
      }
    },
    {
      "path": "/v2/groups/{id}/picture",
      "methods": [
        "PUT"
      ],
      "title": "Set group picture",
      "category": "Groups",
      "description": "Update the group profile picture.",
      "extraInfo": "\n# Visual Branding: The Strategic Psychology of Group Identity\n\nIn the crowded mobile interface, where users often manage dozens of personal and professional chats simultaneously, the **Set Group Picture** endpoint is your primary tool for **Instant Recognition and Brand Affinity**. While the group subject tells the user *what* the group is, its profile picture (also known as its avatar or icon) determines how the user *feels* about the space and how quickly they can locate it in their chat history. By programmatically managing this visual asset, you turn every group into a branded ecosystem that is both professional and easy to navigate.\n\nFor enterprise architects, the group picture is the **Visual Anchor** of the community. This guide explores the strategic imperatives of visual identity management and the psychology of group recognition.\n\n---\n\n## 🏗️ Architectural Philosophy: The Synchronization of Media Metadata\n\nFrom a technical perspective, a group picture is a **High-Density Media Asset** that must be distributed across millions of endpoints.\n\n### Key Architectural Objectives:\n*   **Zero-Latency Visual Recognition**: When a group is created, its default state is often a generic \"Group\" icon. This generic state signals a lack of professional care. By immediately setting a high-quality, branded profile picture via the API, you ensure that the very first time a customer sees the group invitation, it is associated with your official brand colors and logo.\n*   **Authority and Governance**: The ability to set the profile picture is a privileged administrative act. In a professional orchestration, your Wawp instance should maintain [Admin Rights](/v2/groups/{id}/admin/promote) to ensure that only authorized business media is used. This prevents participants from uploading irrelevant or unprofessional photos to your business channels.\n*   **Media Hosting & Proxying**: The Wawp API handles the complex task of taking your external image URL, processing it according to WhatsApp's specific technical requirements, and uploading it to Meta's content delivery network (CDN). This synchronization ensures that a single API call translates into a global push of the new visual identity.\n\n---\n\n## 🚀 Strategic Use Cases: Workflow Branding and Recognition\n\nThe group profile picture should not be static; it can be used as a dynamic indicator of the group's current status or tier.\n\n### 1. Tiered Service Recognition\nIf your business manages different levels of customer support (e.g., Gold, Platinum, VIP), use the profile picture to signal the **Service Level Agreement (SLA)**. A Gold-tier group could have an icon with a gold border, while a VIP group features a distinct \"Platinum\" branding. This visual cue helps both your agents and your customers immediately understand the priority of the conversation without needing to read any meta-text.\n\n### 2. Status-Driven State Visualization\nIn a long-term project lifecycle, the group icon can evolve.\n*   **Active Phase**: A vibrant, colorful logo.\n*   **Milestone Reached**: The logo with a \"Success\" overlay or a green checkmark.\n*   **Archived Phase**: A grayscale or \"Finalized\" version of the logo.\nBy updating the icon programmatically, you provide a visual \"Status Report\" that is visible even when the user isn't looking at the message history.\n\n### 3. Identity Verification and Security\nFor high-security industries like Finance or Legal Services, the profile picture can serve as a \"Trust Signal.\" By using a consistent, high-resolution official company watermark on every group icon, you reassure the customer that the group they have been added to is an official business channel and not a fraudulent or phishing attempt. Visual consistency is the foundation of digital trust.\n\n---\n\n## 🔐 Administrative Mandate: Governance of the Visual Brand\n\nConsistency is the hallmark of enterprise quality. Managing group icons manually across thousands of groups is impossible; automation is the only solution.\n\n### The \"Anti-Tamper\" Protocol\nIf your group settings allow participants to change the profile picture, you risk a user uploading an icon that is inconsistent with your brand guidelines. Your system should listen for the [`group.update`](/v2/webhooks/group-update) webhook. If it detects a picture change that wasn't initiated by your API, it should immediately cross-reference the new media's hash or identifier. If the change is unauthorized, your system can call the **Set Group Picture** endpoint to restore the official branded avatar, maintaining your organization's visual integrity.\n\n### Localization and Culture-Aware Branding\nIf your business operates globally, use the profile picture to provide a **Localized Experience**. A group for Spanish-speaking customers might feature a logo with a subtle cultural variant or a flag-themed element. This \"Dynamic Localization\" through imagery makes the community feel more native and tailored to the specific participant base.\n\n---\n\n## 🛡️ Operational Best Practices: Resolution and Iconography\n\n*   **Aspect Ratio and Centrality**: WhatsApp icons are displayed as circles. When designing your group pictures, ensure that all critical branding (logos, status text) is centered. Any content in the corners will be cropped out.\n*   **Legibility at Scale**: Most users will see the group icon as a tiny 40x40 pixel circle in their chat list. Avoid complex textures or small text. Use bold colors, high-contrast shapes, and iconic symbols that remain recognizable even at a distance.\n*   **File Optimization**: While the Wawp API handles the conversion, the best results come from high-quality square source images (e.g., 640x640 pixels). Using JPEG or PNG formats ensures a clean upload without artifacts.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Verify Admin Status**: Before attempting to change the picture, ensure your instance is a Group Admin. Attempting to set media in a restricted group as a regular member will result in a 403 Forbidden error.\n2.  **Resource URL Accessibility**: Ensure that the URL provided to the API is publicly accessible and has the correct CORS headers if necessary. The Wawp backend needs to be able to fetch the raw image data to perform the upload.\n3.  **Webhook Synchronization**: Listen for the [`group.update`](/v2/webhooks/group-update) event to confirm that the picture was successfully processed by Meta's servers. Once confirmed, you can update your internal CRM's thumbnail for that group to match the reality of the WhatsApp experience.\n\n---\n\n## 🎯 Conclusion: Mastering the Art of the Visual Community\n\nThe **Set Group Picture** endpoint is the \"Design Engine\" of your community architecture. It is your most powerful tool for establishing instant brand recognition, signaling project status, and building professional trust. By treating the group's visual identity as a dynamic, programmable asset, you create a conversational environment that is both beautiful and highly governed. You move beyond \"Simple Chat Lists\" and into the world of **Branded Conversational Spaces**, where every pixel on the user's screen reinforces your organization's commitment to quality and focus.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Format",
          "content": "Use SQUARE JPEG or PNG images for best results."
        },
        {
          "type": "warning",
          "title": "Size",
          "content": "High-res images may be compressed. Aim for 640x640px."
        }
      ],
      "recommendations": [
        "Use your company logo for easy visual identification.",
        "Update the icon to signal special events or status changes.",
        "Ensure the image is centered as it will be cropped to a circle."
      ],
      "args": {
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the group",
          "example": "1234567890@g.us"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "file": {
          "required": true,
          "type": "object",
          "description": "Picture file details (url, mimetype, filename)",
          "example": "{\"url\": \"https://example.com/photo.jpg\", \"mimetype\": \"image/jpeg\", \"filename\": \"group_photo.jpg\"}"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Picture updated successfully",
          "example": {
            "ok": true
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "تعيين صورة المجموعة",
          "description": "تحديث صورة الملف الشخصي للمجموعة.",
          "extraInfo": "\n# العلامة التجارية المرئية: السيكولوجية الاستراتيجية لهوية المجموعة\n\nفي واجهة الهاتف المزدحمة، حيث يدير المستخدمون عشرات المحادثات، تعد واجهة **تعيين صورة المجموعة** أداة أساسية لـ **التعرف الفوري والارتباط بالعلامة التجارية**. فبينما يخبر اسم المجموعة المستخدم *عن ماهيتها*، تحدد الصورة *كيف يشعر* تجاهها ومدى سرعة تحديد موقعها.\n\n---\n\n## 🏗️ الفلسفة المعمارية: مزامنة البيانات الوصفية للوسائط\n\nمن منظور تقني، صورة المجموعة هي **أصل وسائط عالي الكثافة** يتم توزيعه على ملايين النقاط الطرفية.\n*   **التعرف المرئي الفوري**: الحالة الافتراضية للمجموعة هي أيقونة \"مجموعة\" عامة، مما قد يوحي بنقص الاحترافية. من خلال تعيين صورة احترافية فور إنشاء المجموعة، تضمن ارتباط أول انطباع للعميل بعلامتك التجارية الرسمية.\n*   **الحوكمة والسلطة**: تعيين الصورة هو عمل إداري ذو صلاحيات. في التنسيق الاحترافي، يجب أن يحافظ مثيل Wawp على [حقوق المسؤول](/v2/groups/{id}/admin/promote) لضمان استخدام الوسائط المعتمدة فقط ومنع المشاركين من رفع صور غير لائقة.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. التعرف على مستويات الخدمة (SLA)\nإذا كان عملك يدير مستويات دعم مختلفة (ذهبي، بلاتيني)، استخدم الصورة للإشارة لذلك. يمكن للمجموعة الذهبية أن تحمل أيقونة بإطار ذهبي، مما يساعد الوكلاء والعملاء على فهم الأولوية بمجرد النظر.\n### 2. التصور المرئي لحالة سير العمل\nيمكن أن تتطور أيقونة المجموعة عبر مراحل المشروع: شعار ملون للمرحلة النشطة، وشعار مع علامة صح خضراء عند اكتمال المعالم، ونسخة رمادية للمرحلة المؤرشفة.\n### 3. إشارة الثقة والأمان\nفي قطاعات مثل المالية، تعمل الصورة كـ \"إشارة ثقة\". استخدام علامة مائية رسمية للشركة على جميع الصور يطمئن العميل بأن المجموعة هي قناة رسمية وليست محاولة احتيال.\n\n---\n\n## 🛡️ أفضل الممارسات التشغيلية\nتذكر أن أيقونات واتساب تظهر كدوائر، لذا تأكد من توسيط الشعارات المهمة حتى لا يتم قصها. ونظراً لأن معظم المستخدمين سيرون الأيقونة صغيرة جداً (40x40 بكسل)، تجنب التصميمات المعقدة أو النصوص الصغيرة واستخدم ألواناً قوية وأشكالاً واضحة يمكن التعرف عليها بسهولة.\n            ",
          "tips": [
            {
              "title": "التنسيق",
              "content": "استخدم صور JPEG أو PNG مربعة للحصول على أفضل النتائج."
            },
            {
              "title": "الحجم",
              "content": "قد يتم ضغط الصور عالية الدقة. استهدف 640×640 بكسل."
            }
          ],
          "recommendations": [
            "استخدم شعار شركتك للتعرف البصري السهل.",
            "قم بتحديث الأيقونة للإشارة إلى أحداث خاصة أو تغييرات في الحالة.",
            "تأكد من توسيط الصورة حيث سيتم قصها إلى دائرة."
          ],
          "args": {
            "file": {
              "description": "تفاصيل ملف الصورة (الرابط، نوع الملف، واسم الملف)"
            }
          }
        }
      }
    },
    {
      "path": "/v2/groups/{id}/picture",
      "methods": [
        "DELETE"
      ],
      "title": "Delete group picture",
      "category": "Groups",
      "description": "Remove the group profile picture.",
      "extraInfo": "\n# Resetting the Visual State: The Strategic Power of the Default\n\nIn the lifecycle of a professional community, the removal of a brand asset is as significant as its creation. The **Delete Group Picture** endpoint is your primary tool for **Visual State Resetting and Media Governance**. It allows you to programmatically strip a group of its custom profile picture, returning its visual identity to the WhatsApp network's default \"Generic Group\" state. This operation is not merely an act of deletion; it is a strategic signal that a community phase has ended, a brand asset has been retired, or a governance standard is being re-enforced.\n\nFor enterprise architects, managing the absence of an image is a critical component of **Conversational Hygiene**. This guide explores the strategic imperatives of resetting group identity at scale.\n\n---\n\n## 🏗️ Architectural Philosophy: The Removal of Media Metadata\n\nFrom a technical perspective, deleting a group picture is a **State Rollback**. You are instructing Meta's infrastructure to purge the associated media hash from the group's metadata and restore the server-side default.\n\n### Key Architectural Objectives:\n*   **Irrevocable Asset Retirement**: When a group picture is deleted, it is removed from the content delivery network (CDN) for all subsequent requests. While participants may retain a local cache of the old icon on their personal devices for a short time, the official \"Pulse\" of the group no longer carries that visual identity.\n*   **The Power of Admin Authority**: Only a Group Admin has the power to delete the group picture (depending on [Group Settings](/v2/groups/{id}/settings/info)). This ensures that the terminal phase of a group's visual identity is a governed act performed by an authorized authority. If your instance is a regular member and attempts this call, it will fail with a 403 Forbidden error.\n*   **Global Sync and Neutrality**: Upon successful deletion, every participant's device is signaled to update. The group instantly loses its custom \"Branding\" and reverts to the standard WhatsApp silhouette. This \"Return to Neutrality\" is a powerful tool for de-escalating the visual prominence of a group in a cluttered inbox.\n\n---\n\n## 🚀 Strategic Use Cases: Lifecycle Termination and Governance Rejection\n\nThe Delete Group Picture endpoint should be integrated into your broader business logic to handle the decommissioning of community assets.\n\n### 1. The \"Archival State\" Transition\nWhen a project moves into a \"Deep Archive\" phase—where the group still exists for historical records but no active interaction is expected—the custom branded logo should be retired. By calling the Delete Group Picture endpoint, your system signals to all participants that the \"Live Project\" has concluded. The transition from a vibrant company logo to a generic default icon is a subtle but effective way to lower the user's focus on that specific channel without needing to delete the group entirely.\n\n### 2. Governance Policy Enforcement and \"Brand Scrubbing\"\nIf your business policy allows participants to edit group metadata, you may encounter scenarios where a user uploads an inappropriate or non-compliant image as the group icon. While the [Set Picture](/v2/groups/{id}/picture/set) endpoint can be used to overwrite it, the **Delete Group Picture** endpoint serves as the \"Immediate Neutralizer.\" If your system detects a compliance violation via a webhook, it can immediately strip the non-compliant image to restore a safe, neutral state while your legal or moderation team reviews the incident.\n\n### 3. Re-branding Preparation and Handover\nProfessional re-branding operations often involve a \"Blank Slate\" phase. Before uploading a new set of high-fidelity community icons during a corporate acquisition or identity shift, your system can use the Delete endpoint to purge the legacy branding across thousands of groups simultaneously. This ensures that there is no \"Visual Conflict\" or lag where some groups show the old logo while others show the new one.\n\n---\n\n## 🔐 Administrative Mandate: Authority and Consistency\n\nIn an enterprise environment, the group icon is a piece of corporate real estate. You cannot allow it to become a vector for unprofessional behavior.\n\n### Tracking the \"Administrative Footprint\"\nManaging who has the power to strip a group of its identity is a security task. Your system should ensure that only its own JIDs (or verified senior staff) possess the ability to execute the Delete endpoint. This prevents a disgruntled admin from maliciously \"Wiping\" the visual branding of your entire customer-facing ecosystem. Periodically auditing the admin list via [Get Group Info](/v2/groups/{id}) is your primary defense against visual tampering.\n\n### Coordination with Webhooks\nSuccessful visual governance requires a \"Reactive\" architecture. Your system should listen for the [`group.update`](/v2/webhooks/group-update) webhook. When the deletion is confirmed by the WhatsApp network, your system should update its internal CRM thumbnail to a placeholder, ensuring that your agent's dashboard matches the reality of the customer's experience.\n\n---\n\n## 🛡️ Operational Best Practices: Professionalism and Visual Grace\n\n*   **The \"Notice of Retirement\" Pattern**: Removing a group's identity can be confusing for users. Before executing the deletion, we recommend sending a final \"Project Closing\" message or a 1:1 notice to key stakeholders. Explain that the group is transitioning to an \"Archived\" status and the branding is being retired to simplify their inbox.\n*   **Rate Management and System Stability**: Like all metadata operations, deleting pictures in bulk should be staggered. While the network call is lightweight, the downstream \"Push\" to thousands of participants' devices is significant. Clearing pictures at a rate of 5-10 groups per minute is recommended for large-scale decommissioning tasks.\n*   **Preserving the Audit Trail**: Before calling the Delete endpoint, your system should \"Snapshot\" the final state of the group's visual identity. If you need to re-verify the branding used during a specific period for compliance reasons, your internal database should have a record of the former media hash or a local archival copy.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Verify Admin Permissions**: Since your instance must be an admin to delete the picture, always perform a pre-flight check of your instance's role in the group. This prevents avoidable 403 errors and ensures your deletion queue remains active and efficient.\n2.  **Idempotency of Removal**: Calling the delete endpoint on a group that already has no profile picture is a safe, no-op operation. It will return a success signal without causing any state issues. This allows you to include the deletion as part of a \"Global Cleanup\" script without needing complex conditional logic for every group.\n3.  **Synchronization with the Source of Truth**: When the metadata is successfully deleted from WhatsApp, ensure your internal media pointers are nullified. This prevents your platform from trying to fetch or display \"Ghost Images\" that no longer exist on Meta's CDN.\n\n---\n\n## 🎯 Conclusion: Mastering the Art of the Clean State\n\nThe **Delete Group Picture** endpoint is the \"Eraser\" of your community architecture. It allows you to maintain professional standards, enforce governance, and signal the end of a community's active lifecycle with precision. By treating the removal of visual branding as a deliberate, strategic act, you ensure that your WhatsApp ecosystem remains lean, focused, and always aligned with your organization's current identity. A clean, neutral state is often the most professional foundation for an archive, and the ability to programmatically restore that state is what separates a true enterprise platform from a simple messaging tool.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Default",
          "content": "Deleting the picture reverts it to the default WhatsApp placeholder."
        },
        {
          "type": "warning",
          "title": "Visibility",
          "content": "All participants will see that the group icon was removed."
        }
      ],
      "recommendations": [
        "Only delete if the image is outdated or violates policy.",
        "Consider replacing instead of deleting for better branding."
      ],
      "args": {
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the group",
          "example": "1234567890@g.us"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Picture removed successfully",
          "example": {
            "ok": true
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "حذف صورة المجموعة",
          "description": "إزالة صورة الملف الشخصي للمجموعة.",
          "extraInfo": "\n# إعادة ضبط الحالة المرئية: القوة الاستراتيجية للوضع الافتراضي\n\nفي دورة حياة المجتمع الاحترافي، لا تقل إزالة أصل العلامة التجارية أهمية عن إنشائه. تعد واجهة **حذف صورة المجموعة** أداة أساسية لـ **إعادة ضبط الحالة المرئية وحوكمة الوسائط**. هي تتيح لك إزالة صورة الملف الشخصي المخصصة برمجياً، مما يعيد الهوية المرئية لوضع واتساب الافتراضي \"مجموعة عامة\".\n\n---\n\n## 🏗️ الفلسفة المعمارية: إزالة البيانات الوصفية للوسائط\n\nمن منظور تقني، حذف الصورة هو **تراجع عن الحالة (State Rollback)**. أنت توجه بنية Meta التحتية لتطهير بيانات الوسائط المرتبطة واستعادة الوضع الافتراضي.\n*   **تقاعد الأصول غير القابل للرجوع**: عند حذف الصورة، يتم إزالتها من شبكة توصيل المحتوى (CDN). وبالرغم من أن المشاركين قد يحتفظون بنسخة مخبأة محلياً لفترة قصيرة، إلا أن \"نبض\" المجموعة الرسمي لم يعد يحمل تلك الهوية.\n*   **قوة سلطة المسؤول**: فقط مسؤول المجموعة يملك صلاحية حذف الصورة. يضمن ذلك أن تكون المرحلة النهائية للهوية المرئية عملاً محكوماً من قبل سلطة مفوضة.\n*   **المحياد المرئي**: عند الحذف، تفقد المجموعة \"هويتها المخصصة\" وتعود لشكل الظل القياسي لواتساب. هذا \"الرجوع للحياد\" أداة قوية لتقليل البروز المرئي للمجموعة في صندوق الوارد المزدحم.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. الانتقال لحالة \"الأرشفة\"\nعندما ينتقل المشروع للمرحلة المؤرشفة، حيث تظل المجموعة موجودة للسجلات التاريخية فقط، يجب سحب الشعار الملون للشركة. حذف الصورة يرسل إشارة دقيقة لجميع المشاركين بأن \"المشروع النشط\" قد انتهى.\n### 2. فرض سياسة الحوكمة و \"تطهير العلامة التجارية\"\nإذا قام أحد المشاركين برفع صورة غير لائقة، فإن واجهة **حذف الصورة** تعمل كـ \"محايد فوري\". يمكن للنظام اكتشاف المخالفة عبر ويب هوك وحذف الصورة فوراً لاستعادة حالة آمنة ومحايدة أثناء مراجعة الواقعة.\n### 3. التحضير لتغيير العلامة التجارية (Re-branding)\nغالباً ما تتضمن عمليات تغيير الهوية مرحلة \"الصفحة البيضاء\". قبل رفع الأيقونات الجديدة عبر آلاف المجموعات، يمكن للنظام استخدام واجهة الحذف لتطهير الهوية القديمة لضمان عدم حدوث تضارب مرئي.\n\n---\n\n## 🛡️ حصانة المسؤول والاتساق\nفي بيئة المؤسسات، أيقونة المجموعة هي ملكية اعتبارية للشركة. نوصي باتباع نمط **\"إشعار التقاعد\"**؛ فقبل الحذف، أرسل رسالة توضح أن المجموعة تنتقل لوضع الأرشفة. كما نوصي بجدولة عمليات الحذف الجماعي (5-10 مجموعات في الدقيقة) لضمان استقرار النظام.\n            ",
          "tips": [
            {
              "title": "الافتراضي",
              "content": "يؤدي حذف الصورة إلى إعادتها إلى نائب واتساب الافتراضي."
            },
            {
              "title": "الظهور",
              "content": "سيرى جميع المشاركين أنه تمت إزالة أيقونة المجموعة."
            }
          ],
          "recommendations": [
            "تحذف فقط إذا كانت الصورة قديمة أو تنتهك السياسة.",
            "فكر في الاستبدال بدلاً من الحذف للحصول على علامة تجارية أفضل."
          ]
        }
      }
    },
    {
      "path": "/v2/groups/{id}/description",
      "methods": [
        "PUT"
      ],
      "title": "Updates the group description",
      "category": "Groups",
      "description": "Update the description text for the group.",
      "extraInfo": "\n# The Semantic Manifesto: Defining Purpose through Persistent Context\n\nIn the landscape of distributed communities, the **Set Description** endpoint is your primary tool for **Strategic Documentation**. While the group subject identifies the conversation, the description defines its boundaries, its rules, and its technical interfaces. Because the group description is a persistent block of text that is accessible to all members at any time, it functions as a \"Shared Source of Truth\" or a \"Group Handbook\" that lives within the WhatsApp interface itself. By programmatically managing this field, you move beyond the era of ephemeral chatting and into the era of **Governance-First Collaborative Workspaces**.\n\nFor architects and product managers, the group description is the **Contextual Foundation** upon which professional interactions are built. This guide explores the strategic imperatives of managing group manifestos at scale.\n\n---\n\n## 🏗️ Architectural Philosophy: The Persistent Context Layer\n\nFrom a technical perspective, the group description is a **Large-Scale Metadata Buffer** that is synchronized globally.\n\n### Key Architectural Objectives:\n*   **Static Resource Discovery**: Users often forget the specific links or command prefixes required to interact with your business bots. By embedding this information in the group description, you provide a \"Lasting Reference\" that doesn't disappear when the chat history is cleared or when new messages arrive. It is the only part of the group state that remains \"Pinned\" to the top of the group info screen.\n*   **The Power of Admin Authority**: Like the subject, the ability to change the description is a privileged act. In professional environments, you should almost always set your group [Settings](/v2/groups/{id}/settings/info) to \"Admins Only\" for metadata changes. This prevents participants from overwriting your official business SOPs or support links with their own text.\n*   **Zero-Latency Propagation**: When your API updates the description, the change is reflected immediately for all participants. Meta's infrastructure handles the complex heavy lifting of ensuring that a user in Tokyo and a user in London see the same \"Manifesto\" simultaneously, providing a unified global context.\n\n---\n\n## 🚀 Strategic Use Cases: The Command Center and Onboarding Handbook\n\nThe group description should be treated as a dynamic asset that evolves during the project lifecycle.\n\n### 1. The Interactive \"Bot Command Desk\"\nIf your WhatsApp group is integrated with an AI agent or a workflow engine (e.g., a group for a field service team), use the description to host a **Documentation of Capabilities**. List the specific keywords that trigger actions, such as:\n*   `/status` - Fetch the current project milestone.\n*   `/upload` - Get a link to the secure document portal.\n*   `/escalate` - Notify a senior manager.\nBy hosting this \"Cheat Sheet\" in the description, you empower participants to interact with your automation without needing to read a separate 20nd-page PDF manual.\n\n### 2. The Dynamic Onboarding & KYC Handbook\nFor financial or medical groups, the first interaction is often the most critical. When a group is created, your system should automatically populate the description with **Legal Disclaimers, Privacy Links, and Resource Identifiers**. As the user moves through the \"KYC\" (Know Your Customer) process, your system can update the description to reflect their current status (e.g., *\"Verification Pending - Please upload your ID via the link below\"*). This turns the group description into a progress tracker that provides constant reassurance to the user.\n\n### 3. Hyperlink Hub for Managed Workflows\nWhatsApp descriptions support clickable URLs. Use this to bridge the gap between the chat and your external business systems. Include links to:\n*   Shared Google Drive folders for the project.\n*   Specific Salesforce Case pages for the assigned agent.\n*   Direct payment links for an outstanding invoice.\nBy centralizing these links in the group description, you ensure they are never \"Lost in the Scroll\" of a busy conversation.\n\n---\n\n## 🔐 Administrative Mandate: Governance of the Group Handbook\n\nIn an enterprise setting, the group description is a branding asset. Consistency across hundreds of groups is essential for professional representation.\n\n### The \"Standard Operating Procedure\" Template\nWe recommend that your system uses a **Templating Engine** to generate group descriptions. A standard template might include:\n1.  **Mission Statement**: A one-sentence summary of why the group exists.\n2.  **Stakeholder Directory**: A list of the JIDs or names of the official business representatives in the room.\n3.  **Governance Policy**: A brief note on expected behavior and response times (SLA).\n4.  **Resource Footer**: Links to help centers or escalation paths.\n\n### Reconciliation and Integrity\nIf you allow humans (like field agents) to edit group descriptions, your system should still perform a \"Compliance Audit.\" Listen for the [`group.update`](/v2/webhooks/group-update) webhook. If a human agent changes the description and removes the mandatory \"Legal Footer\" or \"Compliance Link,\" your system can automatically detect the missing required text and call the **Set Description** endpoint to restore the correct version, maintaining your organization's regulatory posture.\n\n---\n\n## 🛡️ Operational Best Practices: Formatting and Information Density\n\n*   **Brevity and Bullet Points**: While WhatsApp descriptions can hold a significant amount of text, users will only read what they can quickly scan. Use emojis as bullet points and keep your paragraphs short.\n*   **The \"Above the Fold\" Rule**: Only the first few lines of a description are visible in the main group info screen before the user has to tap \"Read more.\" Put your most critical information (like the CASE ID or the URGENT ACTION LINK) at the very top.\n*   **Avoid Over-Updating**: Every time you call this endpoint, a system message is generated in the chat. Limit updates to major state changes to avoid cluttering the conversational flow with administrative notices.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Check Metadata Permissions**: Always verify that your Wawp instance is an admin before attempting to set the description. If the group is restricted and you aren't an admin, your call will fail with a 403.\n2.  **String Sanitization**: Ensure that your description strings are correctly escaped and don't contain prohibited characters that could cause JSON parsing errors in your API calls.\n3.  **Synchronization with Source of Truth**: When the description is updated via the API, your internal database should be updated simultaneously. This ensures that when an agent looks at your internal dashboard, they are seeing the *exact* same handbook that the customer sees in WhatsApp.\n\n---\n\n## 🎯 Conclusion: Mastering the Art of the Documented Community\n\nThe **Set Description** endpoint is the \"Command Center\" of your community architecture. It is your most powerful tool for establishing long-term context, providing resource discovery, and enforcing behavioral standards. By treating the group description as a living, programmable manifesto, you create a professional environment that is both efficient and highly governed. You move beyond \"Simple Messaging\" and into the world of **Structured Collaborative Workspaces**, where every participant has the information they need to succeed, right at their fingertips.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Visibility",
          "content": "The description is visible to all participants at the top of the chat."
        },
        {
          "type": "positive",
          "title": "SEO",
          "content": "Include keywords and links to your support portal here."
        }
      ],
      "recommendations": [
        "Keep descriptions concise and focused on group rules or resources.",
        "Update the description when project milestones change.",
        "Use emojis to make key sections scanable."
      ],
      "args": {
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the group",
          "example": "1234567890@g.us"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "description": {
          "required": true,
          "type": "string",
          "description": "New group description",
          "example": "This group is for discussing the new project features."
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Description updated",
          "example": {
            "ok": true
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "تحديث وصف المجموعة",
          "description": "تحديث نص الوصف للمجموعة.",
          "tips": [
            {
              "title": "الظهور",
              "content": "الوصف مرئي لجميع المشاركين في الجزء العلوي من الدردشة."
            },
            {
              "title": "تحسين محركات البحث",
              "content": "قم بتضمين الكلمات الرئيسية وروابط لبوابة الدعم الخاصة بك هنا."
            }
          ],
          "recommendations": [
            "اجعل الأوصاف موجزة وتركز على قواعد المجموعة أو الموارد.",
            "قم بتحديث الوصف عند تغير معالم المشروع.",
            "استخدم الرموز التعبيرية لجعل الأقسام الرئيسية سهلة الفحص."
          ],
          "extraInfo": "\n# البيان الدلالي: تحديد الغرض من خلال السياق المستمر\n\nيعد واجهة **تعيين وصف المجموعة** أداتك الأساسية لـ **التوثيق الاستراتيجي**. بينما يحدد اسم المجموعة المحادثة، يحدد الوصف حدودها وقواعدها وواجهاتها التقنية. وبما أن الوصف هو نص ثابت يمكن لجميع الأعضاء الوصول إليه في أي وقت، فإنه يعمل كـ \"مصدر مشترك للحقيقة\" أو \"دليل المجموعة\" الذي يعيش داخل واجهة واتساب.\n\n---\n\n## 🏗️ الفلسفة المعمارية: طبقة السياق المستمر\n\nمن منظور تقني، وصف المجموعة هو **مخزن مؤقت للبيانات الوصفية واسع النطاق** يتم مزامنته عالمياً.\n*   **اكتشاف الموارد الثابتة**: غالباً ما ينسى المستخدمون الروابط المحددة أو بادئات الأوامر. من خلال تضمين هذه المعلومات في الوصف، فإنك توفر \"مرجعاً دائماً\" لا يختفي بمجرد مسح تاريخ الدردشة.\n*   **قوة سلطة المسؤول**: القدرة على تغيير الوصف هي عمل ذو صلاحيات. في البيئات الاحترافية، يجب عليك دائماً ضبط [إعدادات المجموعة](/v2/groups/{id}/settings/info) لتكون \"للمسؤولين فقط\" لمنع المشاركين من الكتابة فوق سياسات العمل الرسمية.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. \"مكتب أوامر البوت\" التفاعلي\nإذا كانت المجموعة مدمجة مع وكيل ذكاء اصطناعي، استخدم الوصف لاستضافة **توثيق القدرات**، مثل:\n*   `/status` - جلب المرحلة الحالية للمشروع.\n*   `/upload` - الحصول على رابط بوابة المستندات الآمنة.\n### 2. دليل \"اعرف عميلك\" (KYC) الديناميكي\nبالنسبة للمجموعات المالية، يمكن للنظام تحديث الوصف ليعكس حالة المستخدم (مثلاً: *\"التحقق معلق - يرجى رفع الهوية عبر الرابط أدناه\"*). هذا يحول الوصف إلى متتبع تقدم يوفر طمأنينة مستمرة للمستخدم.\n### 3. مركز روابط سير العمل المدارة\nيدعم وصف واتساب الروابط القابلة للنقر. استخدم هذا لربط الدردشة بأنظمة عملك الخارجية (مثل مجلدات Google Drive أو صفحات Salesforce).\n\n---\n\n## 🛡️ حوكمة دليل المجموعة\nنوصي باستخدام **محرك قوالب** لإنشاء أوصاف المجموعات لضمان الاتساق. يجب أن يتضمن القالب القياسي: بيان المهمة، دليل أصحاب المصلحة، سياسة الحوكمة (SLA)، وتذييل الموارد. نوصي بوضع المعلومات الأكثر أهمية في البداية لأن السطور الأولى فقط هي التي تظهر قبل أن يحتاج المستخدم للضغط على \"قراءة المزيد\".\n            ",
          "args": {
            "description": {
              "description": "وصف المجموعة الجديد"
            }
          }
        }
      }
    },
    {
      "path": "/v2/groups/{id}/subject",
      "methods": [
        "PUT"
      ],
      "title": "Updates the group subject",
      "category": "Groups",
      "description": "Update the group subject (name).",
      "extraInfo": "\n# The Power of the Label: Naming as Strategic Signaling\n\nIn the high-velocity environment of WhatsApp communication, the **Update Subject** endpoint is your primary tool for **Visual State Management**. It allows you to programmatically change the name of a group, which is the single most visible piece of metadata on a user's mobile device. The group subject is not just a label; it is a real-time status indicator that tells every participant exactly what the current focus of the conversation is. By automating subject changes, you turn the group title into a dynamic signaling mechanism that reflects the progress of your business workflows.\n\nFor enterprise developers, \"Setting the Subject\" is about **Managing the User's Attention**. This guide explores the architectural nuances of identity volatility and the strategic implementation of status-driven naming.\n\n---\n\n## 🏗️ Architectural Philosophy: The Volatility of Visual Identity\n\nFrom a technical perspective, the group subject is a **Mutable Field** mapped to an **Immutable Identifier** (the Global-JID).\n\n### Key Architectural Objectives:\n*   **Decoupling Identity from Presence**: Your internal database must always anchor its logic to the group's JID (`@g.us`), never to its name. Because any admin (human or bot) can change the subject at any time, relying on the name for logic will lead to catastrophic state failure. The Update Subject endpoint allows your system to \"Force\" its preferred naming convention onto the group, ensuring that the visual reality of the chat matches your internal project state.\n*   **The Power of Admin Rights**: Updating the subject is an authorized operation. Depending on the group's [Settings](/v2/groups/{id}/settings/info), this power might be restricted to **Admins Only** or open to all members. To guarantee that your system can always update the name, your Wawp instance should maintain active Admin status.\n*   **Global Sync & Push Notifications**: Every time the subject is updated, Meta's infrastructure pushes a synchronization event to every single member of the group. This often triggers a silent notification or moves the group to the top of the chat list. Use this \"Attention Hook\" strategically to signal major project milestones.\n\n---\n\n## 🚀 Strategic Use Cases: Lifecycle Staging and Status Visibility\n\nThe group subject should evolve alongside the customer's journey. Use it to provide a \"Glanceable\" status report for the user.\n\n### 1. The \"Workflow Staging\" Indicator\nIn a technical support scenario, a group might start with the name `[OPEN] - Case #1234`. As the investigation progresses, your system can automatically update the subject to `[INVESTIGATING] - Case #1234`,\n  tips: [\n        {\n            type: 'info',\n            title: 'Constraints',\n            content: 'Subject has a character limit (approx 100 chars).'\n        },\n        {\n            type: 'warning',\n            title: 'Rate Limit',\n            content: 'Frequent name changes can be flagged as spam.'\n        }\n    ],\n  recommendations: [\n        \"Include a timestamp or status in the subject (e.g., 'Project Alpha [Closed]').\",\n        \"Use consistent naming conventions for easy searching.\",\n        \"Avoid sensitive PII in group subjects as they are visible in notifications.\"\n    ]\n  \n   and finally `[RESOLVED] - Case #1234`. This allows the customer to see the progress of their request just by looking at their chat list, reducing the need for them to send \"Any updates?\" messages and lowering the load on your support team.\n\n### 2. High-Value Serialization for Agent Productivity\nFor businesses managing hundreds of active groups (like a logistics company or an event agency), agents can quickly become overwhelmed by a list of identical-looking names (e.g., \"Customer Support\"). By programmatically injecting **Prefixes and Priority Codes** (e.g., `[PRIO-A] Wawp Corp Delivery`), you allow your human agents to prioritize their responses based on visual cues. The Update Subject endpoint transforms the inbox into a prioritized task list.\n\n### 3. Time-Sensitive Branding for Events\nFor a 3-day conference, the group subject can reflect the **Current Session Name**. By automating the subject change every hour, you turn the group into a \"Live Schedule.\" Attendees don't need to check a PDF or an app; the name of the group they are already in tells them exactly which seminar is currently happening or which room they should be in.\n\n---\n\n## 🔐 Administrative Mandate: Governance of the Group Title\n\nNaming is a component of brand integrity. In an enterprise environment, you cannot allow group names to become chaotic or unprofessional.\n\n### The \"Anti-Tamper\" Reconciliation\nIf your group settings allow participants to change the subject, you risk a user renaming a professional business channel to something inappropriate or confusing. Your system should listen for the [`group.update`](/v2/webhooks/group-update) webhook. If it detects a subject change that wasn't initiated by your API, it should check the new name against a \"Sanity Filter.\" If the change is unauthorized, the system can instantly call the **Update Subject** endpoint to revert the name back to the official business standard.\n\n### Character Limits and Sanitization\nWhatsApp subjects are currently capped at **25 characters**. This \"Subject Line Economy\" requires creative brevity. Your logic should always include a truncation routine to ensure that critical information (like the Case ID) is at the *beginning* of the string, so it isn't cut off on the user's lock screen.\n\n---\n\n## 🛡️ Operational Best Practices: Consistency and Discoverability\n\n*   **Standardized Prefixes**: Use brackets `[]` or emojis to categorize groups. This creates a visual \"System\" that users can learn to recognize quickly. Use a blue heart for customer success, a red alert for urgent support, and a green check for completed projects.\n*   **Clutter Reduction**: Avoid putting redundant information in the subject. If the user already knows they are talking to \"Brand X,\" don't put \"Brand X\" in every group name. Use that limited character space for specific context (e.g., `Project: Skyline Alpha`).\n*   **Staggered Updates**: While changing a subject is a lightweight operation, avoid doing it \"flicker-style\" (multiple times in a few minutes). Every change generates a system message in the chat history (*\"Business Name changed the subject to...\"*). Too many of these can clutter the conversation and look non-professional.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Check Admin Authority**: Before attempting to set the subject, verify if the group is set to \"Admins Only\" for metadata changes. If it is, and your instance isn't an admin, the call will fail. A proactive audit via [Get Group Info](/v2/groups/{id}) is your best defense against 403 errors.\n2.  **Handle Network Delay**: Subject updates are fast but not instantaneous. Your system should wait for the confirmation webhook before updating its internal \"Display Name\" for that group to ensure your backend state and the network state are perfectly aligned.\n3.  **Cross-Instance Name Management**: If you use multiple WhatsApp accounts, ensure that your naming convention is consistent across all of them so that a VIP customer interacting with different departments sees a unified brand identity.\n\n---\n\n## 🎯 Conclusion: Mastering the Art of the Brand-Aware Community\n\nThe **Update Subject** endpoint is the \"Face\" of your community architecture. It is your most direct channel for communicating high-level status without sending a single disruptive message. By treating the group name as a dynamic, programmable asset, you create a professional environment that is both informative and highly governed. You move beyond simple chat names and into the world of **Visual Workflow Orchestration**, where every glance at the phone provides the user with meaningful, real-time business context.\n    ",
      "args": {
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the group",
          "example": "1234567890@g.us"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "subject": {
          "required": true,
          "type": "string",
          "description": "New group subject",
          "example": "Alpha Team Updates"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Subject updated",
          "example": {
            "ok": true
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "تحديث اسم المجموعة",
          "description": "تحديث اسم (موضوع) المجموعة.",
          "tips": [
            {
              "title": "القيود",
              "content": "الموضوع له حد للأحرف (حوالي 100 حرف)."
            },
            {
              "title": "حد المعدل",
              "content": "يمكن اعتبار تغييرات الاسم المتكررة كرسائل عشوائية."
            }
          ],
          "recommendations": [
            "قم بتضمين طابع زمني أو حالة في الموضوع (مثلًا، 'مشروع ألفا [مغلق]').",
            "استخدم اتفاقيات تسمية متسقة للبحث السهل.",
            "تجنب المعلومات الشخصية الحساسة في مواضيع المجموعة لأنها تظهر في الإشعارات."
          ],
          "extraInfo": "\n# قوة التسمية: الإشارة الاستراتيجية للهوية\n\nفي بيئة واتساب عالية السرعة، تعد واجهة **تحديث اسم المجموعة** أداة أساسية لـ **إدارة الحالة المرئية**. فهي تتيح لك تغيير اسم المجموعة برمجياً، وهو الجزء الأكثر وضوحاً من البيانات الوصفية على جهاز المستخدم. اسم المجموعة ليس مجرد تسمية، بل مؤشر حالة في الوقت الفعلي يخبر كل مشارك بالتركيز الحالي للمحادثة.\n\n---\n\n## 🏗️ الفلسفة المعمارية: تقلب الهوية المرئية\n\nمن منظور تقني، اسم المجموعة هو **حقل متغير** مرتبط بـ **معرف غير متغير** (Global-JID).\n*   **فصل الهوية عن التواجد**: يجب أن يرتكز منطق قاعدة البيانات الخاصة بك دائماً على معرف المجموعة (`@g.us`)، وليس اسمها. يتيح لك هذا الـ API فرض اتفاقية التسمية المفضلة لديك، مما يضمن مطابقة الواقع المرئي للمحادثة مع حالة المشروع الداخلية.\n*   **قوة حقوق المسؤول**: اعتماداً على [إعدادات المجموعة](/v2/groups/{id}/settings/info)، قد تقتصر هذه القدرة على **المسؤولين فقط**. لضمان قدرة نظامك دائماً على التحديث، يجب أن يحافظ مثيل Wawp على وضع المسؤول.\n*   **المزامنة العالمية وإشعارات الدفع**: في كل مرة يتم فيها تحديث الاسم، يتم دفع حدث مزامنة لجميع الأعضاء. استخدم هذا \"لجذب الانتباه\" استراتيجياً للإشارة إلى معالم المشروع الكبرى.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. مؤشر \"مراحل سير العمل\"\nفي الدعم الفني، يمكن أن تبدأ المجموعة باسم `[OPEN] - طلب #1234`، ومع التقدم تتغير إلى `[IN PROGRESS]` ثم `[RESOLVED]`. يتيح ذلك للعميل معرفة تقدم طلبه بمجرد النظر لقائمة المحادثات.\n### 2. الترقيم التسلسلي لإنتاجية الوكلاء\nبالنسبة للشركات التي تدير مئات المجموعات، يمكن حقن **أكواد الأولوية** (مثل `[PRIO-A] توصيل شركة أجمي`) لمساعدة الوكلاء البشر على ترتيب أولوياتهم بناءً على إشارات مرئية.\n\n---\n\n## 🛡️ الحوكمة ونظافة التشغيل\nإذا كانت الإعدادات تسمح للمشاركين بتغيير الاسم، فقد تسمي المجموعة باسم غير لائق. نوصي بالاستماع للويب هوك [`group.update`](/v2/webhooks/group-update)؛ وإذا تم اكتشاف تغيير غير مصرح به، يمكن للنظام فوراً إعادة الاسم للمعيار الرسمي للشركة. لاحظ أن أسماء مجموعات واتساب محدودة بـ **25 حرفاً**، لذا يجب أن يكون منطقك مختصراً ويضع المعلومات المهمة في البداية.\n            ",
          "args": {
            "subject": {
              "description": "اسم المجموعة الجديد"
            }
          }
        }
      }
    },
    {
      "path": "/v2/groups/{id}/settings/security/info-admin-only",
      "methods": [
        "GET"
      ],
      "title": "Get \"info admin only\" settings",
      "category": "Groups",
      "description": "Check if only admins can update group info.",
      "extraInfo": "\n# Governance Auditing: The Verification of Metadata Integrity\n\nIn the management of high-sensitivity conversational environments, trust must be verified as much as it is established. The **Get Info Admin Only** endpoint is your primary tool for **Structural Governance Auditing and Compliance Verification**. It allows your automated systems to programmatically query the \"Lock\" state of a group's visual and textual identity. By understanding whether a group is currently restricted to administrators or open to all participants for metadata changes, your system can make informed decisions about its moderation posture, its branding enforcement logic, and its overall risk assessment for that specific community.\n\nFor enterprise architects, this endpoint is the **Pulse Check of Brand Protection**. This guide explores the strategic imperatives of security auditing and the guardianship of shared context.\n\n---\n\n## 🏗️ Architectural Philosophy: Retrieving the Structural Permission Mask\n\nFrom a technical perspective, the Get Info Admin Only endpoint is a **Security State Resolver**.\n\n### Key Architectural Objectives:\n*   **The Baseline of Brand Integrity**: A professional business channel should almost always be \"Locked\" for metadata changes. This endpoint provides the definitive answer to the question: *\"Is our brand identity currently protected from unauthorized changes?\"* By retrieving the current boolean state, your system can identify \"At-Risk Groups\" that have been accidentally or maliciously opened up to participant-led branding.\n*   **Permissionless Verification**: Any member of a group (even if they are not an admin) can query its security settings. This allows your system to monitor groups where it is a regular participant, providing a \"Monitoring-from-Within\" capability that doesn't require elevated privileges to function.\n*   **Low-Overhead State Mapping**: Because only a single boolean flag is retrieved, this API call is extremely lightweight. It is the perfect trigger for a \"Watchdog Utility\" that scans hundreds of groups per minute to ensure they all adhere to your organization's security baseline.\n\n---\n\n## 🚀 Strategic Use Case: Compliance Monitoring and Anti-Tamper Auditing\n\nVisibility into security settings is the foundation of automated correction.\n\n### 1. The \"Governance Watchdog\" Reconciliation\nIn large-scale operations with multiple human admins, it is common for one admin to manually change a group's settings from their phone (e.g., to allow a client to upload a specific photo) and then forget to re-lock the group. Your system should use the **Get Info Admin Only** endpoint to perform a \"Daily Compliance Scan.\" If a group is found to be unlocked (`adminOnly: false`) when your internal policy mandates a lock, the system can automatically flag the group or even [Re-Lock it](/v2/groups/{id}/settings/security/info-admin-only) to restore the authorized posture.\n\n### 2. Risk-Aware Message Orchestration\nBefore sending a message that contains high-value instructions (e.g., a link to an official payment portal), your system should verify the group's \"Integrity State.\" If the group info settings are unlocked, there is a risk that a malicious participant has renamed the group or changed its description to something deceptive. By probing the security state first, your system can decide to refuse to send sensitive information until the group is secured, protecting both your brand and your customers from social engineering.\n\n### 3. Dynamic Moderator Dashboarding\nFor the human agents managing your communities, the security state of a group is a critical piece of context. Displaying the \"Lock Icon\" in your CRM's dashboard—driven by the data from this endpoint—gives the agent instant situational awareness. They know at a glance whether they have absolute control over the group's \"Face\" or whether they need to monitor for unauthorized metadata tampering.\n\n---\n\n## 🔐 Administrative Mandate: The Guardianship of Brand Identity\n\nIn an enterprise setting, the \"About\" section and the Group Icon are corporate assets. Controlling access to them is a regulatory requirement.\n\n### Integrity in Regulated Industries\nFor sectors like Finance or Healthcare, maintaining a static, verifiable group state is essential for audit trails. Auditors must be able to see that your organization maintained a \"Locked\" posture for its entire duration. The **Get Info Admin Only** endpoint provides the raw evidence for your \"Audit Export\"—proving that your system was actively monitoring and verifying the security boundary of its conversational workspaces.\n\n### Protecting the \"Source of Truth\"\nThe group description often hosts critical SOPs and bot commands. If the info settings are unlocked, that \"Document\" is vulnerable. By programmatically verifying the lock state, your system ensures that the information it provide to users remains the definitive, untampered truth. Verification is the final step in the chain of administrative trust.\n\n---\n\n## 🛡️ Operational Best Practices: Consistency and Periodic Verification\n\n*   **The \"Initialization Audit\"**: Immediately after joining a group or being promoted, your system should call this endpoint to understand its new environment. Don't assume the group is locked; verify it.\n*   **Automated Policy Reporting**: Generate a weekly report for your security team showing the \"Governance Compliance\" percentage across all active groups. This high-level visibility is made possible by the aggregate data retrieved from this endpoint.\n*   **Synchronize with Webhooks**: While [`group.update`](/v2/webhooks/group-update) webhooks tell you when a change *happens*, the **Get Info Admin Only** endpoint tells you what the state *is*. During system recovery or after a network partition, skip the webhook history and call the GET API to reconcile your local state with the network truth.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Map Logic to Boolean States**: Ensure your internal state machine understands that `adminOnly: true` corresponds to a \"Governed\" state and `false` to an \"Expressive\" or \"Collaborative\" state.\n2.  **Handle Network Lag**: Like all metadata reads, the response represents the state at the exact moment of the call. If your system is performing a \"Sync-and-Lock\" loop, wait for a few hundred milliseconds after a [Set](/v2/groups/{id}/settings/security/info-admin-only) call before verifying via the GET API.\n3.  **Cross-Reference with Role Power**: A \"Locked\" group is only secure if your Wawp instance (or a trusted human) is an admin. We recommend a `Get Admin Only -> Get Participant Role` sequence to build a complete picture of the group's current governance posture.\n\n---\n\n## 🎯 Conclusion: Mastering the Art of the Audited Community\n\nThe **Get Info Admin Only** endpoint is the \"Integrity Monitor\" of your community architecture. It is your most powerful tool for verifying that your brand identity is protected, your compliance mandates are met, and your communities are operating within a structured, professional framework. By treating the \"Lock\" state as a critical metric to be audited rather than assumed, you build a conversational ecosystem that is resilient to tampering and always aligned with your organization's standards of quality. You move beyond \"Passive Presence\" and into the world of **Active Governance Verification**, where every community operates under the watchful, informed eye of your automated business logic.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Permissions",
          "content": "Checks if 'Edit Group Info' is restricted to admins."
        },
        {
          "type": "info",
          "title": "Boolean",
          "content": "Returns true if restricted (Admins Only), false if open (All Users)."
        }
      ],
      "recommendations": [
        "Verify this setting before attempting to change the Subject or Icon.",
        "Keep this restricted on official announcement groups."
      ],
      "args": {
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the group",
          "example": "1234567890@g.us"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Setting retrieved",
          "example": {
            "adminOnly": true
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "جلب إعدادات 'تعديل المعلومات للمسؤولين فقط'",
          "description": "التحقق مما إذا كان المسؤولون فقط هم من يمكنهم تحديث معلومات المجموعة.",
          "tips": [
            {
              "title": "الأذونات",
              "content": "يتحقق مما إذا كان 'تعديل معلومات المجموعة' مقيدًا بالمسؤولين."
            },
            {
              "title": "قيمة منطقية",
              "content": "يعيد true إذا كان مقيدًا (للمسؤولين فقط)، و false إذا كان مفتوحًا (لجميع المستخدمين)."
            }
          ],
          "recommendations": [
            "تحقق من هذا الإعداد قبل محاولة تغيير الموضوع أو الأيقونة.",
            "ابقِ هذا مقيدًا في مجموعات الإعلانات الرسمية."
          ],
          "extraInfo": "\n# تدقيق الحوكمة: التحقق من نزاهة البيانات الوصفية\n\nتعد واجهة **جلب إعدادات قفل المعلومات** أداة أساسية لـ **التدقيق الهيكلي للحوكمة والتحقق من الامتثال**. هي تتيح لأنظمتك المؤتمتة الاستعلام برمجياً عن حالة \"قفل\" الهوية المرئية والنصية للمجموعة.\n\n---\n\n## 🏗️ الفلسفة المعمارية: استرجاع قناع الأذونات الهيكلية\n\nمن منظور تقني، هذه الواجهة هي **محلل لحالة الأمن (Security State Resolver)**.\n*   **خط أساس نزاهة العلامة التجارية**: يجب أن تكون قنوات العمل الاحترافية \"مقفلة\" دائماً لتغييرات البيانات الوصفية. توفر هذه الواجهة إجابة قاطعة: *\"هل هويتنا محمية من التغييرات غير المصرح بها؟\"*\n*   **التحقق دون صلاحيات**: يمكن لأي عضو في المجموعة الاستعلام عن هذه الإعدادات، مما يتيح لنظامك مراقبة المجموعات التي يشترك فيها كمشارك عادي دون الحاجة لصلاحيات إدارة مرتفعة.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. مصالحة \"كلب الحراسة\" للحوكمة (Watchdog)\nفي العمليات الكبيرة، قد ينسى المسؤولون البشر إعادة قفل المجموعة بعد فتحه للعميل. يمكن لنظامك إجراء \"مسح امتثال يومي\" وإعادة قفل المجموعات (`adminOnly: false`) تلقائياً لاستعادة الوضع المصرح به.\n### 2. تنسيق الرسائل الواعي بالمخاطر\nقبل إرسال تعليمات عالية الحساسية (مثل رابط دفع)، يمكن للنظام التأكد من أن وصف المجموعة مقفل. فإذا كان مفتوحاً، هناك خطر بأن يكون أحد المشاركين قد غيّر الوصف لمعلومات احتيالية، مما يساعدك في حماية علامتك وعملائك.\n\n---\n\n## 🛡️ أفضل الممارسات التشغيلية\nنوصي بنمط **\"تدقيق التهيئة\"**؛ فبمجرد الانضمام لمجموعة، يجب على النظام استدعاء هذه الواجهة لفهم حدود بيئته الجديدة. كما نوصي بعرض حالة القفل بوضوح في لوحة تحكم الوكيل (CRM) لتوفير وعي ظرفي فوري. تذكر أن الويب هوك يخبرك عندما يحدث تغيير، لكن هذه الواجهة تخبرك بالحالة الراهنة (الحقيقة الميدانية).\n            "
        }
      }
    },
    {
      "path": "/v2/groups/{id}/settings/security/info-admin-only",
      "methods": [
        "PUT"
      ],
      "title": "Updates \"info admin only\" settings",
      "category": "Groups",
      "description": "Set whether only admins can update group info.",
      "extraInfo": "\n# Metadata Sovereignty: Enforcing the Integrity of Shared Context\n\nIn the landscape of professional WhatsApp management, the environment is your brand. The **Set Info Admin Only** endpoint is your primary tool for **Metadata Sovereignty and Structural Governance**. It allows you to programmatically toggle the \"Lock\" on a group's visual and textual identity—including its subject, its description, and its profile picture. By restricting these powers to administrators, you ensure that the group remains a professional, business-led workspace, protecting it from the potential chaos of unauthorized changes by regular participants.\n\nFor enterprise architects, managing *who* can change the environment is as important as the environment itself. This guide explores the strategic imperatives of metadata restriction and the enforcement of trusted communication.\n\n---\n\n## 🏗️ Architectural Philosophy: The Locking of Community Attributes\n\nFrom a technical perspective, this endpoint modifies the **Governance Bitmask** of the group's metadata.\n\n### Key Architectural Objectives:\n*   **Protection of the Branding Baseline**: A business group with 500 participants is a high-sensitivity environment. Allowing any one of those 500 users to rename the group to something inappropriate or change the group icon is an unacceptable brand risk. This endpoint allows your system to \"Hard-Lock\" the branding, ensuring that the visual reality of the chat always aligns with your official corporate identity.\n*   **The Power of Admin Authority**: This setting is a \"Privileged Toggle.\" To successfully lock or unlock the group's info settings, your Wawp instance **must be a Group Admin**. This prevents regular members from trying to \"Open Up\" the metadata permissions for themselves.\n*   **Persistent Governance State**: Once the \"Admin Only\" flag is set to `true`,\n  tips: [\n        {\n            type: 'warning',\n            title: 'Admin Only',\n            content: 'You must be an admin to change this setting.'\n        },\n        {\n            type: 'info',\n            title: 'Impact',\n            content: 'Restricting info prevents users from changing the group name/icon.'\n        }\n    ],\n  recommendations: [\n        \"Lock this immediately for branded communities to prevent vandalism.\",\n        \"Unlock temporarily if you want community-driven branding.\"\n    ]\n  \n   the restriction persists until explicitly changed. Even if the group's membership list changes or if new admins are promoted, the structural restriction remains active, providing a \"Steel-Clad Safeguard\" for your conversational real estate.\n\n---\n\n## 🚀 Strategic Use Case: Brand Integrity and Anti-Tamper Orchestration\n\nMetadata sovereignty should be a \"Default-On\" requirement for any professional integration.\n\n### 1. The \"Formal Business Channel\" Posture\nFor high-trust environments (like a Bank-Customer interaction or a Legal War Room), the group must strictly reflect the official case identity. By calling the **Set Info Admin Only** endpoint immediately after [Creating the Group](/v2/groups/create), your system ensures the workspace is professional from its very first second. This prevents \"Vandalism\" where a participant might try to change the group name to something informal, preserving the gravity and professional tone of the channel.\n\n### 2. The \"Campaign-to-Community\" Lifecycle\nImagine a marketing campaign that starts as a tightly controlled, \"Broadcast-First\" environment. Initially, the info settings are locked to Admins Only (`true`). As the campaign matures and the community gains trust, your system might decide to \"Transition\" the channel into a more collaborative space by setting the value to `false`. This allows participants to contribute to the group's identity, fostering a sense of co-ownership as the relationship evolves from \"Alerts\" to \"Engagement.\"\n\n### 3. Anti-Tamper and Reactive Reconciliation\nIn environments where multiple human admins are present, one admin might accidentally \"Unlock\" the group settings. To maintain a strict governance posture, your system should listen for [`group.update`](/v2/webhooks/group-update) webhooks. If your system detects that the `restrict` flag has been flipped to `false` without an authorized API trigger, it can instantly call this endpoint to **Re-Lock the Metadata**, ensuring your brand's visual board remains under automated oversight at all times.\n\n---\n\n## 🔐 Administrative Mandate: The Root of Trusted Communication\n\nControlling the \"Face\" of the group is the first step in controlling the conversation.\n\n### Centralizing the \"Source of Truth\"\nWhen metadata changes are restricted to admins, it allows your business to use the [Group Description](/v2/groups/{id}/description/set) as a **Reliable Resource Catalog**. If any participant could change the description, they could replace your official support links with fraudulent ones. Locking the info settings turns the description into a \"Protected Document,\" ensuring that users can always trust the information hosted in the group's \"About\" section.\n\n### Structural Integrity in Regulated Industries\nFor compliance-heavy sectors, maintaining a fixed group identity is often a legal requirement. Auditors need to know that the \"Case #123\" group they are reviewing was named \"Case #123\" for its entire duration. By leveraging this endpoint, your system provides a \"Governance Lock\" that contributes to your platform's overall auditability and regulatory standing.\n\n---\n\n## 🛡️ Operational Best Practices: Consistency and Security\n\n*   **Default to Restricted**: unless your use case explicitly requires participant-led branding, we recommend that all enterprise groups be initialized with `value: true`.\n*   **Coordinated Metadata Updates**: When you need to update the group name or icon, do it via the API. Because your API instance is an admin, it will bypass the restriction, allowing you to update the branding while keeping the participants locked out.\n*   **Visual Signaling of the Lock**: Participants see a small notification in the group info when permissions are changed. Use this as a signal of \"Official Handover.\" When the group is locked, it signals to users that they are in a professionally managed, high-trust environment.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Verify Admin Status Before Setting**: You cannot change the security settings of a group if you are not an admin. Attempting to set this value as a regular member will result in a 403 Forbidden error.\n2.  **Idempotent Safety**: Setting the value to `true` when it is already `true` is a safe, no-op operation. This allows you to include the \"Locking Call\" as a mandatory step in your \"Project Refresh\" scripts without needing complex conditional logic.\n3.  **Webhook Integration**: Listen for the [`group.update`](/v2/webhooks/group-update) event to confirm that the network has acknowledged the permission change. Once confirmed, you can update your internal CRM's state to reflect that the group is now in a \"Governed\" posture.\n\n---\n\n## 🎯 Conclusion: Mastering the Art of the Governed Workspace\n\nThe **Set Info Admin Only** endpoint is the \"Foundation of Integrity\" for your community architecture. It is your primary tool for protecting your brand's visual identity, enforcing administrative trust, and maintaining a structured, professional environment for your participants. By treating the \"Lock\" on a group's metadata as a strategic asset, you build a conversational ecosystem that is resilient to tampering and always aligned with your organization's highest standards of quality and governance. You move beyond simple chat rooms and into the world of **Trusted Business Hubs**, where every participant knows that the context they are in is official, secure, and perfectly managed.\n    ",
      "args": {
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the group",
          "example": "1234567890@g.us"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "value": {
          "required": true,
          "type": "boolean",
          "description": "True to restrict to admins, false to allow all",
          "example": "true"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Setting updated",
          "example": {
            "ok": true
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "تحديث إعدادات 'تعديل المعلومات للمسؤولين فقط'",
          "description": "تحديد ما إذا كان المسؤولون فقط هم من يمكنهم تحديث معلومات المجموعة.",
          "tips": [
            {
              "title": "للمسؤولين فقط",
              "content": "يجب أن تكون مسؤولاً لتغيير هذا الإعداد."
            },
            {
              "title": "التأثير",
              "content": "يمنع تقييد المعلومات المستخدمين من تغيير اسم/أيقونة المجموعة."
            }
          ],
          "recommendations": [
            "قفل هذا فورًا للمجتمعات ذات العلامة التجارية لمنع التخريب.",
            "افتحه مؤقتًا إذا كنت تريد علامة تجارية يقودها المجتمع."
          ],
          "extraInfo": "\n# سيادة البيانات الوصفية: فرض نزاهة السياق المشترك\n\nتعد واجهة **تعيين قفل المعلومات** أداة أساسية لـ **سيادة البيانات الوصفية والحوكمة الهيكلية**. هي تتيح لك قفل الهوية المرئية والنصية للمجموعة — بما في ذلك اسمها ووصفها وصورتها — وحصرها في المسؤولين فقط، مما يحمي مساحة العمل من التغييرات غير المصرح بها.\n\n---\n\n## 🏗️ الفلسفة المعمارية: قفل خصائص المجتمع\n\nمن منظور تقني، تقوم هذه الواجهة بتعديل **قناع حوكمة البيانات الوصفية**.\n*   **حماية خط أساس العلامة التجارية**: السماح لأي مشارك بتغيير اسم المجموعة أو أيقونتها في مجموعة تضم مئات الأعضاء يمثل مخاطرة كبيرة. يتيح لك هذا الـ API \"القفل الصلب\" للعلامة لضمان توافق الواقع المرئي مع هويتك الرسمية.\n*   **قوة سلطة المسؤول**: هذا الإعداد هو \"مفتاح صلاحيات\"؛ يجب أن يكون مثيل Wawp **مسؤولاً (Admin)** لتنفيذ هذا الطلب.\n*   **حالة حوكمة مستمرة**: بمجرد تفعيل القفل (`true`)، يظل القيد قائماً حتى يتم تغييره يدوياً، مما يوفر ضماناً أمنياً مستمراً لممتلكاتك المحادثاتية.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. وضع \"قناة العمل الرسمية\"\nلضمان احترافية مساحة العمل من اللحظة الأولى، استدعِ هذه الواجهة فور [إنشاء المجموعة](/v2/groups/create). يمنع هذا \"تخريب\" اسم المجموعة أو وصفها، ويحافظ على النبرة الرسمية للقناة.\n### 2. دورة حياة \"من حملة إلى مجتمع\"\nيمكنك البدء بوضع المقيد (`true`) أثناء إطلاق حملة تسويقية لضمان السيطرة، ثم \"فتح\" الصلاحيات (`false`) تدريجياً مع تطور المجتمع لتعزيز روح المشاركة.\n### 3. المصالحة التفاعلية ضد التلاعب\nإذا قام أحد المسؤولين البشر بفتح الإعدادات بالخطأ، يمكن لنظامك اكتشاف ذلك عبر الويب هوك وإعادة قفلها (Re-Lock) فوراً لضمان بقاء علامتك تحت الرقابة المؤتمتة.\n\n---\n\n## 🛡️ النطاق الإداري وحصانة المنشئ\nالتحكم في \"وجه\" المجموعة هو الخطوة الأولى للتحكم في المحادثة. قفل الإعدادات يحول [وصف المجموعة](/v2/groups/{id}/description/set) إلى **مستند محمي** يمكن للمستخدمين الوثوق به كمصدر للمعلومات الرسمية وروابط الدعم، مما يساهم في الامتثال التنظيمي وإمكانية التدقيق.\n            ",
          "args": {
            "value": {
              "description": "True لتقييد التعديل للمسؤولين فقط، false للسماح للجميع"
            }
          }
        }
      }
    },
    {
      "path": "/v2/groups/{id}/settings/security/messages-admin-only",
      "methods": [
        "GET"
      ],
      "title": "Get settings - who can send messages",
      "category": "Groups",
      "description": "Check if only admins can send messages to the group.",
      "extraInfo": "\n# Conversational Auditing: The Strategic Control of Global Dialogue\n\nIn the orchestration of high-volume community networks, the ability to control the \"Microphone\" is as important as the ability to send the message. The **Get Messages Admin Only** endpoint is your primary tool for **Strategic Conversational Auditing and Signal-to-Noise Verification**. It allows your automated systems to programmatically query whether a group is currently in \"Announcement Mode\" (Admins only) or \"Collaboration Mode\" (All participants). By retrieving this boolean state, your platform can make intelligent decisions about its messaging strategy, its moderation load, and its overall posture within the group, ensuring that your organization's voice is always synchronized with the structural permissions of the channel.\n\nFor enterprise architects, this endpoint is the **Pulse Check of Channel Discipline**. This guide explores the strategic imperatives of interaction auditing and the guardianship of community focus.\n\n---\n\n## 🏗️ Architectural Philosophy: Retrieving the Presence of the Interaction Mask\n\nFrom a technical perspective, the Get Messages Admin Only endpoint is a **Low-Latency Permissions Snapshot**.\n\n### Key Architectural Objectives:\n*   **The Foundation of Channel Readiness**: Before initiating a high-priority broadcast, your system needs to know if the channel is \"Clear.\" By retrieving the current message security state, your system can verify that the group is locked to admins-only before sending a critical alert. This ensures that your alert is the first thing a user sees, rather than being buried in a flurry of participant replies.\n*   **Permissionless Monitoring**: Any instance that is a member of the group can query its security settings via this API. This allows you to build a \"Monitoring Grid\"—where a network of instances tracks the conversation state across hundreds of groups—without requiring administrative rights in every single one.\n*   **Real-Time State Mapping**: Webhooks tell you when a change *happens*, but the GET API tells you what the state *is*. During system re-initialization or after a period of instability, this call provides the authoritative \"Ground Truth\" for your internal state machines.\n\n---\n\n## 🚀 Strategic Use Case: Automated Channel Readiness and Alert Verification\n\nUnderstanding the \"Microphone State\" is the first step in sophisticated campaign orchestration.\n\n### 1. The \"Clean Channel\" Pre-Flight Check\nImagine an automated emergency notification system. Before sending an evacuate-and-report order to 1,000 field staff, the system calls the **Get Messages Admin Only** endpoint. If it finds the group is currently unlocked, it first calls the [Set Messages Admin Only](/v2/groups/{id}/settings/security/messages-admin-only) endpoint to \"Clear the Floor,\" and then finally sends the alert. This sequence ensures that the communication is professional, focused, and un-interruptible.\n\n### 2. Forensic Auditing for \"Quiet Hours\" Enforcement\nMany corporate communities have a \"No-Noise\" policy after hours. Your system can use this endpoint to audit its portfolio at 5:00 PM. If a group is still in Collaborative Mode, the system can automatically flag it for moderation. By verifying the state rather than just assuming it, you ensure that your global \"Quiet Hours\" policy is being structuraly enforced by the API, rather than relying on human memory.\n\n### 3. Dynamic Workflow Branching\nYour bot's behavior should change based on whether the group is locked. If your bot is a \"Question-and-Answer\" assistant, its logic can use this endpoint to determine its own availability. If the group is locked to admins, the bot can send a message: *\"The floor is currently closed for official announcements. I will be available for questions once the admins reopen the chat.\"* This provides a premium, context-aware user experience that reflects the actual technical state of the room.\n\n---\n\n## 🔐 Administrative Mandate: The Guardianship of Community Focus\n\nIn a professional environment, noise is a cost. Auditing the \"Microphone\" is a method of cost-control.\n\n### Integrity in High-Stakes Broadcasting\nFor PR and Marketing teams, the ability to confirm that a \"Listen-Only\" environment is active is essential for campaign success. This endpoint provides the raw data for your \"Campaign Governance Report,\" proving that for the duration of a specific product launch, the community was maintained as a high-fidelity broadcast channel with no external interference.\n\n### Protecting the User Experience\nUsers join Groups (vs. Communities) often expecting a high-signal environment. If a group stays in \"Chatty\" mode too long, attrition (leaving) increases. By programmatically auditing the message settings, your system acts as the \"Experience Guardian\"—ensuring that the group returns to a focused, announcement-driven state once a collaborative session has concluded.\n\n---\n\n## 🛡️ Operational Best Practices: Consistency and Demographic Sensitivity\n\n*   **The \"Initialization Sync\" Pattern**: Always call this endpoint immediately after a successful [Join](/v2/groups/join) or [Create](/v2/groups/create). Understand the structural boundaries of your new home before you start speaking.\n*   **Automated Status Dashboards**: Display the \"Microphone State\" (`Locked` or `Open`) clearly in your agent's UI. It is one of the most important pieces of metadata for an agent tasked with managing hundreds of active conversations.\n*   **Coordinate with Throttling Logic**: If the group is in \"Open\" mode, your system should prepare for a higher volume of incoming webhooks. Use the result of this GET call to dynamically scale your webhook processing workers for that specific instance.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **State-Driven Logic Branching**: Build your bot's command-parsing logic to be \"Governance Aware.\" If the group is in admin-only mode, the bot should only respond to commands from admins, even if its internal logic usually allows regular users to interact.\n2.  **Handle Network Propagation**: When changing the setting via the [Set API](/v2/groups/{id}/settings/security/messages-admin-only), allow for a short network propagation delay (approx. 500ms) before re-verifying the state via the GET API to ensure your local cache reflects the server-side change.\n3.  **Cross-Reference with Admin Authority**: Knowing the group is locked is only useful if you know *who* can speak. Combine the data from this endpoint with the [Get Participants](/v2/groups/{id}/participants) API to build a complete map of authoritative voices in the room.\n\n---\n\n## 🎯 Conclusion: Mastering the Art of the Focused Community\n\nThe **Get Messages Admin Only** endpoint is the \"Stethoscope\" of your community architecture. It is your most powerful tool for monitoring channel discipline, enforcing focus, and ensuring that your organization's voice is always delivered in the optimal structural environment. By treating the \"Microphone State\" as a critical piece of operational intelligence to be audited and verified, you build a conversational ecosystem that is professional, respectful of its users' attention, and always aligned with your strategic goals. You move beyond \"Simple Messaging\" and into the world of **Structured Dialogue Orchestration**, where every silence is verified and every broadcast is protected by the structural integrity of the network.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Announce Mode",
          "content": "Checks if 'Send Messages' is restricted to admins."
        },
        {
          "type": "info",
          "title": "Term",
          "content": "Often called 'Announcement Group' or 'Broadcast Mode'."
        }
      ],
      "recommendations": [
        "Use this to determine if your bot can reply in a group where it is not admin.",
        "Display a 'Read Only' UI to agents if this is set to true."
      ],
      "args": {
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the group",
          "example": "1234567890@g.us"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Setting retrieved",
          "example": {
            "adminOnly": false
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "جلب إعدادات 'إرسال الرسائل للمسؤولين فقط'",
          "description": "التحقق مما إذا كان المسؤولون فقط هم من يمكنهم إرسال رسائل في المجموعة.",
          "tips": [
            {
              "title": "وضع الإعلان",
              "content": "يتحقق مما إذا كان 'إرسال الرسائل' مقيدًا بالمسؤولين."
            },
            {
              "title": "مصطلح",
              "content": "غالبًا ما يسمى 'مجموعة الإعلان' أو 'وضع البث'."
            }
          ],
          "recommendations": [
            "استخدم هذا لتحديد ما إذا كان الروبوت الخاص بك يمكنه الرد في مجموعة ليس مسؤولاً فيها.",
            "اعرض واجهة مستخدم 'للقراءة فقط' للوكلاء إذا تم تعيين هذا على true."
          ],
          "extraInfo": "\n# تدقيق المحادثات: السيطرة الاستراتيجية على الحوار العالمي\n\nفي شبكات المجتمعات الكبيرة، تعد القدرة على التحكم في \"الميكروفون\" لا تقل أهمية عن القدرة على إرسال الرسالة نفسها. تعد واجهة **جلب إعدادات قفل المراسلة** أداة أساسية لـ **التدقيق الاستراتيجي للمحادثات والتحقق من نسبة الإشارة إلى الضوضاء**.\n\n---\n\n## 🏗️ الفلسفة المعمارية: استرجاع قناع التفاعل\n\nمن منظور تقني، هذه الواجهة هي **لقطة سريعة للأذونات (Permissions Snapshot)**.\n*   **أساس جاهزية القناة**: قبل البدء في بث عالي الأولوية، يحتاج نظامك لمعرفة ما إذا كانت القناة \"خالية\". التحقق من قفل المراسلة يضمن أن يكون تنبيهك هو أول ما يراه المستخدم، وليس مدفوناً تحت ردود المشاركين.\n*   **المراقبة بدون صلاحيات**: يمكن لأي مثيل عضو في المجموعة الاستعلام عن هذه الإعدادات، مما يتيح لك بناء \"شبكة مراقبة\" تتتبع حالة المحادثات عبر مئات المجموعات دون الحاجة لصلاحيات إدارة في كل منها.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. التحقق الاستباقي من \"نظافة القناة\"\nفي نظام إشعارات الطوارئ، يقوم النظام أولاً بجلب إعدادات القفل؛ وإذا وجدها مفتوحة، يستدعي واجهة [القفل للمسؤولين فقط](/v2/groups/{id}/settings/security/messages-admin-only) لـ \"إخلاء القاعة\" قبل إرسال التنبيه الحرج، لضمان وصوله بشكل احترافي وغير متقطع.\n### 2. فرض \"ساعات الهدوء\" (Quiet Hours)\nيمكن للنظام استخدام هذه الواجهة للتدقيق في محفظة المجموعات عند انتهاء ساعات العمل. إذا كانت المجموعة لا تزال في \"وضع التعاون\"، يمكن للنظام قفلها تلقائياً لفرض سياسة \"منع الازعاج\" ليلاً.\n### 3. تشعب سير العمل الديناميكي\nيجب أن يتغير سلوك البوت بناءً على قفل المجموعة. فإذا كانت المجموعة مقفلة، يمكن للبوت الرد تلقائياً: *\"المجال مغلق حالياً للإعلانات الرسمية، سأكون متاحاً للأسئلة بمجرد إعادة فتح الدردشة\"*.\n\n---\n\n## 🛡️ أفضل الممارسات التشغيلية\nنوصي بعرض حالة \"الميكروفون\" (`مغلق` أو `مفتوح`) بوضوح في واجهة الوكيل، فهي معلومة حيوية لمن يدير مئات المحادثات. كما نوصي بتنسيق هذا الإعداد مع منطق معالجة الويب هوك؛ فإذا كانت المجموعة مفتوحة، يجب أن يستعد نظامك لحجم أكبر من الرسائل الواردة وتوسيع نطاق العمال (Workers) لمعالجتها. تذكر أن الويب هوك يخبرك بالحدث، لكن الـ GET يخبرك بالحقيقة الميدانية.\n            "
        }
      }
    },
    {
      "path": "/v2/groups/{id}/settings/security/messages-admin-only",
      "methods": [
        "PUT"
      ],
      "title": "Set messages admin only",
      "category": "Groups",
      "description": "Set whether only admins can send messages to the group.",
      "extraInfo": "\n# The Power of Silence: Mastering the Flow of Community Dialogue\n\nIn the high-velocity environment of distributed messaging, noise is the enemy of clarity. The **Set Messages Admin Only** endpoint (often referred to as **Announcement Mode**) is your primary tool for **Conversational Flow Control and Structural Discipline**. It allows you to programmatically toggle the ability for regular members to send messages in a group. By restricting the channel to administrator-only communication, you transform a potentially chaotic group chat into a high-fidelity broadcast channel, ensuring that your business's critical alerts and information are never \"Lost in the Scroll\" of participant chatter.\n\nFor enterprise architects, managing the \"Noise Level\" of a community is a critical component of **User Experience and Engagement Orchestration**. This guide explores the strategic imperatives of announcement mode and the art of focused conversation.\n\n---\n\n## 🏗️ Architectural Philosophy: The Enforcement of Unidirectional State\n\nFrom a technical perspective, this endpoint modifies the **Interaction Mask** of the group state.\n\n### Key Architectural Objectives:\n*   **The Foundation of Enterprise Clarity**: In large groups (up to 1,024 members), a single off-topic message can trigger a chain reaction of responses that buries important business updates. Announcement Mode provides a \"Noise-Floor\" of zero, allowing your business to use the group as a dedicated notification channel where every message is guaranteed to be from a verified official source.\n*   **The Power of Admin Authority**: This setting is a \"Privileged Toggle.\" To successfully lock or unlock the group's messaging permissions, your Wawp instance **must be a Group Admin**. This ensures that the control of the \"Microphone\" remains in the hands of the business account.\n*   **Seamless Global Enforcement**: Once the setting is flipped to `true`,\n  tips: [\n        {\n            type: 'positive',\n            title: 'Control',\n            content: 'Set to true to silence non-admins (Announcement Mode).'\n        },\n        {\n            type: 'info',\n            title: 'Reversible',\n            content: 'You can toggle this mode on/off as needed (e.g., open for Q&A, closed for night).'\n        }\n    ],\n  recommendations: [\n        \"Use Announcement Mode for official news channels.\",\n        \"Open the group for limited time windows to drive engagement.\",\n        \"Ensure admins are active to moderate if you open the floor.\"\n    ]\n  \n   the \"Message\" input field on every participant's device is instantly replaced by a system notice (*\"Only admins can send messages\"*). Metadata propagation is near-instant, providing a consistent global boundary for the conversation.\n\n---\n\n## 🚀 Strategic Use Cases: High-Impact Alerts and \"Quiet Hours\"\n\nAnnouncement Mode should not be seen as a permanent gag order, but as a dynamic \"Conversational Gearbox\" that your system can shift into depending on the business context.\n\n### 1. The \"Broadcast-First\" Crisis Escalation\nDuring a service outage or a critical incident, you may need to reach hundreds of stakeholders with precise, authoritative updates. By calling the **Set Messages Admin Only** endpoint at the start of the crisis, you ensure that the group remains a \"Clear Channel\" for your incident commanders. This prevents participants from flooding the chat with \"Is it down for you too?\" messages, which would distract the technical teams and obscure the official status reports.\n\n### 2. The \"Event-Driven Interaction\" Cycle\nImagine a daily webinar or a field service coordination group. During the \"Briefing Phase,\" the system locks the group to ensure everyone reads the instructions. Once the briefing is complete, the system calls the endpoint with `value: false`, \"Opening the Floor\" for a 15-minute Q&A session. Finally, at the end of the day, the system re-locks the group to prevent \"Late-Night Noise\" from disturbing participants. This \"Active Duty Cycle\" reflects a professional, time-sensitive management style.\n\n### 3. Automated Throttling During Resource Saturation\nIf your business logic detects that your human agents are being overwhelmed by a burst of incoming messages in a specific group (e.g., during a controversial marketing launch), your system can automatically trigger **Announcement Mode** as a \"Circuit Breaker.\" This provides your team with the \"Breathing Room\" needed to categorize existing requests before opening the floodgates again.\n\n---\n\n## 🔐 Administrative Mandate: Authority and Policy Governance\n\nControlling the \"Voice\" of the group is the ultimate act of moderation.\n\n### Centralizing the \"Source of Truth\"\nWhen a group is in Announcement Mode, every message has the implicit weight of the business's authority. This makes it the perfect state for:\n*   **Policy Updates**: Sharing new terms of service or compliance mandates.\n*   **Logistics Coordination**: Sending bus routes, room numbers, or schedule shifts.\n*   **KYC Reminders**: Informing a cohort of users that they need to complete a verification step.\nBecause participants cannot reply, these messages become \"System Records\" that users can rely on as the definitive truth.\n\n### Structural Integrity in Community Governance\nFor volunteer-led communities, the ability to lock the chat is the primary tool for **Moderation Enforcement**. If a discussion becomes heated or violates group standards, your automated moderator can call this endpoint to initiate a \"Cool-down Period.\" This forces a pause in the interaction, allowing emotions to settle before the channel is reopened.\n\n---\n\n## 🛡️ Operational Best Practices: Consistency and Engagement Timing\n\n*   **The \"Polite Lock\" Pattern**: Always precede a lock (`value: true`) with an explanatory message (e.g., *\"We are moving into Announcement Mode for the next hour to share project updates. The floor will be reopened at 2:00 PM.\"*). This maintains a positive user experience and prevents users from feeling \"Silenced\" without cause.\n*   **Time-Zone Awareness**: Be mindful of when you unlock a group. Reopening the floor for 500 participants at 3:00 AM in their local time zone can lead to a flood of notifications that disturb their sleep, leading to group exits.\n*   **Admin Participation Strategy**: Remember that all admins can still speak even when the group is locked. This allows you to have a \"Multi-Voice\" broadcast where your primary instance sends the alerts, while human managers provide additional context, all while the general population remains in a \"Listen-Only\" posture.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Verify Admin Permissions**: You cannot change the security settings of a group if you are not an admin. Always perform a pre-flight check via [Get Group Info](/v2/groups/{id}) to ensure your instance has the authority to execute the toggle.\n2.  **Idempotent State Management**: If your system needs to ensure a broadcast-only environment, sending `value: true` repeatedly is a safe, no-op operation. This allows you to tie the \"Locking State\" to your internal cron jobs or alert triggers without complex logic.\n3.  **Webhook Integration**: Listen for [`group.update`](/v2/webhooks/group-update) events. This allows your backend to track the *actual* state of the group's \"Microphone.\" If a human admin unlocks the group manually, your system can detect it and re-lock it if it violates your automated governance policy.\n\n---\n\n## 🎯 Conclusion: Mastering the Art of the Focused Conversation\n\nThe **Set Messages Admin Only** endpoint is the \"Conductor's Baton\" of your community architecture. It is your primary tool for managing engagement density, enforcing clarity, and ensuring that your organization's voice remains the loudest and clearest in the room. By treating the \"Voice\" of the group as a dynamic, programmable resource, you build a conversational ecosystem that respects your users' attention and guarantees the delivery of your most critical business assets. You move beyond \"Simple Chatting\" and into the world of **High-Fidelity Broadcast Orchestration**, where every word counts and every silence is strategic.\n    ",
      "args": {
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the group",
          "example": "1234567890@g.us"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "value": {
          "required": true,
          "type": "boolean",
          "description": "True to restrict to admins, false to allow all",
          "example": "true"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Setting updated",
          "example": {
            "ok": true
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "قصر إرسال الرسائل على المسؤولين فقط",
          "description": "تحديد ما إذا كان المسؤولون فقط هم من يمكنهم إرسال رسائل في المجموعة.",
          "tips": [
            {
              "title": "السيطرة",
              "content": "اضبط على true لإسكات غير المسؤولين (وضع الإعلان)."
            },
            {
              "title": "قابل للعكس",
              "content": "يمكنك تبديل هذا الوضع تشغيل/إيقاف حسب الحاجة (مثلًا، مفتوح للأسئلة والأجوبة، مغلق ليلًا)."
            }
          ],
          "recommendations": [
            "استخدم وضع الإعلان لقنوات الأخبار الرسمية.",
            "افتح المجموعة لفترات زمنية محدودة لزيادة التفاعل.",
            "تأكد من أن المسؤولين نشطون للإشراف إذا فتحت المجال."
          ],
          "extraInfo": "\n# قوة الصمت: إتقان تدفق حوار المجتمع\n\nفي بيئة المراسلة الموزعة السريعة، الضوضاء هي عدو الوضوح. تعد واجهة **قصر الرسائل على المسؤولين** (المعروفة بـ **وضع الإعلانات**) أداتك الأساسية لـ **التحكم في تدفق المحادثة والانضباط الهيكلي**.\n\n---\n\n## 🏗️ الفلسفة المعمارية: فرض حالة الاتجاه الواحد\n\nمن منظور تقني، تقوم هذه الواجهة بتعديل **قناع التفاعل (Interaction Mask)** لحالة المجموعة.\n*   **أساس الوضوح للمؤسسات**: في المجموعات الكبيرة (حتى 1024 عضواً)، يمكن لرسالة واحدة خارج الموضوع أن تطلق سلسلة من الردود التي تدفن تحديثات العمل المهمة. وضع الإعلانات يضمن أن تكون المجموعة قناة بث مخصصة تضمن وصول معلوماتك دون تشويش.\n*   **قوة سلطة المسؤول**: هذا الإعداد هو \"مفتاح صلاحيات\"؛ يجب أن يكون مثيل Wawp **مسؤولاً (Admin)** لتنفيذ هذا التبديل.\n*   **فرض عالمي سلس**: بمجرد تفعيل الإعداد (`true`)، يختفي حقل إدخال الرسائل لدى جميع المشاركين ويُستبدل بإشعار نظام فوري، مما يوفر حدوداً متسقة للمحادثة عالمياً.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. تصعيد الأزمات والبث عالي الأثر\nأثناء انقطاع الخدمة أو الحوادث الحرجة، تحتاج للوصول للمشاركين بتحديثات موثوقة. تفعيل \"وضع الإعلانات\" في بداية الأزمة يضمن بقاء القناة نظيفة لقادة الحوادث، ويمنع إغراق الدردشة بأسئلة \"هل الخدمة متعطلة لديكم؟\".\n### 2. دورة التفاعل القائمة على الأحداث\nفي مجموعات التنسيق الميداني، يمكن للنظام \"قفل\" المجموعة لضمان قراءة الجميع للتعليمات، ثم \"فتحها\" (`false`) لجلسة أسئلة وأجوبة لمدة 15 دقيقة، ثم إعادة القفل لمنع الإزعاج ليلاً.\n### 3. \"قاطع الدائرة\" (Circuit Breaker) التلقائي\nإذا اكتشف النظام تزايداً هائلاً في الرسائل الواردة بشكل قد يربك الوكلاء، يمكنه تفعيل \"وضع الإعلانات\" كقاطع دائرة لمنح الفريق مساحة لفرز الطلبات قبل إعادة فتح المجال.\n\n---\n\n## 🛡️ حوكمة السياسات ونظافة التشغيل\nالتحكم في \"صوت\" المجموعة هو العمل النهائي للإشراف. نوصي باتباع نمط **\"القفل المهذب\"**؛ فقبل القفل، أرسل رسالة توضح السبب ومتى سيتم إعادة الفتح. تذكر أن جميع المسؤولين يمكنهم الاستمرار في التحدث حتى والمجموعة مقفلة، مما يتيح لك بث \"متعدد الأصوات\" من خلال حسابات رسمية وبشرية مع إبقاء الجمهور في وضع الاستماع.\n            ",
          "args": {
            "value": {
              "description": "True لتقييد الإرسال للمسؤولين فقط، false للسماح للجميع"
            }
          }
        }
      }
    },
    {
      "path": "/v2/groups/{id}/invite-code",
      "methods": [
        "GET"
      ],
      "title": "Get the invite code for the group",
      "category": "Groups",
      "description": "Get the current invite code for the group.",
      "extraInfo": "\n# The Key to the Kingdom: Mastering the Distribution of Group Access\n\nIn the landscape of conversational growth, scale is achieved through friction-free entry. The **Get Invite Code** endpoint is your primary tool for **Strategic Access Management and Community Expansion**. While traditional participant management relies on direct \"Add\" operations—which require the business to have the user's contact saved—Invite Codes reverse the onboarding flow. They provide a portable, cryptographically secure token that allows any user to programmatically bridge themselves into your community. By retrieving this code via the API, you turn the \"Closed Gate\" of a private group into an \"Open Door\" that can be integrated into your website, your email campaigns, and your QR codes.\n\nFor enterprise architects, the invite code is the **Growth Engine** of the ecosystem. This guide explores the strategic imperatives of code-driven membership and the stewardship of entry rights.\n\n---\n\n## 🏗️ Architectural Philosophy: The Relationship Between JIDs and Tokens\n\nFrom a technical perspective, an invite code is a **Public Proxy for a Private Identifier**.\n\n### Key Architectural Objectives:\n*   **Decoupling Discovery from Identity**: A Global-JID (`@g.us`) is an internal identifier that is difficult for a regular user to use directly. The invite code provides a user-friendly, textual representation (`chat.whatsapp.com/ABC123...`) that the WhatsApp mobile app can instantly resolve. By retrieving this code, your system creates a \"Portable Link\" that travels through the public internet, ready to be resolved by the first user who clicks it.\n*   **The Power of Admin Stewardship**: Only a Group Admin can retrieve or manage the group's invite code. This ensures that the generation of entry links is a governed act. If your Wawp instance is a regular member, your request for the code will be denied, protecting the group's privacy from unauthorized link extraction.\n*   **Persistence and Volatility**: An invite code is persistent until it is explicitly [Revoked](/v2/groups/invite-code/revoke). This allows you to print a QR code on a billboard or include a link in a monthly newsletter, confident that it will remain functional for the life of the campaign unless you choose to reset it for security reasons.\n\n---\n\n## 🚀 Strategic Use Case: High-Velocity Acquisition and Funnel Integration\n\nThe invite code is the ultimate \"Call to Action\" for modern conversational marketing.\n\n### 1. The \"Zero-Friction\" Landing Page Funnel\nTraditionally, a customer has to \"Message us first\" to start a relationship. With the **Get Invite Code** endpoint, you can place a \"Join our VIP Community\" button directly on your checkout page or in an abandoned cart email. When the user clicks, they are instantly transported into your branded group environment. This eliminates the \"Add to Contacts\" friction, significantly increasing the conversion rate from a lead to a community member.\n\n### 2. Physical-to-Digital Bridge (QR Code Orchestration)\nFor events, retail stores, or packaged goods, the invite code is the primary link to a digital support group. Your system can programmatically retrieve the code for a specific regional group and generate a dynamic QR code for a store display. Customers can scan the code to instantly join a support group for that specific location, creating a \"Hyper-Local\" conversational layer that is centrally managed by your API.\n\n### 3. \"Viral\" Community Expansion\nIn customer loyalty programs, you can encourage existing members to \"Invite a Friend.\" By retrieving the invite code and sharing it with a loyal member, you empower them to act as a growth agent for your brand. Because the invite link is \"Native\" to WhatsApp, it is easily forwarded within the app, creating an organic sharing loop that allows your communities to grow exponentially without increasing your CAC (Customer Acquisition Cost).\n\n---\n\n## 🔐 Administrative Mandate: The Stewardship of Entry Rights\n\nWhile invite codes enable scale, they also introduce a unique security surface area. Anyone with the link can join the room.\n\n### Governance of the \"Open Gate\"\nThe invite code should be treated as a **Dynamic Permission**. We recommend that your system periodically rotates the code using the [Revoke Invite Code](/v2/groups/invite-code/revoke) endpoint. This \"Rotational Security\" ensures that old links found on cached Google pages or in legacy emails eventually stop working, allowing you to maintain control over the \"Cohort\" of users entering your groups at any given time.\n\n### Monitoring the \"Entry Pulse\"\nYour system should listen for the [`group.participants.update`](/v2/webhooks/group-participants-update) webhook. When a user joins via an invite code, the notification often includes a flag indicating the method of entry. By cross-referencing this with the time your API last retrieved the code, you can build \"Channel Analytics\"—measuring exactly which campaigns or websites are driving the most members into your WhatsApp communities.\n\n---\n\n## 🛡️ Operational Best Practices: Consistency, Analytics, and Tracking\n\n*   **URL Prefixing for Professionalism**: When sharing the code, always present it as a full URL: `https://chat.whatsapp.com/{code}`. This ensures that every operating system (Android, iOS, Web) recognizes it as a clickable deep link.\n*   **Metadata Preparation**: Before sharing an invite code publicly, ensure that the group's [Name](/v2/groups/{id}/subject), [Icon](/v2/groups/{id}/picture), and [Description](/v2/groups/{id}/description) are professional and ready for a first-time visitor. The \"Join\" screen is your customer's first impression of your conversational brand.\n*   **Limit the Group Size**: WhatsApp groups have a current limit of 1,024 members. Your system should monitor the member count via [Get Group Info](/v2/groups/{id}). Once a group approaches 90% capacity, your backend should \"Switch\" its landing page links to point to the invite code of a newly created \"Secondary Cell\" group.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Check Admin Permissions**: Your request for the invite code will fail if the Wawp instance is not an admin. Always perform a pre-flight check or implement a retry-after-promotion logic to ensure your link-generation service is always functional.\n2.  **Graceful Handling of Revocation**: If your system has previously stored an invite code in a database and a human admin revokes it manually from their phone, the old code in your database will become dead. Your logic should include a \"Periodic Refresh\" or a \"Check-on-Click\" mechanism to ensure the links you are serving to customers are still active.\n3.  **Cross-Instance Synchronization**: If you use multiple WhatsApp accounts to manage the same group, ensure only the \"Primary Account\" is responsible for managing the invite link to avoid \"Link Conflict\" or accidental revocation by a secondary instance.\n\n---\n\n## 🎯 Conclusion: Mastering the Art of the Accessible Community\n\nThe **Get Invite Code** endpoint is the \"Marketing Engine\" of your community architecture. It is your most powerful tool for building scalable, friction-free entries into your branded spaces. By treating the invite link as a dynamic, programmable asset, you move beyond \"Manual Onboarding\" and into the world of **Automated Acquisition**, where your communities grow in lockstep with your marketing reach. You bridge the gap between your web presence and your conversational world, ensuring that every customer is only one click away from a high-trust, professional interaction with your brand.\n    ",
      "tips": [
        {
          "type": "warning",
          "title": "Security",
          "content": "Anyone with this code can join. Treat it like a password."
        },
        {
          "type": "info",
          "title": "Format",
          "content": "Returns a full URL (https://chat.whatsapp.com/...) and the raw code."
        }
      ],
      "recommendations": [
        "Only share this code in secure channels.",
        "Revoke the code immediately if you detect unauthorized joins.",
        "Use this for 'open' communities where manual adding is too slow."
      ],
      "args": {
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the group",
          "example": "1234567890@g.us"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Invite code retrieved",
          "example": {
            "code": "ABC123XYZ"
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "جلب كود دعوة المجموعة",
          "description": "الحصول على كود الدعوة الحالي للمجموعة.",
          "tips": [
            {
              "title": "الأمان",
              "content": "يمكن لأي شخص لديه هذا الرمز الانضمام. عامله مثل كلمة المرور."
            },
            {
              "title": "التنسيق",
              "content": "يعيد رابطًا كاملاً (https://chat.whatsapp.com/...) والرمز الخام."
            }
          ],
          "recommendations": [
            "شارك هذا الرمز فقط في القنوات الآمنة.",
            "قم بإلغاء الرمز فورًا إذا اكتشفت انضمامات غير مصرح بها.",
            "استخدم هذا للمجتمعات 'المفتوحة' حيث تكون الإضافة اليدوية بطيئة جدًا."
          ],
          "extraInfo": "\n# مفتاح الوصول: إتقان توزيع الدخول للمجموعات\n\nفي عالم نمو المحادثات، يتم تحقيق التوسع من خلال الدخول السلس. تعد واجهة **جلب كود الدعوة** أداتك الأساسية لـ **إدارة الوصول الاستراتيجي وتوسيع المجتمع**. بينما تعتمد الإضافة التقليدية للمشاركين على عملية \"إضافة\" مباشرة — التي تتطلب حفظ جهة اتصال المستخدم — فإن أكواد الدعوة تعكس هذا التدفق؛ فهي توفر رمزاً آمنًا يتيح لأي مستخدم الانضمام لمنتداك برمجياً.\n\n---\n\n## 🏗️ الفلسفة المعمارية: العلاقة بين المعرفات والرموز\n\nمن منظور تقني، كود الدعوة هو **وكيل عام لمعرف خاص**.\n*   **فصل الاكتشاف عن الهوية**: معرف المجموعة (`@g.us`) هو معرف داخلي يصعب على المستخدم استخدامه مباشرة، بينما يوفر كود الدعوة رابطاً نصياً (`chat.whatsapp.com/...`) يمكن لتطبيق واتساب حله فوراً.\n*   **قوة الإشراف الإداري**: لا يمكن إلا لـ **مسؤول المجموعة (Admin)** استرداد الكود أو إدارته، مما يضمن أن توليد روابط الدخول هو عمل تحت الحوكمة.\n*   **الاستمرارية والتقلب**: يظل كود الدعوة قائماً حتى يتم [إلغاؤه](/v2/groups/invite-code/revoke) صراحةً، مما يتيح لك طباعة رمز QR أو تضمين رابط في نشرة إخبارية بثقة في بقائه فعالاً.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي: التحصيل عالي السرعة\n\n### 1. قمع هبوط \"بدون احتكاك\"\nتقليدياً، يجب على العميل مراسلتك أولاً. مع هذه الواجهة، يمكنك وضع زر \"انضم لمجتمع VIP\" مباشرة في صفحة إتمام الشراء، مما يزيل \"احتكاك\" حفظ الأرقام في جهات الاتصال ويزيد معدل التحويل بشكل كبير.\n### 2. جسر من الواقع إلى العالم الرقمي (QR Codes)\nبالنسبة للفعاليات أو المتاجر، يمكن لنظامك جلب الكود لمجموعة إقليمية وتوليد رمز QR ديناميكي للعرض في المتجر، ليمسحه العملاء وينضموا فوراً لمجموعة دعم لهذا الموقع المحدد.\n\n---\n\n## 🛡️ أفضل الممارسات التشغيلية\n*   **هوية الرابط**: عند مشاركة الكود، يفضل دائماً تقديمه كرابط كامل: `https://chat.whatsapp.com/{code}` لضمان تعرف جميع أنظمة التشغيل عليه كرابط عميق قابل للنقر.\n*   **مراقبة نبض الدخول**: استمع لويب هوك [`group.participants.update`](/v2/webhooks/group-participants-update)؛ فعندما ينضم مستخدم عبر كود، يتضمن الإخطار غالباً طريقة الدخول، مما يساعدك في قياس كفاءة حملاتك.\n            "
        }
      }
    },
    {
      "path": "/v2/groups/{id}/invite-code/revoke",
      "methods": [
        "POST"
      ],
      "title": "Invalidates the current group invite code and generates a new one",
      "category": "Groups",
      "description": "Revoke the current invite code and generate a new one.",
      "extraInfo": "\n# Retracting the Welcome: The Strategic Power of Access Revocation\n\nIn the lifecycle of a growing community, the ability to open a door is only half of the governance required; the other half is the ability to change the lock. The **Revoke Invite Code** endpoint is your primary tool for **Strategic Access Nullification and Perimeter Defense**. It allows you to programmatically invalidate the current public-facing invite link (`chat.whatsapp.com/...`) and replace it with a fresh, secure token. This endpoint is the essential counterbalance to the [Get Invite Code](/v2/groups/{id}/invite-code) API, ensuring that your growth remains governed, your cohorts remain isolated, and your group's security perimeter can be rapidly reset in the event of an unauthorized link leak.\n\nFor enterprise architects, revocation is the act of **Reclaiming the Gateway**. This guide explores the strategic imperatives of token rotation and the enforcement of disciplined access lifecycles.\n\n---\n\n## 🏗️ Architectural Philosophy: The Invalidation of Public Tokens\n\nFrom a technical perspective, revoking an invite code is an **Atomically Destructive State Transition**.\n\n### Key Architectural Objectives:\n*   **Immediate Access Severance**: The moment this call is executed, the old invite code is purged from Meta's global resolution directory. Any user who clicks on a legacy link will be met with an \"Invite link has been reset\" or \"This group doesn't exist\" message. This \"Instant Blackhole\" is critical for stopping an influx of unwanted participants who have discovered a link on an unauthorized forum or social media post.\n*   **Mandatory Generation of the New State**: A unique feature of this endpoint is that it doesn't just delete the old code; it **Gives You the New One** in the same response. This ensures that the group always has a functional invite path for your administrative systems, even as you retire the public-facing one.\n*   **The Power of Admin Sovereignty**: Revocation is a high-authority act. Your Wawp instance **must be a Group Admin** to execute this call. This prevents participants from trying to sabotage your growth funnels by maliciously resetting the link.\n\n---\n\n## 🚀 Strategic Use Case: Cohort Isolation and Campaign Discipline\n\nRevocation should be integrated into your \"Campaign Lifecycle\" to handle transition phases and security incidents.\n\n### 1. The \"Campaign Decommissioning\" Protocol\nMarketing campaigns are often time-bound. A \"Join our Black Friday VIP List\" link should not be active in July. By programmatically calling the **Revoke Invite Code** endpoint at the end of a marketing window, you ensure that your \"Black Friday\" group doesn't continue to collect \"Zombie Participants\" who stumble upon the link months later. This allows you to \"Seal the Cohort,\" ensuring that the group remains focused on the specific audience it was created for.\n\n### 2. Rotational Security for High-Value Groups\nFor high-security operations (like a corporate whistleblower group or a high-value transaction hub), an invite link may be shared with a specific stakeholder via email. Once that stakeholder has [Joined](/v2/groups/join), the \"One-Time Use\" policy should be enforced. Your system can listen for the join webhook and immediately call the **Revoke Invite Code** endpoint to invalidate the link. This \"Just-in-Time Revocation\" ensures that the link cannot be forwarded or reused by unauthorized third parties.\n\n### 3. Immediate \"Bot Attack\" Mitigation\nIf your system detects a sudden, rapid influx of unauthorized users (a common sign of a bot attack or a link leak), your \"Breaker Logic\" should trigger an immediate revocation. By resetting the link, you instantly \"Shut the Gate,\" allowing your human moderation team to [Prune](/v2/groups/{id}/participants/remove) the interlopers while your automated backend generates a new, secure link for legitimate distribution.\n\n---\n\n## 🔐 Administrative Mandate: Authority and Boundary Stewardship\n\nIn an enterprise setting, an invite link is a liability that must be actively managed.\n\n### Tracking the \"Token Lineage\"\nYour backend should maintain a history of all invite codes generated for a specific group. This allows you to perform \"Attribution Analysis\"—if an unauthorized user joins, you can check which retired code they attempted to use (if the network permits) or at least know which \"Campaign Window\" was compromised. Revocation is the \"Red Ink\" in the audit log that marks the end of a specific access period.\n\n### Coordination with Physical Assets (Dynamic QRs)\nIf you are using dynamic QR codes in retail locations, ensure your QR generator is \"Aware\" of the revocation. When you rotate the code, your generator must update its target URL to the new code returned by the API. If your QR codes are static (printed on packaging), **Do Not Revoke the Code** unless it is a dire security emergency, as it will render all physical packaging useless. This illustrates the importance of using \"Redirector Links\" for any physical branding.\n\n---\n\n## 🛡️ Operational Best Practices: Professionalism and Graceful Transitions\n\n*   **The \"Notice of Reset\" Pattern**: If you are rotating a link that is currently being used by a legitimate partner or team, send them the new link *before* you revoke the old one to avoid \"Access Gaps.\"\n*   **Internal State Reconciliation**: Upon successful revocation, update your internal database with the new code immediately. Any \"Join Link\" buttons on your website or dashboard must be synchronized to the new token to prevent a \"Broken Link\" experience for your customers.\n*   **Avoid \"Chatter\" Revocation**: Revoking a link multiple times in a few minutes is unnecessary and can lead to synchronization lag across Meta's global CDN. Stick to a \"Schedule-Driven\" or \"Incident-Driven\" rotation policy.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Verify Admin Status**: Like all administrative tools, your request will fail with a 403 if your instance has been demoted. Implement a \"Governance Watchdog\" that ensures your instance's authority is verified before attempting high-security tasks like revocation.\n2.  **Graceful Response Handling**: The API returns the new code in the success object. Ensure your code captures this value and propagates it to your marketing systems. A failure to update the link after a revocation is a self-inflicted \"Denial of Service\" attack on your own funnels.\n3.  **Webhook Integration**: Listen for [`group.update`](/v2/webhooks/group-update) events. This allows your backend to detect if a human admin has revoked the link via the mobile app, ensuring your database and the network's reality are always aligned.\n\n---\n\n## 🎯 Conclusion: Mastering the Art of the Governed Access\n\nThe **Revoke Invite Code** endpoint is the \"Security Shield\" of your community architecture. It allows you to maintain absolute control over the gateways to your private conversations, enabling you to scale without fear of unauthorized access. By treating the invite link as a temporary, rotating token rather than a permanent asset, you build a conversational environment that is resilient, disciplined, and always aligned with your organization's highest standards of governance. You move beyond \"Open-Door\" policies and into the world of **Managed Access Orchestration**, where every entry is a choice and every link is a controlled instrument of growth.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Instant Effect",
          "content": "The old invite link will stop working immediately."
        },
        {
          "type": "positive",
          "title": "Auto-Gen",
          "content": "A new code is automatically generated upon revocation."
        }
      ],
      "recommendations": [
        "Automate revocation if you detect an influx of spam bots.",
        "Notify legitimate waiting users that the link has changed."
      ],
      "args": {
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the group",
          "example": "1234567890@g.us"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Invite code revoked and recreated",
          "example": {
            "code": "NEW456DEF"
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "إلغاء كود دعوة المجموعة وتوليد كود جديد",
          "description": "إبطال كود الدعوة الحالي وتوليد كود جديد للمجموعة.",
          "extraInfo": "\n# سحب الترحيب: القوة الاستراتيجية لإلغاء الوصول\n\nفي دورة حياة المجتمع المتنامي، القدرة على فتح الباب هي نصف الحوكمة فقط؛ النصف الآخر هو القدرة على \"تغيير القفل\". تعد واجهة **إلغاء كود دعوة المجموعة** أداتك الأساسية لـ **إبطال الوصول الاستراتيجي والدفاع عن محيط المجموعة**. هي تتيح لك إبطال رابط الدعوة العام الحالي برمجياً واستبداله برمز آمن وجديد.\n\n---\n\n## 🏗️ الفلسفة المعمارية: إبطال الرموز العامة\n\nمن الناحية الفنية، إلغاء كود الدعوة هو **انتقال حالة تدميري بشكل \"ذرّي\"**.\n*   **قطع الوصول الفوري**: بمجرد تنفيذ هذا الطلب، يتم مسح الكود القديم من سجلات التحليل العالمية لشركة Meta. أي مستخدم ينقر على الرابط القديم سيواجه رسالة \"تمت إعادة ضبط رابط الدعوة\". هذا \"الثقب الأسود الفوري\" حيوي لوقف تدفق المشاركين غير المرغوب فيهم إذا تم تسريب الرابط في منتدى غير مصرح به.\n*   **التوليد الإلزامي لحالة جديدة**: الميزة الفريدة لهذه الواجهة هي أنها لا تحذف الكود القديم فحسب، بل **تعطيك الكود الجديد** في نفس الاستجابة، مما يضمن بقاء مسار دعوة فعال لأنظمتك الإدارية.\n*   **سلطة السيادة الإدارية**: الإلغاء هو عمل ذو صلاحية عالية؛ يجب أن يكون مثيل Wawp **مسؤولاً (Admin)** في المجموعة لتنفيذ هذا الطلب، مما يمنع المشاركين العاديين من تخريب قمع النمو الخاص بك.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي: عزل الأفواج (Cohorts) وانضباط الحملات\n\n### 1. بروتوكول \"إيقاف الحملة\"\nالحملات التسويقية غالباً ما تكون محددة بوقت. عبر إلغاء كود الدعوة في نهاية نافذة التسويق، تضمن عدم استمرار المجموعة في جمع \"مشاركين شبحيين\" عثروا على الرابط بعد شهور، مما يحافظ على تركيز المجموعة على جمهورها المحدد.\n### 2. الأمن التدويري للمجموعات عالية القيمة\nفي العمليات عالية الأمان، قد يتم مشاركة الرابط مع صاحب مصلحة محدد. بمجرد [انضمامه](/v2/groups/join)، يمكن لنظامك فوراً إلغاء الرابط لضمان عدم توجيهه أو إعادة استخدامه من قبل أطراف ثالثة (سياسة الاستخدام لمرة واحدة).\n### 3. التخفيف الفوري لهجمات البوتات\nإذا اكتشف نظامك تدفقاً سريعاً ومفاجئاً لمستخدمين غير مصرح لهم، فيجب أن يطلق منطق الحماية إلغاءً فورياً للكود لـ \"إغلاق البوابة\" فوراً.\n\n---\n\n## 🛡️ أفضل الممارسات التشغيلية\nعند إلغاء كود، تأكد من تحديث قاعدة بياناتك الداخلية بالكود الجديد فوراً. يجب مزامنة أي أزرار \"رابط انضمام\" على موقعك الإلكتروني أو لوحة التحكم مع الرمز الجديد لمنع انقطاع الوصول لعملائك الشرعيين. ثبات الحالة العالمية لـ WhatsApp وجعل حقيقة شبكتك متماشية مع بياناتك هو جوهر الحوكمة الناجحة.\n            ",
          "tips": [
            {
              "title": "تأثير فوري",
              "content": "سيتوقف رابط الدعوة القديم عن العمل فورًا."
            },
            {
              "title": "توليد تلقائي",
              "content": "يتم إنشاء رمز جديد تلقائيًا عند الإلغاء."
            }
          ],
          "recommendations": [
            "قم بأتمتة الإلغاء إذا اكتشفت تدفقًا لروبوتات الرسائل العشوائية.",
            "أخطر المستخدمين الشرعيين المنتظرين بأن الرابط قد تغير."
          ]
        }
      }
    },
    {
      "path": "/v2/groups/{id}/participants",
      "methods": [
        "GET"
      ],
      "title": "Get participants",
      "category": "Groups",
      "description": "Retrieve a list of all participants in the group.",
      "extraInfo": "\n# Demographic Intelligence: The Strategic Audit of Community Membership\n\nIn the orchestration of distributed human networks, understanding *who* is in the room is the foundation of engagement, security, and personalization. The **Get Participants** endpoint is your primary tool for **Strategic Demographic Auditing and Population Mapping**. It allows your automated systems to retrieve a comprehensive census of every JID (`@c.us`) currently associated with a specific WhatsApp group. Beyond a simple list of numbers, this endpoint provides the structural context required to differentiate between influencers (Admins), owners (Creators), and the general population, enabling your platform to tailor its logic to the specific hierarchy of the community.\n\nFor enterprise architects, the participant list is the **Raw Material of Targeting**. This guide explores the strategic imperatives of membership auditing and the governance of group identity.\n\n---\n\n## 🏗️ Architectural Philosophy: Retrieving the Population State\n\nFrom a technical perspective, the Get Participants endpoint is a **State Snapshot of a One-to-Many Mapping**.\n\n### Key Architectural Objectives:\n*   **The Authority Matrix**: Every participant object in the response includes critical boolean flags: `isAdmin` and `isSuperAdmin` (Creator). By retrieving this list, your system builds an \"Authority Map,\" allowing it to know exactly which users have the power to [Add](/v2/groups/{id}/participants/add) or [Remove](/v2/groups/{id}/participants/remove) others. This is essential for building moderated systems that respect the existing human power structure within the chat.\n*   **Real-Time Population Integrity**: WhatsApp groups are fluid; members join and leave constantly. The Get Participants API provides a \"Synchronized Baseline,\" ensuring that your system's internal record of the group's \"Census\" matches the ground truth on Meta's servers. This is critical for preventing \"Ghost Messaging\" to members who have already left or ignoring new members who have just arrived.\n*   **Decoupling Presence from Contacts**: Your instance can see and list all participants in a group even if those users aren't in your official phone contact list. This \"Native Discovery\" is what allows business bots to interact with an unlimited number of customers without the friction of manual contact saving.\n\n---\n\n## 🚀 Strategic Use Case: Target Segmentation and Automated Whitelisting\n\nThe participant list is more than just a registry; it is a signal for automated business logic.\n\n### 1. The \"VIP Tier\" Dynamic Segmentation\nYour system can periodically audit the membership of high-value support groups. If it detects a specific \"Power User\" (identified by their JID in your CRM) is present in multiple groups, the system can automatically flag them for a \"Premium Experience\" or [Promote](/v2/groups/{id}/admin/promote) them to a moderator role. This \"Automated Meritocracy\" ensures that your most important stakeholders are always recognized and empowered within your conversational ecosystem.\n\n### 2. Forensic Auditing and Compliance Verification\nIn regulated sectors (like Healthcare or Finance), knowing who has access to a conversation is a legal requirement. Your system should perform a \"Compliance Audit\" every 24 hours. By calling the **Get Participants** endpoint and comparing the list against your internal \"Authorized Stakeholder Whitelist,\" you can detect \"Unauthorized Observers\"—users who were added manually by a human but who shouldn't have access to sensitive data. The system can then automatically [Remove](/v2/groups/{id}/participants/remove) them, maintaining your organization's regulatory posture.\n\n### 3. Audience Synchronizing for Multi-Channel Orchestration\nIf you are running a combined Email and WhatsApp campaign, the Group Participant list is your \"Source of Truth\" for the WhatsApp segment. Your system can extract the JIDs, map them to email addresses in your CRM, and ensure that a user who receives a \"Group Update\" on WhatsApp also receives the detailed \"Follow-up Report\" via email. This cross-channel synchronization turns a simple chat group into a sophisticated, multi-touch engagement engine.\n\n---\n\n## 🔐 Administrative Mandate: Privacy and the Governance of Identity\n\nManaging a list of human identifiers is a high-responsibility task that requires strict governance.\n\n### Protecting the \"Digital Footprint\"\nGroup participant lists are sensitive data. Your system should ensure that only authorized senior agents or specific automated controllers can access the raw participant data. In your platform's UI, consider masking parts of the phone number for regular agents, while allowing the \"Master Logic\" to use the full JID for routing and personalization. The **Get Participants** endpoint is the \"Secure Feed\" that your platform must protect.\n\n### Handling \"Group Saturation\" (Large Group Logic)\nWhatsApp groups currently support up to 1,024 members. When your system retrieves a participant list for a group nearing this limit, the response can be large. Your backend infrastructure should be optimized to parse these arrays efficiently. We recommend implementing \"Differential Updates\"—comparing the new list with the previous one and only processing the *changes* (joins/leaves)—to minimize the database load and keep your targeting logic responsive.\n\n---\n\n## 🛡️ Operational Best Practices: Consistency and Reconciliation\n\n*   **The \"Welcome Bot\" Trigger**: While the [`group.participants.update`](/v2/webhooks/group-participants-update) webhook is great for real-time events, the **Get Participants** endpoint is your \"Reconciliation Guardrail.\" If your system is unsure about a user's current status, a single GET call provides the definitive answer.\n*   **Staggered Audits**: For organizations managing thousands of groups, avoid auditing every participant list at the same time. Stagger your audits over a 24-hour cycle to distribute the API load and ensure a consistent flow of demographic intelligence.\n*   **Integrity Checks after Migration**: If you move your business logic from one WhatsApp account to another, use the Get Participants API to \"Verify the Handover.\" Ensure that all members from the old groups have been successfully onboarded into the new ecosystem.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Check Instance Membership**: You cannot retrieve the participant list for a group you are not a member of. Attempting to do so will return a 404 or 403 error. Always perform a pre-flight check to ensure your instance is present in the channel.\n2.  **Handle Admin State Mapping**: Remember that `isAdmin` is a state that can change at any time. Your system should not \"Cache and Forget\" this value. The Get Participants call should be treated as a \"Live View\" that expires quickly.\n3.  **Webhook Synchronization**: Professional systems should use a \"Hybrid Model\": listen for webhooks for 99% of updates, and use the **Get Participants** API as the \"Authority\" for 1% of edge cases or system re-initializations.\n\n---\n\n## 🎯 Conclusion: Mastering the Art of the Populated Community\n\nThe **Get Participants** endpoint is the \"Census Bureau\" of your community architecture. It is your most powerful tool for understanding your audience, enforcing security, and personalizing the conversational experience at scale. By treating the participant list as a dynamic, programmable map of authority and identity, you build a conversational ecosystem that is resilient, compliant, and always perfectly targeted. You move beyond \"Sending Messages into a Void\" and into the world of **Structured Demographic Orchestration**, where every interaction is informed by exactly who is listening and who has the power to lead.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Scaling",
          "content": "Large groups return large arrays. Handle pagination or timeouts."
        },
        {
          "type": "info",
          "title": "Roles",
          "content": "The response includes the role (admin, superadmin, participant) of each user."
        }
      ],
      "recommendations": [
        "Cache the participant list and only update on 'participant_changed' events.",
        "Use this to audit who is actually in the group vs your database.",
        "Filter by role to find all admins quickly."
      ],
      "args": {
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the group",
          "example": "1234567890@g.us"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Participants retrieved",
          "example": [
            {
              "id": "1234567890@c.us",
              "isAdmin": true,
              "isSuperAdmin": false
            }
          ]
        }
      ],
      "translations": {
        "ar": {
          "title": "جلب قائمة المشاركين",
          "description": "استرداد قائمة بجميع المشاركين في المجموعة.",
          "tips": [
            {
              "title": "التوسع",
              "content": "المجموعات الكبيرة تعيد مصفوفات كبيرة. تعامل مع تقسيم الصفحات أو المهلة."
            },
            {
              "title": "الأدوار",
              "content": "تتضمن الاستجابة دور (مسؤول، مسؤول متميز، مشارك) لكل مستخدم."
            }
          ],
          "recommendations": [
            "قم بتخزين قائمة المشاركين مؤقتًا وتحديثها فقط في أحداث 'تغيير المشارك'.",
            "استخدم هذا لمراجعة من هو موجود بالفعل في المجموعة مقابل قاعدة بياناتك.",
            "قم بالتصفية حسب الدور للعثور على جميع المسؤولين بسرعة."
          ],
          "extraInfo": "\n# ذكاء الديموغرافيا: التدقيق الاستراتيجي لعضوية المجتمع\n\nفي إدارة الشبكات البشرية الموزعة، يعد فهم *من* في الغرفة هو أساس التفاعل والأمان والتخصيص. تعد واجهة **جلب المشاركين** أداتك الأساسية لـ **التدقيق الديموغرافي الاستراتيجي ورسم خرائط السكان**. فهي تتيح لأنظمتك المؤتمتة الحصول على تعداد شامل لكل معرف واتساب (`@c.us`) مرتبط حالياً بمجموعة محددة.\n\n---\n\n## 🏗️ الفلسفة المعمارية: استرجاع حالة السكان\n\nمن منظور تقني، واجهة جلب المشاركين هي **لقطة لحالة الربط بين \"واحد إلى متعدد\"**.\n*   **مصفوفة السلطة**: يتضمن كل كائن مشارك في الاستجابة علامات منطقية هامة: `isAdmin` (مسؤول) و `isSuperAdmin` (المنشئ). يتيح ذلك لنظامك بناء \"خريطة سلطة\"، مما يساعده في معرفة المستخدمين الذين يملكون صلاحية الإضافة أو الإزالة.\n*   **نزاهة السكان في الوقت الفعلي**: مجموعات واتساب متقلبة؛ الأعضاء ينضمون ويغادرون باستمرار. توفر هذه الواجهة \"خطاً أساسياً متزامناً\"، مما يضمن مطابقة سجلات نظامك مع الحقيقة الميدانية على خوادم Meta.\n*   **فصل التواجد عن جهات الاتصال**: يمكن لمثيلك رؤية وإدراج جميع المشاركين في المجموعة حتى لو لم يكونوا في قائمة جهات اتصال الهاتف الرسمية الخاصة بك. هذا \"الاكتشاف الأصيل\" هو ما يسمح للبوتات بالتفاعل مع عدد غير محدود من العملاء دون قيود.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. التدقيق الجنائي والتحقق من الامتثال\nفي القطاعات الخاضعة للتنظيم (مثل الصحة أو المالية)، يعد معرفة من لديه حق الوصول للمحادثة متطلباً قانونياً. يمكن لنظامك إجراء \"تدقيق امتثال\" كل 24 ساعة بمقارنة قائمة المشاركين مع \"القائمة البيضاء للمصرح لهم\" واكتشاف أي مراقبين غير مصرح لهم تمت إضافتهم يدوياً وإزالتهم تلقائياً.\n### 2. مزامنة الجمهور عبر القنوات\nإذا كنت تدير حملة مشتركة بين البريد الإلكتروني وواتساب، فإن قائمة مشاركي المجموعة هي \"مصدر الحقيقة\" الخاص بك لقطاع واتساب، مما يتيح لك مطابقة المعرفات مع عناوين البريد الإلكتروني في CRM الخاص بك لضمان اتساق الرسائل.\n\n---\n\n## 🛡️ أفضل الممارسات التشغيلية\nنوصي باستخدام \"نموذج هجين\": الاستماع للويب هوك لـ 99% من التحديثات، واستخدام واجهة **جلب المشاركين** كـ \"المرجع النهائي\" لحالات الحواف أو عند إعادة تهيئة النظام وضمان دقة العرض في لوحة التحكم الخاصة بك.\n            "
        }
      }
    },
    {
      "path": "/v2/groups/{id}/participants/add",
      "methods": [
        "POST"
      ],
      "title": "Add participants",
      "category": "Groups",
      "description": "Add one or more participants to the group.",
      "extraInfo": "\n# Expanding the Circle of Trust: The Strategic Orchestration of Participants\n\nIn the architecture of a managed community, the **Add Participants** endpoint is the primary mechanism for scaling interaction and introducing new voices into a shared state. It is not merely a technical bridge to increase a group's headcount; it is a strategic operation that determines who enters your community's \"Trust Zone\" and how your business scales its collaborative reaching. By programmatically managing membership, you shift from the reactive manual addition of users to a proactive, event-driven orchestration model where participants are injected into conversations precisely when their presence is required by the business workflow.\n\nSuccessful community scaling requires a deep understanding of **Governance, Consent, and Systemic Trust**. This guide explores the architectural nuances of participant expansion within the WhatsApp ecosystem.\n\n---\n\n## 🏗️ Architectural Philosophy: The Convergence of Identity and Authority\n\nFrom a system design perspective, adding a participant is an **Authorization Event**. You are granting a specific JID (WhatsApp ID) access to the persistent message history and metadata of a community.\n\n### Key Architectural Objectives:\n*   **The Power of Admin Rights**: Adding participants is a privileged operation. To execute this call, your Wawp instance **must be a Group Admin**. If your instance has been demoted by another admin, the operation will fail with a 403 Forbidden error. Checking your instance's current authority via the [Get Group Info](/v2/groups/{id}) endpoint before attempting a participant expansion is a critical component of a \"Validation-First\" architecture.\n*   **Synchronous State Updates**: When a participant is successfully added, the state change is instantly propagated to every existing member's device. This is often accompanied by a system-generated notice in the chat (e.g., *\"Business Name added [User]\"*). Your system should be prepared to follow this state change with a high-context welcome message, ensuring the new participant is instantly \"Hydrated\" with the group's purpose.\n*   **Multi-Participant Batching**: This endpoint allows for the addition of multiple JIDs in a single request. However, while technologically possible, batching should be used with strategic restraint to maintain a high account reputation score and avoid triggering \"Mass-Spam\" heuristics.\n\n---\n\n## 🚀 Navigating the \"Privacy Shield\": Direct Adds vs. Invite Fallbacks\n\nOne of the most frequent challenges in automated group management is the **WhatsApp Privacy Wall**. WhatsApp provides users with granular control over who can add them to groups.\n\n### The \"Permission Failure\" Scenario\nIf a user has set their privacy settings to \"My Contacts Only\" and your instance is not in their address book, a direct `add` operation will appear to succeed at the API level (returning a 200 OK) but the user will **not** actually appear in the group. This is intentional—it is a security feature designed by Meta to prevent unwanted group participation.\n\n### The \"Invite-as-Fallback\" Strategic Pattern\nTo build a resilient integration that guarantees a path to participation, your system should implement a **Verification and Link sequence**:\n1.  **Initial Add**: Attempt to add the user directly via this endpoint.\n2.  **State Audit**: After a few seconds, verify the group the membership list.\n3.  **Fallback**: If the user is missing from the list, automatically send them a 1:1 message containing the [Group Invite Link](/v2/groups/invite-code). This \"Hybrid Approach\" respects the user's privacy while still empowering them to join the conversation voluntarily.\n\n---\n\n## 🏭 Enterprise Workflow Patterns: Automated Context Injection\n\n### 1. The Dynamic \"Follow-the-Sun\" Support Desk\nIn a 24/7 global support environment, your \"Case Group\" needs to transition between shifts. As the European support lead finishes their day, your system automatically adds the North American shift manager to the group. This ensures that the customer's shared context remains unbroken, and the new expert is brought into the conversation with the full history of the troubleshooting steps already taken.\n\n### 2. The KYC & Verification \"War Room\"\nFor financial services or high-value onboarding, a group might start with just the customer and a bot. Once the bot collects the preliminary documentation, it automatically **Adds a Verification Specialist** to the group to perform a live identity check. This seamless transition from bot-to-human interaction within a single shared state creates a premium, high-fidelity experience for the user.\n\n### 3. The Onsite Event \"Breakout\" Coordination\nFor physical events or workshops, groups can be created for specific breakout sessions. As attendees scan an NFC tag or QR code at their table, the system adds them to the session's group. This allows the facilitator to blast slides, collect real-time polls, and coordinate group activity without requiring manual entry of every attendee's phone number.\n\n---\n\n## 🛡️ Security, Compliance, and the \"Social History\" Mandate\n\nAdding users to groups is a \"High-Sensitivity\" signal for Meta's security heuristics. To protect your business account from being flagged as a spam vector, follow these enterprise-governance principles:\n\n*   **Prioritize Pre-Existing Relationships**: Avoid \"Cold Adds.\" In a professional orchestration model, your system should only add users to a group who have already had at least one 1:1 interaction with your business account within the last 24-48 hours. This \"Social Warm-up\" signals to the WhatsApp network that the group addition is a legitimate continuation of an established dialogue.\n*   **Rate Throttling & Burst Management**: Avoid adding dozens of users to a group simultaneously. We recommend a \"Drip Addition\" approach—adding no more than 5-10 users per minute. This keeps the conversational \"Noise Level\" low for existing members and ensures steady, predictable performance from Meta's infrastructure.\n*   **Administrative Oversight of Members**: Always maintain a clear \"Audit Trail\" of who was added and by which business logic. This is essential for GDPR compliance and for internal security reviews if a participant later engages in prohibited behavior.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Check Group Capacity**: WhatsApp Groups are currently capped at **1,024 participants**. Before calling the Add endpoint, your system should check the current headcount. Attempting to add users to a full group will result in a failure that could have been avoided with a simple pre-flight check.\n2.  **Verify Participant Authenticity**: Ensure that the JIDs you are adding are correctly formatted (`@c.us`). Attempting to add group IDs (`@g.us`) or malformed strings will result in avoidable API errors.\n3.  **Idempotency & Resilience**: Adding a user who is already a member of the group is a safe, idempotent operation. It will not create a duplicate entry or return an error. This allows you to \"Re-Assert\" participation during a recovery workflow without fear of corrupting the group state.\n\n---\n\n## 🎯 Conclusion: Orchestrating the Scalable Human Touch\n\nThe **Add Participants** endpoint is the bridge between your automated logic and your human community. By treating the expansion of a group as a **Strategic Event** rather than a simple data entry task, you build a conversational architecture that is both powerful and governed. When used in conjunction with the [Invite Link API](/v2/groups/invite-code) and the [Roles API](/v2/groups-overview), it becomes a foundational tool for creating dynamic, high-fidelity environments where the right people are in the right room at exactly the right time.\n    ",
      "tips": [
        {
          "type": "warning",
          "title": "Privacy",
          "content": "Users can block being added to groups by strangers."
        },
        {
          "type": "info",
          "title": "Failures",
          "content": "If an add fails, you may need to send an invite link instead."
        }
      ],
      "recommendations": [
        "Check if the user exists on WhatsApp before attempting to add.",
        "Do not spam-add users who have previously left.",
        "Handle partial successes (some users added, others failed)."
      ],
      "args": {
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the group",
          "example": "1234567890@g.us"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "participants": {
          "required": true,
          "type": "array",
          "description": "List of JIDs to add",
          "example": "[{\"id\":\"1234567890@c.us\"}]"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Participants added",
          "example": {
            "ok": true
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "إضافة مشاركين",
          "description": "إضافة مشارك واحد أو أكثر إلى المجموعة.",
          "extraInfo": "\n# توسيع دائرة الثقة: التنسيق الاستراتيجي للمشاركين\n\nتعد واجهة **إضافة المشاركين** الآلية الأساسية للتوسع في التفاعل وإدخال أصوات جديدة إلى الحالة المشتركة. هي ليست مجرد جسر تقني لزيادة عدد أعضاء المجموعة، بل عملية استراتيجية تحدد من يدخل \"منطقة الثقة\" في مجتمعك.\n\n---\n\n## 🏗️ الفلسفة المعمارية: تلاقي الهوية والسلطة\n\nمن منظور تصميم النظام، إضافة مشارك هي **حدث تفويض**. أنت تمنح معرف واتساب (JID) صلاحية الوصول إلى تاريخ الرسائل والبيانات الوصفية للمجتمع.\n*   **قوة حقوق المسؤول**: إضافة المشاركين هي عملية ذات صلاحيات؛ يجب أن يكون مثيل Wawp **مسؤولاً (Admin)** لتنفيذ هذا الطلب.\n*   **تحديثات الحالة المتزامنة**: عند إضافة مشارك بنجاح، ينتشر تغيير الحالة فوراً إلى أجهزة جميع الأعضاء الحاليين، وغالباً ما تصحبه رسالة نظام في المحادثة. يجب أن يكون نظامك مستعداً لإرسال رسالة ترحيب ذات سياق عالٍ فور الإضافة.\n\n---\n\n## 🚀 تجاوز \"درع الخصوصية\": الإضافة المباشرة مقابل روابط الدعوة\nأحد أكثر التحديات شيوعاً هو **جدار خصوصية واتساب**. يمكن للمستخدمين التحكم في من يضيفهم للمجموعات.\n*   **سيناريو فشل الإذن**: إذا ضبط المستخدم خصوصيته على \"جهات الاتصال فقط\" ولم يكن مثيلك في سجل هاتفهم، فقد تظهر عملية الإضافة \"ناجحة\" تقنياً ولكن المستخدم **لن يظهر** فعلياً في المجموعة.\n*   **النمط الاستراتيجي البديل**: نوصي بتنفيذ تسلسل **\"إضافة -> تحقق -> رابط\"**:\n    1. حاول إضافة المستخدم مباشرة.\n    2. تحقق من قائمة الأعضاء بعد ثوانٍ.\n    3. إذا لم يظهر المستخدم، أرسل له تلقائياً رسالة خاصة تحتوي على [رابط دعوة المجموعة](/v2/groups/invite-code).\n\n---\n\n## 🛡️ الأمن والامتثال\nأضف المستخدمين بناءً على علاقات قائمة؛ تجنب \"الإضافات الباردة\" التي قد تؤدي لتبليغ الحساب كـ \"سبام\". نوصي باتباع سياسة \"الإضافة التدريجية\" (بمعدل 5-10 مستخدمين في الدقيقة) للحفاظ على استقرار النظام وسلامة الحساب.\n            ",
          "tips": [
            {
              "title": "الخصوصية",
              "content": "يمكن للمستخدمين حظر إضافتهم إلى المجموعات من قبل الغرباء."
            },
            {
              "title": "الفشل",
              "content": "إذا فشلت الإضافة، قد تحتاج إلى إرسال رابط دعوة بدلاً من ذلك."
            }
          ],
          "recommendations": [
            "تحقق مما إذا كان المستخدم موجودًا على واتساب قبل محاولة الإضافة.",
            "لا تقم بإضافة المستخدمين الذين غادروا سابقًا بشكل عشوائي.",
            "تعامل مع النجاحات الجزئية (تمت إضافة بعض المستخدمين وفشل البعض الآخر)."
          ],
          "args": {
            "participants": {
              "description": "قائمة بمعرفات الواتساب (@c.us) المراد إضافتها"
            }
          }
        }
      }
    },
    {
      "path": "/v2/groups/{id}/participants/remove",
      "methods": [
        "POST"
      ],
      "title": "Remove participants",
      "category": "Groups",
      "description": "Remove one or more participants from the group.",
      "extraInfo": "\n# Pruning the State: The Strategic Governance of Participant Removal\n\nIn the lifecycle of a managed community, the ability to selectively withdraw access is as critical as the ability to grant it. The **Remove Participants** endpoint is your primary tool for **Structural Governance and Security Enforcement**. It allows you to programmatically prune the membership list of a group, ensuring that only actively relevant stakeholders maintain access to the shared conversational state. By moving participant removal from a manual agent task to an automated business rule, you ensure that \"Community Drift\" is minimized and that your business remains in absolute control of its collaborative boundaries.\n\nEffective membership management requires a perspective that balances **Security, Professionalism, and Operational Efficiency**. This guide explores the architectural imperatives of governed participant removal.\n\n---\n\n## 🏗️ Architectural Philosophy: The Enforcement of State Boundaries\n\nFrom a technical perspective, removing a participant is a **Revocation of Authorization**. You are severing the link between a specific JID and the persistent group context.\n\n### Key Architectural Objectives:\n*   **Irrevocable Withdrawal of Context**: Once a participant is removed, they instantly lose access to the group's \"Pulse.\" While they may retain a cached history of previous messages on their local device, they can no longer see new messages, view updated metadata, or see the current participant list. This \"Instant Blackout\" is essential for protecting sensitive business information when a project ends or a stakeholder's role changes.\n*   **The Power of Admin Rights**: Removal is an \"Executive Power.\" To successfully execute this call, your Wawp instance **must be a Group Admin**. This ensures that the dismantling of a community's population is a governed act performed by an authorized authority. If your instance is a regular member, the operation will fail with a 403 Forbidden error, preventing unauthorized users from \"Self-Moderating\" the group.\n*   **System-Generated Accountability**: Every removal triggers a system notification in the chat (e.g., *\"Business Name removed [User]\"*). This creates a transparent audit trail for the remaining members, signaling that the community is actively managed and that standards are being enforced.\n\n---\n\n## 🚀 Strategic Use Cases: Workflow Transitions and Rotation\n\nThe Remove Participants endpoint should be integrated into your broader business logic to handle transitions between different phases of a relationship.\n\n### 1. Shift Rotation & Handover Management\nIn global 24/7 support operations, groups often serve as the bridge between time zones. As a support specialist in Asia completes their shift, your system can automatically **Remove them from the group** while simultaneously adding their counterpart in Europe. This keeps the \"Headcount\" of the group low and ensures that the customer is only interacting with the team currently on duty, reducing confusion and preventing \"Off-hours\" messages from reaching sleeping agents.\n\n### 2. The \"Resolved Ticket\" Pruning Protocol\nFor technical troubleshooting groups, once a bug is confirmed as \"Resolved\" in your CRM, the system should automatically remove all secondary technical experts (senior engineers, developers) while leaving only the account manager and the customer. This \"Pruning\" focuses the conversation on the final closure steps and prevents technical staff from being distracted by the social \"Thank you\" messages that follow a successful fix.\n\n### 3. Subscription & Access Expiry\nIf your business manages \"Premium Community Groups\" for paid members, the Remove Participants endpoint is your **Subscription Enforcer**. When a user's subscription expires in your database, the system triggers the removal call. This turns the WhatsApp group into an \"Access-Controlled Asset\" that is perfectly synchronized with your billing engine.\n\n---\n\n## 🔐 Security & Compliance: Revoking Access in Regulated Environments\n\nIn industries like Finance, Healthcare, and Legal Services, controlling who has access to a shared conversation is a regulatory mandate.\n\n### The \"Need-to-Know\" Enforcement\nThe Remove Participants endpoint allows your system to enforce the principle of \"Least Privilege.\" If a staff member leaves your organization or is moved to a different department, your system can perform a **\"Global Access Wipe\"**—scanning all active WhatsApp groups and removing that individual's JID from every shared state. This ensures that no former employee retains a \"Backdoor\" into ongoing customer conversations via their personal WhatsApp device.\n\n### Preventing \"Community Creep\"\nAs a group matures, it is common for the membership list to grow stale. The Get Group Info endpoint should be used to periodically audit the population. If a user has not interacted with the group for 30 days and is not a core stakeholder, your system can proactively remove them to maintain a \"High-Quality, High-Engagement\" environment.\n\n---\n\n## 🛡️ Operational Hygiene and Professionalism\n\nRemoving a user is a socially sensitive act. Your system should handle it with the same level of care as a welcome sequence.\n\n*   **The \"Exit Notice\" Pattern**: Before executing a hard removal, we recommend sending a polite automated message to the group or a 1:1 message to the user explaining why they are being removed (e.g., *\"Our project is now complete, so we are closing out the active working group. Thank you for your collaboration!\"*). This prevents the \"Kicked out\" feeling and maintains your brand's professional reputation.\n*   **Rate Management**: Like adding participants, removing them in bulk should be staggered. Removing 100 users in a single second can trigger security flags. Aim for a \"Drip Removal\" of 5-10 users per minute to ensure system stability and account safety.\n\n---\n\n## ⚙️ Engineering Best Practices: Validation and Resilience\n\n1.  **Verify Member Status Before Removal**: To avoid unnecessary API calls, use the [Get Group Info](/v2/groups/{id}) endpoint to verify that the target JID is actually a member of the group. Attempting to remove someone who isn't there will return an error that could have been avoided with a simple pre-flight check.\n2.  **Handle Creator Immunity**: Remember that the **Creator** of a group cannot be removed by any other admin. If your system attempts to remove the creator (e.g., your primary instance), the operation will fail at the network level. Your logic should always respect this \"Immunity\" to prevent deadlocks in your automation.\n3.  **Event-Driven Synchronization**: Ensure your backend listens for the [`group.participants.update`](/v2/webhooks/group-participants-update) webhook. When a removal is confirmed by the WhatsApp network, your system should update its internal membership cache to ensure that your agent dashboard always displays the accurate population of the room.\n\n---\n\n## 🎯 Conclusion: Mastering the Art of the Governed Exit\n\nThe **Remove Participants** endpoint is the \"Shield\" of your community architecture. It allows you to maintain the integrity, security, and focus of your shared states. By treating membership pruning as a deliberate, strategic act rather than an afterthought, you build a conversational environment that is both efficient and professional. You ensure that every room your business owns is filled with exactly the right people, and that when their role is finished, they are transitioned out with precision and grace.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Admin Only",
          "content": "Only group admins can remove participants."
        },
        {
          "type": "warning",
          "title": "Notification",
          "content": "The removed user will see a system message that you removed them."
        }
      ],
      "recommendations": [
        "Log the reason for removal in your internal system.",
        "Send a warning message to the user before removing them if applicable.",
        "Remove the user from your local database mapping as well."
      ],
      "args": {
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the group",
          "example": "1234567890@g.us"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "participants": {
          "required": true,
          "type": "array",
          "description": "List of JIDs to remove",
          "example": "[{\"id\":\"1234567890@c.us\"}]"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Participants removed",
          "example": {
            "ok": true
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "إزالة مشاركين",
          "description": "إزالة مشارك واحد أو أكثر من المجموعة.",
          "extraInfo": "\n# تقليم الحالة: الحوكمة الاستراتيجية لإزالة المشاركين\n\nفي دورة حياة المجتمع المدار، تعد القدرة على سحب الوصول بشكل انتقائي لا تقل أهمية عن القدرة على منحه. تعد واجهة **إزالة المشاركين** أداتك الأساسية لـ **الحوكمة الهيكلية وفرض الأمن**. هي تتيح لك تقليم قائمة أعضاء المجموعة برمجياً، مما يضمن أن أصحاب المصلحة المعنيين فقط هم من يملكون حق الوصول للمحادثة.\n\n---\n\n## 🏗️ الفلسفة المعمارية: فرض حدود الحالة\n\nمن منظور تقني، إزالة مشارك هي **إلغاء للتفويض**. أنت تقطع الرابط بين JID محدد وسياق المجموعة المستمر.\n*   **سحب السياق غير القابل للإلغاء**: بمجرد إزالة المشارك، يفقد فوراً القدرة على رؤية الرسائل الجديدة أو البيانات الوصفية المحدثة. هذا \"الحجب الفوري\" ضروري لحماية معلومات العمل الحساسة عند انتهاء المشروع أو تغير دور صاحب المصلحة.\n*   **قوة حقوق المسؤول**: الإزالة هي \"سلطة تنفيذية\"؛ يجب أن يكون مثيل Wawp **مسؤولاً (Admin)** لتنفيذ هذا الطلب، مما يضمن أن تفكيك سكان المجتمع هو عمل قانوني من قبل سلطة مفوضة.\n*   **المساءلة الناتجة عن النظام**: تطلق كل عملية إزالة إشعار نظام في المحادثة (مثل *\"قام [اسم العمل] بإزالة [المستخدم]\"*)، مما يخلق مسار تدقيق شفاف للأعضاء المتبقين.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. إدارة تدوير الورديات والتسليم\nفي عمليات الدعم العالمية على مدار الساعة، يمكن لنظامك تلقائياً **إزالة الأخصائي** الذي انتهت ورديته في آسيا وإضافة نظيره في أوروبا، مما يحافظ على عدد أعضاء المجموعة منخفضاً ويمنع وصول رسائل \"خارج أوقات العمل\" للوكلاء النائمين.\n### 2. بروتوكول تقليم \"التذكرة المحلولة\"\nبمجرد تأكيد حل مشكلة تقنية في CRM، يمكن للنظام تلقائياً إزالة جميع الخبراء التقنيين الثانويين مع ترك مدير الحساب والعميل فقط، لتركيز المحادثة على خطوات الإغلاق النهائية.\n### 3. فرض انتهاء صلاحية الاشتراك\nإذا كنت تدير مجموعات للمشتركين فقط، فإن هذه الواجهة هي **أداة فرض الاشتراك**. عند انتهاء اشتراك المستخدم، يطلق النظام طلب الإزالة، مما يجعل مجموعة واتساب أصلًا مدارًا بدقة مع الفوترة.\n\n---\n\n## 🛡️ نظافة التشغيل والاحترافية\nنوصي بنمط **\"إشعار الخروج\"**؛ قبل تنفيذ إزالة قوية، أرسل رسالة مهذبة توضح السبب بمحافظة على سمعة علامتك المهنية. كما نوصي بـ \"تقليم تدريجي\" (5-10 مستخدمين في الدقيقة) لضمان استقرار النظام وسلامة الحساب.\n            ",
          "tips": [
            {
              "title": "للمسؤولين فقط",
              "content": "يمكن لمسؤولي المجموعة فقط إزالة المشاركين."
            },
            {
              "title": "إشعار",
              "content": "سيشاهد المستخدم الذي تمت إزالته رسالة نظام تفيد بأنك قمت بإزالته."
            }
          ],
          "recommendations": [
            "سجل سبب الإزالة في نظامك الداخلي.",
            "أرسل رسالة تحذير للمستخدم قبل إزالته إذا كان ذلك مناسبًا.",
            "قم بإزالة المستخدم من تعيين قاعدة بياناتك المحلية أيضًا."
          ],
          "args": {
            "participants": {
              "description": "قائمة بمعرفات الواتساب (@c.us) المراد إزالتها"
            }
          }
        }
      }
    },
    {
      "path": "/v2/groups/{id}/admin/promote",
      "methods": [
        "POST"
      ],
      "title": "Promote participants to admin users",
      "category": "Groups",
      "description": "Promote one or more participants to group admins.",
      "extraInfo": "\n# Delegating Authority: The Strategic Elevation of Community Leaders\n\nIn the complex orchestration of enterprise WhatsApp groups, the **Promote Participants** endpoint is the primary tool for **Distributed Governance**. It allows you to programmatically elevate regular members to the status of Group Administrators, granting them the local authority required to manage the community natively from their own devices. This endpoint is the key to building \"Hybrid Moderation\" models where your Wawp instance provides the high-level automation, while trusted human stakeholders handle the day-to-day interpersonal management of the chat.\n\nFor architects, \"Promotion\" is the act of **Delegating State Control**. This guide explores the strategic implications of admin elevation and how to manage the privilege matrix effectively at scale.\n\n---\n\n## 🏗️ Architectural Philosophy: The Elevation of State Permissions\n\nFrom a technical perspective, promoting a participant is a **Permission Mask Update**. You are transitioning a JID from a \"ReadOnly/Interact\" state to a \"Write-Metadata/Manage-State\" state.\n\n### The Admin Privilege Matrix\nWhen a user is promoted via this endpoint, they gain a suite of local capabilities in their WhatsApp app that are previously restricted. A promoted admin can:\n*   **Modify Global Metadata**: Change the group subject, description, and profile picture (depending on group settings).\n*   **Manage the Population**: Add new members directly or remove existing ones.\n*   **Influence Governance**: Promote other members to admin (though they cannot demote the original [Creator](/v2/groups-overview)).\n*   **Enforce Silence**: Toggle the \"Announcement Mode\" to lock or unlock the group for participant messages.\n\n### The Power of the Super-Admin (API Creator)\nIt is vital to remember that while the API can create many admins, the Wawp instance that initialized the group remains the **Super-Admin/Creator**. This hierarchy ensures that even if a promoted admin attempts to be disruptive, your system maintains the \"Master Override\" capability. Promotion is a delegation of *operational* power, not *absolute* ownership.\n\n---\n\n## 🚀 Strategic Use Case: Hybrid Moderation and Human-in-the-Loop\n\nThe most effective community strategies combine the speed of AI with the nuance of human judgment.\n\n### 1. Enabling Local Autonomy for Field Agents\nIn a large-scale real estate or project management deployment, your system might create hundreds of groups. By automatically **Promoting the assigned field agent** to admin status, you empower them to manage the group \"on the fly\" while they are on-site with a client. They can add a subcontractor or change the group subject to reflect a status update without needing to log into a specialized CRM dashboard. The API handles the creation and initial setup, while the promotion grants the human agent the \"Boots-on-the-Ground\" flexibility they need.\n\n### 2. The \"Community Champion\" Incentive\nFor customer-facing communities (e.g., a fan group or a product feedback cohort), promotion can be used as a reward for high engagement. Your system can track message volume and sentiment; once a user crosses a specific \"Trust Threshold,\" the system automatically promotes them to admin, turning them into a volunteer moderator. This \"Automated Meritocracy\" helps scale community management without increasing your business's headcount.\n\n### 3. Escalation-Based Authority Injection\nIn a standard support group, agents might function as regular members to keep the power centralized. However, if your system detects a \"Critical Escalation\" (via keyword analysis or a sentiment trigger), it can instantly **Promote a Senior Manager** to admin status. This provides the manager with the immediate \"Executive Tools\" needed to lock down the group or remove disruptive parties during a crisis.\n\n---\n\n## 🔐 Security & Trust: Managing the Risk of Decentralized Authority\n\nGranting admin rights is a high-trust event that carries inherent risks. A rogue admin can create significant disruption before your automation can react.\n\n### The \"Governance Audit\" Cycle\nTo mitigate the risk of \"Admin Bloat,\" your system should implement a periodic audit. Using the [Get Group Info](/v2/groups/{id}) endpoint, your system should scan the membership list and compare the current admins against your internal \"Authorized Admin Whitelist.\" Any user found with admin rights who isn't on the whitelist can be automatically [Demoted](/v2/groups/{id}/admin/demote) to restore the governance baseline.\n\n### Participant Visibility and Compliance\nAdmin status grants a user more visibility into group activity. In regulated industries, you must ensure that only verified employees are ever promoted. Your system should cross-reference the JID of any promotion target with your internal HR or Active Directory records to prevent accidental elevation of a customer or a third-party contractor to a position of authority over the group state.\n\n---\n\n## 🛡️ Operational Hygiene and Best Practices\n\n*   **Idempotency of Elevation**: Promoting a user who is already an admin is a safe, no-op operation. This allows your system to \"Re-Assert\" authority during a recovery sequence without fearing errors or duplicate state changes.\n*   **Throttling Bulk Promotions**: While the endpoint allows for multiple JIDs, we recommend promoting individuals one by one or in small batches. Large numbers of simultaneous admin changes can sometimes be flagged by Meta's security heuristics as \"Account Hijacking\" patterns.\n*   **System Notifications & Professionalism**: Every promotion triggers a system notification in the chat (*\"Business Name made [User] an admin\"*). This is a public signal of trust. Your system should often follow this up with a 1:1 message to the newly promoted admin, providing them with a \"Moderator Guide\" or a list of responsibilities.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Verify Admin Status of the Instance**: Your Wawp instance must be a Group Admin to promote others. Always perform a pre-flight check of your own permissions before attempting to change the permissions of others.\n2.  **Verify Membership**: You cannot promote someone who is not currently a member of the group. Attempting to do so will result in an API error. A robust workflow includes an `Add -> Verify -> Promote` sequence for new stakeholders.\n3.  **Webhook Integration**: Ensure your system listens for the [`group.participants.update`](/v2/webhooks/group-participants-update) webhook. When the WhatsApp network confirms the promotion, your system should update its internal \"Authority Map\" so that your UI correctly identifies which users are moderators.\n\n---\n\n## 🎯 Conclusion: Mastering the Art of Delegated Success\n\nThe **Promote Participants** endpoint is the tool that transforms a monolithic bot into a dynamic community ecosystem. By strategically delegating authority to trusted humans and secondary automated instances, you build a conversational architecture that is resilient, scalable, and responsive to the needs of its members. You empower your team to lead, while your system maintains the foundational governance that ensures the community's long-term health and alignment with your business goals.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Admin Powers",
          "content": "Admins can edit group info, add/remove users, and promote others."
        },
        {
          "type": "warning",
          "title": "Trust",
          "content": "Only promote trusted bots or humans. They can remove you (unless you are Creator)."
        }
      ],
      "recommendations": [
        "Limit the number of admins to simplify governance.",
        "Use a specific role tag in your CRM for promoted users.",
        "Audit admin lists periodically."
      ],
      "args": {
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the group",
          "example": "1234567890@g.us"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "participants": {
          "required": true,
          "type": "array",
          "description": "List of JIDs to promote",
          "example": "[{\"id\":\"1234567890@c.us\"}]"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Participants promoted",
          "example": {
            "ok": true
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "ترقية المشاركين إلى مسؤولين",
          "description": "ترقية مشارك واحد أو أكثر إلى مسؤولين في المجموعة.",
          "extraInfo": "\n# تفويض السلطة: الرفع الاستراتيجي لقادة المجتمع\n\nتعد واجهة **ترقية المشاركين** الأداة الأساسية لـ **الحوكمة الموزعة**. هي تتيح لك رفع الأعضاء العاديين إلى وضع \"مسؤولي المجموعة\"، مما يمنحهم السلطة المحلية اللازمة لإدارة المجتمع من أجهزتهم الخاصة. هذا هو المفتاح لبناء نماذج \"إشراف هجينة\" حيث يوفر Wawp الأتمتة، بينما يتعامل البشر الموثوق بهم مع الإدارة اليومية.\n\n---\n\n## 🏗️ الفلسفة المعمارية: رفع أذونات الحالة\n\nمن منظور تقني، ترقية مشارك هي **تحديث لقناع الأذونات**.\n*   **مصفوفة صلاحيات المسؤول**: يحصل المسؤول المرقى على قدرات محلية تشمل: تعديل البيانات الوصفية (الاسم والوصف)، إدارة السكان (إضافة/إزالة أعضاء)، وفرض الصمت عبر \"وضع الإعلانات\".\n*   **قوة المسؤول الخارق (منشئ API)**: يظل مثيل Wawp الذي أنشأ المجموعة هو **المنشئ/المسؤول الخارق**. تضمن هذه الهرمية أنه حتى لو حاول مسؤول مرقى إحداث خلل، فإن نظامك يحتفظ بالقدرة على \"التجاوز الرئيسي\". الترقية هي تفويض للقوة *التشغيلية*، وليست ملكية *مطلقة*.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. تمكين الاستقلالية للوكلاء الميدانيين\nفي مشاريع العقارات الكبيرة، يمكن لنظامك تلقائياً **ترقية الوكيل الميداني** ليتمكن من إدارة المجموعة أثناء وجوده مع العميل (إضافة مقاول أو تغيير اسم المشروع) دون الحاجة للرجوع للوحة التحكم.\n### 2. حقن السلطة بناءً على التصعيد\nفي مجموعات الدعم العادية، يعمل الوكلاء كأعضاء عاديين. لكن إذا اكتشف النظام \"تصعيداً حرجاً\" (عبر تحليل المشاعر)، يمكنه فوراً **ترقية مدير أول** لمنحه الأدوات اللازمة لإغلاق المجموعة أو إزالة الأطراف المسببة للمشاكل أثناء الأزمة.\n\n---\n\n## 🛡️ الأمن والثقة: إدارة مخاطر السلطة اللامركزية\nمنح حقوق المسؤول هو عمل يتطلب ثقة عالية. نوصي بتنفيذ \"دورة تدقيق الحوكمة\" دورياً باستخدام واجهة [جلب بيانات المجموعة](/v2/groups/{id}) لمسح قائمة المسؤولين ومقارنتها بقائمتك البيضاء الداخلية، و[تخفيض رتبة](/v2/groups/{id}/admin/demote) أي شخص وجد بصلاحيات غير مصرح بها لاستعادة خط الأساس للحوكمة.\n            ",
          "tips": [
            {
              "title": "صلاحيات المسؤول",
              "content": "يمكن للمسؤولين تعديل معلومات المجموعة وإضافة/إزالة المستخدمين وترقية الآخرين."
            },
            {
              "title": "الثقة",
              "content": "قم بترقية الروبوتات أو البشر الموثوق بهم فقط. يمكنهم إزالتك (ما لم تكن المنشئ)."
            }
          ],
          "recommendations": [
            "قلل عدد المسؤولين لتبسيط الحوكمة.",
            "استخدم علامة دور محددة في نظام إدارة علاقات العملاء (CRM) للمستخدمين الذين تمت ترقيتهم.",
            "قم بمراجعة قوائم المسؤولين بشكل دوري."
          ],
          "args": {
            "participants": {
              "description": "قائمة بمعرفات الواتساب (@c.us) المراد ترقيتها"
            }
          }
        }
      }
    },
    {
      "path": "/v2/groups/{id}/admin/demote",
      "methods": [
        "POST"
      ],
      "title": "Demotes participants to regular users",
      "category": "Groups",
      "description": "Demote one or more admins to regular participants.",
      "extraInfo": "\n# Restoring Governance: The Strategic Withdrawal of Administrative Authority\n\nIn the lifecycle of a managed community, authority is a fluid asset that must be actively governed. The **Demote Participants** endpoint is your primary tool for **Centralizing Control and Enforcing Procedural Discipline**. It allows you to programmatically revoke the administrative privileges of a user, returning them to the status of a regular member. This endpoint is the critical counterbalance to the [Promote API](/v2/groups/{id}/admin/promote), ensuring that your \"Hybrid Moderation\" model remains focused, secure, and aligned with your business's current operational requirements.\n\nFor enterprise architects, \"Demotion\" is the act of **Permission Reclamation**. This guide explores the strategic imperatives of administrative withdrawal and the enforcement of the hierarchy of trust.\n\n---\n\n## 🏗️ Architectural Philosophy: The Enforcement of Disciplined State\n\nFrom a technical perspective, demoting a participant is a **Restrictive State Transition**. You are narrowing the permission mask of a JID, removing their ability to influence the group's metadata and population.\n\n### Key Architectural Objectives:\n*   **The Power of the Master Admin**: Demotion is a \"Corrective Power.\" To successfully execute this call, your Wawp instance **must be a Group Admin**. This prevents regular members from attempting to \"Overthrow\" an admin. However, because your API instance is typically the [Creator](/v2/groups-overview) of the group, it possesses a unique \"Administrative Immunity\" that secondary admins can never challenge.\n*   **Instant Feature Lockdown**: When a user is demoted, their WhatsApp interface instantly updates. They lose the \"Edit Group Info\" option, the ability to add/remove members, and the ability to lock the group. This \"Instant Revocation\" is essential for mitigating the impact of a rogue moderator or a stakeholder whose role has changed.\n*   **Systemic Transparency**: Every demotion triggers a system notification in the chat (e.g., *\"Business Name removed [User] as an admin\"*). This is a public signal of your system's active governance, reinforcing that the community operates under a structured hierarchy.\n\n---\n\n## 🚀 Strategic Use Cases: Rotating Authority and Managing Compliance\n\nDemotion should be used as a routine component of your \"Governance Cycle\" rather than just a reactive measure.\n\n### 1. The \"Shift Handover\" Protocol\nIn a 24/7 global operations center, many staff members may be added to a VIP case group. To avoid having dozens of active admins (which increases the risk of accidental metadata changes), your system can implement a \"Just-in-Time\" authority model. As a shift ends, the system **Demotes the outgoing manager** while promoting the incoming one. This ensures that only the manager currently on duty has the \"Administrative Tools\" active on their device, minimizing operational clutter and risk.\n\n### 2. Moderation Probation and Meritocratic Governance\nIf your system utilizes volunteer moderators from your customer base, demotion serves as your primary tool for **Quality Enforcement**. If your sentiment analysis engine or a user report detects a moderator engaging in off-topic or disruptive behavior, the system can automatically demote them back to member status. This \"Automated Moderation Guardrail\" protects the group's health without requiring human oversight from your internal team.\n\n### 3. Transitioning from \"Active Project\" to \"Long-term Archival\"\nWhen a project moves from its \"Intensive Phase\" to a \"Maintenance Phase,\" the need for multiple active admins decreases. Your system can automatically demote all stakeholders—except for the primary account manager—to regular member status. This \"State Simplification\" signals to everyone in the group that the primary phase of collaboration has concluded and the channel is now in a monitored, low-activity state.\n\n---\n\n## 🔐 Security and Risk Management: The Rogue Admin Threat\n\nGranting admin status to a third party (like a client or a contractor) is a vulnerability. A rogue admin can maliciously clear the group's participants, change the name to something offensive, or lock out other admins.\n\n### The \"Auto-Correction\" Audit\nWe recommend running a \"Governance Audit\" every 60 minutes for high-value groups. Using the [Get Group Info](/v2/groups/{id}) endpoint, your system should verify the current admin list. If it finds a JID that has been promoted manually (bypassing your API logic) or a JID that should no longer have rights, it should immediately call the **Demote Participants** endpoint to restore the authorized state. This \"Anti-Tamper\" logic ensures your API remains the ultimate arbiter of the group's structure.\n\n### The Hierarchy of Demotion: Creator Immunity\nIn the WhatsApp ecosystem, the **Creator cannot be demoted**. This is a hard-coded security feature of the network. This means that if your Wawp instance created the group, it is physically impossible for any other admin (human or bot) to demote your instance. This \"Steel-Clad Anchor\" ensures that your business system always retains the master key to the conversation, regardless of how many temporary admins you appoint.\n\n---\n\n## 🛡️ Operational Hygiene and Professionalism\n\nDemoting a user is a socially sensitive event. Handled poorly, it can lead to frustration or a sense of being \"Punished.\"\n\n*   **The \"Rotation Notice\" Pattern**: Before executing a demotion for operational reasons (like a shift change), send a polite notice to the group or the individual (e.g., *\"Your moderator shift has concluded. Authority is being transitioned to [New User]. Thank you for your support!\"*).\n*   **Rate Throttling**: Avoid mass-demoting users in a single burst. Like all administrative actions, staggering the calls (5-10 demotions per minute) ensures system stability and reduces the risk of triggering Meta's security heuristics.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Check Admin Status Before Demoting**: Ensure the user you are trying to demote is actually an admin. Attempting to demote a regular member will result in an API error. Use [Get Group Info](/v2/groups/{id}) to perform this pre-flight verification.\n2.  **Verify Presence**: You cannot demote someone who is not a member of the group. If a user leaves the group, their admin status is automatically nullified by the network. Your system should listen for the [`group.participants.update`](/v2/webhooks/group-participants-update) webhook to keep your internal \"Authority Map\" current.\n3.  **Idempotent Recovery**: Demoting someone who is already a member is a safe, no-op operation. Use this to your advantage during system recovery or state reconciliation to ensure your groups are in the correct governance posture.\n\n---\n\n## 🎯 Conclusion: Mastering the Art of Disciplined Management\n\nThe **Demote Participants** endpoint is the \"Check and Balance\" of your conversational architecture. It allows you to reclaim authority, mitigate risk, and maintain a clear hierarchy within your communities. By treating the withdrawal of permissions as a routine, strategic operation, you build a community ecosystem that is both flexible and highly governed. You ensure that power is only held by those who currently need it, and that your business system always remains the definitive source of truth and control.\n    ",
      "tips": [
        {
          "type": "warning",
          "title": "Creator Immunity",
          "content": "You cannot demote the group creator."
        },
        {
          "type": "info",
          "title": "Effect",
          "content": "Demoted users become regular participants but remain in the group."
        }
      ],
      "recommendations": [
        "Demote admins who are no longer active to reduce security risks.",
        "Communicate with the user before demoting to avoid confusion.",
        "Verify admin status before calling this endpoint."
      ],
      "args": {
        "id": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the group",
          "example": "1234567890@g.us"
        },
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "participants": {
          "required": true,
          "type": "array",
          "description": "List of JIDs to demote",
          "example": "[{\"id\":\"1234567890@c.us\"}]"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Participants demoted",
          "example": {
            "ok": true
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "تنزيل رتبة المسؤولين إلى مشاركين عاديين",
          "description": "تنزيل رتبة واحد أو أكثر من المسؤولين إلى مشاركين عاديين.",
          "extraInfo": "\n# استعادة الحوكمة: السحب الاستراتيجي للسلطة الإدارية\n\nتعد واجهة **تنزيل رتبة المشاركين** الأداة الأساسية لـ **مركزة التحكم وفرض الانضباط الإجرائي**. هي تتيح لك سحب الامتيازات الإدارية من المستخدم، وإعادته لوضع العضو العادي. هذا هو التوازن الضروري لواجهة [الترقية](/v2/groups/{id}/admin/promote)، مما يضمن بقاء نموذج الإشراف الخاص بك آمناً ومتوافقاً مع متطلبات العمل.\n\n---\n\n## 🏗️ الفلسفة المعمارية: فرض الحالة المنضبطة\n\nمن منظور تقني، تنزيل الرتبة هو **انتقال حالة تقييدي**. أنت تضيق قناع الأذونات للمستخدم، وتزيل قدرته على التأثير في بيانات المجموعة وسكانها.\n*   **قوة المسؤول الرئيسي**: تنزيل الرتبة هو \"سلطة تصحيحية\"؛ يجب أن يكون مثيل Wawp **مسؤولاً (Admin)** لتنفيذ هذا الطلب. وبما أن مثيلك غالباً هو [المنشئ](/v2/groups-overview)، فإنه يمتلك \"حصانة إدارية\" فريدة لا يمكن للمسؤولين الثانويين تحديها.\n*   **إغلاق الميزات الفوري**: عند تنزيل الرتبة، يتم تحديث واجهة واتساب للمستخدم فوراً؛ فيفقد خيار \"تعديل معلومات المجموعة\"، والقدرة على إضافة/إزالة الأعضاء. هذا \"الإلغاء الفوري\" ضروري للتخفيف من أثر مسؤول مارق أو متجاوز.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. بروتوكول تسليم المناوبات\nفي ورديات العمل العالمية، قد يتم إضافة العديد من الموظفين لمجموعة حالة طارئة. لتجنب وجود عشرات المسؤولين النشطين (ما يزيد مخاطر التغييرات غير المقصودة)، يقوم النظام بـ **تنزيل رتبة المدير المغادر** فور انتهاء ورديته وترقية المسؤول القادم.\n### 2. نموذج \"التصحيح التلقائي\"\nنوصي بتشغيل \"تدقيق حوكمة\" كل 60 دقيقة للمجموعات عالية القيمة. إذا وجد النظام مستخدماً تمت ترقيته يدوياً (بتجاوز منطق API الخاص بك)، يجب عليه استدعاء واجهة **تنزيل الرتبة** فوراً لاستعادة الحالة المصرح بها. يضمن هذا أن يبقى الـ API هو الحكم النهائي والمسيطر.\n\n---\n\n## 🛡️ حصانة المنشئ\nفي منظومة واتساب، **لا يمكن تنزيل رتبة المنشئ (Creator)**. هذه ميزة أمنية صلبة في الشبكة. وهذا يعني أنه إذا أنشأ مثيل Wawp المجموعة، فمن المستحيل فيزيائياً على أي مسؤول آخر (بشري أو بوت) تنزيل رتبة مثيلك، مما يضمن احتفاظ عملك دائماً بالمفتاح الرئيسي للمحادثة.\n            ",
          "tips": [
            {
              "title": "حصانة المنشئ",
              "content": "لا يمكنك تخفيض رتبة منشئ المجموعة."
            },
            {
              "title": "التأثير",
              "content": "يصبح المستخدمون الذين تم تخفيض رتبتهم مشاركين عاديين ولكنهم يظلون في المجموعة."
            }
          ],
          "recommendations": [
            "قم بتخفيض رتبة المسؤولين غير النشطين لتقليل المخاطر الأمنية.",
            "تواصل مع المستخدم قبل تخفيض الرتبة لتجنب الارتباك.",
            "تحقق من حالة المسؤول قبل استدعاء نقطة النهاية هذه."
          ],
          "args": {
            "participants": {
              "description": "قائمة بمعرفات الواتساب (@c.us) المراد تنزيل رتبتها"
            }
          }
        }
      }
    },
    {
      "path": "/v2/media-overview",
      "methods": [
        "GET"
      ],
      "category": "Media",
      "isArticle": true,
      "title": "Media Overview",
      "description": "Learn how to handle media files (images, videos, audio, documents) in WhatsApp.",
      "extraInfo": "\n# The Visual Engine: Architecting Media-Rich Conversational Ecosystems\n\nIn the contemporary landscape of digital communication, text is the skeleton, but media—images, videos, documents, and voice notes—is the soul. On a platform as visually and auditorily driven as WhatsApp, the ability to manage media at scale is not just a feature; it is a fundamental pillar of business engagement. The **WhatsApp Media Ecosystem** within Wawp is a sophisticated orchestration layer designed to handle the complexities of binary data transit, formatting constraints, and global distribution. \n\nThis guide provides an architectural overview of how to build resilient media workflows, moving beyond simple uploads and downloads into the realm of **Content Intelligence and Lifecycle Orchestration**.\n\n---\n\n## 🏗️ Architectural Philosophy: The Ephemeral Binary Layer\n\nTo build effectively with media, developers must first understand the fundamental nature of binary storage within the Meta network. Unlike a database that holds text indefinitely, WhatsApp's media infrastructure is designed for **High-Velocity Transit**.\n\n### 1. The Transit State vs. The Permanent Archive\nWhen your system sends an image or a document, it is uploaded to Meta's regional edge caches. From there, it is pushed to the recipient's device. It is critical to recognize that **Metadata is Eternal, but Media is Temporal**. While a message's text might be archived on a device for years, the links to the raw binaries (the `mediaUrl`) frequently expire after a period of approximately 30 days. Architecture that relies on \"hot-linking\" to WhatsApp's internal URLs for long-term storage is doomed to failure. A professional implementation always chooses to \"Offload\" important media—receipts, legal contracts, or customer-shared evidence—to a private enterprise storage solution (like AWS S3 or Google Cloud Storage) immediately upon receipt.\n\n### 2. The Transcode Mandate\nWhatsApp's client-side applications (on iOS and Android) are highly optimized for specific codecs and resolutions. To ensure a seamless user experience, the network enforces strict format requirements. For example, a voice note must be in the OGG format with the Opus codec to appear with the native \"Play\" button in the chat UI. Wawp handles much of this complexity via the [Media Convert](/v2/media/convert) endpoint, acting as a **Real-Time Transcoding Gateway** that prepares your raw business assets for mobile consumption without requiring you to manage heavy-duty FFmpeg clusters yourself.\n\n---\n\n## 🚀 Strategic Use Cases: Beyond \"Sending Pictures\"\n\nMastering the Media API allows you to transform your WhatsApp channel from a simple chat box into a **Visual Command Center**.\n\n### 1. Document Automation and Digital \"Closings\"\nIn the legal, financial, and insurance industries, the \"Document\" is the primary unit of value. Using Wawp, your system can dynamically generate PDF contracts, insurance certificates, or bank statements and send them directly to the user's pocket. This \"Instant Delivery\" bypasses the friction of email (where messages are often lost in spam) and the delays of physical post. By tracking the [`message.ack`](/v2/webhooks/message-ack) status, you can even verify exactly when a user received their document, providing a high-fidelity audit trail for compliance.\n\n### 2. AI-Driven Visual Support and Moderation\nFor customer support teams, \"Evidence\" usually arrives in the form of a photo. A customer might send a picture of a broken product or a screenshot of a software error. A strategic architecture doesn't just wait for a human to look at the photo. Instead, it uses the **Download Media** capability to route the binary to a **Visual AI Engine**. This engine can automatically categorize the issue, detect inappropriate content, or even use OCR (Optical Character Recognition) to extract serial numbers from the image, pre-populating a support ticket before the agent even opens the chat.\n\n### 3. Voice as the \"Human\" Factor in Automation\nIn many cultures, \"Voice Notes\" are the preferred method of communication over typing. For an automated bot, this is a challenge. By programmatically downloading voice notes and routing them to a Speech-to-Text (STT) service, you can bridge the gap. Your system can \"listen\" to the customer's request, process it via a Large Language Model (LLM), and respond either with text or with a generated OGG/Opus voice file that mimics the brand's official tone. This creates a \"Voice-First\" automation experience that feels premium and accessible.\n\n---\n\n## 🏭 Industry-Specific Content Strategies\n\n### 1. Retail and E-Commerce: The Visual Showroom\nInstead of sending a text list of products, send a **WebP Sticker** or a high-quality video preview. Use the Media API to send \"Unboxing Videos\" or \"Styling Guides\" as soon as a customer expresses interest in a category. This visual stimulation is the primary driver of impulsive purchases and high-intent engagement.\n\n### 2. EdTech and Training: The Mobile Classroom\nDistribute educational modules as small, digestible video files or PDF worksheets. By using WhatsApp as the delivery vehicle, you ensure that students can learn \"On the Go,\" without needing to log into a bulky Learning Management System (LMS). The familiar interface of the media player reduce the friction of learning.\n\n### 3. Field Services and Maintenance: The Proof-of-Work Layer\nIn service industries (plumbing, cleaning, construction), trust is built on visibility. Your field agents can send \"Before and After\" photos through your official WhatsApp Business account. These images are automatically downloaded by your system and attached to the job record in your CRM, providing permanent proof of work and a visual history of the property's condition.\n\n---\n\n## 🛡️ Best Practices for High-Performance Media Architecture\n\n*   **URL-First Distribution**: When sending media to thousands of users, avoid the overhead of Base64 encoding. Instead, host the media on a global Content Delivery Network (CDN) and pass the URL to Wawp. This reduces the size of your API requests and leverages the CDN's edge locations for faster delivery to Meta's servers.\n*   **The \"Thumbnail Pre-flight\" Rule**: For larger videos or documents, the initial \"Loading\" state can be frustrating for users. While WhatsApp handles some thumbnailing automatically, providing a high-quality preview or a clear filename in the metadata helps the user identify the content's value before they commit to the download.\n*   **Integrity Verification (Checksums)**: For critical documents (like legal contracts), compare the file size and checksum of the file you *sent* with the one stored in your archive. This ensures that no corruption occurred during the transcode or transit layers.\n*   **Cleanliness and Pruning**: Implement a \"Sanitization Routine\" for your local media storage. If your system downloads every image sent by every customer, you will quickly run out of disk space. Implement an automated policy to delete media older than 60 days unless it has been explicitly marked for \"Permanent Archive.\"\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **MIME-Type Strictness**: Always explicitly define the MIME type in your media calls. While Wawp can attempt to \"guess\" based on the file extension, providing the exact type (e.g., `application/pdf` vs. `application/octet-stream`) ensures the highest compatibility across different versions of the WhatsApp mobile client.\n2.  **Handle Upload Timeouts**: Large media files (100MB+) can take several seconds to upload, especially during peak network usage. Ensure your API client has appropriate timeout settings and implements a retry strategy with exponential backoff for binary uploads.\n3.  **Cross-Platform Testing**: Not all mobile devices handle media equally. Low-end Android devices may struggle with high-bitrate 4K video. We recommend a \"Mobile-First Optimization\" strategy: stick to standard 720p H.264 video and JPEG images under 5MB for maximum reach and reliability.\n\n## 🎯 Conclusion: Mastering the Art of the Multimedia Conversation\n\nThe **Media Lifecycle** is the engine of modern conversational commerce. By moving beyond \"Simple Storage\" and into the world of **Dynamic Content Orchestration**, you build a platform that speaks the language of the modern user. You transform raw binaries into strategic assets that drive trust, verify identity, and catalyze sales. In the world of Wawp, media is not just an attachment; it is the primary vehicle for your brand's digital identity and the key to a truly \"Unforgettable\" customer experience.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "File Limits",
          "content": "Check file size limits for different media types before uploading."
        },
        {
          "type": "warning",
          "title": "Mime Types",
          "content": "Ensure the correct MIME type is specified for the media file."
        }
      ],
      "recommendations": [
        "Compress media files to save bandwidth and improve speed.",
        "Use compatible formats (e.g., MP4 for video, JPEG/PNG for images).",
        "Handle upload failures with retries."
      ],
      "args": {},
      "responses": [],
      "translations": {
        "ar": {
          "title": "نظرة عامة على الوسائط",
          "description": "تعرف على كيفية التعامل مع ملفات الوسائط (صور، فيديو، صوت، مستندات) في واتساب.",
          "tips": [
            {
              "title": "حدود معدل API",
              "content": "احترم حدود معدل API لتجنب الحظر المؤقت."
            },
            {
              "title": "العمليات غير المتزامنة",
              "content": "معظم العمليات غير متزامنة. استخدم Webhooks للتحديثات في الوقت الفعلي."
            }
          ],
          "recommendations": [
            "استخدم متغيرات البيئة لبيانات الاعتماد الحساسة مثل رموز الوصول.",
            "قم بتنفيذ معالجة قوية للأخطاء ومنطق إعادة المحاولة."
          ],
          "extraInfo": "\n# المحرك البصري: هندسة منظومات المحادثة الغنية بالوسائط\n\nفي المشهد المعاصر للاتصالات الرقمية، النص هو الهيكل العظمي، لكن الوسائط — الصور، مقاطع الفيديو، المستندات، والرسائل الصوتية — هي الروح. على منصة تعتمد على الجوانب البصرية والسمعية مثل واتساب، تعد القدرة على إدارة الوسائط على نطاق واسع ركيزة أساسية للتفاعل التجاري. تم تصميم **منظومة الوسائط** في Wawp لتكون طبقة تنسيق متطورة تتعامل مع تعقيدات نقل البيانات الثنائية، وقيود التنسيق، والتوزيع العالمي.\n\n---\n\n## 🏗️ الفلسفة المعمارية: طبقة البيانات الثنائية المؤقتة\n\nلفهم التعامل الفعال مع الوسائط، يجب إدراك طبيعتها داخل شبكة Meta؛ فهي مصممة لـ **النقل عالي السرعة** وليس التخزين طويل الأمد.\n*   **حالة النقل مقابل الأرشيف الدائم**: بينما تظل النصوص محفوظة لسنوات، فإن روابط الوسائط (`mediaUrl`) تنتهي صلاحيتها غالباً بعد 30 يوماً. لذلك، تختار الأنظمة الاحترافية \"تفريغ\" الوسائط الهامة (مثل الإيصالات أو العقود) إلى تخزين سحابي خاص (مثل AWS S3) فور استلامها.\n*   **تفويض التحويل (Transcode Mandate)**: تفرض تطبيقات واتساب متطلبات تنسيق صارمة (مثل تحويل الرسائل الصوتية لـ OGG/Opus). تعالج Wawp هذا التعقيد عبر واجهة [تحويل الوسائط](/v2/media/convert)، مما يضمن تجربة مستخدم سلسة دون الحاجة لتعقيدات الـ FFmpeg الخاصة بك.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. أتمتة المستندات و \"الإغلاق\" الرقمي\nيمكن لنظامك إنشاء عقود PDF أو شهادات تأمين وإرسالها مباشرة إلى جيب العميل، مما يتجاوز احتكاك البريد الإلكتروني. ومن خلال تتبع [`message.ack`]، يمكنك التحقق بدقة من وقت استلام المستخدم لمستنده، مما يوفر سجل تدقيق متكامل.\n\n### 2. الدعم البصري المدعوم بالذكاء الاصطناعي\nبدلاً من انتظار مراجعة بشرية للصور، يمكن توجيه الوسائط الواردة إلى محرك ذكاء اصطناعي بصري لتصنيف المشكلة، أو اكتشاف المحتوى غير اللائق، أو استخراج الأرقام التسلسلية عبر التعرف الضوئي على الحروف (OCR) قبل أن يبدأ الوكيل في الرد.\n\n### 3. الصوت كعامل \"بشري\" في الأتمتة\nيفضل الكثيرون \"الرسائل الصوتية\" على الكتابة. من خلال تحويل الرسائل الصوتية للعملاء برمجياً إلى نص (STT)، يمكن لنظامك فهم الطلب والرد إما بنص أو بملف صوتي تم إنشاؤه يحاكي نبرة العلامة التجارية الرسمية، مما يخلق تجربة أتمتة \"صوتية أولاً\" متميزة.\n\n---\n\n## 🛡️ أفضل الممارسات الهندسية والتشغيلية\n*   **التوزيع عبر الروابط (URL-First)**: عند إرسال الوسائط للآلاف، يفضل استضافتها على شبكة توصيل محتوى (CDN) وتمرير الرابط لـ Wawp لتقليل حجم الطلبات وتسريع الوصول لخوادم Meta.\n*   **قاعدة المعاينة**: توفير اسم ملف واضح أو صورة مصغرة يساعد المستخدم على تحديد قيمة المحتوى قبل الالتزام بالتحميل، مما يوفر استهلاك البيانات لديه.\n*   **التحقق من السلامة (Checksums)**: للمستندات الحرجة، قارن حجم الملف والبصمة الإلكترونية لما أرسلته مع ما تم تخزينه لضمان عدم حدوث أي خلل أثناء النقل أو التحويل.\n      "
        }
      }
    },
    {
      "path": "/v2/media/convert",
      "methods": [
        "POST"
      ],
      "title": "Convert Media",
      "category": "Media",
      "description": "Convert media files to WhatsApp-compatible formats (e.g., to OGG/Opus for voice notes).",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "file": {
          "required": true,
          "type": "object",
          "description": "File to convert (URL, filename, mimetype)",
          "example": "{\"url\":\"https://example.com/audio.mp3\",\"filename\":\"audio.mp3\",\"mimetype\":\"audio/mpeg\"}"
        },
        "outputFormat": {
          "required": true,
          "type": "string",
          "description": "Desired output format (ogg, mp4, etc.)",
          "example": "ogg"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Media converted successfully",
          "example": {
            "url": "https://wawp.net/media/converted.ogg",
            "filename": "converted.ogg",
            "mimetype": "audio/ogg; codecs=opus"
          }
        },
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "extraInfo": "\n# The Transcoding Gateway: Architecting Format Fidelity for Global Mobile Distribution\n\nIn the heterogeneous world of digital media, \"compatibility\" is a moving target. For an enterprise handling millions of multi-format binary assets, the challenge is not just sending a file, but ensuring that the file is **immediately consumable** on any recipient device, regardless of their operating system or hardware age. The **Media Convert** endpoint is Wawp's specialized **Transcoding Infrastructure**, designed to bridge the gap between your raw business assets and WhatsApp's strict mobile-first requirements. \n\nBy acting as a real-time standardization layer, this endpoint transforms raw audio, video, and image signals into the exact bitrates, codecs, and containers optimized for the Meta network. This guide explores the strategic imperatives of media standardization and the architectural benefits of centralized transcoding.\n\n---\n\n## 🏗️ Architectural Philosophy: The Mandate of Standardization\n\nTo understand the necessity of the Media Convert API, one must first recognize the \"Silent Rejection\" problem in mobile messaging. If a business sends a high-bitrate .AVI file or an unoptimized .WAV through a WhatsApp channel, the recipient may receive the file, but their device may fail to play it natively, or it may appear as a \"Generic Attachment\" rather than an interactive media object.\n\n### 1. Codec Optimization and the \"Play-Ready\" State\nThe Media Convert endpoint ensures that every asset is in a **Play-Ready State**. \n*   **Audio and the Opus Paradox**: Standard MP3 files, while universal on the web, are handled by WhatsApp as \"Audio Files.\" They appear with a generic icon and require the user to download them before playing. However, if that same audio is transcoded into the **OGG container with the Opus codec**, it is recognized by WhatsApp as a \"Voice Note.\" This creates the signature blue-microphone experience, allowing for one-tap listening and variable-speed playback. The Media Convert API makes this transformation programmatic and effortless.\n*   **Video and Bitrate Balancing**: Sending a 4K 60FPS video to a user on a low-end device or a limited data plan on the other side of the world often leads to a poor experience. The Transcoding Gateway applies \"Strategic Compression,\" maintaining visual fidelity while optimizing file size for the rapid transit and display constraints of the mobile ecosystem.\n\n### 2. Centralized vs. Distributed Transcoding\nWhile a developer could manage their own FFmpeg cluster to handle these conversions, doing so introduces significant operational overhead, latency, and technical debt. Wawp's Media Convert API provides a **Serverless Transcoding Layer**. Your application simply provides a URL to the source media, and the API handles the compute-intensive task of re-encoding, returning a new, optimized binary URL ready for delivery. This allows your team to focus on business logic rather than binary mathematics.\n\n---\n\n## 🚀 Strategic Use Cases: Empowering Automated Media Flows\n\nCentralized conversion is the \"Secret Sauce\" of premium automated customer experiences.\n\n### 1. The \"Human Bot\" (Voice Note Automation)\nImagine a customer service bot that handles account inquiries. Instead of a text-only interaction, the bot responds with a voice message: *\"Hello! Your refund has been processed. Is there anything else I can help with today?\"* To achieve this, your system generates raw audio from a Text-to-Speech (TTS) engine, uses the **Media Convert** endpoint to standardize it into OGG/Opus, and delivers it as a native voice note. This adds a layer of empathy and personality to your automation that text alone cannot achieve.\n\n### 2. Cross-Channel Content Synchronization\nYour marketing team may produce high-quality videos for Instagram or YouTube. These videos are often high-resolution and high-bitrate. Before distributing these at scale through a [WhatsApp Channel](/v2/channels) or a broadcast list, the **Media Convert** API can \"Sandwich\" them into a WhatsApp-compatible MP4 format. This ensures that every subscriber, from the latest iPhone user to a legacy Android user, sees the vision exactly as the creative team intended, with zero buffering or playback errors.\n\n### 3. Safety and Sanitization through Transcoding\nMalicious files are often disguised as media. By passing every user-uploaded image or document through a \"Rounding\" transcode process, you effectively \"Sanitize\" the file. The re-encoding process strips away non-essential metadata (EXIF data, potential macro-active code) and regenerates the binary from scratch. This creates a \"Logical Firewall,\" ensuring that the files living in your enterprise storage are clean, standardized, and safe for your internal team to open.\n\n---\n\n## 🛡️ Administrative Mandate: Protecting the User Experience (UX)\n\nConsistency is the cornerstone of brand trust. If your bot's media delivery is inconsistent—sometimes working, sometimes showing \"Format not supported\"—your users will lose confidence in the channel.\n\n### The \"Frictionless Consumption\" Guarantee\nBy religiously using the **Media Convert** endpoint for every outbound asset, you guarantee that your content is frictionless. You move the \"Heavy Lifting\" of compatibility from the user's phone (where battery life and data are precious) to the Wawp cloud. This respect for the user's resources is a subtle but powerful brand signal that separates enterprise-grade platforms from basic implementations.\n\n### Monitoring \"Transcoding Velocity\"\nThe Media Convert API should be integrated into your analytics dashboard. Track how long your average conversion takes. For time-sensitive alerts (like emergency updates or real-time news), use \"Pre-transcoding\"—prepare the WhatsApp-optimized version of an asset the moment it is uploaded to your CMS, so it is ready for instant delivery when the broadcast trigger is pulled.\n\n---\n\n## 🛡️ Operational Best Practices: Optimization and Resource Stewardship\n\n*   **The \"Format First\" Policy**: Always check the source file's metadata before sending. If the file is already in a compatible format, skip the conversion to save time and resources. Use the Media Convert API only for \"Legacy\" or \"High-Fidelity\" sources that require standardization.\n*   **Caching Converted Assets**: Media conversion is a deterministic operation. If you convert \"WelcomeVideo.mov\" into \"WelcomeVideo.mp4\" once, store that MP4 URL in your database. Do not re-convert the same asset for every user; reuse the cached version to minimize latency and costs.\n*   **Managing Aspect Ratios**: WhatsApp favors certain aspect ratios for different UI elements (e.g., 1:1 for profile pictures, 9:16 for status updates). Use the \"Orientation Aware\" logic in your transcoding recipes to ensure your content is never stretched or distorted.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Monitor Target MIME Types**: Ensure you are requesting the correct output format for the intended message type. If you are sending a document, stick to PDF. If you are sending a voice note, always use OGG/Opus. \n2.  **Handle Conversion Errors Gracefully**: If a source file is corrupted or in an unsupported container (like an ancient .FLV), the conversion may fail. Your application should be prepared to \"Fall back\" to a lower-level document attachment or notify an administrator that the asset requires manual intervention.\n3.  **Coordinate with Download Timings**: Since the Media Convert API requires a public URL to the source, ensure your source server (e.g., S3) has granted appropriate \"Read\" permissions to the Wawp service. Use short-lived presigned URLs for security during the conversion transit.\n\n---\n\n## 🎯 Conclusion: Mastery of the Global Media Signal\n\nThe **Media Convert** endpoint is the \"Translator\" of your visual and auditory strategy. It bridge the gap between your enterprise content library and the diverse, global reality of the WhatsApp mobile network. By treating transcoding as a strategic prerequisite for engagement, you ensure that your brand's voice is always clear, your vision is always crisp, and your documents are always accessible. You move beyond \"Hopeful Sending\" and into the world of **Engineered Compatibility**, where every media interaction is a guaranteed win for the user's experience.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "File Limits",
          "content": "Check file size limits for different media types before uploading."
        },
        {
          "type": "warning",
          "title": "Mime Types",
          "content": "Ensure the correct MIME type is specified for the media file."
        }
      ],
      "recommendations": [
        "Compress media files to save bandwidth and improve speed.",
        "Use compatible formats (e.g., MP4 for video, JPEG/PNG for images).",
        "Handle upload failures with retries."
      ],
      "translations": {
        "ar": {
          "title": "تحويل الوسائط",
          "description": "تحويل ملفات الوسائط إلى تنسيقات متوافقة مع واتساب (مثلاً إلى OGG/Opus للرسائل الصوتية).",
          "extraInfo": "\n# بوابة التحويل: هندسة جودة التنسيق للتوزيع العالمي عبر الهاتف\n\nفي عالم الوسائط الرقمية المتنوعة، تعد \"التوافقية\" هدفاً متحركاً. واجهة **تحويل الوسائط** هي البنية التحتية المتخصصة في Wawp لسد الفجوة بين ملفاتك الأصلية ومتطلبات واتساب الصارمة للأجهزة المحمولة. من خلال العمل كطبقة توحيد في الوقت الفعلي، تقوم هذه الواجهة بتحويل الإشارات الصوتية والمرئية الخام إلى التنسيقات والترميزات (Codecs) المثالية لشبكة Meta.\n\n---\n\n## 🏗️ الفلسفة المعمارية: إلزامية التوحيد القیاسي\n\nلفهم ضرورة هذه الواجهة، يجب أولاً إدراك مشكلة \"الرفض الصامت\" في المراسلة. إذا أرسلت شركة ملفاً غير محسن، فقد يستلمه العميل كـ \"مرفق عام\" بدلاً من كائن وسائط تفاعلي يمكن تشغيله مباشرة.\n\n### 1. لغز الأوبوس (Opus) والرسائل الصوتية\nتتم معالجة ملفات MP3 القياسية بواسطة واتساب كـ \"ملفات صوتية\" تتطلب التحميل قبل التشغيل وتظهر بأيقونة عامة. ولكن، إذا تم تحويلها إلى **تنسيق OGG بترميز Opus**، يتعرف عليها واتساب كـ \"رسالة صوتية\" (Voice Note)، مما يخلق تجربة الميكروفون الأزرق المميزة التي تتيح التشغيل الفوري والتحكم في السرعة.\n\n### 2. موازنة جودة الفيديو\nإرسال فيديو بدقة 4K لمستخدم على جهاز متواضع قد يؤدي لتجربة سيئة. توفر \"بوابة التحويل\" ضغطاً استراتيجياً يحافظ على الجودة البصرية مع تحسين حجم الملف لسرعة النقل على الأجهزة المحمولة.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي: تمكين تدفقات الوسائط المؤتمتة\n\n### 1. \"البوت البشري\" (أتمتة الرسائل الصوتية)\nيمكن لبوت الدعم الرد برسالة صوتية: *\"مرحباً! تم استلام طلبك. هل هناك شيء آخر؟\"*. لتحقيق ذلك، يتم توليد الصوت من محرك تحويل النص إلى كلام (TTS)، ثم استخدام واجهة **تحويل الوسائط** لجعله رسالة صوتية أصلية، مما يضيف لمسة إنسانية للأتمتة.\n\n### 2. التروية المحمية والتطهير (Sanitization)\nغالباً ما يتم إخفاء الملفات الضارة كملفات وسائط. من خلال تمرير كل صورة أو مستند يرفعه المستخدم عبر عملية تحويل، يتم \"تطهير\" الملف؛ حيث تعيد عملية إعادة الترميز بناء البيانات الثنائية من الصفر وتجردها من البيانات الوصفية غير الضرورية (مثل EXIF)، مما يخلق \"جدار حماية منطقي\" لبيانات شركتك.\n\n---\n\n## 🛡️ أفضل الممارسات الهندسية والتشغيلية\n*   **التخزين المؤقت للوسائط المحولة**: تحويل الوسائط عملية محددة النتائج. إذا قمت بتحويل ملف فيديو ترحيبي مرة واحدة، قم بتخزين رابط النسخة المحولة في قاعدة بياناتك وأعد استخدامه بدلاً من إعادة التحويل لكل مستخدم لتوفير الوقت والتكلفة.\n*   **إدارة أبعاد الصورة (Aspect Ratios)**: يفضل واتساب أبعاداً معينة (مثل 1:1 لصور الملف الشخصي، و 9:16 للحالات). استخدم منطق التحويل لضمان عدم ظهور محتواك بشكل مشوه أو ممتد.\n*   **سياسة التنسيق أولاً**: تحقق دائماً من البيانات الوصفية للملف المصدر. إذا كان الملف متوافقاً بالفعل، تخطَّ عملية التحويل لتوفير الموارد.\n            ",
          "tips": [
            {
              "title": "حدود الملفات",
              "content": "تحقق من حدود حجم الملف لأنواع الوسائط المختلفة قبل التحميل."
            },
            {
              "title": "أنواع MIME",
              "content": "تأكد من تحديد نوع MIME الصحيح لملف الوسائط."
            }
          ],
          "recommendations": [
            "قم بضغط ملفات الوسائط لتوفير النطاق الترددي وتحسين السرعة.",
            "استخدم تنسيقات متوافقة (مثل MP4 للفيديو، JPEG/PNG للصور).",
            "تعامل مع فشل التحميل مع إعادة المحاولة."
          ]
        }
      }
    },
    {
      "path": "/v2/calls-overview",
      "methods": [
        "GET"
      ],
      "category": "Calls",
      "isArticle": true,
      "title": "Calls Overview",
      "description": "Learn how to manage WhatsApp voice and video calls using Wawp.",
      "extraInfo": "\n# The Voice Layer: Strategic Orchestration of Real-Time WhatsApp Communication\n\nIn the hierarchy of digital interactions, voice remains the ultimate bridge of trust. While text-based messaging provides efficiency and scale, the ability to engage in a real-time voice or video conversation is often the final step in closing a high-value sale, resolving a complex technical issue, or providing emotional support in critical scenarios. The **WhatsApp Calls Ecosystem** within Wawp is designed to give enterprise architects the tools to manage these high-fidelity interactions programmatically, transforming a standard peer-to-peer calling feature into a structured, governed, and data-aware business channel.\n\nThis guide provides an architectural deep-dive into the strategic value of WhatsApp Calls, outlining how to build resilient, automated call-management workflows that protect your agents' focus while ensuring your customers receive a premium, personalized experience.\n\n---\n\n## 🏗️ Architectural Philosophy: The Call as a High-Priority Event\n\nTo master the Calls API, one must first understand its place within the Meta messaging infrastructure. Unlike a text message, which is asynchronous and can be queued or processed at leisure, a **WhatsApp Call** is a synchronous, high-priority \"Interrupt\" signal. It demands immediate action and occupies the device's audio/video hardware entirely.\n\n### The Signal vs. The Stream\nIt is critical to distinguish between the **Signaling Layer** and the **Media Stream**. \n*   **The Signaling Layer**: This is what the Wawp API manages. It includes events like [`call.received`](/v2/webhooks/call-received), [`call.accepted`](/v2/webhooks/call-accepted), and [`call.rejected`](/v2/webhooks/call-rejected). These signals tell your system that a connection is being attempted, providing the caller's identity (JID), the type of call (Voice vs. Video), and a unique Call ID.\n*   **The Media Stream**: This is the actual audio/video data. In standard WhatsApp operation, this stream is end-to-end encrypted and flows between the two devices. For enterprise-grade recording or routing to a physical call center (PBX/SIP), your architecture must bridge this stream using specialized VoIP gateways or SIP-to-WhatsApp connectors.\n\nBy controlling the signaling layer via Wawp, your system acts as the **Intelligent Gatekeeper**, deciding which calls reach a human agent and which are redirected to automated workflows.\n\n---\n\n## 🎭 The Strategic Imperative: Managing the \"Microphone\" at Scale\n\nIn a professional environment, an unmanaged phone line is a liability. If any user can call your business at any time, your agents will be overwhelmed by spam, off-hours requests, and low-priority queries. The Calls API transforms this chaos into a **Governed Interaction Model**.\n\n### 1. Automated Rejection as a Service (ARS)\nThe most powerful tool in your arsenal is the [Reject Call](/v2/calls/reject) endpoint. Rejection is not a \"No\"; it is a \"Redirect.\" In a strategic implementation, your system uses the incoming call signal to trigger a lookup in your CRM. If the caller is an active customer but the call arrives outside of their specific \"SLA Support Hours\", the system instantly rejects the call and sends an automated follow-up message: *\"We noticed your call attempt. Our specialized engineers are available from 9 AM to 5 PM EST. To schedule a prioritized callback, please use the link below.\"* This maintains professionalism while enforcing operational boundaries.\n\n### 2. The VIP Bypass (Priority Routing)\nConversely, for high-value stakeholders (VIPs or Tier-1 accounts), your system can ensure their calls are never missed. When a call event is received, your backend verifies the caller's \"Priority Score.\" High-priority calls can trigger an immediate \"High-Alert\" notification to an agent's desktop or even initiate a [Presence Subscription](/v2/presence/subscribe) to track if the agent is currently online to take the call.\n\n### 3. Fraud and Spam Perimeter Defense\nBy programmatically monitoring call attempts, you can detect \"Calling Volatility\"—users who call repeatedly in a short period. Your system can automatically [Block](/v2/contacts/block) these identifiers or route them to a \"Restricted Queue,\" protecting your team from harassment and ensuring that legitimate customers can always get through.\n\n---\n\n## 🚀 The Restricted Command Layer: Why Outbound Calls are \"Link-Only\"\n\nA common question for developers is: *\"How do I initiate a call from my bot?\"* The answer is strategic: **You don't.** \n\nWhatsApp's official protocol does not allow for programmatically initiated outbound calls. This is a foundational security measure by Meta to prevent the platform from becoming a tool for automated \"Robocalls\" or spam telemarketing. \n\n### The \"Call-to-Action\" (CTA) Alternative\nTo build a \"Click-to-Call\" experience for your customers, your system should send a 1:1 message containing a specialized link or a clear instruction: *\"Our expert is ready to discuss your mortgage application. Click here to call us now.\"* When the user clicks that link on their mobile device, it opens their native WhatsApp dialer. At that moment, your Wawp instance receives the [`call.received`](/v2/webhooks/call-received) signal, and your automated logic takes over to route the call to the correct department. This ensures that every voice interaction is **Consensual and Intentional**.\n\n---\n\n## 🏭 Industry-Specific Call Workflows\n\n### 1. Healthcare and Telemedicine\nIn a recovery monitoring scenario, a patient might have a question about their medication. Instead of waiting for a nurse to reply to a text, the patient calls the business number. The system verifies the patient's ID, sees they are currently in a \"Post-Op\" window, and routes the call signal to the on-call medical assistant's SIP phone. If the medical assistant is busy, the call is rejected, and a text is sent with an emergency triage link.\n\n### 2. Real Estate and Property Management\nDuring an open-house event, hundreds of leads may call for directions. Your system can use the **Calls API** to identify these callers. If they aren't in your CRM yet, the system rejects the call (saving agent time) and sends a \"Lead Capture\" form via WhatsApp: *\"Thanks for calling about the Oak Street property! Please fill out this 30-second form to receive the gate access code and digital brochure.\"*\n\n### 3. Financial Services and Identity Verification\nFor high-value transfers, a bank can use a \"Call-Back Verification\" step. The system sends a notification saying: *\"To authorize this transfer, please call our verification line within the next 2 minutes.\"* When the call arrives, the system validates the caller's JID against the account owner's number, providing a dual-factor authentication layer that combines \"Something you have\" (your WhatsApp account) with \"Something you do\" (making a call).\n\n---\n\n## 🛡️ Best Practices for Enterprise Success\n\n*   **The \"Contextual Follow-up\" Rule**: Never reject a call silently. Every programmatic rejection should be immediately followed by a text message that provides the user with an alternative path to resolution. This preserves the relationship and prevents the user from feeling \"ignored\" by a bot.\n*   **Latency-Aware Processing**: Call signals are time-sensitive. Your webhook handler must process the event and decide to [Reject](/v2/calls/reject) or accept within 100-200 milliseconds to avoid a \"Ghost Ring\" experience for the user.\n*   **Analytics and the \"Silent Lead\"**: Track the JIDs of users who call but don't leave a message. These \"Missed Call\" events are often your warmest leads—people who were ready to engage in a high-fidelity conversation but were hesitant to type. A manual follow-up from a sales agent to these callers can significantly increase conversion rates.\n*   **SIP Integration and PBX Bridging**: For professional call centers, work with your infrastructure team to bridge the audio stream. While Wawp handles the \"Who and When,\" your SIP infrastructure handles the \"Speak and Listen.\" This hybrid approach provides the best of both worlds: automated management and human conversation.\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Monitor Webhook Health**: Ensure your webhook endpoint is resilient and scalable. If your system misses a `call.received` event, it cannot manage that interaction.\n2.  **Handle Rejection Error States**: If you attempt to reject a call that has already been terminated by the user, the API will return a 404 or 400 error. Your logic should handle this gracefully as a \"Self-Correcting\" event.\n3.  **Cross-Reference with DND States**: Integrate your agent's \"Do Not Disturb\" status from your internal CRM or Slack. If an agent is in a meeting, your system should automatically reject all their incoming WhatsApp calls and offer a scheduling link instead.\n\nBy mastering the Calls API, you aren't just managing phone rings; you are building a **Conversational Security and Routing Layer** that bridges the gap between digital automation and human empathy. You move beyond \"Simple Answering\" and into the world of **Structured Voice Orchestration**, where every call is an opportunity for a perfectly timed, professional engagement.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Webhook Events",
          "content": "Listen to call.* webhooks to handle incoming calls in real-time."
        },
        {
          "type": "warning",
          "title": "Outbound Calls",
          "content": "WhatsApp API does not support programmatic outbound calls. Use links instead."
        }
      ],
      "recommendations": [
        "Respond to incoming call events quickly to avoid timeouts.",
        "Use the \"Reject\" endpoint for unwanted calls with a polite message.",
        "Log call attempts for analytics and support."
      ],
      "args": {},
      "responses": [],
      "translations": {
        "ar": {
          "title": "نظرة عامة على المكالمات",
          "description": "تعرف على كيفية إدارة مكالمات واتساب الصوتية والمرئية باستخدام Wawp.",
          "tips": [
            {
              "title": "حدود معدل API",
              "content": "احترم حدود معدل API لتجنب الحظر المؤقت."
            },
            {
              "title": "العمليات غير المتزامنة",
              "content": "معظم العمليات غير متزامنة. استخدم Webhooks للتحديثات في الوقت الفعلي."
            }
          ],
          "recommendations": [
            "استخدم متغيرات البيئة لبيانات الاعتماد الحساسة مثل رموز الوصول.",
            "قم بتنفيذ معالجة قوية للأخطاء ومنطق إعادة المحاولة."
          ],
          "extraInfo": "\n# إدارة المكالمات: التنسيق الاستراتيجي للاتصالات الفورية\n\nفي هرم التفاعلات الرقمية، يظل الصوت هو الجسر النهائي للثقة. بينما توفر الرسائل النصية الكفاءة، فإن القدرة على المشاركة في مكالمة صوتية أو مرئية في الوقت الفعلي هي الخطوة الأخيرة في إغلاق صفقة عالية القيمة، أو حل مشكلة فنية معقدة، أو تقديم دعم عاطفي في السيناريوهات الحرجة. تم تصميم **منظومة مكالمات واتساب** في Wawp لمنح المهندسين والمؤسسات الأدوات اللازمة لإدارة هذه التفاعلات برمجياً، وتحويل ميزة الاتصال القياسية إلى قناة عمل منظمة ومحكومة.\n\n---\n\n## 🏗️ الفلسفة المعمارية: المكالمة كحدث عالي الأولوية\n\nلفهم واجهة المكالمات، يجب أولاً استيعاب مكانتها في بنية واتساب. على عكس الرسالة النصية، التي تعد \"غير متزامنة\" ويمكن معالجتها لاحقاً، فإن **مكالمة واتساب** هي إشارة \"مقاطعة\" فورية عالية الأولوية، تتطلب إجراءً فورياً وتستحوذ على موارد الجهاز بالكامل.\n\n### التمييز بين الإشارة وتدفق الوسائط\nمن الضروري التمييز بين **طبقة الإشارة (Signaling Layer)** و **تدفق الوسائط (Media Stream)**:\n*   **طبقة الإشارة**: هذا ما تديره واجهة Wawp. وتتضمن أحداثاً مثل [`call.received`](/v2/webhooks/call-received) (استلام مكالمة)، [`call.accepted`](/v2/webhooks/call-accepted) (قبول المكالمة)، و [`call.rejected`](/v2/webhooks/call-rejected) (رفض المكالمة). تخبر هذه الإشارات نظامك بهوية المتصل ونوع المكالمة.\n*   **تدفق الوسائط**: هذا هو بيانات الصوت/الفيديو الفعلية. في واتساب، يكون هذا التدفق مشفراً من الطرفين (End-to-End Encrypted) وينساب بين الجهازين مباشرة.\n\n---\n\n## 🎭 التوجه الاستراتيجي: إدارة \"الميكروفون\" على نطاق واسع\n\nفي البيئة الاحترافية، يمكن لخط الهاتف غير المدار أن يصبح عبئاً. تحول واجهة برمجة تطبيقات المكالمات هذه الفوضى إلى **نموذج تفاعل محكوم**.\n\n### 1. الرفض الآلي للخدمة (ARS)\nأقوى أداة هي نقطة نهاية [رفض المكالمة](/v2/calls/reject). الرفض هنا ليس مجرد \"لا\"، بل هو \"إعادة توجيه\". إذا وصل اتصال خارج ساعات الدعم، يمكن للنظام رفضه وإرسال رسالة آلية توضح ساعات العمل وتوفر رابطاً لجدولة مكالمة، مما يحافظ على الاحترافية مع فرض الحدود التشغيلية.\n\n### 2. تجاوز VIP (التوجيه ذو الأولوية)\nبالنسبة للعملاء ذوي القيمة العالية، يمكن للنظام التأكد من عدم تفويت مكالماتهم عن طريق التحقق من \"درجة الأولوية\" وتنبيه الوكيل المتاح فوراً، أو حتى تفعيل [اشتراك الحضور](/v2/presence/subscribe) لتتبع توفر الوكيل.\n\n---\n\n## 🚀 لماذا المكالمات الصادرة \"عبر الرابط فقط\"؟\n\nلا يسمح بروتوكول واتساب الرسمي ببدء مكالمات صادرة برمجياً (Outbound) لمنع استخدام المنصة في \"المكالمات الآلية\" المزعجة (Robocalls) أو التسويق غير المرغوب فيه.\n**البديل الاستراتيجي**: لبناء تجربة \"النقر للاتصال\"، يجب على نظامك إرسال رسالة 1:1 تحتوي على رابط متخصص أو تعليمات واضحة: *\"خبيرنا جاهز لمناقشة طلبك، انقر هنا للاتصال بنا الآن\"*. عندما ينقر المستخدم على الرابط، يفتح طالب واتساب لديه، وعندها يستقبل نظامك إشارة [`call.received`] وتتولى برمجياتك توجيه المكالمة.\n\n---\n\n## 🛡️ أفضل الممارسات والتحقق الهندسي\n\n*   **قاعدة المتابعة السياقية**: لا ترفض مكالمة بصمت مطلقاً. يجب أن يتبع كل رفض برجمي رسالة نصية توفر للمستخدم مساراً بديلاً للحل، مما يمنع شعوره بالتجاهل.\n*   **المعالجة السريعة**: إشارات المكالمات حساسة جداً للوقت. يجب أن يتخذ نظامك قرار الرفض أو القبول في غضون 100-200 مللي ثانية لتجنب تجربة \"الرنين الشبح\".\n*   **تحليل \"العملاء الصامتين\"**: تتبع معرفات المستخدمين الذين حاولوا الاتصال ولم يتركوا رسالة، فهؤلاء غالباً ما يكونون من أكثر العملاء اهتماماً ولكنهم ترددوا في الكتابة. المتابعة اليدوية معهم ترفع معدلات التحويل بشكل كبير.\n      "
        }
      }
    },
    {
      "path": "/v2/webhooks-overview",
      "methods": [
        "GET"
      ],
      "category": "Webhooks",
      "isArticle": true,
      "title": "Webhooks Overview",
      "description": "Stream WhatsApp events to your server in real-time.",
      "extraInfo": "\n# The Event Stream: Webhooks\n\nWebhooks are the **nervous system** of your WhatsApp integration. They allow Wawp to push real-time events (messages, reactions, status updates, etc.) to your server, eliminating the need for constant polling.\n\n![webhook.png](https://api.apidog.com/api/v1/projects/1017306/resources/362670/image-preview)\n\n---\n\n## 🏗️ What is a Webhook?\n\nA **webhook** is an HTTP POST request sent from Wawp to your server whenever an event occurs.\n*   **Push-Based**: You don't ask for updates; Wawp sends them automatically.\n*   **Real-Time**: Events arrive within milliseconds of occurring.\n*   **Selective**: You choose which event types to receive.\n\n### The Alternative (Polling)\nWithout webhooks, you would need to:\n```javascript\nsetInterval(async () => {\n  const messages = await api.getMessages();\n  // Process new messages\n}, 5000); // Poll every 5 seconds\n```\n\n**Problems**:\n*   Wastes API quota.\n*   Introduces latency (up to 5 seconds delay).\n*   Misses events if your server is down during the poll.\n\n**Webhooks Solve This**: Events are delivered instantly, and Wawp retries if your server is temporarily unavailable.\n\n---\n\n## 🚀 Setup Guide\n\n### Step 1: Create a Webhook Endpoint\nYour server must expose a publicly accessible URL that accepts POST requests.\n\n**Example (Node.js/Express)**:\n```javascript\napp.post('/webhook/whatsapp', (req, res) => {\n  const event = req.body;\n  console.log('Received event:', event.event);\n  \n  // Acknowledge receipt immediately\n  res.status(200).send('OK');\n  \n  // Process asynchronously\n  processEvent(event);\n});\n```\n\n**Critical**: Always respond with `200 OK` **immediately**. Process the event in the background. If you take too long to respond, Wawp will assume the delivery failed and retry.\n\n### Step 2: Configure in Wawp Dashboard\n1.  Log into [wawp.net/account/connect](https://wawp.net/account/connect).\n2.  Click **Webhook** on your instance card.\n3.  Add your endpoint URL (e.g., `https://yourdomain.com/webhook/whatsapp`).\n4.  Select which events to receive (e.g., `messages`, `reactions`, `status.update`).\n5.  Set a retry policy (e.g., retry every 5 seconds, up to 10 times).\n\n### Step 3: Test with a Tool\nUse **Hookdeck**, **Smee.io**, or **ngrok** to test locally:\n```bash\nngrok http 3000\n# Copy the HTTPS URL (e.g., https://abc123.ngrok.io) to Wawp dashboard\n```\n\n---\n\n## 📦 Event Structure\n\nAll webhook events follow this schema:\n```json\n{\n  \"id\": \"evt_1234567890\",\n  \"timestamp\": 1722170400000,\n  \"session\": \"your_instance_id\",\n  \"engine\": \"WEBJS\",\n  \"event\": \"message\",\n  \"payload\": {\n    \"id\": \"msg_abc123\",\n    \"from\": \"1234567890@c.us\",\n    \"body\": \"Hello!\",\n    \"type\": \"text\"\n  },\n  \"me\": {\n    \"id\": \"your_number@c.us\",\n    \"pushName\": \"Your Bot\"\n  },\n  \"metadata\": {\n    \"user.id\": \"123\",\n    \"user.email\": \"you@example.com\"\n  }\n}\n```\n\n*   **id**: Unique event ID (for deduplication).\n*   **timestamp**: Unix timestamp (milliseconds).\n*   **event**: Event type (e.g., `message`, `message.reaction`, `group.participants.update`).\n*   **payload**: Event-specific data.\n*   **me**: Information about your WhatsApp account.\n\n---\n\n## 🆔 WhatsApp ID (JID) Reference\n\nIn the Wawp ecosystem, every entity (contact, group, channel) is identified by a unique string called a **JID**. Understanding the different suffixes is critical for routing messages and events correctly.\n\n| Suffix | Identity Type | Description |\n| :--- | :--- | :--- |\n| **`@c.us`** | **Individual / Contact** | The standard personal or business WhatsApp account. Used for 1-on-1 chats. |\n| **`@g.us`** | **Group** | Identifies a multi-user group conversation. |\n| **`@newsletter`** | **Channel** | Represents a public Broadcast Channel or Newsletter. |\n| **`@lid`** | **Lookup ID** | A privacy-preserving identifier used by modern WhatsApp features to mask real phone numbers. |\n| **`@broadcast`** | **Broadcast List** | Identifiers for legacy one-to-many broadcast lists (Status/List). |\n\n**Strategic Advice**: When storing identities in your CRM, always store the **full JID** (e.g., `447441429009@c.us`). This ensures your database remains compatible with Wawp's internal routing table and prevents collision between a phone number and a group ID that might accidentally share a similar prefix.\n\n---\n\n## 🔐 Security\n\n### 1. Validate the Source\nWawp does not currently sign webhooks with HMAC. To secure your endpoint:\n*   **IP Whitelist**: Only accept requests from Wawp's server IPs.\n*   **Secret Token**: Add a query parameter to your webhook URL (e.g., `?secret=abc123`) and validate it.\n\n### 2. Idempotency\nWawp may send the same event multiple times (e.g., if your server was slow to respond).\n*   **Solution**: Store the `event.id` in a database. If you've seen it before, skip processing.\n\n```javascript\nconst processedEvents = new Set();\n\napp.post('/webhook', (req, res) => {\n  const event = req.body;\n  if (processedEvents.has(event.id)) {\n    return res.status(200).send('Already processed');\n  }\n  processedEvents.add(event.id);\n  // Process event...\n});\n```\n\n---\n\n## 🛠️ Common Event Types\n\n| Event | Description |\n|-------|-------------|\n| `message` | New message received (text, image, video, etc.) |\n| `message.reaction` | User reacted to a message (emoji) |\n| `message.revoked` | User deleted a message |\n| `message.ack` | Message delivery status changed (sent → delivered → read) |\n| `group.participants.update` | User joined/left a group |\n| `presence.update` | User's online status changed |\n| `call.received` | Incoming voice/video call |\n| `status.update` | User posted a WhatsApp Status (Story) |\n\n---\n\n## 🔄 Retry Logic\n\nIf your server returns a non-200 status code (or times out), Wawp will retry:\n*   **Default**: 5 retries, 5 seconds apart.\n*   **Exponential Backoff**: Optional. Retries at 5s, 10s, 20s, 40s, 80s.\n*   **Dead Letter Queue**: After max retries, the event is logged but not delivered.\n\n**Best Practice**: Log failed events to a database so you can manually replay them later.\n\n---\n\n## 🎯 Use Cases\n\n### 1. Auto-Reply Bot\n```javascript\nwebhook.on('message', async (event) => {\n  if (event.payload.body === 'hi') {\n    await api.sendText(event.payload.from, 'Hello! How can I help?');\n  }\n});\n```\n\n### 2. CRM Sync\n```javascript\nwebhook.on('message', async (event) => {\n  await crm.createTicket({\n    from: event.payload.from,\n    message: event.payload.body,\n    timestamp: event.timestamp\n  });\n});\n```\n\n### 3. Analytics Dashboard\n```javascript\nwebhook.on('message.ack', async (event) => {\n  if (event.payload.ack === 3) { // Read\n    await analytics.trackMessageRead(event.payload.id);\n  }\n});\n```\n\n---\n\n## ⚠️ Common Pitfalls\n\n1.  **Slow Processing**: If your endpoint takes >5 seconds to respond, Wawp will retry. Always respond immediately and process async.\n2.  **No HTTPS**: Webhook URLs **must** use HTTPS. HTTP is not supported.\n3.  **Localhost URLs**: `http://localhost:3000` won't work. Use ngrok or deploy to a public server.\n4.  **Ignoring Duplicates**: Always implement idempotency checks.\n\n---\n\n## 📊 Monitoring\n\nTrack webhook health:\n```javascript\nlet successCount = 0;\nlet errorCount = 0;\n\napp.post('/webhook', (req, res) => {\n  try {\n    processEvent(req.body);\n    successCount++;\n    res.status(200).send('OK');\n  } catch (err) {\n    errorCount++;\n    res.status(500).send('Error');\n  }\n});\n\nsetInterval(() => {\n  console.log(`Success: ${successCount}, Errors: ${errorCount}`);\n}, 60000); // Log every minute\n```\n\n---\n\n## 🎯 Best Practices\n\n1.  **Filter Events**: Only subscribe to events you need to reduce traffic.\n2.  **Queue Processing**: Use a message queue (Redis, RabbitMQ) to handle high-volume events.\n3.  **Logging**: Log all incoming events for debugging and compliance.\n4.  **Graceful Degradation**: If your server is down, Wawp will retry. Ensure you have a fallback plan.\n\n---\n\n# Strategic Deep-Dive: Architecting for Scale and Resilience\n\nThe following sections provide a high-level strategic overview of webhook orchestration for enterprise-grade WhatsApp integrations.\n\n## 🏗️ Architectural Philosophy: The Shift from Pull to Push\nIn the ecosystem of distributed messaging, time is the most valuable commodity. For a business to remain competitive, it must move beyond \"Passive Polling\" and embrace **Active Synchronicity**. Webhooks are the foundational nervous system of the Wawp platform, providing a real-time, push-based communication layer that informs your infrastructure of every critical event—message receipts, status changes, group modifications, and more—the moment they occur on the WhatsApp network.\n\n### 1. Webhooks as High-Fidelity Signal Streams\nA webhook is a **Reactive Event Trigger**. Instead of your system looking for data, the Wawp service pushes a structured HTTP POST payload to your endpoint the millisecond an event is processed. This transforms your application from a \"Batch Processor\" into a **Real-Time Orchestrator**. \n- **Zero Latency**: Events move at the speed of the network. This is critical for customer support and security.\n- **Resource Stewardship**: Your server only expends compute cycles when there is actual work to be done. This leads to higher horizontal scalability and lower operational costs.\n\n### 2. The Idempotent Perimeter\nIn a distributed network, \"At Least Once\" is the practical reality. Webhooks are designed with **Redundancy and Retries**. This means your system must be architected for **Idempotency**—the ability to receive the same event multiple times without triggering duplicate business logic. By deduplicating events at your entry point using the unique Event ID, you ensure that your CRM doesn't create five tickets for the same message.\n\n---\n\n## 🚀 Strategic Use Cases: Powering the Real-Time Enterprise\n\n### 1. The Autonomous Customer Advocate\nWhen a customer sends a message, a webhook triggers background lookups to identify the customer, check tiers, and route messages to specialized agents instantly. By subscribing to `message.ack` events, your system can even detect if an agent's reply was \"Read\", triggering automated follow-ups if needed.\n\n### 2. Perimeter Security and Governance Monitoring\nFor large communities, webhooks monitor `group.participants.update` events to detect unauthorized joins. The system can autonomously remove them and alert security, ensuring conversational perimeters remain secure without manual auditing.\n\n### 3. Event-Driven Marketing and Conversion Funnels\nIn a sales funnel, timing is everything. If a user reacts to a marketing message with an emoji, a `message.reaction` webhook can instantly trigger a personalized discount code, capitalizing on the micro-moment of engagement.\n\n---\n\n## 🛡️ Administrative Mandate: Designing for Resilience and Scale\n\n### 1. The \"Acknowledge First, Process Later\" Protocol\nThe most common failure is bottlenecking during event processing. \n**The Strategic Rule**: Your endpoint should be a \"Thin Ingestion Layer.\" It receives the POST request, puts it into a high-speed message queue (like Redis or RabbitMQ), and immediately returns an HTTP 200. The actual business logic happens asynchronously, ensuring responsiveness during traffic bursts.\n\n### 2. Source Verification and Tunnel Security\nVerify that every incoming request originated from Wawp. Combine secret query parameters with IP Whitelisting and payload validation to prevent \"Payload Injection\" attacks and ensure your CRM logic is never triggered by malicious actors.\n\n---\n\n## 🛡️ Operational Best Practices: Maintaining Ecosystem Health\n- **Selective Subscription**: Only subscribe to the event types your application actually requires to minimize bandwidth and processing overhead.\n- **The \"Dead Letter Queue\" (DLQ) Strategy**: For events that fail all retries, use a DLQ to allow for manual replay once service is restored.\n- **Latency Monitoring**: Track the \"Delivery Gap\"—the time between the event's timestamp and reaching your server—as an early warning sign of bottlenecks.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n1. **High-Availability Infrastructure**: Host your webhook endpoint on an auto-scaling platform. It should be online 99.99% of the time.\n2. **Schema Enforcement**: Treat every incoming webhook as untrusted input and use a strict schema validator.\n3. **Cross-Instance Coordination**: Use the `session` or `me` field in the payload to correctly silo data when managing multiple instances.\n\n## 🎯 Conclusion: Beyond \"Integration\"—The Reactive Advantage\nThe Webhooks Ecosystem is the bridge between a static application and a \"Living\" conversational platform. By architecting around reactive principles, you move from \"Asking for Data\" to **Automated Response**, flowing in harmony with the global pulse of the WhatsApp network.\n    ",
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "Async Processing",
          "content": "Always respond with a 200 OK to the webhook as quickly as possible. Process the data after acknowledging receipt."
        }
      ],
      "recommendations": [
        "Validate the incoming payload to ensure it comes from Wawp.",
        "Use a tool like Hookdeck or Smee.io for local development testing.",
        "Filter events in the dashboard to only receive what your application needs."
      ],
      "responses": [],
      "translations": {
        "ar": {
          "title": "نظرة عامة على الويب هوك (Webhooks)",
          "description": "بث أحداث واتساب إلى خادمك في الوقت الفعلي.",
          "tips": [
            {
              "title": "حدود معدل API",
              "content": "احترم حدود معدل API لتجنب الحظر المؤقت."
            },
            {
              "title": "العمليات غير المتزامنة",
              "content": "معظم العمليات غير متزامنة. استخدم Webhooks للتحديثات في الوقت الفعلي."
            }
          ],
          "recommendations": [
            "استخدم متغيرات البيئة لبيانات الاعتماد الحساسة مثل رموز الوصول.",
            "قم بتنفيذ معالجة قوية للأخطاء ومنطق إعادة المحاولة."
          ],
          "extraInfo": "\n# تدفق الأحداث: الويب هوك (Webhooks)\n\nالويب هوك هي **الجهاز العصبي** لعملية التكامل مع واتساب. فهي تسمح لـ Wawp بدفع الأحداث في الوقت الفعلي (الرسائل، التفاعلات، تحديثات الحالة، إلخ) إلى خادمك فور وقوعها، مما يلغي الحاجة إلى الاستعلام المستمر (Polling) ويوفر استهلاك الموارد.\n\n---\n\n## 🏗️ ما هو الويب هوك؟\n\n**الويب هوك** هو طلب HTTP POST يتم إرساله من Wawp إلى خادمك عند وقوع حدث ما على شبكة واتساب.\n*   **قائم على الدفع (Push-Based)**: المتصفح أو الخادم الخاص بك لا يسأل عن التحديثات؛ بل يرسلها نظامنا تلقائيًا.\n*   **وقت حقيقي (Real-Time)**: تصل الأحداث في غضون أجزاء مئوية من الثانية.\n*   **انتقائي**: يمكنك اختيار أنواع الأحداث التي ترغب في استلامها فقط لتقليل حركة مرور البيانات.\n\n---\n\n## 🚀 دليل الإعداد السريع\n\n### 1. إنشاء نقطة نهاية (Endpoint)\nيجب أن يكشف خادمك عن عنوان URL متاح للعامة يقبل طلبات POST. تأكد دائماً من الرد بـ `200 OK` **فوراً**، مع معالجة الحدث برمجياً في الخلفية لتجنب تكرار الإرسال بسبب التأخير.\n\n### 2. التكوين والاختبار\nيمكنك تكوين الرابط واختيار الأحداث من [لوحة التحكم](https://wawp.net/account/connect). للاختبار المحلي، نوصي باستخدام أدوات مثل **ngrok** أو **Hookdeck** لفتح نفق (Tunnel) إلى جهاز المطور الخاص بك.\n\n---\n\n## 📦 هيكل الحدث (JSON Schema)\n\nتتبع جميع الأحداث هذا الهيكل الموحد لسهولة المعالجة:\n```json\n{\n  \"id\": \"evt_1234567890\",\n  \"timestamp\": 1722170400000,\n  \"session\": \"your_instance_id\",\n  \"event\": \"message\",\n  \"payload\": { ... },\n  \"me\": { \"id\": \"your_number@c.us\", \"pushName\": \"Bot\" }\n}\n```\n\n---\n\n## 🆔 مرجع معرفات واتساب (JID)\n\nفي Wawp، يتم تحديد كل كيان (جهة اتصال، مجموعة، قناة) بواسطة سلسلة فريدة تسمى **JID**. فهم هذه اللواحق ضروري لتوجيه الرسائل والأحداث بشكل صحيح:\n\n| اللاحقة (Suffix) | نوع الهوية | الوصف |\n| :--- | :--- | :--- |\n| **`@c.us`** | **فرد / جهة اتصال** | حسابات الأفراد أو الأعمال القياسية. تستخدم للدردشات الفردية. |\n| **`@g.us`** | **مجموعة** | تحدد المحادثات الجماعية التي تضم عدة مستخدمين. |\n| **`@newsletter`** | **قناة** | تمثل القنوات العامة أو النشرات الإخبارية (Newsletters). |\n| **`@lid`** | **معرف البحث** | معرف يحمي الخصوصية، يستخدم في الميزات الحديثة لإخفاء أرقام الهاتف الحقيقية. |\n\n---\n\n## 🛡️ الأمن والموثوقية\n\n1.  **التحقق من المصدر**: نوصي بإضافة \"معرف سري\" (Secret Token) كباراميتر في رابط الويب هوك الخاص بك (مثل `?key=mysecret`) والتحقق منه في خادمك لضمان أن الطلب قادم من Wawp.\n2.  **إدارة التكرار (Idempotency)**: بما أن الشبكات الموزعة قد تعيد إرسال الحدث (عند تأخر الرد)، يجب على نظامك استخدام `event.id` للتأكد من عدم معالجة نفس الحدث مرتين في الـ CRM الخاص بك.\n3.  **المعالجة غير المتزامنة**: لا تجعل خادم الويب هوك ينتظر تنفيذ منطق العمل المعقد (مثل الاتصال بذكاء اصطناعي). ضع الحدث في \"طابور\" (Queue) وأرسل الرد لـ Wawp فوراً.\n\n---\n\n## 🎯 الخاتمة: الميزة التفاعلية\nمنظومة الويب هوك هي الجسر بين التطبيق الثاكن ومنصة المحادثة \"الحية\". من خلال الهندسة القائمة على رد الفعل (Reactive Design)، ستنتقل مؤسستك من مجرد \"طلب البيانات\" إلى **الاستجابة المؤتمتة**، متبعةً نبض شبكة واتساب العالمية بكل دقة واحترافية.\n      "
        }
      }
    },
    {
      "path": "/session.status",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Session Status Change",
      "description": "This event is triggered when the session status changes (e.g., from WORKING to STOPPED).",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "warning",
          "title": "Uptime Monitoring",
          "content": "Use this event to detect if your WhatsApp instance goes offline so you can alert your support team or trigger an automated restart."
        },
        {
          "type": "info",
          "title": "Status Mapping",
          "content": "The 'status' field returns values like WORKING, STOPPED, and SCAN_QR_CODE."
        }
      ],
      "recommendations": [
        "Store the 'WORKING' status in your database to prevent sending messages to an offline instance.",
        "Notify administrators immediately if a session moves to 'SCAN_QR_CODE' status.",
        "Use the 'session' field to identify which account changed status."
      ],
      "extraInfo": "\n# The Engine Heartbeat: Connectivity Governance and Instance Lifecycle\n\nIn the orchestration of high-scale enterprise messaging, connectivity is not a binary state—it is a dynamic lifecycle. The **Session Status Change** webhook is the definitive signal that informs your infrastructure of the health, availability, and authentication status of your underlying WhatsApp engine. It is the \"Heartbeat Monitor\" of your community and a non-negotiable component of any resilient communication strategy.\n\nThis guide provides a strategic overview of the session lifecycle, exploring how to use status events to build a proactive, self-healing architecture that maximizes uptime and minimizes human intervention.\n\n---\n\n## 🏗️ Architectural Philosophy: Status as a Prerequisite for Action\n\nTo build a reliable WhatsApp integration, your system must operate with \"Connectivity Awareness.\" Attempting to send a high-priority message to a disconnected instance is a waste of compute resources and a risk to business continuity. The [`session.status`] webhook transforms your system from a \"Hopeful Messenger\" into a **Strategic Governor**.\n\n### 1. The State Machine of the WhatsApp Engine\nThe Wawp platform manages a complex state machine for every instance. Each status value represents a specific operational phase:\n*   **WORKING (The Operational Goal)**: This is the only state where the engine can perform full read/write operations. A strategic architecture uses this status as a \"Green Light\" for its outbound message queues. When an instance moves away from this state, your system should automatically \"Pause\" its outbound traffic to prevent delivery failures and quota waste.\n*   **SCAN_QR_CODE (The Gateway to Identity)**: This is a high-priority event signaling that the instance is unauthenticated. By reacting to this webhook, your system can trigger an automated notification to an administrator's internal dashboard or even send a specialized email containing the QR code for instant re-linking.\n*   **DISCONNECTED (The Critical Alert)**: This state indicates that the mobile device has been manually unlinked or has lost its network handshake for a prolonged period. This is an \"Emergency Stop\" signal that requires immediate investigation to ensure customer messages aren't being lost.\n\n### 2. Event-Driven Health Monitoring\nRelying on \"Periodic Heartbeat Checks\" is an inefficient way to monitor connectivity. By using the **Session Status** webhook, you move to a \"Reactive Monitoring\" model. Your server is informed of a failure the moment it happens, allowing for a **Mean Time to Recovery (MTTR)** measured in milliseconds rather than minutes.\n\n---\n\n## 🚀 Strategic Use Cases: Powering Resilient Architectures\n\nMastering the session lifecycle allows you to build systems that are \"Self-Aware\" and robust.\n\n### 1. Proactive Downtime Mitigation and Failover\nIn an enterprise environment managing multiple WhatsApp Business instances, the **Session Status** webhook is the foundation of a \"Failover Strategy.\" If Instance A (Sales-UK) moves to a [`STOPPED`] or [`DISCONNECTED`] state, your central router can detect this event and automatically redirect incoming queries to Instance B (Sales-Global) or escalate the interaction to an email-based support ticket. This ensures that the customer never experiences a \"Dark Chat\" where their messages go unanswered.\n\n### 2. Automated Authentication Workflows\nFor SaaS providers who offer WhatsApp integration to their own customers, managing authentication at scale is a primary challenge. Use the [`SCAN_QR_CODE`] event to trigger a \"Success UI\" on your customer's dashboard. As soon as the webhook arrives, your frontend can automatically display the QR code, wait for the status to transition to [`STARTING`](/v2/webhooks/session-status-starting), and finally show a \"Connected\" checkmark when the status reaches [`WORKING`](/v2/webhooks/session-status-working). This creates a seamless, low-friction \"Onboarding Loop\" that doesn't require the customer to manually refresh their page.\n\n### 3. Engine Integrity and Resource Management\nThe [`STARTING`] and [`STOPPED`] statuses are critical for managing your infrastructure's compute costs. If you are running hundreds of instances, you can use these events to track \"Engine Cold-Starts.\" If an instance remains in a [`STARTING`] state for more than 60 seconds without reaching [`WORKING`], your system can flag this as a \"Stuck Initialization\" and programmatically [Restart](/v2/auth/restart) the instance, maintaining the health of your overall instance fleet without manual human intervention.\n\n---\n\n## 🛡️ Administrative Mandate: The Guardianship of Connectivity\n\nEffective session management is a method of \"Connectivity Insurance.\"\n\n### 1. The \"Working\" State Cache\nEvery message sending function in your application should perform a \"Pre-flight Status Check.\" By caching the most recent status received from the webhook, your system can immediately reject or queue outbound requests if the instance isn't [`WORKING`]. This prevents \"Failed\" message states in your database and allows you to provide immediate feedback to your users: *\"Our WhatsApp connection is temporarily resetting. Your message will be sent in approximately 30 seconds.\"*\n\n### 2. Integrity in Multi-Instance Environments\nWhen managing a fleet of instances, the `session` field in the webhook payload is your primary key. Ensure your monitoring dashboard groups status events by this session ID. A \"Status Heatmap\" can help you identify platform-wide issues (e.g., if multiple instances move to [`DISCONNECTED`] at once, it may indicate a larger network or Meta-side connectivity problem) vs. isolated instance issues (e.g., a specific device's battery died).\n\n---\n\n## 🛡️ Operational Best Practices: Optimizing Lifecycle Awareness\n\n*   **Filter for Change (Deduplication)**: Only trigger your heaviest business logic (like sending an SMS alert to an admin) when the status *changes*. Do not react to repeated heartbeats of the same status unless your specific architecture requires it.\n*   **The \"Human-in-the-Loop\" Escalation**: For [`SCAN_QR_CODE`] events, implement a \"Decaying Alert\" strategy. Send a notification to the manager. If the status hasn't moved to [`WORKING`] within 5 minutes, escalate the alert to the IT department. This balances responsiveness with the need to avoid over-alerting for minor network blips.\n*   **Logging for Post-Mortems**: Store every status transition in a dedicated log table. This allows you to perform \"Uptime Audits\" and identify patterns in connectivity issues (e.g., Instance C always disconnects at 2 AM on Sundays), which is essential for long-term operational optimization.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Coordinate with QR Generation**: When you receive a [`SCAN_QR_CODE`] webhook, do not assume the QR image is ready immediately. There is often a several-hundred-millisecond gap between the status change and the new QR being generated by the engine. We recommend a short \"Wait and Fetch\" strategy before serving the QR image to the user.\n2.  **Graceful Handling of \"Stopped\" States**: A [`STOPPED`] status often indicates a deliberate administrative action. Your system should respect this state and not attempt to \"Force-Restart\" instances that were intentionally shut down for maintenance or billing reasons.\n3.  **Validate Webhook Integrity**: As with all webhooks, ensure you are verifying the source of the status change notification. Malicious actors could attempt to \"Ghost\" your system into thinking an instance is offline, triggering unnecessary failover logic and disrupting your business operations.\n\n## 🎯 Conclusion: Beyond \"Connection\"—The Architecture of Availability\n\nThe **Session Status Change Webhook** is the \"Eye\" of your integration. By building an architecture that listens to the heartbeat of the WhatsApp engine, you move your business from a state of \"Uncertain Connectivity\" to **Guaranteed Availability**. You build systems that detect their own failures, guide users through authentication, and maintain the integrity of the communication channel through any challenge. In the world of Wawp, status is not just a label; it is the strategic signal that ensures your global conversation never skips a beat.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01aaaaaaaaaaaaaaaaaaaaaaaa",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "session.status",
            "payload": {
              "name": "default",
              "status": "STOPPED"
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123123@lid",
              "pushName": "Wawp Instance"
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "تغير حالة الجلسة",
          "description": "يتم تفعيل هذا الحدث عند تغير حالة الجلسة (مثلاً من WORKING إلى STOPPED).",
          "tips": [
            {
              "title": "أمان الجلسة",
              "content": "حافظ على سرية معرف الجلسة session_id ولا تشاركه علنًا أبدًا."
            },
            {
              "title": "حالة الجلسة",
              "content": "تحقق من حالة الجلسة بانتظام أو استخدم Webhooks للتحديثات."
            }
          ],
          "recommendations": [
            "أعد تشغيل الجلسة إذا ظلت في حالة 'STARTING' لأكثر من 60 ثانية.",
            "استخدم نقطة النهاية 'logout' لفصل الجلسة بشكل نظيف."
          ],
          "extraInfo": "\n# نبض المحرك: حوكمة الاتصال ودورة حياة المثيل\n\nفي إدارة مراسلات الشركات واسعة النطاق، لا يعد الاتصال حالة ثابتة، بل هو دورة حياة ديناميكية. ويب هوك **تغير حالة الجلسة** هو الإشارة النهائية التي تبلغ بنيتك التحتية بصحة وأصالة محرك واتساب الخاص بك. إنه \"جهاز مراقبة نبض القلب\" لمجتمعك، ومكون لا غنى عنه في أي استراتيجية اتصال مرنة.\n\n---\n\n## 🏗️ الفلسفة المعمارية: الحالة كشرط مسبق للفعل\n\nيجب أن يعمل نظامك بـ \"وعي بالاتصال\". إن محاولة إرسال رسالة عبر مثيل غير متصل هو إهدار للموارد ومخاطرة باستمرارية الأعمال.\n*   **عامل التشغيل (WORKING)**: هذه هي الحالة الوحيدة التي يمكن للمحرك فيها تنفيذ عمليات القراءة والكتابة الكاملة. تستخدم الأنظمة الاحترافية هذه الحالة كـ \"ضوء أخضر\" لإدارة طوابير الرسائل الصادرة.\n*   **بوابة الهوية (SCAN_QR_CODE)**: حدث عالي الأهمية يشير إلى أن المثيل غير مصدق. يمكن لنظامك الرد على هذا الويب هوك بإرسال إشعار فوري للمسؤول أو عرض رمز الاستجابة السريعة في لوحة التحكم لإعادة الربط فوراً.\n*   **الانقطاع الحرج (DISCONNECTED)**: يشير إلى فقدان الارتباط أو انقطاع الشبكة لفترة طويلة، مما يتطلب تدخلًا فوريًا لضمان عدم ضياع رسائل العملاء.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. تخفيف التوقف والتبديل التلقائي (Failover)\nفي بيئة تدير عدة مثيلات، إذا توقف المثيل (أ)، يمكن للموجه المركزي اكتشاف ذلك عبر الويب هوك وتحويل الاستفسارات الواردة إلى المثيل (ب) تلقائياً، مما يضمن ألا يواجه العميل أبداً \"دردشة مظلمة\" لا يتم الرد فيها على رسائله.\n\n### 2. تدفقات المصادقة المؤتمتة\nيمكنك استخدام حدث [`SCAN_QR_CODE`] لتحديث واجهة المستخدم لدى عميلك وعرض الرمز فوراً، ثم الانتقال لعلامة \"متصل\" بمجرد وصول حالة [`WORKING`]، مما يخلق تجربة انضمام سلسة لا تتطلب من العميل تحديث الصفحة يدوياً.\n\n---\n\n## 🛡️ أفضل الممارسات التشغيلية\n*   **ذاكرة حالة التشغيل**: يجب أن تقوم كل وظيفة إرسال في تطبيقك بـ \"فحص حالة مسبق\" من الذاكرة المؤقتة. إذا لم تكن الحالة `WORKING`، يمكن للنظام تأجيل الطلب وإبلاغ المستخدم: *\"اتصالنا المباشر في مرحلة إعادة الضبط، سيتم إرسال رسالتك قريباً\"*.\n*   **التنبيه المتدرج**: عند استلام [`SCAN_QR_CODE`]، أرسل إشعاراً للمدير. إذا لم تتغير الحالة خلال 10 دقائق، صعد التنبيه لقسم تكنولوجيا المعلومات.\n*   **سجلات التوافر**: قم بتخزين كل انتقال للحالة لتحليل أنماط الانقطاع وأداء التوافر (Uptime) لمثيلك على المدى الطويل.\n            "
        }
      }
    },
    {
      "path": "/message",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Incoming Message",
      "description": "This event is triggered when a new message is received by your WhatsApp instance.",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "fromMe Field",
          "content": "The 'fromMe' boolean is crucial. It tells you if the message was sent by YOU (the instance) or by the CONTACT. This prevents infinite bot loops."
        },
        {
          "type": "positive",
          "title": "Real-time CRM",
          "content": "Use this event to push WhatsApp messages directly into your support dashboard without the user needing to refresh."
        }
      ],
      "recommendations": [
        "Always check 'fromMe' before processing a message to avoid responding to your own bot's messages.",
        "Check 'hasMedia' before attempting to download or process the 'media' object.",
        "Use the 'source' field to identify if a message was sent via the API or manually via the phone."
      ],
      "extraInfo": "\n# The Atomic Unit of Conversation: Deep Analysis of the Message Webhook\n\nIn the architecture of any conversational application, the **Incoming Message** is the fundamental unit of value. It is the primary signal that initiates business workflows, triggers automated intelligence, and drives customer engagement. Within the Wawp platform, the [`message`] webhook is the most prolific and critical event, acting as the real-time bridge between a user's intent and your system's response. \n\nTo master this webhook is to master the conversation itself. This guide provides an architectural deep-dive into the strategic properties of the message payload and the best practices for building a scalable, context-aware ingestion layer.\n\n---\n\n## 🏗️ Architectural Philosophy: The Anatomy of Intent\n\nA WhatsApp message is far more than just a string of text. It is a rich data object containing identity, source, status, and media metadata. When your server receives a [`message`] webhook, it is being handed a **Moment of Opportunity**.\n\n### 1. The Strategy of Contextual Siloing (`fromMe` and `source`)\nOne of the most common pitfalls in building WhatsApp bots is the \"Infinite Feedback Loop\"—where a bot responds to its own message, triggering another message, and so on. Wawp provides two critical \"Guardrail\" properties to prevent this:\n*   **The `fromMe` Boolean**: This field is the foundation of your logic's \"Self-Awareness.\" It tells you instantly if the message was sent by your own WhatsApp instance (`true`) or by an external contact (`false`). An enterprise-grade integration always filters for `fromMe === false` as the very first step of its ingestion pipeline.\n*   **The `source` Field**: This property provides \"Operational Context.\" It identifies if a message was sent via the Wawp API (`api`) or manually by a human operator using the physical phone or WhatsApp Web (`phone`). This distinction is vital for hybrid support models where bots handle initial triage and humans handle complex escalations. If the source is `phone`, your bot logic can automatically \"Step Back\" and stop interfering with the human conversation.\n\n### 2. High-Fidelity Source Identification (JIDs)\nIn the Wawp ecosystem, every message source is identified by a unique **JID** (WhatsApp ID). The [`from`] property allows your system to instantly determine the context of the conversation:\n*   **Individual Chats (@c.us)**: Messages where [`from`] ends in `@c.us` are 1-on-1 private conversations. This is your primary channel for support and personal engagement.\n*   **Group Chats (@g.us)**: If the [`from`] ends in `@g.us`, the message arrived from a shared group. In this context, the [`author`] property is critical—it identifies the specific individual within the group who sent the message.\n*   **Channels and Newsletters (@newsletter)**: Messages from public broadcasts or channels will carry the `@newsletter` suffix. These are typically read-only or one-way communication streams.\n*   **Lookup IDs (@lid)**: Occasionally, you will see `@lid`. These are privacy-preserving identifiers used by Meta for business discovery or internal routing.\n\nBy correctly parsing these suffixes, your ingestion layer can route messages to different internal modules (e.g., \"Group Bot\" vs. \"Personal Assistant\") without needing to perform expensive database lookups for every event.\n\n---\n\n## 🚀 Strategic Use Cases: Powering Intelligent Workflows\n\nThe message webhook is the \"Sensor\" that feeds your business's central nervous system.\n\n### 1. AI-Augmented Triage and Sentiment Analysis\nAs soon as a message arrives, your system should not just \"Reply.\" It should \"Analyze.\" By routing the `body` of the message to a Large Language Model (LLM) or a sentiment analysis engine, you can determine the customer's emotional state and intent. \n*   **Strategic Routing**: If the sentiment is \"Highly Frustrated\" and the intent is \"Billing Issue,\" the system can skip the standard bot menu and immediately alert a senior billing specialist. \n*   **Data Enrichment**: Use the incoming message to update the \"Last Activity\" field in your CRM, ensuring your sales team always has a real-time view of lead engagement.\n\n### 2. The Visual Evidence Pipeline\nWhen `hasMedia` is `true`, the interaction moves from a text-based query to a \"Proof-based Interaction.\" In field services or insurance, a user sends a photo of a damaged item. The Wawp webhook provides a temporary S3 URL to this media. A strategic architecture immediately downloads this binary and tags it with the customer's JID and the Message ID. This \"Visual Proof\" is then attached to the internal dispatch ticket, providing the field technician with zero-latency visual context before they arrive on-site.\n\n### 3. Cross-Platform Mirroring and Archival\nIn regulated industries, every customer interaction must be archived for 7-10 years. The message webhook provides the raw data required to build a \"Shadow Archive.\" Your system can mirror every WhatsApp interaction into a private, searchable database or an official email archive. Because the webhook includes the `replyTo` metadata, you can perfectly reconstruct threaded conversations, providing a high-fidelity record for legal or compliance audits.\n\n---\n\n## 🛡️ Administrative Mandate: Scaling the Ingestion Layer\n\nWhen your business expands to handling tens of thousands of messages per hour, the efficiency of your webhook handler becomes an infrastructure concern.\n\n### 1. The Strategy of \"Thin Ingestion\"\nDo not perform heavy-duty work within the webhook request-response cycle. If your server receives a message and spends 3 seconds calling an AI API before responding to Wawp, your message queue will back up, and you'll experience \"Retries\" for messages you've already processed. \n**The Professional Pattern**: Your ingestion script should perform minimal validation, push the message object into a fast-access queue (like Redis or NATS), and return a 200 OK Status immediately. A fleet of \"Worker Processes\" then picks up messages from the queue to perform the actual business logic. This decouples \"Delivery\" from \"Processing,\" ensuring your system remains responsive during viral traffic events.\n\n### 2. Global Search and the \"Thread ID\"\nTo build a premium user experience, your system must understand \"Conversation State.\" Use the `id` and `replyTo.id` fields to build a local \"Conversation Graph.\" When a user replies to a specific message, your system can look up that Message ID in your database to understand exactly what the user is referring to. This \"Contextual Awareness\" allows your bot to provide specific, helpful answers rather than generic responses.\n\n---\n\n## 🛡️ Operational Best Practices: Maintaining Conversational Integrity\n\n*   **Idempotency is Key**: Always check the unique `id` of the incoming message against a \"Seen Recently\" cache. Network hiccups can cause the same webhook to be delivered twice. If your system isn't idempotent, you might charge a customer twice or send duplicate bot responses.\n*   **Handle Revocations**: Subscribe to the [Revoked Message](/v2/webhooks/message-revoked) event. If a customer deletes a message after sending it, your system should reflect this in your internal dashboard to ensure your agents aren't responding to \"Ghost\" text that no longer exists in the customer's UI.\n*   **MIME-Type Awareness**: Don't just check if a message `hasMedia`. Check the `media.mimetype`. Treating a 50MB PDF document as if it were a 10KB JPEG image will lead to processing errors and slow performance. Build specialized handlers for each media category (Image, Video, Audio, Document).\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Monitor \"Processing Lag\"**: Track the difference between the `timestamp` provided in the message payload (when the user sent it) and the time your system actually finished processing it. A gap of more than 1-2 seconds indicates that your worker fleet is undersized.\n2.  **Verify Authentication**: Ensure that every webhook request contains the expected security headers or query tokens that you configured in your dashboard. This prevents a \"Flood Attack\" where an external actor could attempt to drain your processing resources by sending fake message payloads.\n3.  **Cross-Instance Siloing**: If your backend manages 50 different WhatsApp instances, the `session` field is your primary filtering key. Ensure your database queries always include the `session` scope to prevent \"Data Leakage\" where a message for Instance A is accidentally processed by the logic for Instance B.\n\n## 🎯 Conclusion: Mastering the Art of the Real-Time Signal\n\nThe **Incoming Message Webhook** is the heartbeat of your WhatsApp integration. By treating it not just as a data packet, but as a \"Strategic Signal,\" you move your organization from passive reception to active conversational orchestration. You build a system that hears the customer's intent, understands their context, and responds with engineered precision. In the world of Wawp, every message is a bridge to a deeper relationship, and every webhook is the first step in a perfectly timed journey.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01aaaaaaaaaaaaaaaaaaaaaaaa",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "message",
            "payload": {
              "id": "false_11111111111@c.us_AAAAAAAAAAAAAAAAAAAA",
              "timestamp": 1666943582,
              "from": "11111111111@c.us",
              "fromMe": true,
              "source": "api",
              "to": "11111111111@c.us",
              "participant": null,
              "body": "Hello, world!",
              "hasMedia": true,
              "media": {
                "url": "https://api.wawp.net/api/files/example.oga",
                "mimetype": "audio/ogg",
                "filename": "example.oga",
                "s3": {
                  "Bucket": "my-bucket",
                  "Key": "default/example.oga"
                },
                "error": null
              },
              "ack": -1,
              "ackName": "PENDING",
              "author": "11111111111@c.us",
              "location": {
                "description": "London, UK",
                "latitude": "51.5074",
                "longitude": "0.1278"
              },
              "vCards": [
                "BEGIN:VCARD..."
              ],
              "_data": {},
              "replyTo": {
                "id": "AAAAAAAAAAAAAAAAAAAA",
                "participant": "11111111111@c.us",
                "body": "Hello!",
                "_data": {}
              }
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123123@lid",
              "pushName": "Wawp Instance"
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "رسالة واردة",
          "description": "يتم تفعيل هذا الحدث عند استلام رسالة جديدة بواسطة مثيل واتساب الخاص بك.",
          "tips": [
            {
              "title": "تنسيق المستلم",
              "content": "استخدم @c.us لجهات الاتصال و @g.us للمجموعات."
            },
            {
              "title": "التعامل مع الوسائط",
              "content": "تأكد من أن روابط الوسائط متاحة للعامة وهي روابط مباشرة."
            }
          ],
          "recommendations": [
            "أضف تأخيرات عشوائية بين الرسائل لمحاكاة السلوك البشري.",
            "تحقق من أرقام الهواتف قبل الإرسال لضمان التسليم."
          ],
          "extraInfo": "\n# الوحدة الذرية للمحادثة: تحليل عميق لويب هوك الرسائل\n\nفي هندسة أي تطبيق محادثة، تعد **الرسالة الواردة** هي الوحدة الأساسية للقيمة. فهي الإشارة الرئيسية التي تطلق سير عمل الأعمال، وتفعل الذكاء الاصطناعي، وتقود تفاعل العملاء. يعد ويب هوك [`message`] الحدث الأكثر أهمية وتكراراً في منصة Wawp، حيث يعمل كجسر في الوقت الفعلي بين نية المستخدم واستجابة نظامك.\n\n---\n\n## 🏗️ الفلسفة المعمارية: تشريح \"النية\"\n\nرسالة واتساب هي كائن بيانات غني يحتوي على الهوية، المصدر، الحالة، والبيانات الوصفية للوسائط.\n\n### 1. استراتيجية العزل السياقي (`fromMe` و `source`)\nلتجنب \"حلقة التغذية الراجعة اللانهائية\" (حيث يرد البوت على نفسه)، يوفر Wawp خاصيتين حاسمتين:\n*   **القيمة المنطقية `fromMe`**: تخبرك فوراً إذا كانت الرسالة مرسلة من مثيلك الخاص (`true`) أو من جهة اتصال خارجية (`false`). يجب أن تقوم التكاملات الاحترافية دائمًا بفلترة `fromMe === false` كخطوة أولى.\n*   **حقل المصدر `source`: يحدد ما إذا كانت الرسالة أُرسلت عبر واجهة Wawp (`api`) أو يدوياً بواسطة شخص يحمل الهاتف (`phone`). إذا كان المصدر `phone`، يمكن للبوت \"التنحي\" وترك المجال للمحادثة البشرية.\n\n### 2. تحديد هوية المصدر (JIDs)\nيسمح حقل [`from`] لنظامك بتحديد سياق المحادثة فوراً:\n*   **الدردشات الفردية (@c.us)**: محادثات خاصة بين شخصين.\n*   **الدردشات الجماعية (@g.us)**: محادثات جماعية، وهنا يصبح حقل [`author`] حاسماً لتحديد الفرد الذي أرسل الرسالة داخل المجموعة.\n*   **القنوات (@newsletter)**: رسائل من القنوات العامة أو النشرات الإخبارية.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. الفرز المعزز بالذكاء الاصطناعي\nبمجرد وصول الرسالة، يمكن لنظامك تحليل المحتوى (Sentiment Analysis). إذا تم رصد \"إحباط شديد\" من العميل، يمكن للنظام تخطي البوت وتنبيه وكيل بشري رفيع المستوى فوراً.\n\n### 2. مسار الأدلة البصرية\nعندما تكون قيمة `hasMedia` هي `true`، يتحول التفاعل إلى \"إثبات بصري\". يوفر ويب هوك Wawp رابطاً مؤقتاً للوسائط. يمكن لنظامك تحميلها وتنسيقها فوراً وتضمينها في تذكرة الدعم الفني، مما يوفر سياقاً بصرياً فورياً للوكيل البشري.\n\n---\n\n## 🛡️ أفضل الممارسات التشغيلية والهندسية\n\n*   **استراتيجية \"الاستيعاب الخفيف\" (Thin Ingestion)**: لا تقم بأعمال ثقيلة (مثل استدعاء ذكاء اصطناعي) داخل دورة الويب هوك. قم باستلام الرسالة، وضعها في طابور مهام سريع مثل (Redis)، وأرسل رد `200 OK` فوراً لـ Wawp. ثم دع \"العمال\" (Workers) يعالجون المنطق برمجياً بشكل منفصل.\n*   **إدارة التكرار (Idempotency)**: تحقق دائماً من المعرف الفريد `id` للرسالة الواردة مقابل ذاكرة مؤقتة للرسائل \"المستلمة مؤخراً\". قد تتسبب تقلبات الشبكة في توصيل نفس الويب هوك مرتين.\n*   **الوعي بأنواع الوسائط**: لا تكتفِ بالتحقق من وجود وسائط، بل تحقق من `media.mimetype`. فمعالجة مستند PDF بحجم 50 ميجابايت تختلف تماماً عن معالجة صورة JPEG بحجم 10 كيلوبايت.\n            "
        }
      }
    },
    {
      "path": "/message.reaction",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Message Reaction",
      "description": "Triggered when a user reacts to a message with an emoji.",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "Emoji Removal",
          "content": "An empty reaction string often indicates that a user has removed their previous reaction."
        }
      ],
      "recommendations": [
        "Use this for interactive polling or feedback logic in your bot.",
        "Track which specific message ID the reaction belongs to using the payload."
      ],
      "extraInfo": "\n# The Micro-Engagement Signal: Harnessing Message Reactions (Emojis)\n\nIn the evolution of digital discourse, the traditional text reply is no longer the sole unit of engagement. The **Message Reaction**—the ability to attach a single emoji to a message—has become a fundamental method of low-friction, high-nuance communication. Within the Wawp platform, the [`message.reaction`] webhook provides your infrastructure with real-time visibility into these micro-moments of sentiment. \n\nThis guide provides an architectural overview of how to treat reactions as strategic data points, moving beyond \"Simple Emoji Tracking\" into the realm of **Interactive Triage and Sentiment Analysis**.\n\n---\n\n## 🏗️ Architectural Philosophy: Reactions as Low-Friction Content\n\nTo master the Reaction API, one must first recognize the psychology of the interface. A reaction is a \"Zero-Typing\" response. It allows a user to acknowledge, validate, or escalate a conversation without the cognitive effort of composing a sentence.\n\n### 1. The Intent behind the Gesture\nA reaction is a **Contextual Modifier**. It changes the meaning of the message it is attached to. \n*   **The Acknowledgment (Checkmark/Thumbs Up)**: This confirms receipt and agreement. In a task-management or logistical context, this reaction is as binding as a \"Yes\" message.\n*   **The Emotional Nuance (Heart/Fire/Laugh)**: These provide raw sentiment data. They tell your system how the customer *feels* about your support advice or marketing offer, providing a layer of emotional intelligence that text-based NLP (Natural Language Processing) often struggles to capture.\n*   **The Removal Signal**: A reaction event with an empty string or a \"Revoked\" state indicates the user has changed their mind. This \"Correction\" is a critical data point for long-term sentiment tracking, showing where a brand interaction may have moved from positive to neutral.\n\n### 2. The Relationship Between Parent and Child\nA reaction is technically a \"Child Event\" of a parent message. Your architecture must maintain a strong **Referential Integrity** between the [`messageId`] in the reaction payload and the original message stored in your database. This allows you to reconstruct the \"Reaction Profile\" of a specific interaction, identifying which agents or message types are generating the most positive engagement.\n\n---\n\n## 🚀 Strategic Use Cases: Powering Reactive Intelligence\n\nReactions transform passive chat monitoring into an active engine of engagement.\n\n### 1. Interactive Polling and \"Choose Your Own Adventure\"\nInstead of asking users to type \"1\" or \"2\", your bot can present a menu of options and ask users to \"React with an emoji to vote.\" This reduces friction and increases completion rates for surveys or product selections. \n*   **Strategic Workflow**: A travel bot sends three hotel options. The user reacts to the second one with a \"Star\" emoji. The [`message.reaction`] webhook triggers the booking flow for that specific ID. This creates a \"Click-less\" UI that feels modern and intuitive.\n\n### 2. Real-Time Sentiment Triage for Support Teams\nIn a high-intensity support environment, time is of the essence. Your system can monitor the reaction stream in real-time. If a user reacts to a bot's message with a \"Frown\" or an \"Angry\" emoji, the system should treat this as a \"Negative Sentiment Trigger.\" \n**The Actionable Logic**: The system automatically escalates the chat to a human supervisor and tags the interaction as \"At Risk.\" Conversely, a \"Heart\" or \"Thumbs Up\" on a bot's resolution can automatically trigger a \"CSAT\" (Customer Satisfaction) score update in your CRM without the user ever filling out a form.\n\n### 3. \"Reaction-to-Reward\" Marketing Funnels\nConvert micro-engagement into tangible sales. When a user reacts to a broadcast marketing message (e.g., a \"New Collection\" announcement) with a \"Fire\" or \"Heart\" emoji, the [`message.reaction`] webhook can instantly trigger a personalized coupon code: *\"We love that you love the new collection! Here is a 10% discount code just for you.\"* This \"In-the-Moment\" rewards system capitalizes on positive sentiment before it fades.\n\n---\n\n## 🛡️ Administrative Mandate: Scaling the Perception Layer\n\nHandling reactions at scale requires a focus on \"Data Density\" and \"Signal Filtering.\"\n\n### 1. Filtering Noise from Insight\nNot every reaction requires a business action. Your system should implement a **\"Strategic Reaction Map.\"** Decide which emojis are \"Actionable\" (e.g., Thumbs Up = Confirm) and which are \"Informational\" (e.g., Laugh = Neutral Sentiment). This prevents your worker fleet from being overwhelmed by non-essential events while ensuring that every critical signal is processed with high priority.\n\n### 2. The Idempotency of the Gesture\nWhatsApp allows users to change their reaction multiple times. A user might move from a \"Thumbs Up\" to a \"Heart\" to \"Nothing.\" Your architecture should handle this by treating each reaction event as a **\"State Overwrite\"**. Maintain a \"Latest Reaction\" field in your database for each message ID to ensure your UI and reporting always reflect the user's final sentiment.\n\n---\n\n## 🛡️ Operational Best Practices: Optimizing the Interactive Loop\n\n*   **The \"Double Acknowledgement\" Rule**: For critical interactive polling (e.g., \"React to Confirm Appointment\"), your bot should send a follow-up text once the reaction is received: *\"Thanks for the thumbs up! Your appointment is confirmed for Tuesday at 3 PM.\"* This ensures the user that their gesture was \"Heard\" by the automated system.\n*   **Managing Reaction Latency**: For a smooth user experience, your bot's response to a reaction should arrive within 2 seconds. Ensure your reaction webhook handler is optimized for high-speed lookup of the parent `messageId` in your database.\n*   **Privacy and Group Dynamics**: In group chats, multiple users can react to the same message. The [`senderId`] field is vital here. Your system should track the \"Reaction Count\" per emoji per message, allowing you to build \"Consensus Monitoring\" for internal team polls or community engagement.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Monitor \"Reaction-to-Reply\" Ratios**: High numbers of reactions relative to text replies indicate a healthy, frictionless communication channel. If your users are reacting but not replying, it means your bot is providing clear, concise value that requires no further typing from them.\n2.  **Verify Parent Integrity**: Before processing a reaction, verify that the [`messageId`] belongs to an active, non-archived conversation. This prevents \"Orphaned Reactions\" from triggering legacy logic in your system.\n3.  **Coordinate with Revocations**: If the parent message is revoked by the sender, your system should logically decide if the reactions attached to it are still relevant for your historical sentiment analysis or if they should be purged from the dashboard.\n\n## 🎯 Conclusion: Mastering the Art of the Subtle Gesture\n\nThe **Message Reaction Webhook** is the \"Sentiment Sensor\" of your digital brand. By building an architecture that listens to these subtle, high-nuance signals, you move your business from \"Reading Text\" to **Understanding Emotion**. You build systems that respond to gestures, reward engagement, and triage frustration before it escalates. In the world of Wawp, a reaction is not just an emoji; it is the strategic signal that turns a static message into a living, responsive conversation.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01...",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "message.reaction",
            "payload": {
              "id": "false_11111111111@c.us_...",
              "reaction": "❤️",
              "senderId": "11111111111@c.us",
              "messageId": "false_11111111111@c.us_AAAAA"
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123@lid",
              "pushName": "Instance"
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "تفاعل مع الرسالة",
          "description": "يتم تفعيله عندما يتفاعل المستخدم مع رسالة باستخدام إيموجي.",
          "tips": [
            {
              "title": "تنسيق المستلم",
              "content": "استخدم @c.us لجهات الاتصال و @g.us للمجموعات."
            },
            {
              "title": "التعامل مع الوسائط",
              "content": "تأكد من أن روابط الوسائط متاحة للعامة وهي روابط مباشرة."
            }
          ],
          "recommendations": [
            "أضف تأخيرات عشوائية بين الرسائل لمحاكاة السلوك البشري.",
            "تحقق من أرقام الهواتف قبل الإرسال لضمان التسليم."
          ],
          "extraInfo": "\n# إشارة التفاعل المصغر: الاستفادة من ردود الفعل (الإيموجي)\n\nفي تطور الخطاب الرقمي، لم يعد الرد النصي التقليدي هو الوحدة الوحيدة للمشاركة. أصبح **التفاعل مع الرسالة** — القدرة على إرفاق إيموجي واحد برسالة — وسيلة أساسية للتواصل عالي الدقة ومنخفض الجهد. يوفر ويب هوك [`message.reaction`] لمنظومتك رؤية مباشرة لهذه اللحظات من المشاعر.\n\n---\n\n## 🏗️ الفلسفة المعمارية: التفاعل كمحتوى مرن\n\nالتفاعل هو رد فعل \"بدون كتابة\"، مما يقلل الجهد المعرفي للمستخدم في التعبير عن رأيه أو تأكيد استلامه للمعلومة.\n*   **تعديل السياق**: الإيموجي يغير معنى الرسالة المرفق بها. علامة (الصح ✅) تعني التأكيد والقبول، بينما (القلب ❤️) أو (النار 🔥) توفر بيانات حول مدى إعجاب العميل بالعرض التسويقي.\n*   **إشارة الإزالة**: حدث التفاعل بسلسلة نصية فارغة يشير إلى أن المستخدم سحب تفاعله السابق، وهو أمر هام لتتبع المشاعر بدقة.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. الاستطلاعات التفاعلية و \"اختر مغامرتك\"\nبدلاً من مطالبة المستخدمين بكتابة \"1\" أو \"2\"، يمكن للبوت عرض قائمة خيارات ومطالبة المستخدمين بـ \"التفاعل بإيموجي للتصويت\". يقلل هذا من الاحتكاك ويزيد من معدلات إكمال الاستطلاعات أو اختيار المنتجات.\n\n### 2. فرز المشاعر في الوقت الفعلي لفرق الدعم\nإذا تفاعل المستخدم مع رسالة البوت بإيموجي (غاضب 😡) أو (حزين ☹️)، يجب على النظام التعامل مع هذا كـ \"محفز مشاعر سلبية\" وتصعيد المحادثة فوراً إلى وكيل بشري، بينما يمكن للتفاعلات الإيجابية تحديث نقاط رضا العملاء (CSAT) في الـ CRM تلقائياً.\n\n---\n\n## 🛡️ أفضل الممارسات التشغيلية\n*   **خريطة التفاعلات الاستراتيجية**: قرر أي الإيموجيات تتطلب إجراءً (مثل 👍 = تأكيد موعد) وأيها للمعلومات فقط، وذلك لتقليل ضغط المعالجة غير الضروري.\n*   **قاعدة \"التأكيد المزدوج\"**: في حالة التصويت أو التأكيد بالتفاعل، يفضل أن يرسل البوت رسالة نصية قصيرة فورية: *\"شكراً على تأكيدك! تم تثبيت موعدك يوم الثلاثاء\"*. هذا يشعر المستخدم بأن لفتته البسيطة قد \"سُمعت\" وفُهمت من قبل النظام المؤتمت.\n*   **إدارة التأخير**: لضمان تجربة مستخدم سلسة، يجب أن تصل استجابة البوت للتفاعل في غضون ثانيتين كحد أقصى.\n            "
        }
      }
    },
    {
      "path": "/message.any",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Any Message",
      "description": "Catch-all event for any message activity in the session.",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "warning",
          "title": "High Volume",
          "content": "This event triggers for every single message. Ensure your server can handle the high traffic frequency."
        }
      ],
      "recommendations": [
        "Use this for logging or backup systems that need to track every single movement.",
        "Consider filtering specific events instead if you only need certain message types."
      ],
      "extraInfo": "\n# The Omniscient Listener: Mastering the \"Message Any\" Webhook\n\nIn the architecture of a mission-critical communication platform, data gaps are unacceptable. While specific webhooks like [`message.received`] or [`message.revoked`] provide targeted signals, the **Message Any** event is the global catch-all—the \"Omniscient Listener\" of the Wawp platform. It fires for every single message-related movement within a session, including incoming messages from customers, outgoing messages sent by the API, manual responses made on a physical phone, and even ephemeral system messages.\n\nThis guide provides an architectural deep-dive into the strategic value of global ingestion, moving beyond \"Simple Logging\" into the realm of **Total Auditability, Data Lake Hydration, and Operational Traceability**.\n\n---\n\n## 🏗️ Architectural Philosophy: The Stream of Consciousness\n\nTo master the Message Any API, one must first recognize the shift from \"Event Filtering\" to \"Event Aggregation.\" This webhook represents the raw, unfiltered pulse of the WhatsApp session.\n\n### 1. The Full-Spectrum View\nThe [`message.any`] event collapses the distinction between source and destination.\n*   **The Bidirectional Stream**: It captures both his (`@c.us`/Incoming) and yours (`fromMe: true`/Outgoing). This provides a singular sequence of events, which is essential for reconstructing the \"Conversational Timeline\" in a linear format.\n*   **The Identity Mosaic**: By capturing interactions from Individuals (`@c.us`), Groups (`@g.us`), and Newsletters (`@newsletter`), it creates a holistic view of the instance's total cognitive load and engagement volume.\n\n### 2. The Relationship with Specific Webhooks\nIt is important to understand that [`message.any`] is **Redundant by Design**. Every event it captures is likely also emitted by a more specialized webhook. Its value lies not in *what* it captures, but in its **Consolidated Nature**. A high-performance architecture often uses specialized webhooks for \"Business Logic\" (e.g., triggering a bot response) and [`message.any`] for \"Compliance and Archiving\" (e.g., long-term storage in a Data Lake).\n\n---\n\n## 🚀 Strategic Use Cases: Powering the Auditable Business\n\nThe \"Message Any\" webhook is the engine of technical accountability and historical truth.\n\n### 1. High-Fidelity Audit Trails for Compliance\nIn industries such as Finance, Insurance, and Healthcare, every interaction must be logged for legal review.\n**The Strategic Workflow**: Point your [`message.any`] stream directly at an immutable storage solution (like Amazon S3 or a specialized Audit DB). Because this webhook captures manual phone messages as well as API messages, it provides a \"Complete Truth\" that cannot be bypassed by an agent picking up a physical phone. This ensures your organization remains compliant with non-repudiation and transparency mandates.\n\n### 2. Data Lake Hydration for AI and Analytics\nTo train a custom LLM or to generate \"Sentiment Trends,\" you need the largest possible dataset.\n**The Data Pipeline**: Use [`message.any`] to hydrate your Data Lake. By analyzing the total stream, you can identify \"Peak Activity Hours,\" \"Common Conflict Keywords,\" and \"Customer Effort Scores\" across the entire session. This moves your organization from \"Reactive Support\" to **Proactive Operations**, where business decisions are based on the aggregate signal of every interaction.\n\n### 3. The \"State Reconstruction\" Pattern\nIf your primary database suffers a catastrophic failure, how do you rebuild the conversational state of 10,000 active chats?\n**The Recovery Strategy**: If you have a complete log of [`message.any`] events, you can \"Replay\" the logs to reconstruct the exact state of every chat, including the last message sent, the last reaction, and the last update. This provides a \"High-Availability Safety Net\" that protects your business from data loss in its primary ingestion layers.\n\n---\n\n## 🛡️ Administrative Mandate: Balancing Volume and Value\n\nScaling a \"Global Listener\" requires professional-grade infrastructure.\n\n### 1. Engineering for High-Throughput\nA single Wawp instance can generate thousands of events per hour. If you have 100 instances, the [`message.any`] stream becomes a \"Firehose.\"\n**The Technical Standard**: Do not attempt to process [`message.any`] synchronously within your web server. Instead, use a **Message Broker (like RabbitMQ or Kafka)**. Let your webhook handler do one thing: push the raw payload into the queue and return a `200 OK` instantly. Your \"Archiver Workers\" can then drain the queue at their own pace, ensuring your server never buckles under peak traffic.\n\n### 2. The \"Signal-to-Noise\" Decision\nNot every event in the \"Any\" stream is valuable for your CRM. \n**The Strategic Filter**: Implement a \"Classification Layer.\" Store everything in your raw logs for compliance, but only \"Promote\" specific events from the [`message.any`] stream to your active UI if they meet certain criteria. This prevents your agent dashboard from being cluttered with redundant system messages while still maintaining the integrity of the underlying audit trail.\n\n---\n\n## 🛡️ Operational Best Practices: Optimizing the Global View\n\n*   **De-duplication Logic**: Since [`message.any`] captures events also sent by other webhooks, ensure your database uses the Message ID as a unique constraint. This prevents \"Double Counting\" messages in your analytics.\n*   **The \"Shadow User\" Pattern**: Monitor the [`fromMe: true`] messages to track agent productivity. Since this captures manual phone replies, you can see if an agent is bypassing your official CRM to talk to customers directly. This is a vital tool for quality assurance and \"Shadow IT\" prevention.\n*   **Metadata Enrichment**: The [`message.any`] payload provides basic fields, but can be enriched by cross-referencing with your [Contacts Database](/v2/contacts/all). A premium architecture resolves the JIDs into \"Known Names\" before archiving the event, making the audit logs human-readable.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Idempotent Ingestion**: Always use the Message ID and the Event Type as a combined key. If you receive the same ID via `message.received` and `message.any`, your logic should treat the second arrival as a \"No-Op.\"\n2.  **Verify Payload Integrity**: Ensure you are using the [`engine`] field to handle any subtle differences in payload structure between different Wawp engines (e.g., WEBJS vs. MD).\n3.  **Scoped Resource Allocation**: Dedicate separate compute resources or database instances for your \"Global Ingestion\" pipeline. You don't want a sudden spike in message traffic to slow down your primary \"Reply Logic\" workers.\n\n## 🎯 Conclusion: The Single Source of Truth\n\nThe **Message Any Webhook** is the \"Black Box Recorder\" of your digital brand. By building an architecture that embraces the firehose of data, you move your organization from \"Partial Visibility\" to **Complete Insight**. You build systems that never forget, never miss a signal, and always maintain a high-fidelity record of every word, reaction, and movement. In the world of Wawp, \"Any\" is the signal that ensures your business is always built on the foundation of total, auditable truth.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01...",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "message.any",
            "payload": {
              "id": "true_11111111111@c.us_...",
              "body": "Catching everything!",
              "from": "11111111111@c.us",
              "to": "22222222222@c.us"
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123@lid",
              "pushName": "Instance"
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "أي نشاط للرسائل (Catch-all)",
          "description": "حدث شامل يلتقط أي نشاط يتعلق بالرسائل في الجلسة.",
          "tips": [
            {
              "title": "تنسيق المستلم",
              "content": "استخدم @c.us لجهات الاتصال و @g.us للمجموعات."
            },
            {
              "title": "التعامل مع الوسائط",
              "content": "تأكد من أن روابط الوسائط متاحة للعامة وهي روابط مباشرة."
            }
          ],
          "recommendations": [
            "أضف تأخيرات عشوائية بين الرسائل لمحاكاة السلوك البشري.",
            "تحقق من أرقام الهواتف قبل الإرسال لضمان التسليم."
          ],
          "extraInfo": "\n# المستمع الشامل: إتقان ويب هوك \"أي رسالة\" (Message Any)\n\nفي هندسة منصات الاتصال الحساسة، الفجوات في البيانات غير مقبولة. بينما توفر ويب هوكات محددة مثل استلام الرسائل أو حذفها إشارات مستهدفة، يعد حدث **أي رسالة (Message Any)** هو اللاقط العام — \"المستمع الشامل\" لمنصة Wawp. يتم تفعيله لكل حركة تتعلق بالرسائل، بما في ذلك الرسائل الواردة، الصادرة عبر واجهة البرمجيات، والردود اليدوية من الهاتف.\n\n---\n\n## 🏗️ الفلسفة المعمارية: تدفق الوعي\n\nMastering the Message Any API يعني الانتقال من \"فلترة الأحداث\" إلى \"تجميع الأحداث\". يمثل هذا الويب هوك النبض الخام وغير المصفى لجلسة واتساب.\n*   **بث ثنائي الاتجاه**: يلتقط الرسائل الصادرة (`fromMe: true`) والواردة، مما يتيح إعادة بناء \"خط زمن المحادثة\" بشكل خطي ودقيق.\n*   **القيمة التنظيمية**: بما أن هذا الويب هوك \"فائض عن الحاجة بطبعه\"، فإن قيمته تكمن في كونه **سجلاً موحداً**. غالباً ما تستخدم الأنظمة الاحترافية الويب هوكات المتخصصة لـ \"منطق العمل\" (مثل الرد الآلي) وتستخدم [`message.any`] لـ \"الامتثال والأرشفة\" (مثل تغذية مستودع البيانات).\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي: تمكين الأعمال القابلة للتدقيق\n\n### 1. سجلات تدقيق عالية الدقة للامتثال\nفي القطاعات المالية والقانونية، يجب تسجيل كل تفاعل للمراجعة القانونية. وبما أن هذا الويب هوك يلتقط حتى الرسائل اليدوية من الهاتف، فإنه يوفر \"حقيقة كاملة\" لا يمكن تجاوزها، مما يضمن بقاء مؤسستك ممتثلة لمعايير الشفافية والمساءلة.\n\n### 2. تغذية مستودعات البيانات للذكاء الاصطناعي والتحليلات\nمن خلال تحليل التدفق الكامل للبيانات عبر [`message.any`]، يمكنك تحديد \"ساعات الذروة\"، \"كلمات النزاع الشائعة\"، و \"درجات جهد العميل\" عبر كامل الجلسة. ينقل هذا مؤسستك من \"الدعم القائم على رد الفعل\" إلى **العمليات الاستباقية**، حيث تُبنى القرارات على الإشارة الإجمالية لكل تفاعل.\n\n---\n\n## 🛡️ أفضل الممارسات الهندسية\n*   **هندسة الإنتاجية العالية**: يمكن لمثيل واحد توليد آلاف الأحداث. لا تحاول معالجة [`message.any`] بشكل متزامن؛ بل استخدم وسيط رسائل (مثل Kafka أو RabbitMQ). اجعل معالج الويب هوك يدفع البيانات للحاوية ويرد بـ 200 OK فوراً، ثم دع \"عمال الأرشفة\" يعالجون البيانات بوتيرتهم الخاصة.\n*   **منطق عدم التكرار**: تأكد من أن قاعدة بياناتك تستخدم \"معرف الرسالة\" كقيد فريد لمنع \"الحساب المزدوج\" في التحليلات إذا وصل نفس الحدث عبر قناتين مختلفين.\n*   **مراقبة \"الوكلاء الظل\"**: راقب الرسائل الصادرة (`fromMe: true`) لتتبع إنتاجية الوكلاء البشريين والتأكد من عدم تجاوهم لنظام الـ CRM الرسمي عبر الهاتف الخاص.\n            "
        }
      }
    },
    {
      "path": "/message.ack",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Message Acknowledgement",
      "description": "Track message delivery and read status (sent, delivered, read).",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "ACK Values",
          "content": "1 = Sent, 2 = Delivered (Double check), 3 = Read (Blue ticks)."
        }
      ],
      "recommendations": [
        "Use this to update message status icons in your custom chat UI.",
        "Track performance by measuring the time between 'Sent' and 'Read' acknowledgements."
      ],
      "extraInfo": "\n# The Lifecycle of a Signal: Mastering Message Acknowledgements (ACK)\n\nIn the high-stakes world of enterprise communication, \"Sending\" is merely the beginning of a message's journey. Truth exists not in the submission of a payload, but in the verification of its receipt and consumption. The **Message Acknowledgement (ACK)** webhook is the definitive feedback loop of the Wawp platform, providing your infrastructure with real-time insight into the \"Transit State\" of every outbound interaction. \n\nThis guide provides an architectural deep-dive into the strategic value of delivery tracking, moving beyond simple state changes into the realm of **Operational Accountability and Sentiment Attribution**.\n\n---\n\n## 🏗️ Architectural Philosophy: The Message as a Continuous Variable\n\nTraditional communication channels, like email or SMS, are often \"Fire and Forget.\" Once the message leaves your server, its status becomes a black box. WhatsApp, via Wawp, transforms this into a **Monitored Transit Lifecycle**.\n\n### 1. The Hierarchy of Verification\nAn ACK event is not a static update; it is a progression through a hierarchy of trust:\n*   **ACK_SENT (Level 1)**: The validation that the message has successfully escaped your instance and reached Meta's global infrastructure. This is the first \"Safety Check,\" confirming that your instance is healthy and your API credentials are valid.\n*   **ACK_DELIVERED (Level 2)**: The \"Double Tick\" moment. This confirms that the recipient's device is online and has successfully downloaded the payload. In a logistical or emergency context, this is the most critical signal—it confirms the bridge has been built.\n*   **ACK_READ (Level 3)**: The \"Blue Tick\" phenomenon. This represents a human event—the recipient has actively opened the chat window. For sales and support teams, this is the \"Moment of Perception,\" the signal that the customer is now consciously engaged with your brand.\n\n### 2. Handling the Asynchronous Nature of ACKs\nAcknowledgements frequently arrive out of order or at significantly different intervals. For example, a message may move from `SENT` to `READ` instantly if the user has the chat open, or it may stay in a `SENT` state for hours if the user is on a plane. A professional architecture handles these events as **Deterministic Idempotent Updates**—your database should only update a message's status to a \"Higher\" level and never revert to a \"Lower\" one, regardless of network retry order.\n\n---\n\n## 🚀 Strategic Use Cases: Powering Data-Driven Operations\n\nMastering the ACK stream allows you to measure and optimize the \"Pulse\" of your business communication.\n\n### 1. SLA Monitoring and \"Last-Mile\" Accountability\nFor customer support organizations, the \"Initial Response Time\" (IRT) is a key metric. By using the **Message ACK** webhook, you can calculate a much more precise metric: the **\"Perceived Response Time\"**. By measuring the gap between when your agent sent the message and when the [`ACK_READ`] webhook arrived, you can identify if your customers are actually consuming your support advice or if your messages are being ignored.\n\n### 2. The \"Automated Second-Chance\" (Failover Logic)\nIf a high-priority notification (e.g., a fraud alert or a delivery update) stays in the [`ACK_SENT`] state for more than 5 minutes without reaching [`ACK_DELIVERED`], your system can trigger a \"Cross-Channel Escalation.\" It can automatically resend the alert via SMS or initiate an automated voice call. This \"Smart Redundancy\" ensures that critical information is never lost due to a user's temporary lack of data connectivity on WhatsApp.\n\n### 3. Attribution and Engagement Scoring\nIn marketing campaigns, a \"Read\" is as valuable as a \"Click.\" By correlating [`ACK_READ`] events with your broadcast lists, you can build an \"Engagement Score\" for every contact in your CRM. Users who consistently \"Blue Tick\" your messages within 60 seconds of receipt are your \"Highly Active\" leads and should be prioritized for your most specialized, human-led sales outreach.\n\n---\n\n## 🛡️ Administrative Mandate: Protecting the \"Trust Chain\"\n\nConsistency in status updates is more than a technical requirement; it is a brand promise.\n\n### 1. The \"Sent-to-Read\" Velocity Metric\nTrack the \"Velocity\" of your acknowledgements. A sudden increase in the time between `SENT` and `DELIVERED` across your entire instance fleet often indicates a regional network issue or a temporary degradation of the Meta API. By monitoring these durations in aggregate, your technical team can act as a \"Early Warning System,\" notifying your support agents of potential delays before they start receiving complaints.\n\n### 2. Privacy and the \"Silent Reader\"\nIt is strategically important to recognize that some WhatsApp users choose to disable \"Read Receipts\" in their privacy settings. In these cases, a message will move to [`ACK_DELIVERED`] but never to [`ACK_READ`]. A sophisticated architecture doesn't treat this as a \"Failure.\" Instead, it looks for \"Implicit Acknowledgements\"—if a user replies to the message, you can logically infer they read it, even if the blue tick never arrived.\n\n---\n\n## 🛡️ Operational Best Practices: Designing for High-Volume Status Updates\n\n*   **Batching Database Writes**: In a high-volume instance sending 100,000 messages per day, you will receive at least 300,000 ACK webhooks (Sent, Delivered, Read). Do not perform a synchronous database write for every single one. Use a message queue and a \"Buffered Writer\" to update your message statuses in batches, significantly reducing the I/O load on your primary database.\n*   **The \"Final State\" Rule**: Once a message reaches [`ACK_READ`], it has reached its terminal state. Any further webhooks for that Message ID (e.g., retries of the `DELIVERED` state) should be discarded immediately at the ingestion layer to save processing power.\n*   **UI Synchronization (WebSockets)**: If you provide a custom chat UI for your agents, use the ACK webhook to trigger a WebSocket push to the agent's browser. This allows the blue ticks to appear in their UI in real-time, providing the \"Snappy,\" responsive feel that users expect from a modern messaging application.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Monitor \"Out-of-Order\" Delivery**: In mobile networking, packets can take unpredictable paths. Your logic should always include a \"Strict Progression\" check: only update `SENT` to `DELIVERED`, and `DELIVERED` to `READ`. \n2.  **Verify Message Ownership**: The ACK payload includes the `chatId`. Ensure this matches the expected recipient in your local records before updating the status, providing a dual-layer of data integrity.\n3.  **Coordinate with Revocations**: If you receive a [Message Revoked](/v2/webhooks/message-revoked) event, any subsequent ACKs for that message ID should be handled with care, as the original \"Read\" sentiment may no longer be relevant to the current conversation state.\n\n## 🎯 Conclusion: Mastering the Art of the Loop-Closure\n\nThe **Message Acknowledgement Webhook** is the \"Eyes and Ears\" of your outbound strategy. By treating every status update as a data point in a continuous lifecycle, you move your business from \"Blind Distribution\" to **Accountable Engagement**. You build systems that understand not just what was said, but what was heard. In the world of Wawp, ACKs are the foundation of trust, the pulse of performance, and the key to a truly \"Reactive\" enterprise.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01...",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "message.ack",
            "payload": {
              "id": "true_11111111111@c.us_...",
              "ack": 3,
              "ackName": "READ",
              "chatId": "11111111111@c.us"
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123@lid",
              "pushName": "Instance"
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "تأكيد استلام الرسالة (ACK)",
          "description": "تتبع حالة تسليم وقراءة الرسالة (تم الإرسال، تم التسليم، تمت القراءة).",
          "tips": [
            {
              "title": "تنسيق المستلم",
              "content": "استخدم @c.us لجهات الاتصال و @g.us للمجموعات."
            },
            {
              "title": "التعامل مع الوسائط",
              "content": "تأكد من أن روابط الوسائط متاحة للعامة وهي روابط مباشرة."
            }
          ],
          "recommendations": [
            "أضف تأخيرات عشوائية بين الرسائل لمحاكاة السلوك البشري.",
            "تحقق من أرقام الهواتف قبل الإرسال لضمان التسليم."
          ],
          "extraInfo": "\n# دورة حياة الإشارة: إتقان تأكيدات الرسائل (ACK)\n\nفي عالم اتصالات الشركات، \"الإرسال\" هو مجرد بداية رحلة الرسالة. الحقيقة ليست في إرسال البيانات، بل في التحقق من استهلاكها. ويب هوك **تأكيد الاستلام (ACK)** هو حلقة التغذية الراجعة النهائية في Wawp، مما يوفر رؤية فورية لـ \"حالة العبور\" لكل تفاعل صادر.\n\n---\n\n## 🏗️ الفلسفة المعمارية: الرسالة كمتغير مستمر\n\nعلى عكس البريد الإلكتروني أو الرسائل القصيرة (Fire and Forget)، يحول واتساب عبر Wawp عملية الإرسال إلى **دورة حياة مراقبة**:\n*   **تم الإرسال (SENT - مستوى 1)**: تأكيد خروج الرسالة من مثيلك ووصولها لبنية Meta التحتية.\n*   **تم التسليم (DELIVERED - مستوى 2)**: لحظة \"العلامتين الرماديتين\". تؤكد وصول الرسالة لجهاز المستلم، وهو أمر حيوي في السياقات اللوجستية أو الطارئة.\n*   **تمت القراءة (READ - مستوى 3)**: ظاهرة \"العلامتين الزرقاوين\". تمثل حدثاً بشرياً يشير إلى دخول العميل في حالة تفاعل واعية مع علامتك التجارية.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. مراقبة الـ SLA ومساءلة \"الميل الأخير\"\nبدلاً من مجرد قياس \"وقت الرد الأولي\"، يمكن لفرق الدعم قياس **\"وقت الإدراك الاستجابي\"**. من خلال حساب الفجوة بين وقت إرسال الوكيل للرسالة ووقت وصول [`ACK_READ`]، يمكنك معرفة ما إذا كان العملاء يقرأون نصائح الدعم فعلاً أم يتجاهلونها.\n\n### 2. \"الفرصة الثانية المؤتمتة\" (منطق الفشل)\nإذا بقيت رسالة تنبيه عالية الأهمية (مثل تنبيه احتيال) في حالة [`SENT`] لأكثر من 5 دقائق دون الوصول لـ [`DELIVERED`]، يمكن لنظامك تلقائياً إرسال التنبيه عبر رسالة قصيرة (SMS) أو اتصال صوتي لضمان وصول المعلومة الحساسة رغم ضعف بيانات واتساب لدى المستخدم.\n\n---\n\n## 🛡️ أفضل الممارسات التشغيلية والهندسية\n*   **تجميع عمليات الكتابة (Batching)**: في المثيلات عالية الكثافة، ستصل آلاف تأكيدات الاستلام. لا تقم بتحديث قاعدة البيانات لكل حدث على حدة؛ بل استخدم طابوراً (Queue) لتحديث حالات الرسائل في دفعات (Batches) لتقليل العبء على النظام.\n*   **قاعدة الحالة النهائية**: بمجرد وصول الرسالة لحالة [`ACK_READ`]، فقد وصلت لحالتها النهائية. يجب تجاهل أي ويب هوكات متأخرة لنفس المعرف (مثل إعادة إرسال حالة التسليم) لتوفير جهد المعالجة.\n*   **مزامنة واجهة المستخدم (WebSockets)**: استخدم ويب هوك الـ ACK لتحديث \"العلامات الزرقاء\" في لوحة تحكم الوكلاء في الوقت الفعلي، مما يعطي إحساساً بالاستجابة الفورية والاحترافية.\n            "
        }
      }
    },
    {
      "path": "/message.revoked",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Message Revoked",
      "description": "Triggered when a user deletes a message for everyone.",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "warning",
          "title": "Data Erasure",
          "content": "Respect the user's wish to delete the message by removing it from your own database/UI as well."
        }
      ],
      "recommendations": [
        "Update your UI to show 'This message was deleted' on the corresponding message ID.",
        "In groups, check the sender ID to know who revoked the message."
      ],
      "extraInfo": "\n# The Erasure Event: Mastering Message Revocations (Delete for Everyone)\n\nIn the dynamic landscape of real-time messaging, data is not always permanent. The \"Delete for Everyone\" feature—technically known as a **Revocation**—allows users to retract a message after it has been sent. Within the Wawp platform, the [`message.revoked`] webhook provides your infrastructure with the immediate notification that a specific interaction has been invalidated by the sender. \n\nHandling revocations is not just a technical requirement for database synchronization; it is a fundamental pillar of **Conversational Integrity and Privacy Compliance**. This guide provides an architectural deep-dive into the strategic management of revoked content, moving beyond \"Simple Deletion\" into the realm of **State Governance and User Trust**.\n\n---\n\n## 🏗️ Architectural Philosophy: The Volatile Nature of Text\n\nTo master the Revocation API, one must first recognize the philosophical shift from \"Archive-First\" to \"User-First\" data priority. A revocation is a user's explicit command to purge a specific data point from the shared conversational record.\n\n### 1. The ID Mapping Strategy\nThe [`message.revoked`] payload does not contain the original message text; it contains the unique **Message ID** of the item being removed and the **JID** of the person who revoked it. \n*   **Individuals (@c.us)**: In 1-on-1 chats, only the sender or the receiver (on their own side) can revoke.\n*   **Groups (@g.us)**: In a group environment, the [`revokedBy`] field is critical. It identifies if the original sender deleted their own message or if a group administrator used their elevated privileges to remove a participant's message for the entire group.\n\n### 2. The Relationship Between Event and Entity\nYour architecture must maintain a robust index of Message IDs. When a revocation arrives, your system must perform a \"Reverse Lookup\" to find the corresponding record in your CRM or database. The speed and accuracy of this lookup define the \"Sync Quality\" of your integration. An enterprise-grade system ensures that the revoked content \"Vanishes\" from the agent's view within milliseconds of the event firing.\n\n---\n\n## 🚀 Strategic Use Cases: Powering Clean Conversational States\n\nWebhooks for revocation ensure your internal systems remain in perfect harmony with the customer's actual experience.\n\n### 1. Maintaining the \"Service Truth\" (Anti-Ghosting)\nThere is nothing more unprofessional than a human agent or an AI bot responding to a message that the user has already deleted.\n**The Strategic Workflow**: When a message arrives, your system starts its processing logic. If the [`message.revoked`] webhook arrives before the bot's response is sent, the system should instantly **abort the response generation**. This prevents \"Ghost Interactions\" where your bot appears to be \"Hearing voices\"—responding to a question that is no longer there.\n\n### 2. Professional Moderation in High-Volume Groups\nIn community management, administrators often need to remove offensive or off-topic content. By listening to the revocation webhook, your central community dashboard can update its state in real-time. If an admin deletes a message on their phone, the central control panel should immediately hide that message for all human moderators, ensuring the \"Moderation State\" is synchronized across the entire organization.\n\n### 3. Compliance and the \"Right to be Forgotten\"\nIn many jurisdictions (such as GDPR in Europe), a user's request to delete data is a legal mandate. While Wawp purges its own temporary caches, your internal database must also respect this signal. \n**The Policy Engine**: Configure your system to treat a [`message.revoked`] event as an **Authorized Deletion Request**. Instead of just hiding the message in the UI, your system should logically \"Scrub\" the original body content from your database, replacing it with a metadata flag: *[Content Revoked by User]*. This ensures you remain compliant with privacy laws while maintaining a valid audit trail of the conversation's structure.\n\n---\n\n## 🛡️ Administrative Mandate: Scaling the Erase Pipeline\n\nScaling revocations requires a focus on \"Transaction Atomicity.\"\n\n### 1. Handling the \"Revoke Before Receipt\" Edge Case\nIn rare high-latency scenarios, your server might receive the [`message.revoked`] event *before* the original [`message`] event (due to different routing paths in a microservice architecture). \n**The Strategic Solution**: Use a **\"Negative Cache\"** or an **\"Out-of-Order Buffer\"**. If you receive a revocation for an ID you don't recognize, store that ID in a temporary \"Pending Revocation\" list for 60 seconds. If the original message arrives within that window, it should be discarded immediately upon ingestion.\n\n### 2. The \"Audit Trail\" vs. \"Privacy\" Balance\nFor sensitive financial or support interactions, you may need a record that a message *did exist* (for auditing) without keeping the *content* of that message (for privacy). \n**The Balance**: Store the metadata (timestamp, sender JID, message ID) but delete the body, media URLs, and attachments associated with the revoked ID. This provides a \"Skeleton History\" that allows you to prove an interaction occurred without violating the user's intent to retract their specific words.\n\n---\n\n## 🛡️ Operational Best Practices: Optimizing the User Experience\n\n*   **UI Visual Cues**: In your custom agent dashboard, don't just delete the row. Replace it with a faded \"Message deleted\" placeholder. This provides the agent with context: \"The customer said something but changed their mind.\" This awareness allows the agent to adjust their tone accordingly.\n*   **Aborting Media Downloads**: If a revocation fires for a media message (image/video) that your system is currently downloading, stop the download process immediately. This saves bandwidth and ensures that sensitive visuals are not stored on your servers.\n*   **Admin Revocation Alerts**: In group management contexts, if an admin (`@c.us`) revokes a message in a group (`@g.us`), your system can tag this event as a \"Moderator Action.\" This data can be used to generate \"Moderation Reports,\" helping you identify which admins are most active in keeping the community clean.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Iterative Indexing**: Ensure your Message ID index is optimized for high-speed \"Delete\" operations. Using a B-Tree or Hash index on the ID field is mandatory for maintaining performance as your database grows.\n2.  **Verify Revoker Authority**: In groups, verify the [`revokedBy`] JID. If your system relies on specific \"Trust Levels,\" you should confirm that the revoker has the necessary permission to delete the target message.\n3.  **Cross-Instance Siloing**: Just like the message webhook, ensure revocation logic is scoped to the specific [`session`]. Never allow a revocation from Instance A to accidentally trigger a lookup in the database for Instance B.\n\n## 🎯 Conclusion: The Power of the Retraction Signal\n\nThe **Message Revoked Webhook** is the \"Eraser\" of your digital brand. By building an architecture that respects these signals, you move your organization from \"Static Archiving\" to **Respectful, Real-Time Synchronization**. You build systems that understand the fluidity of human conversation, respect user privacy, and maintain a high-fidelity \"Single Source of Truth.\" In the world of Wawp, a revocation is not an error; it is a vital conversational signal that ensures your integration remains as human, as private, and as accurate as WhatsApp itself.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01...",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "message.revoked",
            "payload": {
              "id": "false_11111111111@c.us_...",
              "revokedBy": "11111111111@c.us"
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123@lid",
              "pushName": "Instance"
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "حذف الرسالة (للجميع)",
          "description": "يتم تفعيله عندما يقوم المستخدم بحذف رسالة للجميع.",
          "tips": [
            {
              "title": "تنسيق المستلم",
              "content": "استخدم @c.us لجهات الاتصال و @g.us للمجموعات."
            },
            {
              "title": "التعامل مع الوسائط",
              "content": "تأكد من أن روابط الوسائط متاحة للعامة وهي روابط مباشرة."
            }
          ],
          "recommendations": [
            "أضف تأخيرات عشوائية بين الرسائل لمحاكاة السلوك البشري.",
            "تحقق من أرقام الهواتف قبل الإرسال لضمان التسليم."
          ],
          "extraInfo": "\n# حدث المحو: إتقان التراجع عن الرسائل (السيادة على المحتوى)\n\nفي اتصالات الوقت الفعلي، البيانات ليست دائمة دائماً. توفر ميزة \"الحذف للجميع\" — والمعروفة تقنياً بـ **النقض (Revocation)** — للمستخدمين القدرة على سحب رسالة بعد إرسالها. يوفر ويب هوك [`message.revoked`] إشعاراً فورياً بأن تفاعلاً معيناً قد تم إبطاله من قبل المرسل، وهو ركن أساسي لـ **سلامة المحادثة والامتثال للخصوصية**.\n\n---\n\n## 🏗️ الفلسفة المعمارية: طبيعة النص المتطايرة\n\nيجب الاعتراف بالتحول الفلسفي من \"الأرشفة أولاً\" إلى \"سيادة المستخدم على بياناته\". النقض هو أمر صريح من المستخدم لتطهير نقطة بيانات معينة من سجل المحادثة المشترك.\n*   **استراتيجية ربط الهوية**: لا تحتوي حمولة [`message.revoked`] على نص الرسالة الأصلي؛ بل تحتوي على **معرف الرسالة** الفريد و **معرف الشخص (JID)** الذي قام بالحذف.\n*   **النقض في المجموعات**: في المجموعات، يعد حقل [`revokedBy`] حاسماً؛ فهو يوضح ما إذا كان المرسل الأصلي قد حذف رسالته، أو إذا استخدم مسؤول المجموعة صلاحياته لإزالة رسالة أحد المشاركين للمجموعة بأكملها.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. الحفاظ على \"حقيقة الخدمة\" (منع التفاعل مع الأشباح)\nمن غير المهني أن يقوم بوت أو وكيل بشري بالرد على رسالة قام المستخدم بحذفها بالفعل. عندما يصل الويب هوك، يجب على النظام فوراً **إيقاف توليد أي رد تلقائي** مرتبط بتلك الرسالة، مما يمنع ظهور البوت كأنه \"يسمع أصواتاً\" أو يرد على أسئلة لم تعد موجودة.\n\n### 2. الامتثال والخصوصية (الحق في النسيان)\nفي العديد من التشريعات (مثل GDPR في أوروبا)، يعد طلب المستخدم حذف بياناته أمراً قانونياً ملزماً. يجب على نظامك معاملة حدث [`message.revoked`] كـ **طلب حذف مخول**. بدلاً من مجرد إخفاء الرسالة، يجب على نظامك \"تطهير\" نص الرسالة الأصلي من قاعدة بياناتك واستبداله بعلامة وصفية: *[تم حذف المحتوى بواسطة المستخدم]*.\n\n---\n\n## 🛡️ أفضل الممارسات التشغيلية والهندسية\n*   **إشارات واجهة المستخدم**: في لوحة تحكم الوكلاء، لا تحذف السطر تماماً، بل استبدله بنص باهت \"تم حذف هذه الرسالة\". هذا يوفر سياقاً للوكيل: \"لقد قال العميل شيئاً ثم تراجع عنه\"، مما يسمح للوكيل بتعديل أسلوبه.\n*   **إيقاف تحميل الوسائط**: إذا تم نقض رسالة وسائط (صورة/فيديو) بينما يقوم نظامك بتحميلها حالياً، فأوقف عملية التحميل فوراً لتوفير البث الأرضي وضمان عدم تخزين صور حساسة على خوادمك.\n*   **تحقق من صلاحية الناقض**: في المجموعات، تأكد من هوية الشخص الذي حذف الرسالة. إذا قام مسؤول بحذفها، يمكنك تسجيل ذلك كـ \"إجراء إشرافي\" لتحليل نشاط المشرفين في الحفاظ على نظافة المجتمع.\n            "
        }
      }
    },
    {
      "path": "/message.edited",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Message Edited",
      "description": "Triggered when a sent message is modified by the user.",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "Time Window",
          "content": "Edits can only happen within a short professional window after sending (approx 15 mins)."
        }
      ],
      "recommendations": [
        "Update the text content for the existing message ID in your database.",
        "Consider keeping an edit history if your application requires message auditing."
      ],
      "extraInfo": "\n# The Second Chance: Mastering Message Edited Webhooks\n\nIn the fluid world of real-time communication, mistakes are inevitable. A typo, an incorrect price quote, or a misunderstood instruction can lead to significant business friction. The **Message Edited** feature on WhatsApp allows users and bots to correct their errors after the signal has been sent. Within the Wawp platform, the [`message.edited`] webhook is the definitive \"Truth Update\" signal, providing your infrastructure with the immediate notification that an existing interaction has been refined.\n\nHandling edits is not just a technical requirement for UI synchronization; it is a fundamental pillar of **Contextual Accuracy and Data Integrity**. This guide provides an architectural deep-dive into the strategic management of edited content, moving beyond \"Simple Text Updates\" into the realm of **Conversational Governance and Professional Auditing**.\n\n---\n\n## 🏗️ Architectural Philosophy: The Mutable Message\n\nTo master the Message Edited API, one must first recognize the transition from \"Immutable Logs\" to \"Living Conversations.\" A message is no longer a static data point; it is a dynamic entity that can be re-defined within a specific professional window.\n\n### 1. The ID Linkage Strategy\nThe [`message.edited`] payload is structurally tied to the **Original Message ID**. \n*   **The Identifier Map**: Your system must use the [`id`] in the payload to locate the specific record in your CRM or support database. Unlike a new message search, this is a \"Correction Search.\"\n*   **The Body Delta**: The payload provides the [`newBody`] (the current truth) and, where available, the [`prevBody`] (the historical context). \n\n### 2. Contextual Reach (JIDs)\nEdits occur across the entire spectrum of WhatsApp interaction:\n*   **Individual Chats (@c.us)**: Messages where [`from`] ends in `@c.us` represent personal or business-to-customer corrections.\n*   **Group Chats (@g.us)**: In a group environment, an edit by a specific participant updates the shared record for all members. Your ingestion layer must handle this as a \"Group State Update,\" ensuring every agent looking at that group sees the corrected information simultaneously.\n\n---\n\n## 🚀 Strategic Use Cases: Powering Accurate Interactions\n\nThe message edited webhook ensures your internal systems remain in perfect harmony with the customer's intended meaning.\n\n### 1. Zero-Friction Correction in Sales and Quoting\nImagine a sales agent sends a quote: \"The total price is $1,500.\" They immediately realize it should be $1,050 and use the WhatsApp \"Edit\" feature to fix it.\n**The Strategic Workflow**: As soon as the [`message.edited`] webhook fires, your backend updates the Quote record in your CRM. If your system was about to generate an automated invoice based on the $1,500 text, the webhook serves as an **Emergency Correction Trigger**, ensuring the final document matches the user's intended price. This prevents billing errors and preserves customer trust.\n\n### 2. Maintaining the \"Contextual Truth\" for Human Agents\nThere is nothing more confusing for a human support agent than a customer saying \"As I said in the corrected message above...\" if the agent's dashboard still shows the old, incorrect text.\n**The Real-Time Sync**: Use the edited webhook to trigger a WebSocket push to the agent's browser. The text should visually \"Morph\" or update with an \"Edited\" badge in real-time. This ensures the human agent is always looking at the **Current State of the Truth**, eliminating the \"Responsiveness Gap\" caused by outdated message logs.\n\n### 3. AI Intent Re-Analysis\nIf your bot logic uses an LLM to determine customer intent, an edit is a \"Signal of Refinement.\"\n**The Logic**: When a message is edited, your system should re-run its intent analysis on the [`newBody`]. If the original message was \"How do I cancel?\" but the user edited it to \"How do I cancel my *Gold* plan specifically?\", the refined intent allows your bot to provide a much more accurate, high-value response. An enterprise-grade system treats an edit as a **Contextual Re-Trigger** for its intelligent processing layers.\n\n---\n\n## 🛡️ Administrative Mandate: Scaling the Correction Pipeline\n\n### 1. The Audit Trail Discipline\nIn regulated industries (like Legal, Finance, or Healthcare), you cannot simply overwrite data. You must maintain an **\"Edit History\"**.\n**The Strategic Architecture**: When a [`message.edited`] event arrives, do not delete the old text. Instead, move the old text into a `message_versions` table. This provides a \"Transparent History\" of the interaction. If a dispute arises later, your compliance team can see exactly what was said first and how it was corrected. This is the gold standard for **Technical Accountability**.\n\n### 2. Handling the \"Race Condition\" on Ingestion\nIn high-frequency environments, a user might send a message and edit it within 2 seconds. Because webhooks are asynchronous, your server might receive the [`edited`] event before the original [`message`] event is fully written to your primary database.\n**The Robust Solution**: Implement a **\"Staged Update\"**. If your lookup for the original Message ID fails, place the edit payload into a \"Pending Sync\" queue for 5-10 seconds. Once the original message is ingested, the queue processor can then apply the edit. This ensures no correction is lost due to transient networking timing.\n\n---\n\n## 🛡️ Operational Best Practices: Designing for Professional Clarity\n\n*   **The \"Edited\" Badge UI**: Always display a visual indicator (like a small clock icon or the word \"Edited\") next to the corrected text in your custom dashboard. This tells the agent: \"The user changed their mind about what they said here.\"\n*   **MIME-Type Stability**: Note that WhatsApp currently primarily supports editing **Text Messages**. If you receive an edit event for a media message (image/video), it typically signifies a change to the **Caption**. Your system should specifically target the `caption` field in your media records to apply these updates.\n*   **Coordinate with Acknowledgements (ACKs)**: Edits do not reset the delivery status. If a message was already \"Read\" (ACK 3), editing it doesn't turn the ticks back to gray. However, the *corrected* content should be treated as \"Not yet consumed\" by the agent until they look at the screen again.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Deduplicate Edits**: If a user edits the same message three times in a row, you will receive three webhooks. Ensure your database update logic is idempotent and only processes the latest timestamp provided in the event metadata.\n2.  **Verify Edit Authority**: In groups (`@g.us`), only the person who sent the message can edit it. Your system should verify the [`author`] in the edit payload matches the author of the original message to prevent state-injection errors.\n3.  **Cross-Instance Siloing**: Ensure that the edit lookup is strictly scoped to the [`session`]. An edit for a message on Instance A should never attempt to update a message record belonging to Instance B.\n\n## 🎯 Conclusion: Beyond Correction—The Art of the Living Record\n\nThe **Message Edited Webhook** is the \"Living Update\" of your digital brand. By building an architecture that listens, archives, and synchronizes these corrections, you move your organization from \"Static Log Management\" to **Dynamic Conversational Alignment**. You build systems that understand the fluidity of human intent, preserve the history of change, and always present the most accurate version of the truth. In the world of Wawp, an edit is not a failure; it is a vital conversational signal that ensures your integration remains as precise, as professional, and as adaptable as the business it represents.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01...",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "message.edited",
            "payload": {
              "id": "false_11111111111@c.us_...",
              "newBody": "Updated message text!",
              "prevBody": "Old message text"
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123@lid",
              "pushName": "Instance"
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "تعديل الرسالة",
          "description": "يتم تفعيله عندما يقوم المستخدم بتعديل رسالة مرسلة.",
          "extraInfo": "\n# الفرصة الثانية: إتقان ويب هوك تعديل الرسائل\n\nفي عالم الاتصالات الفورية، الأخطاء واردة جداً. يوفر ويب هوك [`message.edited`] إشارة \"تحديث الحقيقة\" النهائية، حيث يزود بنيتك التحتية بإشعار فوري بأن تفاعلاً حالياً قد تم تنقيحه. لا تقتصر معالجة التعديلات على مزامنة واجهة المستخدم فحسب، بل هي ركيزة أساسية لـ **دقة السياق وسلامة البيانات**.\n\n---\n\n## 🏗️ الفلسفة المعمارية: الرسالة المتغيرة\n\nيجب إدراك التحول من \"السجلات الثابتة\" إلى \"المحادثات الحية\". لم تعد الرسالة نقطة بيانات جامدة، بل هي كائن ديناميكي يمكن إعادة تعريفه.\n*   **استراتيجية ربط الهوية**: ترتبط حمولة [`message.edited`] برمجياً بـ **معرف الرسالة الأصلي**. يجب على نظامك استخدام المعرف [`id`] لتحديد السجل الصحيح في الـ CRM وتحديثه بدلاً من إنشاء سجل جديد.\n*   **تحديث الحقيقة**: توفر الحمولة النص الجديد [`newBody`]، مما يسمح لنظامك بعرض النسخة الأحدث والأكثر دقة للوكلاء.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي: التفاعل الدقيق\n\n### 1. التصحيح الفوري في عروض الأسعار\nإذا أرسل وكيل مبيعات سعراً خاطئاً وقام بتعديله فوراً عبر واتساب، فإن ويب هوك التعديل يعمل كـ **محفز تصحيح طوارئ**. يضمن ذلك تحديث سجل العرض في الباك-إند وتوليد الفاتورة النهائية بناءً على السعر المصحح، مما يمنع أخطاء الفواتير ويحافظ على ثقة العميل.\n\n### 2. إعادة تحليل النية بالذكاء الاصطناعي\nإذا كان البوت الخاص بك يستخدم نماذج لغوية (LLM) لتحديد نية العميل، فإن التعديل هو \"إشارة تنقيح\". يجب على نظامك إعادة تشغيل تحليل النية على النص الجديد [`newBody`]. فإذا تحولت الرسالة من \"كيف ألغي اشتراكي؟\" إلى \"كيف ألغي اشتراك الباقة *الذهبية* تحديداً؟\"، فإن التعديل يتيح للبوت تقديم إجابة أكثر دقة وعالية القيمة.\n\n---\n\n## 🛡️ أفضل الممارسات المهنية\n*   **سجل التدقيق (Audit Trail)**: في الصناعات الخاضعة للرقابة، لا تكتفِ باستبدال البيانات. احتفظ بـ \"تاريخ التعديلات\" (Edit History)؛ فعند وصول الحدث، انقل النص القديم إلى جدول \"نسخ الرسائل\" وحدث النص الحالي. هذا هو المعيار الذهبي لـ **المساءلة التقنية**.\n*   **علامة \"معدلة\" في واجهة المستخدم**: أظهر دائماً مؤشراً بصرياً (مثل أيقونة ساعة صغيرة) بجانب النص المصحح في لوحة تحكم الوكيل. هذا يخبر الوكيل البشري: \"لقد غير المستخدم رأيه بشأن ما قاله هنا\"، مما يسمح للوكيل بتعديل لهجته وسياق رده.\n            "
        }
      }
    },
    {
      "path": "/group.v2.join",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Group Join (V2)",
      "description": "Triggered when a new member joins or is added to a group.",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "positive",
          "title": "Auto-Welcome",
          "content": "Use this to automatically send a welcome message or rule set to new group members."
        }
      ],
      "recommendations": [
        "Verify if the user joined via a link or was manually added by an admin.",
        "Store the new participant's ID in your CRM database."
      ],
      "extraInfo": "\n# Community Onboarding: Mastering the Group Join Webhook\n\nIn the high-scale world of community management and enterprise collaboration, the point of entry is the most critical moment of the lifecycle. The [`group.v2.join`] webhook is the primary signal that a new entity has entered a shared conversational space. Whether a user joins via a shared invitation link or is manually added by a community moderator, this event provides your infrastructure with the real-time data required to execute onboarding flows, security audits, and membership tracking.\n\nThis guide provides an architectural deep-dive into the strategic importance of group entry events, moving beyond \"Membership Tracking\" into the realm of **Automated Community Governance and Operational Security**.\n\n---\n\n## 🏗️ Architectural Philosophy: The Gatekeeper Pattern\n\nTo build a premium group experience, one must treat the group join event as a \"Membership Handshake.\" A group in WhatsApp is identified by its unique **Group JID** (ending in `@g.us`), and its members are **Individual JIDs** (ending in `@c.us`).\n\n### 1. The Membership Handshake\nWhen an entry event occurs, your system is handed a two-layer payload: the [`chatId`] (the Group) and a list of [`participants`] (the new members). This allows for **Batch Ingestion**. If a moderator adds five users at once, your system receives a single atomic event containing all five IDs. This efficiency is critical for preventing \"Webhook Flood\" during large community migrations.\n\n### 2. Identifying the Entry Vector\nWhile the current event primarily confirms \"Who Joined,\" a sophisticated architecture correlates this with the **Join Method**. \n*   **The Invitation Link**: If a user joins via a link, your system should treat them as a \"Self-Service Lead.\" \n*   **The Manual Add**: If they were added by an admin, they are an \"Invited Participant.\" \nYour onboarding logic (e.g., the welcome message) should adapt based on this vector to ensure the tone of the interaction matches the user's entry experience.\n\n---\n\n## 🚀 Strategic Use Cases: Powering the Responsive Community\n\nThe group join webhook is the \"Sensor\" that triggers your community's automated greeting and security protocols.\n\n### 1. Zero-Latency Onboarding and Rule Enforcement\nFirst impressions are permanent. As soon as the [`group.v2.join`] webhook fires, your bot can instantly send a personalized welcome message to the group: *\"Welcome to the team, [User Name]! Please read our #rules and introduce yourself.\"* \n**Strategic Value**: By automating this, you ensure every new member is immediately integrated into the community standards without requiring a human moderator to be online 24/7. This creates a sense of \"Active Presence\" for your brand.\n\n### 2. Dynamic CRM Hydration and KYC\nFor subscription-based communities (e.g., \"Premium Trading Groups\"), the join event is a **Verification Trigger**. \n**The Logic**: When a user joins the [`@g.us`] group, your system looks up their [`@c.us`] ID in your payment database. If no active subscription is found, your system can autonomously remove the user and send them a private message explaining how to join legally. This \"Automated Perimeter Defense\" protects your revenue stream from unauthorized link sharing.\n\n### 3. Community Health and Growth Analytics\nTrack \"Join Velocity.\" By logging every entry event, you can build a real-time dashboard showing your community's growth rate. If you see a spike in joins after a specific marketing email, you have direct, high-fidelity attribution of that campaign's success. This data allows you to move from \"Managing Chats\" to **Managing a Growing Ecosystem**.\n\n---\n\n## 🛡️ Administrative Mandate: Designing for Community Security\n\n### 1. The \"Shadow Directory\" Strategy\nWhatsApp groups do not naturally sync with external CRMs. You must build a **\"Shadow Directory\"**—a local database that mirrors every group's membership. The [`group.v2.join`] and [`group.v2.leave`] webhooks are the \"Sync Sentinels\" that keep this directory accurate. \n**Benefit**: When an agent needs to send a broadcast to all \"Active Community Members,\" they don't have to query WhatsApp; they query your fast, local directory.\n\n### 2. Guarding against \"Number Scraping\"\nMalicious actors often join groups solely to harvest the phone numbers of other participants. By monitoring the join stream, your system can cross-reference new IDs against a global \"Blacklist\" of known scrapers. If a flagged ID joins, the system can autonomously eject them within seconds, protecting the privacy of your genuine community members.\n\n---\n\n## 🛡️ Operational Best Practices: Optimizing the Onboarding Loop\n\n*   **The \"Welcome Debounce\" Rule**: If three users join within 5 seconds, don't send three separate welcome messages. Your system should \"Debounce\" the event—wait 10 seconds, then send a single message: *\"Welcome to our new members: [User 1], [User 2], and [User 3]!\"* This keeps the chat history clean and professional.\n*   **Private vs. Public Greetings**: For high-privacy groups, consider having the bot send the \"Rules\" message to the new user's **Private Chat (@c.us)** instead of the main group. This provides a personal, 1-on-1 welcome while keeping the group chat focused on its primary topic.\n*   **Handling the \"me\" Identity**: Note that if *your* instance ID (the [`me`] field in the metadata) is added to a new group, this webhook will also fire. Your system should detect this \"Self-Join\" event to automatically initialize the group's metadata and settings in your local records.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Deduplicate Participants**: Always iterate through the [`participants`] array and treat each ID as a separate transactional update in your database. Ensure your \"Member Count\" logic is idempotent to handle potential event retries.\n2.  **Verify Group Integrity**: Before sending a welcome message, verify that the [`chatId`] is still an active, non-archived group in your logic.\n3.  **Coordinate with Presence**: If a user joins but their presence state is \"Invisible\" or has no status, your system might wait for their first message before triggering a complex onboarding flow to ensure they are actually seen by the bot.\n\n## 🎯 Conclusion: Beyond Membership—Building the Conversational Perimeter\n\nThe **Group Join Webhook** is the \"Front Door\" of your digital community. By building an architecture that listens, verifies, and greets, you move your organization from \"Hosting a Chat\" to **Governing an Interface**. You build systems that reward genuine interest, enforce community standards, and protect user privacy with engineered precision. In the world of Wawp, an entry event is not just a log entry; it is the strategic signal that turns a stranger into a member of your conversational ecosystem.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01...",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "group.v2.join",
            "payload": {
              "chatId": "1234567890@g.us",
              "participants": [
                "11111111111@c.us"
              ]
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123@lid",
              "pushName": "Instance"
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "انضمام لمجموعة (V2)",
          "description": "يتم تفعيله عند انضمام عضو جديد أو إضافته إلى مجموعة.",
          "tips": [
            {
              "title": "حدود معدل API",
              "content": "احترم حدود معدل API لتجنب الحظر المؤقت."
            },
            {
              "title": "العمليات غير المتزامنة",
              "content": "معظم العمليات غير متزامنة. استخدم Webhooks للتحديثات في الوقت الفعلي."
            }
          ],
          "recommendations": [
            "استخدم متغيرات البيئة لبيانات الاعتماد الحساسة مثل رموز الوصول.",
            "قم بتنفيذ معالجة قوية للأخطاء ومنطق إعادة المحاولة."
          ],
          "extraInfo": "\n# إدارة استقبال المجتمع: إتقان ويب هوك الانضمام للمجموعات\n\nفي عالم إدارة المجتمعات الكبيرة، تعد لحظة الدخول هي اللحظة الأكثر أهمية. يعد ويب هوك [`group.v2.join`] الإشارة الأساسية لدخول كيان جديد إلى مساحة محادثة مشتركة، سواء عبر رابط دعوة أو إضافة يدوية. يزود هذا الحدث بنيتك التحتية بالبيانات اللازمة لبدء مسارات الاستقبال، والتدقيق الأمني، وتتبع العضوية.\n\n---\n\n## 🏗️ الفلسفة المعمارية: نمط حارس البوابة\n\nلبناء تجربة متميزة، يجب معاملة حدث الانضمام كـ \"صافحة عضوية\".\n*   **صافحة العضوية**: يتم تسليمك حمولة تتضمن [`chatId`] (المجموعة) وقائمة بالـ [`participants`] (الأعضاء الجدد). يتيح ذلك \"المعالجة الجماعية\"؛ فإذا أضاف مسؤول 5 مستخدمين معاً، سيصلك حدث واحد يحتوي على جميع المعرفات، مما يمنع إغراق نظامك بالطلبات.\n*   **تحديد وسيلة الدخول**: ننصح بربط هذا الحدث بوسيلة الانضمام. المنضم عبر رابط هو \"عميل محتمل\"، بينما المنضم يدوياً هو \"مشارك مدعو\". يجب أن تتكيف رسالة الترحيب الخاصة بك بناءً على هذا السياق لضمان نبرة احترافية.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. الاستقبال الفوري وفرض القواعد\nبمجرد انطلاق ويب هوك [`group.v2.join`]، يمكن للبوت إرسال رسالة ترحيب مخصصة فوراً: *\"أهلاً بك في الفريق [اسم المستخدم]! يرجى قراءة #القواعد وتعريف نفسك\"*. هذا يخلق انطباعاً بـ \"الحضور النشط\" لعلامتك التجارية على مدار الساعة.\n### 2. التحقق التلقائي من الهوية (KYC)\nللمجتمعات القائمة على الاشتراكات، يعد حدث الانضمام **محفزاً للتحقق**. يبحث النظام عن معرف المستخدم في قاعدة بيانات الدفع؛ وإذا لم يتم العثور على اشتراك نشط، يمكن للنظام إزالته تلقائياً وإرسال رسالة خاصة توضح كيفية الاشتراك رسمياً، مما يحمي إيراداتك من مشاركة الروابط غير المصرح بها.\n\n---\n\n## 🛡️ التفويض الإداري: تصميم أمن المجتمع\nننصح ببناء **\"دليل الظل\" (Shadow Directory)**؛ وهي قاعدة بيانات محلية تعكس عضوية كل مجموعة. تعمل ويب هوكات [`group.v2.join`] و [`group.v2.leave`] كـ \"حراس المزامنة\" لإبقاء هذا الدليل دقيقاً، مما يسهل عمليات البث الجماعي (Broadcast) دون الحاجة للاستعلام المكثف من واتساب.\n            "
        }
      }
    },
    {
      "path": "/group.v2.leave",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Group Leave (V2)",
      "description": "Triggered when a member leaves or is removed from a group.",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "Retention Logic",
          "content": "Use this to track churn or automatically follow up with members who leave (if appropriate)."
        }
      ],
      "recommendations": [
        "Update your group member list in your backend database.",
        "Check if it's a voluntary leave or an admin removal."
      ],
      "extraInfo": "\n# Group Leaving\n\nTriggered whenever someone is no longer part of the group.\n\n### Fields\n*   **chatId**: The group ID.\n*   **participants**: Array of IDs that left.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01...",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "group.v2.leave",
            "payload": {
              "chatId": "1234567890@g.us",
              "participants": [
                "11111111111@c.us"
              ]
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123@lid",
              "pushName": "Instance"
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "مغادرة مجموعة (V2)",
          "description": "يتم تفعيله عند مغادرة عضو للمجموعة أو إزالته منها.",
          "extraInfo": "\n# مغادرة المجموعة: تحليل دورة حياة العضوية\n\nيعد ويب هوك [`group.v2.leave`] المكمل الضروري لحدث الانضمام. هو الإشارة التي تخبر نظامك بأن مستخدماً لم يعد جزءاً من مساحة العمل المشتركة. يعد تتبع هذا الحدث حيوياً للحفاظ على سلامة بياناتك وفهم معدلات بقاء المستخدمين (Retention).\n\n---\n\n## 🏗️ الفلسفة المعمارية: إنهاء صافحة العضوية\n\n*   **تحديث دليل المزامنة**: يجب أن يقوم هذا الويب هوك فوراً بتحديث \"دليل الظل\" الخاص بك لإزالة المستخدم من المجموعة. يمنع هذا إرسال رسائل أو بيانات حساسة لمستخدم لم يعد مشاركاً.\n*   **تمييز سبب المغادرة**: هل غادر المستخدم طوعاً أم تمت إزالته بواسطة مسؤول؟ (يمكن التحقق من ذلك بمقارنة الحدث مع سجلات المسؤولين). المغادرة الطوعية قد تستحق رسالة \"نأسف لرحيلك\"، بينما الإزالة بواسطة مسؤول قد تكون جزءاً من إجراء انضباطي.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. تحليل الانقطاع (Churn Analysis)\nسيساعدك رصد هذا الويب هوك على فهم \"لماذا يغادر الناس؟\". إذا لاحظت مغادرة جماعية بعد إرسال رسالة معينة من قبل النظام، فقد تكون النبرة غير ملائمة.\n### 2. الأتمتة الإدارية للموارد\nعندما يغادر موظف مجموعة عمل، يمكن للنظام تلقائياً إيقاف وصوله للموارد المرتبطة بتلك المجموعة في أنظمتك الأخرى (مثل Slack أو Drive)، مما يعزز الأمان الهيكلي للشركة.\n            "
        }
      }
    },
    {
      "path": "/group.v2.update",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Group Updated (V2)",
      "description": "Triggered when group settings like title, description, or icon are changed.",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "Synchronization",
          "content": "Keep your mirrored group metadata up to date using this event."
        }
      ],
      "recommendations": [
        "Update the 'subject' or 'description' in your database.",
        "Detect if the group icon changed to refresh your UI cache."
      ],
      "extraInfo": "\n# The Living Community: Mastering Group Update Webhooks (V2)\n\nIn the architecture of large-scale community management and B2B communication, a group is more than just a chat—it is a digital entity with its own identity, rules, and visibility. The **Group Updated (V2)** webhook is the primary signal that the metadata or configuration of a shared workspace has changed. Whether a title is renamed for a new project phase or a group is \"Locked\" by an administrator, the [`group.v2.update`] event provides your infrastructure with the real-time data required to maintain a high-fidelity **Mirror Directory** of your organizational chats.\n\nThis guide provides an architectural deep-dive into the strategic importance of group metadata tracking, moving beyond \"Logging Changes\" into the realm of **Brand Consistency, Operational Governance, and Community Health**.\n\n---\n\n## 🏗️ Architectural Philosophy: The Metadata Mirror\n\nTo build a premium enterprise experience, your system must treat group settings as \"States of Truth.\" A group is identified by its unique **Group JID** (ending in `@g.us`), and its current configuration (Title, Description, Permissions) defines the \"Interface Rules\" for all participants.\n\n### 1. The Mirror Directory Strategy\nWhatsApp does not provide a \"Push Sync\" for group settings until a change occurs. Therefore, your architecture must maintain a local database that mirrors every active group.\n*   **The Ingestion Loop**: When a [`group.v2.update`] fires, your system performs an \"Upsert\" operation. If the Group ID is already in your CRM, update the relevant field (e.g., `subject`). If it doesn't exist, this event acts as a \"Discovery Trigger\" to initialize the group record.\n*   **Field-Level Atomicity**: The payload identifies exactly what changed—be it the [`subject`] (title), [`description`], or [`restrictMode`] (who can send messages).\n\n### 2. Identifying the Actor\nWhile the payload focuses on \"What Changed,\" correlation with the sender JID (if available in the metadata) allows your system to identify **Who** initiated the change. This is critical for auditing accountability in multi-admin environments.\n\n---\n\n## 🚀 Strategic Use Cases: Powering Dynamic Community Governance\n\nGroup updates are the \"Control Signals\" that allow your bot logic to adapt to the changing environment of a live chat.\n\n### 1. Brand Consistency and \"Subject Protection\"\nFor official brand communities, the Group Title (Subject) is a critical asset.\n**The Strategic Workflow**: If a non-authorized user (someone not flagged as a \"Brand Manager\" in your CRM) changes the group's subject to something unprofessional, your system can detect this [`group.v2.update`] immediately. It can then programmatically [Update the Subject](/v2/groups/update) back to the official name and send a warning message: *\"Hi! Only authorized admins are permitted to change the group title. Reverting to 'Official Branding'...\"* This automated protection ensures your brand remains professional 24/7 without manual supervision.\n\n### 2. Operational Pivoting (Announcement Mode)\nMany communities transition between \"Open Discussion\" and \"Announcement Only\" modes (where only admins can post). \n**The Logic**: When you receive a [`group.v2.update`] indicating that [`announceMode`] has been enabled, your bot should immediately \"Step Back.\" It should stop processing user messages (which are now impossible anyway) and perhaps update its internal state to \"Broadcast Mode.\" Conversely, when the group is \"Opened,\" the bot can send a summary of what was missed during the locked period. This creates a \"Smooth Handover\" between different community configurations.\n\n### 3. CRM Information Enrichment\nThe \"Description\" field of a WhatsApp group is often used for #rules, links to external FAQs, or project IDs. \n**The Insight**: By parsing the [`description`] in every update event, your system can automatically extract metadata. If a project manager adds `ProjectID: #9921` to the group description, your Wawp-powered CRM can automatically link this WhatsApp Group JID to the corresponding entry in your Project Management software. This is **Automated Contextual Mapping** at its finest.\n\n---\n\n## 🛡️ Administrative Mandate: Designing for Community Security\n\n### 1. The \"Audit Trail\" for Accountability\nIn sensitive corporate communications, knowing when a group's purpose shifted is vital.\n**The Policy Engine**: store a full \"History of Settings\" for every group. This allows a compliance officer to look back and see: *\"The group was renamed from 'Confidential R&D' to 'Public Beta' at 14:00 by John Doe.\"* This transparency is a requirement for SOC2 and other enterprise compliance frameworks.\n\n### 2. Monitoring \"Description Spam\"\nMalicious actors often join open groups and edit the description to include phishing links. By monitoring the [`description`] update stream, your system can automatically scan for \"Blacklisted URLs.\" If a malicious link is detected in an update, the system can autonomously delete the description or notify an admin within seconds of the edit.\n\n---\n\n## 🛡️ Operational Best Practices: Optimizing the Update Loop\n\n*   **The \"Icon Refresh\" Trigger**: If the group's profile picture changes, the [`group.v2.update`] event (or a companion `profile_picture` event) should trigger your system to fetch the new image URL. This ensures that the avatars in your agent dashboard always match the reality of the WhatsApp client, preventing agent confusion.\n*   **The \"Silent Onboarding\" Rule**: If a group's subject changes from \"New Chat\" to a recognized project name, your bot can use this as a trigger to send a \"Welcome to the Project\" packet, even if the bot was already a member of the group.\n*   **Coordinate with Participants**: Often, a group update happens alongside a participant change (e.g., someone is promoted to Admin). Your system should cross-reference `group.v2.update` with [Group Participant Change](/v2/webhooks/group-v2-participants) events to build a complete picture of the \"Power Dynamics\" within the chat.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Strict State Synchronization**: Use a \"Version Counter\" or a strict timestamp comparison. Do not apply a group update if your database already contains a \"Newer\" update for that specific [`chatId`]. This prevents \"Update Flip-Flopping\" in high-latency network scenarios.\n2.  **Verify Asset Accessibility**: If a description update contains a link, your system should perform a \"Head Request\" to verify the link's safety before allowing it to be indexed in your searchable records.\n3.  **Scoped Logic by ID**: Groups ending in `@g.us` are the only valid targets for this webhook. Ensure your ingestion layer ignores any Malformed/Test IDs to prevent database pollution.\n\n## 🎯 Conclusion: Beyond Settings—The Architecture of Context\n\nThe **Group Updated Webhook** is the \"Registry of Purpose\" for your digital communities. By building an architecture that listens, protects, and synchronizes these metadata shifts, you move your organization from \"Generic Messaging\" to **Context-Aware Governance**. You build systems that protect brand integrity, automate administrative tasks, and maintain a perfect \"Mirror of Reality\" for your human agents. In the world of Wawp, an update is more than a change—it is the strategic signal that keeps your conversational ecosystem aligned with your business objectives.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01...",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "group.v2.update",
            "payload": {
              "chatId": "1234567890@g.us",
              "subject": "New Group Name",
              "description": "Updated description text"
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123@lid",
              "pushName": "Instance"
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "تحديث بيانات المجموعة (V2)",
          "description": "يتم تفعيله عند تغيير إعدادات المجموعة مثل الاسم، الوصف، أو أيقونة المجموعة.",
          "extraInfo": "\n# المجتمع الحي: إتقان ويب هوك تحديث المجموعة\n\nالمجموعة هي كيان رقمي له هوية وقواعد وظهور. يعد ويب هوك [`group.v2.update`] الإشارة الأساسية لتغير البيانات الوصفية أو تكوين مساحة العمل المشتركة. سواء تم تغيير الاسم لمرحلة مشروع جديدة أو \"قفل\" المراسلة، يزودك هذا الحدث بالبيانات اللازمة للحفاظ على **\"دليل مرآة\" (Mirror Directory)** دقيق لمحادثاتك المؤسسية.\n\n---\n\n## 🏗️ الفلسفة المعمارية: مرآة البيانات الوصفية\n\n*   **استراتيجية دليل المرآة**: لا يوفر واتساب مزامنة مسبقة لإعدادات المجموعة حتى يحدث تغيير. لذلك، يجب أن تحافظ بنيتك على قاعدة بيانات تحاكي كل مجموعة نشطة. عند استلام هذا الويب هوك، قم بإجراء عملية \"تحديث أو إدراج\" (Upsert) للحفاظ على تزامن نظامك مع الواقع.\n*   **ذرية الحقول**: تحدد الحمولة بدقة ما تغير — سواء كان العنوان ([`subject`])، الوصف ([`description`])، أو وضع التقييد ([`restrictMode`]).\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. حماية العلامة التجارية والاسم\nإذا قام مستخدم غير مصرح له بتغيير اسم المجموعة لشيء غير لائق، يمكن لنظامك اكتشاف ذلك فوراً واستدعاء واجهة [تحديث الاسم](/v2/groups/update) لإعادته للاسم الرسمي، مما يضمن احترافية العلامة 24/7.\n### 2. المزامنة مع أنظمة إدارة المشاريع\nغالباً ما يُستخدم حقل \"الوصف\" لوضع #قواعد أو روابط أو معرفات مشاريع. من خلال تحليل الوصف في كل تحديث، يمكن لنظامك تلقائياً ربط مجموعة واتساب بالمدخل المقابل في برنامج إدارة المشاريع الخاص بك (مثل Jira أو Trello).\n### 3. التكيف مع \"وضع الإعلانات\"\nعند استلام تحديث يفيد بتفعيل [`announceMode`] (قصر الرسائل على المسؤولين)، يجب أن ينتقل البوت لـ \"وضع البث\" ويتوقف عن معالجة رسائل المستخدمين العادية، وربما يرسل ملخصاً لما فاتهم أثناء فترة القفل.\n\n---\n\n## 🛡️ التفويض الإداري والتحقق الهندسي\nننصح بالاحتفاظ بـ \"سجل تاريخ الإعدادات\" لكل مجموعة لأغراض الامتثال (مثل SOC2)، مما يسمح بمدقق الحسابات برؤية متى ومن قام بتغيير هوية المجموعة. كما يجب مراعاة تزامن الحالات (State Sync) وتجنب \"تذبذب التحديثات\" في حالات تأخر الشبكة عن طريق مقارنة الطوابع الزمنية الصارمة.\n            "
        }
      }
    },
    {
      "path": "/group.v2.participants",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Group Participants Change",
      "description": "Triggered when participants are promoted to admin or demoted.",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "warning",
          "title": "Admin Rights",
          "content": "Be aware of admin status changes if your bot depends on admin permissions to execute certain commands."
        }
      ],
      "recommendations": [
        "Update the 'isAdmin' status for participants in your database.",
        "Trigger specific administrative workflows when new admins are appointed."
      ],
      "extraInfo": "\n# Participant Role Changes\n\nThis event tracks promotions and demotions within a group.\n\n### Fields\n*   **action**: Either `promote` or `demote`.\n*   **participants**: Array of WhatsApp IDs whose roles were changed.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01...",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "group.v2.participants",
            "payload": {
              "chatId": "1234567890@g.us",
              "action": "promote",
              "participants": [
                "11111111111@c.us"
              ]
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123@lid",
              "pushName": "Instance"
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "تغيير رتب المشاركين في المجموعة",
          "description": "يتم تفعيله عند ترقية أحد المشاركين إلى مسؤول (Admin) أو تنزيل رتبته.",
          "extraInfo": "\n# تغيير أدوار المشاركين: تتبع ديناميكيات السلطة\n\nيعد ويب هوك [`group.v2.participants`] الأداة الأساسية لمراقبة توزيع الصلاحيات داخل المجموعة. ففي بيئات العمل، يعني تغيير الرتبة تحولاً في الأهلية لإدارة المحادثة، ويجب أن يكون نظامك على علم تام بهذا التحول لحظة وقوعه.\n\n---\n\n## 🏗️ الفلسفة المعمارية: تحديث مصفوفة الصلاحيات\n\n*   **مراقبة الأهلية**: إذا كان البوت يرفض الأوامر من غير المسؤولين، فإن هذا الويب هوك يضمن تحديث \"قائمة المسموح لهم\" فوراً.\n*   **الأمان الهيكلي**: تتبع من يقوم بالترقية. إذا قام مستخدم غير مصرح له بترقية نفسه (عبر ثغرة أو خطأ بشري)، يمكن للنظام اكتشاف ذلك عبر هذا الويب هوك واتخاذ إجراء تصحيحي فوري.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي\n\n### 1. تدوير السلطة الإدارية\nعند ترقية مشارك جديد إلى مسؤول، يمكن للنظام إرسال \"دليل المسؤول\" له تلقائياً عبر رسالة خاصة، يشرح له فيها كيفية استخدام أوامر البوت المتقدمة وإدارة المجموعة بكفاءة.\n### 2. المصالحة مع أنظمة الموارد البشرية (HR)\nربط رتبة المستخدم في واتساب بمركزه الوظيفي في الشركة. إذا تمت ترقية موظف في CRM الخاص بك، يمكن للنظام التأكد من ترقيته في مجموعات العمل المرتبطة عبر هذا الويب هوك.\n            "
        }
      }
    },
    {
      "path": "/presence.update",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Presence Updated",
      "description": "Triggered when a contact starts typing, recording audio, or changes their online status.",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "Online Privacy",
          "content": "Note that many users have 'Last Seen' and 'Online' status disabled in their privacy settings."
        }
      ],
      "recommendations": [
        "Use 'composing' (typing) status to show live indicators in your dashboard.",
        "Don't rely on this for uptime monitoring as it only shows activity for specific chats."
      ],
      "extraInfo": "\n# The Digital Pulse: Mastering Presence and Activity Webhooks\n\nIn the architecture of a high-performance messaging system, text is only half of the conversation. The other half is **Presence**—the subtle, high-frequency signals that indicate when a human is looking at their screen, composing a thought, or recording a voice note. The [`presence.update`] webhook is the \"Social Sensor\" of the Wawp platform. It provides your infrastructure with real-time insight into the intentions of your contacts before they ever press the \"Send\" button.\n\nThis guide provides an architectural deep-dive into the strategic value of presence monitoring, moving beyond \"Activity Tracking\" into the realm of **Social Intelligence and Conversational Flow Management**.\n\n---\n\n## 🏗️ Architectural Philosophy: The Social Contract of Availability\n\nTo master the Presence API, one must recognize the psychological weight of the \"Typing...\" indicator. It represents active focus. Within Wawp, presence is usually scoped to an **Individual JID** (`@c.us`) within a specific chat context.\n\n### 1. The Hierarchy of Activity\nThe presence event captures the progression of human-device interaction:\n*   **Composing (Typing)**: The user is actively entering text into the input field. This is the strongest signal of \"Pending Input.\"\n*   **Recording**: The user is holding the microphone button to record a voice note. This provides a \"Media Warning\"—your system should expect an audio payload shortly.\n*   **Paused**: The user has stopped typing but still has the chat window open. This is a state of \"Deliberation\" or \"Interruption.\"\n*   **Available / Unavailable**: The global \"Online\" or \"Last Seen\" status. (Note: These are only available if the user's privacy settings allow it).\n\n### 2. The Relationship Between Presence and Priority\nA presence event is a **Temporary State Mutation**. Unlike a message, which is a permanent record, presence is a fleeting signal. Your architecture should treat these events as \"Volatile Data.\" They are primarily used to update a Live UI or to pause bot logic, rather than being archived in a long-term data warehouse.\n\n---\n\n## 🚀 Strategic Use Cases: Powering Socially Intelligent Bots\n\nPresence and activity signals transform a static bot into a \"Conversational Orchestrator\" that respects human rhythms.\n\n### 1. The \"Respectful AI\" Bot (Collision Avoidance)\nOne of the most frustrating user experiences is when a bot sends a long answer *while the user is still typing* their next question. \n**The Strategic Workflow**: When your bot generates a response, it first checks the current \"Activity State\" of the [`chatId`]. If a [`presence.update`] event of type `composing` has arrived in the last 10 seconds, the bot **pauses its output**. It waits for the user to finish typing and send their message before delivering its own answer. This creates a \"Natural Turn-Taking\" flow that mimics human conversation.\n\n### 2. Real-Time Dashboard Synchronicity\nFor human-led support teams, the presence webhook is the engine of the \"Agent Awareness\" feature. When an agent sees \"Customer is typing...\" on their dashboard, they know to wait rather than asking \"Are you there?\". This simple visual cue reduces redundant messages, lowers agent fatigue, and gives the customer the space they need to compose complex queries.\n\n### 3. Presence as a \"Sentiment Warm-up\"\nTrack the \"Time-to-Reply\" starting from the first `composing` event rather than the final `message` timestamp. A user who types for 3 minutes for a 2-word message is likely frustrated or struggling with your interface. Your system can detect this prolonged \"Composing State\" and proactively suggest human assistance before the user even finishes their message.\n\n---\n\n## 🛡️ Administrative Mandate: Balancing Intelligence and Privacy\n\n### 1. The \"Subscribed vs. Unsubscribed\" State\nPresence updates on WhatsApp are typically **Contextual**. You receive typing indicators for users you are currently interacting with. For global \"Online\" status, you may need to call the [`/presence/subscribe`](/presence) endpoint. \n**The Strategic Rule**: Only subscribe to presence for \"Active Leads\" or \"High-Priority Support Tickets.\" Maintaining 10,000 active presence subscriptions simultaneously is an architectural anti-pattern that can lead to backend throttling and unnecessary bandwidth costs.\n\n### 2. Respecting the \"Invisible\" User\nPrivacy is a core pillar of the WhatsApp ecosystem. If a user has disabled \"Read Receipts\" or \"Online Status,\" your system will not receive these webhooks. A premium architecture must fail gracefully. If presence data is missing, your system should default to \"Passive Mode\"—treating every message as if it were sent without warning. Never attempt to \"Infer\" presence via invasive polling, as this can lead to account flags or user complaints.\n\n---\n\n## 🛡️ Operational Best Practices: Handling the High-Frequency Signal\n\n*   **The \"Debounce\" Strategy**: Presence updates can fire every few seconds. Do not trigger a database write for every \"User is typing\" packet. Instead, use an **In-Memory Cache (like Redis)** to store the \"Current State\" of a chat. Only push an update to your frontend UI if the state *actually changes* (e.g., from `paused` to `composing`).\n*   **Visual State Lifespan**: Typing indicators should have a \"Time-to-Live\" (TTL) on your dashboard. If you don't receive a fresh [`presence.update`] within 15 seconds, your UI should automatically hide the \"Typing...\" indicator. This prevents a \"Stuck UI\" if a user closes their app without the `paused` event firing correctly.\n*   **Presence in Groups (@g.us)**: In a group context, you will receive presence updates for multiple different [`from`] JIDs simultaneously. Your system must correctly map these activities to the specific user's avatar within the group UI, allowing agents to see exactly which participant is currently responding.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Low-Latency Ingestion**: Unlike a message, a presence signal loses 90% of its value if it is delayed by more than 2 seconds. Ensure your presence webhook handler is hosted on a high-availability, low-latency node.\n2.  **Verify Event Ordering**: Use the [`timestamp`] in the event metadata to ensure you aren't processing an old \"Typing\" packet after a newer \"Paused\" packet.\n3.  **Coordinate with \"Start Typing\"**: If your bot is about to reply, call the [`/v2/send/start-typing`](/v2/send/start-typing) endpoint yourself. This closes the \"Symmetry Loop\"—the user sees that the bot is \"Thinking,\" and the bot sees that the user is \"Waiting.\"\n\n## 🎯 Conclusion: Beyond Text—The Reactive Pulse of Engagement\n\nThe **Presence Update Webhook** is the \"Peripheral Vision\" of your WhatsApp integration. By building an architecture that listens to these subtle, high-frequency signals, you move your business from \"Reading Logs\" to **Understanding Human Momentum**. You build systems that respect silence, wait for input, and provide reassurance through live visual feedback. In the world of Wawp, presence is the signal that turns a cold interaction into a living, breathing conversation.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01...",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "presence.update",
            "payload": {
              "chatId": "11111111111@c.us",
              "type": "composing",
              "from": "11111111111@c.us"
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123@lid",
              "pushName": "Instance"
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "تحديث التواجد",
          "description": "يتم تفعيله عندما يبدأ جهة اتصال في الكتابة، أو تسجيل صوت، أو تغيير حالة اتصاله بالإنترنت.",
          "tips": [
            {
              "title": "حدود معدل API",
              "content": "احترم حدود معدل API لتجنب الحظر المؤقت."
            },
            {
              "title": "العمليات غير المتزامنة",
              "content": "معظم العمليات غير متزامنة. استخدم Webhooks للتحديثات في الوقت الفعلي."
            }
          ],
          "recommendations": [
            "استخدم متغيرات البيئة لبيانات الاعتماد الحساسة مثل رموز الوصول.",
            "قم بتنفيذ معالجة قوية للأخطاء ومنطق إعادة المحاولة."
          ],
          "extraInfo": "\n# النبض الرقمي: إتقان ويب هوك التواجد والنشاط\n\nفي هندسة نظام مراسلة عالي الأداء، النص هو نصف المحادثة فقط. النصف الآخر هو **التواجد** — الإشارات الدقيقة عالية التردد التي تشير إلى متى ينظر الإنسان إلى شاشته، أو يصيغ فكرة، أو يسجل ملاحظة صوتية. ويب هوك `presence.update` هو \"المستشعر الاجتماعي\" لمنصة Wawp.\n\n---\n\n## 🏗️ الفلسفة الهندسية: العقد الاجتماعي للتوفر\n\nلإتقان واجهة برمجة تطبيقات التواجد، يجب إدراك الوزن النفسي لمؤشر \"يكتب...\". إنه يمثل التركيز النشط.\n\n### 1. تسلسل هرمي للنشاط\nيلتقط حدث التواجد تطور التفاعل بين الإنسان والجهاز:\n*   **Composing (الكتابة)**: المستخدم يدخل النص حالياً. هذه أقوى إشارة لـ \"إدخال معلق\".\n*   **Recording (التسجيل)**: المستخدم يضغط على زر الميكروفون لتسجيل ملاحظة صوتية. يوفر هذا \"تحذيراً للميديا\" — يجب أن يتوقع نظامك حمولة صوتية قريباً.\n*   **Paused (متوقف مؤقتاً)**: توقف المستخدم عن الكتابة ولكن نافذة الدردشة لا تزال مفتوحة.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي: تمكين البوتات الذكية اجتماعياً\n\n### 1. بوت \"الذكاء الاصطناعي المحترم\" (تجنب الاصطدام)\nمن أكثر تجارب المستخدم إحباطاً أن يرسل البوت إجابة طويلة *بينما لا يزال المستخدم يكتب* سؤاله التالي.\n**سير العمل الاستراتيجي**: عندما يولد البوت رداً، فإنه يتحقق أولاً من \"حالة النشاط\" لمعرف الدردشة. إذا وصل حدث `composing` في آخر 10 ثوانٍ، فإن البوت **يوقف مخرجاته مؤقتاً**. ينتظر المستخدم حتى ينتهي من الكتابة ويرسل رسالته قبل تقديم إجابته الخاصة. هذا يخلق تدفقاً يحاكي المحادثة البشرية الطبيعية.\n\n### 2. مزامنة لوحة التحكم في الوقت الفعلي\nبالنسبة لفرق الدعم التي يقودها البشر، ويب هوك التواجد هو محرك ميزة \"وعي الوكيل\". عندما يرى الوكيل \"العميل يكتب...\" على لوحة التحكم، فإنه يعرف أن عليه الانتظار بدلاً من السؤال \"هل أنت هناك؟\".\n\n---\n\n## 🛡️ أفضل الممارسات التشغيلية\n\n*   **استراتيجية \"Debounce\"**: يمكن أن تنطلق تحديثات التواجد كل بضع ثوانٍ. لا تقم بتشغيل كتابة في قاعدة البيانات لكل حزمة \"المستخدم يكتب\". بدلاً من ذلك، استخدم **ذاكرة تخزين مؤقت (مثل Redis)** لتخزين \"الحالة الحالية\" للدردشة.\n*   **عمر الحالة البصرية**: يجب أن يكون لمؤشرات الكتابة \"وقت للعيش\" (TTL) على لوحة التحكم الخاصة بك. إذا لم تتلقَ تحديثاً جديداً خلال 15 ثانية، فقم بإخفاء مؤشر \"يكتب...\" تلقائياً.\n            "
        }
      }
    },
    {
      "path": "/poll.vote.failed",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Poll Vote Failed",
      "description": "Triggered if a vote on a poll fails to process correctly.",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "warning",
          "title": "Error Handling",
          "content": "Use this to notify admins if a voting session is being interrupted by technical errors."
        }
      ],
      "recommendations": [
        "Log the reason code for debugging purposes.",
        "Check if the poll message ID still exists."
      ],
      "extraInfo": "\n# Poll Voting Errors\n\nOccurs when a user attempts to vote but the WhatsApp engine or server cannot register it.\n\n### Common Reasons\n*   **Stale Message**: The poll has been deleted or expired.\n*   **Network Timeout**: Connection issues preventing synchronization.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01...",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "poll.vote.failed",
            "payload": {
              "pollId": "true_11111111111@c.us_...",
              "voter": "11111111111@c.us",
              "reason": "MSG_NOT_FOUND"
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123@lid",
              "pushName": "Instance"
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "فشل التصويت في الاستطلاع",
          "description": "يتم تفعيله إذا فشلت معالجة عملية التصويت في الاستطلاع بشكل صحيح.",
          "extraInfo": "\n# أخطاء التصويت في الاستطلاعات\n\nيحدث عندما يحاول مستخدم التصويت ولكن لا يتمكن محرك واتساب من تسجيله. الأسباب الشائعة تشمل:\n*   **رسالة قديمة**: تم حذف الاستطلاع أو انتهت صلاحيته.\n*   **مهلة الشبكة**: مشاكل في الاتصال تمنع المزامنة.\n            ",
          "tips": [
            {
              "title": "وقت الاستجابة",
              "content": "أرجع حالة HTTP 200 OK فورًا لتأكيد الاستلام."
            },
            {
              "title": "التكرار",
              "content": "تعامل مع أحداث الويب هوك المكررة بشكل مناسب."
            }
          ],
          "recommendations": [
            "تحقق من توقيعات الويب هوك لضمان الأمان.",
            "قم بمعالجة المنطق الثقيل بشكل غير متزامن بعد تأكيد الويب هوك.",
            "سجل الحمولات لأغراض التصحيح."
          ]
        }
      }
    },
    {
      "path": "/chat.archive",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Chat Archived/Unarchived",
      "description": "Triggered when a chat's archive status changes.",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "Folder Logic",
          "content": "Use this to organize chats in your custom dashboard similar to the official WhatsApp app."
        }
      ],
      "recommendations": [
        "Store the 'archived' boolean to filter chats in your list view.",
        "Ensure sync between mobile app movements and your custom CRM."
      ],
      "extraInfo": "\n# Archive Management\n\nFired whenever you or a sync action moves a chat into/out of the archived folder.\n\n### Key Fields\n*   **chatId**: The individual or group ID.\n*   **archived**: `true` if moved to archive, `false` if moved back to active.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01...",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "chat.archive",
            "payload": {
              "chatId": "11111111111@c.us",
              "archived": true
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123@lid",
              "pushName": "Instance"
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "أرشفة الدردشة",
          "description": "يتم تفعيله عند تغير حالة أرشفة الدردشة.",
          "extraInfo": "\n# إدارة الأرشفة\n\nيتم تفعيله كلما قام المستخدم أو إجراء مزامنة بنقل دردشة إلى مجلد الأرشيف أو إخراجه منه. يساعدك في تنظيم الدردشات في لوحة التحكم الخاصة بك بشكل يماثل تطبيق واتساب الرسمي.\n            ",
          "tips": [
            {
              "title": "وقت الاستجابة",
              "content": "أرجع حالة HTTP 200 OK فورًا لتأكيد الاستلام."
            },
            {
              "title": "التكرار",
              "content": "تعامل مع أحداث الويب هوك المكررة بشكل مناسب."
            }
          ],
          "recommendations": [
            "تحقق من توقيعات الويب هوك لضمان الأمان.",
            "قم بمعالجة المنطق الثقيل بشكل غير متزامن بعد تأكيد الويب هوك.",
            "سجل الحمولات لأغراض التصحيح."
          ]
        }
      }
    },
    {
      "path": "/call.received",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Call Received",
      "description": "Triggered when an incoming Voice or Video call is detected.",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "warning",
          "title": "Calling Limitation",
          "content": "Wawp currently does not support ANSWERING calls via API. This is for NOTIFICATION purposes only."
        }
      ],
      "recommendations": [
        "Create a 'Missed Call' notification for your agents.",
        "Detect if users are calling so your bot can tell them to send a text message instead."
      ],
      "extraInfo": "\n# The Voice-to-Text Bridge: Mastering Call Received Webhooks\n\nIn a digital-first support ecosystem, the incoming call is often a signal of high urgency or user frustration. While the Wawp platform is primarily an asynchronous messaging engine and does not support the ingestion of raw VoIP audio streams, the [`call.received`] webhook is a critical diagnostic and operational event. It allows your infrastructure to \"Hear\" the incoming ringing state, providing your system with the metadata required to bridge the gap between a voice request and a text-based resolution.\n\nThis guide provides an architectural deep-dive into the strategic value of call monitoring, moving beyond \"Notification\" into the realm of **Automated Redirection and High-Urgency Triage**.\n\n---\n\n## 🏗️ Architectural Philosophy: The Call as an Escalation Signal\n\nTo master the Call Received API, one must recognize that a WhatsApp call (identified by the [`from`] JID, usually `@c.us`) is a \"Request for Synchronous Interaction.\" In the context of a bot-led flow, this is often a signal that the user is finding the text-based menu insufficient for their current needs.\n\n### 1. The Metadata of the Attempt\nThe [`call.received`] event provides the core identifiers of the interaction:\n*   **The Identity (from)**: The [`@c.us`] JID of the caller. This allows for instant CRM lookup.\n*   **The Vector (isVideo)**: Distinguishing between an Audio and Video call. A video call attempt often indicates a desire to \"Show\" a problem (e.g., a broken product) rather than just \"Tell\" it.\n*   **The Session (me)**: Which of your many WhatsApp instances is receiving the call.\n\n### 2. The Operational Boundary\nIt is architecturally vital to communicate to your stakeholders that Wawp acts as a **Sensor, not a Receiver**. Your system cannot \"Answer\" the call or \"Record\" the audio. Instead, your system should treat the call event as a **Trigger for an Automated Fallback Workflow**.\n\n---\n\n## 🚀 Strategic Use Cases: Powering Automated Call Failovers\n\nCall monitoring allows you to build a sophisticated \"Safety Net\" that ensures no customer is left in the \"Ringing\" void.\n\n### 1. The \"Call-to-Chat\" Redirection Strategy\nThe most powerful use of this webhook is the **Instant Redirect**. \n**The Strategic Workflow**: As soon as the [`call.received`] event fires, your bot can immediately send a private message to the caller: *\"Hi there! We saw you trying to call. We currently only offer support via chat to ensure we can handle all requests efficiently. How can I help you today?\"* \n**Strategic Value**: This moves the user from a frustrated \"No Answer\" state to an active \"Chat Ingestion\" state within seconds. It manages expectations and keeps the conversation within your manageable support pipeline.\n\n### 2. High-Urgency Agent Alerting\nFor premium or VIP accounts, an incoming call should bypass the standard bot and trigger an internal alert for a human agent. \n**The Logic**: When the webhook fires for a VIP JID, your system can trigger a desktop notification or a Slack alert: *\"VIP Customer [Name] is currently calling the WhatsApp line! Please reach out to them via chat immediately.\"* Even if the agent doesn't answer the call (which they can't via API), they can initiate a proactive chat while the user still has their phone in their hand.\n\n### 3. Calculating the \"Frustration Quotient\"\nBy logging the frequency of incoming calls for a specific [`chatId`], you can calculate an \"Engagement Stress\" metric. A user who calls 5 times in 10 minutes is in a high-stress state. Your system can detect this pattern and automatically escalate the next text message from that user to a \"Priority 1\" status, ensuring they receive the fastest possible human response.\n\n---\n\n## 🛡️ Administrative Mandate: Scaling the Notification Layer\n\n### 1. The \"Ghost Call\" and Bot Loops\nAvoid sending a \"Why are you calling?\" message for every single ring event. WhatsApp sometimes emits multiple events for a single long-ringing session. \n**The Strategy**: Implement a **Call Debounce**. If you receive a call event for User A, do not trigger your \"Redirect Bot\" again for the same user within the next 2 minutes. This prevented your system from spamming the user with multiple redirect messages for a single call attempt.\n\n### 2. Respecting the \"No-Voice\" Perimeter\nClearly state in your business profile and your \"Welcome\" messages that you do not support voice calls. Use the [`call.received`] webhook only as a **Secondary Defense**. The primary defense is setting the right expectations in your text-based UI. If a user calls despite the warnings, your system should respond with firm but polite redirection logic.\n\n---\n\n## 🛡️ Operational Best Practices: Designing for Missed Connections\n\n*   **Differentiating Between Ringing and Missed**: Ensure you coordinate this event with the [Call Rejected](/v2/webhooks/call-rejected) event. A [`call.received`] without a rejection often means the call timed out. You should treat \"Missed Calls\" differently than \"Rejected Calls\" in your CRM logging.\n*   **Syncing with Physical Devices**: If you have a physical phone linked to the Wawp instance, that phone *will* ring. This webhook allows your digital backend to \"Know\" what the human holding that phone is seeing, enabling a unified view of the customer across digital and physical touchpoints.\n*   **VCard and Identity Correlation**: If the caller is not in your CRM, use the [`from`] JID to initiate a [Contact Lookup](/v2/contacts/about). You can often retrieve the user's \"Push Name\" or \"About\" info even if they just called for the first time, allowing your \"Redirect Message\" to be personalized (e.g., \"Hi John, we saw you calling...\").\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Low-Latency Routing**: Call events are time-sensitive. If your redirect message arrives 5 minutes after the call ended, it looks unprofessional. Your handler should aim for sub-500ms processing.\n2.  **Verify the Session Scope**: In a multi-instance environment, ensure the [`session`] ID is used to filter the redirection logic. You don't want Instance A sending a \"We don't support calls\" message to a user who called Instance B.\n3.  **Coordinate with Revocations**: Calls do not have \"Revocations\" in the same way messages do, but they do have \"Timeouts.\" Your system should automatically clear any \"Active Call\" flag in your dashboard after 60 seconds if no further status is received.\n\n## 🎯 Conclusion: Turning Silence into Conversation\n\nThe **Call Received Webhook** is the \"Emergency Beacon\" of your integration. By building an architecture that listens to voice attempts and converts them into chat opportunities, you move your organization from \"Missing Connections\" to **Intelligent Redirection**. You build systems that catch every signal, manage every frustration, and bridge every channel gap with engineered precision. In the world of Wawp, a call is not an impossibility; it is a high-priority invitation to a better conversation.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01...",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "call.received",
            "payload": {
              "id": "call_12345",
              "from": "11111111111@c.us",
              "isVideo": false
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123@lid",
              "pushName": "Instance"
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "استلام مكالمة",
          "description": "يتم تفعيله عند اكتشاف مكالمة صوتية أو مرئية واردة.",
          "tips": [
            {
              "title": "حدود معدل API",
              "content": "احترم حدود معدل API لتجنب الحظر المؤقت."
            },
            {
              "title": "العمليات غير المتزامنة",
              "content": "معظم العمليات غير متزامنة. استخدم Webhooks للتحديثات في الوقت الفعلي."
            }
          ],
          "recommendations": [
            "استخدم متغيرات البيئة لبيانات الاعتماد الحساسة مثل رموز الوصول.",
            "قم بتنفيذ معالجة قوية للأخطاء ومنطق إعادة المحاولة."
          ],
          "extraInfo": "\n# جسر \"الصوت إلى نص\": إتقان ويب هوك استلام المكالمات\n\nفي منظومة الدعم الرقمي، غالباً ما تكون المكالمة الواردة إشارة إلى حالة طوارئ عالية أو إحباط لدى المستخدم. وعلى الرغم من أن منصة Wawp لا تدعم استقبال تدفقات الصوت (VoIP) مباشرة، إلا أن ويب هوك [`call.received`] يعد حدثاً تشغيلياً حيوياً؛ فهو يسمح لبنيتك التحتية بـ \"سماع\" حالة الرنين وتزويد نظامك بالبيانات الوصفية اللازمة لسد الفجوة بين الطلب الصوتي والحل القائم على النص.\n\n---\n\n## 🏗️ الفلسفة المعمارية: المكالمة كإشارة تصعيد\n\nيجب إدراك أن مكالمة واتساب هي \"طلب للتفاعل المتزامن\". في سياق سير العمل الذي يقوده البوت، يعد هذا غالباً إشارة إلى أن المستخدم يجد القوائم النصية غير كافية لاحتياجاته الحالية.\n\n### 1. البيانات الوصفية للمحاولة\nيوفر حدث [`call.received`] الهوية الأساسية للتفاعل:\n*   **الهوية (from)**: معرف واتساب للمتصل، مما يتيح البحث الفوري في الـ CRM.\n*   **النوع (isVideo)**: التمييز بين المكالمة الصوتية والمرئية. محاولة الاتصال المرئي تشير غالباً إلى رغبة في \"عرض\" المشكلة (منتج مكسور مثلاً) بدلاً من مجرد \"شرحها\".\n\n### 2. الحدود التشغيلية\nمن الضروري معمارياً معاملة Wawp كـ **حساس (Sensor) وليس كمستقبل (Receiver)**. لا يمكن لنظامك \"الرد\" على المكالمة، وبدلاً من ذلك، يجب معاملة الحدث كـ **محفز لسير عمل احتياطي مؤتمت**.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي: التحويل التلقائي للمكالمات\n\n### 1. استراتيجية إعادة التوجيه الفوري\nبمجرد انطلاق حدث [`call.received`]، يمكن للبوت إرسال رسالة خاصة للمتصل فوراً: *\"أهلاً بك! رأينا محاولتك للاتصال. نحن نقدم الدعم حالياً عبر الدردشة فقط لضمان التعامل مع جميع الطلبات بكفاءة. كيف يمكنني مساعدتك اليوم؟\"*. هذا ينقل المستخدم من حالة \"عدم الرد\" المحبطة إلى حالة \"الدردشة النشطة\" في ثوانٍ.\n\n### 2. تنبيه الوكلاء للحالات الطارئة\nبالنسبة للحسابات المميزة (VIP)، يجب أن يتجاوز الاتصال الوارد البوت القياسي ويحفز تنبيهاً داخلياً لوكيل بشري: *\"العميل [الاسم] يتصل حالياً عبر واتساب! يرجى التواصل معه عبر الدردشة فوراً\"*. حتى لو لم يرد الوكيل على المكالمة (وهو ما لا يمكنه فعله عبر الواجهة)، يمكنه بدء دردشة استباقية بينما لا يزال المستخدم يمسك بهاتفه.\n\n---\n\n## 🛡️ أفضل الممارسات التشغيلية والهندسية\n*   **تجنب رسائل التكرار**: طبق قاعدة \"Call Debounce\"؛ فإذا أرسلت رسالة إعادة توجيه لمستخدم، فلا ترسلها مرة أخرى لنفس المستخدم خلال دقيقتين حتى لو تكرر الرنين.\n*   **المزامنة مع الأجهزة المادية**: إذا كان لديك هاتف مادي مرتبط بالمثيل، فسوف يرن ذلك الهاتف. يتيح لك هذا الويب هوك معرفة ما يراه الشخص الذي يمسك بالهاتف، مما يوفر رؤية موحدة للعميل.\n*   **المعالجة منخفضة التأخير**: تهدف معالجة هذا الويب هوك لإرسال رسالة إعادة التوجيه في أقل من 500 ملّي ثانية لتبقى ذات صلة بسياق المتصل.\n            "
        }
      }
    },
    {
      "path": "/call.accepted",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Call Accepted",
      "description": "Triggered when a received call is picked up on another device.",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "Multi-device Sync",
          "content": "Shows the status shift when you answer the call using your physical phone."
        }
      ],
      "recommendations": [
        "Update the call status in your logs to 'In Progress'."
      ],
      "extraInfo": "\n# Call Acceptance\n\nFired when a call lifecycle moves from `ringing` to `active`.\n\n### Fields\n*   **id**: Match this with the ID from `call.received`.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01...",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "call.accepted",
            "payload": {
              "id": "call_12345"
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123@lid",
              "pushName": "Instance"
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "قبول المكالمة",
          "description": "يتم تفعيله عند الرد على مكالمة واردة من جهاز آخر.",
          "extraInfo": "\n# قبول المكالمة: مزامنة الحالة عبر الأجهزة\n\nيعد ويب هوك [`call.accepted`] إشارة حيوية لمزامنة الحالة في البيئات متعددة الأجهزة. فعندما يتم الرد على المكالمة باستخدام الهاتف المادي المرتبط بالحساب، يتم إرسال هذا التنبيه إلى نظامك الرقمي لإبلاغه بأن دورة حياة المكالمة قد انتقلت من حالة \"الرنين\" إلى الحالة \"النشطة\".\n\n---\n\n## 🏗️ الفلسفة المعمارية: مزامنة الواقع المادي والرقمي\n\n*   **تحديث السجلات**: استخدم هذا الحدث لتحديث حالة المكالمة في قاعدة بياناتك إلى \"قيد التنفيذ\". يضمن ذلك أن لوحة تحكم الوكيل تعكس الحقيقة الميدانية لما يحدث على الهاتف.\n*   **إدارة التوافر**: بمجرد قبول المكالمة، يجب أن يعتبر النظام الوكيل \"مشغولاً\" برمجياً، مما قد يعطل إرسال تنبيهات المكالمات الأخرى إليه مؤقتاً.\n            "
        }
      }
    },
    {
      "path": "/call.rejected",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Call Rejected",
      "description": "Triggered when an incoming call is declined.",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "Sync Status",
          "content": "Useful for accurate logging of missed or ignored calls."
        }
      ],
      "recommendations": [
        "Mark the call as 'Declined' in your communication history database."
      ],
      "extraInfo": "\n# Closing the Voice Loop: Mastering Call Rejected Webhooks\n\nIn the ecosystem of digital communication, the termination of an interaction is as significant as its initiation. The [`call.rejected`] webhook is the definitive \"End of Signal\" event for a voice or video attempt within the Wawp platform. Whether a call is manually declined by a human operator using a physical device or automatically terminated due to system policy, this event provides your infrastructure with the closure required to maintain an accurate, real-time audit trail of customer engagement.\n\nThis guide provides an architectural deep-dive into the strategic value of call termination monitoring, moving beyond \"Status Logging\" into the realm of **Operational Accountability and Customer Experience Synchronization**.\n\n---\n\n## 🏗️ Architectural Philosophy: The Call as a Finite Session\n\nA WhatsApp call is a synchronous state that consumes resources and attention. The [`call.rejected`] event serves as the \"Garbage Collector\" for your communication logic.\n\n### 1. The Termination Vector\nA rejection event can occur due to several distinct triggers, and a premium architecture must account for all of them:\n*   **Manual Decline**: A human agent taps \"Decline\" on the physical phone or WhatsApp Web.\n*   **Automated Policy**: Your backend logic or a third-party app terminates the call.\n*   **User Cancellation**: The caller hangs up before the call is answered (though this sometimes results in a \"Missed\" state, Wawp often emits the rejection signal to clear the socket).\n\n### 2. Identifying the Call Session\nThe only field in the payload is the [`id`] of the call. This is by design. The Call ID is the **Primary Key** that connects the [`call.received`] event with the [`call.rejected`] event. Your system must use this ID to \"Reconcile\" the interaction, moving the call record in your database from `RINGING` to `TERMINATED`.\n\n---\n\n## 🚀 Strategic Use Cases: Powering Accountable Support Flows\n\nCall rejection monitoring allows you to measure the \"Response Gap\" and automate the next step in the customer journey.\n\n### 1. The \"Immediate Proactive Chat\" Strategy\nIf a call is rejected, the user is likely at their phone *right now*. This is the perfect moment for a text-based follow-up.\n**The Strategic Workflow**: As soon as [`call.rejected`] is received, your system checks if it was preceded by a [`call.received`] event. If so, it instantly sends a message: *\"Sorry we couldn't take your call right now! We're currently assisting other customers via chat. How can we help you here?\"* \n**Strategic Value**: This turns a \"Negative Interaction\" (a rejected call) into a \"Positive Engagement\" (a proactive chat). It demonstrates that your brand is aware, responsive, and ready to assist through alternate channels.\n\n### 2. Agent Performance and Accountability Mining\nIn a support center where agents have physical phones, the rejection rate is a key performance indicator (KPI). \n**The Logic**: By correlating the [`call.rejected`] event with the agent assigned to that WhatsApp instance, you can identify patterns of avoided interactions. If an instance consistently rejects 80% of incoming calls during business hours, it indicates a training or staffing issue. This data allows for **Evidence-Based Management**, moving away from \"Feelings\" about agent performance toward hard, technical proof of interaction avoidance.\n\n### 3. CRM History and \"Audit of Intent\"\nA complete CRM record should not just show messages; it should show every attempt at contact. \n**The Data Pattern**: When the rejection webhook fires, update the user's timeline with a specialized \"Missed/Rejected Call\" entry. This gives the next agent to handle the customer a full view of the context: *\"Customer tried to call 3 times this morning and was declined each time.\"* This allows the agent to apologize for the missed connection, significantly improving the \"Personalization Score\" of the next interaction.\n\n---\n\n## 🛡️ Administrative Mandate: Balancing Physical and Digital Reality\n\n### 1. The \"Physical Sync\" Problem\nWhen you use Wawp, you are often using a real WhatsApp account that exists on a physical smartphone. If a human picks up that phone and hits \"Decline,\" the Wawp API receives the [`call.rejected`] webhook. \n**The Strategic Insight**: This webhook is your backend's only way of knowing what the physical human operator did. Use it to keep your digital dashboard \"In Sync\" with the physical reality of the office. If the phone user is declining calls, your digital bot should probably \"Sleep\" for a few minutes to avoid conflicting with the human's manual workflow.\n\n### 2. Guarding against \"Zombie Calls\"\nWithout a rejection signal, your custom dashboard might show a \"Call in Progress\" banner forever if the network drops during the ringing phase. \n**The Strategy**: Use the [`call.rejected`] event as a **Global Clear Command**. When this event fires, it should forcibly remove any \"Active Call\" UI elements for that specific [`session`], ensuring your agents always have an accurate view of the instance's state.\n\n---\n\n## 🛡️ Operational Best Practices: Designing for Professional Closure\n\n*   **Handling the \"Busy\" Signal**: If your system rejects a call because the agent is already in a chat, use the [`call.rejected`] event to trigger a \"Wait\" message. This explains *why* the call was declined, preventing the user from feeling ignored.\n*   **Coordinate with Call Received**: Always index your calls by ID. If you receive a [`call.rejected`] for an ID that you never received a [`call.received`] for, log it as a \"Network Anomaly.\" This helps your technical team identify stability issues with the WhatsApp WebSocket or your server's ingestion lag.\n*   **The \"Zero-Latency\" Rule**: Like all call events, rejection is extremely time-sensitive. If your follow-up message arrives 10 minutes late, the customer has already moved on to a competitor. Host your rejection handler on your fastest, most reliable infrastructure.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Strict ID Mapping**: Ensure your database uses the Call ID as a primary key for call-related records. This prevents \"ID Collision\" and ensures that state updates are applied to the correct interaction.\n2.  **Verify the Session Scope**: In a multi-instance setup, Ensure that the [`session`] ID provided in the webhook metadata is used to gate your follow-up logic. You don't want a \"Sorry we missed you\" message being sent from the wrong business line.\n3.  **Clean up In-Memory States**: If you use a cache (like Redis) to track \"Active Calls,\" use the [`call.rejected`] event to immediately purge the entry for that Call ID. This keeps your cache lean and prevents memory leaks.\n\n## 🎯 Conclusion: Mastering the Art of the End-Point\n\nThe **Call Rejected Webhook** is the \"Final Chapter\" of a voice interaction. By building an architecture that listens to this termination signal and converts it into a proactive opportunity, you move your organization from \"Abrupt Disconnects\" to **Seamless Redirection**. You build systems that respect human decisions, capture interaction data, and maintain a high-fidelity conversational history with engineered precision. In the world of Wawp, a rejection is not the end of the relationship; it is the strategic trigger for a better, more focused conversation.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01...",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "call.rejected",
            "payload": {
              "id": "call_12345"
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123@lid",
              "pushName": "Instance"
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "رفض المكالمة",
          "description": "يتم تفعيله عند رفض مكالمة واردة.",
          "extraInfo": "\n# إغلاق حلقة الصوت: إتقان ويب هوك رفض المكالمات\n\nفي منظومة الاتصالات الرقمية، يعد إنهاء التفاعل بنفس أهمية بدئه. يعد ويب هوك [`call.rejected`] الحدث النهائي لـ \"نهاية الإشارة\" لمحاولة صوتية أو مرئية. سواء تم رفض المكالمة يدوياً بواسطة وكيل بشري عبر الهاتف، أو تم إنهاؤها تلقائياً بناءً على سياسة النظام، فإن هذا الحدث يزود بنيتك التحتية بالإغلاق اللازم للحفاظ على سجل تدقيق دقيق لتفاعل العملاء.\n\n---\n\n## 🏗️ الفلسفة المعمارية: المكالمة كجلسة محدودة\n\nتعمل مكالمة واتساب كحالة متزامنة تستهلك الموارد والاهتمام. يعمل حدث [`call.rejected`] كمنظف للمنطق البرمجي الخاص بك.\n*   **إعادة مطابقة الحالة**: المعرف [`id`] في الحمولة هو \"المفتاح الأساسي\" الذي يربط حدث استلام المكالمة بحدث رفضها. يجب على نظامك استخدام هذا المعرف لنقل سجل المكالمة من \"رنين\" إلى \"منتهي\".\n*   **الشفافية في الأداء**: في مراكز الدعم، يعد \"معدل الرفض\" مؤشراً حيوياً للأداء (KPI). يتيح لك ربط هذا الويب هوك بالوكيل المكلف بالمثيل تحديد أنماط تجنب التفاعلات، مما يساعد في الإدارة القائمة على البيانات التقنية.\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي: الدردشة الاستباقية الفورية\n\nإذا تم رفض مكالمة، فمن المرجح أن المستخدم يمسك بهاتفه *الآن*. هذه هي اللحظة المثالية لمتابعة نصية.\nفبمجرد استلام الويب هوك، يمكن للنظام إرسال رسالة: *\"نعتذر عن عدم قدرتنا على الرد الآن! نحن نساعد عملاء آخرين عبر الدردشة حالياً. كيف يمكننا مساعدتك هنا؟\"*. هذا يحول التفاعل السلبي (مكالمة مرفوضة) إلى مشاركة إيجابية (دردشة استباقية).\n\n---\n\n## 🛡️ أفضل الممارسات الهندسية والتشغيلية\n*   **قاعدة الـ 500 ملّي ثانية**: كبقية أحداث المكالمات، يعد الرفض حساساً جداً للوقت. إذا وصلت رسالة المتابعة متأخرة بـ 10 دقائق، فمن المحتمل أن يكون العميل قد انتقل إلى منافس آخر.\n*   **تنظيف الحالة المؤقتة**: إذا كنت تستخدم ذاكرة مؤقتة (مثل Redis) لتتبع \"المكالمات النشطة\"، استخدم هذا الحدث لمسح المدخل الخاص بمعرف المكالمة فوراً، مما يحافظ على كفاءة الذاكرة.\n*   **المزامنة مع الواقع المادي**: إذا قام شخص بحمل الهاتف المادي والضغط على \"رفض\"، فإن هذا الويب هوك هو وسيلة الباك-إند الوحيدة لمعرفة ما فعله المشغل البشري، مما يبقي لوحة التحكم الرقمية متزامنة مع الواقع.\n            "
        }
      }
    },
    {
      "path": "/label.upsert",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Label Created/Updated",
      "description": "Triggered when a WhatsApp Business label is added or modified.",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "Business Feature",
          "content": "Labels are exclusive to WhatsApp Business accounts. Personal accounts will not fire this event."
        }
      ],
      "recommendations": [
        "Sync your CRM tags with WhatsApp Business labels automatically.",
        "Update the label color and name in your local cache."
      ],
      "extraInfo": "\n# The Taxonomy of Engagement: Mastering Label Upsert Webhooks\n\nIn the sophisticated world of WhatsApp Business management, organization is the engine of efficiency. Labels are the native categorization tool of the WhatsApp Business ecosystem, allowing agents to visually prioritize and segment their conversations. The **Label Created/Updated (Upsert)** webhook is the primary signal that your organization's taxonomy has evolved. Whether a new \"Priority Sales\" label is created or an existing \"In Review\" label is renamed, the [`label.upsert`] event provides your infrastructure with the real-time data required to maintain a perfect synchronization between your WhatsApp interface and your central CRM.\n\nThis guide provides an architectural deep-dive into the strategic importance of label metadata management, moving beyond \"Tag Tracking\" into the realm of **Operational Categorization and Visual Workflow Orchestration**.\n\n---\n\n## 🏗️ Architectural Philosophy: Labels as Structural Metadata\n\nTo build a premium enterprise integration, your system must treat labels as the \"Primary Keys of Segmentation.\" A label consists of three core properties: a unique **ID**, a **Name** (the category title), and a **Color** (the visual priority).\n\n### 1. The Taxonomy Bridge\nA Label Upsert event should be treated as a **Configuration Update**. \n*   **CRM Synchronization**: Your system should mirror these labels as \"Tags\" or \"Status Folders\" within your internal CRM. When a label name changes on WhatsApp, your CRM must update its display name instantly to ensure agents don't experience \"Contextual Mismatch\"—where the phone says \"Lead\" but the CRM says \"Prospect.\"\n*   **The Idempotent Upsert**: Because the payload contains the full label object, your ingestion layer can use an \"Upsert\" (Update-or-Insert) logic. If the Label ID is new, branch it into your taxonomy; if it exists, update its metadata.\n\n### 2. The Visual Pulse (Colors as Priority)\nWhatsApp labels use hex color codes to denote priority. A high-performance architecture maps these colors to internal priority levels. For example, a \"Red\" label might trigger a higher-priority alert in your internal Slack channel than a \"Blue\" label. The [`label.upsert`] webhook is the signal that these priority assignments have shifted.\n\n---\n\n## 🚀 Strategic Use Cases: Powering Categorized Communication\n\nLabels are the \"Sorters\" of your conversational pipeline. Mastering the upsert event allows you to build a system that understands the *meaning* of a chat before an agent even opens it.\n\n### 1. Automated CRM Tag Migration\nFor businesses scaling from manual phone usage to automated Wawp-powered workflows, the label upsert event is the \"Historical Bridge.\" \n**The Strategic Workflow**: As agents create labels on their physical phones, your backend listens to the [`label.upsert`] stream. It automatically creates corresponding \"Segments\" in your email marketing or lead-tracking software. This ensures that the efforts of the \"Front-line\" agents (who organize the chats) are immediately visible to the \"Back-office\" analytical teams.\n\n### 2. Visual Consistency Across Custom Dashboards\nIf you are building a custom multi-agent dashboard using Wawp, you must replicate the \"Look and Feel\" of the WhatsApp Business app. \n**The Real-Time Update**: Use the color and name data from the upsert webhook to dynamically style your dashboard. When an admin changes the \"Urgent\" label from Orange to Red on their phone, the entire team's dashboard should update its CSS in real-time. This visual synchronicity builds a sense of a \"Unified Workspace\" across all devices and platforms.\n\n### 3. Dynamic Routing based on Taxonomy\nCombine the [`label.upsert`] event with the [Label Chat Added](/v2/webhooks/label-chat-added) event to build a \"Category-Based Router.\" \n**The Logic**: If a label [`VIP`] is created/updated, your system updates its routing tables. Any chat that is subsequently tagged with this label can be programmatically moved to the \"Senior Account Manager\" queue. By listening to the upsert, your system stays aware of *what* the labels mean, allowing for more flexible, human-readable routing logic.\n\n---\n\n## 🛡️ Administrative Mandate: Scaling the Organizational Layer\n\nEffective label management is a method of \"Structural Integrity.\"\n\n### 1. The \"Single Source of Truth\" Governance\nDecide who is the master of your taxonomy. \n*   **Hybrid Management**: If you allow agents to create labels on their phones, the [`label.upsert`] webhook is your \"Compliance Sentinel.\" You can use it to monitor the creation of \"Off-brand\" or \"Duplicate\" labels and programmatically [Delete](/v2/labels/delete) them if they violate your organizational policy.\n*   **Wawp-Led Management**: If your CRM is the master, you use the [Create Label](/v2/labels/create) API to push tags to WhatsApp. In this scenario, the webhook acts as a **Confirmation Signal**, letting you know the platform has successfully ingested your new tag.\n\n### 2. High-Fidelity Audit Logs for Business Strategy\nA change in a label name often signals a change in business process. \n**The Data Insight**: By logging the history of label upserts, you can track the evolution of your sales funnel. *\"We changed 'Interested' to 'Qualified' on March 1st\"*—having this technical timestamp in your logs allows you to accurately measure the performance of your marketing campaigns across different procedural eras.\n\n---\n\n## 🛡️ Operational Best Practices: Optimizing the Categorization Loop\n\n*   **Color-to-Severity Mapping**: Maintain an internal mapping table: `#DFE5E7` (Light Gray) = `Archived`, `#FFD700` (Gold) = `Premium`. When an upsert event carries one of these colors, the system should automatically apply the corresponding severity level to any associated support tickets.\n*   **The \"Special Characters\" Warning**: WhatsApp labels support emojis. Ensure your database and ingestion layer use full UTF-8 encoding so that a label named \"🚀 Sales\" doesn't become \"? Sales\" in your CRM.\n*   **Coordinate with label.deleted**: An upsert event updates the label, but it does not tell you if the label was removed from a specific chat. Always coordinate this webhook with [`label-chat-deleted`] to maintain an accurate count of how many users are currently in each \"Live Category.\"\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Deduplicate Rapid Updates**: If an agent is indecisive and renames a label three times in a minute, your system will receive three webhooks. Use the event [`timestamp`] to ensure you only apply the \"Final\" state to your database.\n2.  **Verify Business Engine Compatibility**: Labels are a premium feature of the WhatsApp Business engine. If your instance is downgraded or the engine is swapped to a non-business version, your system should handle the absence of these webhooks gracefully by falling back to \"Generic Text Tags.\"\n3.  **Scoped ID Lookups**: Label IDs are typically small integers (e.g., \"1\", \"2\"). Ensure your lookup logic doesn't confuse a Label ID with a Message ID or a JID, as they exist in different namespaces.\n\n## 🎯 Conclusion: Beyond Tags—The Architecture of Priority\n\nThe **Label Upsert Webhook** is the \"Registry of Categories\" for your conversational brand. By building an architecture that listens, synchronizes, and acts upon these metadata shifts, you move your organization from \"Generic Chat Management\" to **Engineered Prioritization**. You build systems that understand the visual language of the agent, respect the evolution of the sales funnel, and maintain a perfect synchronization between the front-office and the back-office. In the world of Wawp, an upsert is more than a change—it is the strategic signal that keeps your organizational structure aligned with your real-time engagement.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01...",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "label.upsert",
            "payload": {
              "label": {
                "id": "1",
                "name": "New Customer",
                "color": "#DFE5E7"
              }
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123@lid",
              "pushName": "Instance"
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "تم إنشاء/تحديث تصنيف",
          "description": "يتم إطلاقه عند إضافة أو تعديل تصنيف واتساب بيزنس.",
          "tips": [
            {
              "title": "حدود معدل API",
              "content": "احترم حدود معدل API لتجنب الحظر المؤقت."
            },
            {
              "title": "العمليات غير المتزامنة",
              "content": "معظم العمليات غير متزامنة. استخدم Webhooks للتحديثات في الوقت الفعلي."
            }
          ],
          "recommendations": [
            "استخدم متغيرات البيئة لبيانات الاعتماد الحساسة مثل رموز الوصول.",
            "قم بتنفيذ معالجة قوية للأخطاء ومنطق إعادة المحاولة."
          ],
          "extraInfo": "\n# تصنيف التفاعل: إتقان ويب هوك تحديث التصنيفات\n\nفي عالم إدارة واتساب بيزنس، التنظيم هو محرك الكفاءة. التصنيفات هي أداة التصنيف الأصلية لنظام واتساب، وتسمح للوكلاء بتحديد أولويات محادثاتهم وتقسيمها بصرياً. ويب هوك **تم إنشاء/تحديث تصنيف (Upsert)** هو الإشارة الأساسية لتطور تصنيفات مؤسستك. سواء تم إنشاء تصنيف \"مبيعات ذات أولوية\" جديد أو تمت إعادة تسمية تصنيف \"قيد المراجعة\" الحالي، يوفر حدث [`label.upsert`] لبنيتك التحتية البيانات الفورية المطلوبة للحفاظ على مزامنة مثالية بين واجهة واتساب ونظام CRM المركزي الخاص بك.\n\n---\n\n## 🏗️ الفلسفة المعمارية: التصنيفات كبيانات هيكلية\n\nلبناء تكامل مؤسسي متميز، يجب أن يعامل نظامك التصنيفات كـ \"مفاتيح أساسية للتقسيم\". يتكون التصنيف من ثلاث خصائص أساسية: **معرف (ID)** فريد، **اسم** (عنوان الفئة)، و **لون** (الأولوية البصرية).\n\n### 1. جسر التصنيفات\nيجب التعامل مع حدث تحديث التصنيف كـ **تحديث للإعدادات**.\n*   **مزامنة CRM**: يجب أن يعكس نظامك هذه التصنيفات كـ \"وسوم\" أو \"مجلدات حالة\" داخل نظام CRM الخاص بك. عندما يتغير اسم تصنيف في واتساب، يجب أن يقوم نظام CRM بتحديث اسم العرض الخاص به فوراً لضمان عدم تعرض الوكلاء لـ \"عدم تطابق السياق\".\n*   **التحديث الذري**: بما أن الحمولة تحتوي على كائن التصنيف الكامل، يمكن لطبقة الاستيعاب لديك استخدام منطق \"تحديث أو إدراج\". إذا كان معرف التصنيف جديداً، أضفه؛ وإذا كان موجوداً، فقم بتحديث بياناته.\n\n### 2. النبض البصري (الألوان كأولوية)\nتستخدم تصنيفات واتساب أكواد ألوان لتمثيل الأولوية. يقوم المهندس المتميز برسم خرائط لهذه الألوان لمستويات الأولوية الداخلية. على سبيل المثال، قد يطلق التصنيف \"الأحمر\" تنبيهاً ذا أولوية أعلى في قناة Slack الداخلية من التصنيف \"الأزرق\".\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجية\n\n### 1. التزامن التلقائي لوسوم CRM\nبالنسبة للشركات التي تنتقل من استخدام الهاتف اليدوي إلى سير عمل مؤتمت، يعد هذا الويب هوك هو \"الجسر التاريخي\". عندما يقوم الوكلاء بإنشاء تصنيفات على هواتفهم، يستمع نظامك الخلفي لها ويقوم تلقائياً بإنشاء \"شرائح\" مقابلة في برامج التسويق أو تتبع العملاء المتوقعين.\n\n### 2. الاتساق البصري عبر لوحات التحكم المخصصة\nإذا كنت تبني لوحة تحكم متعددة الوكلاء، يجب عليك تكرار \"شكل ومظهر\" تطبيق واتساب بيزنس. استخدم بيانات اللون والاسم من ويب هوك التحديث لتنسيق لوحتك ديناميكياً. عندما يغير المسؤول تصنيف \"عاجل\" من البرتقالي إلى الأحمر على هاتفه، يجب أن يتم تحديث واجهة الفريق بالكامل في الوقت الفعلي.\n\n---\n\n## 🎯 أفضل الممارسات التشغيلية\n\n*   **ربط اللون بالخطورة**: احتفظ بجدول ربط داخلي: مثلاً `#DFE5E7` (رمادي فاتح) = `مؤرشف`، `#FFD700` (ذهبي) = `مميز`.\n*   **تحذير \"الرموز التعبيرية\"**: تدعم تصنيفات واتساب الرموز التعبيرية. تأكد من أن قاعدة بياناتك تدعم ترميز UTF-8 بالكامل حتى لا يصبح التصنيف \"🚀 مبيعات\" هو \"؟ مبيعات\".\n*   **التنسيق مع الحذف**: يخبرك هذا الويب هوك بتحديث التصنيف نفسه، لكنه لا يخبرك إذا تمت إزالته من دردشة معينة. استخدمه دائماً بالتنسيق مع [`label.chat.deleted`].\n            "
        }
      }
    },
    {
      "path": "/label.deleted",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Label Deleted",
      "description": "Triggered when a label is completely removed from the account.",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "warning",
          "title": "Cascading Deletion",
          "content": "When a label is deleted, it is automatically removed from all chats. You should cleanup your local associations as well."
        }
      ],
      "recommendations": [
        "Remove the label ID from your local database to prevent ghost tags."
      ],
      "extraInfo": "\n# Label Deletion\n\nSignals that a specific business label no longer exists.\n\n### Fields\n*   **labelId**: The ID of the removed label.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01...",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "label.deleted",
            "payload": {
              "labelId": "1"
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123@lid",
              "pushName": "Instance"
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "تم حذف تصنيف",
          "description": "يتم إطلاقه عند إزالة تصنيف بالكامل من الحساب.",
          "extraInfo": "\n# حذف التصنيف\n\nيشير إلى أن تصنيفاً تجارياً معيناً لم يعد موجوداً.\n\n### الحقول\n*   **labelId**: المعرف الفريد للتصنيف الذي تمت إزالته.\n            ",
          "tips": [
            {
              "title": "وقت الاستجابة",
              "content": "أرجع حالة HTTP 200 OK فورًا لتأكيد الاستلام."
            },
            {
              "title": "التكرار",
              "content": "تعامل مع أحداث الويب هوك المكررة بشكل مناسب."
            }
          ],
          "recommendations": [
            "تحقق من توقيعات الويب هوك لضمان الأمان.",
            "قم بمعالجة المنطق الثقيل بشكل غير متزامن بعد تأكيد الويب هوك.",
            "سجل الحمولات لأغراض التصحيح."
          ]
        }
      }
    },
    {
      "path": "/label.chat.added",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Label Added to Chat",
      "description": "Triggered when a label is assigned to a specific conversation.",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "Lead Status",
          "content": "Perfect for moving leads through your custom kanban or pipeline based on tags applied in WhatsApp."
        }
      ],
      "recommendations": [
        "Update the 'tags' or 'status' field for the contact/chat in your backend."
      ],
      "extraInfo": "\n# The Signal of Conversion: Mastering the Label-to-Chat Webhook\n\nIn the architecture of a high-performance sales and support engine, a tag is not just a label—it is a **State Transition**. The **Label Added to Chat** webhook is the primary signal that a human agent or an automated system has categorized a conversation into a specific operational phase. Whether a chat is marked as \"Interested,\" \"Payment Pending,\" or \"VIP Support,\" the [`label.chat.added`] event provides your infrastructure with the real-time trigger required to move the customer through your internal Kanban or CRM pipeline.\n\nThis guide provides an architectural deep-dive into the strategic value of dynamic chat labeling, moving beyond \"Tagging\" into the realm of **Automated Pipeline Orchestration and Lead-Scoring Logic**.\n\n---\n\n## 🏗️ Architectural Philosophy: Labels as Pipeline Gates\n\nTo master the Label-to-Chat API, one must recognize that applying a label is an act of **Intentional Classification**.\n\n### 1. The Interaction Identity (JIDs)\nThe mapping of a label to a chat is agnostic of the chat type:\n*   **Individuals (@c.us)**: Tagging a 1-on-1 chat creates a personalized lead profile in your CRM.\n*   **Groups (@g.us)**: Tagging a group chat categorizes the entire community (e.g., \"Project Delta\" or \"Priority Partners\").\nYour system must use the [`chatId`] in the payload to locate the target entity and the [`labelId`] to determine which specific \"Bucket\" the entity now belongs to.\n\n### 2. The Relationship Between Meta and State\nWhile the [Label Upsert](/v2/webhooks/label-upsert) event defines *what* the label is (name/color), the [`label.chat.added`] event defines *where* the label is. A robust architecture treats the Upsert as a \"Schema Update\" and the Added event as a \"Data Mutation.\" \n\n---\n\n## 🚀 Strategic Use Cases: Powering Automated Conversion Funnels\n\nThe Label-to-Chat webhook is the \"Glue\" that connects the human interaction on a phone with the automated processes in your backend.\n\n### 1. Building the \"WhatsApp Kanban\" (Automated Pipeline Sync)\nMany organizations use external tools like Trello, Pipedrive, or custom Kanban boards to track leads.\n**The Strategic Workflow**: When an agent on a physical phone applies the \"Qualified\" label to a chat, Wawp fires the [`label.chat.added`] webhook. Your backend catches this and programmatically moves the corresponding card in your CRM from the \"Lead\" column to the \"Opportunity\" column. This ensures your sales dashboard is **Always in Sync** with the real-time actions of the front-line team, eliminating manual data entry.\n\n### 2. Automated Drip-Sequence Triggers\nLabels can act as \"Switches\" for automated marketing campaigns.\n**The Logic**: If your system detects that a chat has been tagged with \"Send Catalog,\" it can automatically trigger the [`send-pdf`](/v2/send/pdf) endpoint to deliver your latest product brochure to that [`chatId`]. This \"Label-Triggered Automation\" allows human agents to initiate complex bot flows with a single tap of a tag on their phone screen.\n\n### 3. Escalation and Priority Routing\nUse labels to denote \"Escalated\" status.\n**The Use Case**: When a support supervisor tags a chat as \"High Priority,\" your system detects the change via the webhook and updates the metadata in your internal ticketing system. It can also trigger a Slack notification to the engineering team: *\"Urgent assistance required for [Contact Name]—tagged as High Priority.\"* This turns a simple WhatsApp feature into a **Cross-Platform Alerting Engine**.\n\n---\n\n## 🛡️ Administrative Mandate: Scaling the Attribution Layer\n\nScaling labeling logic requires a focus on \"Categorical Integrity.\"\n\n### 1. The \"Single Label\" Policy vs. Multi-Tagging\nWhatsApp allows multiple labels to be applied to a single chat. \n**The Strategic Rule**: Decide how your CRM handles \"Tag Overlap.\" Does your system treat the *latest* label as the primary status, or does it accumulate labels into an array of tags? We recommend an **\"Accumulative Model\"** for marketing segments and a **\"Single-Truth Model\"** for pipeline stages. The [`label.chat.added`] event provides the IDs you need to maintain whichever model fits your business logic.\n\n### 2. Monitoring Agent Productivity and Accuracy\nBy logging every [`label.chat.added`] event with its timestamp, you can measure the \"Time-to-Label\"—the gap between the first message and the moment the lead was qualified. \n**The Data Insight**: If an agent takes 4 hours to label a lead, it indicates a bottleneck in your triage process. If they label 50 chats as \"Spam\" in 5 minutes, it may indicate a data-quality issue or a need for better automated filtering. This webhook is a vital tool for **Operational Quality Control**.\n\n---\n\n## 🛡️ Operational Best Practices: Optimizing the State Loop\n\n*   **Coordinate with label.chat.deleted**: A chat can move out of a category by having the label removed. To maintain an accurate count of \"Live Leads\" in your CRM, your system *must* listen to the [Label Deleted from Chat](/v2/webhooks/label-chat-deleted) event to clear the corresponding tag in your database.\n*   **The \"Shadow State\" Warning**: Note that labels are sometimes applied *before* the first message is received (e.g., from a prior contact). Your system should be prepared to handle a [`label.chat.added`] event for a [`chatId`] that doesn't yet have a message history in your logs.\n*   **Visual Reassurance**: If your custom dashboard has its own tagging UI, ensure that any label added via the Wawp API also triggers the same \"Success\" visuals as a manual tag. This keeps the experience consistent for the user.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Strict ID Mapping**: Always resolve the [`labelId`] using your latest cached data from the [label.upsert](/v2/webhooks/label-upsert) stream. Never hardcode label IDs, as they can change between different WhatsApp Business instances.\n2.  **Verify Asset Consistency**: If a label is added to a Group (`@g.us`), ensure your code updates the metadata for the *Group Entity* rather than a specific individual.\n3.  **Handle \"Mass Tagging\" Scenarios**: Some WhatsApp engines allow \"Bulk Labeling\" (tagging 10 chats at once). Your webhook handler should be designed to receive and process these as atomic, high-speed events.\n\n## 🎯 Conclusion: The Rhythm of Classification\n\nThe **Label Added to Chat Webhook** is the \"Pulse of Progress\" for your digital brand. By building an architecture that listens, automates, and synchronizes these categorical shifts, you move your organization from \"Reactive Chatting\" to **Structured Revenue Management**. You build systems that understand the stage of every lead, automate the delivery of resources, and maintain a high-fidelity pipeline between the WhatsApp interface and your corporate brain. In the world of Wawp, a label is not just a tag—it is the strategic signal that drives your business forward.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01...",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "label.chat.added",
            "payload": {
              "chatId": "11111111111@c.us",
              "labelId": "1"
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123@lid",
              "pushName": "Instance"
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "تمت إضافة تصنيف للدردشة",
          "description": "يتم إطلاقه عند تعيين تصنيف لمحادثة محددة.",
          "tips": [
            {
              "title": "تنسيق المستلم",
              "content": "استخدم @c.us لجهات الاتصال و @g.us للمجموعات."
            },
            {
              "title": "التعامل مع الوسائط",
              "content": "تأكد من أن روابط الوسائط متاحة للعامة وهي روابط مباشرة."
            }
          ],
          "recommendations": [
            "أضف تأخيرات عشوائية بين الرسائل لمحاكاة السلوك البشري.",
            "تحقق من أرقام الهواتف قبل الإرسال لضمان التسليم."
          ],
          "extraInfo": "\n# إشارة التحويل: إتقان ويب هوك ربط التصنيف بالدردشة\n\nفي تصميم محركات المبيعات والدعم عالية الأداء، التصنيف ليس مجرد وسم — إنه **انتقال للحالة**. ويب هوك **تمت إضافة تصنيف للدردشة** هو الإشارة الأساسية إلى أن وكيلاً بشرياً أو نظاماً مؤتمتاً قد صنف المحادثة في مرحلة تشغيلية محددة. سواء تم وسم الدردشة بـ \"مهتم\" أو \"انتظار الدفع\" أو \"دعم VIP\"، يوفر حدث [`label.chat.added`] لبنيتك التحتية المحفز الفوري المطلوب لنقل العميل عبر مراحل الـ Kanban أو نظام CRM الداخلي الخاص بك.\n\n---\n\n## 🏗️ الفلسفة المعمارية: التصنيفات كبوابات للمسار\n\nلإتقان هذه الواجهة، يجب الاعتراف بأن تطبيق التصنيف هو عمل من أعمال **التصنيف المتعمد**.\n\n### 1. هوية التفاعل\nربط التصنيف بالدردشة لا يعتمد على نوع الدردشة:\n*   **الأفراد (@c.us)**: وسم دردشة فردية ينشئ ملف تعريف لعميل محتمل في نظام CRM الخاص بك.\n*   **المجموعات (@g.us)**: وسم دردشة جماعية يصنف المجتمع بأكمله (مثلاً: \"مشروع دلتا\").\nيجب أن يستخدم نظامك [`chatId`] لتحديد الكيان المستهدف و [`labelId`] لتحديد الفئة التي ينتمي إليها الآن.\n\n### 2. العلاقة بين الوصف والحالة\nبينما يحدد حدث [تحديث التصنيف](/v2/webhooks/label-upsert) *ماهية* التصنيف (الاسم واللون)، يحدد حدث [`label.chat.added`] *مكان* التصنيف. تعامل البنية القوية مع التحديث كـ \"تحديث للمخطط\" ومع الإضافة كـ \"تغيير في البيانات\".\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجية\n\n### 1. بناء \"كانبان واتساب\" (مزامنة المسار التلقائية)\nعندما يضع وكيل على هاتف حقيقي وسم \"مؤهل\" لدردشة، يرسل Wawp ويب هوك [`label.chat.added`]. يلتقط نظامك الخلفي هذا ويقوم برمجياً بنقل البطاقة المقابلة في نظام CRM الخاص بك من عمود \"عميل محتمل\" إلى عمود \"فرصة مبيعات\". هذا يضمن أن لوحة مبيعاتك **دائماً متزامنة** مع الإجراءات الفعلية للفريق، مما يلغي إدخال البيانات يدوياً.\n\n### 2. محفزات سلاسل التتابع التلقائية\nيمكن أن تعمل التصنيفات كـ \"مفاتيح\" لحملات تسويقية مؤتمتة. إذا اكتشف نظامك أن دردشة تم وسمها بـ \"إرسال كتالوج\"، فيمكنه تلقائياً استدعاء واجهة [إرسال PDF](/v2/send/pdf) لتسليم كتيب منتجاتك الأحدث لهذا المستخدم.\n\n---\n\n## 🎯 أفضل الممارسات التشغيلية\n\n*   **التنسيق مع label.chat.deleted**: يمكن أن تخرج الدردشة من فئة ما بإزالة التصنيف منها. للحفاظ على عدد دقيق لـ \"العملاء المحتملين النشطين\" في نظام CRM الخاص بك، *يجب* على نظامك الاستماع لحدث [حذف تصنيف من دردشة](/v2/webhooks/label-chat-deleted) لمسح الوسم المقابل في قاعدة بياناتك.\n*   **تحذير \"حالة الظل\"**: لاحظ أن التصنيفات يتم تطبيقها أحياناً *قبل* تلقي الرسالة الأولى (مثلاً من جهة اتصال سابقة). يجب أن يكون نظامك مستعداً للتعامل مع هذا الحدث لدردشة ليس لها سجل رسائل بعد.\n            "
        }
      }
    },
    {
      "path": "/label.chat.deleted",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Label Removed from Chat",
      "description": "Triggered when a label is unassigned from a conversation.",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "Pipeline Movement",
          "content": "Use this to detect when a lead is cleared from a specific stage in your sales funnel."
        }
      ],
      "recommendations": [
        "Synchronize your local tags by removing the specified label from the chat entry."
      ],
      "extraInfo": "\n# Chat Label Removal\n\nSignals that a tag has been disconnected from a chat.\n\n### Fields\n*   **chatId**: ID of the conversation.\n*   **labelId**: The ID of the label that was removed.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01...",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "label.chat.deleted",
            "payload": {
              "chatId": "11111111111@c.us",
              "labelId": "1"
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123@lid",
              "pushName": "Instance"
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "تم حذف تصنيف من الدردشة",
          "description": "يتم إطلاقه عند إلغاء تعيين تصنيف من محادثة.",
          "extraInfo": "\n# حذف تصنيف الدردشة\n\nيشير إلى أنه تم فصل وسم عن دردشة.\n\n### الحقول\n*   **chatId**: معرف المحادثة.\n*   **labelId**: معرف التصنيف الذي تم حذفه.\n            ",
          "tips": [
            {
              "title": "وقت الاستجابة",
              "content": "أرجع حالة HTTP 200 OK فورًا لتأكيد الاستلام."
            },
            {
              "title": "التكرار",
              "content": "تعامل مع أحداث الويب هوك المكررة بشكل مناسب."
            }
          ],
          "recommendations": [
            "تحقق من توقيعات الويب هوك لضمان الأمان.",
            "قم بمعالجة المنطق الثقيل بشكل غير متزامن بعد تأكيد الويب هوك.",
            "سجل الحمولات لأغراض التصحيح."
          ]
        }
      }
    },
    {
      "path": "/event.response",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Event Success Response",
      "description": "Triggered when an asynchronous event completes successfully.",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "Async Tracking",
          "content": "Essential for tracking the completion of bulk tasks or long-running operations."
        }
      ],
      "recommendations": [
        "Use the `requestId` to link the result back to your initial API call."
      ],
      "extraInfo": "\n# Asynchronous Success\n\nThis event confirms that a previously requested async operation has finished without errors.\n\n### Fields\n*   **requestId**: The unique ID you received when making the initial request.\n*   **data**: The successful result or confirmation data.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01...",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "event.response",
            "payload": {
              "requestId": "req_001",
              "data": {
                "status": "completed"
              }
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123@lid",
              "pushName": "Instance"
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "استجابة الحدث بنجاح",
          "description": "يتم تفعيله عند اكتمال حدث غير متزامن بنجاح.",
          "extraInfo": "\n# النجاح غير المتزامن\n\nيؤكد هذا الحدث أن العملية المطلوبة سابقاً (Async) قد انتهت دون أخطاء. استخدم [`requestId`] لربط النتيجة بطلبك الأولي في نظامك.\n            "
        }
      }
    },
    {
      "path": "/event.response.failed",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Event Failure Response",
      "description": "Triggered when an asynchronous event fails to complete.",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "warning",
          "title": "Error Recovery",
          "content": "Always listen for this event to implement retry logic or alert users of a failed task."
        }
      ],
      "recommendations": [
        "Include the error code in your logs for technical troubleshooting."
      ],
      "extraInfo": "\n# Asynchronous Failure\n\nIndicates that an async operation could not be completed.\n\n### Fields\n*   **requestId**: The ID of the failed request.\n*   **error**: Error details describing what went wrong.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01...",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "event.response.failed",
            "payload": {
              "requestId": "req_002",
              "error": "TIMEOUT_ERROR"
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123@lid",
              "pushName": "Instance"
            }
          }
        }
      ]
    },
    {
      "path": "/engine.event",
      "methods": [
        "POST"
      ],
      "category": "Webhooks",
      "title": "Raw Engine Event",
      "description": "Catch-all for low-level system events directly from the WhatsApp engine.",
      "isArticle": false,
      "args": {},
      "tips": [
        {
          "type": "info",
          "title": "Advanced Use",
          "content": "This is primarily for developers needing raw access to internal engine movements not covered by high-level events."
        }
      ],
      "recommendations": [
        "Use this for debugging or building extremely niche integrations."
      ],
      "extraInfo": "\n# Raw Engine Access\n\nThis event exposes internal movements of the underlying engine (`WEBJS`, etc.).\n\n### Usage\nUseful for tracking internal connection retries or low-level protocol debugging.\n    ",
      "responses": [
        {
          "status": 200,
          "description": "Webhook Payload Example",
          "example": {
            "id": "evt_01...",
            "timestamp": 1634567890123,
            "session": "default",
            "metadata": {
              "user.id": "123",
              "user.email": "email@example.com"
            },
            "engine": "WEBJS",
            "event": "engine.event",
            "payload": {
              "raw": {
                "event": "internal_movement",
                "data": {}
              }
            },
            "me": {
              "id": "11111111111@c.us",
              "lid": "123@lid",
              "pushName": "Instance"
            }
          }
        }
      ],
      "translations": {
        "ar": {
          "title": "حدث المحرك الخام",
          "description": "لاقط شامل لأحداث النظام منخفضة المستوى مباشرة من محرك واتساب.",
          "extraInfo": "\n# الوصول المباشر للمحرك\n\nيكشف هذا الحدث الحركات الداخلية للمحرك الأساسي (مثل `WEBJS`). هو مخصص للمطورين الذين يحتاجون للوصول إلى تفاصيل العمليات الداخلية التي لا تغطيها الأحداث رفيعة المستوى، مثل تصحيح أخطاء الاتصال منخفضة المستوى.\n            "
        }
      }
    },
    {
      "path": "/v2/calls/reject",
      "methods": [
        "POST"
      ],
      "title": "Reject Call",
      "category": "Calls",
      "description": "Reject an incoming call for a specific session.",
      "modifiedAt": "Just now",
      "args": {
        "instance_id": {
          "required": true,
          "type": "string",
          "description": "Your unique WhatsApp Instance ID",
          "example": "123456789"
        },
        "access_token": {
          "required": true,
          "type": "string",
          "description": "Your API Access Token",
          "example": "123456789"
        },
        "callId": {
          "required": true,
          "type": "string",
          "description": "The unique ID of the incoming call (from call.received webhook)",
          "example": "call_123456789"
        },
        "from": {
          "required": true,
          "type": "string",
          "description": "The WhatsApp ID (JID) of the caller (from call.received webhook)",
          "example": "123456789@c.us"
        }
      },
      "responses": [
        {
          "status": 200,
          "description": "Success - Request completed successfully",
          "contentType": "application/json",
          "example": {
            "success": true,
            "message": "Operation completed successfully"
          }
        },
        {
          "status": 200,
          "description": "Success (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
        },
        {
          "status": 200,
          "description": "Success (Plain Text)",
          "contentType": "text/plain",
          "example": "Success: Operation completed successfully."
        },
        {
          "status": 400,
          "description": "Bad Request - Missing Required Parameter(s)",
          "contentType": "application/json",
          "example": {
            "code": "missing_param",
            "message": "Missing required parameter: {parameterName}",
            "details": {
              "missing": [
                "{parameterName}"
              ],
              "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
            }
          }
        },
        {
          "status": 400,
          "description": "Bad Request (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 400,
          "description": "Bad Request (Plain Text)",
          "contentType": "text/plain",
          "example": "Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
        },
        {
          "status": 401,
          "description": "Unauthorized - Invalid or Missing Access Token",
          "contentType": "application/json",
          "example": {
            "code": "invalid_access_token",
            "message": "Invalid or expired access token. Please check your credentials.",
            "details": {
              "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
            }
          }
        },
        {
          "status": 401,
          "description": "Unauthorized (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 404,
          "description": "Not Found - Session Does Not Exist",
          "contentType": "application/json",
          "example": {
            "code": "invalid_session",
            "message": "Session not found. Please verify your instance_id or session_name.",
            "details": {
              "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
            }
          }
        },
        {
          "status": 404,
          "description": "Not Found (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
        },
        {
          "status": 500,
          "description": "Internal Server Error - Unexpected Failure",
          "contentType": "application/json",
          "example": {
            "code": "server_error",
            "message": "An internal server error occurred. Please try again later.",
            "details": {
              "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
            }
          }
        },
        {
          "status": 500,
          "description": "Internal Server Error (HTML)",
          "contentType": "text/html",
          "example": "<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
        },
        {
          "status": 502,
          "description": "Bad Gateway - Connection Failed to Upstream",
          "contentType": "application/json",
          "example": {
            "code": "proxy_error",
            "message": "Failed to connect to WhatsApp server.",
            "details": {
              "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
            }
          }
        },
        {
          "status": 502,
          "description": "Bad Gateway (XML Format)",
          "contentType": "application/xml",
          "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
        }
      ],
      "extraInfo": "\n# Strategic Declinism: The Power of Programmatic Call Termination\n\nIn the orchestration of high-volume digital business environments, the ability to say \"No\" is as critical as the ability to respond. The **Reject Call** endpoint is your primary tool for **Strategic Boundary Enforcement and Conversational Routing**. It allows your automated systems to programmatically terminate an incoming voice or video signal based on real-time business logic, ensuring that your organization's human and technical resources are always focused on the highest-priority interactions. Beyond a simple \"Dismiss\" action, this endpoint is the foundation of a managed voice perimeter that protects your agents from noise and your customers from a substandard conversational experience.\n\nFor enterprise architects, rejection is the **First Step of Redirection**. This guide explores the strategic imperatives of call termination and the governance of real-time presence.\n\n---\n\n## 🏗️ Architectural Philosophy: Signal Termination vs. Passive Silence\n\nFrom a technical perspective, the Reject Call endpoint is a **Signaling Command** that instructs Meta's infrastructure to send a \"Busy\" or \"Call Declined\" packet back to the caller.\n\n### Key Architectural Objectives:\n*   **Active vs. Passive Denial**: If your instance simply ignores a call, the caller's phone will continue to ring for 30-45 seconds until it times out. This creates a perception of unresponsiveness or technical failure. By calling the **Reject Call** API, your system provides an immediate, authoritative signal. This \"Active Rejection\" is a professional courtesy that allows the caller to immediately seek an alternative path of resolution.\n*   **Interrupt Management**: Real-time calls are high-intensity events that occupy the device's audio and networking hardware. Programmatic rejection ensures that these resources are cleared as quickly as possible, maintaining the performance and stability of your WhatsApp Business instance for other concurrent tasks, such as sending high-priority alerts or [Broadcasting](/v2/messaging).\n*   **Idempotency and Traceability**: Every rejection is tied to a unique `callId` retrieved from the [`call.received`](/v2/webhooks/call-received) webhook. This ensures that your system never terminates the wrong interaction and provides a clear audit trail for your compliance and performance monitoring engines.\n\n---\n\n## 🚀 Strategic Use Case: Enforcing Operational Boundaries\n\nReal-time voice communication is expensive. Utilizing programmatic rejection allows you to manage this cost while maintaining a premium brand image.\n\n### 1. The \"VIP-Only\" Calling Perimeter\nYour organization may choose to offer live voice support only to high-value stakeholders (e.g., Enterprise Tier clients or VIP partners). When a call arrives, your system performs a \"Call-Sign Verification\" against your CRM. If the caller is a \"Regular Tier\" user, the system instantly rejects the call and initiates a text-based redirection: *\"We see you are trying to call. Live voice support is a feature of our Premium plan. Please continue your request here via text or click this link to upgrade your account.\"* This turns a rejected call into a targeted \"Upsell Opportunity.\"\n\n### 2. Global \"Quiet Hours\" Enforcement\nFor businesses operating across multiple time zones, enforcing local business hours is a logistical challenge. By integrating the **Reject Call** endpoint with a \"Time-Zone aware Scheduler,\" your system can automatically reject calls arriving outside of a specific region's working hours. The system can then provide context-aware feedback: *\"Greetings! Our London office is currently closed. We will be back online at 09:00 GMT. In the meantime, you can leave a voice note or use our automated FAQ bot.\"*\n\n### 3. Combatting the \"Robocall\" Epidemic\nWhatsApp accounts are not immune to automated spam callers. Your system can implement \"Frequency Throttling.\" If a specific JID calls three times in 60 seconds without a prior 1:1 conversation history, the system identifies this as a \"Bot Signature\" and automatically rejects all subsequent attempts, potentially triggering a temporary [Block](/v2/contacts/block) of the identifier to protect your internal infrastructure.\n\n---\n\n## 🔐 Administrative Mandate: The Guardianship of Operational Focus\n\nIn a professional call center or a distributed agent environment, distraction is a measurable cost. Strategic rejection is a method of \"Focus Insurance.\"\n\n### Protecting the \"Deep Work\" State\nYour agents are most productive when they can focus on resolving complex issues without being interrupted by random incoming rings. By using the **Reject Call** endpoint as a \"Gatekeeper,\" you ensure that the only calls that reach a human agent are those that have been \"Qualified\" through a prior text-based interaction. This \"Qualified-Voice-Only\" policy significantly increases agent throughput and reduces the mental fatigue associated with unmanaged conversational noise.\n\n### Integrity in Compliance and Recording\nIn regulated industries (like Finance or Law), every voice call must be recorded for compliance purposes. If your secondary SIP/VoIP bridge is currently down or at capacity, your system should use the **Reject Call** API as a \"Safety Valve.\" It prevents any call from being established that cannot be properly audited, ensuring that your organization remains within its legal and regulatory guardrails at all times.\n\n---\n\n## 🛡️ Operational Best Practices: The \"Rules of the Graceful Exit\"\n\n*   **The \"Contextual Follow-up\" Mandate**: A programmatic rejection should **never** be a standalone event. The strategic objective is to move the user from a synchronous (High-Cost) channel to an asynchronous (Low-Cost) one. Your system must always send a 1:1 text message within 500ms of the rejection, acknowledging the call and providing the next step.\n*   **Latency-Optimized Processing**: The window for a professional rejection is narrow. If your system takes more than 500-1000ms to process the webhook and send the rejection command, the user will experience one or two rings, creating a \"Glitchy\" impression. Ensure your webhook handler is optimized for high-speed decision-making.\n*   **Monitoring \"Rejection Attrition\"**: Track how many users leave your ecosystem after their calls are rejected. If you find a high drop-off rate, it indicates that your redirection messages are not empathetic or helpful enough. Continuous AB testing of your \"Redirect Copy\" is essential for long-term retention.\n\n---\n\n## ⚙️ Engineering Best Practices: The Validation Loop\n\n1.  **Map JIDs to Session Integrity**: Ensure the `from` JID matches your known context for that specific `callId`. This prevents \"Cross-Talk\" errors where your system might accidentally try to terminate a call on a different session.\n2.  **Handle \"Signal Already Terminated\" States**: In high-latency networking scenarios, a user might hang up right as your system is sending the rejection command. Your code should gracefully handle [`400 Bad Request`] or [`404 Not Found`] responses from the API, treating them as successful \"Race Condition\" resolutions.\n3.  **Coordinate with Presence Awareness**: Before rejecting a call from a high-value customer, perform a quick check of your [Presence State](/v2/presence). If the system detects that *no* agents are currently online, the rejection is justified. If agents are online but \"Busy,\" consider a \"Queueing Message\" rather than a hard rejection.\n\n---\n\n## 🎯 Conclusion: Mastering the Art of the Governed Perimeter\n\nThe **Reject Call** endpoint is the \"Shield\" of your community and interaction architecture. It is your most powerful tool for enforcing discipline, protecting resources, and ensuring that every voice interaction is an intentional, high-value event. By treating rejection as a strategic lever rather than a technical necessity, you build a conversational ecosystem that is professional, respectful of both your agents' and your customers' time, and always perfectly aligned with your business objectives. You move beyond \"Simple Signal Handling\" and into the world of **Advanced Presence Governance**, where the boundary of your business is defined by automated intelligence and architectural precision.\n    ",
      "tips": [
        {
          "type": "info",
          "title": "Webhook Events",
          "content": "Listen to call.* webhooks to handle incoming calls in real-time."
        },
        {
          "type": "warning",
          "title": "Outbound Calls",
          "content": "WhatsApp API does not support programmatic outbound calls. Use links instead."
        }
      ],
      "recommendations": [
        "Respond to incoming call events quickly to avoid timeouts.",
        "Use the \"Reject\" endpoint for unwanted calls with a polite message.",
        "Log call attempts for analytics and support."
      ],
      "translations": {
        "ar": {
          "title": "رفض المكالمة",
          "description": "رفض مكالمة واردة لمثيل معين.",
          "tips": [
            {
              "title": "أحداث الويب هوك",
              "content": "استمع إلى خطافات call.* للتعامل مع المكالمات الواردة في الوقت الفعلي."
            },
            {
              "title": "المكالمات الصادرة",
              "content": "لا تدعم واجهة برمجة تطبيقات واتساب المكالمات الصادرة برمجياً. استخدم الروابط بدلاً من ذلك."
            }
          ],
          "recommendations": [
            "استجب لأحداث المكالمات الواردة بسرعة لتجنب انتهاء المهلة.",
            "استخدم نقطة النهاية \"رفض\" للمكالمات غير المرغوب فيها مع رسالة مهذبة.",
            "سجل محاولات الاتصال للتحليلات والدعم."
          ],
          "extraInfo": "\n# الرفض الاستراتيجي: سلطة إنهاء المكالمات برمجياً\n\nفي إدارة بيئات الأعمال الرقمية عالية الكثافة، تعد القدرة على قول \"لا\" بنفس أهمية القدرة على الاستجابة. واجهة **رفض المكالمة** هي أداتك الأساسية لـ **فرض الحدود الاستراتيجية وتوجيه المحادثات**. فهي تسمح لأنظمتك بإنهاء إشارة صوتية أو مرئية واردة بناءً على منطق العمل في الوقت الفعلي، مما يضمن تركيز مواردك البشرية والتقنية على التفاعلات ذات الأولوية القصوى.\n\n---\n\n## 🏗️ الفلسفة المعمارية: إنهاء الإشارة مقابل الصمت السلبي\n\nمن منظور تقني، يعد رفض المكالمة **أمراً إشارياً (Signaling Command)** يوجه بنية Meta التحتية لإرسال حزمة \"مشغول\" أو \"تم رفض المكالمة\" إلى المتصل.\n\n### الأهداف المعمارية الرئيسية:\n*   **الرفض النشط مقابل التجاهل**: إذا قام مثيلك بمجرد تجاهل المكالمة، فسيستمر هاتف المتصل في الرنين لمدة 30-45 ثانية، مما يعطي انطباعاً بعدم الاستجابة أو الفشل التقني. الرفض عبر الواجهة يوفر إشارة فورية وحاسمة، وهو \"لياقة احترافية\" تتيح للمتصل البحث فوراً عن وسيلة بديلة للحل.\n*   **إدارة المقاطعة**: المكالمات أحداث تستهلك موارد الصوت والشبكة بكثافة. يضمن الرفض البرمجي تحرير هذه الموارد بأسرع وقت، مما يحافظ على استقرار المثيل للقيام بمهام أخرى متزامنة مثل [البث الجماعي](/v2/messaging).\n\n---\n\n## 🚀 حالات الاستخدام الاستراتيجي: فرض الحدود التشغيلية\n\nتعد الاتصالات الصوتية في الوقت الفعلي مكلفة. يتيح لك الرفض البرمجي إدارة هذه التكلفة مع الحفاظ على صورة علامة تجارية متميزة.\n\n### 1. محيط مكالمات الـ VIP فقط\nقد تختار مؤسستك تقديم الدعم الصوتي فقط للعملاء ذوي القيمة العالية. عند وصول مكالمة، يتحقق النظام من الـ CRM؛ وإذا كان المتصل من \"الفئة العادية\"، يرفض النظام المكالمة فوراً ويبدأ إعادة توجيه نصية: *\"نرى أنك تحاول الاتصال. الدعم الصوتي المباشر ميزة في خطتنا المميزة. يرجى متابعة طلبك هنا نصياً أو ترقية حسابك\"*. هذا يحول المكالمة المرفوضة إلى فرصة لزيادة المبيعات (Upsell).\n\n### 2. فرض \"ساعات النشاط\" العالمية\nعبر ربط واجهة رفض المكالمات بـ \"جدول زمني واعي بالمناطق الزمنية\"، يمكن لنظامك تلقائياً رفض المكالمات التي تصل خارج ساعات العمل في منطقة معينة، وتزويد المتصل برد سياقي: *\"مكتبنا في لندن مغلق حالياً. سنعود للعمل في الساعة 09:00 بتوقيت جرينتش. يمكنك ترك رسالة صوتية أو استخدام بوت الأسئلة الشائعة\"*.\n\n---\n\n## 🛡️ أفضل الممارسات التشغيلية: قواعد \"الخروج اللبق\"\n\n*   **تفويض المتابعة السياقية**: يجب ألا يكون الرفض البرمجي حدثاً مستقلاً أبداً. الهدف هو نقل المستخدم من قناة متزامنة (عالية التكلفة) إلى قناة غير متزامنة (منخفضة التكلفة). يجب أن يرسل نظامك رسالة نصية في غضون 500 ملّي ثانية من الرفض، تقر بالمكالمة وتوفر الخطوة التالية.\n*   **المعالجة المثلى للتأخير**: نافذة الرفض الاحترافي ضيقة. إذا استغرق نظامك أكثر من ثانية لمعالجة الويب هوك وإرسال أمر الرفض، فسيسمع المستخدم رنة أو رنتين، مما يخلق انطباعاً بوجود \"خلل\". تأكد من تحسين معالج الويب هوك لاتخاذ قرارات فائقة السرعة.\n            "
        }
      }
    }
  ]
}