WhatsApp API Send Message: Developer Guide
WhatsApp API Send Message: How to Send Your First Message
A WhatsApp API send message workflow is straightforward once you understand the four core pieces involved: authentication, the business sender, the recipient and the message content.
With MoceanAPI, your backend authenticates an API request, identifies who the message is from and who should receive it, defines the WhatsApp content, and submits the request. If the request is accepted successfully, MoceanAPI returns a message ID that can later be associated with delivery events.
This guide focuses on that first outbound operation. For exact request syntax, current field requirements and code examples, always refer to the MoceanAPI API documentation.
What Do You Need Before Sending a WhatsApp API Message?
Before making your first request, make sure you have the main pieces required for the outbound workflow.
You will need:
- a MoceanAPI account with appropriate API access;
- a current API token;
- a registered WhatsApp Business sender;
- a valid recipient identifier;
- appropriate message content;
- an understanding of whether a free-form message or approved template is appropriate; and
- access to the current API documentation for the exact implementation.
For a first send, you mainly need to understand how those components come together.
Step 1: Authenticate the WhatsApp API Request
Current MoceanAPI documentation uses API Tokens as the authentication method for REST API requests. For the WhatsApp send operation, the token is supplied through Bearer authentication in the request header.
Authentication should happen from your backend or another secure server-side environment.
Do not expose a real API token in browser-side JavaScript, a public repository or client-side application code. Store credentials using an appropriate secure method, such as environment variables or a secrets-management solution that fits your infrastructure.
Older MoceanAPI documentation may still contain examples that use an API key and API secret. For a new implementation, follow the current /docs and its Bearer API-token model instead.
Step 2: Identify the WhatsApp Business Sender
The sender is represented by:
mocean-from
Its job is simple:
Who is this WhatsApp message being sent from?
Current MoceanAPI documentation defines mocean-from as the registered WhatsApp Business sender phone number and requires the number to include its country code.
For example, this is not simply an arbitrary phone number selected by your application. It needs to correspond to the WhatsApp Business sender configured for your implementation.
The complete registration and WhatsApp Business Account onboarding process is a separate setup concern. At the send-request stage, the important point is that your application supplies the correct registered sender.
Step 3: Identify the WhatsApp Recipient
The recipient is represented by:
mocean-to
This answers:
Who should receive the message?
Current MoceanAPI documentation allows mocean-to to contain either a WhatsApp recipient phone number or a supported Business Scoped User ID (BSUID). Phone numbers must include the country code.
That BSUID support is increasingly important because a phone number should not be treated as the only possible WhatsApp user identifier.
MoceanAPI explains that a BSUID is generated by Meta for a user-business pair and can be used to message the user when their phone number is not available to the business. MoceanAPI also recommends retaining relevant BSUID information for future communication where applicable.
For your first implementation, the practical lesson is simple: validate the identifier you are sending and do not hard-code an assumption that every recipient will always be represented only by a phone number.
Step 4: Choose the Message Content
The actual WhatsApp message is represented by:
mocean-content
This defines what you want to send.
MoceanAPI currently documents several supported content families, including:
- text;
- templates;
- rich media;
- reactions;
- interactive content;
- location; and
- contacts.
For a first-send workflow, keep the mental model simple and start with text:
message type → message text
The current documentation shows text content using a type of text together with the message text itself. The exact JSON structure should come from the live API reference rather than being copied permanently into a blog article.
If you later need images, video, documents, buttons, lists or other supported content, those message types introduce their own content structures.
When Can You Send Free-Form Text?
Free-form messaging is not available in every WhatsApp messaging context.
Under WhatsApp’s current Business Messaging Policy, a business can reply without an approved template within the 24-hour customer-service window following the user’s last message. Outside that window, business-initiated messaging must use an approved message template.
MoceanAPI’s current API documentation reflects the same high-level rule: templates are required for customers who have not yet messaged the business or who have not sent a message within the previous 24 hours.
Its support guidance also states that a business initiating communication without an open customer-service conversation must begin with a template message.
So before using a simple text message, your application needs to know whether the current WhatsApp messaging context allows it.
Detailed template creation, categories, approval and management are separate topics. For this send operation, the key decision is simply:
Can I send free-form content here, or does this message require an approved template?
Review the WhatsApp Business Messaging Policy for current messaging rules. For platform-level implementation guidance, see the official WhatsApp Business Platform developer documentation.
Step 5: Build the Outbound Send Request
At this stage, the pieces come together:
Bearer authentication
- sender
- recipient
- message content
- optional delivery-event URL
Current MoceanAPI documentation lists the WhatsApp send endpoint as:
POST https://rest.moceanapi.com/rest/2/send-message/whatsapp
It defines mocean-from, mocean-to and mocean-content as required request elements, while mocean-event-url is optional.
The optional mocean-event-url specifies a webhook destination for delivery events related to the requested message.
Conceptually, each part has a clear responsibility:
Component | Purpose |
Bearer API token | Authenticates your application |
mocean-from | Identifies the registered WhatsApp Business sender |
mocean-to | Identifies the recipient |
mocean-content | Defines the message being sent |
mocean-event-url | Optionally provides a destination for delivery events |
If you are working out how to send a message through the WhatsApp API, this is the main model to remember.
Do not build your production request from a simplified blog table alone. Use the current MoceanAPI WhatsApp API reference for the exact endpoint, header, JSON structure and current field requirements.
Step 6: Submit the Request and Read the Result
One of the most important distinctions in a WhatsApp API to send message workflow is the difference between:
API request accepted
and
message delivered
and
message read.
They are not the same event.
Current MoceanAPI documentation states that a successful send request returns HTTP status 202. The successful response contains a status value and a message_id.
That means the request has successfully reached the appropriate API stage. It does not mean the recipient has already received or read the WhatsApp message.
Why the message ID matters
The returned message_id gives your application a reference to the message transaction.
Depending on your implementation, you may retain that identifier so that later delivery events can be connected with the original outbound message.
MoceanAPI’s delivery-event documentation explicitly states that the webhook message_id is associated with the transaction and comes from the HTTP response of the WhatsApp send request.
You do not need a particular database schema to make use of this. The important design principle is simply to avoid discarding an identifier that your application may need later.
What Happens After the Send Request?
The high-level lifecycle looks like this:
send request accepted
→ message ID returned
→ WhatsApp delivery lifecycle
→ delivery event
Current MoceanAPI documentation reports delivery states including:
- sent;
- delivered;
- read; and
- failed.
The documentation also notes that read-receipt behaviour can affect whether a read event is available.
This matters because the initial API response and the later message outcome solve two different problems.
The send response tells your application whether the outbound request was accepted.
Delivery events tell your application what happened afterwards.
If your application needs to track delivery or customer responses, that becomes a webhook and event-processing implementation rather than part of the initial send request.
Common WhatsApp API Send-Message Mistakes
A first implementation often fails for relatively simple reasons.
Using outdated authentication
Do not copy an old API-key/API-secret example and assume it is the current method. Current MoceanAPI /docs uses Bearer API-token authentication.
Exposing the token in frontend code
The API token is a credential. Keep authenticated requests in an appropriate backend or server-side component.
Sending from the wrong WhatsApp sender
Check that mocean-from matches the registered WhatsApp Business sender you intend to use.
Formatting the recipient incorrectly
Verify the recipient identifier and country-code formatting. Also remember that MoceanAPI currently supports BSUID as well as a phone number.
Sending free-form text when a template is required
Check the current customer-service window and template rules before deciding which content type to send.
Assuming HTTP success means delivery
A successful request is not proof that the message has been delivered or read. Those are later lifecycle states.
Discarding the message ID
If your application needs delivery tracking or correlation, retain the returned message ID.
Treating a normal send request as a broadcast campaign API
The standard WhatsApp send operation is a programmable messaging API request. It should not be described as a dedicated bulk campaign system, audience-management platform or campaign scheduler.
Testing Your First WhatsApp API Message
Before moving a sending workflow into production, run a controlled test.
Use this checklist:
- Verify the current API token. Make sure your backend is using the active credential and current Bearer-authentication method.
- Verify mocean-from. Confirm the registered WhatsApp Business sender.
- Verify mocean-to. Confirm the recipient or appropriate test identifier and its format.
- Check the messaging context. Decide whether text is allowed or an approved template is required.
- Compare your request with current /docs. Check the latest endpoint, fields and content structure.
- Submit the request.
- Capture the response and message ID.
- Check later delivery state where your application needs it.
MoceanAPI also documents a WhatsApp Sandbox for testing supported sending and receiving behaviour using configured test numbers and trial templates. Verify the latest sandbox procedure in current MoceanAPI support material before relying on it for a test workflow.
Where MoceanAPI Fits
The complete first-send mental model is:
your application/backend
→ Bearer authentication
→ MoceanAPI WhatsApp API
→ WhatsApp recipient
MoceanAPI provides the programmable WhatsApp messaging layer. Your own application still decides why the message should be sent, which customer it relates to, what business action triggered it and what your system should do with later events.
If you need a WhatsApp Business API to send message requests from your application, start by understanding this workflow, then move to the official reference for implementation.
Review the MoceanAPI API documentation for the exact current endpoint, headers, request structure and response fields.
You can also explore MoceanAPI WhatsApp API to review the broader product and its supported business messaging capabilities.
Share this article :
