A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The WhatsApp Business API is how an app or AI agent works with a WhatsApp business account: sending text, template, and interactive messages to customers, marking incoming messages as read, uploading and fetching media, and managing message templates. Access is granted through an access token and a set of Meta permissions, where one permission covers sending messages and another covers managing the account, so an agent reaches only what its token allows. WhatsApp can also push events to a webhook when a customer replies or a sent message is delivered or read.
How an app or AI agent connects to WhatsApp Business determines what it can reach. Calls go through Meta's Graph API with an access token, and the permissions that token carries decide what it can send and manage.
The Cloud API answers through Meta's Graph API at https://graph.facebook.com, hosted by Meta so there is no server to run. Messaging and media calls go through a phone number ID, and account management calls through a business account ID.
Webhooks deliver inbound customer messages and the status of sent messages to a callback URL once an app is subscribed to a business account. The X-Hub-Signature-256 header on each delivery, an HMAC of the body with the app secret, confirms it came from Meta.
A system user access token belongs to an automated service in Business Manager and can be set to never expire, so it suits a production integration that runs unattended. It carries whichever Meta permissions are granted to it.
A business integration system user token is generated through Embedded Signup for a tech or solution provider, scoped to each onboarded customer's business account. It is the route for connecting many customers' WhatsApp accounts.
A user access token is obtained through Facebook Login for Business and acts for a person who has granted the app access. It is short-lived unless exchanged for a long-lived token, and suits onboarding flows.
A temporary access token shown in the App Dashboard lasts about 24 hours and is meant for development and testing, not for production traffic.
The WhatsApp Cloud API is split into areas an agent can act on, such as sending messages, handling media, managing phone numbers, the business profile, and message templates. Each area carries its own permission, and sending messages is separated from managing the account.
Send text, template, media, interactive, location, contact, and reaction messages to a customer, and mark an incoming message as read.
Upload a media file to get a reusable ID, fetch the download URL for a received file, and delete an uploaded file.
List the numbers on a business account, read a single number, register or deregister a number for the Cloud API, and request and confirm a verification code.
Read and update the public business profile shown on a number, such as its description, address, email, and website.
Create a message template for Meta to approve, list the templates on a business account, and delete a template.
Subscribe an app to a business account's webhooks, list the subscribed apps, and remove a subscription.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
MessagesSend text, template, media, interactive, location, contact, and reaction messages to a customer, and mark an incoming message as read.2 | ||||||
| POST | /{PHONE_NUMBER_ID}/messages | Send a message to a customer: text, template, media, interactive, location, contacts, or a reaction. | write | whatsapp_business_messaging | Current | |
The message type is set in the request body. Free-form messages are only allowed inside the 24-hour window that opens when a customer messages first; outside it, an approved template is required. Acts onmessage Permission (capability) whatsapp_business_messagingVersionAvailable since the API’s base version Webhook event messagesRate limit80 messages/sec per number by default SourceOfficial documentation ↗ | ||||||
| POST | /{PHONE_NUMBER_ID}/messages | Mark an incoming message as read, and optionally show a typing indicator. | write | whatsapp_business_messaging | Current | |
Uses the same endpoint as sending, with the body set to status: read and the message_id of the received message. Adding a typing_indicator object shows the customer that a reply is being written. Acts onmessage Permission (capability) whatsapp_business_messagingVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
MediaUpload a media file to get a reusable ID, fetch the download URL for a received file, and delete an uploaded file.3 | ||||||
| POST | /{PHONE_NUMBER_ID}/media | Upload a media file and get a media ID to send later. | write | whatsapp_business_messaging | Current | |
An uploaded file is held on WhatsApp's servers for 30 days, after which it must be uploaded again. Acts onmedia Permission (capability) whatsapp_business_messagingVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /{MEDIA_ID} | Retrieve the download URL for a media file by its ID. | read | whatsapp_business_messaging | Current | |
The returned URL is valid for 5 minutes and the download itself must carry the same access token. Acts onmedia Permission (capability) whatsapp_business_messagingVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /{MEDIA_ID} | Delete an uploaded media file by its ID. | write | whatsapp_business_messaging | Current | |
Removes the file from WhatsApp's servers before its 30-day expiry. Acts onmedia Permission (capability) whatsapp_business_messagingVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Phone numbersList the numbers on a business account, read a single number, register or deregister a number for the Cloud API, and request and confirm a verification code.6 | ||||||
| GET | /{PHONE_NUMBER_ID} | Get a single business phone number's details, such as its display name, quality rating, and verification status. | read | whatsapp_business_management | Current | |
Specific fields are requested through the fields query parameter. Acts onphone number Permission (capability) whatsapp_business_managementVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /{WABA_ID}/phone_numbers | List the phone numbers registered on a business account. | read | whatsapp_business_management | Current | |
The business account is the entity that holds a number, its templates, and its settings. Acts onphone number Permission (capability) whatsapp_business_managementVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /{PHONE_NUMBER_ID}/register | Register a phone number for the Cloud API so it can send and receive messages. | write | whatsapp_business_management | Current | |
The request includes the two-step verification PIN for the number. A number cannot send through the Cloud API until it is registered. Acts onphone number Permission (capability) whatsapp_business_managementVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /{PHONE_NUMBER_ID}/deregister | Deregister a phone number from the Cloud API. | write | whatsapp_business_management | Current | |
After deregistering, the number can no longer send or receive through the Cloud API until it is registered again. Acts onphone number Permission (capability) whatsapp_business_managementVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /{PHONE_NUMBER_ID}/request_code | Request a verification code for a phone number, sent by SMS or voice call. | write | whatsapp_business_management | Current | |
The delivery method and language are set in the request. This is the first step of moving a number onto the Cloud API. Acts onphone number Permission (capability) whatsapp_business_managementVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /{PHONE_NUMBER_ID}/verify_code | Verify a phone number with the code that was sent to it. | write | whatsapp_business_management | Current | |
Confirms ownership of the number before it can be registered. Acts onphone number Permission (capability) whatsapp_business_managementVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Business profileRead and update the public business profile shown on a number, such as its description, address, email, and website.2 | ||||||
| GET | /{PHONE_NUMBER_ID}/whatsapp_business_profile | Get the public business profile for a phone number, such as its description, address, email, and website. | read | whatsapp_business_management | Current | |
The fields query parameter selects which profile fields are returned. Acts onbusiness profile Permission (capability) whatsapp_business_managementVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /{PHONE_NUMBER_ID}/whatsapp_business_profile | Update the public business profile for a phone number. | write | whatsapp_business_management | Current | |
Changes the description, address, email, websites, profile picture, and vertical that customers see. Acts onbusiness profile Permission (capability) whatsapp_business_managementVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Message templatesCreate a message template for Meta to approve, list the templates on a business account, and delete a template.3 | ||||||
| POST | /{WABA_ID}/message_templates | Create a message template for Meta to review and approve. | write | whatsapp_business_management | Current | |
A template carries a name, language, and category (marketing, utility, or authentication), and must be approved before it can be sent. A business account allows up to 100 template creations per hour. Acts onmessage template Permission (capability) whatsapp_business_managementVersionAvailable since the API’s base version Webhook eventNone Rate limit100 templates per WABA per hour SourceOfficial documentation ↗ | ||||||
| GET | /{WABA_ID}/message_templates | List the message templates on a business account and their approval status. | read | whatsapp_business_management | Current | |
Each template returns its status, such as approved, pending, or rejected. Acts onmessage template Permission (capability) whatsapp_business_managementVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /{WABA_ID}/message_templates | Delete a message template by name, or a single language version by its ID. | write | whatsapp_business_management | Current | |
Passing the name query parameter deletes every language version; passing hsm_id with name deletes a single language version. Acts onmessage template Permission (capability) whatsapp_business_managementVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Webhook subscriptionSubscribe an app to a business account's webhooks, list the subscribed apps, and remove a subscription.3 | ||||||
| POST | /{WABA_ID}/subscribed_apps | Subscribe the calling app to a business account's webhooks. | write | whatsapp_business_management | Current | |
Until an app is subscribed to the business account, no webhook events are delivered, even when a callback URL is configured. Acts onsubscribed app Permission (capability) whatsapp_business_managementVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /{WABA_ID}/subscribed_apps | List the apps subscribed to a business account's webhooks. | read | whatsapp_business_management | Current | |
Confirms which app is set to receive a number's messages and statuses. Acts onsubscribed app Permission (capability) whatsapp_business_managementVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /{WABA_ID}/subscribed_apps | Unsubscribe the calling app from a business account's webhooks. | write | whatsapp_business_management | Current | |
After this, the app stops receiving the business account's events. Acts onsubscribed app Permission (capability) whatsapp_business_managementVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WhatsApp can notify an app or AI agent when a customer sends a message or when a sent message changes state, instead of the app repeatedly asking. Meta posts the event to a webhook URL once an app is subscribed to the business account.
| Event | What it signals | Triggered by |
|---|---|---|
messages | Fires when a customer sends a message to the business number, and also when a message the business sent changes state, such as sent, delivered, read, or failed. Both arrive under the single messages subscription field. | /{PHONE_NUMBER_ID}/messages |
WhatsApp limits how many people a number can start a conversation with and how fast it can send, through a tier of unique customers per 24 hours and a separate per-second throughput ceiling.
WhatsApp limits how many people a number can start a conversation with through messaging tiers, counted as unique customers a business contacts in a rolling 24 hours: 250, then 1,000, 10,000, 100,000, and unlimited. A new number starts at 250, business verification raises it to 1,000, and a number climbs the tiers automatically as it sends to more unique people while keeping a good quality rating. Since October 2025 these tiers apply across a business portfolio rather than a single number. Separately, throughput is capped at 80 messages per second per number by default, and an eligible high-tier number can be upgraded automatically to 1,000 per second. Quality matters on top of volume: a low quality rating, driven by blocks and reports, can block tier upgrades and throttle sending.
List endpoints use cursor-based pagination through Meta's Graph API. A response carries a paging object with cursors.before and cursors.after, and a next and previous URL where more pages exist. The next URL should be followed until it is absent, rather than building the URL by hand. The limit query parameter caps how many items a page returns, and a page may hold fewer than the limit, so the presence of a next link is what signals more data.
Requests and responses are JSON over HTTPS. Media size limits depend on the type, for example up to 5 MB for an image and up to 100 MB for a document, and an uploaded media ID is held for 30 days. A message template has a body limit of 1,024 characters, and a business account allows up to 100 template creations per hour.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | 0: AuthException | The request could not be authenticated. The access token is missing, invalid, or expired. | Send a valid, unexpired access token in the Authorization header. |
| 403 | 3: API method | The token does not carry the permission needed for this call, or the capability is not enabled. | Grant the right permission, whatsapp_business_messaging for sending or whatsapp_business_management for account changes. |
| 400 | 100: Invalid parameter | A parameter in the request is missing, malformed, or not allowed for this call. | Check the request against the reference for the endpoint and correct the named field. |
| 400 | 131026: Message undeliverable | The message could not be delivered. Common causes are that the recipient is not a WhatsApp user, has not accepted updated terms, or is on an old version, and Meta does not always say which. | Confirm the number is on WhatsApp, and do not retry the same message in a tight loop. |
| 400 | 131047: Re-engagement message | A free-form message was sent more than 24 hours after the customer's last reply, so the customer service window has closed. | Send an approved template message instead, which can reach a customer outside the 24-hour window. |
| 400 | 131056: Pair rate limit | Too many messages were sent to the same recipient from the same number in a short time. | Slow the rate of messages to that recipient and retry after a short wait. |
| 400 | 132001: Template does not exist | The named template is not found in the business account, or the name or language does not match an approved template. | Check the template name and language against the approved templates on the business account. |
| 400 | 133010: Not registered | The phone number has not been registered for the Cloud API, so it cannot send. | Register the number through the register method before sending. |
| 429 | 80007: Rate limit hit | A business account rate limit was reached for messaging or management calls. | Reduce the request rate and retry after a short wait. |
The Graph API behind WhatsApp Business is versioned by number, and the newest version is v25.0, released on 18 February 2026. Each version is supported for about two years before it expires.
Version v25.0 is the newest version of the Graph API behind WhatsApp Business. The API is versioned by number in the request path, and each version is supported for about two years before it expires, so an integration can pin a version and move up on its own schedule. It was released on Wednesday 18 February 2026.
Version v24.0 was released on Wednesday 8 October 2025. Around this period messaging limits moved to apply across a business portfolio rather than a single phone number.
Version v23.0 was released on Thursday 29 May 2025.
Version v22.0 was released on Tuesday 21 January 2025. In mid-2025 WhatsApp Business messaging moved from conversation-based pricing to per-message pricing, charged per delivered template by category and country.
Version v21.0 was released on Wednesday 2 October 2024. From 1 November 2024, service conversations, the free-form replies inside the 24-hour window, became free with no monthly cap.
An integration can pin a version in the request path and move up on a schedule that suits it.
WhatsApp Business Platform changelog ↗Bollard AI sits between a team's AI agents and WhatsApp Business. Grant each agent exactly the access it needs, read or write, action by action, and every call is checked and logged.