Download the PHP package chengkangzai/laravel-waha-saloon-sdk without Composer

Laravel WAHA Saloon SDK

A comprehensive Laravel package that provides a PHP SDK for the WAHA (WhatsApp HTTP API) service. This SDK is auto-generated from the WAHA Postman collection and wrapped with SaloonPHP for elegant HTTP client functionality.

What is WAHA?

WAHA (WhatsApp HTTP API) is a service that provides HTTP RESTful API access to WhatsApp. It allows you to:

• Send and receive WhatsApp messages programmatically
• Manage WhatsApp sessions and authentication
• Handle contacts, groups, and channels
• Implement WhatsApp business features in your application

This SDK makes it easy to integrate WAHA with your Laravel application, providing a fluent, type-safe interface to all WAHA API endpoints.

Features

• 🚀 Auto-generated from WAHA Postman collection
• 🔌 Elegant HTTP client powered by SaloonPHP
• 📦 Laravel integration with service provider and facade
• 🛠️ Comprehensive API coverage with 23 resources and 134 request types
• 🔐 Built-in API key authentication support
• 🧪 Built with testing in mind using Pest PHP
• 🎯 Type-safe request and response handling
• 📋 Support for Laravel 10.x, 11.x, and 12.x

Installation

You can install the package via composer:

You can publish the config file with:

This is the contents of the published config file:

Configuration

Set your WAHA instance URL and API key in your .env file:

The API key is optional but required for most WAHA endpoints (approximately 50% of endpoints require authentication). If not provided, requests will be sent without authentication headers.

Multiple WAHA Hosts

The SDK supports connecting to multiple WAHA instances. This is useful when you have separate WAHA servers for different purposes (production, staging, different WhatsApp accounts, etc.).

Configuring Multiple Hosts

Update your config/waha-saloon-sdk.php to define multiple connections:

Using the Waha Facade (Recommended)

Using Dependency Injection

Direct Instantiation

Direct instantiation still works and ignores the configuration:

Usage

Quick Start Example

Here's a complete example showing how to send your first WhatsApp message:

Basic Usage Patterns

Working with Sessions

Sessions are the foundation of WhatsApp communication. Each session represents a WhatsApp connection.

Sending Messages

The SDK provides specialized resources for different message types. Here are comprehensive examples:

Working with Chats

Chats represent conversations with individuals or groups. Here's how to manage them:

Working with Contacts

Manage your WhatsApp contacts and verify phone numbers:

Working with Groups

Manage WhatsApp groups and their participants:

Advanced Message Operations

Advanced Features

Error Handling and Best Practices

Available Resources

The SDK provides access to all WAHA API endpoints through these resources:

• Admin ($waha->admin()) - Admin operations (promote/demote participants)
• Api ($waha->api()) - Basic API operations (archive/unarchive chats)
• Auth ($waha->auth()) - Authentication and QR codes
• Channels ($waha->channels()) - Channel management
• Chats ($waha->chats()) - Limited chat operations (get messages, clear, mark read)
• Contacts ($waha->contacts()) - Contact management
• Groups ($waha->groups()) - Group information and settings
• InfoAdminOnly ($waha->infoAdminOnly()) - Admin-only group settings
• InviteCode ($waha->inviteCode()) - Group invitation codes
• Labels ($waha->labels()) - Label management
• Lids ($waha->lids()) - LID (LinkedIn ID) management
• Messages ($waha->messages()) - Message operations (delete, edit, pin)
• MessagesAdminOnly ($waha->messagesAdminOnly()) - Admin-only message settings
• Misc ($waha->misc()) - Main resource with most functionality (send files, media, groups, sessions, health checks, etc.)
• Overview ($waha->overview()) - Chat overview and summaries
• Participants ($waha->participants()) - Group participant management
• Picture ($waha->picture()) - Profile and group picture management
• Presence ($waha->presence()) - Online/offline status
• Profile ($waha->profile()) - Profile management
• Search ($waha->search()) - Channel search functionality
• Send ($waha->sending()) - Advanced sending (link previews, button replies)
• SendText ($waha->sendText()) - Text message sending
• Server ($waha->server()) - Server information and control
• Sessions ($waha->sessions()) - Session management
• Status ($waha->status()) - WhatsApp status updates

Note: Most of the core functionality (sending media, files, managing groups, health checks, etc.) is in the misc() resource.

Understanding WhatsApp IDs and Important Notes

WhatsApp uses specific ID formats:

• Individual chats: [email protected] (phone number + @c.us)
• Group chats: [email protected] (group ID + @g.us)
• Channels: 1234567890@newsletter (channel ID + @newsletter)

Phone numbers should include country code without '+' symbol.

SDK Structure Notes

Important: This SDK is auto-generated from a Postman collection, which results in some unique characteristics:

1. Very descriptive method names: Methods have extremely long, descriptive names that match the API functionality exactly (e.g., getChatsOverviewIncludesAllNecessaryThingsToBuildUiYourChatsOverviewPageChatIdNamePictureLastMessageSortingByLastMessageTimestamp)

2. Most functionality is in misc() resource: Unlike typical SDKs where functionality is spread across logical resources, most operations (sending files, media, groups, health checks) are located in the misc() resource.

3. Parameter order: Pay close attention to parameter order in method calls, as it may not always be intuitive.

4. Auto-generated code: The SDK is regenerated from the Postman collection, so method signatures are exactly as defined in the WAHA API.

For the most up-to-date method signatures and parameters, always refer to the actual class files in src/Waha/Resource/ or use your IDE's autocomplete functionality.

Upgrading

From v0.2.x to v0.3.0

Breaking Change: The auth() method has been renamed to qr().

The QR code methods have been moved from the Auth namespace to Qr namespace to better align with the WAHA API structure.

Update your code:

Search and replace in your codebase:

• Replace ->auth()->getQrCode with ->qr()->getQrCode
• Replace Waha::auth() with Waha::qr()

From v0.0.x to v0.1.0

Step 1: Update the package

Step 2: Publish the new config (optional but recommended)

Step 3: Clear config cache

No code changes required - your existing code will continue to work without modifications.

Optional: You can migrate to the new Waha facade for cleaner syntax:

Note: The LaravelWahaSaloonSdk facade is deprecated in favor of the new Waha facade.

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Development

Regenerating the SDK

The SDK is auto-generated from the WAHA Postman collection. To regenerate:

Code Quality

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• CCK
• All Contributors

License

The MIT License (MIT). Please see License File for more information.