Driver Hangouts Laravel Package

Getting Started

Treat this package as a thin BotMan 2.x driver, not a maintained Google Chat SDK. Last release was 2018 and the repo is unknown, so verify compatibility before adopting.

Minimal steps:

1. Check your BotMan/Laravel/PHP versions first. This package most likely targets BotMan 2.x and PHP 7.x. On Laravel 10/11 or BotMan 3/4, expect Composer conflicts or runtime issues.
2. Require it alongside BotMan:

   composer require botman/botman botman/driver-hangouts
   

3. Inspect the installed source before configuring anything:
   • vendor/botman/driver-hangouts/src/
   • the main driver class, usually HangoutsChatDriver.php
   • composer.json for namespace/autoload and PHP constraints
   • any config, service provider, or README files
4. Register the driver in your BotMan bootstrap or service provider:

   use BotMan\BotMan\Drivers\DriverManager;
   use BotMan\Drivers\HangoutsChat\HangoutsChatDriver;
   
   DriverManager::loadDriver(HangoutsChatDriver::class);
   

   Verify the exact namespace from the vendor source; do not assume it.
5. Configure credentials using the keys the driver actually reads. Expect Google service-account or bot-token style config. Keep secrets in .env and avoid committing service-account JSON.
6. Expose a public HTTPS webhook route for Google Chat/Hangouts Chat and point the bot configuration at it. Exclude the route from CSRF in Laravel.
7. First use case: a room/DM echo bot. Send ping, reply pong:

   $bot->hears('ping', function ($bot) {
       $bot->reply('pong');
   });
   

Where to look first: the driver source and its request/response methods. This package is old enough that the source is the documentation.

Implementation Patterns

• Keep conversation logic in BotMan and isolate Hangouts specifics behind the driver. Use standard hears, receives, ask, reply, conversations, and middleware.
• Register the webhook route with BotMan’s controller or a dedicated controller. In Laravel, make sure the route accepts the HTTP method Google sends and is excluded from CSRF:

  Route::post('/botman/hangouts', [BotManController::class, 'handle']);
  

• Return quickly from the webhook. Validate and enqueue slow work with Laravel jobs/queues, then send replies through the BotMan instance or Hangouts API as appropriate.
• Use middleware for cross-cutting concerns: request logging, JWT/authorization verification, tenant/space resolution, rate limiting, and audit trails.
• For multi-space bots, capture raw payload details early. Hangouts/Google Chat payloads include space, sender, message, and thread information. Use $bot->getMessage()->getPayload() to inspect them.
• Threading matters in rooms. If the driver does not automatically preserve thread names, capture the incoming thread.name and include it on outgoing replies. Otherwise replies may appear as new threads.
• Rich messages are a risk. Hangouts Chat supported cards, but this old driver may only map basic text. Check the driver’s message-sending methods before promising buttons/cards.
• Test conversation logic with BotMan’s web driver or a local test harness, then use ngrok or a tunnel for real webhook testing.
• If the driver lacks a feature, extend it rather than scattering raw Google API calls through controllers. Override the request-building or message-matching methods in a subclass.

Gotchas and Tips

• Staleness is the main risk. “Hangouts Chat” was rebranded to Google Chat, and Google’s APIs/auth requirements have changed since 2018. Verify endpoints, scopes, webhook verification, and payload shapes against current Google Chat docs.
• Do not assume Laravel auto-discovery. You may need to manually register the driver and any service provider.
• If BotMan says no driver matched or the driver is unsupported, confirm DriverManager::loadDriver(...) ran before handling the request and that the class name is correct.
• Inspect the driver for exact config keys. Missing or misnamed credentials often fail at send time, not at webhook receipt time.
• Webhook security is your responsibility if the driver does not verify Google’s authorization/JWT. Add middleware to validate requests before passing them to BotMan.
• Google requires HTTPS webhook URLs. Local HTTP URLs will not work directly.
• Handle non-message events explicitly if needed: added/removed from space, card clicks, etc. The driver may only process normal messages.
• Watch for room-thread bugs: a bot that replies without the correct thread name can create noisy side conversations.
• Clear Laravel config cache after changing driver config: php artisan config:clear.
• Log raw incoming payloads during setup. This is the fastest way to discover what the driver exposes and what Google actually sends.
• Rate limits and retries are not free. Add backoff/retry handling around outbound sends and avoid blocking the webhook response.
• Extension point: subclass the driver and override request sending or message parsing. This is usually cleaner than bypassing BotMan entirely.