Αποστολή και λήψη μηνυμάτων WhatsApp από PHP και Laravel

Πώς λαμβάνετε μηνύματα WhatsApp στο Laravel;

Με ένα GET και ένα POST στην ίδια διαδρομή στο routes/api.php. Εκτελέστε πρώτα php artisan install:api, αν το αρχείο δεν υπάρχει. Τα API routes είναι stateless και βρίσκονται εκτός του web group, επομένως το POST της Meta δεν απορρίπτεται λόγω απουσίας token CSRF, όπως συμβαίνει σε route του routes/web.php.

Το GET απαντά στην επαλήθευση της Meta. Η Meta στέλνει hub.mode, hub.verify_token και hub.challenge, όμως η PHP μετατρέπει τις τελείες στα ονόματα των εισερχόμενων μεταβλητών σε κάτω παύλες, οπότε το Laravel βλέπει hub_mode, hub_verify_token και hub_challenge. Ο κώδικας που διαβάζει τα ονόματα με τελείες παίρνει null και δεν επαληθεύεται ποτέ. Επιστρέψτε το challenge ως απλό κείμενο, όχι μέσω response()->json().

Το POST παραδίδει το payload σε queued job και επιστρέφει αμέσως 200. Βάλτε ένα μακρύ τυχαίο κλειδί στη διαδρομή και ελέγξτε το και στα δύο routes: η Meta υπογράφει τις παραδόσεις με το app secret του Tech Provider, άρα η κεφαλίδα υπογραφής δεν μπορεί να επικυρωθεί από εσάς.

use App\Jobs\HandleWhatsAppEvent;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::get('/whatsapp/{key}', function (Request $request, string $key) {
    abort_unless(hash_equals(config('services.whatsapp.url_key'), $key), 404);

    // PHP turns hub.mode into hub_mode: read the underscored names
    if ($request->query('hub_mode') === 'subscribe'
        && hash_equals(config('services.whatsapp.verify_token'),
                       (string) $request->query('hub_verify_token'))) {
        return response((string) $request->query('hub_challenge'), 200)
            ->header('Content-Type', 'text/plain');
    }

    abort(403);
});

Route::post('/whatsapp/{key}', function (Request $request, string $key) {
    abort_unless(hash_equals(config('services.whatsapp.url_key'), $key), 404);

    HandleWhatsAppEvent::dispatch($request->json()->all());

    return response('', 200);
});

Πώς στέλνετε μήνυμα WhatsApp από το Laravel;

Με τον HTTP client του Laravel: ένα POST στο endpoint messages για το phone number id, με το access token ως bearer token. Και οι δύο τιμές προέρχονται από τη σύνδεση, εμφανίζονται στο dashboard και επιστρέφονται από το get_api_credentials, και ανήκουν στο config/services.php με μεταβλητές περιβάλλοντος και όχι μέσα στον κώδικα.

Η μορφή του σώματος εξαρτάται από τον χρόνο. Μέσα σε 24 ώρες από το τελευταίο μήνυμα του πελάτη λειτουργεί ένα αντικείμενο text, όπως παρακάτω. Εκτός αυτού του παραθύρου η Meta δέχεται μόνο αντικείμενο template που ονομάζει ένα εγκεκριμένο template και τη γλώσσα του, ενώ το ελεύθερο κείμενο αποτυγχάνει με το σφάλμα 131047. Η απόκριση είναι το σημείο όπου θα το δείτε: μια αποτυχημένη κλήση επιστρέφει αντικείμενο error, του οποίου ο κωδικός δείχνει τι πήγε στραβά, γι' αυτό καταγράψτε το αντί να το πετάτε.

Τίποτα στο αίτημα δεν αφορά αποκλειστικά το EasyCoexistence. Είναι η κλήση της τεκμηρίωσης της ίδιας της Meta, οπότε κάθε HTTP client της PHP, το Guzzle ή το απλό cURL, λειτουργεί με τον ίδιο τρόπο.

use Illuminate\Support\Facades\Http;

$response = Http::withToken(config('services.whatsapp.token'))
    ->post('https://graph.facebook.com/v25.0/'
        . config('services.whatsapp.phone_number_id') . '/messages', [
        'messaging_product' => 'whatsapp',
        'to' => '14155550188', // digits only, with country code
        'type' => 'text',
        'text' => ['body' => 'Thanks, we are on it.'],
    ]);

if ($response->failed()) {
    // error.code 131047: outside the window, send a template instead
    logger()->warning('WhatsApp send failed', $response->json('error', []));
}

Τι χρειάζεται ένας handler Laravel παραγωγής πέρα από αυτά;

Πραγματική ουρά, αποσυσσώρευση διπλότυπων και έλεγχο του παραθύρου.

Η ουρά έχει σημασία επειδή η Meta ξαναστέλνει όταν η απόκριση αργεί. Το HandleWhatsAppEvent::dispatch() επιστρέφει γρήγορα μόνο όταν η σύνδεση ουράς είναι πραγματική και τρέχει worker. Με τον driver sync η εργασία εκτελείται μέσα στο αίτημα, και μια αργή κλήση μοντέλου ή εγγραφή στη βάση καταλήγει σε διπλή παράδοση.

Εντοπίστε τα διπλότυπα με βάση το id του μηνύματος, το wamid κάθε μηνύματος, επειδή οι επαναλήψεις είναι φυσιολογικές και όχι εξαίρεση. Αρκεί ένας μοναδικός δείκτης σε αυτή τη στήλη ή ένα cache lock με αυτό το κλειδί.

Τέλος, αποθηκεύετε πότε έγραψε τελευταία φορά κάθε επαφή. Με αυτή την ημερομηνία η διαδρομή αποστολής επιλέγει μόνη της text ή template, αντί να το μαθαίνει από το σφάλμα 131047 όταν ο πελάτης περιμένει ήδη. Οι απαντήσεις που πληκτρολογούνται στο κινητό, στην εφαρμογή WhatsApp Business, φτάνουν ως echo events στο ίδιο route, ώστε ο handler να βλέπει και πότε ένας άνθρωπος ανέλαβε τη συνομιλία.

Συνηθισμένα λάθη

• Ανάγνωση του hub.challenge με τελεία. Η PHP το μετονόμασε σε hub_challenge, οπότε ο handler επιστρέφει κενό σώμα και η Meta δεν επαληθεύει ποτέ.
• Τοποθέτηση του webhook στο routes/web.php. Το POST της Meta δεν έχει token CSRF και απορρίπτεται με 419.
• Αποστολή στην ουρά sync. Η εργασία εκτελείται πριν από το 200, η αργή επεξεργασία ξαναστέλνεται και τα μηνύματα επεξεργάζονται δύο φορές.
• Επιστροφή του challenge με response()->json(). Τα εισαγωγικά γύρω από την τιμή αποτυγχάνουν στον έλεγχο της Meta.

Συχνές ερωτήσεις

Συνεχίστε την ανάγνωση