---
title: "Deploy Evolution API WebSocket"
description: "Stream WhatsApp events to your app over WebSocket"
category: "Automation"
url: https://railway.com/deploy/deploy-evolution-api-websocket-events
---

# Deploy Evolution API WebSocket

Stream WhatsApp events to your app over WebSocket

**[Deploy Evolution API WebSocket on Railway](https://railway.com/template/deploy-evolution-api-websocket-events)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/deploy-evolution-api-websocket-events/manifest.json

- **Creator:** onepush
- **Category:** Automation

## Template content

### Postgres https://devicons.railway.app/i/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

### evolution-api

- **Image:** evoapicloud/evolution-api:v2.3.7@sha256:1bd8afc4a6cf48822e6cf02469aeae7bd35a12a6b616eacd1291926307f4d339
- **Health check:** /
- **Public domain:** Yes

### Redis https://cdn.sanity.io/images/sy1jschh/production/0ce0bfdcfbdbf69662b1116671f97c2dd788b655-157x157.svg

- **Image:** redis:8.2
- **Start command:** `/bin/sh -c "rm -rf $RAILWAY_VOLUME_MOUNT_PATH/lost+found/ && exec docker-entrypoint.sh redis-server --requirepass $REDIS_PASSWORD --save 60 1 --dir $RAILWAY_VOLUME_MOUNT_PATH"`

## Documentation

# Deploy and Host self hosted Evolution API WebSocket (Real-Time WhatsApp Event Streaming) on Railway

Evolution API WebSocket streams WhatsApp instance events over socket.io to a browser dashboard or monitoring tool.

## About Hosting Evolution API WebSocket open-source software on Railway (self hosted Evolution API WebSocket event streaming for live WhatsApp instance events template)

This template runs Evolution API v2.3.7 on Railway with Postgres for instances, messages, and chats, plus Redis as a cache.

With WEBSOCKET_ENABLED set to true, the service streams instance events over socket.io, either on one global socket or per instance.

## Why Deploy Evolution API WebSocket, the Twilio alternative on Railway (Railway Free Trial)

Twilio is the easy managed choice, but it's official Cloud API only and bills per message on top of Meta's fees.

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Evolution API WebSocket on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

### Railway vs Other Hosting Providers and VPS for Evolution API WebSocket self hosting

Running this WebSocket-enabled Evolution API on Railway versus a VPS comes down to how much server work you want to own.

| Provider | What You Get with Railway | What You Get with the Other Provider |
| --- | --- | --- |
| DigitalOcean | Evolution API, Postgres, and Redis linked as services, with a public domain ready for wss. | A droplet you configure yourself, including Docker, TLS, and keeping the socket reachable. |
| AWS | A running service with variables set and managed Postgres and Redis linked, no VPC work. | Fine-grained networking control, but you own IAM, load balancing, and certificates first. |
| Hetzner | A managed deploy with the instance volume attached, no server hardening or proxy config. | Low raw server cost, but you handle the OS, Docker, reverse proxy, and backups. |

Railway trades some low-level control for a faster path to a working live event stream.

## Common Use Cases for hosted Evolution API WebSocket

These are the scenarios where a live socket beats polling a webhook receiver.

- **Live support dashboard:** A browser page subscribes to one instance and shows connection state and incoming messages as they arrive.
- **Multi-instance monitor:** With WEBSOCKET_GLOBAL_EVENTS on, one socket carries events from every instance.
- **Session drop alerts:** Listen for connect and disconnect events and alert the moment a session goes down.
- **Chat UI prototype:** Build a front end that reacts to events directly, with no webhook endpoint to set up yet.
- **Delivery comparison:** Run a socket listener and a webhook receiver side by side to check they see the same events.

## Dependencies for Evolution API WebSocket Docker hosted on Railway

This template runs as three Railway services: evolution-api, Postgres, and Redis.

### Deployment Dependencies for Managed Evolution API WebSocket Service (WhatsApp API)

- **evolution-api service:** image evoapicloud/evolution-api:v2.3.7 on port 8080, public domain, health check on /, volume mounted at /evolution/instances.
- **Postgres:** DATABASE_CONNECTION_URI wired from Railway Postgres DATABASE_URL, with DATABASE_SAVE_* set to true.
- **Redis:** CACHE_REDIS_URI wired from Railway Redis REDIS_URL.
- **Generated variables:** AUTHENTICATION_API_KEY (32 characters), sent as the apikey header, and SERVER_URL set to https://your-railway-domain.

### Implementation Details for Evolution API WebSocket (Using Evolution API official docker image)

Set WEBSOCKET_ENABLED=true on the evolution-api service, and add WEBSOCKET_GLOBAL_EVENTS=true only if you want one socket for every instance.

## How does Evolution API WebSocket compare against other ways to receive live Evolution API and WhatsApp events in real time

### Evolution API WebSocket vs Twilio (Twilio Alternative)

- **Event delivery:** Evolution API pushes instance events over a socket.io connection you hold open, so a dashboard sees activity without polling. Twilio sends inbound messages as HTTP webhooks to a URL you run.
- **Cost model:** Evolution API is free, and you pay only for hosting. Twilio adds a per-message fee on top of Meta's WhatsApp fees.
- **Where Twilio wins:** It is managed and officially supported, with no session to keep alive. For WhatsApp Business access with SLAs, it's the safer call.

### Evolution API WebSocket vs WhatsApp Cloud API webhooks (Official Meta Alternative)

- **Official status:** The Cloud API is Meta's sanctioned business channel. Evolution API can run on the unofficial Baileys connection, which WhatsApp may restrict for spammy traffic.
- **Delivery model:** Cloud API sends events as webhook POSTs your server must accept. A WebSocket gives a long-lived client live events, but only while it stays connected.
- **Where the Cloud API wins:** It needs no QR pairing or session files and suits business-scale sending, once Meta verification and approved templates are in place.

### Evolution API WebSocket vs WPPConnect (Open Source Alternative)

- **Scope:** WPPConnect is a WhatsApp Web automation library and server. Evolution API wraps a similar session approach in a multi-instance API.
- **Event transport:** Evolution API ships WebSocket, webhooks, RabbitMQ, and SQS, so you can pick live streaming or queued delivery. WPPConnect leaves that wiring to your code.
- **Where WPPConnect wins:** If you want a lean library to embed in your own service, its smaller footprint may fit better than a full gateway.

### Evolution API WebSocket vs Baileys (Protocol Library Alternative)

- **Layer:** Baileys is a TypeScript library for the WhatsApp Web protocol, and Evolution API uses it as one connection type. With Baileys you build the server, event fan-out, and socket layer yourself.
- **Ready-made streaming:** Evolution API gives you the instance API, manager UI, and socket.io event stream out of the box, so a dashboard can connect quickly.
- **Where Baileys wins:** Direct library control gives finer protocol-level handling and no extra service to host. For a small custom integration, skip the gateway.

## How to use Evolution API WebSocket (the OSS WhatsApp API gateway)?

1. In the evolution-api Railway service variables, set `WEBSOCKET_ENABLED=true`. For one socket across all instances, also set `WEBSOCKET_GLOBAL_EVENTS=true`. Keep `AUTHENTICATION_API_KEY` set and `SERVER_URL=https://your-railway-domain`. 2. Redeploy the service. 3.

```javascript
import { io } from "socket.io-client";

const socket = io("wss://your-railway-domain/your-instance", {
  transports: ["websocket"],
});

socket.on("connect", () => console.log("connected", socket.id));
socket.on("disconnect", () => console.log("disconnected"));

// in your component cleanup
socket.disconnect();
```

## How to self host Evolution API WebSocket on other VPS Services (Evolution API self hosting guide)

To run this on a plain VPS instead of Railway, follow these steps.

### Clone the Repository

Pull the official source onto your server.

```bash
git clone https://github.com/EvolutionAPI/evolution-api.git
cd evolution-api
```

### Install Dependencies

Install Docker and the Compose plugin.

### Configure Environment Variables

Copy the example file, then set the WebSocket and database values.

```bash
cp .env.example .env
```

```env
AUTHENTICATION_API_KEY=your-32-char-global-key
SERVER_URL=https://your-domain
WEBSOCKET_ENABLED=true
WEBSOCKET_GLOBAL_EVENTS=true
DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI=your-postgres-uri
CACHE_REDIS_URI=your-redis-uri
```

### Start the Evolution API WebSocket Application

Bring the stack up in the background, then confirm the root URL returns the welcome JSON.

```bash
docker compose up -d
```

On a VPS you also manage TLS, backups, and restarts yourself, which Railway handles for you.

## Official Pricing of Evolution API WebSocket (Evolution API pricing)

Evolution API itself is free and open source, so there is no license fee to pay.

## Evolution API WebSocket cloud vs self hosted comparison (Pricing, features, costs, and more)

Here's the honest version: the Evolution API software is free, so your real choice is where it runs and what you pay to keep it running.

### Monthly cost of self hosting Evolution API WebSocket on Railway

Expect roughly 5-15 USD/mo for the API service plus Postgres and Redis at light use, and Railway's 5 USD trial covers early testing.

### System Requirements for Hosting Evolution API WebSocket on a VPS

Run it on a box with enough memory for Node.js plus your Postgres and Redis, and give the instances volume at /evolution/instances persistent storage so WhatsApp sessions survive restarts.

## Frequently Asked Questions (FAQs)

### Do I need webhooks if WebSocket is enabled?

No, the two are independent.

### How do global and per-instance modes differ?

In global mode (`WEBSOCKET_GLOBAL_EVENTS=true`) you connect once to `wss://your-railway-domain` and get events from every instance.

### Why does my socket connect but receive nothing?

Usually the instance isn't connected to WhatsApp yet, so no events are firing, or your listeners use the wrong event name.

### Is the apikey required on the WebSocket handshake?

The upstream docs don't say, so test it on your deployment rather than assuming.

### What happens to events while my client is offline?

Socket.io doesn't replay missed events, so anything fired while you're disconnected is lost to that client.

### Which socket.io client version should I use?

The upstream docs don't pin a version.
Keep the volume attached; it holds all state.
Keep the volume attached; it holds all state.


## Similar templates

- [N8N Main + Worker](https://railway.com/deploy/n8n-main-worker) — Deploy and Host N8N with Inactive worker.
- [Evolution API with n8n](https://railway.com/deploy/evolution-api-with-n8n) — Automate WhatsApp workflows with Evolution API, n8n, and Postgres.
- [Postgres Backup](https://railway.com/deploy/postgres-s3-backups) — Cron-based PostgreSQL backup to bucket storage

Open this page in a browser: https://railway.com/deploy/deploy-evolution-api-websocket-events