WhatsApp Business Platform (API) Channel Configuration

💡 Coming soon: WhatsApp is rolling out usernames in July 2026

When a Contact adopts a username, their phone number will no longer be shared with your business, so WhatsApp is introducing a new Contact identifier, Business-Scoped User ID (BSUID). Respond.io will handle this automatically — conversations will continue as normal and Contact records will remain unaffected.

Here's what's coming:
- Respond.io will support the new Contact identifier, BSUID when no phone number is available.
- Phone number will remain as the primary identifier if it’s present and sending messages via phone number will continue to work as usual.
- A new Request phone number button will be available for Marketing and Utility message templates — letting Contacts share their phone number directly in the conversation.
- For CRM-integrated businesses, BSUID will be available in webhook events and the Developer API, ready to sync with your third-party integrations. This applies to new Contacts created after April 2026.

Need help? Contact support or refer to Meta's documentation.

After connecting your WhatsApp Business Platform (API) Channel to respond.io, use the Channel configuration settings to manage your Channel name, business profile, supported file types, messaging rate limits, and best practices for keeping your WhatsApp Business Account (WABA) in good standing with Meta.

Configuring WhatsApp channel name

Set a unique internal channel name to identify this account within respond.io.

1. Navigate to Workspace Settings and click Channels.

2. Locate the WhatsApp Business Platform (API) Channel and click Manage.

1. Configure the Channel name, which is used internally to identify the account.

2. ClickSave Changes to update the Channel configuration.

Managing the WhatsApp Business Profile

Update or review your WhatsApp Business Profile directly from the respond.io platform.

Step 1: Navigate to Workspace Settings and click Channels.

Step 2: Locate the WhatsApp Business Platform (API) Channel and click Manage > Profile.

Step 3: ClickSync Profile to pull the latest WhatsApp Business Profile information from WhatsApp.

Step 4: Edit the following fields as needed.

Step 5: Review the information and click Save Profile.

Note: If your updated profile isn't showing to customers, click Sync Profile to see what WhatsApp currently has saved. If it still isn't correct, contact support.

Metadata received by Channel

Different channels provide different sets of Contact metadata to the respond.io platform. The following Contact data is available from this channel:

• Phone number

• Phone number ID

• Profile name

• WhatsApp ID

• Business-Scoped User ID (BSUID)

• Username

For WhatsApp Contacts who have adopted a username, BSUID and username fields are now available:
- In the channel array of the Channel Meta object on New Incoming Message and New Outgoing Message webhook events.
- The List Contact Channels endpoint now returns BSUID and username fields. See the API documentation for updated field definitions.
This applies to new Contacts created after April 2026.

Supported file types

Unsupported file types or files that exceed the size limit are automatically converted to a URL link on the respond.io platform. Unsupported messages display as “Unsupported Message” or “Custom Payload” with type (if available). Click Show More to view the JSON payload for Custom Payload messages. Examples of unsupported message types for WhatsApp Business Platform (API): Reactions Deleted messages Polls Ephemeral messages

Confirm the file format is supported before sending. Files that are not converted properly may fail to send even when within the size limit. Learn more about supported media types.

Text formatting

Use text or markdown formatting in your messages. Learn more about how to format text in WhatsApp.

Rate limits

A rate limit is the number of API calls an app or user can make within a given time period. Learn more about the rate limits for this channel.

Channel limitations

WhatsApp groups

Group messaging is supported by Meta on the WhatsApp Business Platform (API) but is not yet available on respond.io. Upvote the feature request if this is important to your use case.

Unsupported number types

WhatsApp doesn’t allow Voice over Internet Protocol (VoIP) or toll-free numbers. This includes Google Voice numbers (VoIP) and domestic toll-free numbers, such as the UAE 800 series.

UAE 800 numbers can’t receive international SMS or voice calls, so Meta’s verification code can’t reach them.

Use a number in full international format, starting with + and the country code. The number must be able to receive SMS or voice calls.

WhatsApp Status

WhatsApp Status is not supported by the WhatsApp Business Platform (API). Posting, sending, receiving, or managing WhatsApp Status is not available. If you’re interested in this feature, upvote the feature request.

Meta Business Agent

Meta Business Agent is a separate Meta capability — Meta's own AI agent, set up and managed in Meta's tools for a specific WhatsApp phone number. Connecting or managing a Meta Business Agent from respond.io is not currently supported. Upvote the feature request if this is important to your use case.

WhatsApp Account Model Evolution (WAME)

Meta is gradually moving WhatsApp Business Accounts (WABAs) to a new account model, WhatsApp Account Model Evolution (WAME). It splits each WABA into two accounts:

To check if your account is on WAME, go to Meta Business Suite > Settings. If WhatsApp accounts and Messaging accounts appear as separate items under Accounts, your account is on WAME.

Existing WhatsApp Channel connections keep working during the rollout. You don't need to reconnect your Channel.

With WAME, one phone number can connect to more than one partner. Each partner has its own Messaging account, templates, and billing. These stay shared across every partner on the number:

• Throughput and messaging limits. Adding a partner doesn't increase them.

• Quality rating. Every partner's sending affects it.

Any partner connected to your number can deregister it.

To add respond.io to a number that's already connected to another partner, follow Add respond.io to a WhatsApp number connected to another partner.

Set respond.io as the primary responder in Conversation Routing

When more than one partner is connected to your number, Conversation Routing in Meta Business Suite decides which partner receives and replies to incoming messages. By default, Meta routes messages to the first partner that connected to the number. If that isn't respond.io, incoming messages won't reach your respond.io Inbox.

You can change Conversation Routing only when more than one partner is connected to your number. It doesn't apply to WhatsApp Coexistence numbers, which can be connected to only one partner.

To route incoming messages to respond.io:

1. Go to Meta Business Suite > Settings.

2. Under Accounts, click WhatsApp accounts, then select your phone number.

   

3. Click the Conversation routing tab.

   

4. Click Manage.

5. In Manage who responds to messages, select respond.io in every dropdown:

   • Customer replies to click-to-WhatsApp ad

   • Customer sends a message

   • Calls with customers

   • Customer replies to a marketing message

   • Customer replies to a utility message

   

6. Click Apply.

Respond.io doesn't support standby mode. Set respond.io as the primary responder for every option, or incoming messages won't reach your respond.io Inbox.

If you remove a partner from your number, check Conversation Routing afterwards. Meta doesn't pick a replacement automatically.

Best practices

To maintain a stable WhatsApp Business Platform (API) setup and avoid unexpected bans or disruptions, follow these best practices.

Avoid WABA disablement

Follow these best practices to avoid WABA disablement.

Use a verified and unique Meta Business Manager (MBM)

• Use one MBM per business. Creating multiple MBMs with the same business name, address, or website may be flagged by Meta.

• If a previous MBM was banned, avoid using the same business details for a new one — Meta may instantly ban it.

• Verify your MBM by submitting official business documents (e.g., business license, matching website).

• Control access carefully: Only grant admin rights to real Facebook profiles with consistent activity (posts, friends, etc.).

• Enable Two-Factor Authentication (2FA) for all admins.

Manage WhatsApp Business Accounts (WABAs) responsibly

• If a WABA is banned, appeal via Meta Support. Do not create a new WABA while an appeal is pending — this may be seen as policy evasion.

• Use clear and accurate display names. For example, “Acme Co – California” is better than just “Acme”.

• Do not delete and recreate phone numbers frequently (“burning” numbers). Resolve reported issues via Meta instead.

Handle Facebook users the right way

• Admins must use authentic Facebook accounts with real history.

• Avoid using newly created or duplicate accounts solely for access purposes.

• Limit access to essential team members and regularly audit MBM users.

• Enforce 2FA to reduce the risk of unauthorized access.

Keep your business aligned across platforms

• Ensure your business name, address, website, and other details match across your MBM, WABA, and Ad Account.

• This alignment increases trust with Meta and improves your chances of verification.

If your WABA gets disabled

• Do not create a new WABA.

• Submit an appeal via Meta Business Support.

• Gather and provide necessary documentation (e.g., business license, proof of domain ownership).

• Review and correct any violations of Meta’s Business Messaging Policy.

Following these best practices helps keep your WhatsApp setup secure, stable, and compliant with Meta’s policies.

CRM or custom integrations

If you are syncing Contacts from respond.io to your CRM or custom integrations, prepare to:

• Add a dedicated BSUID field to your CRM. Store BSUID alongside existing identifiers (phone number or email) to map conversations correctly and link history when a phone number isn't available.

• Build logic to handle both phone numbers and BSUIDs as identifiers. Your system should fall back to BSUID when a phone number is not available to match Contacts to the right record.

Contact book for WhatsApp

Meta’s WhatsApp Business Manager includes a contact book for WhatsApp that stores user contact information to support messaging thread continuity. It is enabled by default.

If this feature is turned off, respond.io will not be able to match Contacts who use WhatsApp usernames with their existing Contact records when there's been no interaction within a 30-day window. This will result in duplicate Contact entries being created.

To avoid duplicate Contact entries:

1. Go to Meta Business Suite > Business settings > Business info⁠

2. Confirm contact book for WhatsApp is toggled on.

Learn more about the contact book and 30-day window.

Set up a WhatsApp business username

Meta is gradually rolling out business usernames to selected regions. In the meantime, you can reserve a username now through Meta Business Suite — Meta holds it for your WhatsApp phone number, so no other business can claim it. Your reserved business username (approved by Meta) will become active once the feature is officially available in your region.

WhatsApp business username is an optional feature that gives your business a unique identifier — for example, @YourBusinessName. Your Contacts can use it to find and message your business without needing your phone number.

Business username is different from the display name:

• Your display name doesn’t have to be unique.

• Your username must be unique per phone number. If you have multiple phone numbers, each needs its own username.

Here’s how to reserve a username:

1. Go to Meta Business Suite > Settings.

2. Click WhatsApp Accounts in the left menu.

3. Click the phone number you want to create a username for.

4. Click Phone numbers, then click the pencil icon.

5. Navigate to Username, then click Create.

6. Enter the username you want. You can also choose a username from Suggested.

7. Click Save.

After setting up the business username, both the username and phone number will remain visible on your business profile.

Learn more about business username for WhatsApp in the Meta doc.  

What’s next?

• Get ready to handle inbound conversations on WhatsApp