WhatsApp API برای توسعه‌دهندگان — بسازید، منتشر کنید، مقیاس دهید

یک WhatsApp API توسعه‌دهنده‌محور با endpointهای REST تمیز، webhook، نمونه کد در شش زبان و زیرساختی که با پروژه شما مقیاس می‌یابد.

اولین فراخوانی API شما

const response = await fetch('https://api2whats.com/send-text', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '971501234567',
    message: 'Hello from my app!'
  })
});
const data = await response.json();
console.log(data.id); // message ID

چرا توسعه‌دهندگان این API را انتخاب می‌کنند

بیشتر راه‌حل‌های WhatsApp API ابتدا برای کاربران غیرفنی و بعد برای توسعه‌دهندگان طراحی شده‌اند. مستندات کم‌مایه است، پیام‌های خطا بی‌فایده‌اند و شما زمان بیشتری را صرف جنگیدن با API می‌کنید تا ساختن با آن. ما این API برعکس ساختیم — اول توسعه‌دهنده، بقیه بعداً.

هر endpoint ساختاریافته JSON با کدهای خطای واضح برمی‌گرداند. هر درخواست قالب پاسخ قابل پیش‌بینی دارد. مستندات شامل نمونه کدهای قابل اجراست که می‌توانید بلافاصله کپی و اجرا کنید. و سیستم webhook پیام‌های ورودی را با payloadهای امضاشده به‌صورت real-time به سرور شما تحویل می‌دهد تا بتوانید اصالت آن‌ها را تأیید کنید.

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

نمای کلی معماری

API میان اپلیکیشن شما و سرورهای واتس‌اپ قرار دارد. وقتی پیامی ارسال می‌کنید، این اتفاقات می‌افتد:

  1. اپلیکیشن شما درخواست HTTP POST به endpoint API ارسال می‌کند
  2. API درخواست شما را با استفاده از کلید API در هدر Authorization احراز هویت می‌کند
  3. پیام به نمونه واتس‌اپ صحیح مسیریابی می‌شود (اگر چند نمونه داشته باشید)
  4. پیام از طریق اتصال دائمی WebSocket به واتس‌اپ تحویل داده می‌شود
  5. پاسخی حاوی شناسه پیام و وضعیت تحویل دریافت می‌کنید
  6. به‌روزرسانی‌های بعدی وضعیت (تحویل، خوانده شدن) به webhook شما ارسال می‌شود

کل رفت‌وبرگشت معمولاً کمتر از ۵۰ میلی‌ثانیه طول می‌کشد. مرورگری در میان نیست، نه پردازش اسکرین‌شات و نه دستکاری DOM. اتصال WebSocket دائمی است و اتصال مجدد، به‌روزرسانی احراز هویت و بازیابی از خطا را به‌طور خودکار مدیریت می‌کند.

مرجع REST API

همه endpointها از قراردادهای REST پیروی می‌کنند. درخواست‌ها از بدنه JSON استفاده می‌کنند. پاسخ‌ها JSON هستند. احراز هویت از طریق توکن‌های Bearer در هدر Authorization انجام می‌شود.

ارسال پیام

روشEndpointتوضیحات
POST/send-textارسال پیام متنی
POST/send-imageارسال تصویر (URL یا Base64)
POST/send-videoارسال ویدیو
POST/send-documentارسال سند یا فایل
POST/send-audioارسال فایل صوتی
POST/send-locationارسال نشانگر موقعیت مکانی
POST/send-stickerارسال استیکر

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

روشEndpointتوضیحات
GET/instance/statusبررسی وضعیت اتصال
POST/instance/connectدریافت کد QR برای اتصال
POST/instance/pairing-codeدریافت کد جفت‌سازی
POST/instance/disconnectقطع اتصال نمونه

Webhook‌ها

روشEndpointتوضیحات
POST/set-webhookتنظیم URL webhook خود
GET/get-webhookدریافت URL webhook فعلی

یکپارچه‌سازی Webhook

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

یک payload webhook به این شکل است:

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

کنترل‌کننده webhook شما این داده را پردازش می‌کند و می‌تواند هر پاسخ خودکاری را فعال کند. سیستم webhook از منطق تلاش مجدد پشتیبانی می‌کند — اگر سرور شما موقتاً در دسترس نباشد، API چندین بار پیش از رد کردن، تحویل را دوباره امتحان می‌کند.

برای امنیت، تمام payloadهای webhook شامل هدر X-Signature هستند که می‌توانید آن را تأیید کنید تا مطمئن شوید درخواست واقعاً از API ما آمده و نه از شخص ثالث.

نمونه کدها در شش زبان

برای هر عملیات رایج، نمونه کد قابل اجرا ارائه می‌دهیم. هر نمونه یک اسکریپت کامل و قابل اجراست — نه تکه‌کدی که شما را در مورد importها، مدیریت خطا یا پیکربندی معطل بگذارد.

PHP

<?php
$ch = curl_init('https://api2whats.com/send-text');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ***',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'to' => '971501234567',
        'message' => 'Hello from PHP!',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Python

import requests

response = requests.post(
    'https://api2whats.com/send-text',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'to': '971501234567',
        'message': 'Hello from Python!',
    }
)
print(response.json())

JavaScript (Node.js)

const response = await fetch('https://api2whats.com/send-text', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        to: '971501234567',
        message: 'Hello from Node.js!',
    }),
});
const data = await response.json();
console.log(data);

مدیریت خطا

API از کدهای وضعیت استاندارد HTTP استفاده می‌کند و پاسخ‌های خطای ساختاریافته برمی‌گرداند:

{
    "success": false,
    "error": {
        "code": "INSTANCE_DISCONNECTED",
        "message": "The WhatsApp instance is not connected"
    }
}

کدهای خطای رایج شامل:

  • 401 Unauthorized — کلید API نامعتبر یا ناموجود
  • 400 Bad Request — فیلدهای الزامی ناموجود یا داده نامعتبر
  • 404 Not Found — نمونه یا منبع وجود ندارد
  • 429 Too Many Requests — عبور از محدودیت نرخ
  • 500 Internal Server Error — خطایی از سمت ما رخ داده است (نادر)

امنیت Webhook

هر درخواست webhook شامل هدر X-Signature است که امضای HMAC-SHA256 بدنه درخواست را در خود دارد. کنترل‌کننده webhook شما باید این امضا را تأیید کند تا مطمئن شود درخواست واقعاً از API ما آمده و نه از شخص ثالث.

// Node.js webhook signature verification
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
    const expected = crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');
    return crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(expected)
    );
}

app.post('/webhook', (req, res) => {
    const sig = req.headers['x-signature'];
    const body = JSON.stringify(req.body);

    if (!verifySignature(body, sig, WEBHOOK_SECRET)) {
        return res.status(401).json({ error: 'Invalid signature' });
    }

    // Process the message...
    res.json({ success: true });
});

آزمایش و رفع اشکال

API چندین ابزار برای آزمایش و رفع اشکال یکپارچه‌سازی شما ارائه می‌دهد:

  • گزارش‌های داشبورد — مشاهده همه درخواست‌های API و پاسخ‌های آن‌ها به‌صورت real-time از داشبورد خود
  • endpoint آزمایش webhook — ارسال webhook آزمایشی برای اطمینان از کارکرد صحیح کنترل‌کننده شما
  • ردیابی وضعیت پیام — جست‌وجوی وضعیت هر پیام با شناسه آن
  • پایش نرخ خطا — ردیابی نرخ خطای API خود در طول زمان در داشبورد

توصیه می‌کنیم با یک نمونه آزمایشی متصل به شماره شخصی خود شروع کنید. پیام‌های آزمایشی بفرستید، webhookها را بررسی کنید و پیش از رفتن به ترافیک production، مدیریت خطا را کنترل کنید.

بهترین شیوه‌ها برای توسعه‌دهندگان

  • کلیدهای API را امن ذخیره کنید — از متغیرهای محیطی استفاده کنید، نه رشته‌های کدنویسی‌شده. هرگز کلیدهای API را در سیستم کنترل نسخه commit نکنید.
  • خطاها را با ظرافت مدیریت کنید — برای خطاهای گذرا (5xx، تایم‌اوت شبکه)، منطق تلاش مجدد با backoff نمایی پیاده‌سازی کنید.
  • امضاهای webhook را اعتبارسنجی کنید — هرگز به درخواست‌های webhook تأییدنشده اعتماد نکنید. همیشه هدر X-Signature را بررسی کنید.
  • از استخر اتصال استفاده کنید — اتصالات HTTP را بین درخواست‌ها به‌جای ساختن اتصال جدید برای هر فراخوانی API، دوباره استفاده کنید.
  • محدودیت‌های نرخ را پایش کنید — هدر X-RateLimit-Remaining را بررسی کنید و هنگام نزدیک شدن به محدودیت‌ها، محدودسازی پیشگیرانه پیاده‌سازی کنید.
  • همه چیز را ثبت کنید — جفت‌های درخواست/پاسخ را برای رفع اشکال ثبت کنید. داده‌های حساس (شماره تلفن‌ها، محتوای پیام‌ها) را در گزارش‌های production حذف کنید.

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

محدودیت‌های نرخ به‌ازای هر کلید API اعمال می‌شوند و بسته به طرح متفاوت‌اند. وقتی به محدودیت برسید، API کد وضعیت 429 با هدر Retry-After برمی‌گرداند. مقادیر پیش‌فرض:

  • طرح پایه — ۱۰۰ درخواست در دقیقه
  • طرح حرفه‌ای — ۳۰۰ درخواست در دقیقه
  • طرح سازمانی — ۱۰۰۰ درخواست در دقیقه

اگر مداوم به محدودیت‌های نرخ برخورد می‌کنید، ارتقای طرح خود یا گروه‌بندی درخواست‌ها در صورت امکان را در نظر بگیرید.

قالب‌های payload webhook

پیام‌های ورودی بسته به نوع پیام، در قالب‌های متفاوتی می‌رسند:

پیام متنی

{
  "event": "message",
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "from": "971501234567",
    "message": "Hello!",
    "type": "text",
    "timestamp": 1691234567
  }
}

پیام تصویری

{
  "event": "message",
  "data": {
    "id": "3EB0A1B2C3D4E5F7",
    "from": "971501234567",
    "type": "image",
    "caption": "Check this out!",
    "mediaUrl": "https://api2whats.com/media/...",
    "mimeType": "image/jpeg",
    "timestamp": 1691234568
  }
}

به‌روزرسانی وضعیت

{
  "event": "status",
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "status": "delivered",
    "timestamp": 1691234600
  }
}

مقادیر وضعیت شامل: sent (تحویل‌شده به واتس‌اپ)، delivered (رسیده به دستگاه) و read (باز شده توسط گیرنده).

شروع به کار

  1. ساخت حساب کاربری (رایگان، بدون کارت اعتباری)
  2. طرحی از صفحه تعرفه‌ها
  3. ساخت نمونه از داشبورد
  4. شماره تلفن خود را از طریق QR یا کد جفت‌سازی متصل کنید
  5. خواندن مستندات کامل API
  6. اولین پیام خود را بفرستید و ساختن را آغاز کنید

جامعه و پشتیبانی

به جامعه توسعه‌دهندگان ما بپیوندید تا کمک بگیرید، یکپارچه‌سازی‌هایتان را به اشتراک بگذارید و از قابلیت‌های جدید باخبر شوید. ما جامعه فعالی از توسعه‌دهندگانی داریم که در هر صنعتی در حال ساخت یکپارچه‌سازی‌های واتس‌اپ هستند.

  • مستندات — مرجع جامع API با نمونه‌های قابل اجرا
  • نمونه کدها — اسکریپت‌های کامل و قابل اجرا در PHP، Python، JavaScript و cURL
  • پشتیبانی ایمیلی — پاسخ ظرف ۲۴ ساعت برای همه سطوح طرح
  • گزارش‌های داشبورد — دید real-time نسبت به درخواست‌های API و تحویل‌های webhook
  • صفحه وضعیت — وضعیت زنده سیستم و سابقه حوادث

چه در حال ساخت اولین یکپارچه‌سازی واتس‌اپ خود باشید و چه در حال مقیاس‌دهی به یکپارچه‌سازی موجود، منابع و تیم پشتیبانی ما برای موفقیت شما اینجا هستند.

همین امروز ساختن را آغاز کنید

API تمیز، مستندات واقعی، نمونه کدهایی که واقعاً کار می‌کنند. یکپارچه‌سازی واتس‌اپ خود را در چند ساعت منتشر کنید، نه چند هفته.

ساخت حساب مطالعه مستندات