WhatsApp-viestien lähetys ja vastaanotto PHP:llä ja Laravelilla

Miten WhatsApp-viestit vastaanotetaan Laravelissa?

GET- ja POST-reitillä samalla polulla tiedostossa routes/api.php. Aja ensin php artisan install:api, jos tiedostoa ei ole. API-reitit ovat tilattomia ja web-ryhmän ulkopuolella, joten Metan POST-pyyntöä ei hylätä puuttuvan CSRF-tokenin vuoksi, kuten käy reitillä routes/web.php.

GET vastaa Metan vahvistukseen. Meta lähettää arvot hub.mode, hub.verify_token ja hub.challenge, mutta PHP muuttaa saapuvien muuttujien nimissä pisteet alaviivoiksi, joten Laravel näkee nimet hub_mode, hub_verify_token ja hub_challenge. Koodi, joka lukee pisteelliset nimet, saa arvon null eikä vahvistu koskaan. Palauta challenge tavallisena tekstinä, älä response()->json()-kutsulla.

POST antaa payloadin jonotettavalle työlle ja palauttaa heti 200. Laita polkuun pitkä satunnainen avain ja tarkista se molemmilla reiteillä: Meta allekirjoittaa lähetykset Tech Providerin sovelluksen salaisella avaimella, joten allekirjoitusotsikkoa ei voi vahvistaa sinun päässäsi.

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);
});

Miten WhatsApp-viesti lähetetään Laravelista?

Laravelin HTTP-asiakkaalla: yksi POST numeron phone number id:n messages-päätepisteeseen, access token Bearer-tokenina. Molemmat arvot tulevat yhteydestä, näkyvät hallintapaneelissa ja palautuvat get_api_credentials-kutsulla. Ne kuuluvat tiedostoon config/services.php ympäristömuuttujien taakse, ei koodiin.

Pyynnön rungon muoto riippuu ajoituksesta. Asiakkaan viimeisestä viestistä 24 tunnin sisällä käy `text`-objekti, kuten alla. Ikkunan jälkeen Meta hyväksyy vain viestipohjaobjektin, jossa on hyväksytyn viestipohjan nimi ja kieli, ja vapaa teksti epäonnistuu virheeseen 131047. Vastauksesta asian näkee: epäonnistunut kutsu palauttaa error-objektin, jonka code kertoo, mikä meni vikaan, joten kirjaa se lokiin äläkä heitä pois.

Mikään pyynnössä ei ole EasyCoexistencelle ominaista. Se on Metan oman dokumentaation kutsu, joten mikä tahansa PHP:n HTTP-asiakas, Guzzle tai pelkkä cURL, toimii samalla tavalla.

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', []));
}

Mitä tuotantokäyttöinen Laravel-käsittelijä tarvitsee lisäksi?

Oikean jonon, kaksoiskäsittelyn eston ja ikkunatarkistuksen.

Jono on tärkeä, koska Meta yrittää hidasta vastausta uudelleen. HandleWhatsAppEvent::dispatch() palaa nopeasti vain, kun jonoyhteys on oikea ja worker on käynnissä. Sync-ajurilla työ suoritetaan pyynnön sisällä, ja hidas mallikutsu tai tietokantakirjoitus muuttuu kaksoistoimitukseksi.

Estä kaksoiskäsittely viestin tunnisteen, kunkin viestin wamidin, perusteella, koska uudelleenyritykset ovat normaaleja eivätkä poikkeuksia. Riittää uniikki indeksi tälle sarakkeelle tai sen mukaan avainnettu välimuistilukko.

Tallenna myös, milloin kukin yhteystieto kirjoitti viimeksi. Tämän aikaleiman avulla lähetyspolku valitsee tekstin tai viestipohjan itse, eikä asia selviä vasta virheestä 131047, kun asiakas on jo odottanut. WhatsApp Business -sovelluksessa puhelimella kirjoitetut vastaukset saapuvat echo-tapahtumina samalle reitille, joten käsittelijä näkee myös, milloin ihminen on ottanut keskustelun hoitaakseen.

Yleiset virheet

• hub.challenge luetaan pisteellä. PHP nimesi sen uudelleen hub_challengeksi, joten käsittelijä palauttaa tyhjän rungon eikä Meta vahvista koskaan.
• Webhook on laitettu tiedostoon routes/web.php. Metan POSTissa ei ole CSRF-tokenia, ja se hylätään virheellä 419.
• Työ lähetetään sync-jonoon. Työ ajetaan ennen 200-vastausta, hidas käsittely yritetään uudelleen ja viestit käsitellään kahdesti.
• Challenge palautetaan response()->json()-kutsulla. Arvon ympärillä olevat lainausmerkit rikkovat Metan tarkistuksen.

Usein kysytyt kysymykset

Lue lisää