This package makes it easy to send notifications using the Facebook Messenger with Laravel.
You can install the package via composer:
composer require laravel-notification-channels/facebook
Follow the Getting Started guide in order to create a Facebook Messenger app, a Facebook page and a page token, which is connecting both.
Next we need to add this token to our Laravel configurations. Create a new Facebook section inside config/services.php
and place the page token there:
// config/services.php
...
'facebook' => [
'page-token' => env('FACEBOOK_PAGE_TOKEN', 'YOUR PAGE TOKEN HERE'),
// Optional - Omit this if you want to use default version.
'version' => env('FACEBOOK_GRAPH_API_VERSION', '4.0')
// Optional - If set, the appsecret_proof will be sent to verify your page-token.
'app-secret' => env('FACEBOOK_APP_SECRET', '')
],
...
Let's take an invoice-paid-notification as an example.
You can now use the Facebook channel in your via()
method, inside the InvoicePaid class. The to($userId)
method defines the Facebook user, you want to send the notification to.
Based on the details you add (text, attachments etc.) will determine automatically the type of message to be sent. For example if you only add text()
then it will be a basic message; using attach()
will turn this into a attachment message. Having buttons
or cards
will change this to the Button Template
and Generic Template
respectivily
use NotificationChannels\Facebook\FacebookChannel;
use NotificationChannels\Facebook\FacebookMessage;
use NotificationChannels\Facebook\Components\Button;
use NotificationChannels\Facebook\Enums\NotificationType;
use Illuminate\Notifications\Notification;
class InvoicePaid extends Notification
{
public function via($notifiable)
{
return [FacebookChannel::class];
}
public function toFacebook($notifiable)
{
$url = url('/invoice/' . $this->invoice->id);
return FacebookMessage::create()
->to($notifiable->fb_messenger_user_id) // Optional
->text('One of your invoices has been paid!')
->isUpdate() // Optional
->isTypeRegular() // Optional
// Alternate method to provide the notification type.
// ->notificationType(NotificationType::REGULAR) // Optional
->buttons([
Button::create('View Invoice', $url)->isTypeWebUrl(),
Button::create('Call Us for Support!', ' 1(212)555-2368')->isTypePhoneNumber(),
Button::create('Start Chatting', ['invoice_id' => $this->invoice->id])->isTypePostback() // Custom payload sent back to your server
]); // Buttons are optional as well.
}
}
The notification will be sent from your Facebook page, whose page token you have configured earlier. Here's a screenshot preview of the notification inside the chat window.
Send a basic text message to a user
return FacebookMessage::create('You have just paid your monthly fee! Thanks')
->to($notifiable->fb_messenger_user_id);
Send a file attachment to a user (Example is sending a pdf invoice)
return FacebookMessage::create()
->attach(AttachmentType::FILE, url('invoices/'.$this->invoice->id))
->to($notifiable->fb_messenger_user_id);
Send a set of cards / items to a user displayed in a carousel (Example is sending a set of links). Note you can also add up to three buttons per card
return FacebookMessage::create()
->to($notifiable->fb_messenger_user_id) // Optional
->cards([
Card::create('Card No.1 Title')
->subtitle('An item description')
->url('items/'.$this->item[0]->id)
->image('items/'.$this->item[0]->id.'/image'),
Card::create('Card No.2 Title')
->subtitle('An item description')
->url('items/'.$this->item[1]->id)
->image('items/'.$this->item[1]->id.'/image')
// could add buttons using ->buttons($array of Button)
]);
You can either send the notification by providing with the page-scoped user id (PSID) of the recipient to the to($userId)
method like shown in the above example or add a routeNotificationForFacebook()
method in your notifiable model:
...
/**
* Route notifications for the Facebook channel.
*
* @return int
*/
public function routeNotificationForFacebook()
{
return $this->fb_messenger_user_id;
}
...
to($recipient, $type)
: (string|array) Recipient's page-scoped Userid
,phone_number
,user_ref
,post_id
orcomment_id
(as one of the supported types - UseEnums\RecipientType
to make it easier). Phone number supported format1(212)555-2368
. NOTE: Sending a message to phone numbers requires thepages_messaging_phone_number
permission. Refer docs for more information.text('')
: (string) Notification message.isResponse()
: Setmessaging_type
asRESPONSE
.isUpdate()
: (default) Setmessaging_type
asUPDATE
.isMessageTag($messageTag)
: (string) Setmessaging_type
asMESSAGE_TAG
, you can refer and make use of theNotificationChannels\Facebook\Enums\MessageTag
to make it easier to work with the message tag.attach($attachment_type, $url)
: (AttachmentType, string) An attachment type (IMAGE, AUDIO, VIDEO, FILE) and the url of this attachmentbuttons($buttons = [])
: (array) An array of "Call to Action" buttons (Created usingNotificationChannels\Facebook\Components\Button::create()
). You can add up to 3 buttons of one of the following types:web_url
,postback
orphone_number
. See Button methods below for more details.cards($cards = [])
: (array) An array of item cards to be displayed in a carousel (Created usingNotificationChannels\Facebook\Components\Card::create()
). You can add up to 10 cards. See Card methods below for more details.notificationType('')
: (string) Push Notification type:REGULAR
will emit a sound/vibration and a phone notification;SILENT_PUSH
will just emit a phone notification,NO_PUSH
will not emit either. You can make use ofNotificationType::REGULAR
,NotificationType::SILENT_PUSH
andNotificationType::NO_PUSH
to make it easier to work with the type. This is an optional method, defaults toREGULAR
type.imageAspectRatio('')
: (string) Image Aspect Ratio if Card withimage_url
present. You can use ofImageAspectRatioType::SQUARE
orImageAspectRatioType::HORIZONTAL
. This is an optional method, defaults toImageAspectRatioType::HORIZONTAL
aspect ratio (image should be 1.91:1).isTypeRegular()
: Helper method to create a notification type:REGULAR
.isTypeSilentPush()
: Helper method to create a notification type:SILENT_PUSH
.isTypeNoPush()
: Helper method to create a notification type:NO_PUSH
.
title('')
: (string) Button Title.data('')
: (string) Button Data - It can be a web url, postback data or a formated phone number.type('')
: (string) Button Type -web_url
,postback
orphone_number
. UseButtonType
enumerator for guaranteeing valid valuesisTypeWebUrl()
: Helper method to create aweb_url
type button.isTypePhoneNumber()
: Helper method to create aphone_number
type button.isTypePostback()
: Helper method to create apostback
type button.
title('')
: (string) Card Title.subtitle('')
: (string) Card Subtitle.url('')
: (string) Card Item Url.image('')
: (string) Card Image Url. Image ratio should be 1.91:1buttons($buttons = [])
: (array) An array of "Call to Action" buttons (Created usingNotificationChannels\Facebook\Components\Button::create()
). You can add up to 3 buttons of one of the following types:web_url
,postback
orphone_number
. See Button methods above for more details.
Please see CONTRIBUTING for details.
The MIT License (MIT). Please see License File for more information.