FAQ

Short answers, grouped by when the question comes up. Each links to the page that has the full version.

Before you start

Do I need a WhatsApp Business API account?

Yes, and you get one as part of connecting a number. The connect flow creates or attaches a Meta business account and a WhatsApp Business account for you. There is no separate application to fill in and no waiting list. What you do need is a phone number nobody is using in the WhatsApp app, and a few minutes inside Meta's own signup popup.

Can I use my existing business number?

Yes, if it is not currently active in the WhatsApp or WhatsApp Business app. Meta will not attach a number that is signed in on a handset.

To move a number you are already using, delete the WhatsApp account from within the app first. That is permanent and takes the chat history with it, so if the number carries conversations you need, use a different one. A landline works.

What does it cost?

Meta charges per 24-hour conversation, not per message, and the price depends on the conversation's category and the customer's country. A marketing conversation costs several times a utility one. A free-form reply inside an open window is a service conversation and is free.

Message credits mirror that, so never budget one credit per message. Every successful send returns X-Message-Category, X-Message-Price and the balance left in response headers, read those rather than assuming. Credits and billing has the detail, and your plan sets the rate card.

How long does template approval take?

Usually minutes, occasionally a few hours. Authentication templates are approved almost immediately; utility and marketing ones take longer. It is Meta's review, so there is nothing to escalate and re-submitting does not restart it.

Poll GET /v1/notifications/events?refresh=true and watch ready climb toward 18. You can start sending an event the moment its own template is approved. You do not have to wait for all of them.

Can I try it before connecting a number?

You can explore the event catalog without a number, GET /v1/notifications/catalog needs no phone number and returns every event with its variables and template preview, which is enough to build an integration against. Actually sending anything needs a linked, registered number.

Setup

I set everything up and nothing sends at all. Why?

Almost certainly the number is linked but not registered on the Cloud API. Those are two separate actions, and an unregistered number is rejected by Meta on every send with error 133010, regardless of templates or credits.

Check health.blockers in GET /v1/notifications/events, or look for the Registered badge on Phone Numbers. Connect your WhatsApp number covers it.

What is the 6-digit PIN for?

It is WhatsApp's two-step verification for that number, required by Meta at registration. It is not a password for this platform and it never goes to customers. Keep it somewhere the business can find it: Meta asks for the same PIN if the number is ever re-registered or moved.

Can I connect more than one number?

Yes. With several linked, pass phoneNumberId on every send, omitting it resolves to the oldest configured number, which is a quiet way to send from the wrong one. Templates are approved per WhatsApp business account, so a template approved for one number is not automatically usable by another.

Messages and delivery

Why did one customer not get a message?

When everyone else received theirs, it is nearly always the phone number rather than the platform. In order of likelihood:

• No number at checkout. Many themes make the phone field optional. The integration logs this as a skip rather than a failure.
• No country code. Non-digits are stripped, so a national number is delivered to a real subscriber somewhere else. Set the integration's default country and store numbers in E.164.
• The number has no WhatsApp account, a landline, or a number nobody registered. Accepted by Meta, never delivered.
• They blocked your business, or opted out with STOP.

The skip log in the integration and the Logs screen in the dashboard will say which. Troubleshooting has the full list.

The API returned success but nothing arrived.

A 200 with a messageId means Meta accepted the message, not that it was delivered. Check GET /v1/notifications/status/:messageId, status moves sent → delivered → read. Updates arrive asynchronously, so a message read back immediately still says sent, which is normal. A wrong-but-valid recipient number is the most common real cause.

Can I message a customer who has never written to me?

Only with an approved template. Outside the 24-hour window opened by a customer's own message, WhatsApp delivers nothing else, which is precisely the situation every new order is in. This is why order notifications are templates rather than text. The 24-hour window explains it in full.

Can I reply to customers?

Yes, from the Inbox, and freely, text, images, buttons, for 24 hours after their last message to you. Those replies are service conversations and cost nothing. Once the window closes, only a template will reach them.

Content and customisation

Can I change the wording of a message?

Yes, but not freely and not instantly. The wording is a Meta-approved template, so changing it means submitting a new template and waiting for review, you cannot edit the text of an approved one at send time.

What you can change without approval is the values: the store name, order id, totals, tracking links and any other variable the template declares. For different wording, submit your own template with POST /v1/templates and send it through /v1/messages/send. Message templates and approval covers the rules that get a template rejected.

How many events are there, and can I add one?

Eighteen, covering orders, shipping, payments, returns, one-time passcodes and three marketing events. The list is fixed, map any other store state, such as packed, delayed or on hold, onto order_status, which takes the status as a variable. For anything genuinely different, write your own template.

What happens if I forget a variable?

The send does not fail. A missing, null or blank value becomes a literal - in the customer's message, the credit is spent, and the response carries the name in missingVariables. Treat any missingVariables as an error in your own logs, nothing else will flag it.

Can I send in a language other than English?

The shipped catalog is en_US. Templates in other languages are submitted the same way as any custom template, and languageCode on a send chooses which locale to look for, en_US also matches a template approved as en.

Stores and consent

Will it work with my theme or my plugins?

On WooCommerce, yes in almost every case: the plugin hooks the order lifecycle rather than the theme, so it does not care how your checkout looks. It reads the billing phone field, so a theme or checkout plugin that hides or renames that field is the one thing that breaks it , make the phone field required and the rest follows. Custom order statuses can be mapped to events.

On Shopify, the app subscribes to order and fulfilment webhooks, which are theme-independent. The one part that touches your theme is the back-in-stock form, which needs a small snippet added to the product page. See WooCommerce and WordPress and Shopify.

My store is custom-built. Can I still use it?

Yes, call POST /v1/notifications/send from your backend with an event key and named variables. That is the same call both integrations make. Custom and headless stores has a worked example, including deduplicating per order and event so a retry cannot send twice.

How do customers opt out?

By replying STOP. Marketing templates carry a Reply STOP to unsubscribe footer because Meta requires an opt-out affordance, and the reply is honoured automatically. The contact is marked opted out and excluded from later marketing sends.

Customers can also block your number in WhatsApp, which stops delivery silently and counts against your quality rating. Contacts and opt-outs covers the consent record.

Does opting out stop order updates too?

Opting out is about marketing. A customer who has bought something still needs to know their parcel shipped, and utility templates are what that is for. Treat STOP as ending promotional contact, not as a reason to stop confirming orders, and never send a marketing message dressed as a utility one to get around it, because Meta reclassifies templates it thinks are promotional, and customers report them.

What is a quality rating and should I worry about it?

Meta grades each number green, yellow or red based on how many recipients block or report it, and the grade sets how many customers you may start a conversation with per day. Order updates rarely hurt it, people want those. Unwanted marketing is what turns it yellow, and red means your daily limit is already being cut. Recovery takes days. Connect your WhatsApp number has the table.

Not answered here

Troubleshooting covers delivery problems in the order worth checking them, and Getting support explains how to raise a ticket that can be answered in one reply.