alresia/laravel-wassenger

WhatsApp Business Api for Larave Using Wassenger Api

1.2.1 2022-11-19 06:29 UTC

Requires

• php: >=5.6.0
• ext-curl: *

MIT

• Fidelis E Peter

• whatsapp
• Wassenger
• LaravelWassenger
• WhatsAppApi
• WhatsAppBusness

README

WhatsApp Business Api for Larave Using Wassenger Api

For more info about Wassenger follow https://www.wassenger.com.

INTRODUCTION

This API documentation provides detailed information about the LARAVEL WASSENGER and WASSENGER endpoints request/response API contracts.

You can easily connect, send request and recieve response on most usable and important endpoint in wassenger using php.

This Package has been built with expection to help ease the time connecting and intergrating WhatsApp on our Application.

With the help of Wassenger Api and it well structured to work on Laravel framework.

IF You like this package please consider supporting by adding a star and introduce this to your friends

INSTALLATION & SETUP

On Composer

Laravel Wassenger is available on Packagist (using semantic versioning), and installation via Composer is the recommended way to install this Package. Just add this line to your composer.json file:

"alresia/laravel-wassenger": "^1.2.0"

or run

composer require alresia/laravel-wassenger

From Laravel Controller

<?php

namespace App\Http\Controllers;

use Alresia\LaravelWassenger\Messages;

class SampleController extends Controller
{
    public function sendMessage()
    {
        $phone = '[phone]';
        $message = 'Hello world! This is a simple test message';
        Messages::message($phone, $message)->send();

    }

}

Using Composer Directly

using composer directly require composer autoload file

<?php
require_once 'vendor/autoload.php';

use Alresia\LaravelWassenger\Wassenger;

    $phone = '[phone]';
    $message = 'Hello world! This is a simple test message';
    Messages::message($phone, $message)->send();

Using Without Composer

Alternatively, if you're not using Composer or Laravel Application, you can download Laravel-Wassenger as a zip file, then copy the contents of the folder into the directory of your php application and load wassenger-loader.php':

<?php

use Alresia\LaravelWassenger\Messages;

require 'PATH_TO_LARAVEL_WASSENGER/laravel-wassenger/src/wassenger-loader.php';

    $phone = '[phone]';
    $message = 'Hello world! This is a simple test message';
    Messages::message($phone, $message)->send();

CONFIGURATION

Laravel

Laravel Wassenger was made to work out-of-the-box, you can override the configuration by simply publishing the config file in laravel.

php artisan vendor:publish --provider="Alresia\LaravelWassenger\WassengerServiceProvider" --tag="config"

After that, you will receive the config/wassenger.php config file with an array like this:

<?php
return [
    'authorisation' => [
        'api_key' => env('WASSENGER_API_KEY', ''),
        'api_host'   => env('WASSENGER_API_URL', 'https://api.wassenger.com'),
        'api_version' => 1,
        'default_device' => env('DEFAULT_DEVICE', '')
    ],
    'http_client' => [
        'return_json_errors' => false,
    ],
];

Others Application

The Configuration file is Located at laravel-wassenger/src/Config.php

<?php

namespace Alresia\LaravelWassenger;

class Config
{
    public const API_KEY = '';
    public const API_HOST = 'https://api.wassenger.com';
    public const API_VERSION = 1;
    public const DEFAULT_DEVICE = null;

    public const RETURN_JSON_ERRORS = false;

Api Keys

The WASSENGER_API_KEY is Required to use this package

To get Your API KEY go to Wassanger Console and Get a Api Key

if you are using Larevel just head over to your .env file to set your Api key and Default device

WASSENGER_API_KEY=<YOUR_KEY_HERE>
DEFAULT_DEVICE=<DEVICE_ID_HERE>

if you want the application to return a Json response instead of an Error Exception
Change the Return JSON Errors to true from the config file

'http_client' => [
        'return_json_errors' => true,
    ],

 public const RETURN_JSON_ERRORS = true;

This is usefull if you want to manage error responses

USAGE

This deals with four endpoint of Wassenger. Doh it only has the most used and important functions

Class	Description
Wassenger::class*	This is the main class of Laravel Wassenger. It contain most usefull methods controlling the packages
Messages::class*	Send, browse and manage outbound messages
Devices::class *	Manage Conneted Device and See status.
Session::class	Manage WhatsApp session status synchronization.

Classes

Main Wassenger Class

To use include the LaravelWassenger\Wassenger namespace in your file;

use Alresia\LaravelWassenger\Wassenger;

The following available methods are:

Method	Description	Parameters
numberExist() see example	Check if a given phone number exists in WhatsApp and is able to receive messages. The number format must be in E164 format. You can check one number at a time.	@param String $phone *required
sessionSync() see example	Force WhatsApp session status synchronization of a device. Note: if you do not specify an ID, will use default device id from config	@param String|Null $deviceId *optional
syncAll() see example	Force synchronize all device session status. Note: This method uses a loop in getting all devices then synchronize them. It will skip device that is already synchronized or last synchronize in less than 60 seconds. Avoid running this function if you have too many device connected to your account.	@param Null

Examples:

Number Exist

Wassenger::numberExist('[phone]');

Sync device session

Wassenger::sessionSync('63615bb1db0ssb686cee2fa4a');

Wassenger::sync('63615bb1db0ssb686cee2fa4a');

Sync all device session

Wassenger::syncAll();

Messages

To use include the LaravelWassenger\Messages namespace in your file;

use Alresia\LaravelWassenger\Messages;

The following available methods are available for sending messages in this package, which you can See the full details here:

Method	Description	Parameters
message() see example	Use to attached text and user phone number.	phone(string:requires) , message (string:required), enqueue (bool:optional)(default:false)
messageGroup() see example	message a group.	group_id(string:requires) , message (string:required), enqueue (bool:optional)
agent()	Optional Agent ID to send the message on behalf of. The chat will not be assigned to the agent unless explicitly defined via message actions. The agent must have access permissions to the device. You can retrieve the agents ID from Here	agent_id(string:optional)
contacts()	Send one or multiple contact cards to a target phone or group chat. Contact is composed based on an E164 international phone number and contact name. Contact name can have spaces representing a person full name. You can send up to 10 contacts in a single message.	Array ([ 1 .. 10 ] items) * phone string [ 6 .. 16 ] characters - required. * name string [ 1 .. 40 ] characters - required
device()	Device ID to be used for message delivery. If not defined, the first created device will be used by default. You can use this to arbitrary send messages across multiple devices connected to your account. You can get the device ID from the Web Console > Devices	deviceId (string required)
location()	Send location details	Array ([ 1 .. 10 ] items) * address string [ 3 .. 100 ] characters. * name string <= 100 characters characters * coordinates Array of numbers = 2 items [ items [ -180 .. 180 ] ]
expiration()	Define a message time-to-live (ttl) expiration time. Use this if you want to automatically do not send a message if the delivery was not possible after a while. E.g: 1h.	Object * seconds number [ 5 .. 8035200 ] * duration string [ 2 .. 5 ] characters * date string <date-time>
schedule() see example	Schedule a Message.	delay(string required)
deliverAt() see example	Schedule to a given time.	ISO_Date (required)
media() see example	Attach a file.	file_array(arrays) ['file'=>'24 characters length file ID']
buttons() see example	Add action Buttons.	butttons_array() Check documentation
findById() see example	Get a specific message by ID.	string
header()	Experimental: optional message header text, restricted to messages with reply buttons. Important: feature not yet available in Multi-Device enabled WhatsApp sessions. The API will return an error if message type is not supported in your linked WhatsApp number.	string <= 60 characters
footer()	Experimental: optional message footer text, restricted to messages with reply buttons. Important: feature not yet available in Multi-Device enabled WhatsApp sessions. The API will return an error if message type is not supported in your linked WhatsApp number.	string <= 60 characters
raw()	Direct use wassenger Api. if you are not satisfy with laraval-wassenger or you can't find what you want here. you can send request directly using this method Use add desires params Messages::raw($paramsArray)->send();	objects (required)
search() see example	Searching from message list.	arrays (required)
find()	Alternatives for search().	arrays (required)
get()	Get the Specified Resource.	null
delete()	Delete the specific resource.	string null
send()	This method initailizes and connect to the message to Wassenger endpoint.	none

Example Usage

Send text message to a phone number

Messages::message('[phone]', 'Hello world! This is a simple test message')
    ->send();

Send text message with high priority to a group

Messages::messageGroup('[e-mail]', 'Hello world! This is a simple test message', 'high')
    ->send();

Send media message to user. Note the file must be updated first, see API endpoint: Files > Upload file

Messages::messageGroup('[phone]', 'Hello world! This is a test media message.', 'high')
    ->media(['file', '<24 characters length file ID>'])
    ->send();

Send text message that should be delivered now

Messages::message('[phone]', 'Hello world! This is a simple test message', false)
    ->send();

Send a scheduled messages with a custom delay.

See "schedule.delayTo" datetime notation shortcuts: https://i.ibb.co/g3DJLSH/datetime-shortcuts.png

Messages::message('[phone]', 'Hello world! This is a simple test message')
    ->schedule('1h')
    ->send();

Send a scheduled messages at a concrete date with a valid ISO 8601 date

Messages::message('[phone]', 'Hello world! This is a simple test message')
    ->deliverAt('2000-01-01T01:00:00+1200')
    ->send();

If You want to attach action buttons to your message

$buttons = [
    [
         "id" => "id1",
         "kind" => "call",
         "text" => "Call us",
         "value" => "[phone]"
    ],
    [
        "id" => "id2",
        "kind" => "url",
        "text" => "Open me",
        "value" => "https://company.com/shop"\
    ],
    [
        "id" => "id3",
        "text" => "Get help"
    ]
];
Messages::message('[phone]', 'Hello world! This is a simple test message')
    ->buttons($buttons)
    ->send();

Getting a Message

Messages::findById('635889e9133a76fddfdfy65r5')
    ->get();

Updating a Message

Messages::findById('635889e9133a76fddfdfy65r5')
    ->message('[phone]', 'Hello world! This is a simple test message')
    ->update();

Deleting a Message

Messages::findById('635889e9133a76fddfdfy65r5')
    ->delete();

Alternatively you can delete a message passing the message ID inside the delete() mothod with using the findById() method

Messages::delete('635889e9133a76fddfdfy65r5');

Device

To use include the LaravelWassenger\Device namespace in your file;

use Alresia\LaravelWassenger\Device;

The following available methods are:

Method	Description	Parameters
findById() see example	Retrieve device details by ID.	@param String $deviceId *required
search() see example	Search devices by phone number, alias or ID. For multiple value searches use comma-separeted values. E.g: +2348113536471,61b37a069cba0c15d6c81000	@param String $values
status() see example	Search devices by status. E.g: operative, pending, disabled, removed	@param String Default: "any" Enum: "any" "invalid" "banned" "removed" "disabled" "unpaid" "preload" "pending" "authorized" "verified" "operative"
session() see example	Search devices by session status. E.g: authorize, online, timeout, offline, error	@param String Enum: "any" "online" "offline" "timeout" "timeout_sync" "conflict" "blocked" "error" "authorize" "authorizing" "new" "loading" "offline_panel"
limit() see example	Limiting the size of the result and get result by pages. This method helps when working with paginations	@param String $size <integer> [ 0 .. 50 ] Default: 0 @param String $page <integer> [ 1 .. 100 ] Default: 0
get() see example	Get the Specified Resource.	@param [Arrays|Objects

Examples:

Get account devices

Devices::get();

Get device by ID

Devices::findById('63615bb1db0b686cee2fa4af')->get();

Search devices by phone number, alias or IDs

Devices::search('+2348113536471,61b37a069cba0c15d6c81000')->get();

Get only verified devices

Devices::status('verified')->get();

Get only pending devices

Devices::status('pending')->get();

Get device by session online

Devices::session('online')->get();

Get device session

Devices::session('any')->get();

Search devices by phone number, alias or IDs that is verified

Devices::search('+2348113536471,61b37a069cba0c15d6c81000')->status('verified')->get();

Search devices by phone number, alias or IDs that is online

Devices::search('+2348113536471,61b37a069cba0c15d6c81000')->session('online')->get();

Search devices by phone number, alias or IDs that is online

Devices::search('+2348113536471,61b37a069cba0c15d6c81000')->session('online')->get();

Sorting Result

Devices::limit(20, 2)->get(); // size 20 page 2

Devices::search('+2348113536471,61b37a069cba0c15d6c81000')->session('online')->limit(20, 3)->get(); // size 20 page 3

All method can be used after another

Devices::session('any')->status('any')->limit(20, 0)->get(); // get() should always be the last

Also You can select or use all params incase not listed here using the get

Devices::get([
    'search' => '+2348113536471,61b37a069cba0c15d6c81000',
    'status' => 'any',
    'sessionStatus' => 'online',
    'size' => '20',
    'page' => '3',
]); 

Sessions

This function is already exist in other class methods

use Alresia\LaravelWassenger\Session;

Session::sync('63615bb1db0b686cee2fa4af');

see https://app.wassenger.com/docs/#tag/Devices/operation/searchDevices to use this method properly

Contributing

All Contribution are welcome here. feel free to email me Fidelis E Peter.

Also you can drop an issue if you observe any

Thank you for considering contributing to the Laravel Wassenger!

Package

This package doesn't require any extra packages

You can also use these package for None Laravel App

NOTE: Changing host and version either from the Config.php or the wassenger.php is not neccessary unless if you know what you are doing