Skip to main content

Connect your own Evolution server

Self-hosted NuSaaS does not sell or provision Hosted WhatsApp. You operate your own gateway, number, instances and credentials; the NuSaaS private console and hosting payment are not required. Existing direct provider integrations, where available, use your own provider accounts—not NuSaaS-managed accounts. SMS/Africa's Talking are not part of this distribution.

Evolution's linked-device integration is unofficial. WhatsApp can disconnect, restrict or ban the number; server limits cannot prevent this. Use a dedicated business number and expected customer-initiated conversations. Campaigns and proactive reminders are not enabled for Evolution.

Deploy the optional stack​

Obtain docker-compose.evolution.yml and .env.evolution.example from the matching published installer bundle. Review the chosen Evolution release's API compatibility, license and network behavior before enabling it. Some releases require activation and periodic licensing heartbeats even when TELEMETRY_ENABLED=false; this package does not approve that activity for you.

Set the following in .env:

WHATSAPP_EVOLUTION_ENABLED=true
WHATSAPP_SELF_HOSTED_URL=https://whatsapp.yourdomain.com
WHATSAPP_CALLBACK_BASE_URL=https://api.yourdomain.com
WHATSAPP_EVOLUTION_NATIVE_BUTTONS=false
WHATSAPP_EVOLUTION_NATIVE_LISTS=false
# Supply reviewed release digests, not these placeholder values.
EVOLUTION_IMAGE=YOUR_REVIEWED_EVOLUTION_IMAGE
EVOLUTION_POSTGRES_IMAGE=YOUR_REVIEWED_POSTGRESQL_16_IMAGE
EVOLUTION_DB_PASSWORD=YOUR_RANDOM_URL_SAFE_PASSWORD

Copy .env.evolution.example to .env.evolution, generate its separate global gateway key, and restrict the file to mode 600. The global key is for your gateway operator only; never enter it in ERP tenant settings or give it to users.

docker compose -f docker-compose.yml -f docker-compose.evolution.yml config --quiet
docker compose -f docker-compose.yml -f docker-compose.evolution.yml up -d

This adds separate Evolution, PostgreSQL and Redis services with persistent sessions/data. Allocate and monitor additional disk, memory and backups. With direct Caddy ingress, add your gateway hostname to Caddy and proxy it to evolution:8080; with Tunnel, include both overlays and route the gateway hostname there. The gateway must be reachable through a public HTTPS DNS origin on port 443. Private-address/direct HTTP endpoints are deliberately rejected by the SSRF-safe ERP connector.

Recreate backend, worker and scheduler services after changing flags or the approved origin. Use the same Compose overlays throughout. Changing WHATSAPP_SELF_HOSTED_URL makes connections to the previous origin ineligible; it does not transfer sessions.

  1. In your Evolution Manager, create a dedicated WHATSAPP-BAILEYS instance and obtain its instance-scoped credential.
  2. In ERP Settings → WhatsApp → Evolution, enter that instance name and credential. The endpoint is read-only, supplied by your operator's WHATSAPP_SELF_HOSTED_URL setting.
  3. Acknowledge the risks, save the connection and display its QR code.
  4. On the business phone, open WhatsApp → Linked devices → Link a device and scan it.
  5. Choose Check connection. NuSaaS validates the instance/number and configures the generated authenticated webhook.
  6. Request an incoming verification code and send it from a different WhatsApp number to the linked business number. Verification updates automatically after an eligible callback arrives.
  7. Activate the verified connection, then enable the relevant ordering configuration with your intended schedule and staff-handoff behavior.

Webhook setup details provides the callback URL, authentication header/token and MESSAGES_UPSERT / MESSAGES_UPDATE subscriptions. Keep event-name URL suffixes disabled. Neither the global gateway key nor the instance key belongs in the webhook URL. Keep callback authentication intact and exclude callback paths from interactive proxy challenges.

Verify operation​

Use a fresh message from a real customer/test phone after explicit operator approval. A connected phone does not prove outbound delivery. Check recorded Queued, Accepted, Sent, Delivered, Read, Failed or Outcome unknown evidence rather than treating gateway acceptance as delivery. Do not blindly replay uncertain sends.

Budgets remain five attempts/minute, 100/day and 30 seconds between attempts to one recipient. A wait for a budget should not be treated as provider failure. Native buttons/lists remain off until rendering and selection callbacks have been verified against your pinned gateway release. Plain-text commands provide the fallback.

Pause preserves history and the linked session while stopping outbound sending/ordering. Unlink logs out the business number after confirmation. Back up gateway sessions and PostgreSQL separately from the ERP; do not delete volumes to resolve connection errors.