Vonage Notification Channel Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel/vonage-notification-channel
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Laravel\Vonage\VonageServiceProvider" --tag="config"
   

2. Configuration: Add Vonage credentials to .env:

   VONAGE_KEY=your_api_key
   VONAGE_SECRET=your_api_secret
   VONAGE_SMS_FROM=YourSenderName
   

3. First Use Case: Create a notification class extending VonageMessage:

   use Laravel\Vonage\VonageMessage;
   
   class OrderConfirmation extends VonageMessage
   {
       public function __construct(public string $orderId)
       {
           $this->to = 'recipient-phone-number';
           $this->message = "Your order #{$this->orderId} is confirmed!";
       }
   }
   

   Send via a user model:

   $user->notify(new OrderConfirmation('ORD123'));
   

Where to Look First

• Documentation: Laravel SMS Notifications
• Config File: config/services.php (Vonage section)
• Notification Class: Extend VonageMessage for SMS notifications.

Implementation Patterns

Core Workflows

1. Sending SMS Notifications:

   • Extend VonageMessage and define to (recipient) and message properties.
   • Use notify() on a user model or directly via Notification::route():

     Notification::route('vonage', $phoneNumber)->notify(new OrderConfirmation('ORD123'));
     

2. Dynamic Recipients:

   • Use route() to dynamically set recipients:

     $user->route('vonage', $user->phone)->notify(new Notification());
     

3. Batch Sending:

   • Queue notifications for efficiency:

     $user->notify(new OrderConfirmation('ORD123'))->onQueue('sms');
     

4. Customizing Messages:

   • Override toVonage() in your notification class for advanced formatting:

     public function toVonage($notifiable)
     {
         return [
             'text' => "Custom: {$this->message}",
             'from' => 'CustomSender',
         ];
     }
     

Integration Tips

• Validation: Validate phone numbers before sending (e.g., using libphonenumber).
• Fallbacks: Combine with other channels (e.g., email) for critical notifications:

  $user->route('mail', $user->email)->notify(new MultiChannelNotification());
  

• Testing: Use Vonage’s sandbox environment (configured in .env):

  VONAGE_SANDBOX=true
  

Gotchas and Tips

Pitfalls

1. Phone Number Format:

   • Vonage expects E.164 format (e.g., +12125551234). Use Str::of($phone)->start('+') to ensure consistency.
   • Debug Tip: Log the formatted number before sending:

     \Log::debug('Sending to:', ['phone' => $this->to]);
     

2. Rate Limits:

   • Vonage enforces rate limits (e.g., 1 SMS/second). Queue notifications to avoid throttling:

     php artisan queue:work --sleep=3 --tries=3
     

3. Sandbox vs. Production:

   • Sandbox numbers (e.g., +14155238886) won’t receive messages in production. Always test with real credentials in staging.

4. Configuration Overrides:

   • Avoid hardcoding VONAGE_SMS_FROM in notifications. Use the config or .env for flexibility.

Debugging

• Enable Logging:

  VONAGE_LOG_LEVEL=debug
  

  Check storage/logs/laravel.log for API responses/errors.

• Vonage API Errors:

  • Common errors:
    • 401: Invalid API key/secret (check .env).
    • 400: Invalid phone number (validate format).
  • Use try/catch in notifications to handle failures gracefully:

    try {
        $user->notify(new OrderConfirmation('ORD123'));
    } catch (\Exception $e) {
        \Log::error("Vonage failed: " . $e->getMessage());
    }
    

Extension Points

1. Custom Vonage Client: Override the default client in config/services.php:

   'vonage' => [
       'client' => \App\Services\CustomVonageClient::class,
   ],
   

2. Webhook Handling: Use Vonage’s inbound SMS to trigger Laravel events. Example:

   // routes/web.php
   Route::post('/vonage-webhook', [VonageWebhookController::class, 'handle']);
   

3. Template Management: Store SMS templates in the database and fetch them dynamically:

   public function toVonage($notifiable)
   {
       $template = Template::find($this->templateId);
       return ['text' => $template->body];
   }
   

4. Multi-Language Support: Localize messages using Laravel’s localization:

   $message = __("notifications.order.confirmed", ['id' => $this->orderId]);