# Appointment changes
Source: https://docs.lobbystack.com/agent/ai-settings/appointment-changes
Let your AI receptionist cancel and reschedule appointments automatically, with confirmation steps that keep you in control.
When customers need to cancel or move an appointment, LobbyStack can handle the conversation automatically by phone or SMS.
Instead of waiting for your team to read a message, check the calendar, and reply manually, the AI receptionist can identify the appointment, confirm the request, and update the booking for you.
## What the AI can handle
LobbyStack can help customers:
* Find their upcoming appointment.
* Cancel an appointment they no longer need.
* Reschedule to another available time.
* Confirm the change before it is applied.
* Receive help in the same channel where they started, including calls and SMS.
This is designed for everyday appointment changes that usually take your team away from higher-value work.
## Built-in confirmation before changes
Appointment changes are not made from a casual request alone. LobbyStack asks for enough detail to make sure the customer is changing the right appointment.
By default, the receptionist uses:
* The phone number from the call or SMS conversation.
* The customer's name.
* An appointment detail, such as the appointment time or service.
* A clear final confirmation before canceling or rescheduling.
If the receptionist cannot confirm the appointment confidently, it will not make the change automatically. It can hand the conversation to your team instead.
LobbyStack helps you apply consistent confirmation steps, but it does not replace your own legal or privacy review. Configure the level of verification that fits your business, region, and appointment type.
## Add a one-time code for stricter verification
For businesses that want extra assurance, you can require a one-time code before the AI changes an appointment.
With one-time code verification turned on, the receptionist sends a code to the customer and waits for the correct code before canceling or rescheduling. This is useful when appointments are sensitive, high-value, or subject to stricter internal policies.
## Automatic calendar updates
When a change is approved, LobbyStack updates the appointment record and syncs the change to your connected calendar.
For cancellations, the appointment is marked as canceled and the calendar event is updated or removed according to the calendar connection.
For rescheduling, LobbyStack checks availability before offering a new time. If the time is available, the appointment is moved and the calendar sync is refreshed.
Connect Google Calendar before relying on automatic rescheduling. This lets LobbyStack avoid offering times that are already busy.
## Turn appointment changes on or off
You control whether the receptionist can cancel, reschedule, or require a one-time code.
In the dashboard sidebar, go to **Agent** > **AI settings**.
Scroll to **Appointment changes**.
Turn cancellation and rescheduling on or off.
Turn on **Require one-time code before changing appointments** if you want stricter verification.
Save your changes.
## Recommended setup
For the best customer experience:
* Add clear service entries so customers can describe what they booked.
* Connect Google Calendar so LobbyStack can check availability and sync changes.
* Keep your transfer number up to date for cases that need human review.
* Use one-time code verification for sensitive or high-value appointments.
Add appointment types and service details that help customers identify their booking.
Let LobbyStack check availability and sync booking changes automatically.
# Overview
Source: https://docs.lobbystack.com/agent/ai-settings/overview
Configure the opening line, default customer language, appointment changes, and default transfer number for your AI receptionist.
Open **Agent** > **AI settings** to edit the basic behavior used by the receptionist.
## Greeting
The greeting is the opening line your receptionist uses when answering a call or starting a conversation. Keep it short and specific.
Good greetings usually include the business name, a quick disclosure that the caller is speaking with the AI receptionist, and a simple offer to help.
| Business type | Example greeting |
| ------------- | --------------------------------------------------------------------------------------------------------------------- |
| Dental clinic | Thanks for calling Bright Smile Dental. I'm the AI receptionist. How can I help? |
| Salon | Thanks for calling North Loop Salon. I can help with services, availability, and messages for the team. |
| Home services | Thanks for calling Peak HVAC. I'm the AI receptionist. Are you calling about service, scheduling, or an urgent issue? |
| Restaurant | Thanks for calling Maple Table. I can help with hours, reservations, and messages for the staff. |
In the dashboard sidebar, go to **Agent** > **AI settings**.
Update the **Greeting** field.
Click **Save** beside the greeting field.
## Default customer language
The **Default customer language** setting supports:
| Option | Value |
| ------- | ----- |
| English | `en` |
| French | `fr` |
Choose the fallback language your receptionist should use when the caller's language is unclear.
This setting is a fallback, not a limit on conversation language. The receptionist can respond in other languages when the caller's language is clear. Add greeting, knowledge, service, and rule content in the languages your callers are most likely to use.
## Default transfer number
The **Default transfer number** is the phone number used when the receptionist performs a live handoff to a human.
Use a number that is answered during business hours. If different teams handle different requests, keep the default number as the safest general handoff and add rules for when a caller should be transferred.
Add a complete phone number in the transfer number field.
Click **Save** beside the transfer number field.
Use **Agent** > **Rules** to describe when the receptionist should transfer, take a message, or ask for callback details.
Add a transfer number when you want live human handoff. Without one, the receptionist takes callback or follow-up details so your team can respond from the dashboard.
## Appointment changes
Use **Appointment changes** to choose whether the AI receptionist can cancel or reschedule appointments automatically.
You can also require a one-time code before any appointment is changed.
See how LobbyStack confirms the customer, updates the calendar, and hands off uncertain requests to your team.
# Knowledge
Source: https://docs.lobbystack.com/agent/knowledge
Add text, documents, and website content so your receptionist can answer common business questions from accurate source material.
The **Knowledge** page is where you add information the receptionist can use when answering callers. Use it for facts that should be easy to retrieve: hours, location, parking, pricing notes, service descriptions, policies, intake requirements, and FAQs.
LobbyStack supports three knowledge sources: text entries, uploaded documents, and public website imports.
Hosted knowledge base is capped at 25 MB on Free, 100 MB on Starter, and 500 MB on Pro. The app also rejects individual document uploads larger than 10 MB.
## Text entries
Text entries are best for short, authoritative facts.
| Entry title | Good content |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Holiday hours | We are closed on statutory holidays. If a caller asks about a specific holiday, take a message so the team can confirm. |
| Parking | Customers can use the lot behind the building. Street parking is also available on Pine Street after 6 PM. |
| Cancellation policy | Please call at least 24 hours before the appointment to cancel or reschedule. |
| New customer intake | New customers should bring ID, insurance information if relevant, and any referral or service notes they have. |
Go to **Agent** > **Knowledge**.
Click **Add Knowledge** and choose **Text**.
Use a short title and put the full answer in the content field.
Click **Save**. The entry appears in the table.
## Document uploads
Use document uploads for PDFs, Word documents, text files, and Markdown files that contain useful caller-facing information.
| Limit | Value |
| --------------- | ------------------------ |
| Supported types | PDF, DOCX, TXT, Markdown |
| Maximum size | 10 MB per file |
Uploaded documents enter a processing flow before they are ready. The table shows status values such as queued, indexing, ready, or error.
Keep uploaded documents caller-ready. Use current, approved material so the receptionist answers with the same information your team would share.
## Website imports
Website import crawls a public URL and adds useful pages to the knowledge base. It is intended for public pages such as services, about, FAQ, hours, locations, menus, pricing, and contact pages.
Website import focuses on public, caller-facing pages and skips:
* Localhost, local network, or direct IP URLs.
* Pages behind a login.
* Low-signal pages such as checkout, cart, account, search, privacy, and terms pages.
* Static assets such as images, PDFs, spreadsheets, ZIP files, scripts, and stylesheets.
Go to **Agent** > **Knowledge**, click **Add Knowledge**, and choose **Website**.
Paste the homepage or section URL you want LobbyStack to crawl.
Click **Import Website**. Imported pages appear as they finish processing.
## Manage entries
From the Knowledge table you can:
* Search entries.
* Open a row to view extracted document text.
* Disable an entry without deleting it.
* Re-enable a disabled entry.
* Delete an entry permanently.
Prefer a smaller set of accurate entries over a large library of stale content. Caller-facing accuracy matters more than volume.
# Overview
Source: https://docs.lobbystack.com/agent/overview
Use the Agent section to configure AI settings, knowledge, services, and rules for your receptionist.
The **Agent** section controls how your AI receptionist behaves. It is split into AI settings, Knowledge, Services, and Rules.
Changes apply to new calls and future SMS automation. They do not rewrite calls or messages that already happened.
Set the opening line, fallback language, appointment changes, and default transfer number.
Add business information from text entries, documents, or a website import.
Add appointment types and the service information callers need.
Add operating instructions for transfers, callbacks, fallback behavior, and special cases.
## How configuration is used
LobbyStack prepares the saved Agent settings for each live call, so callers get stable behavior for the duration of the conversation.
For SMS, LobbyStack uses the current business context and the saved conversation state when generating AI replies.
## Minimum setup for real callers
Before forwarding production calls, check that:
* Your greeting names your business and sets the right expectation.
* The fallback language is set for cases where the caller's language is unclear.
* A transfer number is saved if you want live human handoff.
* Your knowledge entries include hours, location, services, pricing, policies, and common caller questions.
* Your service entries and Google Calendar connection are ready before you rely on appointment booking or appointment changes.
# Rules
Source: https://docs.lobbystack.com/agent/rules
Use plain text rules to define how your agent should act during calls and conversations.
The **Rules** page lets you shape your agent's behavior in plain text. Instead of building workflows or maintaining decision trees, write the instruction the way you would explain it to a teammate.
Rules are useful for actions, policies, and judgment calls: when to transfer a caller, when to take a callback message, what to do after hours, and how to handle questions that need a human response.
## What to put in rules
Good rules are specific, action-oriented, and easy to follow:
* "If a caller says there is an emergency, transfer to the default transfer number."
* "If the caller asks for a human and transfer is unavailable, take a callback message with their name, phone number, and preferred callback time."
* "If the receptionist is not sure of an answer, say that the team will follow up instead of guessing."
* "For after-hours callers, take a message and include the caller's preferred callback window."
Rules give you a simpler way to define what your agent should do than complex workflows or visual builders. Say the behavior you want in clear language, then keep the rule updated as your process changes.
## Rule templates
| Scenario | Template |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Live transfer | If a caller asks for a human or describes an urgent issue, transfer to the default transfer number. |
| Callback | If the caller wants a callback, collect their name, phone number, reason for calling, and preferred callback window. |
| Uncertain answer | If the receptionist is not confident, take a message for the team instead of guessing. |
| After-hours | Outside business hours, take a message and tell the caller the team will follow up during the next business day. |
| Pricing questions | If pricing depends on the customer's situation, explain the starting point and offer to have the team follow up with details. |
## Add a rule
In the dashboard sidebar, go to **Agent** > **Rules**.
Click **Add Rule**.
Add a short title and the full instruction in the content field. Use tags if they help you find the rule later.
Click **Save**. The rule is available to the receptionist after it is saved and indexed.
## Transfers and callbacks
Transfers use the default transfer number in **Agent** > **AI settings**. When a live handoff is not the right next step, the receptionist can create a follow-up task with callback details. Those tasks appear in the dashboard and on call detail pages.
## Recording and transcripts
LobbyStack stores call transcripts and can store call recordings. Operators review recordings from the **Calls** page when a recording is available.
Use rules for call-handling behavior. Manage recording and retention policy in your workspace and compliance settings.
# Services
Source: https://docs.lobbystack.com/agent/services
Add service entries so callers can understand what you offer and ask for the right appointment.
The **Services** page contains the appointment types or offerings your receptionist can discuss with callers. Services are managed with the same entry table pattern as Knowledge and Rules: a title, content, optional tags, status, and actions.
Service entries help LobbyStack explain what you offer, collect the right caller details, and guide appointment requests when your calendar is connected.
## Add a service
Go to **Agent** > **Services**.
Click **Add Service**.
Enter a clear title, such as "Initial Consultation", and describe what the service includes. Add tags that match caller language if helpful.
Click **Save**. The service appears in the Services table.
## Make services easier to book
Write service entries the way callers ask for them:
* Use the plain customer-facing service name.
* Include duration, eligibility, prep instructions, and pricing only when those details are stable.
* Add synonyms in tags when callers use different words for the same service.
* Keep unavailable or seasonal services disabled.
## Service examples
| Service | Helpful details to include |
| --------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Initial consultation | Who it is for, typical duration, whether it can be booked online, and what the caller should prepare. |
| Emergency repair | What counts as urgent, whether same-day service is available, and when the receptionist should transfer the caller. |
| Follow-up appointment | Who should book it, how long it usually takes, and whether it must be with a specific team member. |
| Seasonal service | The months it is offered, any booking window, and what callers should know before requesting it. |
## Calendar booking
Connect Google Calendar when you want LobbyStack to check availability and add bookings to your calendar.
Connect a Google account and select the calendar LobbyStack should use for bookings.
# Affiliate program
Source: https://docs.lobbystack.com/billing/affiliate-program
Earn commission by referring businesses to LobbyStack.
The LobbyStack Affiliate Program lets eligible users earn commission by referring paying customers to LobbyStack.
You get a referral link from the dashboard. Share it with businesses that need better phone coverage, missed-call recovery, appointment booking, or an AI receptionist they can inspect and self-host later.
## Program terms
| Term | LobbyStack |
| -------------- | ---------------------------------------- |
| Commission | 20% |
| Duration | First 12 months after attribution |
| Holding period | 30 days |
| Minimum payout | USD \$100 in eligible unpaid commissions |
| Payout method | PayPal |
Refunds, disputes, cancellations, and invalid payments can void unpaid commissions.
For the overview and earning examples, read the
[LobbyStack Affiliate Program](https://lobbystack.com/affiliate-program/)
page. For a deeper comparison with other programs, see
[Earn 20% With the LobbyStack Affiliate Program](https://lobbystack.com/blog/ai-receptionist-affiliate-program/).
## Get started
In the dashboard header, click the gift icon to open **Affiliate Program**.
Open **Settings** on the affiliate page and save the PayPal email used for payouts.
Use your link in direct recommendations, websites, newsletters, videos, and comparison content.
## Track earnings
The affiliate dashboard shows:
* referral link and referral code
* tracked clicks
* attributed referrals
* paid conversions
* pending commissions
* eligible commissions
* payout records
Commissions become eligible after the 30-day holding period, as long as the referred payment has not been refunded, disputed, reversed, cancelled, or invalidated.
## Payouts
LobbyStack reviews eligible unpaid balances of USD \$100 or more and pays through PayPal using the email saved in your affiliate settings.
You are responsible for taxes, reporting, forms, fees, currency conversion, and payment account issues that apply to your commissions or payouts.
## Promotion rules
When you recommend LobbyStack:
* describe the product accurately
* disclose that you may earn commission
* avoid fake reviews, spam, misleading claims, coupon abuse, and self-referrals
* do not impersonate LobbyStack
* do not bid on LobbyStack trademarks or confusingly similar terms in paid search
Read the [Affiliate Program section in the Terms of Service](https://lobbystack.com/terms/#affiliate-program) for the full rules.
## Good referrals
LobbyStack is easiest to recommend to businesses that depend on phone calls:
* home service companies
* clinics and dental offices
* salons and spas
* contractors and repair businesses
* agencies helping clients improve lead capture
* consultants working on operations, local SEO, or automation
The strongest referrals have a clear phone problem: missed calls, after-hours inquiries, repeated questions, booking requests, or urgent calls that need routing.
# Plans and billing
Source: https://docs.lobbystack.com/billing/plans
Understand LobbyStack plan options: Free, Starter, Pro, Enterprise, and self-host.
LobbyStack supports five plan states in the app:
* **Free** for hosted workspaces with capped included usage.
* **Starter** for hosted workspaces with a monthly or annual subscription, included usage, and billable overages.
* **Pro** for hosted workspaces with higher included usage, monthly or annual billing, and billable overages.
* **Enterprise** for custom hosted arrangements.
* **Self-host** for deployments that use your own providers and infrastructure.
## Hosted plans
| Plan | Monthly charge | Annual charge | Voice minutes | Alert SMS segments | Outbound calls | Knowledge base | Overages |
| ---------- | -------------- | ------------------------------- | ------------- | ------------------ | -------------- | -------------- | -------- |
| Free | \$0 | - | 30 min | 10 | 2 | 25 MB | No |
| Starter | \$30/month | $288/year ($24/month effective) | 150 min | 50 | 20 | 100 MB | Yes |
| Pro | \$100/month | $960/year ($80/month effective) | 500 min | 200 | 100 | 500 MB | Yes |
| Enterprise | Custom | Custom | Custom | Custom | Custom | Custom | Custom |
Paid plan overage rates:
| Usage type | Starter | Pro |
| -------------- | ------------------------ | ------------------------ |
| Voice | \$0.20 per extra minute | \$0.18 per extra minute |
| Alert SMS | \$0.02 per extra segment | \$0.02 per extra segment |
| Outbound calls | \$0.02 per extra attempt | \$0.02 per extra attempt |
Included usage resets monthly on monthly and annual subscriptions. Unused minutes do not roll over.
## AI SMS add-on
AI SMS is available as a Pro add-on.
| Item | Price |
| ------------------ | ---------------------- |
| Monthly add-on | \$5/month |
| One-time setup fee | \$19 |
| Usage | \$0.03 per SMS segment |
AI SMS also requires compliance setup before hosted business-number messaging is ready.
## Self-host
Self-hosted workspaces run on your own providers and infrastructure, outside LobbyStack hosted plan quotas.
Review what your team manages when running LobbyStack yourself.
## Manage billing
In the dashboard, open **Settings** > **Billing** to:
* See the current plan.
* Upgrade to Starter or Pro.
* Manage your subscription.
* Enable the AI SMS add-on when eligible.
* Review recent billing transactions.
* Complete SMS compliance setup for hosted AI SMS.
# Usage and limits
Source: https://docs.lobbystack.com/billing/usage
Track voice minutes, SMS segments, outbound call attempts, knowledge base, and paid-plan overages.
The **Settings** > **Usage** page shows hosted usage for the current billing period. Usage resets at the start of each period.
## Usage metrics
| Metric | Meaning |
| ------------------ | ------------------------------------------------------------------------ |
| Voice minutes | Time spent on live voice calls. |
| Alert SMS segments | SMS notification segments sent by the system. |
| Outbound calls | Outbound call attempts, such as live transfer attempts. |
| AI SMS segments | Metered SMS segments for AI SMS conversations when the add-on is active. |
| Knowledge base | Stored knowledge content size. |
## Included usage
| Metric | Free | Starter | Pro |
| ------------------ | --------------------- | --------------------- | -------------- |
| Voice minutes | 30 min | 150 min | 500 min |
| Alert SMS segments | 10 | 50 | 200 |
| Outbound calls | 2 attempts | 20 attempts | 100 attempts |
| Knowledge base | 25 MB | 100 MB | 500 MB |
| AI SMS segments | Upgrade to Pro add-on | Upgrade to Pro add-on | Metered add-on |
## How limits work
Free hosted workspaces include a set usage pool for each billing period. When an included pool is used up, that usage type pauses until the next period or until the workspace upgrades.
Starter and Pro support billable overages for voice, alert SMS, and outbound call attempts. Knowledge base has a fixed plan allowance; remove old content or upgrade before adding more after the allowance is full.
## Overage rates
| Usage type | Starter | Pro |
| -------------- | ------------------------ | ------------------------ |
| Voice | \$0.20 per extra minute | \$0.18 per extra minute |
| Alert SMS | \$0.02 per extra segment | \$0.02 per extra segment |
| Outbound calls | \$0.02 per extra attempt | \$0.02 per extra attempt |
Annual subscriptions keep monthly usage resets. Unused included minutes do not roll over.
AI SMS is billed separately through its add-on at \$0.03 per segment.
## View usage
In the dashboard, open **Settings**.
Select **Usage** from the settings sidebar.
Check current usage, remaining quota, usage status, and reset timing.
On Starter or Pro, review estimated overage counts and cost for the current period.
Displayed overage amounts are estimates for the current period until the final invoice is created.
# Analytics
Source: https://docs.lobbystack.com/dashboard/analytics
Review engagement trends across calls, messages, appointments, call outcomes, and communication channels.
The **Analytics** page helps you understand how customers are using your receptionist. It summarizes weekly activity and shows whether calls, messages, appointments, and average call duration are moving up or down.
![LobbyStack Analytics page]()
*Analytics helps you spot workload changes and decide where to tune your agent or follow-up process.*
## What Analytics shows
| Section | What it is for |
| ------------------------- | ----------------------------------------------------------------- |
| **Engagement overview** | Weekly calls and messages in one chart. |
| **Calls this week** | Call count and change compared with the previous week. |
| **Messages this week** | SMS conversation activity and weekly change. |
| **Appointments booked** | Booking volume and weekly change. |
| **Average call duration** | Typical call length and week-over-week change. |
| **Call outcomes** | Completed, transferred, live, and missed call outcomes. |
| **Channels** | The share of activity coming from voice, SMS, and other channels. |
## Review performance
In the dashboard sidebar, go to **Manage** > **Analytics**.
Look at the metric cards to see whether call, message, appointment, and duration trends changed from the previous week.
Use **Call outcomes** to see whether calls are completing, transferring, or being missed.
Use **Channels** to understand how much activity is coming through voice, SMS, and other sources.
## How to read the trends
| Signal | What to check |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Calls are rising** | Review whether the team needs more coverage for follow-ups, transfers, or booking requests. |
| **Messages are rising** | Check active conversations and decide whether more threads should stay automated or be handled by staff. |
| **Appointments are rising** | Review upcoming appointments and make sure services and calendar settings still match your capacity. |
| **Missed or failed outcomes increase** | Open recent calls, review transcripts, and adjust knowledge, rules, or transfer settings if callers are getting stuck. |
| **Average duration changes sharply** | Longer calls can mean callers need more explanation; shorter calls can mean answers are easier to find or calls are ending early. |
## Weekly review routine
1. Start with the metric cards to see what changed.
2. Review **Call outcomes** for missed, failed, or transfer-heavy patterns.
3. Open **Calls** for examples behind the trend.
4. Update **Knowledge** or **Rules** when callers are repeatedly asking about the same topic.
5. Recheck Analytics after the next busy period to see whether the change helped.
## When to use it
Use Analytics when you want to understand workload, spot changes in caller behavior, or decide whether your agent setup needs adjustment. For individual conversations, use **Calls**, **Messages**, and **Contacts**.
# Review calls
Source: https://docs.lobbystack.com/dashboard/calls
Use the Calls page to review inbound calls, outcomes, transcripts, recordings, and follow-up tasks.
The **Calls** page is the call history for your active business. It shows inbound calls handled by LobbyStack, including status, outcome, transcript availability, and recording availability.
![LobbyStack Calls page]()
*The Calls page lets operators review the call list, open details, and follow up from one place.*
## What the call list shows
Each row can include:
* Caller name or unknown caller label.
* Caller phone number.
* Purpose or outcome summary.
* Start time.
* Status and disposition.
* Transcript indicator.
* Audio playback when a recording is available.
The page header also shows how many calls are currently live.
## Search and filter
Use the search field to find calls by caller name, phone number, or outcome text. Use the status filter to narrow the list.
## Call detail view
Open a call to see three tabs:
| Tab | What it shows |
| -------------- | ----------------------------------------------------------------------------------------------------- |
| **Transcript** | Saved caller and assistant turns when available. |
| **Recording** | Audio player after call audio is uploaded, or a processing state while audio is still being prepared. |
| **Details** | Outcome, follow-up task, call status, transfer status, and timing details. |
## Follow-up tasks
If the receptionist takes a callback or follow-up message during a call, the task appears on the call detail page. Operators can mark the task done from the dashboard.
## Recordings
LobbyStack stores a recording when call audio is available. While audio is still being prepared, the dashboard shows a processing state.
Recording playback appears after the call audio finishes processing. Use your workspace and compliance settings to manage recording and retention policy.
## Outcomes
Call summaries can include outcomes such as:
* Appointment booked.
* Scheduling started but not completed.
* Message taken.
* Transfer completed, busy, or failed.
* Completed without a structured outcome.
* Failed, canceled, no-answer, or technical issue.
# Manage contacts
Source: https://docs.lobbystack.com/dashboard/contacts
Review caller profiles, interaction history, appointments, blocking status, and SMS consent.
The **Contacts** page lists the people connected to your calls, messages, and appointments. Contacts are created automatically from phone interactions and are updated as new activity happens.
## Contact list
Each row can show:
* Contact name or unknown contact.
* Phone number and email if available.
* Activity counts for calls and messages.
* Appointment count.
* Last interaction time.
* Blocked status.
Use search to filter by name, phone number, or email.
## Contact detail
Open a contact to view:
| Tab | What it shows |
| ---------------- | --------------------------------------------------------------------- |
| **Activity** | Calls, SMS messages, and appointment activity in chronological order. |
| **Appointments** | Service, date and time, status, channel, and calendar sync state. |
| **Details** | Contact info, blocking state, SMS consent, and system metadata. |
## Blocking contacts
Blocking a contact stops new SMS replies and causes new inbound calls from that contact to hang up immediately. You can unblock the contact later from the same menu.
## SMS consent
The contact detail page shows whether the contact is subscribed or opted out of SMS, when the consent state changed, and the source of that change when available.
## Deleting contacts
Contacts with linked conversations or appointments stay in place so activity history remains complete. Contacts without linked records can be deleted from the contact detail page.
Contact deletion is permanent. Linked conversations and appointments stay protected so your activity history remains intact.
# Home
Source: https://docs.lobbystack.com/dashboard/home
Use Home to see what happened recently, what needs attention, and what is coming up next.
The **Home** page is the daily operating view for your workspace. It brings together recent calls, follow-up tasks, upcoming appointments, and high-level activity so your team can decide what to handle next.
![LobbyStack Home dashboard]()
*Use Home at the start of a shift to see what needs attention before opening individual calls or messages.*
## What Home shows
| Section | What it is for |
| ------------------- | ---------------------------------------------------------------------------------------- |
| **KPIs** | Monthly counts for calls, messages, appointments, and contacts. |
| **Action required** | Follow-up tasks that still need a human response, such as callbacks or handoff requests. |
| **Upcoming** | The next booked appointments on the calendar. |
| **Calls per month** | A monthly call-volume chart based on saved call records. |
| **Recent calls** | The latest inbound call activity with caller, timing, and outcome details. |
## Review follow-ups
In the dashboard sidebar, go to **General** > **Home**.
Review callbacks, human handoff requests, and other follow-up items.
Select the item or open the related call from **Calls** to review the transcript, recording, and details.
After your team follows up, mark the task done from the call detail page.
## Use Home at the start of a shift
Start with **Action required**, then check **Upcoming** appointments, then scan **Recent calls** for anything unusual. This keeps the team focused on customers who need a response instead of making them search through every call and message.
# Manage messages
Source: https://docs.lobbystack.com/dashboard/messages
Review SMS conversations, send manual replies, attach files, and pause or resume AI automation for a thread.
The **Messages** page shows SMS conversations for the active business. It is where operators review inbound and outbound messages, reply manually, inspect attachments, and control AI handoff per conversation.
![LobbyStack Messages page]()
*Use Messages for active SMS conversations, manual replies, attachments, and AI handoff control.*
## Conversation list
The left panel shows conversations sorted by recent activity. Each item can show:
* Contact name or unknown contact.
* Last message preview.
* Attachment preview labels such as photo or document.
* Timestamp.
* Blocked status when the contact is blocked.
Use search to find conversations by contact or message content.
## Conversation thread
Open a conversation to see the message timeline. The thread can include:
* Inbound customer messages.
* Outbound AI or operator messages.
* Attachments.
* Delivery failure states.
* Session summaries.
## Send a manual reply
Select an SMS conversation from the list.
Use the composer at the bottom of the thread.
Add up to 3 attachments. Images and documents are supported.
Click **Send**.
If a contact is blocked, the composer is disabled until the contact is unblocked from Contacts.
## Pause or resume AI
The thread header lets operators pause AI replies for that conversation. A human reply also places the conversation into handoff mode. Resume AI when the conversation should return to automated handling.
## Attachments
Messages can include photos and documents. Image attachments may render as previews. Other files appear as attachment cards or links depending on delivery mode.
# Create your account
Source: https://docs.lobbystack.com/getting-started/account-setup
Sign up for LobbyStack with an email and password, then update your business name, email address, or password any time from account settings.
Your LobbyStack account is the starting point for everything — your AI receptionist, your phone number, your call history, and your billing. This page covers how to create an account and how to change your account details after you are signed in.
## Creating an account
Open the LobbyStack sign-up page. You can reach it from the homepage by clicking **Try for free**, or by navigating directly to the sign-up URL.
Provide the email address you want to use for your account and choose a password.
Use a strong, unique password. LobbyStack enforces a minimum password length and complexity requirement.
Click **Sign up**. Your account is created immediately and you are taken into the onboarding flow to verify your phone number and choose a plan. Dedicated business numbers are included on Starter and Pro.
See the [Get started guide](/quickstart) for a full walkthrough of onboarding.
## Logging in
Go to the LobbyStack login page and enter your email and password. If you forget your password, click **Forgot password** on the login page. LobbyStack will send a reset code to your email address. Enter the code and choose a new password to regain access.
## Changing your account settings
Once you are signed in, go to **Settings** in the main navigation, then select **Account**. From there you can update your business name, email address, and password.
### Business name
Your business name appears in your dashboard and is used by the AI receptionist when it greets callers (unless you override the greeting with custom text).
1. In **Settings** > **Account**, find the **Business name** field.
2. Edit the name and click **Save**.
The change takes effect immediately.
### Email address
Changing your email address requires confirmation.
1. In **Settings** > **Account**, find the **Email** field.
2. Enter your new email address and click **Save**.
3. LobbyStack sends a confirmation email to the new address. Open it and click the confirmation link.
4. Your email address is updated once you confirm.
Until you click the link in the confirmation email, your account continues to use your original email address. Check your spam folder if the email does not arrive within a few minutes.
### Password
1. In **Settings** > **Account**, find the **Password** section.
2. Enter your current password, then enter and confirm your new password.
3. Click **Save**.
Your session remains active after a password change. Other devices signed into your account are not automatically signed out.
# Claim a dedicated phone number for your business
Source: https://docs.lobbystack.com/getting-started/claim-your-number
Choose a local or toll-free number that callers dial to reach your LobbyStack AI receptionist, or forward your existing business line to it.
Starter and Pro plans include a dedicated phone number. When someone calls that number, your AI receptionist answers. Free plans can try LobbyStack with dashboard test calls; upgrade when you are ready to go live on a public number.
## What a dedicated number is
A dedicated number is a real phone number assigned exclusively to your business on LobbyStack. Callers dial it like any other phone number. The AI receptionist answers, greets them, and handles the call based on your settings.
You can use the number as your primary business line or keep your existing number and forward calls to it. Calls that reach the LobbyStack number are handled by your AI receptionist.
## Claiming your number during onboarding
Number selection happens after you choose a paid plan during onboarding. Free plan users skip this step and can upgrade later from **Settings → Plan**.
Select Starter or Pro and complete checkout. LobbyStack then unlocks the phone-number step.
LobbyStack automatically suggests a local number based on the area code of the mobile number you verified. The suggestion is displayed with the number itself, its locality, and its region.
If the suggested number looks right for your area, you can accept it and move on.
If you want a different number, click **Pick a different number**. A picker opens with three search options:
* **City** — Enter a city name to find local numbers in that market. LobbyStack pre-fills the city detected from your verified phone.
* **Area code** — Enter a three-digit area code to search for numbers in that specific region.
* **Toll-free** — Find a toll-free number (for example, 800 or 888) if you prefer a number that is not tied to a specific geography.
Enter your search term and click **Search** to see available numbers. Select any number from the list to make it your choice.
Once you have selected the number you want, click **Continue**. LobbyStack reserves the number for your account. It cannot be claimed by anyone else after this point.
Your AI receptionist begins answering calls on this number immediately.
## Using your existing business number
If callers already know your existing business phone number, you do not have to ask them to dial a new one. Instead, set up call forwarding on your current number to route calls to your LobbyStack number. Most phone carriers and VoIP providers support forwarding in their account settings or via a short code.
To forward calls, log in to your current phone carrier or VoIP provider and set the forwarding destination to your LobbyStack number. The exact steps depend on your provider. Contact your carrier if you are unsure how to enable forwarding.
Once forwarding is active, callers dial your existing number as usual and those forwarded calls reach your AI receptionist.
## Free plan and number reclaim
Free plans do not include a dedicated business number. If you already have a number and your account is on Free, LobbyStack schedules that number for release after a 30-day grace period. Upgrade to Starter or Pro before the release date to keep it.
## Number porting
The fastest way to keep your existing business number is call forwarding: callers dial the number they already know, and forwarded calls reach your LobbyStack receptionist. If you need number porting instead, contact the team so we can review the best path for your carrier and region.
# Connect Google Calendar
Source: https://docs.lobbystack.com/integrations/google-calendar
Connect a Google account, choose a writable calendar, and let LobbyStack use it for appointment availability and booking sync.
Google Calendar lets LobbyStack read calendar availability, create booking events, and track calendar sync state for appointments. It also helps LobbyStack cancel or reschedule appointments automatically when appointment changes are enabled.
Connect Google Calendar after you add the services callers can request. This gives LobbyStack a calendar for checking availability, adding bookings, and syncing approved appointment changes.
## How the integration works
LobbyStack uses Google OAuth. You connect a Google account, LobbyStack stores the connection securely, and you select the calendar that should receive bookings. The integration can also sync busy time so LobbyStack avoids offering unavailable slots for new bookings and reschedule requests.
## Connect Google Calendar
In the dashboard, open **Integrations**.
Find **Google Calendar** and click **Connect**.
Sign in to Google and approve the requested calendar permissions.
After returning to LobbyStack, click the connected Google card, choose a calendar from the dropdown, and click **Save calendar**.
## Change the selected calendar
1. Open **Integrations**.
2. Click the Google Calendar card.
3. Choose another calendar.
4. Click **Save calendar**.
LobbyStack uses the newly selected calendar for future availability checks and bookings.
## Reconnect or disconnect
If Google access expires or is revoked, the card shows that reconnect is required. Click **Reconnect Google** and complete OAuth again.
To remove the integration, open the Google Calendar card and click **Disconnect**. LobbyStack removes the current connection for bookings.
# Integrations
Source: https://docs.lobbystack.com/integrations/overview
Connect your favorite tools to bring bookings, customer context, and follow-ups into LobbyStack.
The **Integrations** page is where LobbyStack connects with the tools your team already uses, from calendars to CRMs and communication apps.
Each integration guide explains what the connection does, what access it needs, and how to confirm it is working.
Let LobbyStack read busy time and create appointment events on a selected calendar.
## Google Calendar
Connect Google Calendar when you want LobbyStack to help callers book appointments. After you authorize Google, choose the calendar that should receive bookings.
## Where to find it
Open **Manage** > **Integrations** from the dashboard sidebar.
# SMS alerts and consent
Source: https://docs.lobbystack.com/integrations/sms
How LobbyStack collects consent for outbound appointment and workspace alert SMS.
LobbyStack uses one toll-free SMS number for outbound, non-marketing account notifications.
This number sends:
* Appointment confirmations and reminders to customers.
* Workspace alerts to verified operators.
This number does not send marketing, promotions, age-gated content, AI SMS replies, or manual SMS conversations.
## Consent model
LobbyStack collects SMS consent before sending alerts.
Appointment customers and operators use the same toll-free number, but they consent in different places.
### Appointment customers
When a customer books by phone, the AI receptionist asks for verbal SMS consent before sending an appointment confirmation or reminder.
The disclosure is:
> Can I text this number with your appointment confirmation and reminder? Message and data rates may apply. Reply STOP to opt out or HELP for help.
If the caller says yes, LobbyStack records the opt-in and sends appointment SMS for that phone number.
If the caller says no, the appointment is still booked and no appointment SMS is sent.
### Operators
Operators are verified workspace users.
Before operator workspace alerts are sent by SMS, the operator must enable SMS alerts in **Settings** > **Notifications** and accept the SMS disclosure in the dashboard.
The operator disclosure is:
> I agree to receive SMS alerts from LobbyStack about missed calls, new messages, appointment activity, and workspace notifications at my verified phone number. Message frequency varies. Msg & data rates may apply. Reply STOP to opt out or HELP for help. SMS alerts are optional.
Operators can disable SMS alerts later in notification settings.
## Example messages
Appointment confirmation:
> Example Business: Your haircut appointment is confirmed for May 24 at 2:00 PM. Msg & data rates may apply. Reply STOP to opt out or HELP for help.
Operator alert:
> LobbyStack: New voice message for Example Business. Open your dashboard to review. Msg & data rates may apply. Reply STOP to opt out or HELP for help.
## Opt-out and help
Recipients can reply `STOP` to opt out of future SMS from the toll-free alert number.
Recipients can reply `START` or `SUBSCRIBE` to resubscribe where supported.
Recipients can reply `HELP` for support information.
For help, contact [hello@lobbystack.com](mailto:hello@lobbystack.com) or visit [https://lobbystack.com](https://lobbystack.com).
Message and data rates may apply.
## SMS is optional
SMS alerts are optional.
Customers can book appointments without receiving SMS confirmations or reminders.
Operators can use the dashboard without enabling SMS alerts.
# Introduction
Source: https://docs.lobbystack.com/introduction
LobbyStack helps businesses answer calls, capture caller details, book appointments, and follow up from one operator dashboard.
LobbyStack is an AI receptionist for businesses that rely on phone calls. It answers calls through a dedicated business phone number, uses your saved business knowledge to respond to callers, helps with appointment booking and appointment changes when your services and calendar are connected, and keeps calls, messages, contacts, appointments, transcripts, and recordings organized in one dashboard.
Start with the quick start if you are setting up LobbyStack for the first time. If your workspace is already live, use the dashboard guides to review activity, tune your agent, and keep follow-ups moving.
Want the quickest way to get started? Create an account for free.
Create an account, verify your mobile number, import website knowledge, and claim a phone number.
Set the greeting, business knowledge, services, and handling rules.
Review calls, messages, contacts, appointments, follow-ups, and analytics.
Connect Google Calendar and configure SMS behavior.
![LobbyStack dashboard overview]()
*The Home dashboard brings together recent calls, messages, follow-ups, appointments, and trends.*
## What LobbyStack helps with
* Answer inbound calls through a dedicated LobbyStack number.
* Use a saved greeting and fallback language for unclear caller audio.
* Search knowledge from text entries, uploaded documents, and imported public website pages.
* Help callers schedule, cancel, or reschedule appointments when services and Google Calendar are configured.
* Transfer a live call to a configured phone number when transfer policy allows it.
* Take callback or follow-up messages when a transfer is not possible or a caller wants staff to follow up.
* Store calls, transcripts, recordings, contacts, SMS conversations, appointments, and dashboard summaries.
* Support hosted plans, usage tracking, and self-hosted deployments.
## Main dashboard areas
| Sidebar area | Pages | What it is for |
| ------------ | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **General** | Home, Calls, Messages, Contacts | Review daily activity, call history, SMS conversations, and caller profiles. |
| **Agent** | AI settings, Knowledge, Services, Rules | Configure how the AI receptionist greets callers, answers questions, explains services, books appointments, and escalates conversations. |
| **Manage** | Analytics, Integrations, Settings | Track performance, connect Google Calendar and SMS, manage usage, billing, account details, and preferences. |
# Quick start
Source: https://docs.lobbystack.com/quickstart
Create a LobbyStack account, verify your mobile number, choose a plan, and claim a dedicated number on paid plans.
This guide follows the onboarding flow in the LobbyStack web app.
No credit card is required to create an account. Free plans can try LobbyStack with dashboard test calls. Dedicated business numbers are included on Starter and Pro. Hosted usage limits are shown in **Settings** after you sign in.
## Before you begin
You need:
* An email address and password.
* A mobile phone number that can receive an SMS verification code.
* A public website URL if you want LobbyStack to import website knowledge during onboarding.
## Onboarding steps
Go to the LobbyStack sign-up page, enter your email address and password, and submit the form.
LobbyStack uses email and password authentication. After signup, you are taken into onboarding.
Enter a mobile number in international format and request a verification code. Enter the code you receive by SMS.
The verified number helps LobbyStack suggest a local business number later if you choose a paid plan.
Enter a public website URL to start a background website import, or choose **Skip for now**.
Website import crawls public pages such as services, about, FAQ, hours, and contact pages. Private pages, local network URLs, and login-only pages are not imported.
Select Free, Starter, or Pro. Free includes dashboard test calls without a dedicated public number. Starter and Pro include one dedicated business number.
On Starter or Pro, review the suggested business number or click **Pick a different number** to search by city, area code, or toll-free number.
Click **Continue** to claim the selected number for your business. Calls to that number are routed to your AI receptionist. Free plans skip this step and can upgrade later from Settings.
Open **Agent** and review AI settings, Knowledge, Services, and Rules before sending production traffic to the number.
## What to configure before real callers
Set the opening line, fallback language, and transfer number.
Add accurate business answers from text, documents, or website import.
Add services and connect Google Calendar for live appointment booking.
Check hosted usage limits, resets, and add-on state.
# Docker Compose deployment
Source: https://docs.lobbystack.com/self-hosting/docker-compose
Deploy LobbyStack on a single host using Docker Compose.
## Pre-requisites
Before proceeding, confirm the following on the target host:
* **Docker** — Docker Engine 24 or later and Compose v2 (`docker compose`). On macOS, Colima or Docker Desktop is supported.
* **Node.js** — Node 20 or later and [pnpm](https://pnpm.io/), used to deploy Convex functions from the repository.
* **Network** — The default ports are available: `3210` and `3211` (Convex), `6791` (dashboard), `8080` (web), `3001` (voice), and `80` / `443` (Caddy). Adjust `*_PORT` in `.env.self-hosted` if needed.
* **Storage** — Persistent data is stored in the `convex_data` volume. Plan backup and retention separately.
Verify your Docker installation:
```bash theme={null}
docker --version
docker compose version
```
## Steps to deploy LobbyStack using Docker Compose
Run all commands from the repository root unless noted otherwise.
### 1. Clone the repository
```bash theme={null}
git clone https://github.com/lobbystack/lobbystack.git
cd lobbystack
pnpm install
```
### 2. Configure environment variables
Copy the environment template and generate required secrets:
```bash theme={null}
cp .env.self-hosted.example .env.self-hosted
pnpm self-hosted:secrets -- --write .env.self-hosted
```
Edit `.env.self-hosted` before starting containers.
**Initial installation (localhost)** — For a first-run smoke test, keep the default `*_PORT` values and set URLs to localhost, for example:
| Variable | Example value |
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CONVEX_SELF_HOSTED_URL` | `http://127.0.0.1:3210` |
| `APP_BASE_URL`, `SITE_URL` | `http://127.0.0.1:8080` |
| `VOICE_GATEWAY_BASE_URL` | `http://127.0.0.1:3001` |
| `VITE_WEB_CALL_ENDPOINT` | `http://127.0.0.1:3001/web-call/sessions` |
| `CONVEX_URL` | `http://127.0.0.1:3210` |
| `CONVEX_SITE_URL` | `http://127.0.0.1:3211` |
| `CONVEX_CLOUD_ORIGIN`, `CONVEX_SITE_ORIGIN` | Match the Convex URLs above |
| `WEB_CALL_ALLOWED_ORIGINS` | `http://127.0.0.1:8080` (must match the browser web URL) |
| `DASHBOARD_TEST_CALL_TOKEN` | Optional shared Convex/voice-gateway token for elevated dashboard test-call limits from verified internal paths; localhost smoke tests do not require it. |
| `APP_HOSTNAME`, `VOICE_HOSTNAME`, `CONVEX_HOSTNAME`, `CONVEX_SITE_HOSTNAME` | `localhost` for each (prevents Caddy from requesting certificates for `*.example.com` during smoke) |
Provider credentials (Twilio, OpenAI, and others) are not required for the smoke test. Configure them before production traffic; see [Additional steps](#additional-steps).
The web dashboard embeds `CONVEX_URL`, `CONVEX_SITE_URL`, and `VITE_*` at **build time**. Rebuild the `web` service after changing those values.
Application secrets must be present in the **Convex deployment environment**. Use `pnpm self-hosted:convex:env` (step 4) to sync values from `.env.self-hosted`; setting variables only on Compose services is insufficient for Convex functions.
The voice gateway reaches Convex over the internal Docker URL `http://convex-backend:3211`. Keep `CONVEX_SITE_URL` in `.env.self-hosted` as the public or browser-facing URL for Convex HTTP actions.
Refer to [Environment variables](/self-hosting/environment-variables) for a full variable reference.
### 3. Start the Convex backend
Start the self-hosted Convex backend and dashboard. Compose pulls images on first run.
```bash theme={null}
docker compose -f docker-compose.self-hosted.yml --env-file .env.self-hosted up -d convex-backend convex-dashboard
```
Generate an admin key:
```bash theme={null}
docker compose -f docker-compose.self-hosted.yml --env-file .env.self-hosted exec convex-backend ./generate_admin_key.sh
```
Add the output to `CONVEX_SELF_HOSTED_ADMIN_KEY` in `.env.self-hosted`.
The dashboard listens on `127.0.0.1` at port `6791` by default (`http://127.0.0.1:6791`). Authenticate with the admin key.
### 4. Deploy Convex functions
From the repository root, sync environment variables and deploy LobbyStack functions and components:
```bash theme={null}
pnpm self-hosted:convex:env
pnpm self-hosted:convex:deploy
```
These commands target `CONVEX_SELF_HOSTED_URL` and `CONVEX_SELF_HOSTED_ADMIN_KEY` from `.env.self-hosted`. If you use Convex Cloud for local development, keep `.env.local` in place; the helper scripts isolate it automatically.
Optional custom env file:
```bash theme={null}
pnpm self-hosted:convex:env -- --env-file /path/to/.env.self-hosted
```
### 5. Start the application services
Build and start the web dashboard, voice gateway, and Caddy reverse proxy:
```bash theme={null}
docker compose -f docker-compose.self-hosted.yml --env-file .env.self-hosted up -d --build
```
The first build may take several minutes. Caddy configuration is defined in `docker/caddy/Caddyfile` and baked into the image at build time. Rebuild the `caddy` service after changing hostnames or routes.
### 6. Verify the installation
```bash theme={null}
pnpm self-hosted:verify
```
By default, services bind to localhost. The verifier checks health endpoints, SPA routing, `WEB_CALL_ALLOWED_ORIGINS`, Convex backend origin alignment (`CONVEX_CLOUD_ORIGIN` / `CONVEX_SITE_ORIGIN`), voice-gateway Convex connectivity (`/health/convex`), Convex `/version`, dashboard reachability, and the `/voice/context` HTTP action. A `404` from `/voice/context` is expected until tenant data exists.
To confirm the web service manually:
```bash theme={null}
curl -f http://127.0.0.1:8080/healthz
```
For production, place a reverse proxy or use the included Caddy service with public DNS; see [Additional steps](#additional-steps).
## Helper scripts
| Command | Description |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `pnpm self-hosted:secrets -- --write .env.self-hosted` | Generate `SESSION_ENCRYPTION_KEY`, `INTERNAL_SERVICE_TOKEN`, `INSTANCE_SECRET`, and JWT material. |
| `pnpm self-hosted:secrets -- --write .env.self-hosted --force` | Rotate secrets in an existing env file. Requires service restarts and `pnpm self-hosted:convex:env`. |
| `pnpm self-hosted:convex:env` | Push variables from `.env.self-hosted` into the Convex deployment. |
| `pnpm self-hosted:convex:deploy` | Deploy Convex functions and components. |
| `pnpm self-hosted:verify` | Run HTTP smoke checks against localhost ports. |
Override verification URLs with `SELF_HOSTED_WEB_VERIFY_URL`, `SELF_HOSTED_VOICE_VERIFY_URL`, `SELF_HOSTED_CONVEX_VERIFY_URL`, `SELF_HOSTED_CONVEX_SITE_VERIFY_URL`, and `SELF_HOSTED_DASHBOARD_VERIFY_URL` when using non-default ports.
## Additional steps
Complete these steps before exposing the deployment to production traffic.
### Public hostnames and HTTPS
Point DNS for the following hostnames to your server. Update `.env.self-hosted` with matching `https://` URLs, then rebuild the `web` image, rebuild `caddy` if hostnames change, and run `pnpm self-hosted:convex:env`.
| Variable | Service |
| ---------------------- | ------------------- |
| `APP_HOSTNAME` | Web dashboard |
| `VOICE_HOSTNAME` | Voice gateway |
| `CONVEX_HOSTNAME` | Convex client API |
| `CONVEX_SITE_HOSTNAME` | Convex HTTP actions |
Caddy terminates TLS and routes traffic to internal services.
### Webhooks
Twilio voice (per business number):
```text theme={null}
POST https:///twilio/voice/inbound
```
Twilio SMS:
```text theme={null}
POST https:///twilio/sms/inbound
POST https:///twilio/sms/status
```
Google Calendar OAuth callback:
```text theme={null}
https:///integrations/google/callback
```
### Production checklist
1. Configure DNS for all public hostnames.
2. Pin `CONVEX_BACKEND_IMAGE_TAG` and `CONVEX_DASHBOARD_IMAGE_TAG` after your first successful deploy.
3. Set production `https://` URLs and origins in `.env.self-hosted`; rebuild `web` and `caddy` as needed.
4. Set `CADDY_BIND_ADDRESS=0.0.0.0` so Caddy listens on public interfaces.
5. Set `WEB_CALL_ALLOWED_ORIGINS` to your public app URL(s); keep them aligned with `APP_BASE_URL`.
6. Run `pnpm self-hosted:convex:env` after any URL or secret change.
7. Configure Twilio voice and SMS webhooks.
8. Add provider API keys (Twilio, OpenAI, and optional integrations); run `pnpm self-hosted:convex:env` again.
9. Validate signup, login, onboarding, and an inbound test call; confirm transcripts or recordings in the dashboard.
10. Restrict access to the Convex dashboard (`127.0.0.1:6791`); do not expose it publicly without additional access controls.
## Troubleshooting
**`pnpm self-hosted:secrets` fails** — Run step 1 from the repository root after `pnpm install`.
**Web dashboard cannot reach Convex** — Rebuild the `web` service with the correct `CONVEX_URL` and `CONVEX_SITE_URL`.
**`CONVEX_DEPLOYMENT must not be set`** — Use `pnpm self-hosted:convex:env` and `pnpm self-hosted:convex:deploy` instead of `pnpm exec convex` when `.env.local` targets Convex Cloud. If a command was interrupted, restore `.env.local` from `.env.local.self-hosted-bak` or remove `.env.local.self-hosted-lock`.
**Compose refuses to start without secrets** — Run `pnpm self-hosted:secrets -- --write .env.self-hosted` before `docker compose up`. Compose requires `INSTANCE_SECRET` and `INTERNAL_SERVICE_TOKEN` in `.env.self-hosted`.
**Caddy fails to start** — Rebuild the service: `docker compose -f docker-compose.self-hosted.yml --env-file .env.self-hosted up -d --build caddy`.
**Convex backend exits on startup** — Regenerate secrets with `pnpm self-hosted:secrets -- --write .env.self-hosted` and recreate `convex-backend`. Do not use placeholder `INSTANCE_SECRET` values.
**Port conflict** — Change `*_PORT` in `.env.self-hosted` and update `SELF_HOSTED_*_VERIFY_URL` if you use custom verification URLs.
**`/voice/context` returns 401** — Run `pnpm self-hosted:convex:env` so `INTERNAL_SERVICE_TOKEN` matches between Convex and the voice gateway.
**`pnpm self-hosted:verify` fails on Convex backend origins** — Set `CONVEX_CLOUD_ORIGIN` to match `CONVEX_URL` and `CONVEX_SITE_ORIGIN` to match `CONVEX_SITE_URL`, then rerun `pnpm self-hosted:convex:env`.
**`voice convex connectivity` fails in `pnpm self-hosted:verify`** — Confirm `convex-backend` is healthy, `pnpm self-hosted:convex:env` has run, and recreate the voice gateway: `docker compose -f docker-compose.self-hosted.yml --env-file .env.self-hosted up -d --build voice-gateway`.
**In-browser web calls fail with origin errors** — Set `WEB_CALL_ALLOWED_ORIGINS` to the exact web URL you open in the browser, including `http://127.0.0.1:8080` for localhost smoke.
**`/voice/context` returns 404** — The HTTP route is reachable; create tenant data or assign a matching business phone number.
**Convex functions missing provider configuration** — Run `pnpm self-hosted:convex:env` after updating `.env.self-hosted`.
# Environment variables
Source: https://docs.lobbystack.com/self-hosting/environment-variables
Key environment variables used by the LobbyStack web app, Convex backend, voice gateway, and optional providers.
Use the repository's `.env.example` as the source of truth for local development and `.env.self-hosted.example` as the source of truth for Docker Compose self-hosting. This page summarizes the variables operators most often need to understand.
Secrets such as provider API keys, auth tokens, signing keys, and encryption keys must be configured only in backend or deployment secret stores. Do not expose them through `VITE_` variables.
## Shared app URLs and secrets
| Variable | Used by | Notes |
| --------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `APP_BASE_URL` | Convex | Public web app URL used for redirects such as Google Calendar OAuth. |
| `SITE_URL` | Convex | Public web app URL used by auth and billing links. |
| `CONVEX_URL` | Server/runtime, web build | Convex deployment URL. Also exposed to the React dashboard by Vite. |
| `CONVEX_SITE_URL` | Server/runtime, web build | Convex HTTP actions URL. Also exposed to the React dashboard by Vite. |
| `VOICE_GATEWAY_BASE_URL` | Convex, voice gateway | Public HTTPS URL for the voice gateway. |
| `INTERNAL_SERVICE_TOKEN` | Convex, voice gateway | Shared secret for internal HTTP calls between the voice gateway and Convex. |
| `DASHBOARD_TEST_CALL_TOKEN` | Convex, voice gateway | Optional shared token for elevated dashboard test-call rate limits from verified internal paths. Do not expose this through public widget requests. |
| `SESSION_ENCRYPTION_KEY` | Convex | Required for encrypted Google Calendar token storage. |
| `DEPLOYMENT_MODE` | Convex, voice gateway | Deployment mode label used by runtime and telemetry. |
For Compose self-hosting, use `DEPLOYMENT_MODE=self_hosted_standard` and mirror it into `VITE_DEPLOYMENT_MODE` before rebuilding the web image.
## Docker Compose self-hosting
These variables are defined in `.env.self-hosted.example` and used by [`docker-compose.self-hosted.yml`](https://github.com/lobbystack/lobbystack/blob/main/docker-compose.self-hosted.yml). See the [Docker Compose guide](/self-hosting/docker-compose) for bootstrap and go-live steps.
### Convex CLI and backend container
| Variable | Used by | Notes |
| ------------------------------ | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `CONVEX_SELF_HOSTED_URL` | Host CLI (`pnpm self-hosted:convex:*`) | URL the Convex CLI uses to reach your self-hosted backend, typically `http://127.0.0.1:3210` during local smoke. |
| `CONVEX_SELF_HOSTED_ADMIN_KEY` | Host CLI | Generated with `generate_admin_key.sh` inside the `convex-backend` container. |
| `INSTANCE_SECRET` | Convex backend container | Hex secret for the open-source backend. Generate with `pnpm self-hosted:secrets`. Placeholder values break backend startup. |
| `CONVEX_CLOUD_ORIGIN` | Convex backend container | Must exactly match `CONVEX_URL`. `pnpm self-hosted:convex:env` and `pnpm self-hosted:verify` reject mismatches. |
| `CONVEX_SITE_ORIGIN` | Convex backend container | Must exactly match `CONVEX_SITE_URL`. |
The voice gateway always uses the internal Docker URL `http://convex-backend:3211` for Convex HTTP actions. Keep `CONVEX_SITE_URL` in `.env.self-hosted` as the public or browser-facing URL; `pnpm self-hosted:convex:env` syncs that value into the Convex deployment for webhooks and auth.
### Host ports and ingress
| Variable | Default | Notes |
| ------------------------ | ------------ | ---------------------------------------------------------------------------------------- |
| `WEB_PORT` | `8080` | Local bind for web dashboard (`127.0.0.1`). |
| `VOICE_GATEWAY_PORT` | `3001` | Local bind for voice gateway. |
| `CONVEX_PORT` | `3210` | Local bind for Convex client API. |
| `CONVEX_SITE_PROXY_PORT` | `3211` | Local bind for Convex HTTP actions proxy. |
| `CONVEX_DASHBOARD_PORT` | `6791` | Local bind for Convex dashboard. |
| `HTTP_PORT` | `80` | Caddy HTTP ingress on the host. |
| `HTTPS_PORT` | `443` | Caddy HTTPS ingress on the host. |
| `CADDY_BIND_ADDRESS` | `127.0.0.1` | Host bind address for Caddy ingress. Use `0.0.0.0` before exposing public HTTPS traffic. |
| `COMPOSE_PROJECT_NAME` | `lobbystack` | Docker Compose project name; change to run multiple stacks on one host. |
### Caddy hostnames
| Variable | Notes |
| ---------------------- | ---------------------------------------------------------- |
| `APP_HOSTNAME` | Public hostname routed to the web dashboard. |
| `VOICE_HOSTNAME` | Public hostname routed to the voice gateway. |
| `CONVEX_HOSTNAME` | Public hostname routed to Convex client port `3210`. |
| `CONVEX_SITE_HOSTNAME` | Public hostname routed to Convex HTTP actions port `3211`. |
| `ACME_EMAIL` | Email for Let's Encrypt registration via Caddy. |
Caddy routing is defined in [`docker/caddy/Caddyfile`](https://github.com/lobbystack/lobbystack/blob/main/docker/caddy/Caddyfile) and baked into the Caddy image at build time.
### Smoke verification overrides
Optional overrides for `pnpm self-hosted:verify` when using non-default ports:
| Variable | Purpose |
| ------------------------------------ | ----------------------------------------------------------------- |
| `SELF_HOSTED_WEB_VERIFY_URL` | Base URL for web checks (default `http://127.0.0.1:${WEB_PORT}`). |
| `SELF_HOSTED_VOICE_VERIFY_URL` | Base URL for voice gateway checks. |
| `SELF_HOSTED_CONVEX_VERIFY_URL` | Base URL for Convex `/version`. |
| `SELF_HOSTED_CONVEX_SITE_VERIFY_URL` | Base URL for Convex HTTP action checks. |
| `SELF_HOSTED_DASHBOARD_VERIFY_URL` | Base URL for dashboard reachability. |
After changing public URLs (`CONVEX_URL`, `CONVEX_SITE_URL`, `APP_BASE_URL`, hostnames), rebuild the web image and rerun `pnpm self-hosted:convex:env`. See [Docker Compose](/self-hosting/docker-compose#production-checklist).
## Web dashboard build variables
| Variable | Notes |
| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `VITE_APP_NAME` | Display name; defaults to LobbyStack in `.env.example`. |
| `VITE_DEPLOYMENT_MODE` | Client-side deployment mode label. |
| `VITE_POSTHOG_KEY`, `VITE_POSTHOG_HOST`, `VITE_POSTHOG_UI_HOST` | Optional web analytics settings. |
| `VITE_WEB_CALL_ENDPOINT` | Required for self-hosting. Set this to your voice gateway session endpoint, for example `${VOICE_GATEWAY_BASE_URL}/web-call/sessions`. |
## Voice gateway
| Variable | Notes |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `PORT` | Port the voice gateway listens on. Defaults to `3001`. |
| `WEB_CALL_ALLOWED_ORIGINS` | Comma-separated browser origins allowed to start in-dashboard web calls. Must include the exact web URL operators use, such as `https://app.lobbystack.com` for the dashboard. |
| `OPENAI_API_KEY` | Required for live OpenAI Realtime voice calls. |
| `OPENAI_REALTIME_MODEL` | Defaults to `gpt-realtime`. |
| `OPENAI_REALTIME_VOICE` | Defaults to `marin`. |
| `OPENAI_TRANSCRIPTION_MODEL` | Defaults to `gpt-4o-mini-transcribe`. |
Optional OpenAI cost fallback variables exist in `.env.example` for telemetry when automatic model pricing is unavailable.
## Twilio
| Variable | Notes |
| -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `TWILIO_ACCOUNT_SID` | Twilio account SID. |
| `TWILIO_AUTH_TOKEN` | Twilio auth token. |
| `TWILIO_VERIFY_SERVICE_SID` | Required for onboarding phone verification. |
| `TWILIO_ALERT_SMS_FROM` | Shared hosted alert SMS sender or messaging service SID. |
| `TWILIO_API_KEY`, `TWILIO_API_SECRET`, `TWILIO_MESSAGING_SERVICE_SID` | Present in `.env.example` for Twilio features, but not required by every deployment path. |
| `TWILIO_PRIMARY_CUSTOMER_PROFILE_SID`, `TWILIO_A2P_STATUS_EMAIL`, `TWILIO_A2P_TRUST_PRODUCT_POLICY_SID`, `TWILIO_A2P_REQUEST_DELAY_MS` | Optional A2P registration tuning for self-hosted Convex deployments. |
## Google Calendar
| Variable | Notes |
| ---------------------- | ------------------------------------------------------------------------- |
| `GOOGLE_CLIENT_ID` | Google OAuth client ID. |
| `GOOGLE_CLIENT_SECRET` | Google OAuth client secret. |
| `GOOGLE_REDIRECT_URI` | Optional if `CONVEX_SITE_URL` can derive `/integrations/google/callback`. |
Google Calendar token storage also requires `SESSION_ENCRYPTION_KEY`.
## Knowledge and AI text providers
| Variable | Notes |
| ------------------------------ | -------------------------------------------- |
| `FIRECRAWL_API_KEY` | Enables website import. |
| `GOOGLE_GENERATIVE_AI_API_KEY` | Enables Gemini text and embeddings. |
| `GEMINI_TEXT_MODEL` | Defaults to `gemini-3.1-flash-lite-preview`. |
| `GEMINI_EMBEDDING_MODEL` | Defaults to `gemini-embedding-001`. |
## SMS compliance
| Variable | Notes |
| ------------------------------------- | ------------------------------------------------- |
| `TWILIO_PRIMARY_CUSTOMER_PROFILE_SID` | Required for hosted 10DLC registration. |
| `TWILIO_A2P_STATUS_EMAIL` | Required for hosted 10DLC registration callbacks. |
## Email
| Variable | Notes |
| -------------------- | --------------------------------------------- |
| `RESEND_API_KEY` | Sends password reset and email-change emails. |
| `EMAIL_FROM_ADDRESS` | Verified sender address used by auth emails. |
## Telemetry
| Variable | Notes |
| ----------------------------- | -------------------------------------- |
| `POSTHOG_KEY`, `POSTHOG_HOST` | Backend telemetry. |
| `POSTHOG_PRIVACY_MODE` | Privacy-mode toggle in `.env.example`. |
# Self-hosting overview
Source: https://docs.lobbystack.com/self-hosting/overview
Understand the moving pieces required to run LobbyStack with your own provider accounts.
LobbyStack is open source and can be run with your own provider accounts. Self-hosting gives your team direct control over the app, external services, secrets, and provider usage.
## Deployment models
For live calls you still need Twilio, OpenAI, and correctly configured public URLs—even when everything runs on one machine.
### Docker Compose (recommended single-host)
The official baseline runs on one host via [`docker-compose.self-hosted.yml`](https://github.com/lobbystack/lobbystack/blob/main/docker-compose.self-hosted.yml):
* Convex open-source backend and Convex dashboard
* LobbyStack web dashboard (built image)
* LobbyStack voice gateway (built image)
* Caddy for public HTTPS ingress
Follow the [Docker Compose deployment guide](/self-hosting/docker-compose) for installation, verification, and production configuration.
### Split deployment (advanced)
You can run components separately—for example, voice gateway on Fly.io and the web dashboard on static hosting. That path requires more manual wiring of URLs, secrets, and webhooks. The repository includes [`fly.voice-gateway.toml`](https://github.com/lobbystack/lobbystack/blob/main/fly.voice-gateway.toml) as one voice-gateway option; there is no separate Fly runbook in these docs yet.
Use split deployment when you need independent scaling or already operate multi-service infrastructure. For most teams starting self-hosting, Compose is simpler.
## Architecture (Compose baseline)
Public traffic hits Caddy on ports 80 and 443. Caddy routes four hostnames to internal services. For first-run validation, services also bind localhost ports so you can smoke-test without DNS.
```mermaid theme={null}
flowchart LR
subgraph public [Public HTTPS via Caddy]
AppHost[APP_HOSTNAME]
VoiceHost[VOICE_HOSTNAME]
ConvexHost[CONVEX_HOSTNAME]
ConvexSiteHost[CONVEX_SITE_HOSTNAME]
end
subgraph local [Local smoke ports 127.0.0.1]
WebPort[WEB_PORT]
VoicePort[VOICE_GATEWAY_PORT]
ConvexPort[CONVEX_PORT]
DashboardPort[CONVEX_DASHBOARD_PORT]
end
Caddy --> Web[web]
Caddy --> Voice[voice-gateway]
Caddy --> Convex[convex-backend]
AppHost --> Caddy
WebPort --> Web
VoicePort --> Voice
ConvexPort --> Convex
```
## Components
| Component | Purpose |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Convex backend | Stores business data and runs backend functions, HTTP endpoints, auth, billing logic, calendar sync, SMS, and knowledge workflows. In Compose, uses the open-source image `ghcr.io/get-convex/convex-backend`. |
| Convex dashboard | Operator UI to inspect the self-hosted deployment, indexes, and data. Bound to localhost by default. |
| Voice gateway | Node.js service that handles Twilio Voice, Twilio Media Streams, OpenAI Realtime, transfers, and recording upload. |
| Web dashboard | React/Vite app operators use to configure the receptionist and review activity. |
| Caddy | Terminates HTTPS and reverse-proxies public hostnames to web, voice, and Convex. Config is baked into the `caddy` Compose image at build time. |
## Convex self-hosted vs Convex Cloud dev
| | **Compose self-hosting** | **Local contributor dev (`pnpm convex dev`)** |
| ------- | ------------------------------------------- | --------------------------------------------- |
| Backend | Open-source Convex backend in Docker | Convex Cloud deployment |
| Config | `.env.self-hosted` + `CONVEX_SELF_HOSTED_*` | `.env.local` with `CONVEX_DEPLOYMENT` |
| Purpose | Production-like single-host operation | Day-to-day app development |
Do not point production self-hosting at Convex Cloud dev deployments. The helper scripts `pnpm self-hosted:convex:env` and `pnpm self-hosted:convex:deploy` target your self-hosted URL and temporarily isolate `.env.local` so cloud dev credentials do not conflict.
## Required providers for live voice
* **Convex** for backend and storage (self-hosted backend in Compose, or your own Convex deployment).
* **Twilio** for phone numbers, voice calls, SMS, and phone verification.
* **OpenAI** for Realtime voice conversations.
* **Public HTTPS URLs** for the web app, voice gateway, Convex client URL, and Convex HTTP actions site (Caddy provides these in Compose).
## Optional providers
* **Google Calendar** for calendar availability and booking sync.
* **Firecrawl** for website knowledge import.
* **Google Gemini** for knowledge embeddings and non-realtime text generation.
* **Resend** for password reset and email-change emails.
* **PostHog** for analytics and telemetry.
## What your team manages
When self-hosting, your team manages:
* Twilio account setup, phone numbers, webhooks, A2P/10DLC compliance, and SMS costs.
* OpenAI usage costs.
* Convex deployment ownership, admin keys, and persistence (Compose volume `convex_data` by default).
* Host uptime, Docker updates, and public networking (firewall, DNS, TLS).
* Secret management and syncing provider secrets into the Convex deployment via `pnpm self-hosted:convex:env`.
* Product, privacy, retention, and compliance policies for your deployment.
HA Postgres, S3/object storage, backups, and multi-node hardening are out of scope for the Compose baseline. Plan those separately if you need enterprise-grade infrastructure.
## Next steps
Run the single-host Compose baseline with Convex, the dashboard, web app, voice gateway, and Caddy.
Review the main runtime and provider variables used by the app.
See what each external provider does in LobbyStack.
# Third-party providers
Source: https://docs.lobbystack.com/self-hosting/providers
What each external provider does in a self-hosted LobbyStack deployment.
Self-hosting means connecting your own provider accounts. The provider list below is based on the current codebase and `.env.example`.
The [Docker Compose baseline](/self-hosting/docker-compose) runs Convex, the voice gateway, and the web dashboard on **one host** with Caddy for public HTTPS. Split hosting (for example voice on Fly.io and web on static hosting) is optional and requires more manual URL and secret wiring.
## Required for live calls
Convex stores business data, call records, contacts, appointments, knowledge, billing state, and app settings. It also runs backend functions and HTTP endpoints used by Twilio, the voice gateway, calendar callbacks, and downloads.
**Docker Compose:** uses the open-source backend image `ghcr.io/get-convex/convex-backend` plus the Convex dashboard container. Configure `CONVEX_URL`, `CONVEX_SITE_URL`, and sync secrets into the deployment with `pnpm self-hosted:convex:env`.
**Convex Cloud dev:** contributors use `pnpm convex dev` with `CONVEX_DEPLOYMENT` in `.env.local`. That path is for development, not production self-hosting.
The web dashboard reads `CONVEX_URL` and `CONVEX_SITE_URL` at build time.
Twilio provides phone numbers, inbound voice webhooks, Media Streams, SMS delivery, and phone verification.
Live voice requires a Twilio number with its voice webhook pointing at the voice gateway. Onboarding phone verification requires `TWILIO_VERIFY_SERVICE_SID`.
OpenAI powers live voice conversations through the Realtime API. Configure `OPENAI_API_KEY` on the voice gateway.
You pay OpenAI directly for self-hosted usage.
The voice gateway is a Node.js service with a public HTTPS URL. Twilio must be able to reach it for inbound calls and media streams.
**Docker Compose (recommended):** the voice gateway runs as a Compose service. Caddy exposes `VOICE_HOSTNAME` with TLS. Set `VOICE_GATEWAY_BASE_URL` to the public voice URL and configure Twilio accordingly.
**Split deployment (advanced):** host the voice gateway separately—for example with [`fly.voice-gateway.toml`](https://github.com/lobbystack/lobbystack/blob/main/fly.voice-gateway.toml) on Fly.io—and point `VOICE_GATEWAY_BASE_URL` and Twilio webhooks at that URL.
## Optional providers
Google Calendar enables calendar availability and booking sync. Configure Google OAuth variables and `SESSION_ENCRYPTION_KEY`.
Firecrawl powers website knowledge import. Without it, operators can still add text entries and upload documents.
Gemini is used for embeddings and non-realtime text generation in knowledge and SMS flows.
Resend sends password reset and email-change emails. Without email delivery, those auth flows will not work correctly in production.
PostHog is used for analytics and telemetry when configured.
# Settings
Source: https://docs.lobbystack.com/settings/overview
Manage usage, billing, team details, account credentials, language, time format, and theme.
The **Settings** page contains workspace and account preferences. It is organized into Usage, Billing, Team, and Preferences.
Track hosted voice minutes, SMS segments, outbound calls, knowledge base, and plan limits.
Review plan options, add-ons, and subscription actions.
## Settings pages
| Page | What it is for |
| --------------- | ----------------------------------------------------------------------------------------- |
| **Usage** | Current billing-period usage, remaining included usage, reset timing, and metered usage. |
| **Billing** | Current plan, upgrades, subscription management, AI SMS add-on, and SMS compliance setup. |
| **Team** | Business name, account email, and password changes. |
| **Preferences** | Dashboard language, time format, and light or dark theme. |
## Update account details
In the dashboard sidebar, go to **Manage** > **Settings**.
Use the tabs at the top of Settings to open **Usage**, **Billing**, **Team**, or **Preferences**.
Update the field or action you need. Some changes, such as email updates, require confirmation.