WhatsApp For Business API
Overview
Our WhatsApp Business Platform (WAB) API allows you to interact with WhatsApp users via your WhatsApp Business Account.
This is a quick overview to guide you through the sign up and on-boarding process for WhatsApp Business API. Contact your existing Messaging Platform solutions provider for an overview of WhatsApp Business application features and services.
Onboarding Process
For WhatsApp Business API pricing, and to sign up to our WhatsApp Business API, contact your Account Manager.
Our provisioning team will provision your Mobile Gateway WhatsApp Business API in our system.
You will need to assign a User who has access to your businesses Facebook account.
Our provisioning team will email your designated User a URL link. This will direct the User to our interface, and guide you through the Embedded Sign Up process.
Developer Information
Please see our API Documentation for details and code samples.
Embedded Sign Up
Visit Embedded Sign Up process documentation for details on the process and the role we play as your WhatsApp Solution Provider.
Message Templates
For more information on managing Message Templates within your existing WhatsApp Business Application, visit the Message Template Guidelines or the Business Management API Guide - Templates documentation by Meta.
Webhooks
Visit this link for more information on managing Webhooks within your existing WhatsApp Business Application, or contact your existing Messaging Platform solutions provider.
MO Callback
You will only receive MO messages if you have configured an MO callback URL within your API Configuration.
We recommend using https:// for your callback URLs.
When a MO message is received for you a POST request is made to the MO callback URL, this callback will include the MO message detail as a JSON object in the body of the POST request.
POST callback-url
{
"id": str:id,
"source": str:source,
"Destination": str:destination,
"content": obj:content,
}
These are nofications which will be included in content - Whatsapp Message Notification
| Message type | Description |
|---|---|
| Audio | Audio / voice note. |
| Button | Represents a button reply selected by the user in response to a button message sent by your business. |
| Context | Provides information about the message this message is replying to (threading). |
| Document | Document / file (e.g. PDF, etc.). |
| Errors | Lists any errors associated with sending a message, typically included when status is failed. |
| Identity | Indicates a change in user identity information, such as phone number or profile. |
| Image | An image sent by user. Payload includes media metadata. |
| Interactive | Interaction type messages (e.g. replies to interactive messages your business sent, like list-messages or buttons) |
| Referral | Metadata showing how the user came into contact with your business (e.g., ad click, QR code, link). |
| Sticker | Sticker media. |
| System | System-level notifications such as user identity/phone-number changes |
| text | Plain text message |
| Template | Represents a template message sent by the business, including name, language, and dynamic components. |
| Type | Specifies the kind of message or event, helping the backend parse content correctly (e.g., text, image, interactive, sent, delivered). |
| Video | A video sent by user. |
The value “base64” will be supplied for messages containing binary data. Content will be supplied encoded using base64, decoding content is needed to obtain the original data. NOTE: Regular SMS messages with GSM 7-bit or Unicode content will not supply this parameter.
DLR Callback
You will only receive DLR Statuses if you have configured a DLR callback URL within your API Configuration.
We recommend using https:// for your callback URLs.
When a DLR message is received for you a POST request is made to the DLR callback URL, this callback will include the DLR Status detail as a JSON object in the body of the POST request.
POST callback-url
{
"id": str:id,
"status": str:status,
"reference": str:reference,
}
DLR Message Status
The following are the status codes returned in DLRs that our message gateway supports.
| Status | Description |
|---|---|
| sent | Message has been sent by the carrier transport |
| received | Message has been received |
| rejected | The carrier rejected the message |
| expired | The carrier was unable to deliver the message in a specified amount of time. For instance when the phone was turned off. |
OpenAPI Specification
The OpenAPI (Swagger) specification can be obtained from here
You can see code samples and a breakdown of the specification here.
Error Codes
The following is a list of common errors that can occur:
| Code | Description |
|---|---|
| 131026 | Message Undeliverable: Indicates a “Bad Request” (400), often because the recipient’s phone number is invalid, not on WhatsApp, or the recipient has not accepted new Terms of Service |
| 131048 | Spam Rate Limit Hit: Restrictions applied because too many messages were flagged or blocked as spam |
| 130429 | Rate Limit Hit / Throughput Reached: The maximum allowed Cloud API message limit has been exceeded |
| 131047 | Outside 24 Hour Window: Messages sent outside the 24 hour customer service window |
| 131056 | Message Rate Limit (Same Recipient): Too many messages sent to a single recipient in a short period |
| 131031 | Account Blocked/Locked: The account is blocked by Meta for policy violations |
| 131042 | Payment Issue: Payment account not linked to the WhatsApp Business Account or credit limit exceeded |
| 132001 | Template Does Not Exist: The message template used is not approved, has the wrong name, or is in the wrong language |
A comprehensive list of WhatsApp error codes is available: here
Help
Having trouble integrating with any of our services? Contact support@modicagroup.com and we’ll help you sort it out.
