WhatsApp Business API
Integration Guide

📋 Overview

LeadSoras CRM integrates with WhatsApp Business through the Evolution API — an open-source gateway that connects to WhatsApp Web (via the Baileys library) or the official Meta WhatsApp Business API. This guide covers both approaches:

• Option A — QR Code (WhatsApp Web): Quick setup using QR code scanning. Best for small teams (up to ~1,000 messages/day). No Meta Business verification required.
• Option B — Meta Business API (Official): Full enterprise integration through Meta's Cloud API. Supports high-volume messaging, verified business profiles, and message templates. Requires Meta Business verification.

Architecture Diagram

✅ Prerequisites

Before starting, make sure you have the following:

🏢 Step 1 — Create a Meta Business Account

A Meta Business Account is required to access the WhatsApp Business API. Follow these steps:

📱 Step 2 — Create a Meta App

💬 Step 3 — Add WhatsApp Product

📞 Step 4 — Register Your Phone Number

For Option A (QR Code — WhatsApp Web)

No registration needed. You'll simply scan a QR code with your WhatsApp phone. The number can be your existing personal or business WhatsApp number.

For Option B (Meta Business API)

🔑 Step 5 — Generate Permanent Access Token

The temporary token from the API Setup page expires in 24 hours. For production use, you need a permanent (System User) access token.

# Add to your backend .env file
META_PERMANENT_ACCESS_TOKEN=EAAxxxxxxxxxxxxxxxxxxxxxxx

🚀 Step 6 — Install Evolution API

Evolution API is the middleware that connects LeadSoras CRM to WhatsApp. It handles session management, message queuing, and webhook delivery.

Option 1 — Docker (Recommended)

# Pull the latest Evolution API image
docker pull atendai/evolution-api:latest

# Create and run the container
docker run -d \
  --name evolution-api \
  -p 8080:8080 \
  -e AUTHENTICATION_API_KEY=YOUR_EVOLUTION_API_KEY \
  -e SERVER_URL=https://your-domain.com \
  -v evolution_data:/evolution/instances \
  atendai/evolution-api:latest

Option 2 — Docker Compose

Create a docker-compose.yml file:

version: '3.8'

services:
  evolution-api:
    image: atendai/evolution-api:latest
    container_name: evolution-api
    restart: always
    ports:
      - "8080:8080"
    environment:
      # Authentication
      - AUTHENTICATION_API_KEY=YOUR_SECURE_API_KEY_HERE
      # Server
      - SERVER_URL=https://your-domain.com
      - SERVER_PORT=8080
      # Database (optional - for persistence)
      - DATABASE_ENABLED=true
      - DATABASE_PROVIDER=postgresql
      - DATABASE_CONNECTION_URI=postgresql://user:pass@host:5432/evolution
      # Webhook (for CRM integration)
      - WEBHOOK_GLOBAL_ENABLED=true
      - WEBHOOK_GLOBAL_URL=https://your-crm-backend.com/api/webhooks/evolution
      - WEBHOOK_GLOBAL_WEBHOOK_BY_EVENTS=true
      - WEBHOOK_EVENTS_MESSAGES_UPSERT=true
      - WEBHOOK_EVENTS_MESSAGES_UPDATE=true
      - WEBHOOK_EVENTS_CONNECTION_UPDATE=true
    volumes:
      - evolution_data:/evolution/instances

volumes:
  evolution_data:

Then run:

docker compose up -d

Option 3 — Railway / Cloud Deployment

ngrok http 8080

⚙️ Step 7 — Configure Evolution API

Create a WhatsApp Instance

After deploying Evolution API, create an instance to connect your WhatsApp number:

curl -X POST 'https://your-evolution-api.com/instance/create' \
  -H 'apikey: YOUR_EVOLUTION_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "instanceName": "LeadSoras",
    "integration": "WHATSAPP-BAILEYS",
    "qrcode": true,
    "webhook": {
      "url": "https://your-crm-backend.com/api/webhooks/evolution",
      "byEvents": true,
      "events": [
        "MESSAGES_UPSERT",
        "MESSAGES_UPDATE",
        "CONNECTION_UPDATE"
      ]
    }
  }'

Verify the Instance

curl -X GET 'https://your-evolution-api.com/instance/connectionState/LeadSoras' \
  -H 'apikey: YOUR_EVOLUTION_API_KEY'

Expected response:

{
  "instance": {
    "instanceName": "LeadSoras",
    "state": "open"
  }
}

Environment Variables Reference

🔗 Step 8 — Connect Evolution API to LeadSoras CRM

Option A: Configure via CRM Dashboard (Recommended)

Option B: Configure via Environment Variables

You can also configure the connection through your backend .env file:

# WhatsApp (Evolution API) Configuration
EVOLUTION_API_URL=https://your-evolution-api.com
EVOLUTION_API_KEY=YOUR_EVOLUTION_API_KEY
EVOLUTION_INSTANCE_NAME=LeadSoras

🪝 Step 9 — Configure Webhooks

Webhooks allow the CRM to receive real-time updates from WhatsApp — including incoming messages, delivery receipts, and connection status changes.

CRM Webhook Endpoint

Your LeadSoras CRM backend exposes the following webhook endpoint:

POST https://your-crm-backend.com/api/webhooks/evolution

Configure in Evolution API

You can set the webhook URL either during instance creation (Step 7) or update it after:

curl -X PUT 'https://your-evolution-api.com/webhook/set/LeadSoras' \
  -H 'apikey: YOUR_EVOLUTION_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://your-crm-backend.com/api/webhooks/evolution",
    "enabled": true,
    "webhookByEvents": true,
    "events": [
      "MESSAGES_UPSERT",
      "MESSAGES_UPDATE",
      "CONNECTION_UPDATE",
      "SEND_MESSAGE"
    ]
  }'

Webhook Events Handled by CRM

For Meta Business API — Facebook Webhook (Lead Ads)

If you're also using Facebook Lead Ads integration, configure the Facebook webhook separately:

📱 Step 10 — Connect via QR Code

✉️ Sending Messages

Once connected, you can send WhatsApp messages to your leads directly from the CRM.

From the Lead Chat

Via the WhatsApp Dashboard

Navigate to Dashboard → WhatsApp to access the dedicated messaging interface where you can:

• Send individual messages to any phone number
• View message history and delivery status
• Monitor sending queue and statistics
• Pause/resume message sending
• Retry failed messages

Via API (Programmatic)

curl -X POST 'https://your-crm-backend.com/api/whatsapp/send' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "phoneNumber": "201234567890",
    "messageText": "Hello! This is a test message from LeadSoras CRM.",
    "leadId": "optional-lead-uuid"
  }'

Message Queue System

Messages are not sent immediately — they go through an intelligent queuing system:

📨 Bulk Messaging

📝 Message Templates

Templates allow you to create reusable message formats with dynamic variables. Manage templates at Dashboard → WhatsApp → Templates.

Creating a Template

Hello {{ name }}! 👋

Thank you for your interest in our services.
Your inquiry #{{ phone }} has been received.

Our team will contact you within 24 hours.

Best regards,
LeadSoras Team

Available Variables

🔧 Troubleshooting

Connection Issues

Message Sending Issues

Checking Logs

# Check Evolution API logs
docker logs evolution-api --tail 100 -f

# Check CRM backend logs (Railway)
# Go to Railway dashboard → your service → Logs tab

# Check CRM backend logs (local)
# Look at terminal output or check console logs

❓ Frequently Asked Questions

Can I use my personal WhatsApp number?

Option A (QR Code): Yes, you can use your personal WhatsApp number. Your phone acts as the sender.
Option B (Meta API): No, the number must be exclusively registered with the Business API and cannot have WhatsApp installed on the phone.

How many messages can I send per day?

Option A: WhatsApp doesn't publish official limits for personal accounts, but sending more than ~1,000 messages/day risks temporary bans. Use reasonable delays.
Option B: Depends on your tier — starts at 250/day (unverified), then 1,000, 10,000, 100,000, and unlimited after Meta verification.

Is this integration free?

Evolution API is open-source and free. Meta's WhatsApp Business API charges per conversation (currently first 1,000 service conversations per month are free). Server hosting costs depend on your provider.

Can I send images, videos, and documents?

Yes! The CRM supports sending media messages including images, videos, and documents via WhatsApp. Use the media upload feature when composing messages, or pass mediaUrl and mediaType via the API.

Will incoming messages appear in the CRM?

Yes! When a lead replies to your WhatsApp message, the reply is automatically captured via webhooks and saved in the lead's chat history. The CRM matches incoming messages to leads based on phone number.

Can multiple team members use the same WhatsApp connection?

Yes. The WhatsApp connection is shared at the organization level. All CRM users with WhatsApp permissions can send and view messages through the same connected number.

What happens if my phone disconnects (QR Code mode)?

Pending messages will queue up and be sent once the connection is re-established. If the session fully expires, you'll need to re-scan the QR code from the WhatsApp Settings page.