WhatsApp business messaging and calling

The following FAQs provide guidance on WhatsApp onboarding, messaging behavior, integrations, limits, migrations, billing, compliance, and account management in Genesys Cloud.

Error messagesClick to expand

The following table describes the most commonly encountered errors or scenarios during WhatsApp onboarding or when sending WhatsApp messages to your customers.

Topic/category	Error and scenario	Suggested resolution
Embedded Signup Flow	An `Unknown error saving integration` when you attempt to create or save your integration.	If you are performing a migration, check if the two-factor authentication (2FA) is unavailable for your number in the source WABA. If you reintegrate a number that you previously integrated in Genesys Cloud; for example, in a different region or organization), make sure that you enter the six-digit PIN from the original integration. You can change the PIN for your number in WhatsApp Manager or you can request that Genesys change the PIN.
Template Messages – Per-User Marketing Message Limits	Error code: `131049` Description: `This message was not delivered to maintain a healthy ecosystem.` Meta chose not to deliver the message.	WhatsApp limits the number of marketing template messages that a person receives from any business in a specified period. For more information, see Per-User Marketing Template Message Limit.
Template Messages – Marketing Experiments	Error code: `130472` Description: `User's number is part of an experiment`. Message was not sent as part of an experiment.	WhatsApp does not send marketing messages to users who are part of the marketing message experiment. For more information, see Marketing Message Experiments.
Template Messages – Parameter Count Mismatch	Error Code: `132000` Description: `Template Param Count Mismatch` The number of variable parameter values included in the request did not match the number of variable parameters defined in the template.	Your request must include all the variable parameter values that are defined in the template.
Template Messages – Template does not exist	Error Code: `132001` Description: `Template does not exist` The template does not exist in the specified language or the template has not been approved.	Check if the template you are using has been approved and the template name and language locale are correct.
Messages Not Delivered		For more information, see Support – Cloud API – Documentation – Meta for Developers
Message Undeliverable	Error Code: `131026` Description: `Message Undeliverable` Meta cannot deliver the message. Reasons can include: The recipient phone number is not a WhatsApp phone number. The recipient has not accepted Meta’s new terms of service and privacy policy. Recipient using an old WhatsApp version; must use the following WhatsApp version or later: Android: 2.21.15.15 SMBA: 2.21.15.15 iOS: 2.21.170.4 SMBI: 2.21.170.4 KaiOS: 2.2130.10 Web: 2.2132.6	If you are using communication methods other than WhatsApp, then: Confirm that users can send a message to your WhatsApp business phone number. Confirm that users accepted the latest Terms of Service. Settings > Help or Settings > Application information prompts them to accept the latest terms and policies. Update to the latest version of the WhatsApp client.

Meta business portfolio/business manager accountClick to expand

I no longer have access to my Meta business portfolio/business manager account. How do I register WhatsApp numbers?

If you do not have access to a Meta business portfolio, you cannot register WhatsApp numbers in Genesys Cloud. Also, Genesys Cloud requires Facebook/Meta Login to create WABAs and add phone numbers via the embedded signup flow.

For more information about Meta business portfolio or business manager account access, see:

How can a Genesys partner access their customer’s WABA?

If you are a partner and must access to your customer’s WABAs, work with your clients to gain access. Use either of the following options:

Add people to a business portfolio and assign a business asset. Clients can add individual people from the partner company to their business manager or portfolio and assign those individuals access to specific WABA assets.
Give a partner access to business assets. Clients can share their WABA with the partner without providing access to the Meta business account. This option is more secure. Here, the partner must have their own Meta business account. When the WABA is shared, they can view it from within their Meta account, depending on the assigned type of access.

Meta business verificationClick to expand

What is business verification and why do I need it?

Business verification confirms that your account belongs to a legitimate business or organization and that your business is a legal entity. Verification confirmation allows you to scale your traffic and qualify for higher messaging limits. Business verification provides:

An increase in the phone number limit.
Visibility for your business’ display name.
Eligibility to request official business accounts (OBAs) that have a verified badge or a green check mark.

For more information about Meta business verification, see:

Phone numbersClick to expand

What types of phone numbers can I register on WhatsApp?

You can register any phone number with a country and area code that can receive voice calls or SMS from international numbers. It can include:

Genesys Cloud Voice and local SMS inventory numbers that you procure through Genesys.
800 and toll-free numbers that are not behind an IVR system during the WhatsApp verification process. If you cannot disconnect your number from IVR for WhatsApp registration, Genesys can request originating voice call numbers (ANIs) from WhatsApp. Use these ANIs to reroute your verification calls to another number capable for receiving the calls. Allow at least 2–3 business days for WhatsApp to provide these numbers.
A phone number owned by the business.
You cannot register short codes or sender IDs.

Mobile phone numbers that you register on an Android or iOS WhatsApp Messenger or WhatsApp business app cannot migrate to the WhatsApp business platform. To reuse and register these numbers on the WhatsApp business platform through Genesys Cloud, you must first delete the WhatsApp mobile account first. Follow these instructions to delete the account from your mobile app permanently.

Note: Deleting the app does not release the number; you must delete the account so that the number fully releases and Genesys treats it as a brand-new number for registration. After you have deleted the account, wait 3–5 minutes for WhatsApp to release the number. Then, create your WhatsApp integration in Genesys Cloud by following the process.

For more information about phone number types that you can register on WhatsApp, see , , and .

I procured an SMS number/long code from Genesys Cloud’s SMS number inventory. Can I use the same number for WhatsApp?

Submit your request to your Genesys Account Team. You can find that contact information in Orchestrators > Profile > My Contacts. Please include your Genesys Cloud region, Org ID, SMS number, and the voice-enabled number where you want to forward calls.

Note: Make sure that you send your request before you create your WhatsApp integration.

MigrationsClick to expand

How much downtime can I expect during a WhatsApp migration from another BSP or from Genesys Engage?

For active Genesys Engage numbers:
- Customers must delete their existing WhatsApp integration in Genesys Engage before they migrate via embedded signup in Genesys Cloud.
- If you successfully meet the migration prerequisites, downtime takes under 10 minutes.
For numbers registered through another Solution Partner:
- Downtime depends on whether the number is disconnected ahead of the migration. If the number is not disconnected, downtime does not begin until you create the integration in Genesys Cloud. Until then, you can use the business phone number via another BSP to send and receive messages without interruption.

How are my messages billed during the migration?

If your messages are sent before migration is complete or if you have undelivered messages sent before migration is complete, then your old solution partner is billed. If your messages are sent after the migration is complete, then your new solution partner will be billed.

After the migration, must I recreate existing message templates in the new WABA and also reconfigure my canned responses in Genesys Cloud?

No. You do not need to recreate templates in your destination WABA. They are automatically duplicated from your source WABA to the destination WABA and are granted the same quality ratings and statuses as their source counterparts. If you are migrating from Genesys Engage or another solutions provider, configure your templates as canned responses in Genesys Cloud.

Note: Only templates with a status of Approved and a quality score of Green are eligible for duplication.

If I am moving my contact center from one Genesys Cloud region/org to another, how do I transfer my WhatsApp integration to the new region/org?

To transfer your WhatsApp integration to the new region/org, perform the following steps:

Delete your WhatsApp integration from your existing region/org.
Follow the Embedded Signup Process to recreate your integration in the new region or org.
Note: You do not need to disable 2FA for the number during this process. However, ensure that you enter the same six-digit PIN that you used when the integration was originally created. You can also change the PIN for your number by going to your WhatsApp Manager, or requesting Genesys to change the PIN.

Official business accounts (OBAs)Click to expand

How do I obtain a green check mark or verified badge for my WhatsApp business profile?

OBAs have a green check mark or verified badge beside the display name in the Contacts view.

WhatsApp verifies that an authentic and notable brand owns the account.
Submit your request through your WhatsApp Business Manager.
Note: If an OBA request is denied or rejected by WhatsApp, it cannot be appealed. Wait for 30 days before resubmitting a new request.

Manage your WABAClick to expand

What happens if my WABA is no longer available and how can I reinstate it?

Navigate to Meta Business Support Home to check the status of your WhatsApp Business Accounts. Depending on WhatsApp’s Business or Commerce Policy violation, you can request a review of your restricted or inactive account.

For more information about reinstating your account, see Troubleshoot a restricted account

How do I change the display name associated with my WhatsApp phone number?

To change the display name for a phone number that is part of an existing embedded WABA review the display name guidelines and then perform the following steps:

Navigate to WhatsApp Manager > Account tools > Phone Number settings.
In the Display Name field, edit the display name.
Note: Wait for WhatsApp to approve the new name. Approval can take a few minutes to a few hours. Once the review is complete, Meta sends you a notification to your Meta account or to your email. You can proceed further only if your display name is approved. If the display name is rejected again, repeat Steps 1 and 2 and Edit the name again based on WhatsApp’s guidelines.
If your display name is approved, perform the following steps:
1. Delete your existing WhatsApp integration.
2. Wait for 1-2 minutes for the number to go offline status in your WABA.
3. Create a new WhatsApp integration using the same Embedded Signup Flow. See WhatsApp Embedded Signup flow overview.
4. Select your WABA and the old WhatsApp business profile for your phone number.
  Note: Do not create a new WhatsApp Business Profile. Even though you are selecting the old Business Profile with the old display name, the new display name approved by WhatsApp automatically displays for your Business Profile once the integration is saved.
5. Create or save the integration on the Platforms page by using the same six-digit PIN that you entered previously. If you lost or forgot your PIN, change it by navigating to the WhatsApp Manager > Accounts Tools > Phone Number Settings > Two-step verification page. After you save the integration, check the business profile for the number on your phone, which displays the approved new name.
If your display name is not approved, repeat steps 1 and 2 of the procedure.

Note: It is recommended that you prepare and plan the reintegrating and reverifying your WhatsApp number using voice or SMS during off-peak hours.

How do I update my WhatsApp business profile?

You can manage your WhatsApp phone numbers and business profiles from the WhatsApp Manager within your Meta Business Portfolio/Manager. To update your business profile for your phone number, perform the following steps:

Log in to your Meta Business Manager and select your Business Portfolio.
Navigate to WhatsApp Manager > Account tools > Phone Numbers and update the profile.

How do I create a WhatsApp message link or QR code?

You can request message links or QR codes for your WhatsApp numbers from the WhatsApp Manager within your Meta Business Portfolio/Manager. For more information about how to manage QR codes, see Manage your WhatsApp Business platform QR code.

Manage WhatsApp templatesClick to expand

Does WhatsApp impose any limit on template configurations?

Yes, WhatsApp imposes a limit of 10 total buttons per template. If you configure more than 10 buttons in your canned response, the template message fails to deliver.

What types of WhatsApp message templates are supported in Genesys Cloud?

Only Utility and Marketing templates are currently supported in Genesys Cloud. These templates can contain the following components:

Headers with static or dynamic text or image
Footer text (text-only)
Call to Action buttons
- Quick Reply buttons
- Call Phone Number buttons
- Visit Website button with static or dynamic URL

How do I create a new WhatsApp message template in my WABA?

For more information about how to create a WhatsApp message template in your WABA, see Create message templates for your WhatsApp Business Account.

For more information, see:

How do I add and use an approved WhatsApp message template in Genesys Cloud?

For more information about adding and using the WhatsApp template messages, see Add a WhatsApp template message and Use a WhatsApp template message.

Agentless and agent-initiated WhatsAppClick to expand

Data privacy, security, and compliance & restrictionsClick to expand

Messaging pricing and billingClick to expand

How do I access my WhatsApp insights data?

You can run real time monitoring of messaging and spending analytics of your WhatsApp business account. You can also view the metrics of all conversations on the Insights tab of the WhatsApp Manager. The real time graphs enable you to look into the performance of each metric. For more information about how to view conversation insights for your WABA, see View conversation insights for your WhatsApp Business Account.

Does Genesys always bill for WhatsApp’s passthrough charges?

Yes, for all WhatsApp numbers registered through Genesys Cloud’s Embedded Signup process, Genesys’ credit line is attached to the WABA. Meta bills Genesys for all WhatsApp charges incurred for the WABA. Genesys passes these charges to customers or partners on invoices.

Where can I find more information on Genesys Cloud and WhatsApp pricing?

For more information about Genesys Cloud and WhatsApp pricing, see Messaging pricing and Pricing — WhatsApp Business Platform.

WhatsApp Call button templateClick to expand

How do I create and send a WhatsApp call button template message?

You can send an interactive template message on WhatsApp with a Call on WhatsApp action button to help consumers easily contact your support team. When a consumer taps this button, it starts a WhatsApp call to your business number just like tapping the call icon in the chat title bar. The button cannot be configured to call a different number.

You can set up the message by creating a template in WABA and when WhatsApp approves the temple, you can create and use it as a Canned Response in Genesys Cloud, just like any other message template.

Note: You do not need to configure the Call on WhatsApp button when creating your Canned Response in Genesys Cloud. WhatsApp automatically adds the button to the outbound message when it is delivered to the consumer.

WhatsApp calling deep linksClick to expand

What are WhatsApp calling deep links and how do I create them?

Calling deep links are hyperlinks that let WhatsApp users directly call your business. The process to create a calling deep link is the same as creating a chat deep link.

Create the deep link in the following format: https://wa.me/call/<phone_number>. Replace <phone_number> with your full phone number in international format, including the country code.

Use: https://wa.me/call/1XXXXXXXXXX
Don’t use: https://wa.me/call/+001-(XXX)XXXXXXX

You can use calling deep links to promote WhatsApp calling for your business. For example, on your website, app, or marketing materials. You can also share them as QR codes to make calling even easier.

Also, you can send messages that include calling deep links, allowing WhatsApp users to contact a specific voice-enabled business number. The wa.me/call/<BUSINESS_PHONE_NUMBER> format is simple to copy, paste, and share and it doesn’t require creating a message template in WhatsApp business manager.

Note: Deep links are not supported on WhatsApp desktop clients.

Throughput and rate limitsClick to expand

Are there any throughput constraints for WhatsApp messaging on Genesys Cloud?

Yes. WhatsApp-imposed throughput limits apply independently of Genesys Cloud limits.

All inbound and outbound WhatsApp messages sent through Genesys Cloud are subject to WhatsApp Business Platform (Cloud API) throughput constraints per registered business phone number, regardless of any rate limits, throttling, or capacity configurations configured within Genesys Cloud.

WhatsApp throughput limits

By default, the WhatsApp Cloud API supports up to 80 messages per second (MPS) per business phone number (approximately 4,800 messages per minute). Sometimes, WhatsApp automatically upgrades throughput capacity up to 1,000 MPS.

Throughput limits apply to:

Both inbound and outbound messages.
All message types (session, template, media, interactive, and so on).

Other WhatsApp limits

Even at higher throughput levels, business phone numbers remain subject to more WhatsApp constraints, including:

WhatsApp Business Account (WABA) messaging rate limits
Template messaging limits
Per-user (pair) rate limits when sending high message volumes to the same recipient

If message traffic exceeds the permitted throughput, WhatsApp enforces platform-level throttling. The Cloud API returns error code 130429 (Rate Limit Hit) until message traffic returns within allowed limits.

Capacity planning responsibility

Customers running outbound campaigns—such as notifications, alerts, marketing messages, or large-scale proactive outreach—are responsible for designing campaign pacing, phone number strategy, and messaging volumes in accordance with WhatsApp’s throughput and rate-limit policies.

Are there any rate limits constraints for WhatsApp messaging on Genesys Cloud?

Yes. Genesys Cloud enforces outbound rate limits for WhatsApp messaging to ensure reliable delivery, controlled resource utilization, and compliance with platform and external provider constraints.

Customers planning high-volume outbound campaigns, notifications, alerts, or other proactive messaging use cases can request higher per-minute limits for their organization. To increase these limits, submit a request through Genesys Cloud Product Support.

Outbound WhatsApp campaign rate limits

The following limit applies to outbound WhatsApp campaigns at both the organization and per-campaign levels:

whatsapp.outbound.message.rate.per.minute

Applies to outbound WhatsApp campaigns.
Default (minimum) limit: 300 messages per minute.
Maximum configurable limit: 18,000 messages per minute.

Agentless WhatsApp rate limits

Agentless WhatsApp interactions have a separate rate limit, independent of campaign-based messaging:

agentless.outbound.whatsapp.message.rate.per.minute

Applies to agentless WhatsApp interactions.
Default (minimum) limit: 300 messages per minute.
Maximum configurable limit: 3,000 messages per minute.
Note: These Genesys Cloud limits apply independently of WhatsApp Business Platform (Cloud API) throughput and rate limits. Customers must ensure that their messaging volumes comply with both Genesys Cloud rate limits and WhatsApp-imposed constraints.

[NEXT] Was this article helpful?

Get user feedback about articles.