Messagebird Laravel Package

Getting Started

1. Install and wire credentials.

   composer require laravel-notification-channels/messagebird
   

   Then add the key to config/services.php:

   'messagebird' => [
       'access_key' => env('MESSAGEBIRD_ACCESS_KEY'),
       'originator' => env('MESSAGEBIRD_ORIGINATOR'), // optional default sender
   ],
   

   The package auto-registers its service provider on Laravel 5.5+; there is nothing to publish. As of v4.4.0 the package is tested against Laravel 13.x, so it is a safe dependency on modern Laravel stacks.

2. Teach your notifiable how to be reached. Add a routeNotificationForMessageBird() method returning a phone number or an array of numbers:

   public function routeNotificationForMessageBird($notification)
   {
       return $this->phone; // e.g. '31612345678'
   }
   

3. Build your first notification.

   use NotificationChannels\Messagebird\MessageBirdChannel;
   use NotificationChannels\Messagebird\MessageBirdMessage;
   
   public function via($notifiable) { return [MessageBirdChannel::class]; }
   
   public function toMessageBird($notifiable)
   {
       return MessageBirdMessage::create("Your order #{$this->order->id} has shipped.");
   }
   

4. Where to look first. The README is short and complete; then read src/MessageBirdChannel.php (about 40 lines — it resolves the route, builds the message, calls the SDK) and src/MessageBirdMessage.php (the fluent builder). After that, the only other reference you need is MessageBird's own SMS API docs, because the message object is a thin mirror of that payload.

5. Canonical first use case. A one-way transactional SMS — OTP, order status, appointment reminder — where you already have a Laravel notification and just want a second channel next to mail/database. If you need anything beyond outbound SMS (WhatsApp, voice, conversations), this channel is not the tool.

Implementation Patterns

Basic transactional notification. Keep toMessageBird() returning the fluent message and let the channel handle delivery. MessageBirdMessage::create($body) is shorthand for (new MessageBirdMessage)->content($body).

Anonymous / on-demand recipients. Useful for verification codes to a number captured in a form, with no User model:

Notification::route('messagebird', ['31612345678'])->notify(new SendVerificationCode($code));

The route key must match the string messagebird exactly.

Multi-recipient sends. Passing an array to routeNotificationForMessageBird() or ->recipients([...]) sends one API call per recipient. For fan-out to many numbers, loop inside a queued job rather than stuffing hundreds of numbers into one message.

Per-message overrides. The builder exposes the SMS API's fields — originator(), recipients(), type(), datacoding(), reference(), reportUrl(), validity(), gateway(), typeDetails(), payload(). Two are worth adopting as a habit:

• reference() — your internal ID, echoed back in delivery reports, the cheapest way to correlate.
• reportUrl() — a signed webhook route to receive delivered/failed status.

Fallback fan-out. via() returning [MessageBirdChannel::class, MailChannel::class] with ShouldQueue is the standard resilience pattern: SMS is best-effort, mail/database is the durable record. Since the SMS channel can silently no-op (see Gotchas), never let SMS be the only evidence a notification was sent.

Localization. $notification->locale('nl')->notify(...) works normally; the channel doesn't interfere with translations inside toMessageBird().

Testing. There is no MessageBird::fake() shipped. Use Laravel's Notification::fake() and assert against the message payload you built, which is where your logic actually lives:

Notification::fake();
Notification::route('messagebird', '31612345678')->notify(new OrderShipped($order));

Notification::assertSentOnDemand(OrderShipped::class, function ($n, $channels, $notifiable) {
    return $n->toMessageBird($notifiable)->content === '...';
});

To assert the channel actually fired without network I/O, bind a mock over the underlying MessageBird\Client in the container or use a Guzzle mock handler — Http::fake() will not intercept the SDK.

Gotchas and Tips

Silent no-op when the route is empty. If routeNotificationForMessageBird() returns null/[], the channel returns early — no exception, no log. This is the #1 "why didn't my SMS send" cause. Assert during development that your notifiable has a normalized phone column.

Phone format. MessageBird expects digits with country code and no leading + or separators (31612345678). A raw +31 6 1234 5678 from user input is the second most common failure. Normalize in the notifiable, not in the notification.

Originator rules. Alphanumeric sender IDs are capped at 11 characters and are not deliverable in the US/Canada, where you must use a provisioned long code or short code. Numeric sender IDs need per-country registration. Test with your real target country — a working dev setup in NL says nothing about US deliverability.

Exceptions are wrapped. SDK/HTTP failures surface as NotificationChannels\Messagebird\Exceptions\CouldNotSendNotification (which also covers missing recipients/body). Catch it in a job wrapper if you want retries with backoff; otherwise a queued notification fails the job and triggers your normal failed_jobs handling.

Unicode and length. Default datacoding is plain GSM-7 (160 chars, 153 per concatenated segment). Any non-GSM character (emoji, curly quotes, many accents) forces UCS-2 at 70/67 chars — one emoji can triple your segment count and cost. Set ->datacoding('unicode') only when you know you need it, and strip smart quotes from templated copy.

Config caching. services.messagebird is read at send time from the config repository; after changing .env, run php artisan config:clear (or config:cache) or you'll debug a stale key for twenty minutes.

Method-name casing. routeNotificationForMessageBird and routeNotificationForMessagebird both work (PHP method names are case-insensitive) but pick one and lint for it — mixed casing across models is a real source of "works on my model, not yours."

Version support. v4.4.0 adds Laravel 13.x compatibility (a laravel-shift automated bump); v4.3.0 covered the preceding Laravel line. The wrapper itself is unchanged across these minor releases, so upgrade risk is low. Still pin a minor version in composer.json (e.g. ^4.4) — the package has a low release cadence and only guarantees framework compatibility at release time, not forward-compatibility with a future Laravel major.

Extension points are thin. This is a ~two-file wrapper around messagebird/php-rest-api. If you need retries, rate limiting, templated bulk sends, or delivery-report persistence, you will write that yourself around the notification, not inside it. That's fine — just don't expect the package to grow with you, and pin the version in composer.json rather than relying on a floating constraint given the low release cadence.

Debugging playbook. Reproduce the exact payload ($message->toArray()) and hit the MessageBird dashboard's API logs; the SDK's exception message usually contains the API error code, which is more specific than the wrapped exception alone.