Whatsapi Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require biruwon/whatsapi-bundle
   

   Add to bundles.php (Symfony 2.x):

   Biruwon\WhatsAPIBundle\BiruwonWhatsAPIBundle::class => ['all' => true],
   

2. Configuration Edit config/packages/biruwon_whatsapi.yaml (or create if missing):

   biruwon_whatsapi:
       api_key: '%env(WHATSAPP_API_KEY)%'
       phone_number: '+1234567890'
       base_url: 'https://api.whatsapp.com'
   

3. First Use Case Inject the service and send a message:

   use Biruwon\WhatsAPIBundle\Service\WhatsAPIService;
   
   class SomeController
   {
       public function __construct(private WhatsAPIService $whatsapp)
       {}
   
       public function sendWelcomeMessage()
       {
           $this->whatsapp->sendMessage(
               '+1987654321', // Recipient
               'Hello from Symfony!' // Message
           );
       }
   }
   

Key Files to Review

• src/Service/WhatsAPIService.php (Core logic)
• Resources/config/services.yaml (Service definitions)
• Tests/ (Basic usage examples)

Implementation Patterns

Common Workflows

1. Sending Messages

   $this->whatsapp->sendMessage($phone, $message, [
       'type' => 'text', // Optional: 'text', 'image', 'document'
       'media_url' => 'https://example.com/image.jpg' // For media types
   ]);
   

2. Handling Responses Use Symfony’s event system to listen for message delivery status:

   # config/packages/biruwon_whatsapi.yaml
   biruwon_whatsapi:
       listeners:
           on_message_sent: App\EventListener\WhatsAPIListener
   

   // src/EventListener/WhatsAPIListener.php
   class WhatsAPIListener
   {
       public function onMessageSent(MessageSentEvent $event)
       {
           if (!$event->isSuccess()) {
               // Log or retry failed messages
           }
       }
   }
   

3. Media Handling Upload and send images/documents:

   $this->whatsapp->sendMedia(
       '+1987654321',
       'https://example.com/receipt.pdf',
       'Your invoice.pdf'
   );
   

4. Template Messages (Advanced) Use WhatsApp’s template system (requires pre-approved templates):

   $this->whatsapp->sendTemplate(
       '+1987654321',
       'template_name',
       ['param1' => 'value1'] // Template variables
   );
   

Integration Tips

• Rate Limiting: Implement a queue (e.g., Symfony Messenger) for high-volume sends.
• Logging: Extend the service to log all API calls:

  $this->whatsapp->setLogger($logger); // Inject PSR-3 logger
  

• Testing: Mock WhatsAPIService in unit tests:

  $this->createMock(WhatsAPIService::class)
       ->method('sendMessage')
       ->willReturn(true);
  

Gotchas and Tips

Pitfalls

1. API Key Exposure

   • Never hardcode api_key in config. Use .env and restrict file permissions.
   • Fix: Validate the key in WHATSAPP_API_KEY validation (e.g., Symfony’s env validator).

2. Phone Number Format

   • WhatsApp requires numbers in E.164 format (e.g., +1234567890, not 1234567890).
   • Fix: Use a library like libphonenumber to normalize numbers:

     use libphonenumber\PhoneNumberUtil;
     $util = PhoneNumberUtil::getInstance();
     $phone = $util->format($util->parse($rawNumber), PhoneNumberFormat::E164);
     

3. Media Size Limits

   • WhatsApp enforces 100MB max for documents and 5MB for images/videos.
   • Fix: Validate file sizes before upload:

     if ($file->getSize() > 5 * 1024 * 1024) {
         throw new \RuntimeException('File too large');
     }
     

4. Deprecated Methods

   • The bundle lacks type hints and may use older Symfony 2.x patterns.
   • Fix: Extend the service to add modern PHP types:

     class ExtendedWhatsAPIService extends WhatsAPIService
     {
         public function sendMessage(string $phone, string $message, array $options = []): bool
         {
             // ...
         }
     }
     

Debugging Tips

1. Enable API Debugging Add this to config to log raw API responses:

   biruwon_whatsapi:
       debug: true
   

2. Common Errors

   • 401 Unauthorized: Invalid API key or phone number.
   • 400 Bad Request: Malformed phone number or message.
   • 429 Too Many Requests: Hit rate limits (WhatsApp allows ~240 messages/minute for business accounts).

3. Extension Points

   • Custom HTTP Client: Replace the default client (e.g., for retries):

     $this->whatsapp->setHttpClient($customClient);
     

   • Event Subscribers: Extend MessageSentEvent to add custom logic (e.g., analytics).

Configuration Quirks

• Base URL: The default base_url may not match WhatsApp’s current API endpoint. Verify with WhatsApp Business API docs.
• Environment Variables: The bundle assumes WHATSAPP_API_KEY exists. Add to .env.dist:

  WHATSAPP_API_KEY=your_key_here