Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/netflie/whatsapp-cloud-api

The first PHP API to send and receive messages using a cloud-hosted version of the WhatsApp Business Platform
https://github.com/netflie/whatsapp-cloud-api

php sdk whatsapp whatsapp-api whatsapp-business-api whatsapp-cloud-api whatsappcloudapi

Last synced: about 1 hour ago
JSON representation

The first PHP API to send and receive messages using a cloud-hosted version of the WhatsApp Business Platform

Awesome Lists containing this project

README 

        
![](https://netflie.es/wp-content/uploads/2022/05/whatsapp_cloud_api_banner-1.png)



## What It Does

This package makes it easy for developers to access [WhatsApp Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api "WhatsApp Cloud API") service in their PHP code.



The first **1,000 conversations** each month are free from WhatsApp Cloud API. A conversation.



## Getting Started

Please create and configure your Facebook WhatsApp application following the ["Get Stared"](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started) section of the official guide.



Minimum requirements – To run the SDK, your system will require **PHP >= 7.4** with a recent version of **CURL >=7.19.4** compiled with OpenSSL and zlib.



## Installation

```composer require netflie/whatsapp-cloud-api ```



## Quick Examples



### Send a text message

```php

 'your-configured-from-phone-number-id',

    'access_token' => 'your-facebook-whatsapp-application-token',

]);



$whatsapp_cloud_api->sendTextMessage('34676104574', 'Hey there! I\'m using WhatsApp Cloud API. Visit https://www.netflie.es');

```



### Send a document

You can send documents in two ways: by uploading a file to the WhatsApp Cloud servers (where you will receive an identifier) or from a link to a document published on internet.



```php

sendDocument('34676104574', $media_id, $document_name, $document_caption);



// Or

$document_link = 'https://netflie.es/wp-content/uploads/2022/05/image.png';

$link_id = new LinkID($document_link);

$whatsapp_cloud_api->sendDocument('34676104574', $link_id, $document_name, $document_caption);

```



### Send a template message

```php

sendTemplate('34676104574', 'hello_world', 'en_US'); // If not specified, Language will be default to en_US and otherwise it will be required.

```



You also can build templates with parameters:



```php

 'text',

        'text' => '*Mr Jones*',

    ],

];



$component_buttons = [

    [

        'type' => 'button',

        'sub_type' => 'quick_reply',

        'index' => 0,

        'parameters' => [

            [

                'type' => 'text',

                'text' => 'Yes',

            ]

        ]

    ],

    [

        'type' => 'button',

        'sub_type' => 'quick_reply',

        'index' => 1,

        'parameters' => [

            [

                'type' => 'text',

                'text' => 'No',

            ]

        ]

    ]

];



$components = new Component($component_header, $component_body, $component_buttons);

$whatsapp_cloud_api->sendTemplate('34676104574', 'sample_issue_resolution', 'en_US', $components); // Language is optional

```



### Send an audio message

```php

sendAudio('34676104574', $link_id);

```



### Send an image message

```php

sendImage('', $link_id);



//or



$media_id = new MediaObjectID('');

$whatsapp_cloud_api->sendImage('', $media_id);

```



### Send a video message

```php

sendVideo('', $link_id, '');



//or



$media_id = new MediaObjectID('');

$whatsapp_cloud_api->sendVideo('', $media_id, '');

```



### Send a sticker message



Stickers sample: https://github.com/WhatsApp/stickers



```php

sendSticker('', $link_id);



//or



$media_id = new MediaObjectID('');

$whatsapp_cloud_api->sendSticker('', $media_id);

```



### Send a location message



```php

sendLocation('', $longitude, $latitude, $name, $address);

```



### Send a location request message



```php

sendLocationRequest('', $body);

```



### Send a contact message



```php

sendContact('', $name, $phone);

```



### Send a list message



```php

sendList(

    '',

    'Rate your experience',

    'Please consider rating your shopping experience in our website',

    'Thanks for your time',

    $action

);

```



### Send a CTA URL message



```php

sendCtaUrl(

    '',

    'See Dates',

    'https://www.example.com',

    $header,

    'Tap the button below to see available dates.',

    'Dates subject to change.',

);

```



### Send Catalog Message



```php

'; // product sku id to use as header thumbnail



$whatsapp_cloud_api->sendCatalog(

    '',

    $body,

    $footer, // optional

    $sku_thumbnail // optional

);

```



### Send a button reply message



```php

 'your-configured-from-phone-number-id',

  'access_token' => 'your-facebook-whatsapp-application-token' 

]);



$rows = [

    new Button('button-1', 'Yes'),

    new Button('button-2', 'No'),

    new Button('button-3', 'Not Now'),

];

$action = new ButtonAction($rows);



$whatsapp_cloud_api->sendButton(

    '',

    'Would you like to rate us on Trustpilot?',

    $action,

    'RATE US', // Optional: Specify a header (type "text")

    'Please choose an option' // Optional: Specify a footer 

);

```



### Send Multi Product Message

```php

'),

    new Row(''),

    // etc

];



$rows_section_2 = [

    new Row(''),

    new Row(''),

    new Row(''),

    // etc

];



$sections = [

    new Section('Section 1', $rows_section_1),

    new Section('Section 2', $rows_section_2),

];



$action = new Action($sections);

$catalog_id = '';

$header = 'Grocery Collections';

$body = 'Hello! Thanks for your interest. Here\'s what we can offer you under our grocery collection. Thank you for shopping with us.';

$footer = 'Subject to T&C';



$whatsapp_cloud_api->sendMultiProduct(

    '',

    $catalog_id,

    $action,

    $header,

    $body,

    $footer // optional

);

```



### Send Single Product Message

```php

';

$sku_id = '';

$body = 'Hello! Here\'s your requested product. Thanks for shopping with us.';

$footer = 'Subject to T&C';



$whatsapp_cloud_api->sendSingleProduct(

    '',

    $catalog_id,

    $sku_id,

    $body, // body: optional

    $footer // footer: optional

);

```



### Replying messages



You can reply a previous sent message:



```php

replyTo('')

    ->sendTextMessage(

        '34676104574',

        'Hey there! I\'m using WhatsApp Cloud API. Visit https://www.netflie.es'

    );

```



### React to a Message



You can react to a message from your conversations if you know the messageid



```php

sendReaction(

        '',

        '',

        '👍', // the emoji

    );



// Unreact to a message

$whatsapp_cloud_api->sendReaction(

        '',

        ''

    );



```



## Media messages

### Upload media resources

Media messages accept as identifiers an Internet URL pointing to a public resource (image, video, audio, etc.). When you try to send a media message from a URL you must instantiate the `LinkID` object.



You can also upload your media resources to WhatsApp servers and you will receive a resource identifier:



```php

$response = $whatsapp_cloud_api->uploadMedia('my-image.png');



$media_id = new MediaObjectID($response->decodedBody()['id']);

$whatsapp_cloud_api->sendImage('', $media_id);



```



### Download media resources

To download a media resource:



```php

$response = $whatsapp_cloud_api->downloadMedia('');

```



## Message Response

WhatsAppCloudApi instance returns a Response class or a ResponseException if WhatsApp servers return an error.



```php

try {

    $response = $this->whatsapp_app_cloud_api->sendTextMessage(

        ',

        'Hey there! I\'m using WhatsApp Cloud API. Visit https://www.netflie.es',

        true

    );

} catch (\Netflie\WhatsAppCloudApi\Response\ResponseException $e) {

    print_r($e->response()); // You can still check the Response returned from Meta servers

}

```



## Webhooks



### Webhook verification

Add your webhook in your Meta App dashboard. You need to verify your webhook:



```php

verify($_GET, "");

```



### Webhook notifications

Webhook is now verified, you will start receiving notifications every time your customers send messages.



```php

read(json_decode($payload, true)), true) . "\n");



//Read all messages in case Meta decided to batch them

fwrite(STDOUT, print_r($webhook->readAll(json_decode($payload, true)), true) . "\n");

```



The `Webhook::read` function will return a `Notification` instance. Please, [explore](https://github.com/netflie/whatsapp-cloud-api/tree/main/src/WebHook/Notification "explore") the different notifications availables.



### Mark a message as read

When you receive an incoming message from Webhooks, you can mark the message as read by changing its status to read. Messages marked as read display two blue check marks alongside their timestamp.



Marking a message as read will also mark earlier messages in the conversation as read.



```php

markMessageAsRead('');

```



### Get Business Profile

```php

businessProfile('');

```



### Update Business Profile

```php

updateBusinessProfile([

    'about' => '',

    'email' => ''

]);

```



Fields list: https://developers.facebook.com/docs/whatsapp/cloud-api/reference/business-profiles



## Features



- Send Text Messages

- Send Documents

- Send Templates with parameters

- Send Audios

- Send Images

- Send Videos

- Send Stickers

- Send Locations

- Send Location Request

- Send Contacts

- Send Lists

- Send Buttons

- Send Multi Product Message

- Send Single Product

- Upload media resources to WhatsApp servers

- Download media resources from WhatsApp servers

- Mark messages as read

- React to a Message

- Get/Update Business Profile

- Webhook verification

- Webhook notifications



## Getting Help

- Ask a question on the [Discussions forum](https://github.com/netflie/whatsapp-cloud-api/discussions "Discussions forum")

- To report bugs, please [open an issue](https://github.com/netflie/whatsapp-cloud-api/issues/new/choose "open an issue")



## Migration to v2



Please see [UPGRADE](https://github.com/netflie/whatsapp-cloud-api/blob/main/UPGRADE.md "UPGRADE") for more information on how to upgrade to v2.



## Changelog



Please see [CHANGELOG](https://github.com/netflie/whatsapp-cloud-api/blob/main/CHANGELOG.md "CHANGELOG") for more information what has changed recently.



## Testing

```php

composer unit-test

```

You also can run tests making real calls to the WhastApp Clou API. Please put your testing credentials on **WhatsAppCloudApiTestConfiguration** file.

```php

composer integration-test

```

## Contributing



Please see [CONTRIBUTING](https://github.com/netflie/.github/blob/master/CONTRIBUTING.md "CONTRIBUTING") for details.



## License



The MIT License (MIT). Please see License File for more information. Please see [License file](https://github.com/netflie/whatsapp-cloud-api/blob/main/LICENSE "License file") for more information.



## Disclaimer



This package is not officially maintained by Facebook. WhatsApp and Facebook trademarks and logos are the property of Meta Platforms, Inc.