Tropo Webapi Php Laravel Package

Getting Started

Minimal Setup

1. Install via Composer

   composer require camcima/tropo-webapi-php
   

   Ensure your composer.json includes the package under require.

2. Basic Initialization

   use Camcima\Tropo\Tropo;
   
   $tropo = new Tropo('YOUR_ACCOUNT_SID', 'YOUR_AUTH_TOKEN');
   

   • Replace YOUR_ACCOUNT_SID and YOUR_AUTH_TOKEN with your Tropo credentials.
   • Store credentials securely (e.g., Laravel .env file).

3. First Use Case: Sending a Simple SMS

   $response = $tropo->sms()->send(
       '+1234567890', // Recipient
       'Hello from Tropo!', // Message
       ['from' => '+1987654321'] // Optional sender ID
   );
   

   • Check $response->isSuccess() and $response->getBody() for results.

4. Key Classes to Explore

   • Tropo\Sms – SMS operations.
   • Tropo\Call – Voice call management.
   • Tropo\Webhook – Handling Tropo webhook events.
   • Tropo\Session – Managing Tropo sessions.

Implementation Patterns

1. Workflow: Handling Incoming Calls/SMS

use Camcima\Tropo\Tropo;
use Camcima\Tropo\Webhook;

$tropo = new Tropo(env('TROPO_SID'), env('TROPO_TOKEN'));

// Middleware to validate webhook signatures (if needed)
$webhook = new Webhook($tropo);
$webhook->setSecret(env('TROPO_WEBHOOK_SECRET'));

// Route incoming events (e.g., in Laravel routes file)
Route::post('/tropo-webhook', function (Request $request) {
    $webhook->handle($request->input());
    // Process events (e.g., store in DB, trigger actions)
});

2. Workflow: Dynamic Call Responses

$call = $tropo->call();
$response = $call->answer()
    ->say('Welcome to our service!')
    ->gatherInput(['action' => 'menu'])
    ->on('menu', function ($session) {
        $session->say('You selected: ' . $session->getInput());
    })
    ->send();

3. Integration with Laravel

• Service Provider Bind the Tropo client to Laravel’s container:

  // app/Providers/AppServiceProvider.php
  public function register()
  {
      $this->app->singleton(Tropo::class, function ($app) {
          return new Tropo(env('TROPO_SID'), env('TROPO_TOKEN'));
      });
  }
  

  Inject Tropo into controllers/services via constructor.

• Queued Jobs for Async Operations

  use Camcima\Tropo\Jobs\SendSmsJob;
  
  SendSmsJob::dispatch('+1234567890', 'Your message')->onQueue('tropo');
  

4. Testing

• Mocking Tropo Responses Use Laravel’s Mockery to stub API calls:

  $mock = Mockery::mock(Tropo::class);
  $mock->shouldReceive('sms->send')
       ->once()
       ->andReturn(new Response(true, ['sid' => 'CA123']));
  

Gotchas and Tips

Pitfalls

1. Webhook Signature Validation

   • If using webhooks, ensure setSecret() is called to validate Tropo’s signature.
   • Without validation, your endpoint is vulnerable to spoofing.

2. Rate Limits

   • Tropo enforces rate limits. Handle 429 Too Many Requests gracefully:

     try {
         $response = $tropo->sms()->send(...);
     } catch (RateLimitException $e) {
         // Retry with exponential backoff
     }
     

3. Session Timeouts

   • Tropo sessions expire after 30 minutes of inactivity. Design your workflows to handle reconnection or timeouts.

4. Deprecated Methods

   • The package is lightweight (2 stars, low activity). Check the Tropo API docs for breaking changes.

Debugging Tips

• Enable Verbose Logging

  $tropo->setDebug(true); // Logs HTTP requests/responses
  

• Inspect Raw Responses

  $response = $tropo->sms()->send(...);
  \Log::debug($response->getRawBody()); // Debug full API response
  

Extension Points

1. Custom Response Handlers Extend the Response class to add domain-specific logic:

   class CustomResponse extends \Camcima\Tropo\Response {
       public function isValid() {
           return $this->getStatus() === 200 && $this->getBody()['valid'] === true;
       }
   }
   

2. Event Dispatching Trigger Laravel events when Tropo webhooks fire:

   $webhook->on('call.started', function ($event) {
       event(new TropoCallStarted($event));
   });
   

3. Fallback for Missing Features Use Tropo’s REST API directly if the package lacks a feature:

   $client = new \GuzzleHttp\Client();
   $response = $client->post('https://api.tropo.com/1/sessions', [
       'json' => ['accountSid' => env('TROPO_SID'), '...']
   ]);
   

Configuration Quirks

• Environment Variables Always use .env for credentials:

  TROPO_SID=your_account_sid
  TROPO_TOKEN=your_auth_token
  TROPO_WEBHOOK_SECRET=your_webhook_secret
  

• Default Headers The package adds X-Tropo-Version: 1 by default. Override if needed:

  $tropo->setDefaultHeaders(['X-Custom-Header' => 'value']);