How to Send a WhatsApp Message With Cloud API

Before sending your first Cloud API message from code, you need a WhatsApp Business Account, a registered or test phone number, its Phone Number ID, an access token, and a recipient that your current setup is allowed to message. Keep the Graph API version configurable so the guide does not lock your application to one old version.

For a production sender, use server side credentials and a real business number. For initial development, Meta's test resources are enough to prove the request format. Once one message succeeds, save the returned message ID and add webhook tracking before building larger workflows.

Phone number configuration is part identity, part routing. The visible business number is what customers recognize, while the Phone Number ID is what the Graph API uses in message and registration endpoints. Make sure the number is attached to the intended WABA and is in the expected registration state.

Normalize customer numbers before sending and keep country code handling explicit. Avoid guessing a country code from local formatting in production workflows. A CRM should store phone numbers in a consistent international representation so the same customer is not created multiple times under different formats.

An access token proves that your backend is allowed to call Meta's Graph API. The token alone is not enough: it must belong to the right app or system user, include the required permissions, and have access to the WhatsApp business assets involved in the request.

When debugging authentication, first identify what kind of token you are using and whether it is intended for temporary development or server side production use. Then verify the permissions and asset assignments instead of repeatedly generating new tokens without understanding the original failure.

Outbound Cloud API messages are sent to the Graph API messages endpoint for the sending Phone Number ID. The request is authenticated with a bearer token and the JSON body declares messaging_product as whatsapp together with the recipient and message type.

Keep the Graph API version configurable instead of hard coding an old version throughout your application. Your backend should also store the returned WhatsApp message ID because that ID is how later webhook status events are matched back to the message you sent.

For a first direct API test, keep the payload simple. Send a text message to a test recipient that is allowed by your current setup, then inspect both the HTTP response and the message that arrives on the phone. A successful API response confirms that the token, Phone Number ID, payload, and recipient are accepted by Meta.

Do not treat an accepted request as the final delivery result. The API response gives you a message ID. Delivery, read, or failure outcomes arrive later through webhook status events, so production applications should store that ID and update its status asynchronously.

cURL is useful because it removes your application framework from the test. If the same request works in cURL but fails in your backend, the problem is usually in how your application builds headers, serializes JSON, reads environment variables, or handles the response.

Use placeholders in documentation and keep real tokens out of shell history, screenshots, repositories, and support messages. When debugging, compare the exact URL, headers, and JSON body with the request generated by your application.

Once the request works outside your application, move it into server side code. Keep the token and Phone Number ID in environment variables, validate the recipient before sending, and return a controlled error to the calling workflow instead of exposing the full Meta response to the browser.

The example below uses the built in fetch API available in current Node.js runtimes. In a larger application, put this logic behind a small WhatsApp client module so retries, logging, API version changes, and error handling stay in one place.

The initial send response is not the final delivery result. Store the outbound WhatsApp message ID and update that record when webhook events report sent, delivered, read, or failed states.

Start with the exact error returned by the failing layer. For a Graph API request, record the HTTP status and the structured error object. For a webhook, record the request path, response status, and event identifiers. For an external API or CRM, keep its response separate so one provider's error is not mistaken for another provider's failure.

Retry only when the failure is safe to retry. Authentication, invalid parameters, missing templates, and permission errors usually need a configuration or data fix. Network timeouts and some temporary server failures can be retried with backoff, but message and workflow operations should be idempotent so a retry does not create duplicates.

Webhooks are the event input for a WhatsApp integration. Meta verifies a public HTTPS callback URL, then sends incoming messages and message status events to that endpoint. Your app also needs the correct WhatsApp Business Account subscription so events reach the callback.

A production sender needs more than one successful API call. Move credentials into protected server configuration, use a system user token appropriate for production, add webhook status tracking, and make message creation idempotent so retries do not send duplicates.

Separate message intent from transport. Your business workflow should decide what needs to be sent, while one messaging service validates the recipient, selects the correct message type or template, calls Meta, stores the message ID, and returns a controlled result to the workflow.