Requirements

• PHP 7.3+

Installing

Use Composer to install it:

composer require positus/positus-api-php-client

If you use Laravel, we provide a wrapper.

Instantiating

use Positus\Client;

$client = new Client();

Authentication

If you don't have an authentication token, click here to generate one.

$client = new Client();

$client->setToken('you-api-token');

Sending Messages

The first step to be able to send messages is to specify the ID number of origin:

$number = $client->number('your-number-id');

Then send the message and wait for a response.

If you want to test a Sandbox you can pass a second argument when calling the number method as true:

$number = $client->number('sandbox-number-id', true);

If you want to send a message using data on your own, you can use:

$response = $number->sendData([
    'to' => '+5511999999999',
    'type' => 'text',
    'text' => [
        'body' => 'Hi!'
    ]
]);

To check all the data that can be sent in each type of message, check the WhatsApp Business documentation.

If you prefer, we provide ready methods for each type of message.

Text

$response = $number->sendText('+5511999999999', 'Your message');

Template

$response = $number->sendTemplate('+5511999999999', 'namespace', 'name', 'languageCode', [
    "type" => "body",
    "parameters" => [
        [
            "type" => "text",
            "text" => "Param 1"
        ],
        ...
    ]
]);

Please check the documentation related to templates in the WhatsApp Business documentation.

Contacts

$response = $number->sendContacts('+5511999999999', [
    [
        'name' => [
            "formatted_name" => "John Doe"
        ],
        'phones' => [
            'phone' => '+5511888888888',
            'type' => 'CELL'
        ]
    ]
]);

Please check the documentation related to contacts in the WhatsApp Business documentation.

Location

$response = $number->sendLocation('+5511999999999', '-23.553885', '-46.662819', 'Robbu - Atendimento digital inteligente', 'Av. Angélica, 2530 - Bela Vista, São Paulo - SP, 01228-200');

Image

$response = $number->sendImage('+5511999999999', 'https://example.com/image.jpg', 'Random Image');

Document

$response = $number->sendDocument('+5511999999999', 'https://example.com/document.pdf', 'Random Document');

Video

$response = $number->sendVideo('+5511999999999', 'https://example.com/video.mp4', 'Random Video');

Audio

$response = $number->sendAudio('+5511999999999', 'https://example.com/audio.mp3');

Receiving media

To download a media, use the following method:

$response = $number->getMedia('media-id');

Responses

After any call you can check if everything went well and receive the data using the following methods:

if ($response->success()) {
    echo 'Message with Id ' . $response->json()->messages[0]->id . ' sent successfully';
}

If everything goes correctly you will receive an answer like this:

{
    "messages": [
        {
            "id": "gBEGVUOWQWWQAgnFOaNl67sTDIE"
        }
    ],
    "message": "The message was successfully sent"
}

If something goes wrong, you will receive a message detailing the errors:

{
    "errors": [
        {
            "code": 1008,
            "title": "Required parameter is missing",
            "details": "Parameter 'body' is mandatory for type 'text'"
        }
    ],
    "message": "Unfortunately we were not able to send your message"
}

Please check all possible errors that the api may return in the WhatsApp Business documentation.

Feel free to create a pull request or open a support ticket in Positus Studio if you have or find any problems.

You can check if it failed:

if ($response->error()) {
    echo 'Something went wrong';
}

If you only need the status code:

$response->status();

You can get the answer from api as a string:

$response->body();

Or if you prefer as JSON:

$response->json();

Or if you prefer as object:

$response->object();

You can get a header:

$response->header('Content-Type');

Or you can get all headers:

$response->headers();