ربط واتساب API مع Laravel — إرسال رسائل التحقق OTP بسهولة

أضف مفتاح الـ API الخاص بك ورابط الخدمة إلى ملف .env ثم مررهما في config/services.php:

# .env
EZYCODE_API_KEY=ezk_live_xxxxxxxxxxxxxxxxxxxx
EZYCODE_API_URL=https://connect-dashboard.ezycode.dev/connect/v1

// config/services.php
return [
    // ...
    'ezycode' => [
        'api_key' => env('EZYCODE_API_KEY'),
        'base_url' => env('EZYCODE_API_URL', 'https://connect-dashboard.ezycode.dev/connect/v1'),
    ],
];

كلاس خدمة متوافق مع Laravel 10/11/12 يستخدم واجهة Http Client المدمجة مع ترويسة Idempotency-Key لمنع تكرار الإرسال بالخطأ:

<?php

namespace App\Services;

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Str;

class WhatsAppService
{
    protected string $baseUrl;
    protected string $apiKey;

    public function __construct()
    {
        $this->baseUrl = config('services.ezycode.base_url');
        $this->apiKey = config('services.ezycode.api_key');
    }

    /**
     * Send OTP Verification Message
     *
     * @param string $phone E.164 formatted number (e.g. +201000000000)
     * @param string $otpCode 6-digit code
     * @return array
     */
    public function sendOtp(string $phone, string $otpCode): array
    {
        $idempotencyKey = 'otp_' . Str::uuid();

        $response = Http::withToken($this->apiKey)
            ->withHeaders([
                'Idempotency-Key' => $idempotencyKey,
                'Content-Type'    => 'application/json',
                'Accept'          => 'application/json',
            ])
            ->timeout(10)
            ->post("{$this->baseUrl}/messages", [
                'to'   => $phone,
                'type' => 'text',
                'text' => "رمز التحقق الخاص بك في منصتنا هو: {$otpCode}. لا تشاركه مع أي شخص.",
            ]);

        if ($response->failed()) {
            Log::error('EzyCode WhatsApp OTP dispatch failed', [
                'status' => $response->status(),
                'body'   => $response->json(),
            ]);

            return [
                'success' => false,
                'status'  => $response->status(),
                'error'   => $response->json('message') ?? 'Connection failed',
            ];
        }

        return [
            'success'    => true,
            'message_id' => $response->json('data.id'),
            'status'     => $response->json('data.status'),
        ];
    }
}

نموذج كامل لتوليد رمز عشوائي مكون من 6 أرقام، حفظه في الكاش لمدة 5 دقائق، وإرساله فوراً للمستخدم:

<?php

namespace App\Http\Controllers\Auth;

use App\Http\Controllers\Controller;
use App\Services\WhatsAppService;
use Illuminate\Http\Request;

class WhatsAppOtpController extends Controller
{
    public function requestOtp(Request $request, WhatsAppService $whatsApp)
    {
        $validated = $request->validate([
            'phone' => ['required', 'string', 'regex:/^\+[1-9]\d{1,14}$/'],
        ]);

        $otp = (string) random_int(100000, 999999);
        cache()->put('otp_' . $validated['phone'], $otp, now()->addMinutes(5));

        $result = $whatsApp->sendOtp($validated['phone'], $otp);

        if (!$result['success']) {
            return response()->json([
                'error' => 'تعذر إرسال رمز التحقق. يرجى المحاولة لاحقاً.'
            ], 422);
        }

        return response()->json([
            'message' => 'تم إرسال رمز التحقق بنجاح عبر واتساب',
            'message_id' => $result['message_id'],
        ]);
    }
}

استقبل أحداث تسليم الرسائل وقراءتها لحظياً، وتأكد من أمان الطلب عبر التحقق من توقيع HMAC-SHA256:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;

class EzyCodeWebhookController extends Controller
{
    public function handle(Request $request)
    {
        $signature = $request->header('X-EzyCode-Signature');
        $secret = config('services.ezycode.webhook_secret');

        if ($secret && $signature) {
            $expected = hash_hmac('sha256', $request->getContent(), $secret);
            if (!hash_equals($expected, $signature)) {
                return response()->json(['error' => 'Invalid signature'], 401);
            }
        }

        $event = $request->input('event');
        $data = $request->input('data');

        Log::info("EzyCode Webhook Received: {$event}", $data);

        // Update message status in your database: sent, delivered, read, failed
        return response()->json(['status' => 'acknowledged'], 200);
    }
}