PHPackages                             101media/bird - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. 101media/bird

Abandoned → [spits-online/laravel-bird-api](/?search=spits-online%2Flaravel-bird-api)Library[API Development](/categories/api)

101media/bird
=============

This package allows you to connect to Bird's API using Laravel

2.0.4(1y ago)1405[1 issues](https://github.com/101Media/bird/issues)MITPHPPHP ^8.4

Since Dec 2Pushed 12mo ago1 watchersCompare

[ Source](https://github.com/101Media/bird)[ Packagist](https://packagist.org/packages/101media/bird)[ Docs](https://github.com/101media/bird)[ RSS](/packages/101media-bird/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (11)Versions (13)Used By (0)

[![image](https://repository-images.githubusercontent.com/820425309/723992d8-e187-420a-8bb6-b23c2991b8ca)](https://repository-images.githubusercontent.com/820425309/723992d8-e187-420a-8bb6-b23c2991b8ca)

Bird.com API Support for Laravel
================================

[](#birdcom-api-support-for-laravel)

1. [Introduction](#overview)
    - [Why This Package?](#why-this-package)
2. [Installation](#installation)
    - [Prerequisites](#prerequisites)
    - [Step-by-Step Installation](#step-by-step-installation)
3. [Configuration](#configuration)
4. [Usage](#usage)
    - [1. Contact Management](#1-contact-management)
        - [Retrieve Contacts](#retrieve-contacts)
        - [Retrieve a Single Contact](#retrieving-a-single-contact)
        - [Create or Update Contacts](#create-or-update-contacts)
        - [Delete Contacts](#delete-contacts)
        - [Contact Model Overview](#contact-model-overview)
    - [2. Sending Notifications](#2-sending-notifications)
        - [Supported Notification Channels](#supported-notification-channels)
        - [Example: Sending SMS Notifications](#example-sending-sms-notifications)
5. [Exception Handling](#exception-handling)
6. [Contributing](#contributing)
7. [License](#license)
8. [Contact](#contact)

Overview
--------

[](#overview)

The Laravel Bird Package simplifies integrating the powerful MessageBird API into your Laravel applications. It provides a user-friendly way to manage contacts and send notifications via SMS, WhatsApp, email, and more. This package is designed to make communication between [Laravel](https://laravel.com) and [Bird](https://bird.com)(AKA MessageBird) seamless and efficient.

### Why This Package?

[](#why-this-package)

- **Ease of Use**: Straightforward methods to interact with Bird's API.
- **Multi-Channel Support**: Send notifications via SMS, WhatsApp, Email, Telegram, and more.
- **Contact Management**: Create, update, retrieve, or delete contacts in Bird directly from your application.
- **Error Handling**: Built-in exception classes for better debugging and recovery.

Installation
------------

[](#installation)

### Prerequisites

[](#prerequisites)

Before installing this package, ensure your system meets the following requirements:

- **PHP**: Version `^8.3`
- **Laravel**: Version `^10.0`, `^11.0`, `^12.0`
- **Bird Account**

### Step-by-Step Installation

[](#step-by-step-installation)

1. Add the package to your Laravel project using Composer: ```
    composer require 101media/bird
    ```
2. Once installed, the package will automatically register the `BirdServiceProvider` using Laravel's package auto-discovery.
3. Run the following command to publish the package configuration: ```
    php artisan vendor:publish --tag="bird-config"
    ```

    This will create a `config/bird.php` file in your application.

Configuration
-------------

[](#configuration)

The `config/bird.php` file contains all configurable options, including:

- API Access Key: Set your Bird.com API access key via `BIRD_ACCESS_KEY` in the .env file.
- Workspace ID: Define your workspace using the `BIRD_WORKSPACE_ID` environment variable.
- Channel IDs: Specify channel IDs (e.g., SMS, WhatsApp, Email) for notifications in your .env file: ```
    BIRD_ACCESS_KEY={your-bird-access-key}
    BIRD_SMS_CHANNEL_ID={your-sms-channel-id}
    ```

For detailed configuration options, refer to the comments within the config/bird.php file.

Usage
-----

[](#usage)

### 1. Contact Management

[](#1-contact-management)

This package provides functionality for managing contacts via the Bird API. Below are the key actions you can perform with the `ContactService`.

#### Retrieve Contacts

[](#retrieve-contacts)

You can retrieve a list of contacts using the `index()` method. This allows you to specify the number of contacts to retrieve and whether to reverse the order of the results. To be able to retrieve the contacts, make sure you have specified your `BIRD_WORKSPACE_ID` in you `.env` file.

```
use Media101\Bird\Services\ContactService;

$birdContacts = app(new ContactService())->index(limit: 20, reverse: true);
```

Parameters:

- `limit`: The number of contacts to retrieve (default is 10).
- `reverse`: Set to `true` to retrieve contacts in reverse order.
- `nextPageToken`: Use for pagination when retrieving the next set of results.

#### Retrieving a single contact

[](#retrieving-a-single-contact)

You can also retrieve a single contact using the `show()` method. This allows you to get only one contact by specifying its id.

```
use Media101\Bird\Services\ContactService;

$birdContact = app(new ContactService())->show('bird-contact-id-123');
```

Parameters:

- `contactId`: The id of the contact

#### Create or Update Contacts

[](#create-or-update-contacts)

You can create or update a contact by passing a `Contact` object to the `createOrUpdate()` method. This method requires the contact's identifier (phone number or email address) to determine whether to create a new contact or update an existing one.

```
use Media101\Bird\Models\Contact;
use Media101\Bird\Enums\IdentifierKey;
use Media101\Bird\Services\ContactService;

$contact = (new Contact())
    ->displayName('John Doe')
    ->phoneNumber('+12345678901')
    ->emailAdress('johndoe@mail.com');

$response = (new ContactService())->createOrUpdate($contact, IdentifierKey::PHONE_NUMBER);
```

Parameters:

- `Contact`: The `Contact` object containing the contact information.
- `IdentifierKey`: The identifier type used to identify the contact (either `PHONE_NUMBER` or `EMAIL_ADDRESS`).

#### Delete Contacts

[](#delete-contacts)

To delete a contact, simply call the `delete()` method with the contact's ID.

```
use Media101\Bird\Services\ContactService;

$response = (new ContactService())->delete('contact-id-123');

if ($response === true) {
    // Successfully deleted the contact
    dd('Contact deleted successfully.');
} else {
    // Handle error
    dd($response);
}
```

Parameters:

- `contactId`: The unique ID of the contact to be deleted.

Return Values:

- Returns `true` if the deletion was successful.
- Returns an error response if the deletion failed.

---

#### Contact Model Overview

[](#contact-model-overview)

The `Contact` model provides an easy-to-use interface for building and manipulating contact records before sending them to the Bird API.

##### Example Contact Creation

[](#example-contact-creation)

```
use Media101\Bird\Models\Contact;

$contact = (new Contact())
    ->displayName('Jane Doe')
    ->phoneNumber('+98765432103')
    ->emailAdress('jane@example.com')
    ->attribute('company', 'Acme Corp');

// The contact can then be passed to the `ContactService` for API interaction
```

##### Contact Methods:

[](#contact-methods)

- `displayName(string $name)`: Sets the display name of the contact.
- `phoneNumber(string $number)`: Sets the phone number of the contact.
- `emailAdress(string $email)`: Sets the email address of the contact.
- `attribute(string $attribute, mixed $value)`: Adds additional attributes to the contact.
- `toArray()`: Converts the contact into an array for sending to Bird API.

Ensure to validate the phone number using the regex defined in the configuration (`bird.phone_number_regex`) before sending it to the API.

---

### 2. Sending Notifications

[](#2-sending-notifications)

This package supports a variety of notification channels, including SMS, WhatsApp, email, and more. Below are the details on using the SMS channel for sending notifications, leveraging predefined templates, and handling advanced use cases.

### Supported Notification Channels

[](#supported-notification-channels)

Currently, we only support the SMS channel. This is not going to be the case soon though, as we are planning on adding support for WhatsApp, facebook and telegram notification channels.

### Example: Sending SMS Notifications

[](#example-sending-sms-notifications)

The `SMSChannel` allows you to send SMS notifications by leveraging Laravel notification system. Make sure you are allowed to send SMS notifications using Bird. You need to configure an SMS channel before you can send SMS notifications.

#### Notification Class Example

[](#notification-class-example)

Define a custom notification class implementing the `toSMS` method.

```
use Illuminate\Notifications\Notification;
use Media101\Bird\Models\Messages\SMSMessage;
use Media101\Bird\Notifications\Channels\SMSChannel;

class OrderNotification extends Notification
{
    public function via(): array
    {
        return [ SMSChannel::class ];
    }

    public function toSMS($notifiable): SMSMessage
    {
        $contact = (new Contact())
            ->displayName('Jane Doe')
            ->phoneNumber('+98765432103')
            ->emailAdress('jane@example.com')
            ->attribute('company', 'Acme Corp');

        return (new SMSMessage())
            ->text('Your order has been shipped!')
            ->toContact($contact);
    }
}
```

#### Sending the Notification

[](#sending-the-notification)

You can send the notification using Laravel's `Notification` facade or the `notify` method.

```
use Illuminate\Support\Facades\Notification;

Notification::send($user, new OrderNotification());
```

### Exception Handling

[](#exception-handling)

The package uses custom exceptions to handle errors:

- `InvalidParameterException`: Thrown when a parameter is invalid.
- `ConnectionException`: Thrown when there is a connection error with the API.
- `NotAnSmsMessageException`: Thrown when the provided message is not an instance of `SMSMessage`.
- `NotificationNotSent`: Thrown when the notification could not be sent.

Make sure to catch these exceptions in your code to handle errors gracefully.

Contributing
------------

[](#contributing)

Please submit issues and pull requests to the [GitHub repository](https://github.com/101media/bird).

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT license](LICENSE).

Contact
-------

[](#contact)

For any inquiries or support, please contact [101Media](mailto:webapps@101media.nl).

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance29

Infrequent updates — may be unmaintained

Popularity17

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity63

Established project with proven stability

 Bus Factor1

Top contributor holds 53.6% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~16 days

Recently: every ~35 days

Total

10

Last Release

381d ago

Major Versions

1.2.0 → 2.0.02024-12-03

PHP version history (3 changes)1.0.0PHP ^8.2

1.2.0PHP ^8.3

2.0.1PHP ^8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/120329c84548b7ce0785ca352aec0dddb5c7f5f3cddcfceeeca45d6092a384af?d=identicon)[webapps101](/maintainers/webapps101)

---

Top Contributors

[![abrar-blip](https://avatars.githubusercontent.com/u/234959552?v=4)](https://github.com/abrar-blip "abrar-blip (30 commits)")[![SpitsAdmin](https://avatars.githubusercontent.com/u/16835345?v=4)](https://github.com/SpitsAdmin "SpitsAdmin (26 commits)")

---

Tags

laravelbird101media

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/101media-bird/health.svg)

```
[![Health](https://phpackages.com/badges/101media-bird/health.svg)](https://phpackages.com/packages/101media-bird)
```

###  Alternatives

[dedoc/scramble

Automatic generation of API documentation for Laravel applications.

2.0k7.8M55](/packages/dedoc-scramble)[scalar/laravel

Render your OpenAPI-based API reference

6183.9k2](/packages/scalar-laravel)[ryangjchandler/bearer

Minimalistic token-based authentication for Laravel API endpoints.

8129.8k](/packages/ryangjchandler-bearer)[combindma/laravel-facebook-pixel

Meta pixel integration for Laravel

4956.9k](/packages/combindma-laravel-facebook-pixel)[stechstudio/laravel-hubspot

A Laravel SDK for the HubSpot CRM Api

2971.0k](/packages/stechstudio-laravel-hubspot)[likeabas/filament-chatgpt-agent

Integrate with OpenAI ChatGPT

235.3k](/packages/likeabas-filament-chatgpt-agent)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)