README

WhatsApp Business API adapter for the laravel-bootdesk multi-platform messaging framework.

Install

composer require bootdesk/chat-sdk-adapter-whatsapp

Requires a PSR-18 HTTP client (guzzlehttp/guzzle, symfony/http-client, etc.) and a PSR-17 factory (nyholm/psr7 bundled).

Configuration

use BootDesk\ChatSDK\WhatsApp\WhatsAppAdapter;

$adapter = new WhatsAppAdapter(
    accessToken: env('WHATSAPP_ACCESS_TOKEN'),
    httpClient: new \GuzzleHttp\Client,
    phoneNumberId: env('WHATSAPP_PHONE_NUMBER_ID'),
    appSecret: env('WHATSAPP_APP_SECRET'),
    verifyToken: env('WHATSAPP_VERIFY_TOKEN'),
);

Laravel

The ChatServiceProvider auto-binds Psr\Http\Client\ClientInterface to GuzzleHttp\Client. Add to config/chat.php:

'whatsapp' => [
    'access_token'    => env('WHATSAPP_ACCESS_TOKEN'),
    'phone_number_id' => env('WHATSAPP_PHONE_NUMBER_ID'),
    'app_secret'      => env('WHATSAPP_APP_SECRET'),
    'verify_token'    => env('WHATSAPP_VERIFY_TOKEN'),
],

Quick Example

// Send a message to a phone number
$adapter->postMessage('whatsapp:+15551234567', 'Hello from laravel-bootdesk!');

Text Formatting

WhatsApp supports *bold*, _italic_, ~strikethrough~, `monospace`, code blocks , bullet lists (*/-), numbered lists (1.), and quotes (>). The SDK's WhatsAppFormatConverter automatically converts standard markdown (**bold**, ~~strike~~) to WhatsApp format when sending, and converts WhatsApp syntax back to standard markdown when receiving.

Template Messages

WhatsApp supports pre-approved message templates for notifications, alerts, and marketing. Send them via PostableMessage::template():

use BootDesk\ChatSDK\WhatsApp\WhatsAppTemplate;

$adapter->postMessage(
    'whatsapp:phone123:5511999999999',
    PostableMessage::template(
        WhatsAppTemplate::create('order_confirmation', 'en_US')
            ->bodyParam('John')
            ->bodyParam('#12345')
            ->buttonParam('Track Order', 'track_payload')
    )
);

WhatsAppTemplate API

Serializes to WhatsApp API format:

{
  "type": "template",
  "template": {
    "name": "order_confirmation",
    "language": { "code": "en_US" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "John" },
          { "type": "text", "text": "#12345" }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": 0,
        "parameters": [{ "type": "quick_reply", "payload": "track_payload" }]
      }
    ]
  }
}

Named parameters

Templates using {{first_name}} instead of {{1}}:

WhatsAppTemplate::create('order_confirmation', 'en_US')
    ->named()
    ->bodyParam('Jessica', 'first_name')
    ->bodyParam('SKBUP2-4CPIG9', 'order_number');

Sends parameter_name on each parameter and parameter_format: "named" at the template level. Omit ->named() (or call ->positional()) for positional {{1}} format.

Falls back to markdown text via __toString() when an adapter doesn't support templates.

Thread ID Format

Webhook

WhatsApp Cloud API sends webhook payloads. Verify requests using HMAC signature verification with the app secret.

BSUID (Business-Scoped User ID) Support

As of May 2026, WhatsApp supports BSUIDs — a user identifier independent of phone numbers. The adapter transparently handles both identifiers:

• Inbound: reads from (phone) with fallback to from_user_id (BSUID)
• Outbound: detects BSUID format (XX.xxxx) and uses recipient instead of to
• Thread IDs: use whatever identifier was available in the webhook

Feature Matrix

Notes

WhatsApp Business API only. No edit or delete support in the WhatsApp Cloud API.

Documentationn

Full API documentation: https://bootdesk.github.io/chat-sdk

License

MIT