To connect WhatsApp Cloud API, a Facebook app with the WhatsApp Product enabled is required. Refer to Meta's guide on setting up your Facebook app.
WhatsApp Cloud API is available to any business of any size to communicate with customers using the official WhatsApp API.
This channel has a limited 24-hour messaging window due to WhatsApp regulations.
Connecting WhatsApp Cloud API
To chat with your customers over WhatsApp Cloud API, connect a WhatsApp Business Profile and Meta Business Account. A Facebook App and Meta Business Account are required, and you must be the admin of both to connect.
- Navigate to Workspace Settings and click Add Channel.
- Locate the WhatsApp Cloud API Channel and click Connect.
- Click Connect With Facebook.
- Sign in using the Facebook account with admin access to the Facebook App and Meta business account.
- In the dropdown, select the WABA name with the WhatsApp number you'd like to connect.
- Add the Callback URL: go to the WhatsApp section in your Facebook Developer App, navigate to the Configuration subsection, and set up the Callback URL. Add the generated Callback URL and verify token from Aelyst to the corresponding fields in the webhook dialog.
- On the Facebook App, verify and save changes to the app.
- Subscribe to the webhook event: select the Webhooks tab under the Products panel, select WhatsApp Business Account in the dropdown, and click subscribe on the messages event.
- Click the toggle at the top of the page to turn on live mode. (Remember to fill in your privacy policy URL — if it's blank, you won't be allowed to turn on live mode.)
- Click Save Changes to complete the setup.
Once setup is complete, any messages sent to your WhatsApp number are received in your Workspace.
Channel configuration
The WhatsApp Cloud API Channel can be configured with a unique internal Channel name.
- Navigate to Workspace Settings and click Channels.
- Locate the WhatsApp Cloud API Channel and click Manage.
- Configure the Channel name, used internally to identify the account.
- Click Save Changes.
Metadata received by the Channel
The following Contact data is available from this channel:
- Phone number
- Phone number ID
- Profile name
- WhatsApp ID
Managing the WhatsApp Cloud API Profile
To change or check your WhatsApp Cloud API Profile from Aelyst:
- Navigate to Workspace Settings and click Channels.
- Locate the WhatsApp Cloud API Channel and click Manage > Profile.
- Click Sync Profile to obtain the latest information from WhatsApp.
- Edit the fields as needed, then review and click Save Changes.
Editable profile fields:
- Profile Photo — the WABA's profile picture. 640×640 recommended.
- About — appears beneath the profile image, phone number, and contact buttons.
- Address — max 256 characters.
- Description — max 512 characters.
- Email — a valid contact email. Max 128 characters.
- Vertical — the business industry (e.g. Automotive, Education, Food and Grocery, Restaurant, Other). Can't be set back to empty once created.
- Website — up to 2 URLs (including http:// or https://), each max 256 characters.
Managing WhatsApp message templates
Before sending a message template to a Contact in Aelyst, make sure you've submitted the template for approval and added the approved template to the Workspace by syncing.
Submitting message templates
- Navigate to Workspace Settings and click Channels.
- Locate the WhatsApp Cloud API Channel and click Manage.
- Click Templates > Submit Template.
- Fill in the required information:
- Template Name — lowercase alphanumeric characters and underscores only.
- Category — the category the template belongs to.
- Language — the language the template is written in.
- Create the message by filling in the components, then review it in the preview. You may include parameters like
{{1}},{{2}}as placeholders for personalized content. - Provide sample values (only if you included parameters). Sample values help the WhatsApp reviewer understand the message.
Template building blocks:
- Body — the main text of your template (text only; markdown formatting supported).
- Header — optional title, supporting text, image, video, or document (uploads up to 20 MB).
- Footer — optional, text only, for supplementary information.
- Button — optional interactivity. Call-to-Action buttons send clients to a website or phone number (max one URL and one phone number per template). Quick Reply buttons get quick answers (max 3 per template, each up to 20 characters).
Syncing message templates
- Navigate to Workspace Settings and click Channels.
- Locate the WhatsApp Cloud API Channel and click Manage.
- Click Templates > Sync Template.
After syncing, templates are listed with their statuses, the last synced timestamp updates, and any rejection reason appears below a rejected template. Possible statuses:
- Submitted — pending approval.
- Approved — can be sent to contacts.
- Rejected — cannot be used.
Supported file types
- Audio and Video — 16 MB
- Document — 100 MB
- Image — 5 MB
- Sticker — 100 KB
Unsupported file types or files exceeding the size limit are automatically converted to a URL link in Aelyst. Unsupported messages display as "Unsupported Message" or "Custom Payload" with the type (if available); click Show More to view the JSON payload. Examples include reactions, deleted messages, polls, and ephemeral messages.
Rate limits
A rate limit is the number of API calls an app or user can make within a given time period. Refer to Meta's documentation for this channel's specific rate limits.
FAQ and troubleshooting
Unable to send messages
Make sure the number connected to the platform is a WhatsApp Cloud API number.
Messages aren't arriving
This can happen when the messages webhook isn't subscribed. Open the Facebook App's Webhooks page, select WhatsApp Business Account, verify the messages event is subscribed, then send a test message to check if it arrives.
Unable to receive read receipts
When the connected user changes their Facebook password, permissions become outdated and need refreshing. Go to Workspace Settings > Channels, locate the Channel, click Manage > Troubleshoot > Refresh Permission, then send a test message.
Unable to send outbound messages: Validating Access Token Error
This can happen when the token-validation session expires, when a user's admin privileges change in Meta Business Manager, or after a password change. To resolve it, refresh your Channel permissions and send a test message again. You must be the admin of the Meta Business Manager to refresh permissions.
Contact not receiving messages
This can happen when the Contact hasn't agreed to WhatsApp's latest terms and privacy policy. Make sure they've accepted it.
What are the phone number requirements for WhatsApp Cloud API?
The number used for WhatsApp Cloud API can't be used in the WhatsApp personal or business app — delete that account first. The number can still be used for calling and receiving SMS after registration. Once used for Cloud API, it can no longer be used on the WhatsApp Business App.
Is Business Verification needed to start using Cloud API?
No, it isn't mandatory to complete Facebook Business Verification to start sending messages. Without it, your business can still respond to unlimited user-initiated conversations, send business-initiated conversations (templates) to 250 unique customers in a rolling 24-hour period, and register up to 2 phone numbers. Initiate Business Verification when you're ready to scale business-initiated conversations or become an Official Business Account.
Can I view conversation insights for my WABA?
Yes. Monitor messaging and spending analytics in real time in the Insights tab of your Meta WhatsApp Manager.
What are WhatsApp messaging limits?
Messaging limits determine the maximum number of unique WhatsApp users a business portfolio can start business-initiated conversations with in a 24-hour period, shared across all phone numbers in the portfolio. They don't apply to user-initiated conversations. A business-initiated conversation starts when the first message is delivered and lasts 24 hours. Note that multiple messages to the same user within 24 hours still count as one conversation.
How do I add a payment method to my WABA?
You can add a payment method to your WhatsApp Business account in Business Manager. Refer to Meta's guide for the steps.
Why did my message fail with "Business eligibility payment issue"?
This is most likely due to exceeding the monthly free tier threshold without a valid payment method. To resolve it, add a valid payment method.
What is WhatsApp Cloud API pricing?
Since July 1, 2025, WhatsApp Cloud API uses a hybrid pricing model. Service Conversations (replying to a customer within 24 hours) are billed per conversation. Template messages — Marketing, Utility, and Authentication — are billed per message sent. Utility templates are free if sent within 24 hours, while Authentication and Marketing templates are always charged per message. High-volume Utility and Authentication templates receive automatic tiered discounts. Free Entry Point Conversations from ads or Page CTAs open a 72-hour free window where all message types are free.
How do I delete a phone number from a business account?
There are a few requirements and steps involved — refer to Meta's documentation for details.
Can I send a Cloud API broadcast with the Meta test number?
You can send a test broadcast using the Meta test number, but it's limited to five recipients, and you must first add those five recipients to the phone number list in Meta Developer tools. If you don't add them or attempt to send to recipients not on the list, you'll receive an error.
Can I delete the Meta test number from my connected Cloud API account?
No. This number is automatically provided to all accounts for sending test messages and can't be deleted. Note that it's a test number and shouldn't be used for other purposes.
Why do I see duplicate Contacts from the same WhatsApp channel?
WhatsApp sometimes passes the Contact's phone number in a format different from the E.164 format Aelyst uses, which can duplicate Contacts from certain countries. If this occurs, contact support.
How do I change my Cloud API display name?
Navigate to your Facebook Business Manager > WhatsApp Account > Phone Number (this page shows your messaging limit and quality). Hover over the pencil icon next to the display name to edit, click Next to submit to Meta for approval, then await confirmation.
What should I do once my new Cloud API display name is approved?
After Meta approves the new display name, re-register your phone number using the newly approved name: execute a POST API call to verify your phone number, then another POST call to re-register the verified number. Once successful, the display name update is complete.
Why did I get "Error validating access token: the session has been invalidated…" when sending a message?
This occurs after you recently update your Facebook credentials, which can disrupt the Channel connection. To resolve it, refresh the channel permissions using your updated credentials (requires an Admin role). Refreshing re-establishes the connection so outbound messages send successfully.
How do I offboard WhatsApp Cloud API from Aelyst?
Step 1 — Delete the Channel in Aelyst: Go to Workspace Settings > Channels, select your WhatsApp Cloud API Channel, and delete it.
Step 2 — Delete the phone number from WhatsApp Manager: Go to Meta Business Manager, navigate to WhatsApp Manager > Phone Numbers, and delete the number.
What happens after I offboard WhatsApp Cloud API?
- Aelyst stops receiving and sending messages.
- Webhooks connected to Aelyst stop working.
- Deleting the Channel in Aelyst doesn't automatically delete the number from your Meta Business Account.
- To use the number again in the WhatsApp Business App, you must first delete it from Cloud API (as required by Meta).
- If the number continues messaging through another integration, standard Meta conversation pricing may apply.