← Help center

Connect a WhatsApp sender

Connect your WhatsApp Business number to Yapper to let your AI assistant automatically reply to customers. Yapper uses Meta's embedded signup flow to connect numbers quickly without requiring you to manually generate and paste access tokens.

Prerequisites

Before starting the setup process in the dashboard, make sure you have:

• A Facebook Business account (also known as a Meta Business Account).
• A phone number you control that can receive a verification code via SMS or voice call. This can be a fresh number, or a number you already use in the WhatsApp Business app — that number keeps working in the app after connecting, and Yapper imports its contacts and chat history. A number tied to a personal WhatsApp account must be released from it first.

Connecting a Number

To connect your number:

1. Navigate to Admin → Connections in the dashboard.
2. Click Connect WhatsApp Account.
3. Log in to Facebook in the popup window and select the Meta Business Account you want to use.
4. Select or create your WhatsApp Business Account and choose the phone number you wish to connect.
5. Verify the phone number by entering the verification code sent to you.

Once connected, the phone number is imported as an active sender (see senders). If your WhatsApp Business Account has multiple phone numbers, Yapper automatically imports the additional numbers as separate senders.

Playbook Association

Every sender must be linked to a playbook, which contains the instructions and reply settings for your assistant.

• Existing setups: If you are importing an additional number on a WhatsApp Business Account that is already connected, it automatically reuses the existing playbook.
• New setups: For a newly connected WhatsApp account, Yapper creates a default playbook. The dashboard will show a "Join an existing playbook?" option if you want to reuse an existing playbook from your account instead.
• Reconnecting numbers: If you reconnect or re-onboard a number, Yapper automatically carries over your assistant's customized settings—such as prompt instructions, message examples, and the selected AI model—from the prior playbook.

Contact and Message Sync

If you connected a number that stays on the WhatsApp Business app, Yapper begins syncing that app's contacts and message history in the background right after connecting.

• Status Card: You can monitor the sync status under Admin → Connections. The dashboard displays separate rows for contacts and history, and each can finish independently.
• Partial Sync: If you did not enable history sharing during the Meta signup flow, the history row shows "not shared" instead of failed. If a sync fails or hits Meta's processing deadline, it is marked as failed, with a retry option where possible.
• Sync Summary: Once the sync is complete, a summary card shows the total synced contacts (including new and removed contacts) and total synced messages (along with the number of distinct conversations). This summary remains accessible in the sender's settings page.

Importing New Numbers

If you add new phone numbers to your WhatsApp Business Account in the Meta Business Manager later, you can import them to Yapper. Select the connected WhatsApp account in Admin → Connections and click the option to sync and import new phone numbers.

Disconnected and Disabled Senders

A WhatsApp sender may become disconnected due to Meta-side events (such as removing the integration from Facebook or account suspension).

• What Happens: When a connection is disabled, the sender is marked as disconnected in the dashboard. Yapper automatically blocks all outbound messages from this sender, including manual responses, bulk templates (see whatsapp-templates), scheduled messages, and auto-replies. Trying to send a message manually will return a connection disabled error.
• How to Fix: The most reliable way to restore a disabled connection is to click the reconnect option in the dashboard to re-authorize the integration via Meta's signup flow.
• Account Blocks: If Meta restricts or blocks your WhatsApp account, see whatsapp-account-blocks.
• Troubleshooting: For troubleshooting a sender that is not responding, see sender-not-replying.

Customer Identity and Username Changes

WhatsApp customers are usually identified by their phone numbers, but they may also use usernames or opaque identifiers provided by Meta.

• Seamless Threads: Yapper automatically handles both types of identifiers. If a customer changes their phone number or adopts a username, Yapper links the new identifier to the existing customer profile so that all messages land in the same conversation thread in your Inbox.
• Inactive Conversations: If a conversation has been inactive for more than 30 days, Meta may stop sending the customer's phone number in new message webhooks. If the conversation previously had both a phone number and an opaque identifier linked, Yapper continues to route the messages to the correct thread.