WhatsApp Integration

WhatsApp is the most popular channel on PalySales. Customers can browse products, ask questions, and place orders directly in a WhatsApp conversation with your AI assistant.

What You'll Need Before Starting

Before you begin the setup wizard, make sure you have:

• A Meta Business Account (free to create)
• A WhatsApp Business Platform app in Meta's developer portal
• A verified phone number for WhatsApp Business
• About 10-15 minutes to complete the setup

You'll collect four pieces of information from Meta during this process:

Setup Wizard (6 Steps)

In the left sidebar, click Settings → Channels. You'll see cards for each available channel. Click the WhatsApp card to open the setup wizard.

Step 1: Introduction

What you'll see: A welcome screen explaining what WhatsApp integration does and listing the requirements.

What to do: Review the requirements checklist, then click Let's Get Started at the bottom.

Step 2: Create Your Meta App

What you'll see: Numbered instructions for creating a Meta Developer app.

What to do:

1. Open Meta for Developers in a new tab
2. Click Create App and choose the Business type
3. Give your app a name (e.g., "My Store WhatsApp")
4. Add the WhatsApp product to your app
5. On the WhatsApp Getting Started page, note your Phone Number ID and Business Account ID

Once you've created your app, click Continue at the bottom.

Step 3: Enter Your Credentials

What you'll see: A form with four fields: Phone Number ID, Business Account ID, Access Token, and App Secret.

What to do:

1. Paste your Phone Number ID into the first field
2. Paste your Business Account ID into the second field
3. For the Access Token: go to your Meta Business Settings → System Users → create a system user (if you don't have one) → click Generate Token → select your WhatsApp app → grant the whatsapp_business_messaging and whatsapp_business_management permissions → copy the token
4. For the App Secret: in your Meta app, go to App Settings → Basic → click Show next to the App Secret → copy it

Important: The token generated on the WhatsApp "Getting Started" page expires in 24 hours. For production use, always generate a permanent token through System Users as described above.

Click Continue. PalySales will validate your credentials and generate a unique webhook verify token for your store.

Step 4: Configure the Webhook in Meta

What you'll see: Two values with copy buttons:

• Callback URL — something like https://app.palysales.com/api/webhooks/whatsapp
• Verify Token — a unique token starting with pv_ followed by random characters

What to do:

1. In your Meta app, go to WhatsApp → Configuration
2. Under Webhook, click Edit
3. Paste the Callback URL into the "Callback URL" field
4. Paste the Verify Token into the "Verify token" field
5. Click Verify and Save — Meta will send a test request to verify the connection
6. After verification succeeds, click the Subscribe toggle next to the messages field

Click Continue in PalySales.

Step 5: Test the Connection

What you'll see: A Test Connection button.

What to do: Click Test Connection. PalySales will call Meta's API to verify your credentials are working. Specifically, it checks:

• That your Access Token is valid
• That your Phone Number ID exists
• That Meta returns your verified business name and phone display

If the test passes, you'll see a green success message with your phone number displayed. If it fails, you'll see a specific error message — check the Troubleshooting section below.

Click Complete to finish.

Step 6: Done!

What you'll see: A success screen confirming WhatsApp is connected.

What to do: Click Go to Inbox to return to the channels page. Your WhatsApp card will now show as Connected with your phone number displayed.

Testing It Out

Send a message to your WhatsApp Business number from a personal phone. Within a few seconds, you should see:

1. The message appear in your Inbox (click Inbox in the left sidebar)
2. An AI-generated response sent back to your phone

If you don't see a response, check the Troubleshooting section.

How WhatsApp Messages Are Processed

Here's what happens when a customer sends you a message:

1. WhatsApp delivers it to your webhook URL (the Callback URL from Step 4)
2. PalySales verifies the signature — every message includes a X-Hub-Signature-256 header. PalySales uses your App Secret to verify this signature matches, confirming the message is genuinely from WhatsApp
3. Your store is identified by matching the Phone Number ID in the message
4. The customer is matched by phone number (automatically normalized to international format). If it's a new customer, a record is created
5. The message is saved with a unique key to prevent duplicates
6. The AI generates a response using your product catalog, knowledge base, and conversation history
7. The response is sent back through WhatsApp

Message Types the AI Can Send

How Media Messages Are Handled

Security

Signature Verification

Every incoming message is verified to prevent fake messages:

1. WhatsApp includes a X-Hub-Signature-256 header with each message
2. PalySales computes a matching signature using your App Secret
3. If they don't match, the message is logged as a security event and silently rejected

PalySales always returns a success response to WhatsApp, even for invalid messages. This prevents WhatsApp from retrying failed deliveries and flooding your webhook.

Per-Store Isolation

• Each store has its own App Secret, Access Token, and Verify Token
• The same Phone Number ID cannot be used by two different stores
• Credentials are masked in the dashboard (only the last few characters are visible)
• Your webhook only processes messages from the environment where you connected it

Troubleshooting

"app_secret not configured"

Your App Secret isn't saved for this store. Go to Settings → Channels, click the WhatsApp card, and re-enter your App Secret from Meta's App Settings → Basic page.

Webhook verification failed in Meta

• Make sure the Verify Token in Meta matches exactly what PalySales shows — copy it again using the copy button
• Make sure the Callback URL is correct and starts with https://
• If you're on a development environment, make sure the URL is publicly accessible

Test Connection failed

• "Invalid access token" — your token may have expired. Generate a new permanent token through System Users
• "Phone number not found" — double-check the Phone Number ID you entered
• "Token appears to be masked" — you need to re-enter the full access token, not the masked version shown in the dashboard

Messages not appearing in Inbox

1. Make sure you subscribed to the messages webhook field in Meta (Step 4)
2. Verify your Access Token hasn't expired (use a permanent System User token)
3. Check that your store's subscription is active (trial or paid plan)
4. Make sure you connected WhatsApp on the same environment you're checking (e.g., if you connected on app.palysales.com, check the inbox there, not on a dev URL)

AI not responding to messages

• In the left sidebar, click AI Assistant and make sure the AI is enabled
• Check that the conversation isn't in Waiting status (handoff mode) — look for a yellow banner in the Inbox
• Verify you haven't exceeded your plan's AI conversation or message limit in Settings → Billing