Download the PHP package spits-online/laravel-bird without Composer

Bird SMS and WhatsApp for Laravel

[](https://packagist.org/packages/spits-online/laravel-bird) [](https://github.com/Spits-online/laravel-bird/actions/workflows/run-tests.yml) [](https://github.com/Spits-online/laravel-bird/actions/workflows/phpstan.yml) [](https://packagist.org/packages/spits-online/laravel-bird)

Notification channels for Bird (formerly MessageBird), plus a small client for the contacts in your workspace.

Requirements

• PHP 8.3+
• Laravel 12 or 13
• A Bird workspace with an SMS and/or WhatsApp channel

Installation

Add your credentials to .env. Only the channels you use need an id.

You'll find these in Bird:

• Access key: Settings → Access keys.
• Workspace id: Settings → Workspace.
• Channel ids: Channels → your SMS or WhatsApp channel → Channel ID.

That's all the configuration most apps need, so you don't have to publish a config file. When you do want to change something, such as package defaults key by key, so everything you leave out keeps its default:

Don't copy keys at their default value. A copied default looks like a deliberate choice, and it stops following the package when the default changes. To see every option, you can publish the full file with php artisan vendor:publish --tag="bird-config". Keep the keys you change and delete the rest.

Using another workspace

The facade uses the workspace in your config. Build a client for another one with fromConfig(), which takes the same keys:

Bird::fake() only replaces the client behind the facade. A client you build with fromConfig() still calls Bird, so fake its requests in your tests with Http::fake().

Sending notifications

Choosing the recipient

The channels send to whatever routeNotificationForBird() on your notifiable returns: a phone number in international format, or an array of them to send to several people.

To send to someone else, set the recipient on the message (->to('+31612345678')), or send an on-demand notification:

to() takes several recipients at once. A value with an @ is sent as an email address, anything else as a phone number, the way Identifier::from() reads it. You can also pass an Identifier:

bird is the route name both Bird channels read, like mail for the mail channel. A phone number is the same for SMS and WhatsApp, so you set it once, and the notification's via() still decides which channels send.

SMS

Add SmsChannel to via() and return an SmsMessage from toBirdSms(), as in the example at the top.

WhatsApp

To start a WhatsApp conversation you need a template approved in Bird Studio. Add WhatsAppChannel to via() and return a WhatsAppMessage from toBirdWhatsApp():

The template's parameters are the variables you defined in Bird Studio. Each value is sent with a matching type: a boolean as boolean, an int or float as number, an array as object, and everything else as string. The version defaults to latest; pass version: to pin one.

Naming templates

To avoid repeating project ids, give your templates a name in your app's config/bird.php. Each entry needs a project_id. version (default latest) and locale are optional:

version pins a template version instead of using the latest.

Then use them by name:

Inside WhatsApp's 24-hour service window you can also send any other message body Bird supports:

SMS and WhatsApp together

A notification can use both channels. Each one calls its own method:

Sending without a notification

Pass a channelId to send through a channel other than the configured one: Bird::send($message, channelId: '…').

Managing contacts

upsert() creates the contact, or updates the one with this phone number or email address. Pass an Identifier::email() to match on the email address:

Contacts are listed a page at a time:

Error handling

Every exception extends SpitsOnline\Bird\Exceptions\BirdException:

A 404 status means the contact doesn't exist.

When a channel throws, Laravel fires its NotificationFailed event. For queued notifications, the job is retried as usual.

Testing your app

Bird::fake() records messages instead of sending them:

Bird::sent() returns the sent messages themselves, optionally filtered:

A message tells you who it goes to and what Bird would receive:

Contact calls go through Laravel's HTTP client, so fake them with Http::fake().

Testing

Changelog

Please see UPGRADE.

Contributing

Please see CONTRIBUTING for details.

Security vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• SpitsOnline
• All Contributors

License

The MIT License (MIT). Please see License File for more information.