- How do I install xaamin/whatsapi in a Laravel application?
- Install it with Composer using composer require xaamin/whatsapi. Laravel's package auto-discovery registers the service provider, so no manual binding is required in a standard app. Publish the package config with php artisan vendor:publish and set the endpoint URL and credentials for your WhatsApp bridge in the .env file. The PHP side is only a convenience layer, so nothing works until the Node.js sidecar it talks to is running and authenticated.
- Do I need to run a Node.js sidecar to use this package?
- Yes. This package is a thin PHP client that forwards requests to a separate Node.js process, which holds the actual WhatsApp session and exposes an HTTP endpoint. The PHP side handles config, the service provider and a few DTOs, but it carries no messaging logic itself. Treat the Node bridge as the real dependency when planning your infrastructure, and vendor it into your own container image so a upstream change does not break you silently.
- Can I send images, documents and other media with this package?
- Sending media is supported in the same way text messages are: the wrapper forwards the payload to the bridge, which performs the actual upload and send. Template and interactive messages follow the same pattern. Beyond the happy path the PHP API surface is thin, so you will often be reading the Node bridge documentation to understand exactly what arguments get passed through. Pin the bridge version so its payload format does not drift away from what your code expects.
- How do I verify incoming WhatsApp webhooks in Laravel?
- Expose a route that is excluded from CSRF verification and handle the incoming callback in a controller, using the package's verification helper on the handshake request. Return the challenge value on a successful verification and a 4xx otherwise. Because the PHP layer is a wrapper, delivery receipts and message events ultimately reflect what the underlying bridge emits, so log raw payloads while you build the integration. Queue any heavy processing so the webhook responds quickly and does not time out.
- Which Laravel and PHP versions does xaamin/whatsapi support?
- The package fits Laravel codebases on PHP 7.4 through 8.x, and it uses standard service provider auto-discovery and config publishing, so it slots into modern Laravel apps without custom bootstrap. The exact constraints live in its composer.json, so check those against your own PHP and Laravel versions before committing. Because it is maintained on a best-effort basis, pin the version in composer.lock and read the changelog before upgrading.
- Is it safe to use this package for business messaging, or does it break WhatsApp's Terms of Service?
- It rides an unofficial WhatsApp Web session, which is outside WhatsApp's terms for business messaging, so accounts used this way are subject to silent bans. The ban applies to the phone number, not the library, which is a real operational loss if that number is a business asset. Get legal or compliance sign-off before putting a production phone number behind an unofficial client, and keep the number disposable until that has happened. For anything customer-facing at scale, the official WhatsApp Business Cloud API is the defensible choice.
- How can I test the package without sending real WhatsApp messages?
- Mock the package facade or fake the outbound HTTP calls with Http::fake in your feature tests and assert on the payloads your application produces. That keeps tests fast and avoids touching the bridge or the phone number at all. Because the real work happens in the Node process, integration tests should hit a separate staging bridge with a dedicated number. Keep a small contract test that verifies your request shapes still match what the wrapper forwards.
- Does this package work on serverless, Lambda or shared hosting?
- No. The sidecar needs a long-lived process with persistent disk for the session store and a stable single instance, which rules out typical FaaS and shared hosting deployments. It fits naturally if your application is containerised on ECS, Kubernetes or a VPS where you control a long-running service. Plan where the Node process lives, whether it needs outbound internet access, and who owns it operationally before you start.
- What is the migration path from xaamin/whatsapi to the official WhatsApp Business Cloud API?
- Hide messaging calls behind your own interface so the wrapper is an implementation detail rather than something controllers call directly. Once that boundary exists, swapping in an official Cloud API SDK is a contained change rather than a rewrite. The same insulation helps if you move between wrappers in the same lineage, where method names are near-identical but the underlying bridge version must match. Budget for the day the upstream protocol breaks and you have to fix it yourself or migrate.
- Is xaamin/whatsapi actively maintained and what are the alternatives?
- It is an MIT-licensed package with a single maintainer and a modest star count, so best-effort maintenance is the right assumption. Sibling wrappers such as muktabd/whatsapi are close relatives with similar method names, and official WhatsApp Business Cloud API SDKs exist if you can accept the official route. Whatever you choose, pin versions, vendor the Node sidecar into your own image, and keep the exit path to the Cloud API short.