Skip to main content

​
Quick Start Guide

This guide will help you set up Highway locally and create your first automated verification call in minutes.

​
Prerequisites

Before you begin, ensure you have the following:
1

Node.js and npm

Install Node.js (version 16 or higher) and npm. Verify installation:
node --version
npm --version
2

Twilio Account

Sign up for a Twilio account and obtain:
  • Account SID
  • Auth Token
  • Twilio Phone Number (with voice capabilities)
3

OpenAI API Key

Get your OpenAI API key from the OpenAI Platform.
You’ll need access to the GPT-4o Realtime API. Ensure your account has the necessary permissions.
4

Supabase Project

Create a Supabase project and set up the required tables:verifications table:
create table verifications (
  id bigserial primary key,
  name text not null,
  phone text not null,
  data jsonb,
  type text,
  created_at timestamp with time zone default now()
);
calls table:
create table calls (
  id bigserial primary key,
  verification bigint references verifications(id),
  status text default 'in_progress',
  created_at timestamp with time zone default now()
);

​
Installation

1

Clone the Repository

Clone the Highway repository to your local machine:
git clone <repository-url>
cd highway
2

Install Backend Dependencies

Navigate to the backend directory and install dependencies:
cd highway-backend
npm install
The backend uses the following key dependencies:
  • express - Web server framework
  • express-ws - WebSocket support for Express
  • twilio - Twilio SDK for phone calls
  • openai - OpenAI API client
  • @supabase/supabase-js - Supabase client
3

Install Frontend Dependencies

In a new terminal, navigate to the frontend directory and install dependencies:
cd highway-frontend
npm install

​
Configuration

1

Configure Backend Environment

Create a .env file in the highway-backend directory with your credentials:
# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key_here

# Twilio Configuration
TWILIO_ACCOUNT_SID=your_twilio_account_sid
TWILIO_AUTH_TOKEN=your_twilio_auth_token
TWILIO_PHONE_NUMBER=your_twilio_phone_number

# Server Configuration
PORT=3000
Keep your .env file secure and never commit it to version control. The file contains sensitive API keys and credentials.
2

Configure Supabase Connection

Update the Supabase configuration in your backend and frontend code:Backend (highway-backend/routes.js and highway-backend/websocket.js):
const supabase = createClient(
  'YOUR_SUPABASE_URL',
  'YOUR_SUPABASE_ANON_KEY'
);
Frontend (uses environment variables): Create a .env.local file in highway-frontend:
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
3

Configure API Base URL

Update the API base URL in highway-frontend/src/utils/api.ts to point to your backend:
const API_BASE_URL = "http://localhost:3000";
For production deployments, you’ll need to expose your backend via a public URL (e.g., using ngrok, a cloud provider, or a VPS).

​
Running Highway

1

Start the Backend Server

In the highway-backend directory, start the Express server:
node index.js
You should see:
Listening on port 3000
The backend server handles:
  • REST API endpoints for initiating calls
  • WebSocket connections for real-time audio streaming
  • Integration with Twilio and OpenAI
2

Start the Frontend Development Server

In a new terminal, navigate to highway-frontend and start the Next.js development server:
npm run dev
The frontend will be available at http://localhost:3001 (or the port shown in the terminal).
3

Expose Backend with ngrok (Optional but Recommended)

For Twilio to communicate with your local backend, expose it using ngrok:
ngrok http 3000
Update the API_BASE_URL in your frontend code with the ngrok URL:
const API_BASE_URL = "https://your-ngrok-url.ngrok-free.app";

​
Create Your First Verification

1

Access the Dashboard

Open your browser and navigate to http://localhost:3001. You’ll see the Highway dashboard with the “Pending Verifications” table.
2

Add a Verification

Click the “Add verification” button and fill in the form:
  • Name: Customer’s name (e.g., “John Doe”)
  • Phone Number: 10-digit phone number (e.g., “5551234567”)
  • Background: Context for the call (e.g., “customer signed up for a loan”)
  • Verification Data: JSON object with data to verify
Example verification data:
{
  "date of birth": "1990-01-01",
  "address": "123 Main St, Anytown, USA",
  "last four of SSN": "1234"
}
Click “Add verification” to create the record.
3

Initiate the Call

In the verifications table, find your newly created verification and click the “Initiate call” button.The system will:
  1. Create a call record in the database
  2. Initiate a Twilio call to the specified phone number
  3. Establish a WebSocket connection for audio streaming
  4. Connect to OpenAI’s Realtime API
  5. Begin the AI-powered verification conversation
4

Answer the Call

When the phone rings, answer it. You’ll hear the AI agent:
  1. Introduce itself as an agent from Olive Financial
  2. Explain the purpose of the call
  3. Ask verification questions based on your data
  4. Conduct a natural conversation
  5. Thank you and hang up when complete
The AI uses OpenAI’s “shimmer” voice and is configured to be cheerful and professional.
5

View Call Results

Navigate to the “Calls” page (if available) or check your Supabase database to see the call status:
  • successful_call: Identity verified successfully
  • unsuccessful_call: Identity not verified
  • user_hung_up: Customer ended the call early
  • system_error: Technical error occurred
  • in_progress: Call is ongoing
The calls are displayed with detailed information including:
  • Customer name and phone number
  • Call status with color-coded badges
  • Timestamp of the call
  • Verification data that was used

​
What’s Happening Under the Hood?

When you initiate a call, here’s the flow:
  1. Frontend sends a POST request to /call-customer with phone number and verification ID
  2. Backend creates a call record in Supabase with status “in_progress”
  3. Twilio initiates the phone call with TwiML containing a WebSocket stream URL
  4. WebSocket connection establishes between Twilio and your backend at /media-stream/:id/:numid
  5. Backend connects to OpenAI Realtime API and fetches verification data from Supabase
  6. Audio streaming begins bidirectionally:
    • Customer audio → Twilio → Backend WebSocket → OpenAI
    • OpenAI response → Backend WebSocket → Twilio → Customer
  7. AI conversation proceeds based on the session configuration and verification data
  8. Status updates occur when the AI calls the call_reflection_data function
  9. Call ends when the AI calls hang_up_call or the customer hangs up

​
Next Steps

Architecture Overview

Learn about Highway’s system architecture and component interactions

Customize AI Behavior

Customize the AI agent’s voice, instructions, and conversation flow

API Reference

Explore all available API endpoints and WebSocket events

Deployment Guide

Deploy Highway to production with cloud providers

​
Troubleshooting

  • Verify your Twilio credentials are correct in .env
  • Ensure your Twilio phone number has voice capabilities
  • Check that your backend is publicly accessible (use ngrok for local testing)
  • Verify the WebSocket URL in the TwiML is correct
  • Check that your OpenAI API key is valid and has Realtime API access
  • Verify the WebSocket connection to OpenAI is established (check logs)
  • Ensure verification data exists in Supabase for the given ID
  • Check backend logs for any error messages
  • Verify the API_BASE_URL in src/utils/api.ts is correct
  • Check CORS configuration in backend index.js
  • Ensure backend server is running on the expected port
  • Test the backend health endpoint: GET /
  • Verify your Supabase URL and anon key are correct
  • Ensure the verifications and calls tables exist
  • Check Row Level Security (RLS) policies allow the operations
  • Verify your Supabase project is active
Remember to keep your API keys and credentials secure. Never commit .env files to version control.

Build docs developers (and LLMs) love

Get started for freeTalk to us