واتساب API بلغة PHP: إرسال رسالة واتساب من PHP ولارافيل بمثال كامل
إرسال رسالة واتساب بلغة PHP عبر API الرسمي: دالة cURL واحدة لكل النداءات، وإرسال قالب معتمد والتعامل مع كل رد، والنص الحر وحالة الرسالة، ومثال لارافيل، والأخطاء الشائعة.
في هذه الصفحة 7
الإجابة المختصرة
لإرسال رسالة واتساب من PHP لا تحتاج إلى مكتبة: نداء cURL واحد إلى POST https://app.arabybot.com/api/v1/messages/template بمفتاحك في ترويسة Authorization وجسم JSON فيه رقم المستلم بكود الدولة واسم القالب المعتمد ومتغيراته. يعود الرد برقم الرسالة وحالتها، وحقل reference يمنع تكرارها إن أعاد نظامك الطلب. وفي لارافيل يكفي عميل Http بسطر واحد.
يُسأل عنها أيضًا: «whatsapp api php» · «ارسال رسالة واتساب php» · «كود php لارسال رسالة واتساب» · «ارسال واتساب من لارافيل»
ما تحتاجه قبل أول سطر
- رقم واتساب متصل بعربي بوت
على واجهة واتساب الرسمية، وعليه قالب معتمد واحد على الأقل. الرسائل تخرج من رقمك أنت، وتظهر في محادثة العميل داخل الدردشة المباشرة.
- باقة تشمل «أدوات المطورين»
«WhatsApp Pro» أو «WhatsApp Premium» أو «Complete Plan» أو «Ultimate Plan».
- مفتاح
أنشئه من صفحة «أدوات المطورين». يبدأ بـ
abk_ويظهر مرة واحدة، فانسخه إلى متغير البيئةARABYBOT_API_KEYعلى خادمك.
دالة واحدة لكل النداءات
الواجهة خمسة عناوين كلها تأخذ JSON وتعيده، فتكفيها دالة واحدة بـcURL. ومهلة عشرين ثانية تمنع أن يتعلق طلب في صفحتك إن تأخر الرد.
<?php
// One helper for every call. The key comes from the environment, never from the code.
function arabybot(string $method, string $path, ?array $body = null): array
{
$headers = ['Authorization: Bearer ' . getenv('ARABYBOT_API_KEY')];
$options = [
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 20,
];
if ($body !== null) {
$headers[] = 'Content-Type: application/json';
// JSON_UNESCAPED_UNICODE keeps Arabic values readable in your logs
$options[CURLOPT_POSTFIELDS] = json_encode($body, JSON_UNESCAPED_UNICODE);
}
$options[CURLOPT_HTTPHEADER] = $headers;
$ch = curl_init('https://app.arabybot.com/api/v1/' . ltrim($path, '/'));
curl_setopt_array($ch, $options);
$raw = curl_exec($ch);
curl_close($ch);
$answer = is_string($raw) ? json_decode($raw, true) : null;
return is_array($answer) ? $answer : ['success' => false, 'error_code' => 'NETWORK'];
}
// 1) does the key work, and which numbers does it send from?
$me = arabybot('GET', 'me');
// 2) the approved templates — each comes with a ready request body in "example"
$templates = arabybot('GET', 'templates'); رد templates يحمل مع كل قالب حقل example فيه جسم الطلب جاهزًا بأسماء الحقول التي يحتاجها ذلك القالب بعينه. ابدأ منه بدل أن تخمّن عدد المتغيرات.
إرسال قالب، والتعامل مع كل رد
<?php
$sent = arabybot('POST', 'messages/template', [
'to' => '201012345678', // with the country code
'template' => 'order_shipped',
'language' => 'ar',
'variables' => ['Ahmed', '1042'], // the template's {{1}}, {{2}} in order
'reference' => 'order-1042-shipped', // the same reference is never sent twice
]);
if (($sent['success'] ?? false) === true) {
// "accepted" = WhatsApp took it, "queued" = it waits its turn and goes out by itself
save_message_id($orderId, $sent['id']);
} elseif (in_array($sent['error_code'] ?? '', ['TRY_AGAIN', 'NETWORK'], true)) {
retry_later($orderId); // same request, same reference
} elseif (($sent['error_code'] ?? '') === 'UNCERTAIN') {
check_later($sent['id'] ?? null); // ask GET messages/{id} before sending again
} else {
error_log('ArabyBot ' . ($sent['error_code'] ?? '') . ': ' . ($sent['message_en'] ?? ''));
} ثلاثة أشياء في هذا الكود تفرق بين تجربة وبين نظام يعمل كل يوم. الأول حقل reference: إن أعاد نظامك الطلب بعد انقطاع فلن تصل الرسالة مرتين. والثاني أن TRY_AGAIN يُعاد بالطلب نفسه، وأن UNCERTAIN يُسأل عنه قبل الإعادة. والثالث أن بقية الرموز، كقالب لم يُعتمد أو عميل أوقف الرسائل التسويقية، لا تنفع معها إعادة فسجّلها وانتقل.
كل الحقول ورموز الرفض والحدود في مرجع واجهة الإرسال
النص الحر وحالة الرسالة
<?php
// a free-text reply, only inside 24 hours of the customer's last message
$reply = arabybot('POST', 'messages/text', [
'to' => '201012345678',
'text' => 'Your order 1042 is ready for pickup at the branch.',
]);
// where is message 512 now? queued · accepted · sent · delivered · read · failed
$status = arabybot('GET', 'messages/512');
if (($status['status'] ?? '') === 'failed') {
error_log('WhatsApp said: ' . ($status['error']['meta_code'] ?? '') . ' ' . ($status['error']['message'] ?? ''));
} النص الحر يُقبل خلال ٢٤ ساعة من آخر رسالة كتبها العميل فقط، وهذا شرط ميتا. وخارجها أرسل قالبًا. أما الحالة فاسأل عنها حين تحتاجها، ككتابة «تم التسليم» بجوار الطلب في لوحتك، ولا تسأل عن كل رسالة كل ثانية.
في لارافيل
<?php
// config/services.php → 'arabybot' => ['key' => env('ARABYBOT_API_KEY')],
use Illuminate\Support\Facades\Http;
$sent = Http::withToken(config('services.arabybot.key'))
->timeout(20)
->post('https://app.arabybot.com/api/v1/messages/template', [
'to' => $order->customer_phone,
'template' => 'order_shipped',
'language' => 'ar',
'variables' => [$order->customer_name, (string) $order->number],
'reference' => 'order-' . $order->id . '-shipped',
])
->json(); ضع هذا النداء داخل مهمة في الطابور لا داخل المتحكم، فيعود رد صفحتك للمستخدم فورًا وتُعاد المهمة وحدها عند TRY_AGAIN. والمرجع المبني من رقم الطلب يجعل إعادة المهمة آمنة.
أخطاء شائعة في PHP
| الخطأ | ما يحدث | الحل |
|---|---|---|
| المفتاح مكتوب في الكود | يتسرب مع أول نسخة للمستودع | متغير بيئة، وألغِ المفتاح إن ظهر في أي مكان عام |
| الرقم بلا كود الدولة | BAD_PHONE | خزّن الأرقام بالصيغة الدولية من البداية |
| متغيرات أقل من القالب | BAD_VALUES مع قائمة بما ينقص | اقرأ example من نداء القوالب |
| الإرسال من صفحة يفتحها المستخدم | إعادة تحميل الصفحة تكرر الطلب | مهمة في الخلفية ومعها reference |
| بلا مهلة | طلب معلّق يوقف الصفحة | CURLOPT_TIMEOUT |
الشرح نفسه بلغة بايثون · ومن Node.js · واجهة رموز التحقق OTP
الأسئلة الشائعة
هل أحتاج إلى مكتبة أو SDK لإرسال واتساب من PHP؟
لا. الواجهة نداءات HTTP عادية بجسم JSON، ويكفيها cURL الموجود في أي استضافة PHP، أو عميل Http في لارافيل.
هل يعمل الكود على استضافة مشتركة؟
نعم ما دامت إضافة cURL مفعّلة والاستضافة تسمح بالاتصال الخارجي عبر HTTPS، وهذا حال أغلب الاستضافات. ضع المفتاح في متغيرات البيئة أو في ملف خارج مجلد الموقع العام.
لماذا تصل الحروف العربية مشوّهة؟
في الغالب لأن الملف أو قاعدة البيانات ليس بترميز UTF-8. الواجهة تستقبل JSON بترميز UTF-8 وتعيده كذلك، فتأكد أن القيم التي تقرؤها من قاعدتك بالترميز نفسه قبل إرسالها.
كيف أرسل إلى مئات العملاء دفعة واحدة؟
أرسل كل رسالة بطلب مستقل ومرجع مختلف، ومن مهمة في الخلفية لا من صفحة يفتحها مستخدم. الواجهة تقبل ٦٠٠ طلب في الدقيقة لكل مفتاح، وما يزيد على سرعة رقمك عند واتساب ينتظر في الطابور ويُرسل وحده.
اقرأ بعدها
جرّب الوكيل قبل أن تدفع شيئًا
الوكيل الذي يرد على عملائك هو نفسه الذي يرد عليك الآن: اسأله من زر الدردشة هنا أو على واتساب. وحسابك مجاني بلا بطاقة ائتمان، والتجربة المجانية على رقمك أو صفحتك تُفعَّل بعد التواصل مع الإدارة على واتساب خدمة العملاء.