README

This Laravel package's goal is to abstract and simplify the integration with the Facebook's Whatsapp Business API through services, facades and methods, as well properly documenting how to work with it, since it is sometimes hard to find the info you need to correctly implement the API.

Check our package on Packagist.

Project Meta Data

Project Status (beta branch)

Table of Contents

• Composer Scripts
• Configure Whatsapp Webhook
• Using the Package
  • Migrations
    • whatsapp_messages Table
    • Messageable Migration
  • General Concepts
    • Whatsapp API Entities
  • Meta Webhook Validation
  • Receiving Messages
• Run and Test
• Tooling
  • Comitzen
  • Sample App
  • Pinggy
  • How to use Pinggy
• Contributors
• Changelog
• Roadmap

Composer Scripts

We tried to automate as much boring tasks and CLI commands as we could on short composer scripts. Below you will find a general description of what each one does:

• composer commit: Runs the comitzen binary which opens an interactive CLI to keep commits in a standard that our pipeline can use to generate the package changelog automatically.
• composer coverage: Run the tests and generates code coverage. If you are contributing, please make sure you do not lower the current coverage. ;)
• composer start: Serves the sample application (through php artisan serve) with the package already loaded. It will run the Sample App on port 8000.
• composer connect: Connects to Pinggy service and expose your local environment to the web. It assumes that the local app is running on port 8000.
• composer test: Run the tests (do not generate coverage report)

Configure Whatsapp Webhook

[WIP]

Using the Package

After installing, if the auto discovery did not pick it up right away, just add those 2 lines in your bootstrap/providers.php file:

return [
  // [...]
  The42dx\Whatsapp\RouteServiceProvider::class,
  The42dx\Whatsapp\WhatsappServiceProvider::class,
];

After making sure the Service Providers are loaded, you will need to adjust the package configs according to your Facebook/Meta application, and run the migrations to create tables and columns the package needs.

Publish the configuration file and adjust it to suit your needs:

php artisan vendor:publish --tag=whatsapp-business-api-config

Migrations

The package will create a whatsapp_messages table to store the messages (both inbound and outbound) handled by the package. It will also create a unique phone column on your messageable entity (usually, and by default on the users table). If you need to customize this, adjust the database.* keys in your /config/whatsapp.php file before running the migrations.

To keep everything nice and tidy in your project, it is recommended (but not necessary) to publish the default migrations. You can do so by running the following command:

php artisan vendor:publish --tag=whatsapp-business-api-migrations

whatsapp_messages Table

[WIP]

$Messageable Migration

[WIP]

General Concepts

[WIP]

Whatsapp API Entities

[WIP]

Meta Webhook Validation

[WIP]

Receiving Messages

[WIP]

Sending Messages

[WIP]

General DB Columns

[WIP]

Message-Type Specific columns

[WIP]

Run and Test

We included a sample fresh Laravel app to help those who want to contribute to the package. To start it just go through the following steps:

1. Clone this repository.
2. Run composer setup from the repository root. It will cd on sample app's folder, install the dependencies and cd back to the root folder.
3. Run composer start from the repository root. It will run the sample app through artisan serve command.
4. With the local server running, from another terminal run composer connect from the repository. It will connect to pinggy service and expose your local application to the web.
5. Adjust your webhook configuration on the Meta/Facebook dashboard with the generated pinggy URI.

Tooling

There are a few tools we provide alongside with the source code to ease a little bit the burden of following a bunch of patterns and standards we set up, as well as automate some boring processes.

Comitizen

This CLI helps with writting commit messages in a meaningful and standardized way, so that our automation process can use them to properly write our software changelog.

If you like the tool, kudo the devs ;)

How to use Comitzen

Just run composer commit from the repository's root folder instead of the traditional git commit and follow the CLI interactive steps :)

Sample App

For those who want to test and/or contribute to this package, we included a sample fresh laravel application with the package already locally loaded, so you can emulate a real Laravel application that uses the package :)

How to run the Sample App

Just run composer serve from the repository's root folder. The script will cd into the sample folder and run the Laravel artisan command php artisan serve from there.

Pinggy

This service allows routing external requests to your local environment. You can use it to test your Watsapp webooks locally while developing.

If you like the tool, kudos the devs ;)

How to use Pinggy

Just run composer connect from the repository's root folder. You will need to have our sample application running so you can receive webhook requests locally.

Contributors

Kudos to all our dear contributors. Without them, nothing would have been possible ❤️

Rafael Eduardo Paulin 💻 🎨 📖 🤔 🚇 🚧 📆 👀 ⚠️ 🔧 ✅

Would you like to see your profile here? Take a look on our Code of Conduct and our Contributing docs, and start coding! We would be thrilled to review a PR of yours! 💯

back to top

Changelog

All changes made to this package since the start of development can be found either on our release list or on the changelog.

back to top

Roadmap

Any planned enhancement to the package will be described and tracked in our project page

back to top