مستندات WhatsApp API

مرجع کامل WhatsApp REST API. احراز هویت، endpoint‌ها، webhook‌ها، کدهای خطا و نمونه کدها.

احراز هویت

همه درخواست‌های API به کلید API ارسالی در هدر Authorization نیاز دارند. کلید API شما هنگام ساخت نمونه تولید می‌شود و در داشبورد شما قابل مشاهده است.

Authorization: Bearer YOUR_API_KEY

درخواست‌های بدون کلید API معتبر، خطای 401 Unauthorized برمی‌گردانند. کلیدهای API محدود به نمونه‌ها هستند — هر نمونه کلید مخصوص خود را دارد.

URL پایه

https://api2whats.com

همه endpoint‌ها نسبت به این URL پایه هستند. فقط از HTTPS استفاده کنید — درخواست‌های HTTP رد می‌شوند.

ارسال پیام متنی

ارسال پیام متنی به یک شماره واتس‌اپ.

POST /send-text

بدنه درخواست:

{
  "to": "971501234567",
  "message": "Hello from the API!"
}

پارامترها:

• to (رشته، الزامی) — شماره تلفن گیرنده با کد کشور، بدون + یا فاصله
• message (رشته، الزامی) — محتوای متنی، از Unicode و ایموجی پشتیبانی می‌کند

پاسخ:

{
  "success": true,
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "status": "sent"
  }
}

ارسال تصویر

ارسال تصویر از طریق URL یا Base64.

POST /send-image

{
  "to": "971501234567",
  "image": "https://example.com/photo.jpg",
  "caption": "Check out this product!"
}

پارامترها:

• to (رشته، الزامی) — شماره تلفن گیرنده
• image (رشته، الزامی) — URL تصویر یا رشته کدگذاری‌شده با Base64
• caption (رشته، اختیاری) — زیرنویس متنی زیر تصویر

ارسال ویدیو

ارسال فایل ویدیویی.

POST /send-video

{
  "to": "971501234567",
  "video": "https://example.com/demo.mp4",
  "caption": "Product demo video"
}

ارسال صدا

ارسال فایل صوتی (پیام صوتی یا کلیپ صوتی).

POST /send-audio

{
  "to": "971501234567",
  "audio": "https://example.com/voice.mp3"
}

ارسال استیکر

ارسال تصویر استیکر (قالب WebP یا PNG).

POST /send-sticker

{
  "to": "971501234567",
  "sticker": "https://example.com/sticker.webp"
}

ارسال سند

ارسال فایل پیوست (PDF، DOCX، XLSX و غیره).

POST /send-document

{
  "to": "971501234567",
  "document": "https://example.com/invoice.pdf",
  "filename": "invoice-march-2026.pdf"
}

پارامترها:

• to (رشته، الزامی) — شماره تلفن گیرنده
• document (رشته، الزامی) — URL سند یا رشته کدگذاری‌شده با Base64
• filename (رشته، اختیاری) — نام فایل نمایشی (پیش‌فرض: نام فایل URL)

ارسال موقعیت مکانی

ارسال نشانگر موقعیت جغرافیایی.

POST /send-location

{
  "to": "971501234567",
  "latitude": 25.2048,
  "longitude": 55.2708,
  "name": "Dubai Office"
}

پیکربندی Webhook

webhook‌ها به سرور شما امکان می‌دهند پیام‌های ورودی را در زمان واقعی (real-time) دریافت کند. URL webhook خود را از طریق API تنظیم کنید:

POST /set-webhook

{
  "url": "https://yourserver.com/webhook"
}

وقتی کسی به شماره متصل شما پیامی بفرستد، API یک درخواست POST به URL شما ارسال می‌کند:

{
  "event": "message",
  "instance": "instance_abc123",
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "from": "971501234567",
    "message": "Hi, I need help",
    "timestamp": 1691234567,
    "type": "text"
  }
}

webhook‌های ورودی را با استفاده از هدر X-Signature که همراه هر درخواست ارسال می‌شود، تأیید کنید.

مدیریت نمونه‌ها

وضعیت اتصال نمونه واتس‌اپ خود را بررسی کنید:

GET /instance/status

پاسخ:
{
  "connected": true,
  "phone": "971501234567",
  "name": "Business Account"
}

کدهای خطا

محدودیت نرخ

محدودیت نرخ بسته به طرح متفاوت است:

• Basic — ۱۰۰ درخواست در دقیقه
• Professional — ۳۰۰ درخواست در دقیقه
• Enterprise — ۱۰۰۰ درخواست در دقیقه

وقتی محدودیت نرخ فعال شود، API کد 429 Too Many Requests را با هدر Retry-After که نشان می‌دهد چه زمانی می‌توانید دوباره تلاش کنید، برمی‌گرداند.

نمونه کدها

نمونه‌های کاربردی در PHP، Python، JavaScript و cURL در بخش نمونه کدهای ما موجود است. هر نمونه یک اسکریپت کامل و قابل اجراست.

صفحه‌بندی و محدودیت‌ها

هنگام فهرست کردن منابع (نمونه‌ها، تاریخچه پیام‌ها)، API صفحه‌بندی را از طریق پارامترهای query پشتیبانی می‌کند:

GET /messages?page=1&limit=50

پاسخ:
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 342,
    "pages": 7
  }
}

اندازه پیش‌فرض صفحه ۵۰ است. حداکثر ۱۰۰. از پارامترهای query به نام page و limit برای مرور نتایج استفاده کنید.

ارسال گروهی

ارسال پیام به چند گیرنده در یک فراخوانی API. این روش کارآمدتر از ارسال درخواست‌های جداگانه برای هر گیرنده است.

POST /send-batch

{
  "messages": [
    { "to": "971501234567", "message": "Hello Ahmed!" },
    { "to": "971509876543", "message": "Hello Sara!" },
    { "to": "971501112222", "message": "Hello Omar!" }
  ]
}

ارسال گروهی به‌طور خودکار محدودیت نرخ را اعمال می‌کند. پاسخ شامل وضعیت هر پیام است تا بدانید کدام پیام‌ها موفق و کدام ناموفق بوده‌اند.

دستورالعمل بارگذاری رسانه

هنگام ارسال رسانه، برای تحویل بهینه این دستورالعمل‌ها را رعایت کنید:

• Images — JPEG یا PNG، حداکثر ۵ مگابایت از طریق Base64، بزرگ‌تر از طریق URL. ابعاد پیشنهادی: 1200x630 برای افقی، 600x600 برای مربع.
• Videos — قالب MP4، حداکثر ۱۶ مگابایت. کدگذاری H.264 برای بهترین سازگاری پیشنهاد می‌شود.
• Documents — PDF، DOCX، XLSX، PPTX، TXT. حداکثر ۱۰۰ مگابایت از طریق URL.
• Audio — قالب MP3 یا OGG. حداکثر ۱۶ مگابایت.
• Stickers — WebP یا PNG، 512x512 پیکسل، حداکثر ۵۰۰ کیلوبایت.
• Locations — مختصات عرض/طول جغرافیایی همراه با نام و نشانی اختیاری.

برای کدگذاری Base64، پیشوند data URI را قرار دهید: data:image/jpeg;base64,/9j/4AAQ.... برای URLها، مطمئن شوید URL به‌صورت عمومی قابل دسترسی است و هدر Content-Type صحیح را برمی‌گرداند.

متغیرهای محیطی

کلید API و پیکربندی خود را در متغیرهای محیطی ذخیره کنید، نه در کد:

# .env file
WHATSAPP_API_KEY=your_api_key_here
WHATSAPP_API_BASE=https://api2whats.com
WEBHOOK_SECRET=your_webhook_secret_here

هرگز فایل .env خود را در سیستم کنترل نسخه commit نکنید. آن را به .gitignore اضافه کنید. برای محیط production از تنظیمات متغیر محیطی پلتفرم استقرار خود استفاده کنید.

نسخه‌بندی

نسخه API از طریق مسیر URL مدیریت می‌شود. نسخه فعلی v1 است (پیش‌فرض). وقتی تغییرات ناسازگار معرفی کنیم، نسخه جدیدی منتشر کرده و نسخه قبلی را حداقل ۱۲ ماه نگه می‌داریم.

# Current version (implicit)
https://api2whats.com/send-text

# Explicit version (future-proof)
https://api2whats.com/v1/send-text

گزارش تغییرات

ما گزارش تغییرات عمومی برای همه تغییرات API نگه می‌داریم. برای اطلاع از آخرین اخبار، فید RSS گزارش تغییرات را دنبال کنید یا ما را در GitHub دنبال کنید. تغییرات عمده حداقل ۳۰ روز پیش از استقرار از طریق ایمیل به همه کاربران ثبت‌نام‌شده اعلام می‌شود.

به کمک نیاز دارید؟

برای سوالات رایج، سوالات متداول را بررسی کنید. برای مسائل خاص، با تیم پشتیبانی ما تماس بگیرید. ما ظرف ۲۴ ساعت پاسخ می‌دهیم.

سوالات متداول

حداکثر طول پیام چقدر است؟

پیام‌های متنی تا ۴٬۰۹۶ نویسه را پشتیبانی می‌کنند. برای محتوای طولانی‌تر، ارسال یک سند یا تقسیم پیام در چند ارسال را در نظر بگیرید.

آیا می‌توانم به گروه‌ها پیام بفرستم؟

در حال حاضر، API فقط از پیام‌رسانی یک‌به‌یک پشتیبانی می‌کند. پیام‌رسانی گروهی در نقشه راه ما برای نسخه‌های آینده قرار دارد.

پیام‌ها با چه سرعتی تحویل داده می‌شوند؟

بیشتر پیام‌ها ظرف ۱ تا ۳ ثانیه تحویل داده می‌شوند. زمان تحویل به اتصال شبکه گیرنده و وضعیت دستگاه او بستگی دارد. پیام‌های ارسالی به دستگاه‌های آفلاین توسط واتس‌اپ در صف قرار می‌گیرند و با آنلاین شدن دستگاه تحویل داده می‌شوند.

آیا سطح رایگان وجود دارد؟

می‌توانید به‌صورت رایگان حساب بسازید و داشبورد را کاوش کنید. طرح‌های پولی برای دسترسی به API و ارسال پیام از $9.99 در ماه شروع می‌شوند. برای دسترسی آزمایشی با ما تماس بگیرید.

اگر کلید API من به خطر بیفتد چه می‌شود؟

بلافاصله کلید به‌خطرافتاده را از داشبورد خود لغو کنید و کلید جدیدی بسازید. همه نشست‌های فعالی که از کلید قدیمی استفاده می‌کنند خاتمه می‌یابند. توصیه می‌کنیم کلیدهای API را به‌طور دوره‌ای عوض کنید و آن‌ها را در متغیرهای محیطی ذخیره نمایید.

آیا می‌توانم از API برای پیام‌رسانی انبوه استفاده کنم؟

Yes, with proper rate limiting. Send messages with 2-3 second delays between them. Do not send identical messages to large groups — personalize each message. Monitor delivery rates and slow down if they drop below 90%. docspage.faq.a6.link

صفحه وضعیت

وضعیت سیستم و سابقه آپ‌تایم ما را در صفحه وضعیت بررسی کنید. در طول حوادث، به‌روزرسانی‌های لحظه‌ای ارائه می‌دهیم و برای هرگونه اختلال در سرویس، تحلیل تفصیلی منتشر می‌کنیم.