- Introduction
- Features
- Prerequisites
- Installation
- References
- Configuration
- Database Migrations
- Usage
- Webhooks
- Testing
- Troubleshooting
- License
Evolution API Lite is a streamlined microservice for WhatsApp Business connectivity, designed to be:
- Policy‑compliant: uses only the official WhatsApp Business Cloud API. Do not enable any WhatsApp Web libraries (e.g., Baileys) — they violate Meta’s terms.
- Lightweight: no extra integrations (Typebot, Chatwoot, OpenAI) or audio features.
- Production‑ready: works out of the box with Docker, Kubernetes, or your own infrastructure.
Ideal for projects like TradeMore, where you need fast, reliable WhatsApp messaging without extra overhead.
- ✅ Official WhatsApp Business Cloud API only
- ✅ Single‑responsibility microservice
- ✅ Built‑in webhook handling
- ✅ Flexible persistence (PostgreSQL, MySQL)
- ✅ Pluggable telemetry (optional)
- Node.js ≥ 16 or Docker & Docker Compose
- A Meta Developer account with a WhatsApp Business App (Cloud API)
- PostgreSQL or MySQL (or use the provided Docker Compose)
Clone the TradeMore monorepo and install Evolution API Lite alongside other apps:
git clone git@github.com:checkatrade-labs/trademore.git
cd trademore/apps/evolution-api-lite
npm install
# or
yarn installAlternatively, you can use the automated installation script which handles Node.js installation, dependencies, and database setup:
npm run install:local
# or with development mode
npm run install:local -- -devNote: This runs in the same repo as
apps/webandapps/mobile.
Use docker-compose.yml to bring up all services:
docker compose up -d
# logs
docker compose logs -f evolution_apiThis starts:
- evolution_api on port 8080
- postgres (DB)
- redis (cache)
- Original Evolution API Lite:
- Meta WhatsApp Solution Providers:
To integrate TradeMore as a tech provider, Meta requires:
- Meta Developer Account & App
Create an app in Meta for Developers and add the WhatsApp Business API product. - Business Verification & Portfolio
Complete KYC/AML verification and set up a Business Portfolio to manage numbers and templates. - Tech Provider‑Client Relationship
TradeMore’s service acts as a Solution Provider. Clients grant access to their WhatsApp Business numbers via Business Manager, allowing us to:- Receive customer messages in TradeMore’s central inbox
- Send templated and session messages on behalf of trades
- Track delivery receipts and update CRM records
- Webhooks & Templates
- Configure your webhook URL to receive callbacks: incoming messages, status updates.
- Register required message templates.
Refer to Meta’s official guide for full steps:
https://developers.facebook.com/docs/whatsapp/solution-providers/get-started-for-tech-providers
Copy .env.example to .env and populate only the variables required for TradeMore’s flow:
| Variable | Description | Example |
|---|---|---|
SERVER_TYPE |
Protocol for internal callbacks (http or https) | http |
SERVER_PORT |
Port where the API listens | 8080 |
SERVER_URL |
Public URL for webhooks (must match Meta webhook) | https://api.trademore.com |
TELEMETRY |
Enable usage metrics reporting | true |
CORS_ORIGIN |
Allowed origins (comma‑separated, * to allow all) |
https://app.trademore.com |
LOG_LEVEL |
One or more of ERROR,WARN,INFO,DEBUG,WEBHOOKS |
INFO,WEBHOOKS |
DATABASE_ENABLED |
Enable persistent storage | true |
DATABASE_CONNECTION_URI |
PostgreSQL/MySQL connection URI | postgresql://user:pass@db:5432/trademore |
AUTHENTICATION_API_KEY |
Simple API key for protecting internal endpoints | a1b2c3d4e5f6g7h8 |
WA_BUSINESS_URL |
Base URL for WhatsApp Business API | https://graph.facebook.com |
WA_BUSINESS_VERSION |
WhatsApp Business API version | v20.0 |
WA_BUSINESS_TOKEN_WEBHOOK |
Verification token for Meta webhook setup | your_webhook_token |
WEBHOOK_GLOBAL_ENABLED |
Globally enable incoming webhook dispatch | true |
WEBHOOK_GLOBAL_URL |
Public URL to receive all WhatsApp callbacks | https://api.trademore.com/webhooks/whatsapp |
⚠️ For additional features (RabbitMQ, Redis, S3, SQS, etc.), see the official docs:
https://doc.evolution-api.com/v2/en/get-started/introduction#environment-variables
Ensure your .env is loaded and the service is running.
curl -X POST $SERVER_URL/project/create \
-H "apikey: $AUTHENTICATION_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"TradeMore"}'curl -X POST $SERVER_URL/customer/create \
-H "apikey: $AUTHENTICATION_API_KEY" \
-H "Content-Type: application/json" \
-d '{"projectId":"<projectId>","firstName":"John","email":"john@example.com","instancesLimit":1}'curl -X POST $SERVER_URL/instance/create \
-H "apikey: $AUTHENTICATION_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"projectId":"<projectId>",
"customerId":"<customerId>",
"instanceName":"trademore",
"qrcode":false,
"integration":"WHATSAPP-BUSINESS"
}'curl -X POST $SERVER_URL/message/sendText/<instanceId> \
-H "apikey: $AUTHENTICATION_API_KEY" \
-H "Content-Type: application/json" \
-d '{"number":"5511999999999@s.whatsapp.net","text":"Hello from TradeMore!"}'-
To get started with the WhatsApp Business API, follow the official Getting Started guide for a detailed onboarding.
-
But if you are looking for a quick start, you can check our Quick Start guide here.
-
You can also check the Postman collection for a complete set of API calls.
## Webhooks
Configure your webhook endpoint to receive incoming messages and status updates. Payloads are sent to `/webhooks/whatsapp` or your per-instance callback.
Example:
```json
{
"messages": [ { /* ... */ } ]
}The project uses Prisma for database migrations. To manage your database schema:
# Generate Prisma client from schema
npm run db:generate
# Deploy migrations to the database
npm run db:deploy
# Create a new migration after schema changes (development)
npm run db:migrate:dev
# Open Prisma Studio (database GUI)
npm run db:studioTBD
TBD
© 2024 Evolution API Lite
Licensed under the Apache License 2.0. See LICENSE for details.