FAQ and troubleshooting

Before you buy#

Can I run it as a SaaS with the Regular License?#

Only if your end users are not charged. The Envato Regular License covers one end product whose users do not pay. If businesses pay you to use it (subscriptions, setup fees, any paid plan), you need the Extended License. See Envato's licence terms and Selling it as SaaS.

What are the server requirements?#

Node.js 22 running as a long-lived process (a VPS or container host, not serverless), Postgres 12 or newer, a domain with HTTPS and WebSocket support, an OpenAI key for live voice and an xAI key for chat. As a starting point, 2 vCPU and 2 to 4 GB of RAM is comfortable for a small SaaS. Full details: Requirements.

Can I host it on Vercel, Netlify or another serverless platform?#

No. Live calls hold two WebSockets open for the length of the call and background jobs run inside the process, neither of which serverless functions support. Use a VPS, Docker host, Railway, Render, Fly.io or similar, with auto-stop or scale-to-zero turned off.

Are there default admin credentials?#

No. There are no default accounts and no setup wizard. You name the first admin in ADMIN_EMAILS, sign up with that address and verify it (Google sign-in, or a confirmation link that is emailed or printed in the server log). Or run npm run admin:grant -- you@example.com. See First admin.

Can xAI (Grok) be used for speech-to-speech calls?#

No. Live, interruptible calls use OpenAI's Realtime API. xAI powers typed chat, the website widget, the turn-based phone path, voice previews and the AI helpers. See AI models and providers.

Is GPT-Live-1 supported?#

Not yet. Live voice is built on OpenAI's Realtime API (gpt-realtime-2.1 and gpt-realtime-2.1-mini); GPT-Live-1 uses a different protocol from the Realtime API.

Which Realtime model is the default?#

The flagship, gpt-realtime-2.1, whenever REALTIME_MODEL is blank. gpt-realtime-2.1-mini is roughly a third of the price; switch under Configuration → AI.

Do I need both an OpenAI and an xAI key?#

For the full product, yes. OpenAI for live voice; xAI for chat and most AI features. In 1.0.0 connecting another chat provider does not replace the xAI key.

Which phone carriers work?#

Twilio answers and places calls. Plivo and SIP trunks (via OpenAI SIP) answer only. Vonage and Telnyx are limited to outbound announcements. See Phone numbers and carriers.

Does it come with phone numbers or AI credits?#

No. You use your own carrier and AI provider accounts and they bill you directly. Nothing is marked up.

Can it transfer a caller to a person?#

Not as a live transfer in 1.0.0. It records a handoff with a brief and your team calls back. See Known limitations.

Does the receptionist know what is in my documents on phone calls?#

On live calls, only through the search_catalog tool, so switch it on. Chat, the widget and the turn-based phone path use your knowledge automatically. Put essentials such as prices and opening times in the instructions too.

Does it work in languages other than English?#

Live calls answer in the caller's language, and receptionists can be set to English, Spanish, French, Hindi, German, Portuguese, Japanese, Korean, Chinese or Arabic. The turn-based Twilio path recognises English (US) speech only.

Can I rebrand it?#

Yes. Set the brand name, support email, site title, description, favicon and social image under Configuration, and you have the full source to change anything else. Check what your licence allows for redistribution.

Is there a demo?#

Yes: receptionai.cc/login, with one-click business-owner and platform-admin access and sample data. You can run the same showroom on your own install with DEMO_MODE=true.

Troubleshooting#

I cannot stay signed in#

Session cookies require HTTPS on any host except localhost. Serve the site over HTTPS through a reverse proxy, and set BETTER_AUTH_URL to your HTTPS origin. If everyone is signed out after every restart, BETTER_AUTH_SECRET is not set.

Carrier webhooks cannot reach the app#

• The site must be on a public HTTPS address, and APP_URL must match it exactly (no trailing slash).
• Locally, use npm run tunnel and put the printed APP_URL in .env, then restart.
• Check the carrier's webhook URL: https://<APP_URL>/api/voice/inbound for Twilio, https://<APP_URL>/api/voice/plivo for Plivo.

Calls connect, then there is silence#

• Your proxy is not passing WebSocket upgrades for /api/voice/stream, or it closes idle connections too quickly. See the nginx example.
• OPENAI_API_KEY is missing or invalid. /api/health reports "openaiKey": false when it is missing.

It works locally but fails on my serverless host#

Serverless platforms cannot hold the call WebSockets or run the in-process job queue. Move to a host that runs a persistent process.

"AI is not available in this environment"#

XAI_API_KEY is not set. Add it to the environment or under Configuration → AI.

The homepage voice demo says live voice isn't switched on#

Set OPENAI_API_KEY, and make sure FEATURE_WIDGET has not been turned off.

Errors such as relation "…" does not exist#

The migrations have not been run against your database. Run npm run db:migrate (or, with Docker, docker run --rm --env-file .env.production reception-ai npm run db:migrate) and restart. Make it a step in every deploy.

Saving a phone number or connector fails#

CREDENTIAL_ENCRYPTION_KEY is missing (or not 32 bytes). Generate one with openssl rand -base64 32, set it, and restart. If you changed the key after saving credentials, the old ones cannot be decrypted and must be entered again.

I am not becoming an admin#

• Your address must be in ADMIN_EMAILS in the environment (not the admin panel), and the app restarted after adding it.
• The address must be verified: sign in with Google, or open the confirmation link. Without SMTP, look in the server log for lines starting with [admin].
• Links expire after one hour, and become invalid after a restart if BETTER_AUTH_SECRET is not set. Visit /admin again for a new one (at most every five minutes).

Plivo calls say "This line is not configured yet"#

Set APP_URL and OPENAI_PROJECT_ID under Configuration, and PLIVO_AUTH_TOKEN for signature checks.

Campaigns never start#

The job queue drains every minute in a built server, but not under npm run dev; call /api/jobs/run from the same machine in development. Also check that FEATURE_OUTBOUND is on and that the campaign is inside its calling window (its timezone defaults to America/New_York).

No booking times are offered#

Save opening hours and a timezone under Settings → Hours. Templates do not set hours, and slots are only generated when hours are saved.

The app listens on the wrong port#

The built server defaults to port 3000 unless PORT is set; the Docker image sets PORT=8080, and npm run dev always uses 8080.