Laravel Zoho Cliq Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require realrashid/laravel-zoho-cliq
   

   Publish the config file:

   php artisan vendor:publish --provider="Realrashid\ZohoCliq\ZohoCliqServiceProvider" --tag="config"
   

2. Configuration: Update .env with your Zoho Cliq credentials:

   ZOHO_CLIQ_CLIENT_ID=your_client_id
   ZOHO_CLIQ_CLIENT_SECRET=your_client_secret
   ZOHO_CLIQ_REDIRECT_URI=http://your-app.test/zoho-cliq/callback
   ZOHO_CLIQ_ACCESS_TOKEN=your_access_token  # Optional (for direct API calls)
   

3. First Use Case: Send a simple message to a user:

   use Realrashid\ZohoCliq\Facades\ZohoCliq;
   
   ZohoCliq::sendMessage('user@example.com', 'Hello from Laravel!');
   

4. Authentication Flow: Redirect users to Zoho Cliq for OAuth:

   return ZohoCliq::auth()->redirect();
   

   Handle the callback in your routes:

   Route::get('/zoho-cliq/callback', [ZohoCliqController::class, 'handleCallback']);
   

Implementation Patterns

Core Workflows

1. Sending Messages:

   • Basic Text:

     ZohoCliq::sendMessage('user@example.com', 'Hello!');
     

   • Rich Content (Markdown/HTML):

     ZohoCliq::sendRichMessage('user@example.com', [
         'text' => 'Hello!',
         'markdown' => true,
         'attachments' => [
             ['title' => 'Report', 'url' => 'https://example.com/report.pdf']
         ]
     ]);
     

   • To Channels:

     ZohoCliq::sendChannelMessage('channel_id', 'Team update: ...');
     

2. File Sharing:

   ZohoCliq::uploadFile('user@example.com', 'path/to/file.pdf', 'Report.pdf');
   

3. User Management:

   // List users in a channel
   $users = ZohoCliq::getChannelUsers('channel_id');
   

4. Event Listeners: Integrate with Laravel events (e.g., user.registered):

   event(new UserRegistered($user));
   // In a listener:
   ZohoCliq::sendMessage($user->email, 'Welcome! Your account is ready.');
   

Integration Tips

• Queue Jobs: Offload Cliq messages to a queue for async processing:

  dispatch(new SendCliqMessageJob('user@example.com', 'Hello!'));
  

  Implement the job:

  public function handle()
  {
      ZohoCliq::sendMessage($this->email, $this->message);
  }
  

• Middleware: Attach Cliq notifications to authenticated routes:

  Route::middleware(['auth', 'notify.cliq'])->group(function () {
      // Routes that trigger Cliq notifications
  });
  

• Laravel Notifications: Extend Laravel’s Notification class:

  use Realrashid\ZohoCliq\Notifications\CliqMessage;
  
  Notification::route('cliq', 'user@example.com')
              ->notify(new CliqMessage('Your task is complete!'));
  

Gotchas and Tips

Pitfalls

1. Token Expiry:

   • Access tokens expire (typically 30 days). Implement token refresh logic:

     try {
         ZohoCliq::sendMessage(...);
     } catch (\Realrashid\ZohoCliq\Exceptions\TokenExpiredException $e) {
         ZohoCliq::auth()->refreshToken();
         // Retry the failed operation
     }
     

2. Rate Limits:

   • Zoho Cliq enforces rate limits (e.g., 100 messages/hour). Cache frequent messages or implement exponential backoff:

     if (ZohoCliq::isRateLimited()) {
         sleep(ZohoCliq::getRetryAfter());
     }
     

3. Email vs. User ID:

   • The package defaults to email-based messaging. For internal teams, use user_id (if available) for reliability:

     ZohoCliq::sendMessage('user_id:12345', 'Hello!');
     

4. Webhook Delays:

   • Real-time webhooks may have delays. Use polling for critical updates:

     $messages = ZohoCliq::getRecentMessages('channel_id', 10);
     

Debugging

• Enable Logging: Add to config/zoho-cliq.php:

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

  Check logs for API responses/errors:

  tail -f storage/logs/laravel.log | grep zoho-cliq
  

• API Response Inspection: Use the debug() method to inspect raw responses:

  $response = ZohoCliq::sendMessage(...)->debug();
  

Extension Points

1. Custom Message Formats: Extend the MessageBuilder:

   namespace App\Services;
   
   use Realrashid\ZohoCliq\MessageBuilder;
   
   class CustomMessageBuilder extends MessageBuilder
   {
       public function addCustomField($key, $value)
       {
           $this->payload['custom_fields'][$key] = $value;
           return $this;
       }
   }
   

   Register the binding:

   $this->app->bind(MessageBuilder::class, function () {
       return new CustomMessageBuilder();
   });
   

2. Webhook Handlers: Create a custom webhook controller:

   use Realrashid\ZohoCliq\Webhook;
   
   class CliqWebhookController extends Webhook
   {
       protected $events = [
           'message.created' => 'App\Listeners\HandleNewMessage',
       ];
   }
   

   Register in AppServiceProvider:

   public function boot()
   {
       $this->app->make(\Realrashid\ZohoCliq\Webhook::class);
   }
   

3. Testing: Use the ZohoCliqFake for unit tests:

   use Realrashid\ZohoCliq\Facades\ZohoCliq;
   use Realrashid\ZohoCliq\Testing\ZohoCliqFake;
   
   beforeEach(function () {
       ZohoCliqFake::fake();
   });
   
   it('sends a message', function () {
       ZohoCliq::sendMessage('user@example.com', 'Test');
       ZohoCliqFake::assertSent(function ($message) {
           return $message->to == 'user@example.com';
       });
   });
   

Config Quirks

• Redirect URI: Ensure the ZOHO_CLIQ_REDIRECT_URI matches exactly what’s registered in Zoho Cliq’s developer console (including trailing slashes).

• Scopes: Request additional OAuth scopes during auth:

  ZohoCliq::auth()->scopes(['ZohoCliq.users.READ', 'ZohoCliq.channels.CREATE']);
  

• Proxy Support: Configure proxy settings in config/zoho-cliq.php if behind a firewall:

  'proxy' => [
      'host' => env('HTTP_PROXY_HOST'),
      'port' => env('HTTP_PROXY_PORT'),
      'username' => env('HTTP_PROXY_USER'),
      'password' => env('HTTP_PROXY_PASS'),
  ],