How to Integrate the WhatsApp Cloud API in Laravel: A Production-Ready Guide
You want to send automated WhatsApp messages from your Laravel application. Maybe it is an OTP for a login, a payment reminder, or an order confirmation.
Many tutorials tell you to install heavy, third-party Laravel packages. Do not do that. Meta’s WhatsApp Cloud API is a straightforward JSON API. Laravel’s built-in HTTP client is all you need. Adding extra packages just introduces dependency debt that will break when you upgrade Laravel next year.
This guide walks you through setting up the official Meta WhatsApp Cloud API inside a Laravel application from scratch. We will write clean, native code, test it via an Artisan command, and handle the errors that actually happen in production.
What You Need Before You Start
Do not write a single line of code until you have these four things ready:- A Meta Developer Account: Go to developers.facebook.com and register.
- A Meta Business Portfolio: Formerly known as Business Manager. You can start sending test messages without a verified business, but you will need verification to scale. To understand these boundaries, read about The Reality of Using WhatsApp API Without Business Verification.
- A Clean Phone Number: This number cannot have an active WhatsApp personal or business app account. If it does, you must delete that account. Once a number is registered on the Cloud API, you cannot use it on your phone's WhatsApp app anymore.
- A Laravel App: We are using Laravel 10 or 11 running on PHP 8.2+.
Step 1: Set Up the Meta Developer Console
Log into your Meta Developer Dashboard and click Create App. Select Other under the use cases, then select Business as the app type. Give your app a name (for example, "Laravel Notifications") and link it to your Business Portfolio. Once the app is created, scroll down on the product setup screen and click Set Up under the WhatsApp card. Meta will automatically generate a temporary access token, a test phone number, and a Phone Number ID. Copy these values. You will need them in the next step. Add your personal phone number (with the country code, e.g., 923001234567 or 919876543210) to the recipient list on the right side of the panel. Meta will send a verification code to your phone. You can only send test messages to verified recipient numbers during this sandbox phase.Step 2: Configure Your Laravel Environment
Open your Laravel project. We need to store our API credentials securely. Open your.env file and add the following keys:
WHATSAPP_TOKEN="your-temporary-or-permanent-access-token" WHATSAPP_PHONE_NUMBER_ID="your-phone-number-id" WHATSAPP_VERSION="v20.0"Next, open
config/services.php and map these environment variables so we can access them cleanly through Laravel's config system:
'whatsapp' => [
'token' => env('WHATSAPP_TOKEN'),
'phone_number_id' => env('WHATSAPP_PHONE_NUMBER_ID'),
'version' => env('WHATSAPP_VERSION', 'v20.0'),
],
Step 3: Write the WhatsApp Service Class
We will create a dedicated service class to handle the API calls. This keeps your controllers clean and makes it easy to swap out logic later. Run this command to create a directory and file:mkdir app/Services touch app/Services/WhatsAppService.phpNow, open
app/Services/WhatsAppService.php and paste the following code:
<?php
namespace App\Services;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;
class WhatsAppService
{
protected string $token;
protected string $phoneNumberId;
protected string $version;
protected string $baseUrl;
public function __construct()
{
$this->token = config('services.whatsapp.token');
$this->phoneNumberId = config('services.whatsapp.phone_number_id');
$this->version = config('services.whatsapp.version');
$this->baseUrl = "https://graph.facebook.com/{$this->version}/{$this->phoneNumberId}";
}
/**
* Send a template message to a user.
*/
public function sendTemplate(string $to, string $templateName, string $languageCode = 'en_US', array $components = []): array
{
$payload = [
'messaging_product' => 'whatsapp',
'to' => $to,
'type' => 'template',
'template' => [
'name' => $templateName,
'language' => [
'code' => $languageCode,
],
],
];
if (!empty($components)) {
$payload['template']['components'] = $components;
}
$response = Http::withToken($this->token)
->acceptJson()
->post("{$this->baseUrl}/messages", $payload);
if ($response->failed()) {
Log::error('WhatsApp API Error', [
'status' => $response->status(),
'body' => $response->json(),
'to' => $to,
]);
return [
'success' => false,
'error' => $response->json()['error']['message'] ?? 'Unknown API error',
];
}
return [
'success' => true,
'message_id' => $response->json()['messages'][0]['id'] ?? null,
];
}
}
This service class uses Laravel’s native Http client. It formats the request, attaches the Bearer token, and handles API failures by logging them and returning a clean array.
Step 4: Create a Test Command
The fastest way to verify your integration is with a custom Artisan command. It avoids the hassle of setting up web routes or clicking through a UI just to trigger an API call. Run the following command to generate the file:php artisan make:command TestWhatsAppSendOpen
app/Console/Commands/TestWhatsAppSend.php and replace its contents with this:
<?php
namespace App\Console\Commands;
use Illuminate\Console\Command;
use App\Services\WhatsAppService;
class TestWhatsAppSend extends Command
{
protected $signature = 'whatsapp:test {phone}';
protected $description = 'Send a test WhatsApp template message';
public function handle(WhatsAppService $whatsAppService)
{
$phone = $this->argument('phone');
$this->info("Sending test message to {$phone}...");
// We use the default hello_world template provided by Meta
$result = $whatsAppService->sendTemplate($phone, 'hello_world');
if ($result['success']) {
$this->info("Success! Message ID: " . $result['message_id']);
} else {
$this->error("Failed! Error: " . $result['error']);
}
}
}
Step 5: Run the Test and Confirm It Works
Now run your command in the terminal. Replace the phone number with the verified recipient number you set up in the Meta dashboard:php artisan whatsapp:test 923001234567If everything is configured correctly, your terminal will show:
Sending test message to 923001234567... Success! Message ID: wamid.HBgLOTIzMDAxMjM0NTY3FQIAERgSQ0VDQzNBRTQ3RDVDRDU4OUIzAA==Check your phone. You should have a message from Meta’s test number containing their standard "hello_world" greeting.
What to Do When the Step Fails
If your test did not work, do not panic. The WhatsApp API is notoriously picky. Here are the most common failure points:1. Error Code 100: Invalid Parameter
This usually means your phone number format is wrong. Meta expects a clean string containing only numbers, starting with the country code.- Bad: +92-300-1234567
- Bad: 00923001234567
- Good: 923001234567
2. Error Code 190: Invalid OAuth Access Token
Your temporary access token has expired. These tokens only last 24 hours. You need to generate a permanent system user token in your Business Manager settings if you are moving beyond local testing.3. Error Code 100: Template Not Found
You cannot send custom, free-form text messages to a user who has not messaged you first. You must use an approved template. If you misspelled the template name or requested a language (likeur_PK) that you have not submitted for approval, the API will reject it outright.
For high-volume production setups, you will encounter deeper infrastructure bottlenecks. If you are planning to send thousands of alerts, read about Why Your WhatsApp API Calls Are Failing: Rate Limits, Queues, and Production-Ready Architecture.
Moving Beyond the Sandbox
Once your test message arrives, you are only halfway there. To build a robust production app, you must tackle these next steps:1. Set Up a Permanent Access Token
Temporary tokens expire. To get a permanent one, go to your Meta Business Suite, navigate to Users > System Users, create an Admin System User, and generate a token with thewhatsapp_business_messaging permission. Use this token in your production .env.
2. Configure Webhooks
Sending messages is a one-way street. You need to know if the message was delivered, read, or if it failed. Meta sends these updates via webhooks. You will need to build a Laravel controller with an endpoint that handles Meta's verification GET request and processes their incoming POST payloads. To understand how to read these statuses, handle delivery failures, and manage costs, check out our guide on Tracking WhatsApp API Message Statuses: Webhooks, Error Codes, and Costs.3. Consider Your Gateway Options
Setting up Meta's API directly gives you complete control, but managing system users, template approvals, and webhook verification can be a headache. If you want to skip the complex Meta onboarding, WA Link offers a managed API gateway. It simplifies the setup process so you can get your Laravel app sending messages in minutes. However, keep in mind that using any managed gateway means you will not have direct access to Meta's raw debug logs in the developer console.Frequently Asked Questions
Can I use my regular personal WhatsApp number for the API?
No. If you register a number on the WhatsApp Cloud API, you can no longer use it on the physical WhatsApp application on your phone. If you try, Meta will disconnect the API connection. Use a dedicated virtual number or a separate SIM card for your business API.How much does it cost to send messages?
Meta does not charge per message. Instead, they charge per 24-hour conversation. A conversation starts when your template message is delivered. The first 1,000 service conversations each month are free, but utility and marketing conversations have varying rates based on the recipient's country code.Why can't I send a simple text message like "Hello"?
To prevent spam, Meta blocks businesses from initiating conversations with arbitrary text. You must use a pre-approved template (which can contain placeholders like{{1}} for names). Once the customer replies to your template message, a 24-hour customer service window opens. During this window, you can send free-form text messages.