# WhatsApp Business Integration (WPsigner)

> LLM-friendly plain Markdown. Human docs: https://docs.wpsigner.com/integrations/whatsapp/

**Plugin:** WPsigner 3.0.6+  
**API:** Meta WhatsApp Cloud API / Graph API **v25.0**  
**Setup mode (current):** Manual credentials + **Complete Setup** (step-by-step). One-click Meta Embedded Signup exists in code but is disabled until WPsigner Tech Provider approval.

---

## What it does

Sends WhatsApp template messages for signing workflows:

| Event | Template name | When |
|-------|---------------|------|
| Signing request | `signing_request` | Same timing as signing-request email (`wps_signing_request_sent`) |
| Signature recorded | `signing_signed` | Individual signer finishes (not the final “all done” notice) |
| Document complete | `signing_completed` | All required signers finished |
| Document declined | `signing_declined` | Signer declines |
| Reminder | `signing_reminder` | Manual or scheduled reminder |
| OTP | `otp_verification` | AUTH template for WhatsApp OTP (advanced signing) |

Credentials are stored encrypted (AES-256-GCM). Templates use **named parameters** (not positional `{{1}}`).

---

## Prerequisites

- Meta Business Account
- Meta app with WhatsApp product
- Business phone number (or Meta test number for sandbox)
- Permanent System User access token with:
  - `whatsapp_business_management`
  - `whatsapp_business_messaging`
- WhatsApp Business Account ID (WABA) — auto-detected by Complete Setup when possible

---

## Setup (current user flow)

### 1. Create Meta app + WhatsApp

1. https://developers.facebook.com/apps/ → Create App
2. Use case: **Connect with customers through WhatsApp** (or add WhatsApp product to a Business app)
3. Complete WhatsApp API Setup (test number is fine for development)

### 2. Get credentials

**Phone Number ID**  
WhatsApp → API Setup → copy **Phone number ID** (digits only).

**Permanent Access Token (recommended)**  
1. Meta Business Suite → System users  
2. Create system user (Admin)  
3. Assign WhatsApp Business Account asset (full control)  
4. Generate token for your app, permissions above  
5. Prefer long-lived / never-expire system user token for production  

Temporary API Setup tokens expire (~24h) — do not use in production.

**WABA ID**  
WhatsApp Business Account ID. Optional to paste manually; **Complete Setup** tries to detect it from Phone Number ID + token.

### 3. Configure in WordPress

1. WP Admin → **WPsigner → Integrations → WhatsApp Business**
2. Paste **Phone Number ID** and **Permanent Access Token**
3. (Optional) paste Business Account ID / set template language
4. Click **Complete Setup**  
   WPsigner will:
   - Save credentials
   - Test connection
   - Detect WABA when possible
   - Create missing default templates in Meta
   - Enable notification toggles
5. Or use **Test Connection** + **Save Settings** if you prefer manual control
6. In **Message Templates**, use **Create Missing Templates** / refresh until status is **APPROVED**

### 4. Signer phones

When adding signers, enter WhatsApp in **E.164** (e.g. `+15551234567`).  
Signers without a valid phone only get email.

---

## Default templates (created from WPsigner)

WPsigner submits these to Meta (Utility / Authentication). Bodies use **named** params.

### signing_request (UTILITY)

Named params: `signer_name`, `document_title`, `expire_hours`  
URL button → site signing path.

### signing_signed (UTILITY)

Named params: `signer_name`, `document_title`

### signing_completed (UTILITY)

Named params: `document_title`, `signed_date`, `brand_name`

### signing_reminder (UTILITY)

Named params: `document_title`, `deadline`  
URL button → signing path.

### signing_declined (UTILITY)

Named params: `signer_name`, `document_title`, `decline_reason`

### otp_verification (AUTHENTICATION)

Meta AUTH components + `message_send_ttl_seconds` (600). Copy-code OTP button.

Approval is by Meta (Utility often minutes–hours). Pending templates cannot send until APPROVED.

---

## Notification toggles

In WhatsApp settings: Request, Signature recorded, Document complete, Declined, Reminders.  
Complete Setup turns them **on** by default.

---

## Hooks (WordPress)

| Hook | WhatsApp behavior |
|------|-------------------|
| `wps_signing_request_sent` | Send `signing_request` if notify_request enabled |
| `wps_reminder_sent` | Send `signing_reminder` |
| `wps_after_document_signed` | Send `signing_signed` |
| `wps_document_completed` | Send `signing_completed` |
| `wps_document_declined` | Send `signing_declined` |

PHP class: `\InSigner\Integrations\Messaging\WhatsApp`

Useful methods:

- `WhatsApp::is_enabled(): bool`
- `WhatsApp::is_configured(): bool`
- `WhatsApp::validate_phone(string $phone): bool`
- `WhatsApp::test_connection(string $phone_id = '', string $token = '')`
- `WhatsApp::get_default_templates(): array`
- `WhatsApp::sync_default_templates(): array`
- `WhatsApp::get_setup_status(bool $refresh = false): array`

---

## Troubleshooting

| Symptom | Check |
|---------|--------|
| Connection failed | Numeric Phone ID; token not expired; WhatsApp product on app |
| Templates missing | Enter WABA / run Complete Setup; Create Missing Templates |
| PENDING forever | Wait for Meta approval; refresh templates |
| No message received | E.164 phone; template APPROVED; recipient has WhatsApp; quality/limits |
| “Cannot register customers” (Embedded Signup) | Meta Tech Provider / business verification / App Review — one-click path not offered in UI yet |

---

## One-click Embedded Signup (not in UI yet)

Code + `api.wpsigner.com` proxy support Meta Embedded Signup.  
Re-enable later with:

```php
define('WPS_WHATSAPP_EMBEDDED_SIGNUP', true);
```

Until Meta allows customer registration for the WPsigner business app, users must use the manual Complete Setup flow above.

---

## Related

- Human docs: https://docs.wpsigner.com/integrations/whatsapp/
- Docs LLM index: https://docs.wpsigner.com/llms.txt
- Meta WhatsApp Cloud API: https://developers.facebook.com/docs/whatsapp/cloud-api