WhatsApp Configuration
Connect your WhatsApp Business API to start accepting bookings via WhatsApp. This comprehensive guide walks you through the entire setup process, from creating a Meta Developer account to configuring webhooks and testing your integration. WhatsApp is the most popular booking channel, so proper setup is essential for maximizing your booking potential.
Prerequisites
Before you begin the WhatsApp Business API setup, ensure you have the following prerequisites:
- Meta Developer Account: Create a free account at developers.facebook.com. You'll need a Facebook account to sign up. Complete the developer verification process which may require providing business information and identity verification.
- WhatsApp Business API Account: Access to WhatsApp Business API through Meta. This requires business verification if you're using the official API. Alternatively, you can use a Business Solution Provider (BSP) that handles the API access for you.
- Verified WhatsApp Business Phone Number: A phone number that can receive SMS for verification. This number will become your WhatsApp Business number. It should be a dedicated business number, not a personal number. The number must be able to receive verification codes via SMS or voice call.
- Access to Meta Developer Console: Full access to your Meta Developer Console where you'll configure apps, manage API credentials, and set up webhooks.
- Business Verification: For production use, Meta requires business verification. This involves providing business documents, proof of business operations, and may take several days to weeks for approval.
- Domain Verification: You may need to verify domain ownership for webhook setup, depending on your configuration.
Important Note: Setting up WhatsApp Business API requires approval from Meta and can take anywhere from a few days to several weeks, depending on your business verification status and the completeness of your application. Start the process early to avoid delays in going live.
Tip: If you need to get started quickly, consider using a Business Solution Provider (BSP) that can expedite the setup process. However, direct API access through Meta provides more control and lower costs at scale.
Step-by-Step Setup
1
Create Meta Developer Account
Create your Meta Developer account to access the WhatsApp Business API:
- Visit developers.facebook.com and click "Get Started" or "Log In"
- Sign up or log in with your Facebook account (use a business Facebook account if possible, as personal accounts may have limitations)
- Complete the developer verification process:
- Accept Meta's Developer Terms and Policies
- Provide your contact information and business details
- Complete identity verification (may require phone number or ID verification)
- Set up two-factor authentication for security
- Create a new app or use an existing one:
- Click "Create App" in the Developer Console
- Select "Business" as the app type (or "Other" if Business isn't available)
- Enter your app name (e.g., "Your Business Name - WhatsApp Booking")
- Enter your contact email
- Select your app's purpose (typically "Customer Communication" or "Business Management")
Tip: Use a descriptive app name that includes your business name. This helps with organization if you manage multiple apps or integrations.
2
Set Up WhatsApp Business API
Set up WhatsApp Business API in your Meta Developer Console:
- In Meta Developer Console, add WhatsApp product to your app:
- Navigate to your app's dashboard
- Click "Add Product" or find "WhatsApp" in the products list
- Click "Set Up" next to WhatsApp
- Follow the initial setup prompts
- Complete the WhatsApp Business API setup wizard:
- Select your use case (typically "Customer Service" or "Notifications")
- Choose your WhatsApp Business Account (create one if you don't have one)
- Review and accept WhatsApp Business API terms
- Complete any required business information forms
- Verify your business (if required by Meta):
- This step is required for production use and higher message volumes
- Submit business verification documents (business license, tax ID, etc.)
- Provide business information and website
- Wait for Meta's review (can take several days to weeks)
- You can test with limited functionality while verification is pending
- Get your phone number approved for WhatsApp Business:
- Add a phone number in the WhatsApp → Phone Numbers section
- Choose a number (you can use an existing number or request a new one)
- Verify the number via SMS or voice call
- Wait for number approval (usually instant for test numbers, longer for production)
- Note down your important IDs (you'll need these for Pitstop configuration):
- Phone Number ID: Found in WhatsApp → Phone Numbers → Your Number (usually a long numeric ID)
- Business Account ID: Found in WhatsApp → Overview or Business Settings (also called WABA ID)
- App ID: Your app's ID (found in App Dashboard → Settings → Basic)
Important: Keep these IDs secure. You'll need them in the next steps to configure Pitstop. Screenshot or copy them to a secure location.
3
Get API Credentials
Collect all required API credentials from Meta Developer Console. You'll need these to configure Pitstop:
- Access Token:
- Navigate to WhatsApp → API Setup in Meta Developer Console
- Find your "Temporary Access Token" (for testing) or generate a "Permanent Access Token" (for production)
- For production, create a System User and generate a token with WhatsApp permissions
- Copy the token (it starts with a long string of characters)
- Note: Temporary tokens expire in 24 hours. For production, use permanent tokens or implement token refresh
- Phone Number ID:
- Found in WhatsApp → Phone Numbers → Your Number
- It's a long numeric ID (not your actual phone number)
- Copy this ID exactly as shown
- Business Account ID (WABA ID):
- Found in WhatsApp → Overview or Business Settings
- Also called WhatsApp Business Account ID or WABA ID
- Another long numeric ID
- App Secret:
- Found in App Dashboard → Settings → Basic
- Click "Show" next to App Secret (you may need to enter your password)
- Copy the secret key
- Important: This is sensitive - never expose it in client-side code
- Webhook Verify Token:
- Create a secure, random token for webhook verification
- Use a strong random string (at least 32 characters)
- You can generate one using:
openssl rand -hex 32or any secure random generator - Save this token - you'll use it in both Meta and Pitstop configuration
- This token verifies that webhook requests are coming from Meta
Security Warning: Keep these credentials secure and never share them publicly. Treat them like passwords. If compromised, regenerate them immediately. Use environment variables or secure credential storage, never commit them to version control.
Best Practice: For production, use Meta's System User tokens which are more secure and don't expire. Set up proper token rotation and monitoring for security.
4
Configure Webhook in Meta
Set up the webhook in Meta Developer Console to enable two-way communication. The webhook allows Meta to send incoming messages to Pitstop and enables real-time message delivery:
- Navigate to Webhook Configuration: Go to WhatsApp → Configuration in Meta Developer Console. You'll see the Webhook section with current settings.
- Edit Webhook Settings: Click "Edit" or "Set Up" next to the Webhook section. This opens the webhook configuration dialog.
- Enter Webhook URL:
- Copy the webhook URL from your Pitstop dashboard (Settings → WhatsApp → Webhook URL)
- Paste it into the "Callback URL" field in Meta
- Ensure the URL is exactly as shown (must be HTTPS, not HTTP)
- The URL should look like:
https://your-domain.com/api/webhooks/whatsapp
- Enter Verify Token:
- Enter the webhook verify token you created in step 3
- This must match exactly what you'll enter in Pitstop
- The token is case-sensitive, so copy it exactly
- Verify Webhook: Click "Verify and Save" button. Meta will send a verification request to your webhook URL:
- If verification succeeds, you'll see a green checkmark
- If it fails, check that your webhook URL is accessible and the verify token matches
- Common issues: incorrect URL, token mismatch, or webhook endpoint not responding correctly
- Subscribe to Webhook Fields: After verification, subscribe to the required webhook fields:
- messages - Required for receiving incoming messages from customers
- message_status - Optional but recommended to track message delivery status
- Click the checkboxes next to each field you want to subscribe to
- Click "Save" to apply subscriptions
Tip: The webhook URL and verify token are shown in your Pitstop dashboard under Settings → WhatsApp. Copy them exactly as displayed. If webhook verification fails, double-check that both the URL and token match exactly in both Meta and Pitstop.
Important: Your webhook URL must be publicly accessible over HTTPS. Meta cannot reach private IP addresses or localhost URLs. If you're testing locally, use a tunneling service like ngrok, but switch to your production URL before going live.
5
Add WhatsApp Number in Pitstop
Connect your WhatsApp number in the Pitstop dashboard to complete the integration. This links your Meta WhatsApp Business API account with your Pitstop account:
- Navigate to WhatsApp Settings: Go to Settings → WhatsApp or Integrations → WhatsApp in your Pitstop dashboard. You'll see the WhatsApp configuration page.
- Add WhatsApp Number: Click Add WhatsApp Number or Connect WhatsApp button. This opens the configuration form.
- Enter API Credentials: Fill in all required fields with the credentials you collected from Meta:
- Phone Number ID: Paste the Phone Number ID from Meta (the long numeric ID, not your actual phone number). This identifies which WhatsApp Business number to use.
- Business Account ID (WABA ID): Enter your WhatsApp Business Account ID. This links to your Meta business account.
- Access Token: Paste your access token. For production, use a permanent System User token. Temporary tokens expire in 24 hours.
- App Secret: Enter your app secret from Meta. This is used for webhook verification and security.
- Webhook Verify Token: Enter the verify token you created earlier. This must match exactly what you entered in Meta's webhook configuration.
- Enter Phone Number: Enter your WhatsApp Business phone number in international format:
- Include country code (e.g., +1 for US, +44 for UK)
- Format:
+[country code][number](e.g., +1234567890, +447911123456) - No spaces, dashes, or parentheses
- This is the number customers will message to book appointments
- Configure Webhook URL: The webhook URL is automatically generated by Pitstop. Copy this URL - you'll need it for Meta webhook configuration (step 4). The URL is unique to your account and secure.
- Test Connection: Click Test Connection or Verify to check if your credentials are correct:
- Pitstop will attempt to connect to Meta's API
- If successful, you'll see a green success message
- If it fails, check each credential carefully for typos or incorrect values
- Save Configuration: Once the connection test succeeds, click Save or Connect. Your WhatsApp number is now connected to Pitstop.
Security Note: All credentials are encrypted and stored securely. Never share these credentials or commit them to version control. If you suspect credentials are compromised, regenerate them in Meta and update Pitstop immediately.
Best Practice: After saving, verify the connection status shows "Connected" in green. If it shows "Disconnected" or an error, review the troubleshooting section or contact support.
6
Verify Connection
Test that everything is working correctly. Comprehensive testing ensures your WhatsApp integration is fully functional before going live:
- Test Incoming Messages:
- Send a test message from your personal WhatsApp to your WhatsApp Business number
- Wait a few seconds for the message to be received
- Check your Pitstop dashboard → Conversations or Messages section
- The message should appear within 5-10 seconds
- If it doesn't appear, check webhook configuration and connection status
- Verify AI Assistant Response:
- If your AI assistant is configured, it should automatically respond to your test message
- Check that the response appears in WhatsApp within a few seconds
- Test with a simple question like "What are your business hours?" or "Can I book an appointment?"
- Verify the AI's response is accurate and helpful
- If the AI doesn't respond, check AI assistant configuration and knowledge base setup
- Test Outgoing Messages:
- Go to the conversation in your Pitstop dashboard
- Type a test message and click Send
- Check that the message appears in WhatsApp on your phone
- Verify message delivery status shows as "delivered" or "read"
- If messages aren't sending, check access token validity and rate limits
- Test Booking Flow:
- Send a booking request message like "I'd like to book a haircut tomorrow at 2pm"
- Follow the AI assistant's prompts to complete a test booking
- Verify the booking appears in your dashboard → Bookings
- Check that confirmation message is sent to WhatsApp
- This end-to-end test ensures the complete booking flow works
- Check Connection Status:
- Go to Settings → WhatsApp in your dashboard
- Verify connection status shows "Connected" in green
- Check "Last Message Received" timestamp to confirm recent activity
- Review any error messages or warnings displayed
- If status shows "Disconnected", review credentials and webhook configuration
- Test Message Templates (if using):
- If you're using message templates for outbound messages, test template delivery
- Verify templates are approved in Meta Developer Console
- Test template message sending from dashboard
- Check that template variables are correctly populated
- Monitor Webhook Activity:
- Check webhook delivery logs in Meta Developer Console
- Verify webhook requests are being received successfully (200 status codes)
- Check for any webhook errors or failures
- Review Pitstop dashboard logs for any processing errors
Success! If messages are flowing both ways, the AI assistant is responding correctly, and bookings can be created, your WhatsApp integration is complete and ready for production use. You can now start accepting bookings via WhatsApp!
Ongoing Monitoring: Regularly check connection status and message delivery. Set up alerts for connection issues or message delivery failures. Monitor webhook logs weekly to ensure everything continues working smoothly.
Message Templates & Rate Limits
Message Templates
For messages sent outside the 24-hour customer-initiated conversation window, you must use approved message templates. Templates ensure compliance with WhatsApp's policies and enable proactive customer communication:
- Template Requirements:
- Templates must be approved by Meta before use
- Each template has a specific purpose (notifications, reminders, confirmations)
- Templates can include variables for personalization (customer name, appointment time, etc.)
- Template approval typically takes 24-48 hours
- Rejected templates include specific reasons for rejection
- Creating Templates:
- Go to Meta Developer Console → WhatsApp → Message Templates
- Click "Create Template" and select template category
- Write template content following WhatsApp's guidelines
- Add variables for dynamic content (e.g., {{1}} for customer name)
- Submit template for approval
- Wait for approval before using the template
- Template Best Practices:
- Keep templates clear, concise, and professional
- Include all necessary information (date, time, location, etc.)
- Use variables appropriately for personalization
- Avoid promotional language unless using marketing templates
- Test templates with sample data before submitting
- Review and update templates regularly
- Common Template Types:
- Booking Confirmations: Confirm new bookings with all details
- Reminders: Send appointment reminders (configurable: 1, 2, or 3 hours before)
- Rescheduling Notifications: Notify customers of appointment changes
- Cancellation Confirmations: Confirm booking cancellations
- Follow-up Messages: Send post-appointment follow-ups
Rate Limits & Usage
Understanding rate limits helps you manage message volume and avoid delivery issues:
- Conversation Limits:
- Free Tier: 1,000 conversations per month (a conversation is a 24-hour messaging window)
- Check your current usage in Meta Business Manager → WhatsApp → Analytics
- If exceeded, wait for monthly reset or upgrade to paid tier
- Plan message volume to stay within limits
- Per-Second Rate Limits:
- Typically 80 messages per second for approved businesses
- Lower limits for new or unverified accounts
- Rate limits increase with business verification and good standing
- Monitor rate limit errors and adjust sending patterns if needed
- 24-Hour Messaging Window:
- After a customer messages you, you have 24 hours to send free-form messages
- After 24 hours, you can only send approved template messages
- This window resets when the customer messages you again
- Use this window effectively for customer service and follow-ups
- Managing Rate Limits:
- Monitor usage regularly to avoid hitting limits
- Prioritize important messages if approaching limits
- Upgrade your Meta plan if you consistently exceed limits
- Implement message queuing for high-volume periods
- Use templates efficiently to maximize message delivery
Security Best Practices
Security is critical when working with API credentials and webhooks. Follow these best practices to protect your WhatsApp integration:
- Keep Credentials Secure:
- Never share your access tokens, app secrets, or verify tokens publicly
- Don't commit credentials to version control (Git repositories)
- Use environment variables or secure credential management systems
- Only share credentials with trusted team members who need access
- If credentials are exposed, regenerate them immediately in Meta
- Use Strong Verify Tokens:
- Create a long, random webhook verify token (minimum 32 characters, recommended 64+)
- Use cryptographically secure random generators (not predictable patterns)
- Include a mix of letters, numbers, and special characters
- Store the token securely - you'll need it in both Meta and Pitstop
- Regenerate tokens periodically (every 6-12 months) for additional security
- Regular Token Rotation:
- Rotate access tokens periodically (every 90 days recommended for production)
- Use Meta's System User tokens which are more secure than temporary tokens
- Implement token rotation procedures before tokens expire
- Update tokens in Pitstop immediately after regenerating in Meta
- Monitor token expiration dates and set reminders
- Monitor Access:
- Regularly check your Meta Developer Console for unauthorized access or suspicious activity
- Review access logs and API usage patterns
- Set up alerts for unusual activity (unexpected API calls, new IP addresses)
- Enable two-factor authentication on your Meta Developer account
- Review team member access permissions regularly and remove access for former employees
- Webhook Security:
- Always use HTTPS for webhook URLs (never HTTP)
- Ensure your webhook endpoint validates the verify token on every request
- Implement rate limiting on webhook endpoints to prevent abuse
- Validate webhook signatures if available (Meta provides signature verification)
- Monitor webhook logs for suspicious or unexpected requests
- Network Security:
- Use secure networks when accessing Meta Developer Console
- Avoid public Wi-Fi when managing credentials
- Use VPN for additional security when working remotely
- Ensure your webhook server has proper firewall rules and security measures
- Credential Storage:
- Use encrypted storage for credentials (Pitstop handles this automatically)
- Never store credentials in plain text files or documents
- Use password managers for team credential sharing if needed
- Implement principle of least privilege - only grant access to those who need it
Important: If you suspect your credentials have been compromised, immediately regenerate all tokens and secrets in Meta Developer Console, update them in Pitstop, and review recent API activity for any unauthorized usage.
Troubleshooting
Common Issues
Webhook Verification Fails
Common Causes and Solutions:
- Incorrect Webhook URL: Verify the webhook URL is exactly as shown in your Pitstop dashboard. Check for typos, missing characters, or incorrect protocol (must be HTTPS). Copy and paste the URL directly rather than typing it manually.
- Verify Token Mismatch: The verify token must match exactly in both Meta and Pitstop. It's case-sensitive, so ensure capitalization matches. Copy the token from one place and paste it in the other to avoid typing errors.
- HTTPS Required: Ensure your webhook endpoint is using HTTPS, not HTTP. Meta requires secure connections. If testing locally, use ngrok or similar tunneling service with HTTPS.
- Webhook Endpoint Not Accessible: Verify your webhook URL is publicly accessible. Meta cannot reach private IP addresses (192.168.x.x, 10.x.x.x) or localhost. Test the URL in a browser to ensure it's reachable.
- SSL Certificate Issues: Ensure your webhook endpoint has a valid SSL certificate. Self-signed certificates or expired certificates will cause verification to fail. Use a trusted certificate authority.
- Webhook Endpoint Not Responding: Your webhook endpoint must respond correctly to Meta's verification challenge. Check server logs to see if requests are being received. The endpoint should return the verify token in the response during verification.
- Connection Status: Check the connection status in your Pitstop dashboard. If it shows "Disconnected" or an error, review the error message for specific guidance.
Debugging Steps: Use Meta's webhook testing tool in Developer Console to send test events. Check your server logs for incoming webhook requests. Verify your webhook endpoint is handling GET requests for verification and POST requests for messages.
Messages Not Received
Common Causes and Solutions:
- Webhook Not Subscribed: Verify webhook is subscribed to "messages" field in Meta Developer Console. Go to WhatsApp → Configuration → Webhook and ensure "messages" checkbox is checked. Without this subscription, you won't receive incoming messages.
- Webhook Status Issues: Check webhook status in Meta Developer Console. It should show as "Verified" with a green checkmark. If it shows errors, review the error details and fix the underlying issue.
- Phone Number Not Approved: Verify your phone number is approved for WhatsApp Business in Meta. Go to WhatsApp → Phone Numbers and check the status. Test numbers work immediately, but production numbers may require approval.
- Connection Status: Check connection status in your Pitstop dashboard (Settings → WhatsApp). It should show "Connected" in green. If disconnected, review credentials and webhook configuration.
- Webhook Delivery Failures: Check webhook delivery logs in Meta Developer Console. Look for failed deliveries (non-200 status codes). Common causes: server downtime, rate limiting, or webhook endpoint errors.
- Message Outside 24-Hour Window: If customers haven't messaged you in the last 24 hours, you can only send template messages. Customers need to initiate conversation first, then you have 24 hours to respond with free-form messages.
- Rate Limiting: Check if you've exceeded Meta's rate limits. Free tier allows 1,000 conversations per month. If exceeded, wait for monthly reset or upgrade your plan.
- Account Restrictions: Verify your WhatsApp Business account isn't restricted or suspended. Check Meta Business Manager for any policy violations or account warnings.
Debugging Steps: Send a test message from your personal WhatsApp to your business number. Check Meta's webhook logs to see if the message event was sent. Review Pitstop dashboard logs for any processing errors. Verify webhook endpoint is receiving and processing requests correctly.
Messages Not Sending
Common Causes and Solutions:
- Expired Access Token: Verify access token is valid and not expired. Temporary tokens expire in 24 hours. Check token expiration in Meta Developer Console. For production, use System User tokens which don't expire. Regenerate and update token in Pitstop if expired.
- Rate Limits Exceeded: Check rate limits in Meta Developer Console (WhatsApp → Analytics). Free tier: 1,000 conversations/month. Per-second limits: typically 80 messages/second for approved businesses. If exceeded, wait for reset or upgrade plan. Monitor usage to avoid hitting limits.
- Incorrect Phone Number ID: Ensure phone number ID is correct. It's a long numeric ID, not your actual phone number. Verify it matches what's shown in Meta Developer Console (WhatsApp → Phone Numbers).
- Business Account Inactive: Verify business account is active and not restricted. Check Meta Business Manager for account status. Ensure business verification is complete if required for your message volume.
- Message Template Issues: For messages outside 24-hour window, you must use approved message templates. Verify templates are approved in Meta. Check template format compliance and variable correctness. Review rejected templates for specific errors.
- Invalid Phone Number Format: Ensure recipient phone numbers are in international format (e.g., +1234567890) with country code. No spaces, dashes, or parentheses. Invalid formats will cause send failures.
- Message Content Violations: Ensure messages comply with WhatsApp's content policies. No spam, prohibited content, or policy violations. Review error messages for specific content issues.
- Message Length Limits: Text messages limited to 1,600 characters. If longer, split into multiple messages or use media messages. Check message length before sending.
- Media URL Issues: If sending media (images, documents), ensure URLs are publicly accessible and properly formatted. Media must be hosted on accessible servers with valid URLs.
Debugging Steps: Check message delivery status in Pitstop dashboard. Review error messages for specific failure reasons. Test with a simple text message first to isolate the issue. Verify API credentials are correct and account is in good standing. Check Meta's status page for any service outages.
Still having issues? Check our Troubleshooting guide or contact support.