WhatsApp Business Integration

Connect WhatsApp Business to receive customer messages as feedback and reply directly from your dashboard.

How It Works

1. A customer sends a message to your WhatsApp Business number
2. The message appears in your UserHero dashboard as feedback
3. Follow-up messages within 15 minutes are grouped into the same conversation thread
4. Your team can reply from the Customer Thread — the reply is delivered via WhatsApp

Prerequisites

Before connecting, you need:

• A Meta Business Account with Business Verification completed
• A WhatsApp Business Account (WABA) — created during setup if you don't have one
• A phone number to use with WhatsApp Business (cannot be registered on regular WhatsApp)
• Your phone number's display name must be approved by Meta — check the status in WhatsApp Manager > Phone Numbers. Approval is usually automatic but can take up to 24 hours.

Setup

Step 1: Connect WhatsApp

1. Go to Workspace Settings → Integrations
2. Find WhatsApp Business and click "Connect WhatsApp"
3. You'll be redirected to Meta's Embedded Signup flow
4. Log in with your Meta Business account
5. Select or create a WhatsApp Business Account
6. Select or register a phone number
7. Click "Continue" to complete the connection

Step 2: Assign a Project

After connecting:

1. Go to your project Settings → Integrations
2. In the WhatsApp section, select the connected WhatsApp number
3. Save — incoming messages from this number will now create feedback in this project

Step 3: Verify the Connection

Send a test message to your WhatsApp Business number from a personal phone. You should see it appear as new feedback in your dashboard within seconds.

Receiving Messages

Text Messages

Text messages create feedback items with:

• The message content
• Sender's WhatsApp name and phone number
• A "WhatsApp" source badge on the feedback card
• Customer Thread automatically enabled

Media Messages

Supported media types are automatically downloaded and attached to the feedback:

Conversation Grouping

When a customer sends multiple messages within 15 minutes, they are grouped into the same feedback thread. This prevents inbox clutter from rapid messages.

After 15 minutes of inactivity, the next message creates a new feedback item.

Replying to Customers

You can reply to WhatsApp customers directly from the Customer Thread:

1. Open a WhatsApp feedback item
2. In the Customer Thread, type your reply
3. Click the green "Send via WhatsApp" button
4. The customer receives your reply on WhatsApp

Sending Attachments

You can attach media to your replies:

• Images (JPEG, PNG)
• Videos (MP4)
• Audio files

Attachments are sent as separate WhatsApp messages after the text reply.

Token Management

WhatsApp access tokens expire after 60 days. UserHero automatically manages token refresh:

• Tokens are checked daily
• Tokens within 7 days of expiry are automatically refreshed
• If a token cannot be refreshed, the connection is marked as disconnected and the workspace owner is notified via email
• To reconnect, go to Workspace Settings and click "Connect WhatsApp" again

Disconnection

A WhatsApp connection may be disconnected if:

• The access token expires and cannot be refreshed
• The workspace is downgraded to a plan that does not include WhatsApp
• The connection is manually disconnected from Workspace Settings

When disconnected, incoming messages are no longer processed. Previous feedback and conversations are preserved.

Plan Requirements

Troubleshooting

Connection stalls or times out

Make sure you complete all steps in the Meta popup (select a business account, choose a phone number, and click Finish). If the popup closes without finishing, try again.

"Display name needs approval" error

Your phone number's display name hasn't been approved by Meta yet. Check the status in WhatsApp Manager > Phone Numbers. Approval is usually automatic but can take up to 24 hours.

Messages not appearing

• Verify the connection status is Active in Workspace Settings
• Check that a project is assigned to the WhatsApp number
• Ensure your Meta Business Verification is completed

Replies not delivered

• Check that the reply is within the 24-hour customer service window
• Verify the connection status is Active
• Check the browser console for error details

Connection disconnected unexpectedly

• The access token may have expired — reconnect from Workspace Settings
• Your plan may have been downgraded — upgrade to Pro or Pro Max