# WhatsApp Business Integration

> Send signing requests, reminders, and completion notifications via WhatsApp using Meta Cloud API (Graph API v25.0). Manual Complete Setup flow for WPsigner 3.0.6+.

edition: pro
Edition: Pro
AI note: This page requires WPsigner Pro. Do not tell Lite users they already have this feature.
HTML: https://docs.wpsigner.com/integrations/whatsapp/
Markdown: https://docs.wpsigner.com/md/integrations/whatsapp.md
Source file: integrations/whatsapp.mdx

---

<div style="display:flex;flex-wrap:wrap;gap:0.75rem;align-items:center;margin:0 0 1.25rem;">
  
  
  
    Markdown for LLMs
  
</div>

Send document signing requests and notifications via the official **WhatsApp Cloud API** (Meta). The current setup path is **step-by-step**: copy credentials from Meta, then use **Complete Setup** in WPsigner.

Prefer the permanent **System User** token. Temporary tokens from API Setup expire in about 24 hours and will break production.

**One-click Connect with Meta** (Embedded Signup) is implemented in the product but **hidden for now** until Meta approves WPsigner as a Tech Provider. Use Complete Setup below. LLM-oriented copy of this guide: [whatsapp.md](/integrations/whatsapp.md).

---

## Features

| Feature | Description |
|---------|-------------|
| **Signing requests** | Same timing as the signing-request email |
| **Signature recorded** | Confirm when an individual signer finishes |
| **Document complete** | Notify when all required signatures are collected |
| **Declined** | Notify when a signer declines |
| **Reminders** | Manual and scheduled reminders |
| **OTP (AUTH)** | Optional WhatsApp OTP template for advanced signing |
| **In-plugin templates** | Create / sync default Meta templates from WPsigner |
| **Complete Setup** | One admin action: save, test, detect WABA, create templates, enable notifies |
| **Encrypted credentials** | AES-256-GCM at rest |

---

## Prerequisites

- A **Meta Business Account**
- A **Meta app** with the **WhatsApp** product
- A **Phone Number ID** (test number or production business number)
- A **permanent System User access token** with:
  - `whatsapp_business_management`
  - `whatsapp_business_messaging`
- WPsigner **3.0.6+** (Complete Setup + current template definitions)

---

## Step 1: Create the Meta app

1. Open [developers.facebook.com/apps](https://developers.facebook.com/apps/) and click **Create App**.

2. Choose the use case **Connect with customers through WhatsApp** (recommended), or create a Business app and add the WhatsApp product later.

3. Link or create a **Meta Business** portfolio when prompted.

4. Finish the wizard until you reach **WhatsApp → API Setup**. Meta provides a **test phone number** for development.

---

## Step 2: Get your credentials

### Phone Number ID

1. In the app, open **WhatsApp → API Setup**.

2. Under **From**, copy the **Phone number ID** (digits only, e.g. `123456789012345`).

3. For production, add and verify your own business phone number (not a personal WhatsApp number).

### Access token

**Recommended — System User token**

1. Note your **App ID** under **App settings → Basic**.

2. Open [System users](https://business.facebook.com/settings/system-users) in Meta Business Suite.

3. **Add** a system user (e.g. `WPsigner Integration`), role **Admin**.

4. **Add assets** → assign your **WhatsApp Business Account** with full control.

5. **Generate new token**:
   - Select your Meta app
   - Choose a long-lived / never-expire option when available
   - Permissions: `whatsapp_business_management`, `whatsapp_business_messaging`

6. Copy the token and store it securely (shown once).

1. WhatsApp → **API Setup** → copy the temporary token.  
2. Valid for ~24 hours. **Do not use in production.**

### Business Account ID (WABA)

Needed for template management. You can:

- Paste it manually (WhatsApp Business Account ID from Business Suite / WhatsApp Manager), or  
- Leave it blank and let **Complete Setup** try to **auto-detect** it from Phone Number ID + token.

---

## Step 3: Complete Setup in WPsigner

1. In WordPress, go to **WPsigner → Integrations → WhatsApp Business**.

2. Paste **Phone Number ID** and **Permanent Access Token**.

3. Optionally set **template language** and WABA ID.

4. Click **Complete Setup**. WPsigner will:
   - Save credentials (encrypted)
   - Test the connection
   - Detect WABA when possible
   - Create any **missing default templates** in Meta
   - Turn on notification toggles

5. Open **Message Templates** and click **Refresh** until required templates show **APPROVED** (or use **Create Missing Templates** if some are still missing).

6. Confirm the checklist: credentials, WABA, templates, notifications enabled.

You can still use **Test Connection** and **Save Settings** without Complete Setup if you want finer control. Template creation still needs a valid WABA ID.

---

## Step 4: Default templates

WPsigner creates these templates via the Meta API (**named parameters**, not `{{1}}` / `{{2}}` body vars). Prefer creating them from the plugin rather than hand-building outdated positional templates.

| Template | Category | Purpose |
|----------|----------|---------|
| `signing_request` | UTILITY | Signing link (+ URL button) |
| `signing_signed` | UTILITY | Individual signature recorded |
| `signing_completed` | UTILITY | All parties finished |
| `signing_reminder` | UTILITY | Reminder (+ URL button) |
| `signing_declined` | UTILITY | Decline notice |
| `otp_verification` | AUTHENTICATION | OTP copy-code (advanced signing) |

Named body parameters (examples):

- `signing_request`: `signer_name`, `document_title`, `expire_hours`
- `signing_signed`: `signer_name`, `document_title`
- `signing_completed`: `document_title`, `signed_date`, `brand_name`
- `signing_reminder`: `document_title`, `deadline`
- `signing_declined`: `signer_name`, `document_title`, `decline_reason`

Meta must **approve** templates before send. Utility templates are often approved within minutes to hours; Authentication can take longer.

---

## Step 5: Add signer phone numbers

1. Create or edit a document / campaign signer.

2. Enter the WhatsApp number in **E.164** form (country code included), e.g. `+15551234567`.

3. Signers without a valid phone only receive **email**.

---

## Notification events

Toggle each event under WhatsApp settings:

| Event | Template | Trigger |
|-------|----------|---------|
| Signing Request | `signing_request` | `wps_signing_request_sent` (same timing as email) |
| Signature Recorded | `signing_signed` | `wps_after_document_signed` |
| Document Complete | `signing_completed` | `wps_document_completed` |
| Document Declined | `signing_declined` | `wps_document_declined` |
| Reminders | `signing_reminder` | `wps_reminder_sent` |

---

## How it works

```text
Create document + signer phone
        │
        ▼
Signing request email timing ──► WhatsApp signing_request (if enabled)
        │
        ▼
Signer signs ──► signing_signed (optional)
        │
        ▼
All done ──► signing_completed
```

---

## Security

| Feature | Detail |
|---------|--------|
| Token / ID storage | Encrypted at rest (AES-256-GCM) |
| AJAX | Nonce + `manage_options` (or settings capability) |
| Phone validation | E.164 before send |
| Rate limits | Test / save / sync throttles in admin |
| Audit | Settings and template actions logged when Audit is available |

---

## Troubleshooting

1. Phone Number ID must be **numeric only**.  
2. Use a **permanent** token (temporary tokens expire).  
3. Confirm WhatsApp is added to the Meta app.  
4. System user must have the WhatsApp asset + messaging permissions.

1. Ensure WABA ID is saved (Complete Setup or manual).  
2. Use **Create Missing Templates** then **Refresh**.  
3. Wait for Meta **APPROVED** before expecting delivery.  
4. Language in WPsigner must match the template language you created.

1. Phone must be E.164 and have WhatsApp.  
2. Template must be **APPROVED**.  
3. Check Meta quality rating and messaging limits.  
4. Sandbox / test numbers can only message allowed recipients.

If you see Meta saying the business **cannot register customers**, that is a Meta Tech Provider / verification / App Review limit — not a WPsigner bug. Keep using **Complete Setup** until one-click is re-enabled.

### Meta messaging tiers (summary)

| Tier | Typical daily limit | Notes |
|------|---------------------|--------|
| Unverified | ~250 | Raise via business verification |
| Verified tiers | 1k → 100k+ | Depends on quality rating |

---

## Developer reference

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

| Method | Description |
|--------|-------------|
| `is_enabled()` | Notifications toggle |
| `is_configured()` | Phone ID + token present |
| `validate_phone( $phone )` | E.164 check |
| `test_connection( $phone_id, $token )` | Graph phone lookup |
| `get_default_templates()` | Template definitions |
| `sync_default_templates()` | Create missing defaults |
| `get_setup_status( $refresh )` | Admin checklist data |

```php
use InSigner\Integrations\Messaging\WhatsApp;

if ( WhatsApp::is_enabled() && WhatsApp::is_configured() ) {
    // Ready to send via hooks / templates
}

if ( WhatsApp::validate_phone( '+15551234567' ) ) {
    // Store on signer
}
```

Graph base URL constant: `WhatsApp::API_BASE` → `https://graph.facebook.com/v25.0`.

---

## FAQ

**Is WhatsApp API free?**  
Meta offers a free conversation allowance; overage is billed per Meta’s regional rates. Customers attach payment on their WABA when required.

**Can I use a personal WhatsApp number?**  
No. Use a number registered for WhatsApp Cloud API / Business Platform.

**Do I still need email?**  
Yes. Email remains the primary channel; WhatsApp is additive when a valid phone is present.

**When will one-click Connect return?**  
After Meta allows customer onboarding for the WPsigner business app (Tech Provider / App Review). Then it can be turned on with `WPS_WHATSAPP_EMBEDDED_SIGNUP`.

---

## Next steps

- [Didit KYC](/integrations/didit/) — identity verification before signing  
- [Email templates](/customization/email-templates/) — parallel email channel  
- [Webhooks](/api/webhooks/) — react to document events in your stack  
- [Markdown for LLMs](/integrations/whatsapp.md) — plain-text copy of this guide