Clickatell Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require arcturial/clickatell
   

   Add the service provider to config/app.php (if not using Laravel's auto-discovery):

   'providers' => [
       // ...
       Arcturial\Clickatell\ClickatellServiceProvider::class,
   ],
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="Arcturial\Clickatell\ClickatellServiceProvider"
   

   Update .env with your Clickatell API credentials:

   CLICKATELL_API_KEY=your_api_key_here
   CLICKATELL_ACCOUNT_SID=your_account_sid
   

3. First Use Case: Sending a Basic SMS Inject the Clickatell facade or service into a controller/service:

   use Arcturial\Clickatell\Facades\Clickatell;
   
   public function sendSms()
   {
       $response = Clickatell::send([
           'to' => '27821234567',
           'text' => 'Hello from Laravel!',
       ]);
   
       return $response->success() ? 'SMS sent!' : 'Failed: ' . $response->error();
   }
   

Implementation Patterns

Common Workflows

1. Sending SMS with Recipients

   // Single recipient
   Clickatell::send(['to' => '27821234567', 'text' => 'Hi there']);
   
   // Multiple recipients (bulk)
   Clickatell::send([
       'to' => ['27821234567', '27831234567'],
       'text' => 'Group message',
   ]);
   

2. Sending Unicode/Emoji Messages

   Clickatell::send([
       'to' => '27821234567',
       'text' => 'Hello! 😊 How are you?',
       'unicode' => true, // Enable Unicode support
   ]);
   

3. Scheduling SMS (via Laravel Queues)

   use Arcturial\Clickatell\Jobs\SendSmsJob;
   
   SendSmsJob::dispatch([
       'to' => '27821234567',
       'text' => 'Scheduled message',
   ]);
   

   Register the job in AppServiceProvider:

   public function boot()
   {
       $this->app->make('Arcturial\Clickatell\Jobs\SendSmsJob')->handle();
   }
   

4. Handling Responses

   $response = Clickatell::send(['to' => '27821234567', 'text' => 'Test']);
   
   if ($response->success()) {
       $messageId = $response->messageId(); // Unique ID for tracking
   } else {
       $error = $response->error(); // Error message
   }
   

5. Using Templates (Clickatell Smart Messages)

   Clickatell::send([
       'to' => '27821234567',
       'templateId' => 'YOUR_TEMPLATE_ID',
       'variables' => ['name' => 'John'],
   ]);
   

Integration Tips

1. Logging Responses Wrap API calls in a try-catch and log responses for debugging:

   try {
       $response = Clickatell::send([...]);
       \Log::info('SMS sent', ['response' => $response->toArray()]);
   } catch (\Exception $e) {
       \Log::error('SMS failed', ['error' => $e->getMessage()]);
   }
   

2. Rate Limiting Implement Laravel's throttle middleware for API calls to avoid hitting Clickatell's rate limits:

   Route::middleware(['throttle:10,1'])->group(function () {
       Route::post('/sms', 'SmsController@send');
   });
   

3. Retry Failed Jobs Use Laravel's retryAfter for failed SMS jobs:

   SendSmsJob::dispatch([...])
       ->retryAfter(5); // Retry after 5 minutes
   

4. Testing Mock the Clickatell facade in tests:

   $this->mock(Clickatell::class)->shouldReceive('send')
       ->once()
       ->andReturn(new \Arcturial\Clickatell\Response(true, 'OK', '123'));
   

Gotchas and Tips

Pitfalls

1. Deprecated API

   • The package was last updated in 2016, so it may not support Clickatell's latest API endpoints or features (e.g., v3 API).
   • Workaround: Extend the Clickatell class or use a wrapper to adapt to newer APIs:

     class ExtendedClickatell extends \Arcturial\Clickatell\Clickatell {
         public function sendV3(array $data) {
             // Custom logic for v3 API
         }
     }
     

2. No Async Support by Default

   • The package doesn’t natively support async/queueing for SMS. Use Laravel's queue system (as shown above) to avoid timeouts.

3. Unicode Handling

   • Unicode messages require explicit unicode => true and may incur additional costs. Test with a small batch first.

4. Error Handling

   • Clickatell’s API returns generic errors. Parse responses carefully:

     if (!$response->success()) {
         $errorCode = $response->errorCode(); // Check for specific codes (e.g., 100 = invalid number)
     }
     

5. Number Formatting

   • Ensure phone numbers are in E.164 format (e.g., +27821234567). The package doesn’t auto-format.

Debugging Tips

1. Enable Debug Mode Set debug to true in config/clickatell.php to log raw API responses:

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

2. Check HTTP Status Codes Inspect the raw response for HTTP status codes (e.g., 401 Unauthorized):

   $response->raw(); // Returns the full HTTP response
   

3. Validate API Credentials Test credentials manually via Clickatell’s API docs or Postman before integrating.

4. Common Errors

   • Error 100: Invalid phone number format.
   • Error 200: Insufficient credit.
   • Error 300: Message too long (max ~1600 chars for Unicode).

Extension Points

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

   namespace App\Services;
   
   use Arcturial\Clickatell\Response as BaseResponse;
   
   class ClickatellResponse extends BaseResponse {
       public function isDelivered() {
           return $this->errorCode() === 0;
       }
   }
   

2. Add New Endpoints Extend the Clickatell class to support unsupported features (e.g., MMS):

   class ExtendedClickatell extends \Arcturial\Clickatell\Clickatell {
       public function sendMms(array $data) {
           $data['type'] = 'mms';
           return $this->post('mms/send', $data);
       }
   }
   

3. Webhook Integration Use Laravel’s route:list to verify webhook routes and handle Clickatell’s delivery reports:

   Route::post('clickatell/webhook', function (Request $request) {
       $payload = $request->json()->all();
       // Process delivery status (e.g., update DB)
   });
   

4. Fallback Mechanisms Implement a fallback to another SMS provider if Clickatell fails:

   try {
       $response = Clickatell::send([...]);
   } catch (\Exception $e) {
       $response = FallbackSms::send([...]);
   }