التكاملات

واتساب API بلغة PHP: إرسال رسالة واتساب من PHP ولارافيل بمثال كامل

إرسال رسالة واتساب بلغة PHP عبر API الرسمي: دالة cURL واحدة لكل النداءات، وإرسال قالب معتمد والتعامل مع كل رد، والنص الحر وحالة الرسالة، ومثال لارافيل، والأخطاء الشائعة.

8 دقائق قراءة آخر تحديث 15 نوفمبر 2026 فريق عربي بوت
فريق عربي بوتشريك Meta الرسمي · نكتب من بيانات منصتنا
في هذه الصفحة 7
  1. ما تحتاجه قبل أول سطر
  2. دالة واحدة لكل النداءات
  3. إرسال قالب، والتعامل مع كل رد
  4. النص الحر وحالة الرسالة
  5. في لارافيل
  6. أخطاء شائعة في PHP
  7. الأسئلة الشائعة

الإجابة المختصرة

لإرسال رسالة واتساب من PHP لا تحتاج إلى مكتبة: نداء cURL واحد إلى POST https://app.arabybot.com/api/v1/messages/template بمفتاحك في ترويسة Authorization وجسم JSON فيه رقم المستلم بكود الدولة واسم القالب المعتمد ومتغيراته. يعود الرد برقم الرسالة وحالتها، وحقل reference يمنع تكرارها إن أعاد نظامك الطلب. وفي لارافيل يكفي عميل Http بسطر واحد.

يُسأل عنها أيضًا: «whatsapp api php» · «ارسال رسالة واتساب php» · «كود php لارسال رسالة واتساب» · «ارسال واتساب من لارافيل»

ما تحتاجه قبل أول سطر

  1. رقم واتساب متصل بعربي بوت

    على واجهة واتساب الرسمية، وعليه قالب معتمد واحد على الأقل. الرسائل تخرج من رقمك أنت، وتظهر في محادثة العميل داخل الدردشة المباشرة.

  2. باقة تشمل «أدوات المطورين»

    «WhatsApp Pro» أو «WhatsApp Premium» أو «Complete Plan» أو «Ultimate Plan».

  3. مفتاح

    أنشئه من صفحة «أدوات المطورين». يبدأ بـ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

الأسئلة الشائعة

1

هل أحتاج إلى مكتبة أو SDK لإرسال واتساب من PHP؟

لا. الواجهة نداءات HTTP عادية بجسم JSON، ويكفيها cURL الموجود في أي استضافة PHP، أو عميل Http في لارافيل.

2

هل يعمل الكود على استضافة مشتركة؟

نعم ما دامت إضافة cURL مفعّلة والاستضافة تسمح بالاتصال الخارجي عبر HTTPS، وهذا حال أغلب الاستضافات. ضع المفتاح في متغيرات البيئة أو في ملف خارج مجلد الموقع العام.

3

لماذا تصل الحروف العربية مشوّهة؟

في الغالب لأن الملف أو قاعدة البيانات ليس بترميز UTF-8. الواجهة تستقبل JSON بترميز UTF-8 وتعيده كذلك، فتأكد أن القيم التي تقرؤها من قاعدتك بالترميز نفسه قبل إرسالها.

4

كيف أرسل إلى مئات العملاء دفعة واحدة؟

أرسل كل رسالة بطلب مستقل ومرجع مختلف، ومن مهمة في الخلفية لا من صفحة يفتحها مستخدم. الواجهة تقبل ٦٠٠ طلب في الدقيقة لكل مفتاح، وما يزيد على سرعة رقمك عند واتساب ينتظر في الطابور ويُرسل وحده.

فريق عربي بوتشريك Meta الرسمي للأعمال في الشرق الأوسط 239 دليلًا أرقام من منصتنا كل الأدلة

كيف نكتب هذه الأدلة الأرقام من منصتنا وفواتير ميتا الفعلية ومؤرّخة بعيّنتها، والوصف لما يعمل اليوم لا لما نعد به، ونذكر ما لا نفعله ومتى يكون غيرنا الخيار الأفضل. راجعه فريق عربي بوت في 15 نوفمبر 2026.

شارك الدليل
وتديره كله من موبايلككل ما في هذه الصفحة تديره من تطبيق عربي بوت على جوالك — الردود والطلبات والحملات وتقارير الذكاء الاصطناعي. لا لوحة تحكم على الويب فحسب.

جرّب الوكيل قبل أن تدفع شيئًا

الوكيل الذي يرد على عملائك هو نفسه الذي يرد عليك الآن: اسأله من زر الدردشة هنا أو على واتساب. وحسابك مجاني بلا بطاقة ائتمان، والتجربة المجانية على رقمك أو صفحتك تُفعَّل بعد التواصل مع الإدارة على واتساب خدمة العملاء.