WhatsApp best practices and FAQ

WhatsApp watches how customers react to business messages. Businesses whose messages are wanted keep a high quality rating, reach more customers, and see fewer failures. This page collects the practices that keep you there, the failure codes you may see, and answers to common questions.

Get and respect opt-in#

WhatsApp requires customers to agree to receive messages from your business on WhatsApp before you message them.

• Ask clearly. The opt-in names your business and says that messages arrive on WhatsApp, for example a checkbox reading "Send me order updates from Acme on WhatsApp".
• Ask in your own channels: your website, app, checkout, or in person. A pre-checked box or a buried clause in your terms is not consent.
• Keep a record of when and how each customer opted in.
• Make stopping easy. Tell customers how to stop messages, and stop as soon as they ask in any channel.
• Separate marketing from updates. A customer who agreed to delivery updates did not agree to promotions.

Write messages customers value#

• Send what customers expect, when they expect it: a shipping update when the parcel ships, a reminder the day before an appointment.
• Make the first line count. Say who you are and why you are writing; customers decide in seconds whether to block.
• Personalize with names, order numbers, and dates through variables, instead of generic broadcasts.
• Mind the hour. Send in the recipient's daytime, not at night.
• Limit marketing frequency. WhatsApp limits how many marketing messages one customer receives from all businesses, and holds back messages beyond it (code meta_131049).

Protect your quality rating#

Your quality rating reflects how customers reacted to your messages in the last few days. Blocks and spam reports lower it; read and replied messages don't raise it on their own, but they show the messages are wanted.

• Watch the rating on each sender's page. A move from High to Medium is a warning: slow down marketing sends and review the templates you sent recently.
• Act on paused templates. A paused template received too much negative feedback. Rework its wording before you send it again; repeated pauses disable it.
• Clean your lists. Stop sending to numbers that fail repeatedly with meta_131026, or that opted out of marketing (meta_131050).
• Grow gradually. When your messaging limit rises, increase volume step by step rather than sending to everyone at once.

Send reliably#

• Use an idempotency key derived from the triggering event, such as order-A-1234-shipped, so a retry never sends twice. See Idempotency keys.
• Send from background jobs, not inside user-facing requests, and retry rate limits and network errors with backoff.
• Don't resend uncertain messages blindly. They may have reached the customer. See When a message is uncertain.
• Track delivery with webhooks rather than polling, and store the message ID with your order, appointment, or account record.
• Keep the payment method valid in WhatsApp Manager; Meta refuses template messages without one (code meta_131042).

WhatsApp failure codes#

When WhatsApp refuses or cannot deliver a message, the message becomes failed, with WhatsApp's error code in failure_code as meta_<code>, and WhatsApp's explanation in failure_reason. When WhatsApp gives no code, failure_code is meta_error.

Meta's error code reference lists every code.

Go-live checklist#

Account#

• Your production number is connected in your production project and shows Connected.
• Your business verification is submitted or approved, and your display name is approved.
• A valid payment method is set in WhatsApp Manager.
• The business profile has a description, website, and photo customers will recognize.

Templates#

• Every template you will send is Approved, in every language you need.
• Your code maps each use case to its Template IDs, and fills every variable.
• Templates are categorized honestly: updates as utility, promotions as marketing.

Integration#

• Production uses its own API key with the WhatsApp send only permission, stored as a secret.
• Every send uses an idempotency key derived from the triggering event.
• Your code handles failed and uncertain messages, and distinguishes plan limits from transient errors.
• A webhook receives whatsapp.message.delivered and whatsapp.message.failed, verifies signatures, and stores events before acknowledging them.

Customers#

• Every recipient opted in to WhatsApp messages from your business, and you keep a record of it.
• Customers can stop messages easily, and opt-outs are honored everywhere.
• You know your plan's included messages, your wallet balance, and your messaging limit.

Frequently asked questions#