Deploy WhatsApp API (Postgres + Redis)

Deploy and Host Evolution API with Railway

Evolution API is an open-source REST API for WhatsApp: connect a number by QR code, send and receive messages, manage groups and contacts, and push events to webhooks, n8n, Chatwoot or Typebot. This template runs Evolution API 2.3.7 with Postgres, Redis, the built-in Manager UI and a generated API key.

This template runs Evolution API (evolution-foundation/evolution-api). Evolution API is licensed under Apache-2.0 with additional conditions (see License below). This is a community template, not affiliated with Evolution Foundation, Meta or WhatsApp.

About Hosting Evolution API

Evolution API keeps a long-lived WhatsApp Web connection per instance (one instance = one phone number), stores instances, credentials, messages and contacts in Postgres, and uses Redis for its cache and WhatsApp session keys. This template wires all three over Railway's private network. The API listens on one public HTTPS domain; every endpoint requires the global API key, and the Manager UI at /manager asks for the same key.

On boot the service waits for Postgres and Redis, applies the database migrations, then starts. The application files come unmodified from the official evoapicloud/evolution-api:v2.3.7 image (pinned by digest) and run on a current Node.js 24 LTS. Two small fixes are applied on top, both listed below.

Common Use Cases

• Send order updates, appointment reminders and support replies from your own backend to customers who contacted you
• Connect a WhatsApp number to Chatwoot as a shared support inbox
• Trigger n8n, Typebot, Dify or OpenAI bots from incoming WhatsApp messages
• Receive WhatsApp events (messages, status, connection) as webhooks in your app

Dependencies for Evolution API Hosting

• Evolution API service (repo build on top of the official image, volume at /evolution/instances)
• Postgres 18 (Railway image, volume)
• Redis 8.2 with append-only persistence (volume)

Deployment Dependencies

• Evolution API on GitHub
• Evolution API documentation
• Evolution API license and trademark policy
• WhatsApp Terms of Service and WhatsApp Business Messaging Policy
• Railway Fair Use Policy

Implementation Details

First steps

1. Open the Evolution API service, Variables tab, and copy AUTHENTICATION_API_KEY.
2. Open https://{your-domain}/manager, enter https://{your-domain} as the server URL and the key, and create an instance. Scan the QR code with WhatsApp (Linked devices).
3. Or use the API: POST /instance/create with header apikey: {key} and body {"instanceName":"main","integration":"WHATSAPP-BAILEYS","qrcode":true}. The response contains the QR code as base64.
4. Send a message: POST /message/sendText/main with {"number":"{country code + number}","text":"Hello"}.

GET /healthz is the healthcheck. GET / shows the version. Requests without the key get 401.

Security defaults

• The API key is generated at deploy (48 characters). If it is empty, shorter than 16 characters or a public example value, the service starts but stays locked with a random key and the log says how to fix it.
• Telemetry to the Evolution API project is off (TELEMETRY_ENABLED). The Cloud API webhook verify token is generated.
• Backport of the Evolution API 2.3.8 security fix (issue #2435): an instance's own token can no longer act on another instance through ?instanceName= in the query string.
• The database URL is never written to the log (upstream's start script prints it).

WhatsApp stability fix

WhatsApp now sends status stanzas that Baileys 7.0.0-rc.9 (shipped in 2.3.7) never acknowledges; after about 50 minutes the connection looks open but stops receiving messages (upstream issue #2778). The build applies the 3-line fix from the open upstream pull request #2788.

Official WhatsApp Cloud API

Besides the default WHATSAPP-BAILEYS connection (WhatsApp Web protocol), Evolution API can create WHATSAPP-BUSINESS instances that use Meta's official Cloud API with your Meta app token, phone number ID and business ID. Point the Meta webhook to https://{your-domain}/webhook/meta with the value of WA_BUSINESS_TOKEN_WEBHOOK as verify token.

Resources and plans

Measured on Railway: Evolution API about 0.12 GB idle and 0.28 GB while an instance generates QR codes, Postgres 0.06-0.12 GB, Redis 0.03 GB. It runs on the Free plan (0.5 GB per service; tested) and on Trial (1 GB). Each connected number adds memory, so plan more for many instances.

Scaling and upgrades

Run one replica: two replicas would open the same WhatsApp sessions twice. The volume makes Railway stop the old deployment before starting the new one, which avoids that during redeploys. To upgrade, change the EVOLUTION_IMAGE digest and EVOLUTION_VERSION in services/evolution-api/Dockerfile of your fork; the build checks the Baileys file it patches and fails instead of shipping a half-patched image. Migrations run on every start.

Risks you accept with the WhatsApp Web connection

• WHATSAPP-BAILEYS instances use Baileys, an unofficial implementation of the WhatsApp Web protocol. It is not provided or endorsed by Meta or WhatsApp, and WhatsApp can restrict or ban numbers that use it, especially new numbers or numbers that send many messages.
• You must follow WhatsApp's Terms of Service and Business Messaging Policy. Do not send spam, bulk or unsolicited messages; message only people who agreed to hear from you. Railway's Fair Use Policy also forbids abusive bots, and Railway may remove such deployments.
• Use a number you can afford to lose for testing. For business-critical or high-volume messaging, use the official Cloud API integration.

License

Evolution API is licensed under Apache-2.0 with additional conditions: if you use its frontend (the Manager), you may not remove or change its logo or copyright; and if you build Evolution API into a product, show your administrators a clear notice that Evolution API is used (for example in your documentation or settings page). Otherwise a commercial license from Evolution Foundation may be required. This template keeps the Manager unmodified and prints the notice in the service log at every start. "Evolution API" is a trademark of Evolution Foundation.

Why Deploy Evolution API on Railway?

Railway runs the API, Postgres and Redis as one project with private networking, volumes, HTTPS and logs, so you get a working WhatsApp API in minutes without managing servers, and you pay only for what the three services use.