Laravel Chatwork Laravel Package

Getting Started

1. Install the package

   composer require sun-asterisk/laravel-chatwork
   

   Laravel's package auto-discovery should register the service provider and the Chatwork facade alias. If you're on an older Laravel version (or auto-discovery is disabled), add the provider and alias to config/app.php manually.

2. Publish the config and set the token

   php artisan vendor:publish --tag=chatwork
   

   Then in .env:

   CHATWORK_API_KEY=your_personal_api_token
   

   The token comes from Chatwork → Account Settings → API Token. This is a per-user token, not an organization-level credential — plan for that (see Gotchas).

3. Where to look first

   • config/chatwork.php — base URL, timeout, and any default room settings the package exposes.
   • The facade class (SunAsterisk\Chatwork\Facades\Chatwork) — the public method surface is small; read the source before relying on it.
   • The README's usage example — this package is a thin SDK wrapper, so the README is effectively the API reference.

4. First use case: post a message to a room

   use SunAsterisk\Chatwork\Facades\Chatwork;
   
   Chatwork::room(123456789)->message()->create('Deploy finished on production.');
   

   Start with a single hardcoded room ID in a console command (php artisan chatwork:ping) to prove the token and network path work before wiring it into application events.

Implementation Patterns

Wrap the facade in your own service class. Don't scatter Chatwork:: calls across controllers. A single App\Services\ChatworkNotifier gives you one seam to swap, mock, and retry:

class ChatworkNotifier
{
    public function notify(int $roomId, string $body): void
    {
        Chatwork::room($roomId)->message()->create($body);
    }
}

Fire from domain events, not inline. Treat Chatwork as a side channel. Listen to events (OrderFailed, DeployCompleted, InvoiceOverdue) and send from a listener, so the core flow doesn't depend on Chatwork being reachable.

Queue the sends. Implement ShouldQueue on the listener or wrap the call in a queued job. Chatwork's API is an external network hop; blocking a web request on it will bite you during incidents — exactly when you most want the alert to go out.

Fan out with a config map. Keep room IDs in config/chatwork.php keyed by purpose (alerts, deploys, support), not scattered as magic integers:

foreach (config('chatwork.rooms.alerts') as $roomId) {
    app(ChatworkNotifier::class)->notify($roomId, $message);
}

Build a notification channel. For day-to-day reach, wrap the package in a custom NotificationChannel so Chatwork becomes a first-class channel alongside mail and Slack:

public function send($notifiable, Notification $notification)
{
    $roomId = $notification->toChatwork($notifiable);
    Chatwork::room($roomId)->message()->create($notification->message);
}

This lets you route Laravel's existing notification system (including Notification::route()) at Chatwork without new plumbing.

Scheduled digests. Combine with the scheduler for daily standups, weekly metrics, or stale-ticket reports. Build the body as a string with Chatwork's markup ([info][title]Daily Report[/title]...[/info]) and send one message per room rather than one message per line.

Error-hook integration. Wire it into app/Exceptions/Handler::report() or a MessageLogged listener for critical-level log entries. Guard it behind an environment check so local development never pings the team room.

Testing. Never hit the real API in tests. Because this is a thin HTTP wrapper, Http::fake() around the underlying request generally works; otherwise bind a fake notifier into the container and assert on notify() calls.

Gotchas and Tips

The token is a personal credential. It authenticates as the user who generated it, so messages appear to come from that person. Create a dedicated bot account, add it to the relevant rooms, and use its token. Otherwise a departing employee's account rotation silently breaks your alerts.

Rate limits are real. Chatwork enforces per-token request limits. Fan-out loops and log-triggered alerts are the usual offenders — throttle with Redis::throttle(), batch messages into a single room post, and never call the API inside a foreach over users.

Escape user-generated content. Chatwork message bodies interpret tags like [To:], [info], [code], and [hr]. If you interpolate exception messages or user input straight in, malformed input can swallow the rest of your message or ping the wrong people. Sanitize brackets before sending.

Don't assume a return contract. This is a low-traffic package (17 stars, essentially zero dependents), so verify how it surfaces HTTP failures — it may throw, or it may return a response object with a status. Wrap your calls in a try/catch, log the failure, and decide explicitly whether a failed notification should fail the parent job or be swallowed with a warning.

Cache and config changes. After editing CHATWORK_API_KEY or room IDs in production, run php artisan config:clear (or re-run config:cache). A stale config cache is the most common "the token is right but it 401s" cause.

Pin the version and audit the source. With a small maintainer surface, treat upgrades as meaningful events: composer require sun-asterisk/laravel-chatwork:^x.y with an explicit constraint, and read the diff. The package is thin enough that the whole surface is auditable in a few minutes — do that once, up front.

Have an escape hatch. Because the wrapper is slim, the cost of falling back to Http::withToken(config('chatwork.api_key'))->post(...) is low. If you hit an API endpoint the package doesn't cover, don't fork it — call the REST endpoint directly from the same service class.

Extension points are limited. There's no rich event system or pluggable transport here. Your extension point is your own wrapper class; keep all package contact inside it so a future swap is a one-file change rather than a grep across the codebase.

Local development. Set CHATWORK_ENABLED=false (or check app()->isProduction()) in your service class so test suites and local debugging never post to real rooms — a misconfigured listener firing on every local exception page is an embarrassing and noisy failure mode.