WhatsApp Business

Overview

WhatsApp Business integration enables your AI agent to communicate with customers through the world's most popular messaging platform. With over 2 billion users globally, WhatsApp provides a familiar and convenient channel for customer support, sales, and engagement.

This integration uses Meta's WhatsApp Business API to provide:

• 24/7 automated customer support through your verified business number
• Handover to human agents when needed
• Rich messaging capabilities including text, images, and interactive elements
• Global reach with end-to-end encryption for secure conversations

---

Prerequisites

Before setting up the WhatsApp integration, ensure you have:

✅ A dedicated phone number for WhatsApp Business

• Must be able to receive SMS or voice calls for verification
• Cannot be registered to any existing WhatsApp account (personal or business)
• Can come from another WhatsApp Business provider. See Move a phone number to another WABA.

✅ Business verification requirements

• Company's legal name and website
• Valid business email address
• SSL-secured website with clear business information

✅ Meta Business Account (or ability to create one)

• Admin access to your Facebook Business Manager
• Authority to grant permissions to third-party apps

✅ Moveo account setup

• An active AI agent configured
• An environment to connect the integration

---

How it works

The WhatsApp Business integration creates a bridge between your customers on WhatsApp and your Moveo AI agent:

1. Customer initiates conversation by messaging your WhatsApp Business number
2. Moveo receives the message through Meta's WhatsApp Business API
3. AI agent processes and responds based on your configured knowledge and dialogs
4. Messages are delivered back to the customer through WhatsApp
5. Handover to human agents when the AI agent determines it's necessary

All conversations maintain WhatsApp's end-to-end encryption and comply with Meta's business messaging policies.

---

Setup guide

Connect WhatsApp Business with the embedded signup. The embedded signup opens a Meta window from the console, and Moveo configures the integration for you.

WhatsApp Business App users

If you want to keep using the WhatsApp Business App on your phone alongside Moveo's AI automation, see WhatsApp coexistence mode. This allows agents to respond directly from the mobile app while keeping messages synced with Human Chat.

Embedded signup

📱 Connect with the embedded signup

Step 1: Prepare your information

Before starting, gather:

• Your phone number for WhatsApp Business
• Company registration details
• Business website URL
• Business email address

Step 2: Start the connection process

1. Navigate to Connections in your Moveo account
2. Select your environment
3. Select Connect on the WhatsApp card
4. On the Connect WhatsApp card, if two-step verification is already on for the phone number, enter its 6-digit PIN in Two-step verification PIN. Leave the field empty for a number without two-step verification.
5. Select Connect to open the Meta signup window

Step 3: Authenticate with Meta

1. Log in to Facebook with your personal or professional account
2. Select Continue as [Your Name]
3. Select Get Started

Step 4: Configure Meta Business Account

Select or create

Create new account

Select existing account

• Existing account: Select from dropdown
• New account: Fill in your company information

Step 5: Set up WhatsApp Business Account

Select or create

Create new account

Select existing account

When selecting your WhatsApp account type, choose WhatsApp Business App if you want to use coexistence mode. This lets human agents respond from the mobile app while the AI agent handles automated conversations on the same number.

Fill in:

• Account Name
• Display Name (shown to customers)
• Business Category

Step 6: Verify your phone number

Insert phone number

Verify phone number

Permissions

Limits

1. Enter your phone number
2. Choose verification method (SMS or voice call)
3. Enter the 6-digit verification code
4. Review permissions and limits
5. Select Finish

Step 7: Activate the integration

1. Return to the integration page in Moveo
2. Wait for Moveo to register the phone number with Meta and subscribe it to messages (usually instant)
3. Turn on the switch on the WhatsApp card at the top of the page, so that the AI agent responds to incoming messages

Setup through the API or the MCP server

The embedded signup runs only in the console, because Meta opens it in the browser of a logged-in user. The console then registers the phone number with Meta, subscribes your WhatsApp Business Account (WABA) to the Moveo app, and saves the access token in the integration. The REST API can create a WhatsApp integration, but only with credentials of your own Meta App. The Moveo MCP server cannot create a WhatsApp integration.

Console

Use the embedded signup. Go to Connections, select the environment, and select Connect on the WhatsApp card. This is the only path that registers the phone number and subscribes the WABA for you.

API

Send POST /v1/desks/{desk_id}/integrations with a manage API key. See Add integration. Set type to whatsapp and put the credentials of your own Meta App in config:

{
  "type": "whatsapp",
  "name": "WhatsApp support",
  "active": true,
  "config": {
    "access_token": "<system user access token>",
    "phone_number_id": "<phone number ID>",
    "page_id": "<the same phone number ID>",
    "waba_id": "<WhatsApp Business Account ID>",
    "verify_token": "<token you choose for the webhook>",
    "app_secret": "<app secret of your Meta App>"
  }
}

• Set page_id to the same value as phone_number_id. Moveo uses page_id to route incoming messages to the integration.
• Moveo does not register the phone number or subscribe the webhook on this path. Do these steps in your Meta App. Contact Moveo support for the callback URL of your integration.
• If access_token or phone_number_id is missing, Moveo marks the integration as having missing credentials. Add them later with Update integration.

MCP

moveo_create_integration accepts only the web and web_voice types. The server lists whatsapp as a dashboard-only type. After the console connects the number, moveo_list_whatsapp_templates reads the approved templates of the integration.

These steps need the console or Meta, on every path:

• The embedded signup and the coexistence connection run in the console.
• Test → Test with Whatsapp runs in the console.
• You create and edit message templates in WhatsApp Manager. Meta reviews each template.

---

Phone numbers and WhatsApp Business accounts

Each WhatsApp integration connects one phone number. A WhatsApp Business Account (WABA) can hold more than one phone number. Each number can connect to a different integration, in the same Moveo account or in another Moveo account.

• Moveo checks the phone number, not the WABA. A phone number connects to one WhatsApp integration only, in all Moveo accounts.
• To connect another number from the same WABA, create another WhatsApp integration. In the Meta window, select the same WABA and the other number.
• An integration stays tied to the WABA that you selected when you connected it. When you reconnect the integration, select the same WABA. For another WABA, the console shows Selected WhatsApp account does not match existing integration.
• When you reconnect and select another number of the same WABA, the console opens Phone number changed. Confirm to connect the new number to the integration.

If another integration already has the phone number, the console stops the connection before Meta registers the number:

Console message	What to do
This WhatsApp number is already connected to another integration. Open it to reauthorize or detach it first.	Select Open existing integration. Reconnect that integration, or delete it and connect the number again.
This WhatsApp number is already connected to a workspace you don't have access to.	Another Moveo account has the number. Contact Moveo support at the email address that the console shows.

Move a phone number to another WABA

To move a phone number to another WABA, move the number in Meta, then connect it to a new Moveo integration. Meta owns the move, and the Meta steps depend on your account:

• In the new WhatsApp account model, you move a number inside one business portfolio when you link and unlink WhatsApp accounts in Meta Business Suite. The number stays connected.
• A number cannot move to another business portfolio.
• Meta does not migrate a number from one provider to another in the new account model. To connect a number that you use with another provider, share its WhatsApp account with Moveo in the embedded signup. The other provider can keep its access.

See Meta: Move numbers within your business and Updates to WhatsApp Business accounts.

To connect the number after the move:

1. Move the number to the destination WABA in Meta.
2. Open the WhatsApp integration that has the number, select Delete integration, and confirm.
3. Create a WhatsApp integration and select Connect, as in the embedded signup.
4. In the Meta window, select the destination WABA and the phone number.
5. Turn on the switch on the WhatsApp card.

To move a number to another Moveo account without a change of WABA, do steps 2 to 5 only. Do step 2 in the old account and steps 3 to 5 in the new account.

Before you move a number, check these points:

• When you delete the integration, Moveo deregisters the phone number from the WhatsApp Cloud API. The number does not send or receive messages through Moveo until you connect it again. For a number in coexistence mode, Moveo does not deregister the number.
• Message templates and the payment method belong to the WABA, not to the phone number. Make sure that the destination WABA has the templates that your AI agent and campaigns use, and an active payment method.
• If two-step verification is on for the number, enter its PIN in Two-step verification PIN before you select Connect.
• If the connection fails, see Migration issues.

---

Configuration options

Business profile customization

Customize how your business appears to customers in WhatsApp:

• Profile picture: Your business logo or avatar
• Business description: Brief description of your services
• Business hours: Operating hours displayed to customers
• Category: Industry classification
• Website: Link to your business website

Access these settings in WhatsApp Manager.

Message templates

WhatsApp requires pre-approved templates for business-initiated conversations:

1. Create templates in WhatsApp Manager
2. Submit for Meta approval (the review can take up to 24 hours)
3. Use approved templates for:
   • Appointment reminders
   • Order updates
   • Account notifications
   • Re-engagement campaigns

Connection status

The Connection card of the integration shows the status of your phone number in Meta:

Field	What it shows
Quality rating	The quality rating of the phone number: High, Medium, Low or Unknown.
Messaging limit	The number of customers that you can message in 24 hours, such as 1K customers per 24 hours, or Unlimited.
Display name	The review status of the display name: Approved, In review, Declined or Expired.
Throughput	The number of messages per second: Standard (80 messages per second) or High (1,000 messages per second).

The card shows only the rows that Meta sends a value for. For example, a phone number without a display name review has no Display name row. When Meta declines the display name or the approval expires, the card shows a warning. Submit a new display name in WhatsApp Manager and wait for the Meta review.

Rate limits and messaging tiers

Meta sets a messaging limit for your business portfolio. The limit is the number of unique customers that you can message outside of a customer service window in a moving 24-hour period. All phone numbers in the business portfolio share the limit. Replies inside an open customer service window are outside this limit.

Limit	How to reach it
250	The start limit of a new business portfolio.
2,000	Verify your business, or send 2,000 messages outside of a service window in 30 days with high-quality templates.
10,000	Meta raises the limit by one level when your quality is high and you used half of the limit in 7 days.
100,000	Same as above.
Unlimited	Same as above.

The Messaging limit row of the Connection card shows your current limit. See Meta: Messaging limits.

---

Testing your integration

Test mode

Before going live, test your AI agent with the WhatsApp number of your environment:

1. Open your AI agent and select Test → Test with Whatsapp
2. Select Add number and add your personal WhatsApp number
3. Scan the QR code and send a message
4. Verify AI agent responses

Test scenarios

Validate these key scenarios:

• ✅ Welcome message and greeting
• ✅ FAQ responses
• ✅ Multi-turn conversations
• ✅ Handover to human agent
• ✅ Media handling (images, documents)
• ✅ Error handling and fallback responses

---

Common use cases

Customer support

• 24/7 automated responses to common queries
• Order status and tracking information
• Technical troubleshooting guides
• Escalation to human agents for complex issues

Sales and lead generation

• Product information and recommendations
• Price quotes and availability checks
• Appointment scheduling
• Lead qualification and routing

Notifications and updates

• Order confirmations and shipping updates
• Appointment reminders
• Account alerts and security notifications
• Marketing campaigns (with user consent)

---

Troubleshooting

Connection issues

Phone number verification fails

• Ensure the number can receive SMS/calls
• Check it's not registered to any WhatsApp account
• Try voice call if SMS doesn't arrive
• Contact Meta support if verification repeatedly fails

Business verification pending

• Review your website for clear business information
• Ensure SSL certificate is valid
• Add privacy policy and terms of service
• Typical approval time: 1-2 business days

Messages not being received

• Verify integration is set to Active
• For an integration that you set up through the API, check the webhook configuration in your Meta App
• Confirm phone number registration is complete
• Review Meta App permissions

Message delivery issues

Customer doesn't receive responses

• Check WhatsApp messaging tier limits
• Verify template approval for business-initiated messages
• Review quality rating in WhatsApp Manager
• Ensure customer hasn't blocked your number

Media files not sending

• Verify file size limits (images: 5 MB, documents: 100 MB)
• Check supported formats (JPEG, PNG, PDF, etc.)
• Ensure proper media URL configuration
• Review Meta's media guidelines

Meta error codes

When Meta rejects a message, Moveo marks the message as failed and stores the Meta error code. In the conversation, the failed message has an error mark. Hover over it to see the error text. A webhook or a campaign log carries the same code.

Code	Error text in Moveo	Cause and fix
131047	Re-engagement message required. More than 24 hours have passed since the recipient last replied.	The 24-hour customer service window is closed. Send an approved template message. In live chat, the composer offers templates after this error.
131053	Unable to upload media	Meta could not get the media file. Moveo sends media to Meta as a link, so Meta downloads the file from your URL. Serve the file from a public HTTPS URL that stays valid, with the correct Content-Type, and in a format that WhatsApp supports.
131052	Unable to download media sent by user	Meta could not give Moveo the file that the customer sent. Ask the customer to send the file again.
131026	Unable to deliver message. The recipient may not have WhatsApp, may not have accepted our Terms of Service, or may be using an outdated version.	The recipient cannot receive the message. See Error 131026 for the full list of causes.
131049	Message not delivered to maintain healthy ecosystem engagement	Meta limits marketing messages per user. Wait at least 24 hours before you send the template again.
131050	User has stopped receiving marketing messages from your business	The customer opted out of marketing messages. Do not send again.
131056	Too many messages sent to this recipient in a short period	You sent too many messages to the same number. Wait, then send again. Moveo does not retry this error.
131051	Unsupported message type	The message type is not supported by WhatsApp. Send a supported type.
132000	The template parameters are missing or invalid	The number of variable values does not match the template. Send a value for each variable.
132001	The template does not exist or is not approved	Check the template name, the language, and the approval status in WhatsApp Manager.
131042	Payment issue with WhatsApp Business Account	Add a valid payment method to the WABA in Meta Business Manager.
131031	Account has been locked	Meta restricted the WABA for a policy violation. Check the account status in WhatsApp Manager.
368	Temporarily blocked for policy violations	Same as 131031.
133010	Phone number not registered	The phone number is not registered on the WhatsApp Business Platform. Connect the number again.
190	Access token has expired	The access token of the integration is no longer valid. Reconnect the integration.
131000	Something went wrong	An unknown Meta error. Moveo retries the send. If the error stays, contact Moveo support.

Moveo retries a send automatically only for rate limit errors (4, 17, 32, 613, 80006, 80007, 130429) and for 131000. See Meta: Error codes.

---

Migration issues

Registration fails with a two-step verification PIN error

• Error message: The two-step verification PIN is missing or does not match the PIN of this phone number.
• Cause: Two-step verification is on for the phone number, and the PIN is empty or wrong.
• Resolution: Enter the correct 6-digit PIN in Two-step verification PIN, and connect again.
• After too many wrong PINs, Meta blocks the registration of the phone number for 72 hours. Try again after that time.

Phone migration blocked by Two-Factor Authentication (2FA)

• Error message: Please ensure two-step authentication is disabled.
• Cause: Two-step verification is enabled on the source WhatsApp Business Account (WABA).
• Resolution:
  • Disable two-step verification in WhatsApp Manager. See Meta: Disabling Two-Step Verification
  • In Moveo, delete the failed integration and reconnect after disabling 2FA

Missing payment method/credit line after migration

• Error message: Your WhatsApp account must have an active credit line in order to send messages after migration.
• Cause: The new or migrated WABA (WhatsApp Business Account) has no active payment method/credit line in Meta Business Manager.
• Resolution:
  • Add a valid payment method to the WABA in Meta Business Manager
  • In Moveo, delete the integration and reconnect once billing is active

Registration fails with a data localization region error

• Error message: Migrated phone number should be first registered with the same data localization region used on the source WABA. Data localization region: 'BR'. The region code changes with the source WABA.
• Cause: The phone number used local storage in a region on its source WABA. Moveo registers the number without a data localization region.
• Resolution: Contact Moveo support, and give the region code from the error message. See Meta: Local storage.

---

Limitations

Platform limitations

• 24-hour messaging window: After 24 hours of customer inactivity, only template messages allowed
• Media restrictions: Limited file types and sizes
• Rate limits: Based on tier and quality rating
• Template approval: Required for business-initiated conversations

Integration constraints

• One phone number per Moveo WhatsApp integration
• One integration per phone number: a phone number can belong to one WhatsApp integration only, in all Moveo accounts. If you connect a number that another integration has, the console shows This WhatsApp number is already connected to another integration. Open it to reauthorize or detach it first.
• Moveo does not limit the number of WhatsApp integrations in an environment. Each integration needs its own phone number.
• One WABA can connect to more than one integration and more than one Moveo account, with a different phone number for each. See Phone numbers and WhatsApp Business accounts.
• Cannot use personal WhatsApp numbers
• Business verification required for higher tiers
• Geographic restrictions in some countries

---

Resources

Official documentation

• WhatsApp Business Platform
• Embedded Signup Errors
• WhatsApp Manager
• Business Verification

Support

• Meta Business Help Center
• WhatsApp Business API Support
• Moveo support: support@moveo.ai

---

Next steps

Once your WhatsApp integration is active:

1. Configure your AI agent with WhatsApp-specific responses
2. Set up message templates for proactive messaging
3. Test thoroughly before promoting your WhatsApp number
4. Monitor analytics to optimize response quality
5. Train your team on handover procedures