Magpadala at tumanggap ng WhatsApp mula sa PHP at Laravel

Paano tumanggap ng mga mensahe sa WhatsApp sa Laravel?

Gumamit po ng isang GET at isang POST sa iisang path sa routes/api.php. Patakbuhin muna ang php artisan install:api kung wala pa ang file. Stateless ang mga API route at nasa labas ng web group, kaya hindi tinatanggihan ang POST ng Meta dahil sa kulang na CSRF token, na siyang nangyayari sa route na nasa routes/web.php.

Ang GET ang sumasagot sa verification ng Meta. Nagpapadala ang Meta ng hub.mode, hub.verify_token at hub.challenge, pero ginagawang underscore ng PHP ang mga tuldok sa pangalan ng papasok na variable, kaya hub_mode, hub_verify_token at hub_challenge ang nakikita ng Laravel. Ang code na bumabasa ng mga pangalang may tuldok ay nakakakuha ng null at hindi kailanman nagve-verify. Ibalik ang challenge bilang plain text, hindi sa pamamagitan ng response()->json().

Ang POST ay ipinapasa ang payload sa isang queued job at agad na nagbabalik ng 200. Maglagay ng mahaba at random na key sa path at i-check ito sa parehong route: pinipirmahan ng Meta ang mga delivery gamit ang app secret ng Tech Provider, kaya hindi ma-validate sa inyong panig ang signature header.

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

Paano magpadala ng mensahe sa WhatsApp mula sa Laravel?

Gamit ang HTTP client ng Laravel: isang POST sa messages endpoint para sa phone number id, na ang access token ay ipinapadala bilang bearer token. Ang dalawang value ay galing sa koneksyon, makikita sa dashboard at ibinabalik ng get_api_credentials, at dapat nasa config/services.php na nakabatay sa mga environment variable at hindi nasa mismong code.

Nakasalalay sa oras ang hugis ng body. Sa loob ng 24 oras mula sa huling mensahe ng customer, gumagana ang text object, tulad ng nasa ibaba. Sa labas ng window na iyon, template object lamang ang tinatanggap ng Meta, na may pangalan ng aprubadong template at ng wika nito, at pumapalya ang free-form text na may error 131047. Ang response ang dapat tingnan: ang bigong call ay nagbabalik ng error object na ang code ay nagsasabi kung ano ang nagkamali, kaya i-log po ito sa halip na itapon.

Walang bahagi ng request na espesipiko sa EasyCoexistence. Ito ang mismong call sa dokumentasyon ng Meta, kaya pareho ang takbo sa anumang PHP HTTP client, Guzzle man o simpleng 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', []));
}

Ano pa ang kailangan ng production Laravel handler bukod dito?

Isang tunay na queue, deduplication, at pag-check ng window.

Mahalaga ang queue dahil nire-retry ng Meta ang mabagal na response. Mabilis lang na nagbabalik ang HandleWhatsAppEvent::dispatch() kapag tunay na queue connection ang gamit at may worker na tumatakbo. Sa sync driver, tumatakbo ang job sa loob mismo ng request, at ang mabagal na model call o database write ay nauuwi sa duplicate na delivery.

Mag-deduplicate po ayon sa message id, ang wamid sa bawat mensahe, dahil normal ang mga retry at hindi eksepsyon. Sapat na ang unique index sa column na iyon, o cache lock na nakabatay dito.

At i-store kung kailan huling sumulat ang bawat contact. Sa timestamp na iyon, ang send path na mismo ang pipili ng text o template, sa halip na malaman pa mula sa error 131047 kung kailan naghihintay na ang customer. Ang mga sagot na tinype sa telepono sa WhatsApp Business app ay dumarating bilang echo event sa parehong route, kaya makikita rin ng handler kapag may taong pumalit na sa isang usapan.

Mga karaniwang pagkakamali

• Pagbasa ng hub.challenge na may tuldok. Pinalitan ito ng PHP bilang hub_challenge, kaya walang laman ang ibinabalik ng handler at hindi kailanman nagve-verify ang Meta.
• Paglalagay ng webhook sa routes/web.php. Walang CSRF token ang POST ng Meta kaya tinatanggihan ito ng 419.
• Pag-dispatch sa sync queue. Tumatakbo ang job bago ang 200, nire-retry ang mabagal na pagproseso, at dalawang beses napoproseso ang mga mensahe.
• Pagbabalik ng challenge gamit ang response()->json(). Pumapalya sa check ng Meta ang mga panipi sa paligid ng value.

Mga madalas itanong

Magpatuloy sa pagbabasa