Skip to main content
The Highway backend is an Express.js server that handles WebSocket connections, Twilio integration, and OpenAI Realtime API communication.

​
Installing Dependencies

1

Navigate to backend directory

cd highway-backend
2

Install npm packages

npm install
This will install the following core dependencies:
  • express - Web framework
  • express-ws - WebSocket support
  • cors - Cross-origin resource sharing
  • dotenv - Environment variable management
  • twilio - Twilio SDK for phone calls
  • openai - OpenAI SDK for Realtime API
  • winston - Logging framework
  • @supabase/supabase-js - Supabase client
3

Configure environment variables

Create a .env file in the backend directory. See Environment Variables for required variables.

​
Directory Structure

The backend follows a modular structure: 
highway-backend/
├── index.js              # Main server entry point
├── config.js             # Configuration and environment variables
├── routes.js             # HTTP route handlers
├── websocket.js          # WebSocket connection handling
├── conversationConfig.js # OpenAI Realtime API configuration
├── logging/
│   └── logger.js         # Winston logger setup
├── middleware/           # Express middleware
└── package.json

​
Key Files

index.js - Server initialization
  • Sets up Express app
  • Configures CORS
  • Registers routes and WebSocket handlers
  • Starts server on configured port
config.js - Configuration management
  • Loads environment variables
  • Exports configuration constants
  • Defines system messages and voice settings
routes.js - HTTP endpoints
  • / - Health check endpoint
  • /call-customer - Initiates Twilio calls
  • Handles Supabase database operations
websocket.js - WebSocket handling
  • Manages media stream connections
  • Bridges Twilio and OpenAI Realtime API
  • Handles audio streaming

​
Starting the Server

cd highway-backend
node index.js
You should see: 
2026-03-02 12:00:00 info: Listening on port 3000

​
Port Configuration

The server port is configured via the PORT environment variable:
.env
PORT=3000
Default: If not specified, you must set a PORT value.
When deploying, ensure your hosting platform’s port configuration matches your environment variable.

​
CORS Setup

The backend is configured with CORS to allow frontend connections:
index.js
app.use(
  cors({
    origin: "*", // Replace with your frontend's domain
    methods: ["GET", "POST", "PUT", "DELETE"],
    credentials: true,
  })
);
In production, replace origin: "*" with your specific frontend domain for security:
origin: "https://your-frontend-domain.com"

​
Logging Configuration

Highway uses Winston for structured logging. The logger is configured in logging/logger.js: Features:
  • Console output with colorization
  • Timestamp formatting (YYYY-MM-DD HH:mm:ss)
  • Exception handling
  • Info level logging by default
Usage in code: 
const logger = require("./logging/logger");

logger.info("Server started");
logger.error("Connection failed", error);
Log levels:
  • info - General information (default)
  • warn - Warning messages
  • error - Error messages
  • debug - Debug information
Logged event types (configured in config.js):
  • response.content.done
  • rate_limits.updated
  • response.done
  • input_audio_buffer.committed
  • input_audio_buffer.speech_stopped
  • input_audio_buffer.speech_started
  • session.created

​
Verification

Test your backend setup:
1

Check server is running

curl http://localhost:3000
Expected response:
{"message":"Running"}
2

Verify environment variables

Check that all required variables are loaded by reviewing the startup logs.
3

Test WebSocket connection

Use a WebSocket client to connect to ws://localhost:3000/media-stream/{verification}/{callId}

​
Next Steps

Environment Variables

Configure all required environment variables

Frontend Setup

Set up the Next.js frontend

Build docs developers (and LLMs) love

Get started for freeTalk to us