README

PHP SDK for SDKWA WhatsApp HTTP API

Installation

Install the package via Composer:

composer require sdkwa/whatsapp-api-client-php

📚 New to this library? Check out the Getting Started Guide for a step-by-step tutorial including authorization setup!

Quick Start

Step 1: Initialize Client

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

use SDKWA\WhatsAppApiClient;

$client = new WhatsAppApiClient([
    'apiHost' => 'https://api.sdkwa.pro', // optional
    'idInstance' => 'YOUR_INSTANCE_ID',
    'apiTokenInstance' => 'YOUR_API_TOKEN'
]);

Step 2: Authorize (Scan QR Code)

⚠️ IMPORTANT: Before you can send or receive messages, you must authorize your instance by scanning the QR code.

// Get QR code for WhatsApp authorization
$qr = $client->getQr('whatsapp');

echo "Scan this QR code with WhatsApp:\n";
echo $qr['message']; // Display QR code or URL

// Check authorization status
$state = $client->getStateInstance('whatsapp');
echo "State: " . $state['stateInstance']; // Should be 'authorized' after scanning

For Telegram authorization, use phone number confirmation:

// Send confirmation code to phone
$client->sendConfirmationCode(712345678989, 'telegram');

// After receiving code, sign in
$client->signInWithConfirmationCode('YOUR_CODE', 'telegram');

Step 3: Send Messages

Once authorized, you can send and receive messages:

// Send a WhatsApp message
$response = $client->sendMessage([
    'chatId' => '79999999999@c.us',
    'message' => 'Hello, World!'
], 'whatsapp');

// Send a Telegram message
$response = $client->sendMessage([
    'chatId' => '@username',
    'message' => 'Hello from Telegram!'
], 'telegram');

echo "Message sent with ID: " . $response['idMessage'];

Features

✅ Multi-Messenger Support: WhatsApp and Telegram
✅ Send text messages
✅ Send files (by upload or URL)
✅ Send contacts and locations
✅ Manage groups
✅ Handle webhooks
✅ Account management
✅ QR code authorization
✅ Instance management
✅ Telegram app creation
✅ Full API coverage

Documentation

⚠️ Important: Before you can send or receive messages, you must authorize your instance by:

WhatsApp: Scanning the QR code with your WhatsApp mobile app

Telegram: Confirming your phone number with a verification code

See the Authorization section below for details.

Basic Usage

Initialize Client

use SDKWA\WhatsAppApiClient;

$client = new WhatsAppApiClient([
    'apiHost' => 'https://api.sdkwa.pro', // optional, defaults to https://api.sdkwa.pro
    'idInstance' => 'YOUR_INSTANCE_ID',
    'apiTokenInstance' => 'YOUR_API_TOKEN',
    'userId' => 'YOUR_USER_ID', // optional, required for instance management
    'userToken' => 'YOUR_USER_TOKEN' // optional, required for instance management
]);

Note: The messengerType parameter is passed with each API method call, not during initialization. This allows you to use the same client instance for both WhatsApp and Telegram.

Authorization (Required First!)

Before sending or receiving any messages, you must authorize your instance:

WhatsApp Authorization (QR Code)

// Step 1: Get QR code
$qr = $client->getQr('whatsapp');

// Display the QR code (can be shown as image or text)
echo "QR Code: " . $qr['message'] . "\n";

// Step 2: Check if authorized
$state = $client->getStateInstance('whatsapp');

if ($state['stateInstance'] === 'authorized') {
    echo "WhatsApp is authorized and ready!";
} else {
    echo "Please scan the QR code with WhatsApp";
}

Telegram Authorization (Phone Number)

// Step 1: Send confirmation code to your phone
$response = $client->sendConfirmationCode(712345678989, 'telegram'); // Phone without +

// Step 2: Enter the code you received
$result = $client->signInWithConfirmationCode('12345', 'telegram');

// Step 3: Verify authorization
$state = $client->getStateInstance('telegram');
echo "Telegram state: " . $state['stateInstance'];

Send Messages

// Send WhatsApp text message
$response = $client->sendMessage([
    'chatId' => '79999999999@c.us',
    'message' => 'Hello, World!',
    'quotedMessageId' => 'optional_quoted_message_id'
], 'whatsapp');

// Send Telegram text message
$response = $client->sendMessage([
    'chatId' => '@username',
    'message' => 'Hello from Telegram!'
], 'telegram');

// Send file by upload (WhatsApp)
$response = $client->sendFileByUpload([
    'chatId' => '79999999999@c.us',
    'file' => '/path/to/file.jpg',
    'fileName' => 'image.jpg',
    'caption' => 'Check out this image!'
], 'whatsapp');

// Send file by URL (Telegram)
$response = $client->sendFileByUrl([
    'chatId' => '@username',
    'urlFile' => 'https://example.com/file.pdf',
    'fileName' => 'document.pdf',
    'caption' => 'Important document'
], 'telegram');

// Send contact (WhatsApp - default)
$response = $client->sendContact([
    'chatId' => '79999999999@c.us',
    'contact' => [
        'phoneContact' => 79999999999,
        'firstName' => 'John',
        'lastName' => 'Doe'
    ]
]);  // Default messenger type is 'whatsapp' if not specified

// Send location
$response = $client->sendLocation([
    'chatId' => '79999999999@c.us',
    'latitude' => 51.5074,
    'longitude' => -0.1278,
    'nameLocation' => 'London',
    'address' => 'London, UK'
], 'whatsapp');

Account Management

// Check account authorization status
$state = $client->getStateInstance('whatsapp');
echo "Status: " . $state['stateInstance']; // 'notAuthorized', 'authorized', 'blocked', etc.

// Get account settings (defaults to 'whatsapp')
$settings = $client->getSettings();

// Set account settings for Telegram
$client->setSettings([
    'webhookUrl' => 'https://yourserver.com/webhook',
    'outgoingWebhook' => 'yes'
], 'telegram');

// Reboot WhatsApp account
$client->reboot('whatsapp');

// Logout Telegram account
$client->logout('telegram');

Group Management

// Create WhatsApp group
$response = $client->createGroup('My Group', [
    '79999999999@c.us',
    '79999999998@c.us'
], 'whatsapp');

// Get Telegram group data
$groupData = $client->getGroupData('@groupname', 'telegram');

// Add participant (defaults to whatsapp)
$client->addGroupParticipant('GROUP_ID@g.us', '79999999997@c.us');

// Remove participant from Telegram group
$client->removeGroupParticipant('@groupname', '@username', 'telegram');

// Set group admin
$client->setGroupAdmin('GROUP_ID@g.us', '79999999999@c.us', 'whatsapp');

// Update group name
$client->updateGroupName('GROUP_ID@g.us', 'New Group Name', 'whatsapp');

// Leave group
$client->leaveGroup('GROUP_ID@g.us', 'whatsapp');

Webhook Handling

// Handle incoming webhook
$webhookHandler = $client->getWebhookHandler();

// Set up webhook handlers
$webhookHandler->onIncomingMessageText(function($data) {
    echo "Received text message: " . $data['messageData']['textMessageData']['textMessage'];
});

$webhookHandler->onIncomingMessageFile(function($data) {
    echo "Received file: " . $data['messageData']['fileMessageData']['downloadUrl'];
});

$webhookHandler->onOutgoingMessageStatus(function($data) {
    echo "Message status: " . $data['statusMessage'];
});

// Process webhook (call this in your webhook endpoint)
$webhookHandler->processWebhook($_POST);

Instance Management

// Get all instances (requires userId and userToken)
$instances = $client->getInstances();

// Create new instance
$response = $client->createInstance('DEVELOPER', 'infinitely');

// Extend instance
$response = $client->extendInstance(123, 'DEVELOPER', 'month1');

// Delete instance
$response = $client->deleteInstance(123);

Receiving Messages

// Receive WhatsApp notification
$notification = $client->receiveNotification('whatsapp');

// Receive Telegram notification
$notification = $client->receiveNotification('telegram');

// Delete processed notification (defaults to whatsapp)
$client->deleteNotification($notification['receiptId']);

// Get chat history from Telegram
$history = $client->getChatHistory([
    'chatId' => '@username',
    'count' => 50
], 'telegram');

Telegram Support

The library fully supports Telegram API integration. Simply pass 'telegram' as the $messengerType parameter to any API method.

Telegram Authorization (Required First)

Before using Telegram, you must authorize with your phone number:

// Step 1: Send confirmation code to your phone
$response = $client->sendConfirmationCode(712345678989, 'telegram'); // Without +
echo "Code sent! Check your Telegram app.";

// Step 2: Sign in with the code you received
$result = $client->signInWithConfirmationCode('12345', 'telegram');
echo "Authorized successfully!";

// Step 3: Verify you're authorized
$state = $client->getStateInstance('telegram');
if ($state['stateInstance'] === 'authorized') {
    echo "Ready to send messages!";
}

Telegram-Specific Methods

// Create Telegram app (optional)
$app = $client->createApp(
    'My App',                    // title
    'myapp',                     // short name
    'https://myapp.com',         // URL
    'App description',           // description
    'telegram'                   // messenger type
);

// Send message via Telegram
$message = $client->sendMessage([
    'chatId' => '@username',  // Telegram username or chat ID
    'message' => 'Hello from Telegram!'
], 'telegram');

Working with Both Messengers

// Same client instance can be used for both messengers
$client = new WhatsAppApiClient([
    'idInstance' => 'YOUR_INSTANCE_ID',
    'apiTokenInstance' => 'YOUR_API_TOKEN'
]);

// Send to WhatsApp
$client->sendMessage([
    'chatId' => '79999999999@c.us',
    'message' => 'Hello WhatsApp!'
], 'whatsapp');

// Send to Telegram
$client->sendMessage([
    'chatId' => '@username',
    'message' => 'Hello Telegram! 🚀'
], 'telegram');

// Send file to Telegram
$client->sendFileByUrl([
    'chatId' => '@username',
    'urlFile' => 'https://example.com/file.pdf',
    'fileName' => 'document.pdf',
    'caption' => 'Check this out!'
], 'telegram');

Examples

See the examples/ directory for complete working examples:

WhatsApp Examples:

Telegram Examples:

Error Handling

The client throws exceptions for HTTP errors and invalid responses:

use SDKWA\Exceptions\WhatsAppApiException;

try {
    // Send message (defaults to 'whatsapp' if not specified)
    $response = $client->sendMessage([
        'chatId' => '79999999999@c.us',
        'message' => 'Hello!'
    ], 'whatsapp');
    
    // Or send to Telegram
    $response = $client->sendMessage([
        'chatId' => '@username',
        'message' => 'Hello!'
    ], 'telegram');
} catch (WhatsAppApiException $e) {
    echo "API Error: " . $e->getMessage();
    echo "Status Code: " . $e->getStatusCode();
} catch (Exception $e) {
    echo "General Error: " . $e->getMessage();
}

Requirements

PHP 7.4 or higher
ext-json
ext-curl
Guzzle HTTP client

License

MIT License. See LICENSE file for details.

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

sdkwa / whatsapp-api-client-php

Maintainers

Details