Client Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require vonage/client
   

   Verify installation by checking composer.json for the dependency.

2. Basic Initialization

   use Vonage\Client\Credentials\Basic;
   use Vonage\Client;
   
   $credentials = new Basic('YOUR_API_KEY', 'YOUR_API_SECRET');
   $client = new Client($credentials);
   

   • Replace YOUR_API_KEY and YOUR_API_SECRET with your Vonage credentials (found in the Vonage Dashboard).
   • Store credentials securely (e.g., .env file) and avoid hardcoding.

3. First API Call (SMS Example)

   $response = $client->sms()->send([
       'to'   => '15551234567',
       'from' => 'YourApp',
       'text' => 'Hello from Vonage!'
   ]);
   

   • Check $response->successful() to verify the request worked.
   • Log responses for debugging:

     \Log::debug('SMS Response:', $response->getData());
     

4. Key Documentation Links

   • Vonage PHP SDK Docs
   • Vonage API Reference
   • Vonage PHP SDK Examples

Implementation Patterns

Common Workflows

1. SMS Messaging

• Sending SMS

  $client->sms()->send([
      'to'      => '15551234567',
      'from'    => 'YourBrand',
      'text'    => 'Your message here',
      'type'    => 'promo', // Optional: 'promo', 'transactional', etc.
      'unicode' => true,    // For non-ASCII characters
  ]);
  

  • Use type for compliance with carrier rules (e.g., promo for marketing messages).
  • Handle failures gracefully:

    if (!$response->successful()) {
        \Log::error('SMS failed:', $response->getErrors());
        // Retry logic or notify admin
    }
    

• Checking SMS Status

  $response = $client->sms()->status('SMS_MESSAGE_UUID');
  $status   = $response->getData()['status']['smsMessageData']['status'];
  

2. Voice API

• Making a Call

  $response = $client->voice()->createCall([
      'to'   => ['type' => 'phone', 'number' => '15551234567'],
      'from' => ['type' => 'phone', 'number' => '15559876543'],
      'answerUrl' => 'https://your-app.com/answer',
      'eventUrl'  => 'https://your-app.com/events',
  ]);
  

  • Use answerUrl for IVR logic (e.g., TwiML responses).
  • Store call uuid for tracking:

    $callUuid = $response->getData()['uuid'];
    

• Recording Calls

  $response = $client->voice()->createCall([
      'to'   => ['type' => 'phone', 'number' => '15551234567'],
      'record' => true,
      'recordFileFormat' => 'mp3',
  ]);
  

3. Number Insights

• Checking Number Status

  $response = $client->numberInsights()->get('15551234567');
  $status   = $response->getData()['numberType'];
  

  • Useful for validating phone numbers before sending SMS/voice.

4. Verify API (2FA)

• Start Verification

  $response = $client->verify()->start([
      'number' => '15551234567',
      'brand'  => 'YourApp',
  ]);
  $requestId = $response->getData()['request_id'];
  

• Check Verification Status

  $response = $client->verify()->check($requestId);
  $status   = $response->getData()['status'];
  

Integration Tips

• Rate Limiting Vonage enforces rate limits (e.g., 1 SMS/second by default). Implement exponential backoff:

  use Vonage\Client\Exceptions\RateLimitExceeded;
  
  try {
      $response = $client->sms()->send([...]);
  } catch (RateLimitExceeded $e) {
      sleep($e->getRetryAfter());
      retry();
  }
  

• Webhooks Configure webhooks in the Vonage Dashboard to handle events (e.g., SMS delivery reports, call events). Example Laravel route:

  Route::post('/vonage/webhook', function (Request $request) {
      $payload = $request->json()->all();
      // Validate payload (e.g., check signature)
      // Process event (e.g., update DB, send notification)
  });
  

• Testing Use Vonage’s sandbox environment for testing:

  $sandboxCredentials = new Basic('YOUR_SANDBOX_KEY', 'YOUR_SANDBOX_SECRET');
  $sandboxClient = new Client($sandboxCredentials);
  

• Logging Enable debug logging for troubleshooting:

  $client = new Client($credentials, [
      'log' => [
          'enabled' => true,
          'file'    => storage_path('logs/vonage.log'),
      ]
  ]);
  

Gotchas and Tips

Pitfalls

1. Credentials Leaks

   • Issue: Hardcoding API keys in code or committing them to version control.
   • Fix: Use Laravel’s .env and config/services.php:

     VONAGE_KEY=your_api_key
     VONAGE_SECRET=your_api_secret
     

     // config/services.php
     'vonage' => [
         'key'    => env('VONAGE_KEY'),
         'secret' => env('VONAGE_SECRET'),
     ];
     

   • Tool: Use laravel/env-editor to manage secrets safely.

2. Timeouts

   • Issue: Vonage API calls may timeout if the server is slow or the request is large.
   • Fix: Increase timeout in the client:

     $client = new Client($credentials, [
         'timeout' => 30, // Default is 10 seconds
     ]);
     

3. Webhook Verification

   • Issue: Unverified webhook payloads can lead to security risks.
   • Fix: Validate Vonage’s X-Vonage-Signature header:

     $signature = $request->header('X-Vonage-Signature');
     $payload   = $request->getContent();
     $expected  = hash_hmac('sha256', $payload, config('services.vonage.secret'));
     if (!hash_equals($expected, $signature)) {
         abort(403, 'Invalid signature');
     }
     

4. Number Format

   • Issue: Incorrect phone number formats (e.g., missing country code) cause failures.
   • Fix: Use E.164 format (e.g., +15551234567 for US numbers). Validate with:

     use Vonage\Client\Helpers\NumberHelper;
     $validNumber = NumberHelper::format($number, 'E164');
     

5. Idempotency

   • Issue: Retrying failed requests without idempotency keys may cause duplicate charges.
   • Fix: Use the idempotencyKey option:

     $response = $client->sms()->send([
         'to'   => '15551234567',
         'from' => 'YourApp',
         'text' => 'Hello',
     ], [
         'idempotencyKey' => Str::uuid()->toString(),
     ]);
     

Debugging Tips

• Enable Debug Mode

  $client = new Client($credentials, [
      'debug' => true,
  ]);
  

  • Logs will appear in storage/logs/vonage.log.

• Inspect Raw Responses

  $response = $client->sms()->send([...]);
  \Log::debug('Raw Response:', $response->getRawData());
  

• Common Errors | Error | Cause