Messagebird

Instalation

composer require qore/messagebird

Usage

Creating a message

The following types of messages are currently supported:

• Text
• Template

Text

You can create a text type message (simple message) by calling the text method on the Message class.

This method will give you a builder class that you will have to return back in the closure.

$message = Message::make()
    ->text(fn(\Qore\Messagebird\Message\Text\TextBuilder $builder) => $builder
        ->text('The following text is a message')
    );

Actions

Reply actions can be set for messages that are going to be sent through the following available channels from Messagebird:

• WhatsApp

$message = Message::make()
    ->text(fn(\Qore\Messagebird\Message\Text\TextBuilder $builder) => $builder
        ->text('The following text is a message')
        ->action(fn (\Qore\Messagebird\Message\Text\ActionBuilder $builder) => $builder
            ->reply('Reply with this message')
        )
    );

Multiple actions can be set by calling the action builder again.

$message = Message::make()
    ->text(fn(\Qore\Messagebird\Message\Text\TextBuilder $builder) => $builder
        ->text('The following text is a message')
        ->action(fn (\Qore\Messagebird\Message\Text\ActionBuilder $builder) => $builder
            ->reply('Reply with this message')
        )
        ->action(fn (\Qore\Messagebird\Message\Text\ActionBuilder $builder) => $builder
            ->reply('Reply with another message')
        )
    );

danger

Setting actions on messages that are going via SMS channel will make it fail being delivered.

Template

You can send templates (created from inside the Messagebird studio) by calling the template method on the Message class.

Same as text method, this method returns a builder as a parameter in a closure.

$message = Message::make()
    ->template(fn(\Qore\Messagebird\Message\Template\TemplateBuilder $builder) => $builder
        // build here
    );

Setting the template/project id

The Project/Template ID refer to the same id. This is a required setting for the builder and you can set it calling either the projectId or the templateId method.

$message = Message::make()
    ->template(fn(\Qore\Messagebird\Message\Template\TemplateBuilder $builder) => $builder
        ->templateId('0372763f-d313-4bcb-87f9-29e8c31a2ca8')
    );

Setting variables

You can add values to variables defined in the template by calling the variable method on the builder.

$message = Message::make()
    ->template(fn(\Qore\Messagebird\Message\Template\TemplateBuilder $builder) => $builder
        ->templateId('0372763f-d313-4bcb-87f9-29e8c31a2ca8')
        ->variable('name', 'Andrei Croitoru')
    );

You can add multiple variable values by calling the method many times.

$message = Message::make()
    ->template(fn(\Qore\Messagebird\Message\Template\TemplateBuilder $builder) => $builder
        ->templateId('0372763f-d313-4bcb-87f9-29e8c31a2ca8')
        ->variable('name', 'Andrei Croitoru')
        ->variable('date', '1st of September')
        ->variable('status', 'Success')
    );

Setting locale

The default locale that will be used is the application locale, i.e.: App::getLocale().

You can override the locale that will be used for the message by calling the locale method on the builder.

$message = Message::make()
    ->template(fn(\Qore\Messagebird\Message\Template\TemplateBuilder $builder) => $builder
        ->templateId('0372763f-d313-4bcb-87f9-29e8c31a2ca8')
        ->locale('ro')
    );

Setting the version

The default version that will be used is the latest published version.

You can override this by calling the version method on the builder.

$message = Message::make()
    ->template(fn(\Qore\Messagebird\Message\Template\TemplateBuilder $builder) => $builder
        ->templateId('0372763f-d313-4bcb-87f9-29e8c31a2ca8')
        ->version('33074e90-1a0f-491e-865e-709a35d39dae')
    );

Setting a recipient

For the message to get to someone you need to set a recipient.

You can set a recipient by calling the receiver method on the Message class.

$message = Message::make()
    ->text(fn(\Qore\Messagebird\Message\Text\TextBuilder $builder) => $builder
        ->text('The following text is a message')
    )
    ->receiver('+310880123900');

Multiple recipients can be added by calling the method again.

$message = Message::make()
    ->text(fn(\Qore\Messagebird\Message\Text\TextBuilder $builder) => $builder
        ->text('The following text is a message')
    )
    ->receiver('+310880123900')
    ->receiver('+310880123901');

Sending a message

You can call the Messagebird helpers sendMessage method to send a message class.

Qore\Messagebird\Messagebird::sendMessage($message);

The sendMessage accepts overriding the workspaceId and channelId, by default it will use the ones defined in the plugin configuration.

Qore\Messagebird\Messagebird::sendMessage(
    message: $message,
    channelId: 'custom-channel-for-this-message'
);

Sending a message via notification

This plugin creates a custom Notification channel that can be used to send notification classes.

Notification Class

Your notification needs to implement the SendableWithMessagebird contract, that will force you to implement a method named toMessagebird.

This method will return a Message, without receipients.

use Qore\Messagebird\Message\Message;
use Qore\Messagebird\Message\Text\TextBuilder;
use Qore\Messagebird\Notifications\MessagebirdChannel;
use Qore\Messagebird\Notifications\SendableWithMessagebird;
use Illuminate\Notifications\Notification;

class TestNotification extends Notification implements SendableWithMessagebird
{
    public function via(): array
    {
        return [MessagebirdChannel::class];
    }

    public function toMessagebird(mixed $notifiable): Message
    {
        return Message::make()
            ->text(fn (TextBuilder $builder) => $builder
                ->text('Message from notification class')
            );
    }
}

Notifiable Class

The notifiable class needs to implement a method named routeNotificationForMessagebird.

class User extends Model
{
    use Notifiable;

    public function routeNotificationForMessagebird()
    {
        return '+310880123900';
    }
}

Multiple recipients can be set, as for messages by using an array.

class User extends Model
{
    use Notifiable;

    public function routeNotificationForMessagebird()
    {
        return [
            '+310880123900',
            '+310880123901',
        ];
    }
}

tip

Currently the channel doesn't support setting custom channel ids for sending to different channels, not the default one (the plugins settings).

For this you should create a custom channel using the Messagebird::sendMessage client.

Sending a message manually

You can make use of the HTTP client to manually send a message.

use Illuminate\Support\Facades\Crypt;
use Qore\Messagebird\MessagebirdClient;
use GuzzleHttp\Exception\ClientException;

$client = new MessagebirdClient(Crypt::decrypt(setting('qore/messagebird', 'authorization_token')));

$workspaceId = setting('qore/messagebird', 'workspace_id');
$channelId = setting('qore/messagebird', 'channel_id');

try {
    $client->sendMessage($workspaceId, $channelId, $message)
} catch (ClientException $exception) {
    // message couldn't be sent
}

info

Messages that couldn't be delivered will not throw an exception here, it is visible inside the channels status in Messagebird platform.

The exception is triggered by an API exception i.e. an malformed message object.

Plugin Configuration

The following settings are required:

• API Key Used to connect to Messagebirds API
• Workspace ID Used as default workspaceId parameter when talking to the Messagebird API
• Channel ID Used as default channelId parameter when talking to the Messagebird API