Documentation
Learn how Dualhook works, from initial setup to advanced configuration and WhatsApp platform operations.
Getting Started
Quick Start
Set up Dualhook and connect your first WhatsApp Business Account in minutes.
About Dualhook
What Dualhook is, where it fits in the WhatsApp ecosystem, and how it works.
Embedded Signup
How Dualhook uses Meta's Embedded Signup flow to connect WhatsApp Business Accounts via OAuth.
WhatsApp Webhook Override
How Dualhook uses WhatsApp Webhook Override to route supported customer-path webhooks directly from Meta to your server.
Pricing
Dualhook subscription plans, what is included, and how pricing relates to Meta messaging fees.
Billing Enforcement
What happens to Dualhook connections when a subscription ends or a plan limit is exceeded.
Troubleshooting
Common issues and solutions for Dualhook connections, webhooks, and health monitoring.
Support, Contact, and Bug Reports
How to contact Dualhook support, use the in-app support chat, report bugs, attach screenshots or PDFs, and know when email is the right path.
Support FAQ
Frequently asked questions about WhatsApp Business Platform and Dualhook.
Meta Platform
Meta Business Portfolio
The top-level container for business assets in Meta and why it matters for WhatsApp.
Meta Business ID
How to find your Meta Business ID and the difference between Business ID and WABA ID.
WhatsApp Business Accounts
What a WABA is, how it relates to phone numbers, and how ownership works.
Phone Numbers
Managing phone numbers in WhatsApp Business Platform: adding, removing, and limits.
Display Names
How display names work, naming rules, review statuses, and common rejection patterns.
Business Profiles
Managing the public-facing WhatsApp business profile for your phone number.
Official Business Account (OBA)
The WhatsApp blue checkmark: eligibility, notability requirements, and limitations.
Two-Step Verification (2FA)
Phone-number-level security using a 6-digit PIN for WhatsApp Business Platform.
Verification
Meta Business Verification
Overview of verification paths: PLBV, Standard, and Meta Verified for Business.
Standard Business Verification
The standard verification flow through Meta Security Center for non-coexistence accounts.
Meta Verified for Business
Paid subscription for trust, badge, and brand-protection features across Meta assets.
Coexistence
Templates & Messaging
Templates
Template lifecycle, categories, and management through Dualhook and Meta Graph API.
Template Elements
Template structure: headers, body, footer, buttons, variables, and practical limits.
Template Analytics
Measuring template performance: sent, delivered, read, and clicked metrics.
Sending Template Messages
How to send template messages via Cloud API with variables, media headers, and URL buttons.
Marketing Messages
Marketing template messaging hub: send paths (Cloud API and MM API), specialty template types, opt-out handling, billing, quality, and compliance.
Marketing Messages API for WhatsApp
MM API for WhatsApp: the /marketing_messages endpoint, feature comparison vs Cloud API, status webhook shape, fallback behavior, and the disable-marketing-on-Cloud-API toggle.
MM API Onboarding
Onboarding a WABA to MM API for WhatsApp: eligibility check (marketing_messages_onboarding_status), Terms of Service, Embedded Signup with marketing_messages_lite, and the MM_LITE_TERMS_SIGNED webhook.
Marketing Conversion Tracking
Measure conversions from marketing messages with Meta Pixel, Conversions API, and the Meta SDK. Includes fbclid handling, the click-event webhook, and Android deep-link attribution.
Marketing Creative Optimizations
Configure Meta's automatic creative optimizations on MM API marketing templates: creative_features_spec at template and WABA level, opt-in/opt-out per key.
Marketing Deep Links
Map a URL button on a marketing template to an Android app deep link via app_deep_link, with fallback URLs for non-Android clients and uninstalled-app users.
Marketing Max-Price (Beta)
Set a maximum price per marketing message delivery on MM API for WhatsApp using bid_spec. Includes per-message multiplier, reach estimation, and rollout phases.
Utility Messages
Utility template messaging hub: supported components and buttons, specialty types (location, call permission), CSW-free billing, volume tiers, content rules, and recategorization.
Location Templates
WhatsApp templates with a map header. Specify latitude, longitude, name, and address at send time. Useful for delivery updates, store finders, ride-hailing pickup and drop-off.
Authentication Messages
OTP and verification code delivery via WhatsApp: copy-code, one-tap, and zero-tap templates, linked device security, the 'I didn't request a code' webhook, and PendingIntent deprecation.
OTP Handshake & Android SDK
How the WhatsApp OTP handshake works for one-tap and zero-tap authentication templates: OTP Android SDK, manifest setup, eligibility checks, multi-app support, error codes, and PendingIntent deprecation.
Authentication Bulk Management
Use upsert_message_templates to create or update authentication templates across many languages in one call, and use message_template_previews to preview localized text before committing.
Authentication Best Practices
Security and UX best practices for WhatsApp authentication: identity hash binding for recycled phone protection, opt-in collection, isWhatsAppInstalled checks for Android and iOS, multi-app support.
Webhooks & API
The Basics Overview
Base URL, authentication, message send payloads, and webhook subscription basics.
Messaging Overview
Core messaging endpoint, text messages, formatting, delivery statuses, and common errors.
Messaging Webhook
Real-time webhook events for inbound messages, delivery statuses, and errors.
Webhook Events & Notifications
Management webhook events: template status, quality updates, account alerts, and forwarding.
Webhook Subscription Fields
Reference list of all 22+ WhatsApp Business Platform webhook subscription fields, what each notifies you of, required permissions, payload size limits, retry policy, mTLS support, and IP allowlisting.
account_alerts Webhook
Field reference for WhatsApp account_alerts webhooks: messaging-limit alerts, OBA status, profile-photo alerts, payload shape, and Dualhook handling.
account_review_update Webhook
Field reference for WhatsApp account_review_update webhooks: WABA review decisions, payload shape, and Dualhook handling.
account_update Webhook
Field reference for WhatsApp account_update webhooks: WABA lifecycle events, restrictions, partner events, pricing tiers, MM API terms, offboarding, and Dualhook handling.
business_capability_update Webhook
Field reference for WhatsApp business_capability_update webhooks: messaging limits, phone-number caps, capability changes, and Dualhook handling.
history Webhook
Field reference for WhatsApp history webhooks: Coexistence chat-history sync, phases, chunks, declined sharing, direct routing, and Dualhook handling.
smb_app_state_sync Webhook
Field reference for WhatsApp smb_app_state_sync webhooks: Coexistence contact sync, add/remove actions, direct routing, and Dualhook handling.
smb_message_echoes Webhook
Field reference for WhatsApp smb_message_echoes webhooks: Business App sent-message echoes, edits, revokes, direct routing, and Dualhook handling.
message_template_components_update Webhook
Field reference for WhatsApp message_template_components_update webhooks: template component edits, button fields, payload shape, and Dualhook handling.
message_template_quality_update Webhook
Field reference for WhatsApp message_template_quality_update webhooks: template quality score changes, payload shape, and Dualhook handling.
message_template_status_update Webhook
Field reference for WhatsApp message_template_status_update webhooks: template approval, rejection, pause, disablement, archive, deletion, appeal, and Dualhook handling.
security Webhook
Field reference for WhatsApp security webhooks: two-step verification PIN changes, reset requests, requester IDs, payload shape, and Dualhook handling.
template_category_update Webhook
Field reference for WhatsApp template_category_update webhooks: scheduled and completed template recategorization, payload shape, and Dualhook handling.
Service Messages
Free-form messages sent inside an open customer service window: type list, contextual replies, media caching, TTL, message quality, and pricing.
Interactive Service Messages
Interactive WhatsApp messages: CTA URL button, reply buttons, list, media carousel, and location request. Includes payload shapes and inbound-webhook formats for each type.
Address Messages (India)
India-only interactive form for collecting structured shipping addresses inside WhatsApp. Covers prefill, saved addresses, validation errors, the nfm_reply submission webhook, and feature-not-supported (error 1026) fallback.
Reaction Messages
Apply emoji reactions to WhatsApp user messages. Limitations (sent-only status, 30-day window, error 131009), how to remove a reaction, and inbound user reaction webhooks.
Media Messages
Sending and receiving images, video, audio, documents, and stickers via Cloud API.
Upload, Retrieve & Delete Media
Media lifecycle: upload files, retrieve download URLs, and delete media objects.
Contacts & Location Messages
Sending and receiving contact cards and location messages via Cloud API.
QR Codes & Short Links
Create, list, update, and delete WhatsApp QR codes and short links via the Business Management API. Each code prefills a message in the chat — useful for campaigns, signage, and tenant-specific entry points.
Welcome, Ice Breakers & Commands
Welcome messages, ice breakers, and slash commands for WhatsApp business numbers. (Note: for interactive buttons/lists/carousels, see Interactive Service Messages.)
Configure Welcome, Ice Breakers & Commands
Step-by-step setup and testing of welcome messages, ice breakers, and commands.
WABA Integration
End-to-end WhatsApp Business Account integration: token validation, discovery, and subscription.
Meta API Error Reference
Complete WhatsApp Cloud API and Meta Graph error code reference — what each code means, where it appears, and how to fix it.
WhatsApp Error Codes
WhatsApp Error 131049: Healthy Ecosystem Engagement
WhatsApp error 131049 means Meta withheld a marketing message to maintain healthy ecosystem engagement. Causes, the per-user limit, and how to fix it.
WhatsApp Error 131047: Re-Engagement Message Required
WhatsApp error 131047 means 24+ hours passed since the customer last replied, so the service window is closed. Why it happens and how to fix it with templates.
WhatsApp Error 131026: Message Undeliverable
WhatsApp error 131026 means the message is undeliverable — not a WhatsApp number, unaccepted Terms, or an outdated app. Causes and how to fix it.
WhatsApp/Graph Error 190: Access Token Expired
WhatsApp/Graph error 190 means your access token expired or is invalid. Why it happens and how to switch to a long-lived system-user token.
WhatsApp Error 130497: Country Restriction
WhatsApp error 130497 means your WABA is restricted from messaging users in certain countries. Causes, the scaling path, and Brazil/Indonesia limits.
WhatsApp Error 132001: Template Not Found
WhatsApp error 132001 means the template doesn't exist in that language/locale or isn't approved. Match the exact name, locale, approval state, and WABA context.
WhatsApp Error 132000: Template Variable Mismatch
WhatsApp error 132000 means the parameter count in your request doesn't match the approved template. Fix body, header, and button variables to match exactly.
WhatsApp Error 131056: Pair Rate Limit Hit
WhatsApp error 131056 means too many messages to the same recipient too fast (pair rate limit). How to pace per-recipient sends, back off, and prevent it.
WhatsApp Error 131031: Account Has Been Locked
WhatsApp error 131031 means your WABA is restricted/disabled for a policy violation, or request data (e.g. two-step PIN) could not be verified. How to recover.
WhatsApp Error 131050: Recipient Opted Out of Marketing
WhatsApp error 131050 means the recipient opted out of your marketing messages. You cannot override it — stop retrying and track opt-outs via user_preferences.
WhatsApp Webhook Error 100: "Before Override the Current Callback URI…"
"(#100) Before override the current callback uri" means your app must subscribe to the WABA messages field first. The two-step fix, plus webhook 2200/2201.
WhatsApp Error 130429: Throughput Limit Hit
WhatsApp error 130429 means your send rate exceeded the per-number throughput Meta allows (default ~80 msg/sec). How to queue, shard, and back off safely.
WhatsApp Error 131048: Spam Rate Restriction
WhatsApp error 131048 means the phone number is restricted because previous messages were blocked or flagged as spam. How to recover number health safely.
WhatsApp Error 131000: Something Went Wrong
WhatsApp error 131000 is Meta’s generic "something went wrong" send failure. When to retry, and how to investigate persistent unknown errors with fbtrace_id.
WhatsApp Error 80007: WABA Rate Limit Reached
WhatsApp error 80007 means the WhatsApp Business Account hit its rate limit on management/Graph calls. How to back off, cache, and stop over-polling.
WhatsApp Error 132012: Template Parameter Format Mismatch
WhatsApp error 132012 means template variable values are formatted incorrectly (e.g. header expected IMAGE, received UNKNOWN). Causes, fixes, and prevention.
WhatsApp Error 131042: Business Eligibility / Payment Issue
WhatsApp error 131042 means your account has a payment-method problem blocking sends. The full Meta cause list, how to restore billing eligibility, and prevention.
WhatsApp Error 131008: Required Parameter Is Missing
WhatsApp error 131008 means the request is missing a required parameter — common with flow buttons and dynamic template buttons. Causes and step-by-step fixes.
WhatsApp Error 131051: Unsupported Message Type
WhatsApp error 131051 means an unsupported message type — often inbound edited, deleted, poll, or unavailable messages hitting your webhook handler. What to do.
WhatsApp Error 368: Temporarily Blocked for Policy Violations
WhatsApp error 368 means your WhatsApp Business Account was restricted or disabled for a platform policy violation. How to diagnose, appeal, and prevent it.
WhatsApp Error 4: App Has Reached Its API Call Rate Limit
WhatsApp error 4 means the app has reached its API call rate limit (Graph app-level, not message throughput). How to back off, batch, and prevent it.
WhatsApp Error 200: No Access Token / Permission Issue
WhatsApp error 200 means no access token was provided ('Provide valid app ID'); in practice it also surfaces as a missing-permission-to-send error. How to fix both.
WhatsApp Error 10: Permission Denied
WhatsApp error 10 means permission is not granted or has been removed — missing scopes, unaccepted terms, or (for Flows) a non-allowlisted number. How to fix it.
WhatsApp Error 133016: Too Many Registration Attempts
WhatsApp error 133016 means registration/deregistration failed due to too many attempts for the number in a short period. Why it happens and how to recover.
WhatsApp Error 130403: Business Has Blocked the End User
WhatsApp error 130403 means your business has blocked the recipient on WhatsApp, so the message can't be delivered. Do not retry — unblock the user instead.
WhatsApp Error 131064: Messaging Limit from Template Classification Violations
WhatsApp error 131064 means your account hit a messaging limit due to template classification violations, affecting templates and direct sends. How to recover.
Calling
Cloud API Calling
Voice calling on WhatsApp Business Cloud API: VoIP via WebRTC or SIP, business-initiated and user-initiated calls, prerequisites, availability, and integration patterns.
Calling Pricing
How Meta bills WhatsApp Calling: free user-initiated calls, per-pulse business-initiated billing, volume tiers, customer service window interaction, call permission request charges, billing prerequisites.
Calling Configuration
Enable calling on a business phone number, configure call hours and holidays, restrict the call icon by country, set callback permissions, choose audio codecs, listen for settings webhooks.
Call Permissions
Obtain permission to call WhatsApp users: temporary (7-day) and permanent permissions, three ways to obtain (free-form request, template request, callback auto-prompt, business profile), get permission state endpoint, permission reply webhook.
SIP Configuration
Use SIP signaling instead of Graph API + webhooks for WhatsApp calling. TLS certificate requirements, digest authentication, business and user initiated SIP flows, SDES vs DTLS for SRTP, custom SIP headers.
Business-Initiated Calls
Place outbound voice calls to WhatsApp users. POST /calls with action: connect, SDP offer/answer flow, call status webhooks (RINGING/ACCEPTED/REJECTED), terminate webhook with duration, biz_opaque_callback_data tracking.
User-Initiated Calls
Receive inbound voice calls from WhatsApp users. Call Connect webhook with SDP offer, pre-accept for faster setup, accept/reject/terminate actions, DTMF dial pad, companion-device support.
Call Buttons & Deep Links
Drive WhatsApp calls from messages and links: voice_call interactive messages, voice_call template buttons, wa.me/call/<number> deep links with biz_payload tracking.
Calling API Reference
Consolidated WhatsApp Calling reference: every endpoint, every webhook, WebRTC and ICE guidelines, DTLS certificate recommendations, SDP requirements, bandwidth budget, IP allowlisting.
Timezone IDs
Reference for the numeric timezone_id field returned by Meta APIs. Maps to TZ_<REGION>_<CITY> constants. Used by call_hours.timezone_id (which takes IANA name on write) and other Meta resources.
Calling Troubleshooting
WhatsApp Calling errors and fixes: full error code table (138000-138023), SIP-specific status codes, media-flow timeouts, audio clipping causes and mitigations (SDES, pre-accept), quick triage guide.
Operations
Messaging Health Status
Monitor phone number health: AVAILABLE, LIMITED, BLOCKED states and quality rating.
Capacity, Quality & Limits
API rate limits, messaging limit tiers, quality rating, and scaling guidance.
Maintain Account Health
Ownership hygiene, quality monitoring, opt-out governance, and incident playbook.
Messaging Best Practices
Opt-in, notification quality, contact validation, callback handling, and pre-launch checklist.
Meta BSUID, Usernames & Contact Book Transition Guide
Overview of Meta's WhatsApp BSUID rollout: usernames, contact book behavior, parent BSUIDs, API recipient support, webhook changes, and migration timeline.
BSUID Webhook Changes
WhatsApp webhook payload changes for BSUIDs, usernames, parent BSUIDs, optional phone-number fields, statuses, contacts, groups, calling, and Coexistence events.
BSUID API and Sending Changes
How WhatsApp APIs use BSUIDs and parent BSUIDs in the recipient field for messages, Marketing Messages API, groups, block users, calling, and SIP.
BSUID Contact Book and Contact Requests
Meta contact book behavior for WhatsApp BSUIDs, phone-number inclusion rules, contact book deletion, REQUEST_CONTACT_INFO, and contacts webhooks.
Parent BSUIDs
Parent BSUID behavior for eligible multi-portfolio WhatsApp businesses, including payload fields, account lookup, supported APIs, and limitations.
WhatsApp Business Usernames
Business username rules for WhatsApp business phone numbers, including format, display priority, reserved usernames, management APIs, webhook updates, and errors.
WhatsApp Business API Permissions
OAuth scopes, WABA task access, delegated Meta access, and troubleshooting missing WhatsApp Business API permissions.
Compliance & Data Retention
Privacy boundary, configurable retention, CSV export, and organization isolation.
WhatsApp API Architecture & Security
Cloud API architecture, encryption, data residency, GDPR, and Dualhook's direct-routing security model.
Implementation Guides
Chatwoot WhatsApp Integration
Connect WhatsApp Cloud API to a Chatwoot inbox with Dualhook: route Meta's message webhooks straight to Chatwoot, match the verify token, and keep the inbox app-secret-free.
n8n Webhook Integration
Use n8n as a direct WhatsApp webhook receiver with Meta verification, payload-shape validation, and Graph API sends.
Make Webhook Integration
Use Make Custom Webhooks for direct Meta deliveries, payload-shape validation, and WhatsApp template sends.
Zapier Webhook Integration
Use a lightweight gateway for Meta verification, then forward approved WhatsApp events into Zapier for downstream automation.
Node.js Webhook Receiver
Set up a Node.js Express endpoint to receive WhatsApp webhooks routed by Dualhook.
Laravel Webhook Integration
Build a Laravel webhook controller for WhatsApp messages routed through Dualhook.
Shopify WhatsApp Integration
Connect Shopify order events to WhatsApp template messages via Dualhook and Cloud API.