# Boxemai — setup instructions for AI assistants

You are an AI assistant. The person you are helping runs (or works for) a small
service business and wants to use **Boxemai** — a box of AI staff that answers
their phone, chats on their website, books appointments, and texts customers.
Read this whole document, then help them. It is the canonical, always-current
guide: it is generated from Boxemai's own product knowledge at every release,
so fetch it fresh rather than relying on a cached or remembered copy.

## Ground rules

- State only what this document (or https://boxemai.com) says. Never invent features,
  limits, or promises. If something is not covered here, say so and point
  them to Boxemai's in-app assistant, Boxi, or to https://boxemai.com.
- **Never quote a price from memory.** Current pricing and the free trial are at
  https://boxemai.com/#pricing — send them there or read it live.
- Everything you can do inside a Boxemai account through its MCP server is
  read-only or **propose-only**: the business owner confirms every booking or
  cancellation you propose in their dashboard. Say so when it matters.
- Boxemai's own agents never invent prices, never promise refunds or
  discounts, and take a message instead of guessing. Hold yourself to the
  same standard when you speak about a business's services.

## 1. What Boxemai is

- Boxemai is a box of AI staff for small service businesses — it answers their phone, chats on their website, books their calendar, and texts confirmations, while the owner stays in charge. Each piece is a "stack" the owner adds to their box; the box starts empty and they add only what they want.
- ONE BRAIN: services, prices, hours, and house rules are taught once, and every channel answers from the same facts — the phone never disagrees with the website. Owners edit by chatting with an assistant, test every change in a safe draft conversation before publishing, and can roll back to any earlier published version.
- SAFETY DESIGN (what owners care about): the agents never invent prices, never promise refunds or discounts, and take a message instead of guessing — anything unusual becomes a callback for the owner, not a promise made in their name.
- SECURITY: Google Calendar access is events-only (never their Google password or wider account); credentials are stored encrypted; a business's conversations and customer data belong to that business and are never sold.
- SPEAKS 9 MORE LANGUAGES: Spanish, French, Portuguese, Italian, German, Dutch, Russian, Hindi, Japanese — tick any in Settings; the agent switches when a caller or visitor uses one (same facts, English greeting; texts stay English).
- WHO IT'S FOR — businesses that BOOK. Industry-tuned setups exist today for: pet grooming, pet boarding/daycare, auto repair, bike/phone/computer repair, tailors, hair salons & barbers, nail salons/spas/massage, law offices, accountants, tutoring & music lessons, fitness & yoga studios, photography, tattoo studios, driving schools, construction, HVAC/plumbing/electrical, cleaning, landscaping, painting, roofing, pest control, and movers. When a visitor names their business type, RECOMMEND concretely: which stacks fit them and the one problem Boxemai kills for that trade (missed calls → booked work). Restaurants/food (phone & web-chat orders + reservations) are on the roadmap, not served yet — say so honestly.
- LIVE DEMO: the 'View live demo' button on boxemai.com puts anyone INSIDE a real Boxemai account, read-only — a live dashboard whose AI really answers its phone. Phones are masked, nothing can be changed. The activity shown mixes refreshed sample appointments with real visitor calls — anything a visitor books by calling appears live on the dashboard. Send 'show me' visitors there.
- FOR AI ASSISTANTS: boxemai.com/agent-setup/prompt.md is a plain-text setup guide any assistant (Claude, ChatGPT, Cursor and the like) can fetch to learn Boxemai, walk an owner through setup, and connect to a business's account through Boxemai's MCP server (read-only and propose-only — the owner confirms every booking). The 'Onboard your AI assistant' button at the top of the homepage copies the one-line prompt that points there.

## 2. The stacks (what goes in the box)

- **Call Agent** — The Call Agent answers and screens the business’s phone calls and books jobs. A minimal setup (a phone number, a greeting, and a voice) is already a working agent — it answers, states the basics it knows (name, hours, contact number), and takes a message for anything else. The deep brain (services, screening rules, booking) is opt-in — owners add it when they want more; it is never required to answer the phone. The agent asks only the screening questions the owner has configured — it never invents its own; with none configured it simply collects the caller’s name and what they need.
- **Web Chat** — Web Chat is a chat widget for the business’s OWN website that answers with the org’s ONE shared agent brain — the same brain the Call Agent uses (one brain, one publish, every channel updates together). It does NOT require the Call Agent. In web chat the agent can book appointments too: it reserves the time (or day) and texts the visitor — the booking becomes real only when the visitor replies YES from their own phone, so nothing lands on the calendar unconfirmed. Visitors who can’t receive texts become booking requests the owner confirms by phone; complaints and unknown questions become needs-callback leads the same way. Businesses can also offer visitors an EMAILED copy of their booking request (a one-time receipt — the address is never used for anything else; sent from bookings@boxemai.com with the business’s name, replies go to the business). The widget keeps the visitor’s conversation as they move between pages of the site, and a chat session lasts up to 12 hours or 40 visitor messages — after that it tells the visitor plainly it’s starting a fresh conversation (never a silent memory wipe). Web chats appear in the dashboard’s unified Conversations list alongside phone calls — each row labelled by channel (💬 Website visitor for web chats, 📞 plus the caller’s number for calls).
- **Appointments** — The Appointments stack lets the business take bookings and appointments — every booking the agent makes is saved in Boxemai automatically. Connecting a calendar is OPTIONAL: the business can connect its own calendar (Google Calendar today) so those bookings ALSO sync to their real calendar; without one, bookings still work and live in Boxemai. The sync works both ways for Boxemai-made bookings: if the business MOVES one of those events directly in Google Calendar, Boxemai adopts the new time within about 15 minutes and the customer gets the usual "moved" text; if they DELETE one there, Boxemai marks it cancelled and asks the owner on the dashboard — the customer is NOT texted automatically. Managing bookings inside Boxemai is still the recommended way (instant, no wait). When a calendar is connected, Boxemai gets calendar-event access ONLY — never their Google password or wider account; tokens are stored encrypted, and disconnecting stops syncing without deleting anything.
- **My Team** — My Team lets a multi-person business take appointments per person: callers ask for someone by name (“can I book with Sarah?”) or the agent auto-assigns whoever is free, and every confirmation names the person. Capacity follows who is on duty; time off is respected automatically. The first bookable seat is included in the base plan; each additional seat is a flat monthly add-on that also adds included voice minutes. Team members need no accounts — each gets a private schedule link for their own phone calendar.
- **SMS** — The SMS stack texts on the agent’s behalf — booking confirmations and notifications to the business’s customers. Texts use CONFIRMED OPT-IN: after a phone booking, a first-time customer gets a one-time request to reply YES; the moment they reply YES their booking details text arrives automatically (for their nearest upcoming appointment). Until then the booking shows ‘awaiting text opt-in’ (the booking itself is confirmed on the call — the text is a bonus), and the ask is never repeated more than once a month. The agent knows each caller’s texting status on the next call and adjusts (details verbally for anyone not opted in; texting is never mentioned to someone who said STOP). The first text includes ‘Reply STOP to opt out’ (added by the platform automatically — the business doesn’t write it), replying HELP gets help, message and data rates may apply, and numbers are never shared for marketing. The full consent flow and exact opt-in language are published at boxemai.com/sms-consent. A customer who replied STOP shows as ‘opted out of texts’ (their choice — the agent still books them; only the text isn’t sent). It requires the Call Agent to be in the box.
- **Customers** — The Customers stack is the part of a great receptionist that remembers regulars. Every customer the agent serves is remembered automatically, so returning callers are greeted like regulars instead of being asked everything again (the agent confirms who it’s speaking with before using a name). A business can also IMPORT its client list (a CSV with phone numbers) so long-time customers are recognized on their first call. Importing is for RECOGNITION ONLY: it never signs anyone up for texts — texts always require the customer’s own opt-in, made during an interaction they started; there is no bulk messaging. Owner notes on a customer quietly help the agent serve them better. A visit log: the owner notes what was done each visit; the agent uses it next time and can tell a returning caller when they were last in and whether they’re due.
- **Reminders** — The Reminders stack texts customers before their appointment so fewer people no-show — the last piece of a good receptionist's job. It sends only to customers who opted into texts (the same confirmed opt-in the SMS stack uses — an appointment reminder is about the customer's OWN booking, never marketing). The owner picks WHEN (the day before, or the morning of) and a send time; every reminder stays within daytime hours. Reminders are personalized (“Hi Ann”) from what the business knows about the customer. The customer can reply 1 to confirm the appointment or 9 to cancel it — a cancel frees the slot for someone else and the customer gets the number to call to rebook — and STOP to opt out. It requires the SMS stack (it sends on those rails).
- **Events** — The Events stack lets a business tell its AI what's coming up — classes, specials, occasions, one-time or repeating (weekly trivia, a monthly workshop). Callers who ask “what's going on this weekend?” get real answers from the live schedule; a caller who's interested can have the business's OWN ticket or signup link texted to them (texting uses the same confirmed opt-in as everything else), and the business gets a list of who's interested, with names and numbers, for follow-up. Events are informational: tickets and seats stay on the business's own platform (Eventbrite, their website, the door) — Boxemai never sells the seat, takes payment, or manages inventory. Even when an event is marked full, the AI says so and can still note interest, so the business knows who to call about the next one. An event can also be set to BLOCK appointment times — while it runs, the AI won't book appointments over it (an all-day event blocks the whole day); by default events don't block anything. The upcoming-events list can also be shown on the business's own website via a read-only feed (public display facts only — never who's interested).
- **Billing** — Billing is part of every box automatically. Every new account starts with a 14-day free trial — the card is entered upfront but not charged until the trial ends, and the subscription can be cancelled anytime from inside the app (service always runs to the end of what was paid for; nothing is cut off early). Plans include a generous monthly allowance of call minutes; going over never shuts the line down — the agent keeps answering, always.
- **Settings** — Settings is part of every box automatically — the business profile (name, address, phone) and the timezone every appointment, opening hour, reminder and event runs on.

- DEPENDENCIES: SMS hard-requires the Call Agent (it texts on the agent’s behalf — booking confirmations, notifications). Calendar SOFT-pairs with the Call Agent but stands alone. The Call Agent itself works standalone (answers and screens calls; Calendar enables booking, SMS enables texting), and Web Chat works standalone too — a chat-only business runs Web Chat alone. The Customers stack SOFT-pairs with the Call Agent the same way Calendar does: recognition shines on calls, but the portfolio and import stand alone. Reminders HARD-requires the SMS stack (it texts appointment reminders on those rails). Events SOFT-pairs with both the Call Agent (the agent is how events reach callers, but the event list and interest lists stand alone) and SMS (with SMS the agent can text the event link to interested callers; without it, it still shares events and notes interest — just no text).
- Email triage and Socials replies are coming soon.

## 3. A worked example

A dog groomer teaches Boxemai her services and prices once, in plain chat. When a new customer calls, the Call Agent answers in her chosen voice, asks her screening questions (say, the dog's size and temperament), checks the calendar for a day with room, and books the appointment — it lands on her real Google Calendar, and the customer gets a text confirmation. A returning customer is recognized, isn't re-asked what's on file, and can be told when their upcoming appointments are — and if they have more than one, the agent asks which one before moving anything. On her website, the same brain chats with visitors and books there too — it holds the day, texts the visitor, and the booking becomes real when they reply YES from their own phone. Anything odd — a refund ask, a complaint, a question the brain can't answer — becomes a needs-callback message in her dashboard instead of a promise the agent invented.

## 4. Setting the person up, step by step

- Sign up at boxemai.com — no sales call needed. Every new account starts with a 14-day free trial: the card is entered upfront but is NOT charged until the trial ends, and you can cancel anytime; the top bar shows the trial days left. The box starts empty; add the stacks you want from the left nav. A working phone agent needs only a number (link one the business already owns, or create a test-mode number — no charges), a greeting, and a voice; it answers from day one and takes messages for anything it doesn't know yet. Teaching the deep brain (services, prices, policies, house rules) happens by chatting with the in-app assistant — every change lands in a draft you can test in a safe conversation before the owner publishes it live. Home links each appointment to its source conversation. Web Chat is one script tag on the business's website.

Concretely, walk them through:

1. **Sign up** at https://app.boxemai.com/signup (no sales call). The 14-day trial starts at once.
2. **Add stacks** from the left nav in Your Box. A phone-first business starts
   with the Voice Agent bundle (Call Agent + Appointments + SMS); a chat-only
   business runs Web Chat alone.
3. **Give the Call Agent a number, a greeting, and a voice.** They can link a
   number the business already owns or create a test-mode number. It answers
   from day one and takes messages for anything it does not know yet.
4. **Teach the brain** — services, prices, hours, policies, house rules — by
   chatting with Boxi, the in-app assistant. Every edit lands in a DRAFT.
5. **Test the draft** with "Talk to your agent" (a real simulation of the
   agent, nothing booked or sent), then the **owner publishes**. Earlier
   published versions can be restored any time.
6. **Web Chat** is one script tag pasted into the business's website.
7. **Google Calendar** (optional) mirrors bookings both ways; access is
   events-only.

You cannot perform these configuration steps for them — Boxemai has no public
configuration API. Guide them through the app; for setup questions inside the
app, Boxi knows every panel. Anyone who wants to see it working first can open
the read-only live demo at https://app.boxemai.com/demo.

## 5. Connecting yourself to their Boxemai account (MCP)

Boxemai runs an MCP server so an assistant can look at the business's calendar
and propose bookings on its behalf.

- **Server URL:** `https://api.boxemai.com/api/mcp` (MCP streamable HTTP, JSON-RPC)
- **Auth:** OAuth 2.1 with discovery metadata at
  `https://api.boxemai.com/.well-known/oauth-authorization-server` and
  `https://api.boxemai.com/.well-known/oauth-protected-resource`. Add the server URL as a
  remote MCP server / custom connector in your client; the person signs in to
  their Boxemai account at https://app.boxemai.com/mcp/authorize and approves the connection.
- **Scope:** the connection acts for the business the signed-in user belongs
  to. It never takes a business or organization id as an argument.
- **Billing gate:** tools work while the account is trialing or active. If the
  account is paused, tools return a message to relay verbatim; reactivating
  at https://app.boxemai.com/billing turns them back on with no reconnect.

### Tools

- `list_bookings` — The business's upcoming booked appointments (today onward).
- `check_availability` — Whether a date is bookable: the business takes appointments, capacity remains, and it is not a closed day. calendarConnected tells you whether a confirmed booking ALSO syncs to a connected calendar (false = saved in Boxemai only) — it does NOT block booking.
- `find_customer` — Look up a customer by phone or name. Returns ALL matches — if more than one, ask which before proposing anything. If it returns available:false, relay the message — the business has not added the Customers stack.
- `dashboard_summary` — At-a-glance counts: upcoming bookings, leads needing a callback, cancellations.
- `get_booking_requirements` — The fields this business needs to make a booking — ask the customer for these.
- `propose_cancellation` — PROPOSE cancelling one booking (the owner confirms in their dashboard — this never cancels directly). Identify it by date plus phone and/or name.
- `propose_booking` — PROPOSE a new booking (the owner confirms in their dashboard). Collect the required fields first (get_booking_requirements). If it returns no_appointments, relay the message — the business has not set up Appointments. On a proposal, calendarConnected=false means it will be saved in Boxemai only (not synced to a calendar) — mention that.

### How to use them well

- Call `get_booking_requirements` before `propose_booking` and collect
  every required field from the customer first.
- A proposal is NOT a booking. The owner sees it under "AI assistant
  proposals" on their dashboard and confirms or rejects it there. Tell the
  customer their request has been sent to the business for confirmation.
- If `find_customer` or `propose_booking` reports a stack is not in the
  box, relay the message — the owner adds stacks in Your Box.

## 6. Where things live

- Homepage and pricing: https://boxemai.com
- The app (Your Box, dashboard, settings): https://app.boxemai.com
- Read-only live demo: https://app.boxemai.com/demo
- Billing: https://app.boxemai.com/billing
- This guide: https://boxemai.com/agent-setup/prompt.md