wdevs/whatshooked
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Whatsapp Business support

Browse Source
This commit is contained in:
Warky
2025-12-29 06:23:16 +02:00
parent 09a12560d3
commit ae169f81e4
14 changed files with 2269 additions and 800 deletions
Download Patch File Download Diff File Expand all files Collapse all files

236
README.md
View File

@@ -1,6 +1,6 @@
# WhatsHooked
A service that connects to WhatsApp via the whatsmeow API and forwards messages to registered webhooks. Enables two-way communication by allowing webhooks to respond with messages to be sent through WhatsApp.
A service that connects to WhatsApp and forwards messages to registered webhooks. Supports both personal WhatsApp accounts (via whatsmeow) and WhatsApp Business API. Enables two-way communication by allowing webhooks to respond with messages to be sent through WhatsApp.
![1.00](./assets/image/whatshooked.jpg)
@@ -12,6 +12,7 @@ A service that connects to WhatsApp via the whatsmeow API and forwards messages
## Phase 1 Features
- **Multi-Account Support**: Connect to multiple WhatsApp accounts simultaneously
- **Dual Client Types**: Support for both personal WhatsApp (whatsmeow) and WhatsApp Business API
- **Webhook Integration**: Register multiple webhooks to receive WhatsApp messages
- **Two-Way Communication**: Webhooks can respond with messages to send back to WhatsApp
- **Instance/Config Level Hooks**: Global hooks that receive all messages from all accounts
@@ -27,7 +28,9 @@ The project uses an event-driven architecture with the following packages:
- **internal/config**: Configuration management and persistence
- **internal/logging**: Structured logging using Go's slog package
- **internal/events**: Event bus for publish/subscribe messaging between components
- **internal/whatsapp**: WhatsApp client management using whatsmeow
- **internal/whatsapp**: WhatsApp client management (supports both whatsmeow and Business API)
- **whatsmeow/**: Personal WhatsApp client implementation
- **businessapi/**: WhatsApp Business API client implementation
- **internal/hooks**: Webhook management and message forwarding
- **cmd/server**: Main server application
- **cmd/cli**: Command-line interface for management
@@ -88,9 +91,23 @@ Edit the configuration file to add your WhatsApp accounts and webhooks:
},
"whatsapp": [
{
"id": "account1",
"id": "personal",
"type": "whatsmeow",
"phone_number": "+1234567890",
"session_path": "./sessions/account1"
"session_path": "./sessions/personal",
"show_qr": true
},
{
"id": "business",
"type": "business-api",
"phone_number": "+9876543210",
"business_api": {
"phone_number_id": "123456789012345",
"access_token": "EAAxxxxxxxxxxxx",
"business_account_id": "987654321098765",
"api_version": "v21.0",
"verify_token": "my-secure-verify-token"
}
}
],
"hooks": [
@@ -122,8 +139,20 @@ Edit the configuration file to add your WhatsApp accounts and webhooks:
**WhatsApp Account Configuration:**
- `id`: Unique identifier for this account
- `type`: Client type - `"whatsmeow"` for personal or `"business-api"` for Business API (defaults to "whatsmeow")
- `phone_number`: Phone number with country code
- `session_path`: Path to store session data
**For whatsmeow (personal) accounts:**
- `session_path`: Path to store session data (default: `./sessions/{id}`)
- `show_qr`: Display QR code in terminal for pairing (default: false)
**For business-api accounts:**
- `business_api`: Business API configuration object
- `phone_number_id`: WhatsApp Business Phone Number ID from Meta
- `access_token`: Access token from Meta Business Manager
- `business_account_id`: Business Account ID (optional)
- `api_version`: Graph API version (default: "v21.0")
- `verify_token`: Token for webhook verification (required for receiving messages)
**Hook Configuration:**
- `id`: Unique identifier for this hook
@@ -187,6 +216,146 @@ Clients can provide the API key using either:
- All `/api/*` endpoints require authentication when enabled
- Both authentication methods can be configured simultaneously - the server will accept either valid credentials or a valid API key
## WhatsApp Business API Setup
WhatsHooked supports the official WhatsApp Business Cloud API alongside personal WhatsApp accounts. This allows you to use official business phone numbers with enhanced features and reliability.
### Prerequisites
1. **Meta Business Account**: Sign up at [Meta Business Suite](https://business.facebook.com/)
2. **WhatsApp Business App**: Create a WhatsApp Business app in the [Meta for Developers](https://developers.facebook.com/) console
3. **Phone Number**: Register a business phone number with WhatsApp Business API
### Getting Your Credentials
1. Go to [Meta for Developers](https://developers.facebook.com/) and select your app
2. Navigate to **WhatsApp** → **API Setup**
3. Obtain the following:
- **Phone Number ID**: Found in the API Setup page
- **WhatsApp Business Account ID**: Found in the API Setup page (optional but recommended)
- **Access Token**: Generate a permanent token (not the temporary 24-hour token)
- **API Version**: Use the current stable version (e.g., `v21.0`)
### Configuring the Account
Add a Business API account to your `config.json`:
```json
{
"whatsapp": [
{
"id": "business",
"type": "business-api",
"phone_number": "+1234567890",
"business_api": {
"phone_number_id": "123456789012345",
"access_token": "EAAxxxxxxxxxxxx_your_permanent_token",
"business_account_id": "987654321098765",
"api_version": "v21.0",
"verify_token": "my-secure-random-token-12345"
}
}
]
}
```
**Important Notes:**
- Use a **permanent access token**, not the temporary 24-hour token
- The `verify_token` is a random string you create - it will be used to verify Meta's webhook requests
- Keep your access token secure and never commit it to version control
### Setting Up Webhooks (Required for Receiving Messages)
To receive incoming messages from WhatsApp Business API, you must register your webhook with Meta:
1. **Start the WhatsHooked server** with your Business API configuration
2. **Ensure your server is publicly accessible** (use ngrok for testing):
```bash
ngrok http 8080
```
3. **In Meta for Developers**, go to **WhatsApp** → **Configuration**
4. **Add Webhook URL**:
- **Callback URL**: `https://your-domain.com/webhooks/whatsapp/{accountID}`
- Replace `your-domain.com` with your public domain or ngrok URL
- Replace `{accountID}` with your account ID from config (e.g., `business`)
- Example: `https://abc123.ngrok.io/webhooks/whatsapp/business`
- **Verify Token**: Enter the same `verify_token` from your config
5. **Subscribe to Webhook Fields**:
- Check **messages** (required for receiving messages)
- Check **message_status** (optional, for delivery/read receipts)
6. Click **Verify and Save**
### Testing Your Business API Connection
Once configured, start the server and the Business API account will connect automatically:
```bash
./bin/whatshook-server -config config.json
```
Look for logs indicating successful connection:
```
Business API client connected account_id=business phone=+1234567890
```
Send a test message:
```bash
./bin/whatshook-cli send
# Select your business account
# Enter recipient phone number
# Type your message
```
### Business API Features
**Supported:**
- ✅ Send/receive text messages
- ✅ Send/receive images with captions
- ✅ Send/receive videos with captions
- ✅ Send/receive documents with filenames
- ✅ Media upload via Meta CDN
- ✅ Delivery and read receipts
- ✅ Event publishing to webhooks (same format as whatsmeow)
**Differences from whatsmeow:**
- No QR code pairing (uses access token authentication)
- Rate limits apply based on your Meta Business tier
- Official support from Meta
- Better reliability for business use cases
- Costs apply based on conversation pricing
### Running Both Client Types Simultaneously
You can run both personal (whatsmeow) and Business API accounts at the same time:
```json
{
"whatsapp": [
{
"id": "personal",
"type": "whatsmeow",
"phone_number": "+1234567890",
"session_path": "./sessions/personal"
},
{
"id": "business",
"type": "business-api",
"phone_number": "+9876543210",
"business_api": {
"phone_number_id": "123456789012345",
"access_token": "EAAxxxxxxxxxxxx"
}
}
]
}
```
Both accounts will:
- Receive messages independently
- Trigger the same webhooks
- Publish identical event formats
- Support the same API endpoints
## Usage
### Starting the Server
@@ -365,17 +534,21 @@ Examples with `default_country_code: "27"`:
The server exposes the following HTTP endpoints:
**Public Endpoints:**
- `GET /health` - Health check (no authentication required)
- `GET /api/hooks` - List all hooks (requires authentication if enabled)
- `POST /api/hooks/add` - Add a new hook (requires authentication if enabled)
- `POST /api/hooks/remove` - Remove a hook (requires authentication if enabled)
- `GET /api/accounts` - List all WhatsApp accounts (requires authentication if enabled)
- `POST /api/accounts/add` - Add a new WhatsApp account (requires authentication if enabled)
- `POST /api/send` - Send a message (requires authentication if enabled)
- `POST /api/send/image` - Send an image (requires authentication if enabled)
- `POST /api/send/video` - Send a video (requires authentication if enabled)
- `POST /api/send/document` - Send a document (requires authentication if enabled)
- `GET /api/media/{accountID}/{filename}` - Serve media files (requires authentication if enabled)
- `GET/POST /webhooks/whatsapp/{accountID}` - Business API webhook verification and events (no authentication, validated by Meta's verify_token)
**Protected Endpoints (require authentication if enabled):**
- `GET /api/hooks` - List all hooks
- `POST /api/hooks/add` - Add a new hook
- `POST /api/hooks/remove` - Remove a hook
- `GET /api/accounts` - List all WhatsApp accounts
- `POST /api/accounts/add` - Add a new WhatsApp account
- `POST /api/send` - Send a message
- `POST /api/send/image` - Send an image
- `POST /api/send/video` - Send a video
- `POST /api/send/document` - Send a document
- `GET /api/media/{accountID}/{filename}` - Serve media files
## WhatsApp JID Format
@@ -393,17 +566,30 @@ The server accepts both full JID format and plain phone numbers. When using plai
```
whatshooked/
├── cmd/
│ ├── server/ # Main server application
│ └── cli/ # CLI tool
│ ├── server/ # Main server application
│ │ ├── main.go
│ │ ├── routes.go
│ │ ├── routes_*.go # Route handlers
│ │ └── routes_businessapi.go # Business API webhooks
│ └── cli/ # CLI tool
├── internal/
│ ├── config/ # Configuration management
│ ├── events/ # Event bus and event types
│ ├── logging/ # Structured logging
│ ├── whatsapp/ # WhatsApp client management
│ ├── hooks/ # Webhook management
│ └── utils/ # Utility functions (phone formatting, etc.)
├── config.example.json # Example configuration
└── go.mod # Go module definition
│ ├── config/ # Configuration management
│ ├── events/ # Event bus and event types
│ ├── logging/ # Structured logging
│ ├── whatsapp/ # WhatsApp client management
│ │ ├── interface.go # Client interface
│ │ ├── manager.go # Multi-client manager
│ │ ├── whatsmeow/ # Personal WhatsApp (QR code)
│ │ │ └── client.go
│ │ └── businessapi/ # WhatsApp Business API
│ │ ├── client.go # API client
│ │ ├── types.go # Request/response types
│ │ ├── events.go # Webhook processing
│ │ └── media.go # Media upload/download
│ ├── hooks/ # Webhook management
│ └── utils/ # Utility functions (phone formatting, etc.)
├── config.example.json # Example configuration
└── go.mod # Go module definition
```
### Event Types