2N Voiceblue Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bestnetwork/2n-voiceblue
   

   Add the service provider to config/app.php:

   BestNetwork\Voiceblue\VoiceblueServiceProvider::class,
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="BestNetwork\Voiceblue\VoiceblueServiceProvider"
   

   Update config/voiceblue.php with your gateway credentials (IP, port, username, password).

3. First Use Case: Basic Call Initiation Inject the Voiceblue facade or service into a controller:

   use BestNetwork\Voiceblue\Facades\Voiceblue;
   
   public function makeCall()
   {
       $call = Voiceblue::call('1234567890', 'extension123');
       return response()->json($call);
   }
   

Implementation Patterns

Common Workflows

1. Call Management

   • Initiate a call:

     $call = Voiceblue::call('destinationNumber', 'sourceExtension');
     

   • Hang up a call:

     Voiceblue::hangup($callId);
     

   • List active calls:

     $activeCalls = Voiceblue::activeCalls();
     

2. Extension Management

   • Register an extension:

     Voiceblue::registerExtension('extension123', ['name' => 'John Doe']);
     

   • Unregister an extension:

     Voiceblue::unregisterExtension('extension123');
     

3. Event Listeners Use Laravel’s event system to listen for gateway events (e.g., CallStarted, CallEnded):

   Voiceblue::listen('call.started', function ($event) {
       Log::info('Call started: ' . $event->callId);
   });
   

4. Integration with Queues Offload call operations to queues for async processing:

   Voiceblue::dispatch(new InitiateCallJob('destination', 'extension'));
   

Integration Tips

• Logging: Enable debug logging in config/voiceblue.php for troubleshooting:

  'debug' => env('VOICEBLUE_DEBUG', false),
  

• Error Handling: Wrap calls in try-catch blocks to handle gateway timeouts or auth failures:

  try {
      $call = Voiceblue::call('1234567890', 'extension123');
  } catch (\BestNetwork\Voiceblue\Exceptions\GatewayException $e) {
      Log::error($e->getMessage());
  }
  

• Testing: Use the VoiceblueFake class for unit testing:

  Voiceblue::fake()->shouldReceive('call')->once()->andReturn(['id' => 'test123']);
  

Gotchas and Tips

Pitfalls

1. Connection Issues

   • Ensure the gateway IP/port is whitelisted in the firewall.
   • Verify credentials in config/voiceblue.php match the gateway settings.
   • Debug with telnet to the gateway port to confirm connectivity:

     telnet <gateway-ip> <gateway-port>
     

2. Rate Limiting The gateway may throttle requests. Implement exponential backoff in retries:

   use Illuminate\Support\Facades\Retry;
   
   Retry::times(3)->backoff(100)->try(function () {
       Voiceblue::call('destination', 'extension');
   });
   

3. Extension States Extensions must be registered before making calls. Unregistered extensions will fail silently.

4. Timeouts Default timeout (30s) may be too short for slow networks. Adjust in config:

   'timeout' => 60, // seconds
   

Debugging Tips

• Enable Verbose Logging:

  'log_level' => 'debug',
  

• Check Gateway Logs: Access the Voiceblue web interface (http://<gateway-ip>) for real-time events.
• Use dd() for Responses: Inspect raw responses from the gateway:

  $response = Voiceblue::rawCall('destination', 'extension');
  dd($response);
  

Extension Points

1. Custom Commands Extend the VoiceblueManager to add custom commands:

   Voiceblue::extend(function ($manager) {
       $manager->addCommand('custom.command', function ($params) {
           return $this->sendCommand('CUSTOM ' . json_encode($params));
       });
   });
   

2. Event Customization Override default event classes in config/voiceblue.php:

   'events' => [
       'call.started' => \App\Events\CustomCallStarted::class,
   ],
   

3. Middleware Add middleware to modify requests/responses globally:

   Voiceblue::middleware(function ($request, $next) {
       $request->header('X-Custom-Header', 'value');
       return $next($request);
   });