WhatsApp Business Integration

Since v2.0.0

Send document signing requests and notifications directly to your signers via WhatsApp. This integration uses the official WhatsApp Business API from Meta (Graph API v22.0).

Tip

WhatsApp messages have a 98% open rate compared to 20% for emails. Use this integration to dramatically improve signer response times.

---

Features

Feature	Description
Signing Requests	Send signature links directly via WhatsApp
Reminders	Automated reminders for pending signatures
Completion Notifications	Notify signers when document is complete
Template Messages	Pre-approved Meta templates for compliance
Encrypted Credentials	AES-256-GCM encryption for API tokens
Country Selector	80+ countries with flag emojis

---

Prerequisites

Before you begin, you’ll need:

• ✅ A Meta Business Account (free to create)
• ✅ A Facebook App with WhatsApp product added
• ✅ A verified phone number for WhatsApp Business
• ✅ Approved message templates (required by Meta)

---

Step 1: Create Meta Developer Account

1. Go to developers.facebook.com

2. Click “Get Started” or “Log In” with your Facebook account

3. Accept the Meta Platform Terms and Developer Policies

4. Verify your account (phone or email verification may be required)

5. You now have a Meta Developer Account

Note

Your Facebook personal account is used to access the developer portal, but your business will be separate.

---

Step 2: Create a Meta App

1. In developers.facebook.com/apps, click “Create App”

2. Select use case: Choose “Other” and click “Next”

3. Select app type: Choose “Business” and click “Next”

4. Enter app details:

   • App name: e.g., “MyCompany Signing Notifications”
   • Contact email: Your business email
   • Business Account: Select existing or choose “No Business Manager account selected” (you can add one later)

5. Click “Create App” and complete any security verification

Tip

You can create a Meta Business Account later and link it to your app.

---

Step 3: Add WhatsApp Product to Your App

1. In your App Dashboard, scroll down to “Add products to your app”

2. Find “WhatsApp” and click “Set up”

3. If prompted, select or create a Meta Business Account

4. You’ll be redirected to the WhatsApp API Setup page

5. Meta provides a test phone number you can use for development

---

Step 4: Configure Meta Business Account

1. Go to business.facebook.com

2. If you don’t have an account, click “Create Account”

3. Enter your business details:

   • Legal business name
   • Your name
   • Business email

4. Go to Business Settings → WhatsApp Accounts

5. Verify your app is connected

Caution

Business Verification (optional but recommended):
Go to Security Center → Start Verification to increase message limits from 250 to 1,000+ per day.

---

Step 5: Get Your Credentials

Phone Number ID

1. In WhatsApp → “API Setup”

2. Under “From”, you’ll see a phone number with a test number provided by Meta

3. Copy the Phone number ID (a long numeric string like 123456789012345)

4. For production, click “Add phone number” to use your own business number

Access Token

There are two types of tokens:

Temporary Token (Testing)

Valid for 24 hours:

1. Go to WhatsApp → “API Setup”
2. Click “Copy” next to the temporary token
3. Use this for testing only

Caution

Temporary tokens expire after 24 hours. Do not use in production.

Permanent Token (Production)

Never expires - Recommended:

1. Go to App Settings → “Basic”

2. Note your App ID and App Secret

3. Go to business.facebook.com/settings/system-users

4. Click “Add” to create a System User:

   • Name: “WPsigner Integration”
   • Role: Admin

5. Click “Add Assets” and assign your WhatsApp Business Account with full control

6. Click “Generate New Token”:

   • Select your App
   • Set expiration to “Never”
   • Select permissions:
     • whatsapp_business_management
     • whatsapp_business_messaging

7. Copy and securely store this token

Business Account ID (Optional)

1. Go to business.facebook.com/settings
2. Your Business Account ID is in the URL or under “Business Info”

---

Step 6: Create Message Templates

Meta requires pre-approved templates for business-initiated messages.

Required Templates

Create these three templates in WhatsApp Manager:

signing_request

Template Name: signing_request
Category: Utility
Language: English (en)

Header: Text - “Document Ready for Signature 📝”

Body:

Hello {{1}},

You have a new document "{{2}}" ready for your signature.

Click here to sign: {{3}}

This link expires in {{4}} hours.

Thank you for using WPsigner.

Variables:

• {{1}} - Signer name
• {{2}} - Document title
• {{3}} - Signing URL
• {{4}} - Expiration hours

Footer: “WPsigner - Secure Electronic Signatures”

signing_reminder

Template Name: signing_reminder
Category: Utility
Language: English (en)

Header: Text - “Reminder: Signature Pending ⏰”

Body:

Hello,

This is a friendly reminder that the document "{{1}}" is still awaiting your signature.

Please sign by {{2}} to avoid delays.

Sign now: {{3}}

Thank you!

Variables:

• {{1}} - Document title
• {{2}} - Due date
• {{3}} - Signing URL

signing_completed

Template Name: signing_completed
Category: Utility
Language: English (en)

Header: Text - “Document Signed Successfully ✅”

Body:

Great news!

The document "{{1}}" was successfully signed on {{2}}.

You will receive a copy via email shortly.

Thank you for choosing {{3}}.

Variables:

• {{1}} - Document title
• {{2}} - Completion date
• {{3}} - Brand name

Note

Template approval typically takes 24-48 hours. You can check status in WhatsApp Manager → Message Templates.

---

Step 7: Configure WPsigner

1. In WordPress admin, go to WPsigner → Integrations

2. Find WhatsApp Business and click “Configure”

3. Enter your credentials:

   • Phone Number ID: From Step 5
   • Permanent Access Token: Your permanent token
   • Business Account ID: Optional

4. Click “Test Connection” to verify your credentials are correct

5. Enable the “WhatsApp Notifications” toggle

6. Click “Save Settings”

Tip

You can test the connection before enabling the integration. This lets you verify your credentials are valid without activating WhatsApp notifications yet.

---

Step 8: Add Phone Numbers to Signers

When creating a document:

1. Go to WPsigner → New Document

2. In Step 2 (Add Signers), you’ll see a new WhatsApp field

3. Select the country code using the dropdown (with flags 🇺🇸 🇬🇧 🇲🇽)

4. Enter the phone number (digits only)

5. The full E.164 number is automatically formatted (e.g., +15551234567)

Tip

WhatsApp is optional for each signer. Signers without phone numbers will only receive email notifications.

---

How It Works

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Create Document │────▶│  Signer Added   │────▶│  WhatsApp Sent  │
│  with Phone #    │     │  (wps_signer_   │     │  with Sign Link │
│                  │     │   created hook) │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                         │
                                                         ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Completion     │◀────│  Document       │◀────│  Signer Signs   │
│  WhatsApp Sent  │     │  Completed      │     │  Document       │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Automatic Triggers

Event	Hook	WhatsApp Action
Signer added with phone	wps_signer_created	Signing request with link sent
Signer completes signing	wps_after_document_signed	Confirmation notification sent
All signers done	wps_document_completed	Final notification sent to remaining signers (skips those already notified)
Manual reminder	Triggered from admin	Reminder template sent with updated link

---

Security Features

WPsigner implements enterprise-grade security for WhatsApp integration:

Feature	Implementation
Token Encryption	AES-256-GCM encryption at rest via WPS_Encryption
Rate Limiting	5 test connection attempts/min, 10 saves/min per user
Input Validation	Numeric-only IDs, E.164 phone format validation before sending
Phone Validation	Numbers validated with validate_phone() before API calls
Audit Logging	All settings changes logged with user attribution
Nonce Verification	CSRF protection on all AJAX requests
Capability Checks	Only manage_options users can configure

---

Troubleshooting

Common Issues

Connection Failed

Error: “Connection failed” when testing

Solutions:

1. Verify Phone Number ID is numeric only
2. Check token hasn’t expired (use permanent token)
3. Ensure WhatsApp product is added to your app
4. Verify system user has correct permissions
5. Make sure you entered credentials in the form before clicking Test Connection

Message Not Delivered

Error: Messages not received

Solutions:

1. Verify phone number format (E.164: +15551234567)
2. Check recipient has WhatsApp installed
3. Ensure templates are approved
4. Verify you’re not in sandbox mode for production numbers
5. Check WP debug log for “Invalid phone format” errors

Template Error

Error: Template not found

Solutions:

1. Verify template name matches exactly: signing_request, signing_reminder, signing_completed
2. Ensure template is approved (not pending/rejected)
3. Check language code matches (default: en)
4. Wait 24-48h for newly created templates

Buttons Not Working

Error: “Test Connection” or “Save Settings” buttons have no effect

Solutions:

1. Update to WPsigner v2.0.1+ (earlier versions had this bug)
2. Clear your browser cache and reload the page
3. Check the browser console for JavaScript errors

Note

This was fixed in v2.0.1 — AJAX handlers are now registered regardless of the enabled/disabled state.

Rate Limits

Meta WhatsApp API has these limits:

Tier	Messages/day	Requirements
Unverified	250	None
Verified Tier 1	1,000	Business verification
Verified Tier 2	10,000	Good quality rating
Verified Tier 3	100,000	Excellent quality rating

---

API Reference

Public Methods

Method	Description	Return
WPS_WhatsApp::is_enabled()	Check if integration is enabled	bool
WPS_WhatsApp::is_configured()	Check if credentials are set	bool
WPS_WhatsApp::validate_phone($phone)	Validate E.164 phone number	bool
WPS_WhatsApp::send_template_message($phone, $template, $params)	Send a template message	array|WP_Error
WPS_WhatsApp::send_reminder($signer_id)	Send reminder to a signer	bool|WP_Error
WPS_WhatsApp::send_completion($signer_id)	Send completion notification	bool|WP_Error
WPS_WhatsApp::test_connection($phone_id, $token)	Test API connection	array|WP_Error

Send WhatsApp Message Programmatically

// Send a signing request via WhatsApp
$result = WPS_WhatsApp::send_template_message(
    '+15551234567',           // Phone in E.164 format
    'signing_request',        // Template name
    [
        'John Doe',           // {{1}} Signer name
        'NDA Contract',       // {{2}} Document title
        'https://...',        // {{3}} Signing URL
        '48',                 // {{4}} Hours to expire
    ]
);

if ( is_wp_error( $result ) ) {
    error_log( 'WhatsApp send failed: ' . $result->get_error_message() );
}

Check WhatsApp Status

// Check if WhatsApp is enabled and configured
if ( WPS_WhatsApp::is_enabled() && WPS_WhatsApp::is_configured() ) {
    // WhatsApp is ready to send messages
}

Validate Phone Number

// Validate phone before storing
$phone = '+15551234567';
if ( WPS_WhatsApp::validate_phone( $phone ) ) {
    // Valid E.164 format
}

Send Manual Reminder

// Send reminder for a specific signer
$result = WPS_WhatsApp::send_reminder( $signer_id );

if ( is_wp_error( $result ) ) {
    // Handle error
}

Test Connection Programmatically

// Test with specific credentials (useful for validation before saving)
$result = WPS_WhatsApp::test_connection( '123456789012345', 'your_token' );

if ( ! is_wp_error( $result ) ) {
    echo 'Connected: ' . $result['verified_name'];
}

WordPress Hooks

You can extend the WhatsApp integration using these hooks:

// Hook into the signing request flow
add_action( 'wps_signer_created', function( $signer_id, $document_id ) {
    // Called when a signer is added to a document
    // WhatsApp message is sent automatically if phone is set
}, 10, 2 );

// Hook into document signed event
add_action( 'wps_after_document_signed', function( $document_id, $signer_id ) {
    // Called when a signer completes signing
}, 10, 2 );

// Hook into document completed (all signers done)
add_action( 'wps_document_completed', function( $document_id ) {
    // Called when all signers have completed
}, 10, 1 );

---

Best Practices

Use Permanent Tokens

Never use temporary tokens in production. Generate a permanent token from a System User.

Verify Your Business

Complete Meta Business Verification for higher message limits and trust.

Monitor Quality Rating

Keep your quality rating high by avoiding spam and honoring opt-outs.

Test Before Production

Use Meta’s test phone number during development before going live.

---

FAQ

Q: Is WhatsApp Business API free?
A: Meta offers 1,000 free conversations per month. Additional messages are charged per conversation (typically $0.01-0.05 based on region).

Q: Can I use my personal WhatsApp number?
A: No, you must use a dedicated business number registered with WhatsApp Business API.

Q: How long does template approval take?
A: Usually 24-48 hours. Some templates may be rejected if they violate Meta’s policies.

Q: What happens if WhatsApp fails?
A: Email notifications are always sent as a fallback. WhatsApp is an additional channel.

---

API Version & Compatibility

Component	Version
Meta Graph API	v22.0 (supported until ~May 2027)
WPsigner integration	v2.0.0+
Database	MySQL and SQLite (WP_SQLite_DB) compatible

Note

WPsigner automatically handles API version management. The Graph API version is defined in the WPS_WhatsApp::API_BASE constant and will be updated in future plugin releases as Meta deprecates older versions.

---

Next Steps

• Configure API Keys - Set up REST API access
• Template Customization - Customize email templates
• Webhooks - Handle document events programmatically