← 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 → Senders 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.

Connecting takes up to a couple of minutes while Yapper finishes the setup with Meta. Keep the page open until it confirms.

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.

Defaults for New Senders

Above the connection options in Admin → Senders, a Defaults for new senders row lets you pick a Timezone and a Playbook before connecting. These apply to any new sender created by a connection — WhatsApp, Instagram, Messenger, or web chat — so set them once before you connect.

• Timezone sets each new sender's default timezone, which affects when scheduled and time-aware messages are sent. You can change it per sender afterward in the sender's settings.
• Playbook lets you either create a new playbook or attach the new senders to one you already have. Reconnecting an existing sender keeps its playbook. A reconnected Instagram or Messenger sender also keeps its timezone; a reconnected WhatsApp number takes the selected timezone.

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.

If the Connection Fails

If Yapper cannot finish the setup with Meta, the dashboard shows an error message explaining why, and refreshes the sender list.

• What to do: Click Connect WhatsApp Account again and go through Meta's signup flow once more. Yapper picks up where it left off, so you do not need to remove anything first.
• A sender already appears in the list: Part of the setup may have completed before the failure. Reconnecting the same number finishes it and keeps that sender and its playbook; its timezone becomes the one selected under Defaults for new senders.
• PIN mismatch: If the message says the two-step verification PIN does not match Meta's record, the number was registered earlier with a different PIN. Reset the PIN in WhatsApp Manager (Meta applies a 7-day waiting period), then connect again.
• "Couldn't confirm the WhatsApp connection": The dashboard lost contact while waiting. Check the sender list in Admin → Senders before trying again — the connection may have completed.

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 → Senders. 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 → Senders 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.