WhatsApp Business Integration

WPsigner 3.0.6+Graph API v25.0

Markdown for LLMs

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.

Tip

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

Note

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.

---

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 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

Permanent token (production)

Recommended — System User token

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

2. Open 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).

Temporary token (testing only)

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.

Tip

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

Note

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

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

Connection failed

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.

Templates missing / PENDING

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.

Message not delivered

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.

Embedded Signup blocked

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

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 — identity verification before signing
• Email templates — parallel email channel
• Webhooks — react to document events in your stack
• Markdown for LLMs — plain-text copy of this guide