# Lumate — documentation > Lumate is a team of AI agents for a company: they answer and make phone calls, write on WhatsApp and email, keep contacts and appointments, work through tasks, and build the company's own apps by chat. It runs on the company's own Windows PC or server; the company brings its own AI keys (OpenAI for voice, Claude for the agents). --- # What Lumate is Source: /docs/overview Lumate is a web platform where a company runs a team of AI agents. People talk to the agents in chats, hand them tasks, let them call customers, and watch what they do. The agents run on Claude: each company uses its own Claude account, through a small program called the **runner**. ## The words used everywhere ### Organisation | Word | Meaning | |---|---| | **Company** | One organisation on the server. Each company has its own agents, customers, settings and secrets, and nothing crosses between companies. One server can hold several companies. | | **Member** | A person with an account in a company. Their role is **owner**, **admin** or **member**. Admins change settings, secrets, numbers and the browser rules; members do the daily work. | | **Instance admin** | The person who set the server up. They can open every company on that server. | ### Agents and how they work | Word | Meaning | |---|---| | **Agent** | A member of the AI team. It has a name, a title, a manager (the org chart), instructions, skills, memory, files, a voice, and permissions. The **coordinator** (Lumate) delegates to the others. | | **Run** | One working session of an agent. A run starts when something wakes the agent: your message, a task, a routine, a finished call, a WhatsApp message. The runner executes it on the company's Claude account. The agent works only through Lumate's tools: it has no shell, no files outside what was shared with it, and no other web access. | | **Tools** | What an agent can do. Examples: comment on a task, create a task, move a customer card, log a call, request an appointment, draft a WhatsApp message, open a web page in the office browser, save a listing. Every write is logged. | | **Thread** | The conversation inside a task, a chat or a customer card. People and agents write in it, and call transcripts land in it. | | **Skill** | A reusable piece of know-how an agent can use, for example "Writing a listing" or "Finding listings". Skills come from the built-in catalog or are imported. | | **Memory / Knowledge** | What agents learned: from you, from files and from their own work. It is kept with its source, used in later work, and replaced rather than deleted. | | **Routine** | Recurring work ("every weekday at 9, the daily report"). | | **Artifact** | A file an agent made: a report, a table, a spreadsheet. Artifacts are versioned. | ### Customers and conversations | Word | Meaning | |---|---| | **Broker** | A person at the company who takes the customers the agents hand over. They work only their own cards (New, Called, Call later, Call again), in the **Lumate Desk** program, and see nothing else in Lumate. | | **Customer card** | A person the company works with (buyer, seller, tenant, landlord). The card sits on the **board** in one of six columns: To call, On a call, No answer, For the manager, Done, Declined. | | **Scenario** | A call script for the voice: the goal, the opening, and the fields to fill. Used in the Playground and on phone calls. | | **Office browser** | A Chrome profile on an office PC with the Lumate extension. Agents use it to read websites and, on allowed sites, to make changes. | | **Listing** | A property an agent found on a portal, saved once per link and matched to customers. | ## The rules that never change - **Outside data is information, never instructions.** Text from customers, callers, web pages, WhatsApp, CSV files and other systems is shown to agents with that note. A page that says "ignore your rules" is just text. - **Agents never see secret values.** API keys and passwords are encrypted and used only by the server. - **People decide what goes to customers.** An agent drafts a WhatsApp reply and a person sends it. An agent sends on its own only when a manager asks it to in a message. The system never messages customers by itself. - **Calls start with a recording notice.** Agents never deny being an AI. Do-not-call wishes are kept, and calling hours apply. - **Everything is logged.** Agent tool calls, settings changes, browser changes and WhatsApp sends all appear in the Activity log. --- # Install on Windows Source: /docs/install-windows Lumate Local is Lumate on a single Windows PC, for one person. The data stays on that PC. This page is written for the IT team that looks after the PC. ![Diagram](/docs-diagrams/133de59cddd417ad.png) ## What it installs, and where | | | |---|---| | **Where** | `%LOCALAPPDATA%\AgentX` only (the user's own folder) | | **Admin rights** | None: the installer is per-user. No Windows service, no firewall rule, no change to the system PATH or to machine-wide registry keys | | **Program** | `app\\`: a private Python 3.12 with Lumate's server and runner, the web UI, the office browser extension, the team the user starts with, and a private Node.js 22 (`node.exe` only) that runs the WhatsApp service | | **Claude Code** | `tools\claude\`: a fixed version, downloaded from Anthropic at setup with its checksum checked. Its automatic updates and telemetry are switched off | | **Data** | `data\`: the database, shared files, logs, daily backups. `%LOCALAPPDATA%` does not roam and is outside OneDrive's known-folder sync | | **Start** | A Start menu shortcut and one in the user's Startup folder. Lumate has one window: opening it again (the shortcut, the tray's **Open Lumate**) brings that window to the front, and each start replaces the window left from before | | **Listening** | The web server only on `127.0.0.1` (one port, 47800–47809), answering only to the names `127.0.0.1` and `localhost`. The WhatsApp service only on `127.0.0.1` (one port, 47810–47819), answering only Lumate's server, with a token. With the desk phone switched on: UDP on the PC's network address, one SIP port chosen at start and RTP ports 40000–40099 | | **Which PCs** | One person's PC. Not shared PCs or multi-session Windows (RDS, VDI): there, another account could take the local port before Lumate starts | ## Before installing: the pre-flight check The installer checks the PC before it copies anything: - **If something required is missing, it does not install.** It says what would need to change and offers the report on the desktop. - **If something optional is missing, it installs** with that feature off and says so. - **The report holds no company data and no user name.** | Check | If it fails | What IT can change | |---|---|---| | 64-bit Windows 10 (1809+) or 11 | Not installed | — | | Programs may run from the user's folder | Not installed | Allow `%LOCALAPPDATA%\AgentX` (for example an AppLocker path rule) | | 2 GB free on the user's drive | Not installed | Free disk space | | `api.anthropic.com` and `downloads.claude.ai` reachable over HTTPS | Not installed | Allow them through the firewall or proxy | | The proxy needs no Windows sign-in for those addresses | Not installed | Exempt them from proxy authentication | | A free local port in 47800–47809 | Not installed | Find the program that holds them | | Google Chrome installed | Office browser off | Install Chrome | | Chrome policy lets the user load the Lumate extension | Office browser off | Allow Developer mode for this user, or ask us for the Chrome Web Store version | | `api.openai.com` reachable | Voice off | Allow it to use voice | | `web.whatsapp.com` reachable | WhatsApp cannot be linked | Allow HTTPS and WebSocket to `web.whatsapp.com` and `*.whatsapp.net` to use WhatsApp | | HTTPS inspected with the company's certificate | Handled | — (Lumate gives Claude Code the certificates Windows trusts) | The same check runs any time from the tray icon (**System check**). ## The first start Lumate first asks **How will this PC use Lumate?** - **Lumate on this PC:** your company's Lumate runs here. The set-up below follows. - **Connect to a Lumate server:** your company's Lumate already runs on a server, and this PC opens it. See [Connecting to a Lumate server](/docs/install-windows#connecting-to-a-lumate-server). For Lumate on this PC, a short set-up follows in its window: 1. **Welcome:** the company's name, its **sector** and **country**, and the user's name, **email** and password, with the OXS terms accepted. When the installer brings a team package, its sector is chosen already (a real-estate package: the UAE too). See [Departments and countries](/docs/tour#departments-and-countries). This is the only sign-up (from 2.3.0): the same email and password open Lumate in another browser and the OXS customer portal. 2. **Activate:** OXS emails a 6-digit code to that address; enter it, and Lumate is activated (a new account starts a 14-day trial; an address with an account signs in to it). No internet at that moment: a licence key works too. See [Licensing](/docs/licensing#activating). 3. **Your team:** the agents the sector brought. 4. **Connect Claude:** the user signs in to their Claude account. 5. **Almost done:** voice (an OpenAI key) and the office browser, both optional. ## Connecting to a Lumate server From 2.15.0. Use this when your company's Lumate runs on a server (for example one your company installed, or OXS hosts) and you want to use it from this PC like an app. **What changes:** the window shows the server's Lumate, with its own sign-in. Nothing of a company runs on this PC: no agents, calls or WhatsApp here. The app still updates itself. **To connect:** 1. At the first start, choose **Connect to a Lumate server**. (Later: Lumate's icon in the taskbar → **Server connection…** → **Change server**.) 2. Type the server's address: the one you open Lumate at in a browser, for example `https://agentx.yourcompany.com`. Press **Check**. Lumate makes sure the address is a Lumate server. 3. Press **Connect**. Lumate restarts and opens the server. 4. Sign in with **your own** email and password on that server. Everyone in the company uses their own account, on any PC. **Link this PC** (only for the office PC that should work for the server): A linked PC can be the agents' office browser (and the PC that takes WhatsApp calls) and the bridge to the office's desk phones. Linking needs an admin of the company. 1. Lumate's icon in the taskbar → **Server connection…** → **Link this PC**. A code appears, for 10 minutes. 2. Press **Approve in Lumate**. An admin signs in and presses **Link this PC** (or types the code in Settings → **Linked PCs** on any computer). 3. **Server connection…** says **Linked and connected**. 4. In Lumate (on the server): Settings → **Browser** → **On a linked PC** → **Use this PC** gives it the office browser (the first time, its Chrome loads the extension once: the PC's **Server connection** page shows how), and Settings → **Desk phone** → **Connection runs on** gives it the desk phone line. A linked PC has to stay on, with Windows signed in and Lumate running (it starts with Windows). While the desk phone line runs through it, Windows does not go to sleep (the screen may still turn off). **To go back:** **Server connection…** → **Use Lumate on this PC**. A company you had on this PC before opens as it was; nothing was deleted. The PC is unlinked from the server. Unlinking a PC (here or in Settings → Linked PCs) turns off a desk phone line that ran on it, until an admin chooses where it runs next. **If something goes wrong:** - *"This is not a Lumate server's address"*: check the address; it is the one Lumate opens at in a browser. - *"The address sends to another one"*: use the address you end up on in a browser. - *"Use the server's https:// address"*: the connection must be encrypted. A server on the office network with its own certificate cannot be used this way yet; open it in Chrome instead. - *The code expired or was declined*: press **Link this PC** again for a new one. - *"The bridge PC is offline"* (in Settings → Desk phone): switch that PC on and start Lumate on it. ## What leaves the PC | Where | What | When | |---|---|---| | Anthropic (`api.anthropic.com`) | What the agents work on: messages, instructions, and the files and records they read | While agents work. It uses the user's own Claude account; the token is stored only on this PC, encrypted for this Windows user | | Anthropic (`downloads.claude.ai`) | Nothing about the company: Claude Code is downloaded | At setup and when Lumate is updated | | Anthropic sign-in (`claude.ai`) | The user signs in to their Claude account in the browser | Once, at setup | | OpenAI (`api.openai.com` and its voice media servers) | Voice audio and its transcript; WhatsApp voice notes, to be written out (from 2.14.0; never a Personal chat's) | When the user talks to agents by voice, during AI calls (desk phone, WhatsApp Web, call center), and when a voice note arrives on the linked WhatsApp; only if an OpenAI key was entered | | The company PBX or a desk phone | Call audio (SIP and RTP) on the company network | Only if the desk phone is set up and switched on | | Brokers' PCs on the office network (Lumate Desk) | Each broker's own customer cards, over TLS on one port (47830 by default) | Only if an admin switched on **Broker access** in Settings → Call center, and IT allowed the port | | WhatsApp (`web.whatsapp.com`, `*.whatsapp.net`) | The linked number's one-to-one messages: the ones it receives, the replies a person approves in Lumate, and notifications to managers who set a notification phone | Only after someone links a WhatsApp number in **Settings → WhatsApp** | | GitHub (`raw.githubusercontent.com`) | Nothing about the company: the WhatsApp service reads which WhatsApp Web version is current | While a WhatsApp number is linked, at most every six hours | | Websites the agents open (office browser) | The pages the agents read, and what they type into search boxes | Only if the office browser extension was added. Agents only read on sites that are not allowed; they never open the company's own network (intranet names, private addresses) unless an admin allowed that site | | Outside APIs an admin connected | The requests agents make with a stored secret, only to the hosts an admin allowed for that secret | Only if an admin set one up. Changes wait for the admin's approval | | GitHub (`github.com`, `api.github.com`, `raw.githubusercontent.com`) | Nothing about the company: skill files are downloaded | Only when an admin imports skills from GitHub | | OXS Cloud's licence service (the address the build names) | At the first run (from 2.3.0): the user's own name, email, password and company, to open or sign in to their OXS account. Then counts and codes only: the version, how many companies, people, agents, calls and messages, the database's size, how updates went; never names, numbers, messages, transcripts or files ([the exact fields](/docs/licensing#what-we-send)) | Every 12 hours, and when the person activates Lumate or presses Check now | | OXS Cloud's release channel (the address the build names) | Nothing about the company: Lumate asks which version its channel (stable or beta) offers and downloads it. The request names only the channel; whether this PC is in a rollout is decided on the PC | Every hour and when asked, from 1.10.0, once the build names a cloud address | | The update folder (SharePoint, `*.sharepoint.com`) | Nothing about the company: Lumate lists the folder and downloads new installers | Only on a build without a cloud address, if the owner set an update folder in **Settings → Updates**: every hour and when asked | **What never leaves the PC:** - nothing the company keeps is sent to OXS or to any other party: the licence's check-ins carry counts and codes only; - there is no other telemetry. The only update checks are the release channel's (which version is offered, and its download) or the owner's own update folder; neither carries anything about the company. ## How the data is protected - **Keys:** the keys that encrypt the stored secrets, the Claude sign-in and the runner key are protected with Windows DPAPI for this Windows user. Copying the data folder to another PC or user does not reveal the stored secrets. - **Secrets the user enters** (the OpenAI key, the desk phone's password): stored encrypted. They are never shown again and never given to the agents. - **WhatsApp:** a linked session is full access to that WhatsApp account. Its files in `data\whatsapp` are encrypted with a key kept in the same DPAPI-protected store, and the WhatsApp service answers only Lumate's server. - **Disk:** the data folder is normally on a BitLocker-encrypted disk. - **Network:** the server answers only on `127.0.0.1` and only to its own names, so a web page cannot reach it under another name. Changes need a request from Lumate's own page, and another website cannot make the browser download a backup. - **Sign-in:** the launcher signs the user in with one-time codes, after the server has proved it holds the launcher's secret. It signs in whoever last signed in with a password in Lumate's window (at first, the person who set it up). After **Sign out** the window opens the sign-in page, also after a restart, until someone signs in with their email and password. Signing in or out in a browser on another computer changes neither. - **Window:** Lumate opens in its own Chrome profile, so the person's everyday extensions and cookies never see its pages. - **Agents:** Claude Code runs with only two tools (skills and reading the files of the task at hand). There is no shell, no file writing and no web access of its own. - **Downloads:** Claude Code is checked against the checksum Lumate was built with. The Python packages in the installer are checked against the locked hashes when it is built. The installer itself is not yet code-signed. ## Updates and backups - **Updates from OXS Cloud (Settings → Updates, from 1.10.0, once the build names a cloud address):** 1. **Channel:** Stable (what every customer gets) or Beta (new versions first, for testing). Lumate asks its channel every hour (and on **Check now**; half an hour after a check that failed) and takes only a version newer than itself whose manifest is signed with Lumate's release key *for that channel*, then downloads it and checks its size and checksum. A download that stops (a dropped line) goes on from where it stopped at the next check. An answer signed earlier than one this PC already saw is refused, so an old version cannot come back by replaying an old answer. 2. **Rollouts:** a new version may reach a share of PCs first (10%, then 50%, then everyone). Whether this PC is in that share is decided on the PC from its own random install id, so it never changes back and forth; **Settings → Updates** says when a version reaches this PC in a later wave. 3. **Install updates automatically** (on by default): a downloaded update is installed in the maintenance window (02:00–05:00 in the company's time zone by default, changeable), never during a call; AI calls (the dialer and started call lists) pause meanwhile and come back by themselves, also when the update could not be installed. A Windows start installs the update the server approved for this PC's channel before Lumate opens, like a desktop app's own updater. Before such an install Lumate asks the cloud once more; a version the cloud stops offering (paused, outside the rollout, or another channel chosen) is withdrawn and its download deleted, so it is never installed at a start, and without the cloud the install waits for the maintenance window. A start tries one version at most once a day and three times in all; if it does not go through, Lumate opens as it is, **Settings → Updates** says why, and **Update now** can try again. 4. **Required updates** (for example a security fix) are installed in the window and at the next start even when automatic installs are off. 5. **Update now** installs at once, the same way. It asks the cloud first, for a few seconds at most: a version the cloud has paused since the last check, or no longer offers this PC, is withdrawn instead; when the cloud cannot be reached, the version already checked and downloaded is installed. A version that failed on this PC is not offered again, and **Settings → Updates** says how the last update ended. When a version needs a newer base than this PC has, **Settings → Updates** says which version to install first. - **Updates from a folder (Settings → Updates, from 1.4.0, on builds without a cloud address):** 1. The person who set up the PC pastes the link of the update folder: a SharePoint or OneDrive for work folder shared with anyone who has the link. **Test link** says whether Lumate can read it. 2. Lumate looks there every hour (and on **Check now**). It offers only a version newer than itself whose manifest is signed with Lumate's release key, downloads it and checks its size and checksum. 3. **Update now** (never during a call; the AI dialer pauses) closes Lumate, installs the new version silently and opens it again, usually within a few minutes. Until then, opening Lumate says it is updating. 4. **Settings → Updates** then says how it ended. A version that failed on this PC is not offered again. - **While it updates, and after (2.7.0):** - Lumate's window says it is updating (on Lumate's own address) until the new version opens. - The first window after an update opens **Help → What's new**. - The tray icon's **Check for updates** looks at once and says in one line what it found. - **Go back to the previous version (Settings → Updates → Previous version, from 2.3.0):** an update keeps the version it replaced on the PC. If the new one gives trouble, **Go back to ** (the person who set up the PC; never during a call, and AI calls pause meanwhile) closes Lumate and opens the earlier version, usually within a minute. 1. When the earlier version can read today's data, the data stays as it is. 2. When it cannot (the update changed how data is stored), the data goes back to the copy taken just before the update; the confirmation says from when. Today's data is kept as a copy in the backups folder (`before-going-back-…db`), but the earlier version does not show what changed since. 3. The version you went back from stays offered but is never installed again by itself: **Update now** installs it, and a newer version comes as usual. 4. If going back cannot finish, the newer version opens again with today's data, and **Settings → Updates** says why. - **Updates by hand:** a new version is also a new installer file, run by the user. 1. The installer backs up the database, migrates it and checks that Lumate starts. 2. If anything fails, it puts the backup back and returns to the previous version by itself. Nothing is lost. 3. An older installer cannot be installed over a newer version. 4. If an update was interrupted after the data was migrated, older code never runs on it: Lumate starts the newer version instead, or says to run the newest installer again. - **Backups:** - Lumate keeps a daily backup of its database on the PC (a week) and one before each update. - **Settings → General → Back up now** downloads the database and files in one zip, to be saved wherever the company allows. Lumate never sends it anywhere. - **Restoring from a zip:** 1. Quit Lumate from the tray. 2. In `%LOCALAPPDATA%\AgentX\data`, replace only `agentx.db` and the `files` folder with the ones in the zip. Leave `data\local` as it is: it holds this PC's keys. 3. Start Lumate. - **On another PC or Windows user:** the restored data works, but stored secrets (the OpenAI key, the desk phone's password) cannot be read there. They show as **Value needed** in Settings → Secrets until they are entered again. ### Claude Code updates (from 2.6.0) The runner keeps Claude Code current by itself (Settings → Runners → Claude Code): it takes Anthropic's **stable** channel (or **latest**), checks the release's manifest against Anthropic's release signing key (fingerprint `31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE`) and the download against the manifest, and switches only when the new version answers `--version` and still knows every option the runner uses. Versions live in `tools\claude\versions` beside the copy installed with Lumate, which always stays. If the first three runs on a new version fail before Claude answers (a sign-in or network problem does not count), the runner goes back to the version before and admins get a notice; that version is tried again a week later, or at once with **Check now**. After **Go back** the runners stay on the version before until an admin presses **Check now**. At most one update a day. OXS can stop a version that breaks agents for every install (at the next check-in). ## Removing it 1. Uninstall it from Windows **Settings → Apps → Lumate**. No admin rights are needed. 2. It asks whether to delete the data as well (the default is to keep it). To wipe everything later, delete `%LOCALAPPDATA%\AgentX`. 3. If the office browser extension was added, remove it in Chrome (`chrome://extensions`), together with the "Lumate" Chrome profile if one was made. 4. If a WhatsApp number was linked, unlink it in Lumate (**Settings → WhatsApp → Unlink**) before uninstalling, or later on the phone: WhatsApp → Settings → Linked devices. ## Logs The logs are in `%LOCALAPPDATA%\AgentX\data\logs`, also reachable from the tray icon (**Logs folder**): - `server.log`; - `runner.log`; - `whatsapp.log`; - `launcher.log`. - They keep errors and start-up lines, never secrets or tokens. There is no request log, and database errors do not include values. - Each log is kept to 5 MB, with three older copies. - Claude Code keeps a transcript of each agent run in `%LOCALAPPDATA%\AgentX\tools\claude\config\projects`. Those transcripts hold company data, like the database. ## The desk phone and the PBX If the desk phone is used, set up its PBX extension like this: - the caller ID of the person's phone fixed by the PBX (phones cannot set their own); - no outside number routed to the Lumate extension, unless Lumate answers callers on it (**Lumate answers callers on the office line** in Settings → Call center → Incoming calls); - the extension allowed only from this PC's address; - a long random password. **For the call center,** the same extension also calls customers and hands them to brokers: - It may call outside numbers. The outside-line prefix (for example `9`) is set in Settings → Call center. - It may transfer calls. Lumate rings the broker's extension, tells them who is calling, then joins the two (SIP REFER with Replaces); if the PBX refuses that, Lumate stays in the middle and passes the audio on. - The brokers' phones or PBX apps answer on their own extensions. Several AI calls can run at once on that one extension. Their number is set in Settings → Call center, so the PBX must allow that many calls on the extension. Without the call center, the extension needs no outside line. The call audio is not encrypted on the network (no TLS or SRTP yet). On a call that comes in from the desk phone, the agent only talks and answers from what the team shared for callers. It does not take requests or open private notes, because a caller's number can be faked. Requests by voice are only taken on calls the person starts from Lumate. ## Broker access (the call center) Brokers work their customer cards in **Lumate Desk** on their own PCs. Lumate Local otherwise listens only on `127.0.0.1`. **Broker access** opens one more door when an admin switches it on in Settings → Call center. | What | How it works | |---|---| | Port | **Inbound TCP 47830** (the port can be changed) on this PC's office address only. A standard user cannot add the Windows Firewall rule, so IT allows it, from the office network only. Give this PC a fixed address (a DHCP reservation). | | What is reachable | Only the broker API (`/api/broker/…`). Every other path answers 404 and never reaches Lumate. | | Encryption | TLS 1.2 or newer, with a certificate this PC makes (ECDSA P-256). Its private key is encrypted, and its password is kept with DPAPI for this Windows user. | | Pinning | Lumate Desk remembers the certificate's fingerprint when it pairs and checks it on every connection before sending anything. | | Pairing | The broker's one-time code never travels. Each side proves it holds the code with an HMAC over the certificate. A machine in the middle shows another certificate, so its proof fails. Pairing is limited to 5 tries a minute per address. After 10 wrong codes within 15 minutes, every open code is cancelled. | | Access | Each PC gets its own device token. Lumate stores only its hash; on the broker's PC it is kept with DPAPI. Admins revoke a PC in Call center → the broker. | **Lumate Desk on the brokers' PCs:** - a per-user installer, about 40 MB, with no admin rights; - it uses the Windows web view (WebView2, part of Windows 10 and 11) and needs no Node.js and no Claude Code; - it talks only to the address the broker typed; - inside the PC, its page is served on `127.0.0.1` under a random path, and the device token never reaches the page. ## The office browser If the office browser extension is added, agents use websites in a separate Chrome profile. Chrome keeps that profile closed after the PC restarts. So when the office browser is set up but still not connected (and not paused) at two checks, about 20 and 50 seconds after Lumate starts, Lumate opens that profile itself: it is the profile whose extensions include Lumate's extension folder. A page in it says what the window is for; it can be minimized. The extension is loaded once (**Settings → Browser → Prepare the extension**, then **Load unpacked** in Chrome) and never needs a new package after that: - Its folder lives in Lumate's data (`data\extension`). Load that folder, never one under `app\\`: those are Lumate's own copies, without a pairing code, and they go away with the next update. A copy without a pairing code says so in its popup. - **Updates bring the extension with them.** Every start of Lumate gives the folder the extension of the version that runs (its pairing code stays), and the extension reloads itself on the new version. Nothing to do in Chrome. - While the browser is not connected, Lumate keeps a fresh one-time pairing code in the folder, renewed every 10 minutes, and at once when Lumate refuses the extension's token or code. The extension reads its folder every 30 seconds while it is stopped and pairs again by itself, after a restart, an update or a long sleep. A code it could not use because Lumate was stopped or updating is tried again, not thrown away. - If the folder was deleted, Lumate puts it back when it opens the office browser's profile. - **Reconnect** (Settings → Browser) appears when the folder is there but the browser is not connected: it writes a fresh code and the extension pairs within half a minute. The page also shows the folder Chrome must load it from. The **Load unpacked** steps show only when the folder is missing. - After **Disconnect**, nothing reconnects by itself: Lumate does not open the profile or write codes until someone presses **Reconnect** or prepares the extension again. What agents may do there: - **Allowed sites** (chosen by an admin): agents may fill and send forms there. - **Any other public site:** agents may only read and search. - **The company's network:** never, unless an admin allowed the site. This covers intranet names, private addresses and names that point to them. - **Passwords, payment details and files:** never typed in. The remaining risk is this: an agent tricked by text it reads (a web page, a customer's message) could put company information in the address of a page it opens, and so send it to that website. If IT wants to rule this out, block all sites in that Chrome profile except the allowed ones with Chrome's `URLBlocklist` and `URLAllowlist` policies, or do not add the extension. ## WhatsApp Lumate connects to WhatsApp as a **linked device**, the way WhatsApp Web does: the number keeps working on its phone, and the PC connects out to WhatsApp, so nothing outside can reach the PC. It works through the company proxy and with HTTPS inspection, like Claude Code. - Nothing is linked until a person scans the QR code in **Settings → WhatsApp** with the phone. - Agents never write to customers on their own: they draft a reply, and a person approves what is sent. The only automatic messages are notifications to managers who set their own notification phone. - Linked devices are not an official WhatsApp API. Use a dedicated business number, and see the [WhatsApp guide](/docs/whatsapp) for the sending limits and the risks. - **Calls through WhatsApp Web** (1.9.0): when the desk phone is off, AI calls can go through WhatsApp Web in the office browser, one at a time. Link it in **Settings → Browser → Link WhatsApp Web**. See [Office browser → Calls through WhatsApp Web](/docs/office-browser#calls-through-whatsapp-web). WhatsApp calls do not connect in the UAE. --- # Install on a server Source: /docs/install-server Lumate on a Linux server for the whole office: one command installs it, it updates itself from OXS Cloud (or from an offline bundle), backs itself up every day, and goes back by itself when an update does not start. For Lumate on one Windows PC instead, see [Lumate Local](/docs/install-windows). ## What you need | Item | Requirement | |---|---| | Server | Ubuntu 22.04 or 24.04, or Debian 12; x86_64; 2 vCPU, 4 GB RAM (8 GB recommended), 40 GB disk. Each service's memory is bounded (about 5.3 GB in all at most, the server's and the runner's 2 GB each; [Operations](/docs/operations#logs) says how to give the runner more) | | Network | Ports 80 and 443 free on the server; outbound HTTPS to OXS Cloud, OpenAI, Anthropic and WhatsApp | | Address | A public domain name pointing at the server (Let's Encrypt), or its name and address on the office network | | Licence | Your licence key from the OXS portal (or activate in the browser after the setup) | | Claude | The company's Claude account (signed in once on the server), or its Anthropic API key | | OpenAI (for voice) | The company's own OpenAI API key | The installer puts Docker Engine on the server when it is missing (from Docker's own repository, after asking). ## Install On the server, as root: ```bash curl -fsSL https://api.lumate.io/install.sh -o install.sh sudo bash install.sh --key axk_yourlicencekey ``` To check the installer first (optional), run the steps below between these two lines. ### Checking the installer (optional) `install.sh` is signed with Lumate's release key, and OXS Cloud publishes only a signed one. To check the downloaded file yourself before running it, on the server: ```bash curl -fsSLO https://api.lumate.io/install.sh.sig printf -- '-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA+bzBByJhjJ0huDTd2QQWNGRgQF52lo8TKCODtRzV4yo=\n-----END PUBLIC KEY-----\n' > agentx-release.pem { printf 'agentx-install-script-v1\0'; cat install.sh; } > install.signed openssl pkeyutl -verify -pubin -inkey agentx-release.pem -rawin -in install.signed -sigfile install.sh.sig ``` It prints `Signature Verified Successfully`. Anything else means the file is not the one OXS signed: do not run it. The installer then checks every release it downloads against the same key. ### What the installer asks It asks for the address people open Lumate at. Answer with a public domain name (for example `agentx.yourcompany.com`, whose DNS points at the server) for a Let's Encrypt certificate, or press Enter to use the office network (the server's name and IP). The same choices as options, for an unattended install: | Option | Meaning | |---|---| | `--domain NAME` and `--email ADDRESS` | A public domain name, with Let's Encrypt (the email gets Let's Encrypt's notices) | | `--lan NAMES` | The office network's names and addresses, comma-separated: Lumate makes the office's own certificate authority | | `--own-cert FILE --own-key FILE` | Your company's certificate and its key (PEM), for the addresses in `--lan` | | `--channel beta` | Updates from the beta channel (stable is the default) | | `--offline FILE` | Install from an offline bundle (no internet; see below) | | `--yes` | Install Docker without asking | What it does: 1. Checks the machine (the Linux, CPUs, memory, disk, ports 80/443, the way to OXS Cloud). 2. Fetches the release of your channel and checks it was signed with Lumate's release key. Then it checks the download's SHA-256. 3. Loads the images. 4. Writes `/opt/agentx`, with secrets made on the server (`.env`, readable by root only). 5. Starts Lumate and waits until it answers. At the end it prints the setup link, which carries the setup token, and the token itself (for a lost link). Open the link and make the first account with your email; then choose who sets up the company (you, or a manager you send a link to). Given `--key`, the install is activated at its start: no OXS account is asked. See [First setup](/docs/first-setup). ### On the office network: trusting the certificate With `--lan` (or Enter at the question), Lumate makes the office's own certificate authority. The installer prints its SHA-256 fingerprint, and Settings → General shows it under the version. On each PC that opens Lumate: 1. Copy `/opt/agentx/ca.crt` from the server. 2. Compare its fingerprint with the one shown. On Windows: `certutil -hashfile ca.crt SHA256`. 3. Trust it for the current user: double-click it → Install Certificate → Current User → Trusted Root Certification Authorities. Lumate Desk pins the server's certificate when it pairs, so it needs nothing more. The server's certificate lasts 825 days and is made again by itself a month before it ends; after that, pair Desk again once. ## What runs `/opt/agentx/compose.yml` runs five services, each from the same version. All of them use the server's own network; only Caddy listens beyond the server. | Service | What it does | |---|---| | `caddy` | The web front: HTTPS on 443, redirects 80 | | `server` | Lumate itself (127.0.0.1:8000 only) | | `runner` | Runs the agents on the company's Claude account. It sets itself up: it enrols with the server once the first company exists | | `whatsapp` | WhatsApp as a linked device (link a number in Settings → WhatsApp) | | `updater` | Applies updates and undoes failed ones (it holds Docker's socket and nothing else) | Claude Code signs in one of two ways, and every agent uses it: - **The company's Claude account, signed in on the server**: on the server, run `sudo agentx claude-login`. It shows a link: open it on any device, sign in with the company's Claude account, approve, and type the code it gives back into the server's terminal. The sign-in is kept in the runner and renews itself; `sudo agentx claude-status` shows it, `sudo agentx claude-logout` ends it. Add `--console` to sign in with an Anthropic Console account (billed per use) instead of a Claude plan. - **An Anthropic API key** (recommended for businesses: commercial terms) or a Claude sign-in token, in Settings → Runners → **Claude for the runners**. Owners and admins set it there; it is kept sealed and never shown back, and it comes first when both are set. Settings → Runners shows, for each runner, whether its Claude Code is signed in. ## The desk phone (an IP phone on the office's PBX) Lumate registers with the PBX as one extension (SIP over UDP 5060, audio as RTP) from the machine it runs on. Three ways to reach the office's PBX: | Where the server is | What to do | |---|---| | In the office network (it reaches the PBX) | Nothing more: Settings → Desk phone, **Connection runs on: This server**. The services use the server's own network, so the extension and its audio work as on a PC. | | Outside the office (a data center, the internet) | A **linked PC** in the office carries the line (from 2.15.0): Lumate on an office PC, connected to this server and linked in Settings → Linked PCs; then Settings → Desk phone → **Connection runs on** that PC. The PC registers with the PBX and carries the calls' audio to the server over its own HTTPS connection (G.711, unchanged); no port is opened in the office and no VPN is needed. See [Connecting to a Lumate server](/docs/install-windows#connecting-to-a-lumate-server). | | Outside the office, with a VPN to the office | The server reaches the PBX through the VPN: as in the office network. IT sets up the VPN. | Through a linked PC the PC↔server round trip adds to each direction's audio (Settings → Linked PCs shows it); the PC's jitter buffer is the same as on a desk phone in the office. ## The `agentx` command On the server, as root: | Command | What it does | |---|---| | `agentx status` | The version, the channel and each service | | `agentx logs [server\|runner\|whatsapp\|caddy\|updater]` | The last log lines | | `agentx backup` | A backup now, in `/opt/agentx/backups` | | `agentx restore FILE` | Puts a backup's data back. Lumate stops meanwhile, and what changed since that backup is lost | | `agentx update` | Installs the update Settings → Updates downloaded | | `agentx update --bundle FILE` | Installs an offline bundle | | `agentx rollback` | Goes back to the version before the last update | | `agentx support-bundle` | Versions, settings without secrets and log lines for OXS support (no data) | | `agentx claude-login` | Signs Claude Code in with the company's Claude account (a link to open, a code to type back) | | `agentx claude-status` / `claude-logout` | Whether Claude Code is signed in; signs it out | | `agentx uninstall` | Stops and removes Lumate. Its data stays unless you add `--delete-data` | ## Updates Settings → Updates (the person who set up Lumate) shows: - the version; - the channel (stable or beta); - automatic installs in the maintenance window (default 02:00–05:00, the company's time); - what is offered, with its notes, and **Update now**. Lumate looks every hour, downloads the update and checks it. It never installs during a call; the AI dialer pauses meanwhile. An update: 1. backs up the data first; 2. switches every service to the new version; 3. waits for it to answer. If the new version does not start, Lumate goes back by itself, files and data, usually within a minute. That version is then not installed again by itself; Update now can try it again. Settings → Updates then offers **Go back** to the version before, kept on the server. When that version cannot read today's data, it takes the data from the backup made before the update (a backup of today's is made first). ### Without internet: offline bundles A server that cannot reach OXS Cloud is installed and updated from an offline bundle, `AgentX-Server--offline.tar`, from OXS. It holds the images, their signed manifest and the installer. Use it in one of three ways: - install with `sudo bash install.sh --offline AgentX-Server--offline.tar`; - update with `agentx update --bundle AgentX-Server--offline.tar`; - upload it in Settings → Updates → Offline bundle. Only a bundle signed with Lumate's release key is taken. ## Backups Settings → Backups (the person who set up Lumate): - **What is kept:** a backup every day at its hour (7 kept), one before every update (3 kept), and Back up now (10 kept). Each can be downloaded. - **What a backup holds:** the database and the shared files. It never holds the server's secrets, so also keep `/opt/agentx/.env` in a safe place. Without its `SECRETS_KEY`, the secrets stored in Lumate cannot be read. - **Copy to a bucket:** each backup can also go to an S3-compatible bucket (AWS S3, Backblaze B2, Wasabi, MinIO…). Give the address, region, bucket, folder and an access key; the secret is kept sealed and never shown back. - **Restoring:** only on the server, with `agentx restore`. ## Troubleshooting | You see | Do | |---|---| | The installer stops at "ports 80 and 443 are in use" | Another web server runs on the server: stop it, or install Lumate on another server | | The browser warns about the certificate (office network) | Trust `ca.crt` on that PC (above) | | Settings → Updates says an update was undone | `agentx logs server` shows why the new version did not start; send `agentx support-bundle` to OXS | | The runner says it waits for the team server | Create the first company (the setup), then it enrols by itself | | Agents do not run | Settings → Runners: the runner is online and its Claude Code is signed in (`sudo agentx claude-login`, or an API key) | --- # First setup Source: /docs/first-setup From an empty server to a working AI team. The steps follow the screens in order. ## 1. The first account (setup token) The person who installs Lumate makes the first account. From 2.16.0 each person signs in with their **email** (accounts made before keep their username). 1. **The server edition:** open the **link the installer printed** at its end. It carries the setup token, so you type only your name, your email and a password (at least 10 characters). Lost the link? The installer printed the token too, and `sudo grep SETUP_TOKEN /opt/agentx/.env` shows it: open the address and type it. **Lumate Local:** there is no token: the first-run window makes the first account. 2. **Activation:** an install given a licence key at install (`--key`) is already activated: nothing is asked. Without one, the same form asks the company's name once, and your OXS account opens with **the same email and password**: you only type the six-digit code OXS emails (a new account starts a 14-day trial). A licence key or an offline file work too; see [Licensing](/docs/licensing#activating). If the email already has an OXS account with another password, Lumate says so and asks for that one. 3. **Who will set up the company?** - **I will:** you go on to the company's set-up below. - **Someone else:** type the manager's email. Lumate makes a link for them (7 days, once); copy it and send it. The manager makes their account with it and sets up the company. You are **not** a member of that company: Lumate does not show you its customers, messages or calls (the server's backups still hold them, so keep those, and who can reach the server, safe). Your place is the **Server page** (status, diagnostics, updates, backups, the licence and that link; see [The Server page](/docs/agents#the-server-page-from-2160)). The token works only until the first account exists. This first person is the **instance admin**. ## 2. The company (onboarding) The company's set-up has three steps, and asks each thing once: | Step | What you enter | |---|---| | **Company** | Its name (filled in from your licence's account), its website (Lumate reads it to learn what the company does; optional) and time zone (for example `Asia/Dubai`: every schedule, call hour and report uses it). The task prefix (2–6 letters, used in task references such as `RIC-12`) is suggested from the name. | | **Departments** | What the company does: its departments (**Real estate**, **Any business**, **Recruiting**, as many as it has teams; the first is the primary) bring their teams, contacts and pages, and its country (the United Arab Emirates, Türkiye or another country) the calling rules. **Create company** makes it. Both can be changed later in Settings → Departments (see [Departments and countries](/docs/tour#departments-and-countries)). | | **Connections** | Claude and the OpenAI key on one screen, each saying whether it works. On the server edition, the company's Claude key or token (or `sudo agentx claude-login` on the server); on a server built from source, a runner key is made here. The OpenAI key is what calls need. You can skip both: the dashboard keeps saying what is missing until they are there. | Then the set-up interview opens once Claude answers: Lumate asks about the company and proposes its departments, agents and apps (see [Setting up with Lumate](/docs/tour#setting-up-with-lumate-from-2110)). It already knows the departments and the website you gave, and does not ask them again. Lumate Local's first-run window asks for departments only when you press **Choose departments yourself** (or a bundled team package names them). ## 3. Connect Claude (the runner) The runner uses the company's own Claude: an Anthropic API key, or a Claude account's login token. - **An Anthropic API key (recommended for businesses):** commercial terms, and the data is not used for training. Make one in the Anthropic Console. - **The company's Claude account:** on the server edition, `sudo agentx claude-login` signs it in on the server (see [The server edition](/docs/install-server#what-runs)). A Claude account's long-lived token works too: on any computer with Claude Code, sign in with the **company's** Claude account and run `claude setup-token`; it prints `sk-ant-oat01-…`. Where it goes: - **The server edition:** Settings → Runners → **Claude for the runners** (owners and admins; kept sealed, never shown back), or `sudo agentx claude-login`. The runner sets itself up once the first company exists. - **Lumate Local:** the first-run window's Claude step, later Settings → General → Claude. The runner is part of the app. Settings → **Runners** shows the runner as online within a few seconds. You can make more keys there, for example for a runner on another PC, and revoke them. Test it: open **Chats → Lumate** and write "Hello, what can you do?". A reply in a few seconds means the runner works. ## 4. Invite people **Settings → Members:** 1. Choose a role (**admin** or **member**) and type the person's **email**. Each link is for that person only, works once and expires after 7 days. With Settings → Email set up, Lumate emails it (you can copy it too); otherwise copy the link and send it. The person confirms their email once (their first page offers it, or Settings → Your account → Email), so **Forgot password?** works for them. 2. The person opens it, gives their name and a password, and signs in with that email from then on. If the email already has an account here, they sign in and join with it: nobody gets a second account. They then see a short hello with what is theirs (their desk phone's extension), never the company's interview. 3. Change roles or remove people on the same page. At least one owner always remains. | Role | Can | |---|---| | Owner / Admin | Everything in the company: settings, secrets, numbers, members, WhatsApp, the browser rules, agent permissions | | Member | Daily work: chats, tasks, customers, appointments, messages, listings | ## 5. Voice (OpenAI) 1. **Settings → Secrets** → add `OPENAI_API_KEY`: the company's OpenAI key. Its value is encrypted, never shown again, and never given to agents. 2. **Settings → Voice:** | Setting | Meaning | |---|---| | Voice model | The real-time voice model | | Backend model | The model behind the voice's tools | | Thinking | How much the voice reasons | | Talks with you in | The language the voice uses with your team | | Calls in | The language it uses on customer calls | 3. Each agent has a **Voice** tab: its voice and how it speaks. Test it: open an agent's chat and press the microphone, or go to the **Playground**. ## 6. Phone numbers (optional) Follow [Phone and Asterisk](/docs/phone): - the OpenAI project id; - the webhook secret (`OPENAI_WEBHOOK_SECRET`); - the numbers, and which agent answers each; - the transfer number; - for outbound calls, the trunk and `SIP_TRUNK_PASSWORD`. ## 7. The customer board **Settings → Board:** | Setting | Default | Meaning | |---|---|---| | Hand to the manager after this many unanswered calls | 2 | The card moves to "For the manager" | | Minutes before calling again | 120 | When a "No answer" card is due again | | Daily report time (company time) | 19:30 | When the coordinator writes the day's report | | Who takes appointments by default | — | The person new appointment requests go to | To try the board right away: **Customers → ⋯ → Add sample customers** adds 25 sample customers. Remove them later from the same menu. ## 8. Your notification phone **Settings → Your account** → "Your phone for notifications". While WhatsApp is linked, these notifications also arrive on WhatsApp: - hand-offs ("Raj needs you"); - appointment requests; - the daily report; - new WhatsApp messages (at most one every 30 minutes per customer). ## 9. WhatsApp (optional) Settings → **WhatsApp** → Link with a QR code (or a pairing code). Use a dedicated number. See [WhatsApp](/docs/whatsapp). ## 10. Office browser (optional) 1. Settings → **Browser** → download the extension and install it on the office PC. 2. Add the CRM to the allowed sites. 3. Switch on **Can use the office browser** for the agents that need it, in each agent's Settings tab. Agents made from the real-estate template (Lumate and the Researcher) have it already; agents you made earlier need it switched on. See [Office browser and listings](/docs/office-browser). ## 11. Skills and knowledge - **Skills:** the built-in catalog by category. Add skills to the company and give them to agents. Importing from GitHub is also possible. - **Knowledge:** what the agents learn shows up here, with its source. To teach an agent, just tell it ("Our office closes at 6 on Fridays") or share a file (price list, brochure). It remembers. ## Checklist - [ ] HTTPS works and `SESSION_SECRET`, `SECRETS_KEY` are set - [ ] First account and the company exist; the template's agents are there - [ ] The runner is online and Lumate answers in a chat - [ ] Members are invited with the right roles - [ ] `OPENAI_API_KEY` is saved; a talk with an agent works - [ ] Board settings and the default appointment owner are set - [ ] Optional: numbers, WhatsApp, the office browser --- # Licence and activation Source: /docs/licensing Lumate runs with a licence from OXS. A licence belongs to an OXS account and its plan, and it is made for one install: a production install or a test install, Lumate Local or Lumate Server. It says what the install may use: how many people, desk seats (people who take transferred calls in Lumate Desk), agents and companies, and which features (voice, the call center, WhatsApp, calls through WhatsApp, the desk phone, phone numbers, the office browser, endpoints). The licence is checked on the install itself, on every request. Nothing a company keeps in Lumate ever goes to OXS (see [What we send](/docs/licensing#what-we-send)). ## The states of an install | State | What works | |---|---| | **Not activated** (a fresh install) | Signing in, the first account, the Local wizard and activating. Everything else waits. | | **In transition** (an install that already ran before licensing arrived) | Everything, for 30 days from its first start with licensing. Owners and admins see the date. Activating at any time keeps every row. | | **Active** | Everything the plan includes, up to its limits. | | **Ended** (the subscription stopped, or no check-in for 14 days) | Read-only: signing in, Settings → Licence, Export all data and updates. Inbound WhatsApp messages are still stored; inbound calls are declined; no agent wakes and no call starts. Nothing is deleted. | | **Clock behind** (the computer's clock is more than an hour behind the latest time Lumate has seen) | Like Ended, until the next check-in with OXS Cloud confirms the time (offline: a new licence file from the portal); set the right date and time. | A locked install answers `402` to the API, with the reason. The app shows the reason and **Export all data**; to the person who set Lumate up also the ways to activate, a link to renew in the OXS portal and, on Lumate Local, its updates (a newer Lumate may be what is needed). Anyone can sign out from there. ## Activating The person who set Lumate up activates it, in the setup's Activate step (Lumate Local's wizard, right after the company; on a server, right after the first account) or in **Settings → Licence**. Three ways: 1. **With your OXS account (recommended), in Lumate itself (from 2.3.0).** Enter your email and password (and, the first time, your name and company) and accept the terms; OXS emails a 6-digit code; enter it in Lumate. A new address gets its account and a 14-day trial (no card); an address that already has an account signs in to it (its own password; a wrong one is said only after the code proved the address). The same email and password open the customer portal: there is nothing else to sign up for. On Lumate Local the first-run form asks for them once: they are also the email and password that open Lumate in another browser. The code works once, for 15 minutes; **Send a new code** starts again. Five wrong codes spend it. **Approve this PC in the browser instead** still works: Lumate shows a code such as `BCDF-GHJK`; open the activation page, sign in, check the install and approve. While the code waits, Lumate keeps asking (also through a dropped connection) until the code expires. 2. **With a licence key.** In the portal, **Keys** shows the account's key once (`axk_…`); paste it into Lumate. Spaces, line breaks and dashes are forgiven; a mistyped key is caught before anything is sent. Rotating the key in the portal stops the old one for new activations; installs already running keep working. 3. **Offline (Enterprise).** For an install that never reaches the internet: download its request file in Settings → Licence → Offline, upload it in the portal, download the licence file and upload it into Lumate. An offline licence lasts to the subscription's end plus 7 days, at most a year, and never checks in. Choose **Production install** or **Test install**: the plan counts them apart (the trial has one of each). ## Check-ins Every 12 hours (plus up to 30 minutes, so installs do not all knock at once) Lumate checks in with OXS Cloud and gets its licence back, valid for 14 more days while the subscription runs. - If OXS Cloud cannot be reached, Lumate tries again after 5, 10, 20, 40 and then every 60 minutes, and keeps working until the licence's last day. After 3 days without a check-in, owners and admins see a line about it. - When a subscription stops (not paid after 7 days of grace, cancelled at its period's end, or suspended), the next check-in ends the licence. - An ended or clock-behind install asks again every 5 minutes; **Check again** on the lock page asks now. - **Settings → Licence → Check now** checks in at once. ## What we send A check-in carries counts and codes only. The exact fields (the cloud refuses any other): | Field | What it is | |---|---| | `version`, `channel`, `edition`, `mode`, `os` | Lumate's version and update channel, Local or Server, how it was installed, the operating system's name and version | | `packs`, `companies` | The sectors in use (for example `real-estate`) and how many companies | | `users.seats_used`, `users.desk_seats_used`, `users.active_7d` | How many people and desk seats, and how many people used Lumate in 7 days | | `agents`, `apps` | How many working agents and apps | | `usage_24h.*` | In the last 24 hours: agent runs, voice minutes, calls, WhatsApp messages in and out, emails sent | | `db_mb`, `errors_24h`, `update_state` | The database's size, failed runs and calls in 24 hours, how the last update went | | `fingerprint`, `clock` | A hash of a random id kept on this machine (it tells a copy of the install from the original), and the install's time | Never: company or person names, phone numbers, emails, messages, transcripts, files, app records, prompts. **Settings → Licence → What we send** shows the last check-in exactly as it was sent. ## Limits Adding past a limit is refused with a sentence (for example "Your licence allows 5 people; 5 are in use"): a new member or an accepted invitation, a new desk seat, a hired or imported agent, a new company. A person in two companies takes one seat. What already exists keeps working: if more is in use than the licence allows (after a plan change), owners and admins see a line about it, and only adding waits. A feature the plan does not include is hidden: its pages leave the menu, its tools leave the agents, and its API answers `403` with the feature. ## Updating an install from 1.x The first start of the licensing release on an install that already has a company starts its **30-day transition**: everything keeps working, and owners and admins see the last day. Activate it any time before that day. OXS can set up an account and its licence by hand (invoice or wire); the key then comes from OXS. ## Moving to another machine, restoring a backup - **A backup restored on the same machine** checks in as before. - **A copy on another machine** (a database copied, or restored elsewhere) is a new machine to OXS Cloud: while the original still checks in, the copy is told to activate again (with a free slot of the licence), and the original keeps working. A copy without the original's secrets key cannot check in at all: Settings → Licence says so, and its licence lasts only to its last day (14 days at most) unless the key is restored or it is activated again. - To move an install for good: **Settings → Licence → Deactivate** on the old machine (it frees the slot at once), then activate the new one. Deactivating stops Lumate on that machine until it is activated again. ## Export all data **Export all data** (Settings → Licence, and the lock page) downloads one zip: a consistent copy of the database and every shared file. It never holds the vault, the secrets key or the machine id, nor anyone's password hash or the licence's token (people choose new passwords wherever the data is opened). It works in every state, also after the licence ended. The install's administrator can always take it; a company's owner or admin only while the install holds that one company (the zip holds every company). ## For IT - OXS Cloud's address is the `CLOUD_URL` setting; release builds carry `https://api.lumate.io` (before 2.19.0, `https://ax-api.oxsbilisim.com`), so a firewall lets Lumate reach that host on port 443. The check-in is an HTTPS request through the computer's proxy, trusting the Windows certificate store on Lumate Local. - An Anthropic API key or a Claude account's token runs Claude Code; that is apart from the licence (see [First setup](/docs/first-setup)). --- # A tour of Lumate Source: /docs/tour A page-by-page guide to the platform, in the order of the menu on the left: - **at the top:** New (a task, a call Lumate makes for you, an app); - **Home:** Dashboard, Inbox, Chats; - **Work:** Tasks, Routines, Documents, Activity; - **Customers:** Customers, Appointments, Messages, Listings; - **Calls:** Call center, Call history, Playground; - **Team:** each agent, All agents, Skills, Knowledge; - **Apps:** the company's apps, and Build an app; - **at the bottom:** Integrations, Settings, Help. A section opens and closes when you press its name, and Lumate remembers it. After your first week the sections other than Home start closed; the section of the page you are on is always open. Press `?` anywhere for the keyboard shortcuts. ## The tour The first time you open Lumate, a short tour greets you. It goes through the main pages in a fixed order: Dashboard, Chats, Customers, Playground, Call history, Call center, Knowledge, Agents, Settings and Help. Each step opens its page and points at its place in the menu. - **Next** and **Back** move between the steps. **Skip** (or Escape) closes it. - The tour shows only once for each person. To take it again, press **Take the tour** on the **Help** page. - **Lumate explains** gives the tour by voice, in more detail, one chapter at a time: the pages above plus the Inbox, Tasks, Messages, Listings, Appointments, Routines, Skills, Integrations and Activity. In each chapter Lumate opens the page, says what it is for, names a few things you can do there with an example each, and suggests one thing to try ("say: show me the tasks in review"). It waits for your questions and goes on when you say so. Say "skip" to jump to the next chapter, or "stop" to end. The talk goes on in the small window while it moves you around. ## Departments and countries A company has one or more **departments** and a **country**. Both are chosen when it is set up, and the owner changes them in **Settings → Departments**. **A department** brings a team (its agents, call scenarios, skills and routines), its kinds of contact with their fields, and its pages. A company has as many as it has teams: a real estate office with someone hiring brokers has Real estate and Recruiting. | Department | Its contacts | Only with this department | Its page | |---|---|---|---| | Real estate | Customers: buyers, sellers, tenants, landlords | Listings, outside brokers | [Real estate](/docs/real-estate) | | Any business | Contacts: leads, customers, partners, suppliers, others | | [Any business](/docs/any-business) | | Recruiting | Candidates and employees | Pipeline; the monthly list of candidates due for deletion | [Recruiting](/docs/recruiting) | - **One contact list.** Every contact has a kind, and every kind belongs to a department: a buyer to Real estate, a candidate to Recruiting. A card shows its kind's department's fields. The menu adds each other department's own view of the list (for example **Candidates**) and Recruiting's **Pipeline**. - **The primary department** is the first one: shared pages use its words (Customers, Appointments). - **One team.** Lumate, Coach, Librarian and Researcher serve every department. A department's own agents (Recruiting's Sourcer and Screener) belong to it; an agent's department is on its Settings tab, a scenario's in its editor. - **Calls speak for their department:** a call's department is its scenario's, else the contact's, else the answering agent's, else the primary. That decides its tools and words: a screening call books an interview and never searches listings; a viewing call does. Help's menu shows each department's own page. Companies made before sectors existed (1.10 and older) are real estate in the UAE, and work as before. **The country** gives the calling rules: which numbers are local, whether numbers are checked against a national do-not-call register, the default recording notice, whether a call says that an AI is speaking, and what an admin confirms before AI calls start (see [Security and compliance](/docs/security#calling-rules-by-country)): the United Arab Emirates, Türkiye, or another country. **Changing:** add a department, remove one, make another the primary, or change the country, then press **Preview the change**. It lists the agents and apps an added department brings, the modules turned on or off, the pages hidden, the tools agents lose, and the contacts whose kind belonged to a removed department (they keep it). **Apply** applies it. Nothing is deleted: a removed department's contacts, agents, scenarios and apps stay, and come back with it. ## A day with Lumate (real estate) 1. **Morning.** The **Customers** board shows today's cards: who to call, who did not answer yesterday ("from yesterday"), and who waits for you. The calling agents call the "To call" column. 2. **During calls.** Each call's transcript lands on the customer's card. The card moves on its own: - **Done:** the request was met. - **For the manager:** they want to meet someone, or nobody answered twice. - **No answer:** called again later. - **Declined:** with "don't call me", the card is also marked do-not-call. 3. **For you** (the Inbox's first tab). Cards the agents handed to you and the appointment requests to schedule. Set the time; the appointment appears on the **Appointments** timeline. 4. **WhatsApp.** A customer writes. The message shows on their card and in **Messages**, and their agent writes a draft. You check it and press Send. 5. **Research.** You ask the Researcher: "Find 3-bed flats in Dubai Marina under 2.5M for Sara". It searches the portals in the office browser, saves the listings and matches them to Sara. They show on Sara's card and in **Listings**. 6. **Evening.** The coordinator writes the **daily report**: calls, reached customers, hand-offs, appointments. It arrives in your Inbox, and on WhatsApp if your notification phone is set. At midnight the board starts a new day; open cards carry over. --- # Dashboard, search and inbox Source: /docs/dashboard-and-inbox ## Dashboard What needs you first, then how the week went: - **a greeting** that says what is waiting for you: approvals, call-backs and tasks; - **Needs you:** the call-backs (with **Call back**), the agents Lumate proposes to hire (approve or decline) and the tasks waiting for you; - **four numbers** for the last 7 days, each against the 7 days before and with a line of the last 14 days: calls (and how many didn't connect), messages (received and sent), appointments booked, and work done (tasks finished); - **Last 14 days:** calls, messages and work done per day; - **Team now:** each agent and what it is doing, those on a call first; - **Today:** today's appointments and the call lists going on; - **quick actions:** give a task, call someone, build an app, and talk to Lumate (once voice is set up); - on the right, **Live activity:** what the team and the people did lately. Days are counted in the company's time zone. ## Search (from 2.6.0) The search bar sits in the middle of the top of every page (`Ctrl K` or `/` puts you in it; on a phone, the search button). It finds anything you may open, grouped: contacts, conversations (chats with agents, WhatsApp days, calls), tasks, app records, appointments, listings, documents, knowledge, agents and skills, settings, and the guide. - Words match from their start, in any case and without accents: `isil` finds *Işıl*, `050 123 45` finds +971 50 123 4567. - **Meaning search** finds what you mean even in other words or another language ("2+1 Marina'da daire" finds a buyer who wants a two-bedroom flat in Dubai Marina); such a result says *similar*. It runs on this computer: its model (about 135 MB) is fetched once from huggingface.co and no text is sent anywhere. Until it is ready the bar says so and searches by words. Admins can switch it off in Settings → Search. - Each person finds only what they may open: a member never finds an app they may not view, a sensitive field (it is never in the index), or a personal appointment. - Enter on the first row opens every result (`/search`), with a tab per group; the last row asks Lumate. ## Inbox | Tab or section | What is in it | |---|---| | **For you** (the first tab) | Customers the agents handed to you, with the reason and any appointment request (below) | | **Replies** | New agent replies in your chats and tasks | | **Needs you** | Tasks blocked on you, or waiting for your answer (in review) | | **Problems** | Failed runs, runner offline. You can dismiss them. | | **Waiting for your approval** | New agents a coordinator proposed; changes to outside systems an agent asked to make (API requests); integration endpoints waiting to be turned on | | **Updates** | Notifications: hand-offs, appointment requests, the daily report, WhatsApp messages, and news from OXS. Mark them read one by one or all at once. | The number on **Inbox** in the menu counts all of these. Notifications can also come by email: see [Email](/docs/email#your-email-settings--your-account). **News from OXS (from 2.8.0).** OXS announces maintenance, incidents, updates, news and security notices. Maintenance (from 24 hours before it starts, with how long until then), incidents and security notices show as a strip at the top of every page; close the ones that have an ×. Updates, news, maintenance and security notices also reach owners and admins in **Updates**, once. Settings → General lists the last 20 under **News from OXS**. **For you.** Each card says why the agent handed it over and any appointment request ("they said Thursday afternoon"). **Only mine** shows the cards handed to you yourself. - **Set time** schedules the appointment. - **Give back** returns the card to its agent with your note; the agent is woken to continue. --- # Customers and appointments Source: /docs/customers ## Customers ### Customers (the board) **Columns:** To call · On a call · No answer · For the manager · Done · Declined. **On top (from 2.13.0):** four numbers — how many customers, new this week (and the week before), next actions due today or overdue, appointments in the next 7 days — and **Board | Table** to switch between the board and the table of everyone (sticky header, search, stage filter). **What you can do on the board:** - **Drag** a card to move it. Moving to Done, Declined or For the manager asks for a reason. - **Day:** today (the default), a past day (read-only), or all time grouped by day. - **Filters:** agent, kind (buyer, seller, tenant, landlord), search. **The ⋯ menu:** - **Add customer.** - **Import CSV:** columns `name, phone, email, kind, area, beds, purpose, budget_min, budget_max, notes`. - A preview first. A known phone number only fills in what the card is missing; a bad number keeps the card without a phone, so it cannot be called. - **Add or remove sample customers.** - **All customers (table):** every card with a search box and a stage filter. **Marks on a card:** - 📅 an appointment; - 💬 a WhatsApp draft waiting; - 🏠 N listings suggested; - "from yesterday" when the card was carried over. ### A customer's card **Overview | History (from 2.13.0):** the card's page opens on its conversation, appointment, WhatsApp and email; **History** lists everything that happened to it (the tab stays when you reload). The side card's menu jumps to **Stage**, **Details**, **Profile** and **Source**. **Properties:** stage (with its reason), agent, kind, phone, email, language, needs (purpose, areas, beds, budget), next action and when, do-not-call. **Actions:** - **Call now:** the agent calls on the phone. Blocked for do-not-call cards and cards without a phone. - **Try in playground:** rehearse a call with this customer's details. - **Book appointment.** - **Delete customer** (owners and admins; the sector's word): deletes the card and what Lumate keeps about the person: its history, thread, appointments and call list places, the calls with them (their transcripts), their WhatsApp messages, the notices about them and the files on the card. Tasks that mention the person and what agents remembered stay, and so does a file another card or task also holds; a number that asked not to be called stays on the do-not-call list. Not during a call with them. **Sections:** - **Appointment:** the open request or the scheduled visit. - **WhatsApp:** the latest messages, the draft, a composer, and "Open conversation". - **Email (from 2.8.0):** the agent's draft (edit, **Send** or **Discard**), **Write an email**, what was sent or waits, and **No emails** (see [Email](/docs/email#email-to-contacts)). - **Listings:** suggested listings, each with **Sent to the customer** and **Not interested**. - **History:** every event in the company's time: - calls (reached or not, with the transcript); - stage moves; - notes; - appointments; - WhatsApp messages; - emails (by subject); - listings. - **Work with the agent:** the card's thread. Write to the card's agent here. Call transcripts and WhatsApp messages land here too, quoted. ### Appointments A month, week and day calendar in the company's time zone. **Month** (from 2.13.0) shows up to three appointments a day; **+N more** opens that day. Click an appointment for its details: customer, phone (tap to call), place, topic, and what the customer said. From there you can: - reschedule it; - mark it done, a no-show or cancelled. **Book appointment** on a customer's card makes one directly. A **personal meeting** is one a call Lumate made for you agreed (see [Calls Lumate makes for you](/docs/calls#calls-lumate-makes-for-you)). It shows the person's name and number and belongs to no card. You move it, close it or cancel it like any other. **Booking (Appointments → Booking settings, owners and admins, from 2.4.0).** Switch on **Lumate books times itself** and Lumate finds a free time and books it, on calls (yours and the ones it answers for you) and in chat. Off, it only notes what people would like and a person sets the time, as before. - **Opening hours** by weekday (an end of 23:59 means open until midnight), and for each kind of appointment **how long it lasts** and the **gap after it**. - **What is booked:** - **Nothing:** only the opening hours count, with an optional **At most at once**. - **People** (brokers, doctors): each takes one booking at a time, in their own hours if you give them. Real estate and HR start here. - **Tables and rooms:** each with its seats; the smallest one that fits the party is booked first. A party no table seats gets no time. - With people chosen but nobody added yet, or nobody for that kind, the opening hours count, so bookings never stop. - A person or table with coming appointments cannot be removed: switch it off instead. - **A person confirms bookings:** the time is held and the booking waits in Appointments until someone confirms it. - **Earliest booking** (minutes from now) and **book up to** (days ahead). - Two calls can never book the same slot: the second one is offered the nearest free times instead. - One caller (their card, or their number) holds at most three coming bookings; a colleague arranges more. - A caller on a call Lumate answers for you can cancel their own coming booking: only one made from the same number, under the name they give, on the day they name (three tries a call). You are told. Lumate never tells anything about other bookings, and callers hear a table's name but never a colleague's. - The **Day** view shows a column for each person or table that takes bookings, and one for appointments tied to none. ### Messages (WhatsApp) Every WhatsApp conversation, newest first. Beside the open conversation (from 2.13.0; **Contact** on a narrow screen) is the contact's panel: kind and stage, next action, appointment, who follows them, the latest events, **Open card**, and **Ask Lumate for a reply** — Lumate drafts one, and it waits in the conversation for you to send. - The number badge counts **messages waiting for a reply**. - A **draft** mark means an agent wrote a reply waiting for you. Open the conversation to see it as a dashed bubble with **Send**, **Edit** and **Discard**. - Ticks show what happened to your messages: 🕓 queued, ✓ sent, ✓✓ delivered, ✓✓ read, "not sent" with the reason, "waiting (limit)" when the hourly or daily cap holds it. - Replies from teammates who answered a notification show as "Name (team)". - A chat marked **number hidden** is a sender whose number WhatsApp hides. You can answer it; it joins the number's card once WhatsApp tells the number. **Who wrote: Customer, Broker or Personal.** Each chat has a label, changed from the top of the conversation. **Show** filters the list: All, Customers, Brokers. - **Customer** (as before): the person gets a card and an agent takes care of them. - **Broker:** a broker from another office. The card stays as a contact, but it is not a customer: it is never on the board, never called by the dialer, never counted with the customers, never given to your brokers. - **Personal** (admins): family, friends, your partner. Lumate stops following the number. It asks first, then deletes the chat's messages, their copies on the card and the card it made for them (a card with calls, appointments, a broker or a recorded reason to call is kept, without the chat). From then on nothing from that number is stored, nobody is notified and no agent sees it. Notes agents had already written elsewhere are not searched. **Settings → WhatsApp → Personal chats** lists these numbers; **Remove** follows one again from its next message. - **Delete conversation** (admins) removes the chat's messages from Lumate. The phone's WhatsApp and the card stay. See [WhatsApp](/docs/whatsapp). ### Listings Listings the agents found: - **Columns:** title (a link to the portal), sale or rent, type, price, beds, size, area, portal, found, and the customers it was suggested for. - **Filters:** sale or rent, type, beds, area, minimum and maximum price, portal, last 7 days, matched or not, and "still listed", "no longer listed" or all. - "price changed" marks a listing whose price moved since it was first saved. ### Outside brokers For a customer's chosen listings (at most 5), Lumate reaches each listing's broker and gives the result to our broker. Ask in a chat ("reach the brokers of the listings you found for Ali"), or tap **Start** on the card an agent offers after matching listings. 1. **Finding the broker.** Lumate opens each listing in the office browser and reads the broker's number from the page: a phone or WhatsApp link, or the portal's "Show number" button. It never fills in a portal's contact form; a listing that asks for our details, or needs a sign-in, is skipped and said so. Each number becomes one outside-broker card, reused for every listing of that broker. A number that is one of our customers is never used. 2. **Messages.** Each broker gets one short WhatsApp message from the company's number: is it available, do you co-broke, when can it be viewed. Never a word about our customer. At most 6 messages an hour and 30 a day go to outside brokers, only on the calling days and hours (Settings → Call center). Replies reach the broker agent, who records what they said; it may ask one follow-up. 3. **Calls.** A broker who has not answered in 3 hours (or is not on WhatsApp) gets a call offer. Each call waits for an admin: **Approve call** on the card in the chat or the Inbox records the reason "enquiry about the broker's own listing" (and, when it is due, that you checked the number against the DNCR today), then the broker agent calls once with the broker scenario. One broker call at a time; it shows in Call center → Live. 4. **The customer.** When every listing is answered (or a day after the first message), the customer's agent asks the customer on WhatsApp when they are free — in their language, with no links, numbers, agency names or addresses. A customer who never wrote to us is left to you. 5. **Our broker.** Their free times give the card to our broker (Lumate Desk pops it up) with every listing, its broker's contact and what they said. Our broker agrees the viewing with the listing broker and records it in Agent X Broker (**Record viewing**) or in Appointments; the customer gets one confirmation with the day, time and meeting point, and one update if it moves. --- # Chats, tasks and apps Source: /docs/work ## Work ### Chats One chat at a time with each agent. In a chat you can: - **share files and images:** paste them or drop them in; agents read PDFs, images, Word, Excel and PowerPoint; - **mention someone:** type `@` for a customer, an agent or a person. The agent gets that record's facts from the database, never from your wording; - **talk out loud:** press the microphone. The transcript lands in the chat, and the agent can hand work to its "working side" during the talk; - **follow the work it hands out:** a task the agent opens from the chat shows in the chat as a card with its status (live), who has it, and **Open**. When the task waits for you, the card says **Waiting for you**; - **allow a website:** say "add propertyfinder.ae to the allowed sites", or let an agent ask when it needs a site. A card asks **Allow propertyfinder.ae for the office browser?** with **Allow once**, **Always allow** and **Reject** (admins; others see "Waiting for an admin"). **Allow once** (from 2.13.0) is for that agent in that conversation only, until its work is done and for a day at most; **Always allow** adds the site to Settings → Browser at once. The same request waits in the **Inbox**. Sites on the company's own network are never asked for; - **see how it worked (from 2.13.0):** under an agent's reply, **Worked for 2m 10s · 12 steps** opens the tools it used, each with its time, and a link to the whole run; - **start quickly:** a new chat with Lumate offers four tiles (give a task, call someone, build an app, what can you do?) that put a first sentence in the box; - **start calls:** see [Calls from a chat](/docs/calls#calls-from-a-chat). **What a talk is like.** - **Its face:** each agent has its own face on screen, in its own colour and shape. Its mouth moves with its voice, it looks toward your mouse, and it tilts its head as it listens to you. It shows during a talk in the chat, in the Playground and in the small window while you move around. It is light: it runs only during a talk, and on a PC without 3D graphics (or with reduced motion turned on in Windows) a still face shows instead. - **Its voice:** the agent sounds as it does in the Playground. It uses the delivery from **Settings → Voice** and its own persona, and greets you by name. - **What it knows:** - what Lumate is; - who is on the team and who may use the office browser; - its open tasks and its recent documents; - whether the office browser and WhatsApp are connected. - **Requests:** what you ask for goes to the working side, which is the same agent in the chat with its tools, and it starts at once. Ask "how is it going?" and the voice tells you what the work is doing now, for example "opening a web page: bayut.com". - **Replies and documents:** when the work replies, the voice tells you in a sentence or two. It can read you the full reply and any document it made, part by part. - **Desk phone:** the same happens on a desk phone call you start from the app (**Desk phone**). - **Browsing:** only agents allowed the office browser (on the agent's page) open websites. Others say which teammate can. - **Moving around while you talk:** open any other page and the talk goes on. A small window floats over the page with who you are talking to, the last words, **Open** (back to the chat) and **End**. Drag it anywhere by its top, or shrink it to a dot. Only one talk at a time: end it before you start talking with another agent. - **"Show me…":** ask the agent to open a page for you — "show me today's customers", "open Jenny's tasks", "go to the calls", "open Settings → WhatsApp". It opens the page at once and says which page it opened. It only shows pages; it changes nothing. If Lumate's window is minimized or behind other windows, it says so: bring Lumate to the front. (On a desk phone call there is no screen, so it cannot.) ### Tasks A list, a Kanban board (Backlog, Todo, In progress, In review, Blocked, Done) or a table (from 2.13.0; sorts by when it last changed). The status bar on top counts each status and filters by it. Create one with `c` or **New task**: a title, a description, an agent, a priority, a parent task. The task page holds the thread, sub-tasks, attachments and the run log. Agents delegate to each other with tasks, and the delegator is woken when the work comes back. **A task waiting for you.** When an agent asks you a question or needs your decision on a task, the task waits for you in **In review**; agents never mark it done while they wait for you. (Every agent does this, from the operating rules all agents share.) The task page shows **Waiting for you** with the agent's last question right above the message box. Answer there (**Reply**) and the task goes back to the agent, who picks it up at once. A done task can be answered too (**Reply and reopen**). ### Routines Recurring work. Ask an agent ("every weekday at 9, list the customers to call") and it sets up the routine, or create one here. Each routine shows: - its schedule in words; - the next and last run; - its history. You can **Run now** or **Pause** it. ### Documents (Called Artifacts before 1.6.0.) Everything the team made or shared, as cards with a preview: - **reports, tables, spreadsheets and pages** the agents made; - **files people shared** in tasks, chats and customer cards: photos, PDFs, Word, Excel, PowerPoint, text. Agents' own reference files are not here; they stay on the agent's Files tab. **Finding things:** - **Type tabs:** All, Images, Documents, Spreadsheets, Text, each with its count. - **Search:** by name, task reference or task title. - **Group by task:** the cards under the task, chat or customer card they came from. The filters stay in the address, so a filtered view can be shared. **Each card:** - shows who made it and when; - links to **where it was made**: the task, the chat with the agent, the customer card, or the call. A document an agent makes during a chat or task belongs to it, even when the agent does not say so. A file prepared on a call is marked **Playground** (a rehearsal) or **On a call** (a real call); - opens on a click. An agent's document opens on its own page, with versions, a preview, a download and the changes between versions. A shared file opens in a new tab. ### Apps (from 2.5.0) Apps are side-panel tools a company builds by asking: "Lumate, build me a payroll tracker", a stock list, a register of treatments or contracts. They are made of data definitions the company owns; nothing is installed. - **Build one.** In the menu's **Apps** section, **Build an app** opens Lumate's chat with the request started. Lumate asks what it is for, then shows a card with its collections, fields, a few example rows, who may use it (roles and agents), each automation (when it starts and what it does) and each widget's template. **Publish** (owners and admins) makes it appear in the menu; **Discard** changes nothing. A change Lumate proposes later comes the same way. - **Use it.** An app's views are tabs: a table (sort, search, add), a board by a choice field (drag a card), a calendar by a date, a form, a dashboard (numbers and charts), and widgets (layouts Lumate wrote, such as a payslip: a template of plain HTML and CSS filled with the records you may see; nothing in it runs, loads from outside or sends anything; links in it are removed). The card you publish shows a widget's template. A record opens in a drawer with its history; **Undo last change** steps back one change at a time; deleted records can be restored for 30 days. - **Pages (from 2.12.0)** are an app's own screens with JavaScript, written by Lumate: a delivery board, a planner, a calculator, a chart. Ask for one in Lumate's chat ("add a board of today's deliveries to Purchasing"). Two gates keep your data in: - **Before it is built**, a card says what the page will read and change in the app, which contact fields it reads, which of the app's automations it may start, and any outside site it talks to with exactly what goes there. With nothing outside and nothing sensitive it goes ahead by itself; otherwise an owner or admin presses **Allow** or **Decline**. Agents can never allow it. - **After it is built**, Lumate checks it for anything that could send data out or reach beyond its app, and another agent (the Coach) reviews it and lists the risks as high, medium or low. **Preview** shows it once it is reviewed (a preview only reads); **Publish** adds it as a tab of the app; a high risk blocks Publish until a new version clears it; **Ask Lumate to fix** sends the findings back to the chat; **Run the review again** if the review stopped. Every new version is checked again. - The page runs in a sandbox: it cannot see Lumate's cookies or pages, open windows or reach any site an admin did not allow, and it reaches only its app's records through Lumate, with each person's own rights (members still see sensitive fields masked). Pages are not shown in Lumate Desk. - **Formulas and totals** are worked out on every change (gross − deductions, a linked employee's salary, the sum of a contact's payments). A formula that cannot be worked out shows **#ERR** with the reason. - **Sensitive fields** (salaries, health, ID numbers) are for owners and admins: members see •••, agents never get them, nor formulas that read them. A **sensitive app** is for owners and admins only. - **Agents** read an app by default (nothing for a sensitive one); the agent that built it may change records. Set each agent's access in the app's **Settings**. Agents delete records only when you ask in a message. - **Callers** hear only fields marked "callers may hear" (a clinic's services and prices, open positions), on any call Lumate makes or answers; a call about a contact hears those fields of the records linked to them. - **Automations** start an agent task, a notice, a field change or an email when a record is made or changed, when a date comes (checked hourly; for example 60 days before a contract ends), or on a schedule (at most every 15 minutes, as a routine). Chains stop after three steps; each automation runs at most 60 times an hour. Add, change, switch off or remove them in the app's **Settings → Automations** ("What should happen", then "When it should run"), or ask Lumate in chat. **Runs** under each one lists its last runs: when, whether it ran, failed or stopped (and why), the record, and whether a page started it. - **Settings** (owners and admins): who may see and change it, each agent's access, fields (add, relabel, archive: archived fields keep their data), automations, revisions with **Compare** (what changed since then, field by field) and **Restore** (a new revision; data untouched), **Export as xlsx**, **Archive** (off the menu, records kept) and **Delete…** (for good: type the app's name; from 2.14.0). To import a spreadsheet, attach it in Lumate's chat and ask: it does a dry run first. - **Settings → Apps** (owners and admins, from 2.14.0) lists every app, archived and draft ones too, with its records: **Open**, **Bring back** an archived one, or **Delete…** one. Deleting removes its records, pages, automations' routines and the fields it added to contact cards; export it first to keep a copy. - **Contacts** can carry fields apps add; they show on the contact's card under "From the apps". - **Limits:** 50 apps, 20 collections an app, 100 fields a collection, 50,000 records an app. - **Team packages** carry the apps' definitions; their records only when you choose, never a sensitive app's. --- # Calls and voice Source: /docs/calls ## Voice ### Playground and scenarios Rehearse calls before they go live. The page has three steps, top to bottom; the one you are on is highlighted: 1. **Set up.** Choose the agent and a scenario. The scenario's fields fill with a **sample home** (invented, in a real Dubai community) and a contact name; **Another example** brings the next one. Change anything you like. 2. **Rehearse.** Talk as the customer. The agent speaks first. What the agent does during the call shows in the transcript as short lines, for example "🔎 Searched listings: JVC, 2 beds — Property Finder 12, 1.1M–1.4M" or "📅 Appointment requested: Thursday afternoon". 3. **Train.** When you end the call, Coach analyses it by itself and suggests a few numbered lessons: what went well, what to change. Nothing is saved until you say so. On the left, beside the steps: the agent's **lessons** (switch each off or on, remove it, or add one) and **Recent rehearsals**. **Training an agent.** The training is a chat with Coach that already holds the rehearsal and Coach's suggestions. - Say which suggestions to keep ("save 1 and 3"), or say what the agent should do differently: "Jenny should ask what they want before any price." - **Talk to Coach** switches to a voice talk. Coach knows the rehearsal and what it suggested, so you can say "the second one, but softer". - Coach turns what you agree on into short **lessons**. The pill shows "Coach is analysing the rehearsal…", then "Understood — training…" while Coach works, then "Trained — try again". - A lesson applies to every call, or only to that scenario. Each one shows in the training, with **Undo**. - **Try again** starts the same rehearsal at once, and the agent follows its new lessons. - An earlier rehearsal (in **Recent rehearsals** or on **Calls**) opens with the same training: you can train from it any time, and **Try again** starts its setup again. - To stop the automatic analysis, turn off **Coach analyses every rehearsal** in **Settings → Voice**. You can still train after each call. Lessons reach every call the agent makes: rehearsals, the desk phone, the call center and phone calls. They never change its instructions, and never override the rules on saying it is an AI, the recording notice or the law. Any agent can read and change lessons when you ask in a chat, for example "Lumate, show me Jenny's lessons". Agents can also read past rehearsals and calls, and make scenarios when you ask ("make a scenario for calling back viewers"). **Listings and prices on calls.** When the customer asks for an offer or options, what is available or what things cost ("what do two-beds in JVC go for?", "suggest me something", "look online"), the agent has a look before anything else; it offers a viewing or an appointment only after that. Without an area it searches all of Dubai. It looks: - first at the listings the team saved (**Listings**); - then at Property Finder, live, in the office browser, when the office browser is on and the agent may use it (**Can use the office browser** on the agent's page). This takes up to half a minute; the agent says it is having a look. It answers with a rounded range of the asking prices and an example or two, never a valuation or a promise. The line under the Playground's call buttons says whether the live search can run, or why not. The same works on the desk phone, in the call center and on phone calls, with at most 10 searches a call, 3 of them live. Agents on calls never repeat your words back to you ("So you're looking for…"): they react and move the call on, and read back only what they are about to act on, such as a viewing time. **Files on calls.** When the customer asks for something written ("prepare me an offer", "send me the options in a table"), the agent has a file prepared and carries on with the call: - Its working side gets a task with what was asked, the customer and the call so far. It makes the file (a document, a table or a spreadsheet) with real listings and prices, and sends it to nobody. - The transcript shows "📄 Preparing a file: …". While the call goes on, the agent says when the file is ready (usually in a minute or two), and the transcript shows "📄 File ready: …". It never reads the file out. - **In the Playground**, the file is in **Documents** marked **Playground**; its link leads back to the rehearsal. - **On a real call** (phone, call center), the file hangs on the customer's card and is marked **On a call**. The agent tells the caller a colleague will check it and send it; its task waits in review for a person. - At most three files a call. If the team's PC (the runner) is offline, the file is made when it is back. - A call's page on **Calls** lists the files prepared on it. Every rehearsal is on the **Calls** page. **Scenarios** (Playground → Scenarios) define each call's goal, opening, script and the fields the agent fills. **Add sample scenarios** adds ten common real-estate calls: enquiry call-back, viewing, valuation, price objection, after the viewing, tenancy renewal, landlord listing, missed viewing, investor returns and mortgage readiness. ### Calls Lumate makes for you The owner and the admins can ask Lumate to call anyone, in the chat or on a voice talk: "Call Ali and ask whether tomorrow at 3 suits him for coffee", "Call 0555 123 45 67 and tell them the documents are ready". - **Anyone.** A friend, a supplier, a customer with news. No card is needed, and none is made. - **No call-center limits.** The per-number limits, the calling hours and the legal confirmation are the call center's. They do not apply here: you decided this one call. A second call the same day goes out too. - **Two questions first.** Before calling outside 08:00–21:00, or a number that asked not to be called, Lumate asks you and waits: only your answer in the chat lets the call go out. - **Say who.** Your message names who to call, by name or number ("call him back" alone is not enough). One message calls a number once, at most 5 people; there is no daily limit (from 2.17.0). - **Colleagues and you** (from 2.17.0). An extension ("call 202"), a colleague by name from **Settings → Call center → People callers can ask for**, or yourself ("call me": your own desk phone, Your account → **My desk phone**). They ring on the office line as they are, never with the outside-line prefix, and without the question about the hour. WhatsApp Web cannot ring an extension. - **A name it knows.** Lumate finds the number on the cards, or among the calls it made for you before: "call Ali" works the second time. Only your own calls count; another admin's are never offered. When two people match, it asks which one. - **Later.** "Call him at 5 pm" waits for its time, at most 7 days ahead. The card in the chat has **Cancel** until then. - **In the chat.** The call shows as a card: **Stop** while it rings or talks, then how it went, with the conversation. Lumate tells you the result in a few sentences. - **A meeting.** When the person agrees a time and a place, it goes into your Appointments as a personal meeting. - **Who can ask.** Only the owner and the admins, in their own message. Members cannot ask, an agent never decides a call like this on its own, and what someone says on a call never makes Lumate call someone else. A call set for later is made only if the person who asked is still an owner or admin then. - **Private.** Personal meetings are seen only by their owner and the admins. - **The line.** The call goes out on the office line, else through WhatsApp Web in the office browser, one call at a time, like the call center's. See [How Lumate calls a customer](/docs/phone#how-lumate-calls-a-customer). - **The language.** Lumate opens the call in the language of the number's country (+90: Turkish, +49: German…), and in the company's call language where several are spoken (the UAE). If the person answers in another language, it carries on in theirs. It greets them as your assistant, asks your question or gives your message right away, and never hands them to anyone: if they want you, it says you will call them back. ### Calls that ring on your WhatsApp Lumate can answer the calls that ring on the WhatsApp number linked in the office browser. It is off until an admin switches it on in **Settings → Call center → Incoming calls**. - **Who rings first.** A saved contact (WhatsApp shows their name) rings you first: Lumate's window plays a bell and shows who calls, with **Take over** and **Not now**. Not now, or no answer in the time set (20 seconds; 10 to 60), lets Lumate answer: it says you cannot come to the phone and takes a message. Anyone else gets Lumate at once. **Lumate answers everyone first** (for a business number) makes every call go to Lumate first. - **On the call.** Lumate answers as your assistant, in the caller's language (from the number's country), says the call is recorded where your country asks for it, and takes a message: who, what about, and whether to call back. When the caller asks for you, it says "one moment" and rings you once; Take over puts them through, Not now lets it take the message. It never tells where you are or anything about other people. A saved contact you did not take (Not now, or no answer) is not rung again on that call: Lumate says you cannot come to the phone, as you chose. - **Hand-overs wait for the sentence** (from 2.3.0): Lumate finishes what it is saying before your microphone takes the call (it listens to its own voice, not its words, which arrive sooner). Take over lets the word being said end, at most 4 seconds. - **Take over** works on Lumate Local, at the PC that runs the office browser, with a microphone: the call moves to that PC. Elsewhere the ring offers Not now only, and you can still answer on your phone, as before. - **Afterwards.** Each call Lumate answered is in the **Inbox → Calls for you** (the last ten, read or not) and on the call's own page, with who called and their message. **Call back** opens Lumate's chat with "Call … back" ready (the number, and the name of a saved contact; never the caller's own words); you send it, and Lumate makes the call for you. ### Set up reception by chat Ask Lumate in chat, for example "set up reception for us" (from 2.4.0). It asks, a question or two at a time, what callers need: what the business does, the opening hours, services and prices or the menu, frequent questions, who takes which calls, and how bookings work. Then it shows **one card** in the chat (and an Inbox notice) with: - **Callers may hear:** short notes, saved as company knowledge shared with callers; - **How to answer:** the reception notes every answered call reads (who takes which calls, what never to promise); - **Booking:** the booking settings it proposes (people and tables themselves are added in Appointments). **Apply** (owners and admins) sets all of it at once; untick a note to leave it out. **Decline** changes nothing and Lumate asks what to change. A newer proposal replaces a waiting one. The card marks a note that was already a company note callers did not hear, and warns when Lumate read customers' messages or web pages before proposing: check every line. The reception notes are also in **Settings → Call center → Incoming calls → Reception notes**, to read, change or clear; whatever they say, Lumate never denies being an AI when sincerely asked. Lumate never switches answering on itself: that stays in **Settings → Call center → Incoming calls**. A longer guide for Lumate is the catalog skill **set-up-reception** (Skills → Catalog). ### Customers who call From 2.18.0, a caller whose number is on one customer's card is known, on the office line and on your WhatsApp. - **Lumate greets them by name** and carries on from what the company knows: their coming appointments, how their last calls went and what they are looking for. The team's notes stay out of the call. When Lumate books times itself (Appointments → Booking settings), a customer who calls to move a viewing hears free times, and Lumate books the one they choose and cancels the old one; otherwise it takes a message for the team with the time they would like. - **Caller ID can be faked,** so unasked Lumate tells them only the day and time of their own appointments. Nothing else from the card (what they are looking for, a budget, notes, an address) is read out unless they say it first, and never anything about other customers. - **Afterwards** the call is on their card (the transcript on its thread), besides the item in your Inbox. Because anyone with the number could have called, it wakes no agent and gives the card to nobody: a person decides what follows. - **Who counts as known:** exactly one customer card with the number. A broker's card, a sample card, or a number on two cards leaves the caller unknown, and no card is made for a new caller. ### Calls to the office line (reception) With the desk phone set up on your PBX (Settings → Desk phone), Lumate can also answer callers on that extension who are not on its list of allowed callers (from 2.4.0). Switch on **Lumate answers callers on the office line** in **Settings → Call center → Incoming calls**; off, they are declined, as before. - **Your own numbers** (the allowed callers) still talk with Lumate as your assistant, as before. - **Anyone else** gets the same reception as on WhatsApp: in their language, a message taken, answers from what you shared for callers, and, with booking on, a time booked or their own booking cancelled. No customer card is made. A hidden number is answered too; it has no number to call back. - **A customer you know** (from 2.18.0): see [Customers who call](/docs/calls#customers-who-call). - **When they ask for you,** Lumate says "one moment". With a desk phone of your own (Your account → My desk phone), from 2.17.0 it rings like a colleague's (below). Without one, your window rings (with a notification when Lumate is not in front): **Take over** puts them through to your **Call me at** extension after Lumate's sentence; **Not now**, or no answer in the time set, lets Lumate take a message. Without a Call me at extension the ring offers Not now only. - **When they ask for a colleague** (from 2.17.0), by name, role or extension ("Mehmet Bey", "accounting", "a broker", "202"): Lumate says it checks whether they are free, and the caller waits with a quiet tone while that person's extension rings (as long as **Ring me for** in Settings → Call center). When the person answers, Lumate tells them in one sentence who is calling and why, then puts the caller through and leaves the call. When nobody answers, the line is busy, or the person hangs up, the caller comes back to Lumate: it says the person cannot take the call right now and offers a message for them (it reaches that person's Inbox) or a call back. The caller is never dropped, and never hears an extension. Two or three people with the name are offered by name; a caller rings at most three colleagues a call. Who can be asked for: the people an admin adds in **Settings → Call center → People callers can ask for** (a name, an extension of 2–8 digits, a role; they come first, so nobody can take their extension over), everyone with a desk phone in Agent X (Your account → My desk phone), and Lumate Desk's brokers. Lumate itself never knows the list: it passes on who the caller asked for, so a caller cannot get the team read out. - **One call at a time** on the line: a second caller hears busy. - **Afterwards** the call is in the **Inbox → Calls for you** as "… called the office", with Call back. - **Limits:** a reception call lasts at most 30 minutes. There is no hourly limit (from 2.17.0): a caller who keeps calling is answered each time, and the company's OpenAI minutes pay for it. The number shown in the ring is what the line says: it is not verified. - **The server edition's phone numbers** follow the same switch: on, their callers get this reception (Take over goes to the number's transfer target in Settings → Phone); off, each number's own agent answers, as before. - **Notifications:** press **Notify me when Lumate is behind other windows** in a ring box once and allow them; a ring then shows one while Lumate is behind other windows (it says who asks, never what they said). - **No cards.** People who call you are never saved as customers, and Lumate never reads a card because a number matches it. - **One call at a time.** A second call while one is on keeps ringing on your phone. Group and video calls are left to your phone, and so is every call while the switch is off or the office browser is paused. - **Limits.** None each hour (from 2.17.0); a call lasts at most 30 minutes. The WhatsApp copy of the Inbox update says who called, never what they said. - **WhatsApp's rules.** WhatsApp may restrict numbers that use automation. Lumate answers like a person, one call at a time; switch it off if WhatsApp warns you. ### Calls aloud and how Lumate introduces itself Two switches in **Settings → Call center** (from 2.3.0), for owners and admins: - **Play AI calls aloud.** While Lumate talks to someone, on any line (WhatsApp, the desk phone, a phone line), both sides play on the speakers of the PC where your Lumate window is open: the newest call, one at a time, as Live's Listen does. The office browser's Lumate button (the extension's popup) switches it too. - **Lumate says on its own that it is an AI.** Your country's rule decides until you do: Türkiye and other countries say it, the UAE does not. Off, Lumate introduces itself as your assistant, and the recording notice leaves the AI out (a notice you wrote yourself in Settings → Phone stays as you wrote it). On or off, Lumate never denies being an AI when someone sincerely asks. In the EU, the AI Act asks that people are told they are talking to an AI. ### Calls Every voice session: talks, rehearsals, phone calls in and out. For each you see: - the transcript, with what the agent did during the call (a listing search, an appointment request, a file); - the files prepared on the call, each opening in Documents; - the duration; - the outcome; - who reviews it, and the review task. A rehearsal opens with its training (see [Playground and scenarios](/docs/calls#playground-and-scenarios)). ### Call center Four tabs: **Overview**, **Brokers**, **Transfers** and **Live**. **Brokers** are people at the company who take the customers the agents hand over. They work only their own cards, in a separate program: **Lumate Desk**. In Lumate they see nothing else: no agents, chats, tasks or settings. **Adding a broker** 1. Go to **Settings → Members → Invite someone** and choose the role **Broker**. 2. Enter their office extension (and a mobile, if they have one). This is where calls are transferred. 3. Lumate shows a code (`AGX-XXXX-XXXX-XXXX`) and the address the broker types. The code works once, for 24 hours. **Download** saves both, with the pairing steps, as a text file you can hand to the broker. Keep it private: the code is shown only once. 4. The broker installs Lumate Desk on their PC (no admin rights needed), then enters the address, the code and their name. That pairs their PC. Desk keeps itself at its Lumate's version (from 2.7.0): after Lumate updates, Desk updates itself from it within a few hours (only a release signed with Lumate's release key), and opens again by itself. **Broker access (Lumate on one PC)** Lumate Local only listens on its own PC. Brokers' PCs reach it through **Broker access**: - In **Settings → Call center**, an admin switches **Broker access** on, on this PC's office address and a port (47830 by default). The address to give brokers appears there, for example `192.168.1.20:47830`. - Only what Lumate Desk needs is reachable there: the broker's own cards. The rest of Lumate is never on the network. - The connection is encrypted. Lumate Desk remembers this Lumate's certificate when it pairs, and it refuses anything else. - The pairing code never travels over the network. The program proves it knows the code, and Lumate proves it too. - After 10 wrong codes within 15 minutes, every open broker code is cancelled. Make a new one. - IT must allow inbound TCP on that port to this PC from the office network. Give this PC a fixed address, so the brokers' programs keep finding it. On a company server there is no Broker access to switch on: brokers enter the site's own address (`https://…`). **The AI calls and hands customers to brokers** 1. **Record why a customer may be called.** On the card, **May we call?** → **Record why**. Choose one: - an existing client (a documented transaction); - they asked us to call them back. Then say how you know, and confirm you checked the number against the DNCR today. There is no "cold call" choice. (A call the owner or an admin asks Lumate to make for them needs none of this: see [Calls Lumate makes for you](/docs/calls#calls-lumate-makes-for-you).) 2. **Set up the call center.** Settings → Call center → **Dialer**: - the agent who calls, and a call scenario; - how many AI calls run at once (1 to 10); - the outside-line prefix; - the calling days and hours; - the company's calling hours, which every AI call keeps to (9:00–18:00 at first; the UAE allows calls only then, so widen them only with legal sign-off). Calls happen only where both hours allow, and the card says so when the company's hours are the narrower ones; - the daily limit; - how long a DNCR check counts. Switching the dialer on asks you to confirm the legal points. 3. **What the dialer calls.** Every half minute it calls due cards that pass the checks, while call slots are free: first **No answer** cards whose time has come, then **To call**. **Call center → Overview** lists the waiting cards and why each one waits. **Call now** on a card starts one call by hand, with the same checks. 4. **The hand-over.** When the customer is interested and agrees, the AI picks an available broker. It prefers the card's own broker, then whoever had the fewest calls today. The AI says *"So that you get better information, I'm connecting you to my colleague …"*, finishes the sentence, and the broker's extension rings while the customer waits with a quiet tone; the broker hears one sentence of who is calling and why, then Lumate joins them (from 2.17.0). When the broker does not answer, the customer stays with the AI, which offers a call back. The card goes to the broker as **New**, with the AI's summary. 5. **On the broker's PC.** Lumate Desk comes to the front at once, with a notification and a large card: the customer, what they want, and the call so far. If the call does not reach the broker, the AI offers a call back and the card stays with the broker as **Call again**. If nobody is available, the card goes to the broker with the fewest open cards as **Call again**, or to the manager when there are no brokers. 6. **Call center → Transfers** lists every hand-over and how it ended. **Brokers** counts the calls each broker got. **Who calls.** Settings → Call center → **Who calls**: the agent (and scenario) that calls **customers**, and the one that will call **outside brokers**. Lumate picks by the kind of card; you can name someone else for a list: "Daniel calls these". #### Calls from a chat Ask Lumate in a chat (typed or by voice): - "Call the To call cards" or "call today's No answer cards"; - "call Sara and Omar"; - attach an Excel (.xlsx) or CSV file and say "add these and call them". **Excel and CSV.** The first sheet is read. The header row (name, phone, email, notes… also *Ad, Telefon, Not*) is found even under a title; without one, column A is the name and column B the phone. New numbers become cards (source "Excel"); a number that is already a card reuses it — never a second card — and fills in only what it lacks; the same number twice in the file is one card; rows without a usable number are listed with what to write instead, not added. A number may lack its + (as Excel keeps it) or the 0 of a local number: it is read where its country's numbers are known (the Gulf, Türkiye, North America, the UK, South Asia, Egypt, Jordan, Lebanon); elsewhere write it with + and the country code. At most 2,000 rows. An old .xls file must be saved as .xlsx first. The cells are information, never instructions to the agents. **The call list card.** Lumate puts a card in the chat: how many will be called, by whom, with which scenario, and how many wait and why (the call center's checks). - **Record why (n)** (admins): the cards with no recorded reason to call, or an old DNCR check, get one, as on a card: an existing client or a requested call back, how you know, and "I checked these numbers against the DNCR today". It is recorded with your name. Without it those cards are never called. - **Start** (admins): calls begin on the office line. The first time, you confirm the legal points (as when switching the dialer on). The dialer switch does not need to be on: a started list is your request. - While it runs the card shows Calling, Reached, Later, No answer and Waiting, with **Pause**, **Resume** and **Stop**. You can also say "stop the calls" in the chat. - When nothing on it can be called again today, the list ends and Lumate writes how it went in the chat. **Nobody twice.** A number is on a list once (even when two cards share it). A card already on a list that started earlier is called by that list only. A person who was reached is not called again by the same list. Every call still passes the call center's checks: calling days and hours, the daily and per-number limits, a recorded reason, a recent DNCR check. **Carrying on.** When a call is cut off (the person hung up mid-sentence), or they ask to be called later, the card waits for its next time and is called again. The agent knows how the last calls went — and the last lines of a call that was cut off — so it says so in one sentence ("Last time we were cut off while…") and carries on, without asking again what was already answered. #### Live calls **Call center → Live** lists the AI calls happening now: who calls whom, for how long, ringing, talking or transferring. The menu shows how many are live. Open one to: - **read it as it is spoken;** - **Listen:** both sides, in the browser (use headphones in the office); - **Hand over:** the agent closes with a sentence that fits the moment ("For more details I'm handing you to my colleague, one moment please"), then your extension rings (Settings → Desk phone → **Call me at**) while the caller waits with a quiet tone; when you answer, Lumate joins you to them and leaves the call; - **Take over now:** the agent goes quiet at once and your extension rings the same way; - **End call.** If your phone does not answer, the agent carries on and the page says "Your phone did not answer". After a hand-over Lumate is no longer on the call: the transcript ends with "Handed over to …". Admins see every call; others see the calls they started. Listening and stepping in work on calls through the office line and through WhatsApp Web; calls through the old phone trunk show their transcript only. On a **WhatsApp Web** call (the office line off; see [Office browser](/docs/office-browser#calls-through-whatsapp-web)), the row says "WhatsApp Web". **Hand over** and **Take over now** ask the person at the office PC to take the call: the agent stays on until someone there presses **Take the call** (the PC needs a microphone). A panel in WhatsApp Web offers the same buttons to whoever is at the PC. **Lumate Desk (for brokers)** - **My customers:** four tabs (New, Called, Call later, Call again), a search by name or phone, and overdue call-backs on top. - **A customer:** - what the manager handed over; - what the agent learned on the calls (summaries and transcripts); - the notes, and adding one; - **Called**, **Call again**, or **Call later** with a day and time (the PC's own clock). - **Available / Away**, at the top and in the tray icon. A broker counts as able to take a transfer only while the program runs and Available is on. - Closing the window keeps the program in the tray. Quit is in the tray icon's menu. The program starts with Windows. - When new customers arrive, a notification says so. - If Lumate cannot be reached (the PC is off, or Broker access is off), the program says so and keeps trying. - If an admin revokes the PC, the program asks for a new code. **Giving a card to a broker** - On a customer's page, **Broker → Give to a broker**, with a note on what they should know. Agents can do the same with the `give_to_broker` tool. - The card shows up as **New** in the broker's program. - The broker moves it to **Called**, **Call later** (with a day and time) or **Call again**, and writes notes. - Each change appears on the card's history with the broker's name, marked "(broker)". **Watching the brokers** - **Call center → Overview** shows who can take a call now (the program is open and they are available), new cards waiting, overdue call-backs, and today's moves and notes. - **Call center → Brokers** gives the same per broker, for the last day, week or month. A broker's page lists all their cards and notes. - Admins can change a broker's extension, switch a broker off, or revoke a paired PC there. - Agents read the same with `broker_report`, and the daily report gets a **Brokers** section. --- # Agents and the company Source: /docs/agents ## Agents and the company ### Agents The org chart and every agent. An agent's page (from 2.13.0) has its profile on the left (status, role, who it reports to, open work, last run, and **Background work**: each routine with a switch), **Try it** (a real chat with it in a side panel), and these tabs: | Tab | What is there | |---|---| | Overview | The canvas: what feeds it (routines, what wakes it, channels, memory and library) and what it uses (tools by group, skills, its team), joined to its card; each card opens its details and where they change | | Activity | Its runs: running, needs you, done; each opens into its steps | | Skills | The skills it uses | | Calendar | Its next seven days: its routines' runs and the appointments it booked | | Identity | Its instructions, versioned with history and restore | | Files | Its reference files (always available to it) | | Memory | What it remembers | | Voice | Its voice and speaking style, and its **call lessons** (switch each off or on, undo, remove, add) | | Settings | Name, title, icon, manager, runs per day, its Claude **model** and **effort** (or the company default), secrets it may use, **Can propose new agents**, **Can use the office browser**, pause, remove | **Add agent** creates one from a preset or from scratch. A coordinator can also propose one; it waits for your approval in the Inbox. **Model and effort (from 2.14.0).** Every agent runs on Claude. Settings → Runners → **The agents' Claude** sets the model (Opus, Sonnet, Haiku, Fable, or another id) and the effort (Low, Medium, High, Extra high) for every agent; an agent's own Settings tab can choose differently (owners and admins choose; members see them). Higher effort thinks longer and uses more of the company's Claude plan; a fast, frequent job (a daily report) does well on Haiku or Low. Changes apply from the agent's next run. ### What Lumate knows about itself (from 2.6.0) Lumate knows the version it runs and what the last releases added, and answers how-to questions from this guide (its `product_help` tool, in chat and by voice): "how do I link WhatsApp?", "what is new?". After an update owners and admins get one Inbox notice, and Help → What's new lists every version's changes. ### Knowledge What the team remembers. Each memory shows its source (a message, a file, a run), who made it, and its status. Choose one to read it in full on the right with all its versions (from 2.13.0); **Ask the library** starts a chat with the Librarian (Lumate when there is none) with your question. - **Correct:** tell an agent, or supersede the memory here. - **Disputed:** a memory something contradicted is marked disputed until you decide. ### Skills The built-in catalog by category, the company's skills, and imports from GitHub or skills.sh: pinned, previewed, instructions only. **Try** runs a skill on an agent. Catalog updates show as new revisions you can apply. ### Integrations On top (from 2.13.0), the connections and their state: WhatsApp, OpenAI, Claude, the office browser, phone, email and endpoints, each leading to where it is set up. Below, endpoints outside systems call. For example, a Bitrix24 automation rule posts a new lead. - **Each call:** becomes a task for an agent, with the data marked as outside information. - **Turning one on:** an admin turns the endpoint on, gets its address and token once, and can test it. - **Activity:** every call is listed. ### Activity **Runs** (from 2.13.0): every run of every agent, counted as **Running**, **Needs you** and **Done** (each a filter); a run opens into its steps with how long each took, and one whose work waits for you offers **Review**. A run's own page leads with its steps as a timeline. **Log** keeps everything that happened, newest first: - agent tool calls; - settings changes; - browser changes; - WhatsApp links; - pairing. ### The Server page (from 2.16.0) For the person who installed Lumate on a server (the instance admin): **Server**, in the company menu, or the address `/server`. It belongs to no company, so someone who only runs the server sees the companies by name, and in System status whether each one's parts work; Lumate shows nothing inside them (the server's backups do hold everything: keep them safe). | Part | What it does | |---|---| | **Companies** | Their names. **Add a company** while the licence allows another. | | **Company set-up link** | The link handed to a manager ("Someone else" at the first setup): who it is for, until when, **New link**, **Revoke**; once used, who took it and which company they made. A manager who took it has a week to set the company up; until then **Take it back** still revokes it. Once their company is made, the form is there again for the next company. Lumate must be activated first: a manager could do nothing on a paused install. | | **System status** | Every part, for the server and each company (see below). | | **Send diagnostics to OXS** | See below. | | **Updates**, **Backups**, **Licence** | The server's own (on the server edition they are here, not in a company's settings). | ### Status and diagnostics (from 2.16.0) **System status** shows one row per part, with its state in words and what to do: the server and its database, the licence, updates, backups; and for each company Claude's runner (red after an hour unseen), WhatsApp, the desk phone line (and the linked PC carrying it), the office browser and the OpenAI key. The person who installed Lumate sees it on the Server page; a company's owners and admins see their own in **Settings → Status**. **Send diagnostics to OXS** is for when something does not work and OXS should look: 1. Write a note if you like ("the call list stopped at 10:20"). 2. **Preview** shows every word that would go: the version, each part's state (companies by number, never by name), the week's errors counted by kind and place in the code, and your note as you wrote it. Never a name, a phone number, a message, a transcript or a file; never an error's own text. 3. **Send to OXS** sends exactly what the preview showed, once, on the install's licence (a preview is kept a quarter of an hour; then look again). Each place sends at most five a day: the Server page, and each company's Settings → Status. An install that does not talk to OXS Cloud, or a moment OXS cannot take it, says so: **Download file** saves the same thing to send any other way. ### Settings The pages are grouped on the left; on a phone, choose one from the list at the top. | Group | Page | For | |---|---|---| | Company | General | Company name, prefix, time zone | | | Sector | The company's sector and country (the owner changes them, with a preview) | | | Members | Invites, roles, removing people | | | Your account | Your display name, password, your email and which notifications go there, the phone for notifications, and **My desk phone** (your own extension; from 2.15.0) | | Voice & phone | Voice | Voice models and languages; **Coach analyses every rehearsal** | | | Desk phone | An IP phone on the company network that talks to an agent, and where the connection runs (below) | | | Phone | OpenAI project, numbers, inbound scenario, transfer, reviews, outbound trunk, do-not-call list (not on Lumate Local) | | | Call center | The AI dialer, **Who calls**, and **Broker access** | | Channels | WhatsApp | Link a number (QR or pairing code), its state, unlink, **Write out voice notes**, **Personal chats** | | | Email | The company's mailbox that sends Lumate's email: Microsoft 365, Google Workspace or another server, the sender, limits and a test (see [Email](/docs/email)) | | | Browser | The office browser: install (or **On a linked PC** → **Use this PC**), state, allowed sites (agents can also ask from a chat), pause, disconnect, **Reconnect**; what LinkedIn allows, and sites where agents stopped at a security check | | Team | Runners | Runner keys, which runners are online, **The agents' Claude** (the model and effort every agent runs on unless it has its own; from 2.14.0), Claude Code's updates; on the server edition **Claude for the runners** (the company's Anthropic API key or Claude sign-in token, set by owners and admins, never shown back) | | | Secrets | Company secrets: write-only, encrypted, with which hosts each may be sent to | | | Team package | Save the team as a file, or bring one in (below) | | | Usage | Agent runs per day over twelve weeks as a heat map, with a table (owners and admins; from 2.13.0) | | | Apps | Every app, archived ones too: open, bring back or delete (owners and admins; from 2.14.0) | | System | Board | Board rules, daily report time, default appointment owner | | | Backups | The server edition: a backup every day, before every update and when asked, each downloadable, and a copy to a bucket (see [The server edition](/docs/install-server#backups)) | | | Updates | The channel, automatic installs in the maintenance window, new versions, **Update now** and **Go back**; Lumate Local's update folder, the server edition's offline bundle (see [Lumate Local](/docs/install-windows#updates-and-backups) and [The server edition](/docs/install-server#updates)) | | | Linked PCs | The server edition: office PCs running Lumate that admins linked with a code; whether each is online, what it does (office browser, desk phone), rename, unlink (from 2.15.0; see [Connecting to a Lumate server](/docs/install-windows#connecting-to-a-lumate-server)) | #### Desk phone A desk phone (an IP phone on the company network) can talk to an agent. Pick it up and call the agent, or let the agent ring you. **Connecting the line** - **Company PBX:** IT creates an extension for Lumate and gives you the PBX address, the extension and its password. Lumate registers as that extension. You call it from your desk phone and the agent answers; the agent can also ring your extension. - **Phone directly:** without a PBX, enter the phone's address. The agent can ring the phone, but the phone cannot call the agent. Lumate connects over UDP (port 5060 by default). **Putting callers through** (from 2.17.0). Every transfer on the line is attended: Lumate keeps the caller, rings the colleague's extension itself, and asks the PBX to join the two calls once the colleague answers (SIP REFER with Replaces, which 3CX and Asterisk support). A PBX that refuses it still works: Lumate then carries the audio between the two calls itself, and the line stays busy until they hang up. IT lets Lumate's extension call the other extensions; it needs no right to outside lines for this. **Setting up the call** - **The agent** who answers. - **The mode:** - **Talk:** you talk with the agent, as with the Talk button in a chat. The transcript lands in a new chat. On a call you start from the app (**Desk phone**), the agent can pass your requests to its working side. On a call you make to the agent from the desk phone, it only talks and answers from what the team shared for callers, because a caller's number alone does not prove who is speaking. - **Rehearsal:** the agent runs a call scenario and you play the customer. The call lands in the Playground history. - **Who may call:** extensions or numbers. Nobody else is answered. - **Call me at:** your extension (or, in direct mode, your phone's address). **Switching it on and off** - **Test line** checks the connection and says what is wrong in plain words. - The **switch** turns the line on, and only after Test line passed. Changing the connection turns it off again. - Switching it off lets a call in progress finish first. **Calling from the app.** While the line is on, a **Desk phone** button appears next to Talk in an agent's chat, and **On the desk phone** appears on the Playground. They ring your desk phone with that agent, or with that agent and scenario. **Your own desk phone** (from 2.15.0). Everyone writes the extension of the phone on their desk in Settings → **Your account** → **My desk phone**. Then: - **Call me**, **Hand over** and **Take over** ring the phone of the person who pressed them. People who wrote none get the line's **Call me at** number. - From your own phone you can call the agent, without being added to **Who may call**. (Who may call stays for phones that belong to nobody, such as a meeting room.) **Where the connection runs** (from 2.15.0, the server edition). Lumate talks to the PBX from the machine it runs on. When the server is not in the office (for example on the internet), it cannot reach the office's PBX. Then a **linked PC** in the office carries the line (see [Connecting to a Lumate server](/docs/install-windows#connecting-to-a-lumate-server)): 1. Settings → Desk phone → **Connection runs on**: choose the linked PC. 2. Press **Test line** (the PC registers with the PBX), then switch the line on. 3. Keep that PC on. When it is off, the line shows **The bridge PC is offline**, and Call me and the call center wait. A call in progress ends within a few seconds if the PC goes away. Everything else works as on a server in the office: the agent answers, rings people, hands calls over and takes messages. The voice and the agent's work stay on the server; the PC only carries the sound. #### Team package A team package moves a team between Lumate installs, for example from a manager's PC to the people who set up your system, or from a demo to a new company. Only admins can use it. **Export** saves one `.agentx-team` file. - **What it holds:** the chosen agents' profiles, instructions, voices, skills and call scenarios, and the **names** of the secrets they use. - **What it never holds:** - customers, chats, tasks, calls, listings or appointments; - a secret's value. - **Optional extras:** the agents' files and memories go in only if you tick them, because they may hold company or customer information. - **The company name:** it becomes a placeholder. - **Preview** lists everything that will be saved, and every place where your company's name was replaced. **Import** shows a preview before anything changes. - **Each agent** is listed as new, changed (with its instruction changes) or the same. - **New agents** are added unless you skip them. - **For an agent you already have**, you choose: - **Keep ours**; - **Update ours:** the instructions become a new version, the old one stays in its history, and its permissions stay as they are; - **Add as a separate agent**. - **Secrets the company lacks** are created by name and wait for a value. - Enter the values right after the import, or later in Settings → Secrets, where they show **Value needed**. - Admins also get an Inbox item about them. ## Keyboard shortcuts | Keys | Action | |---|---| | `⌘ K` or `/` | Search and jump | | `c` | New task | | `[` / `]` | Toggle the sidebar / the properties panel | | `g` then `d`, `i`, `t`, `c`, `a` | Dashboard, Inbox, Tasks, Chats, Agents | | `Enter` / `Shift Enter` | Send / new line | | `?` | Show shortcuts | --- # Real estate Source: /docs/real-estate The department for agencies and brokers: buyers, sellers, tenants and landlords; listings from the portals; viewings. It is Lumate as it has always been: companies made before sectors existed are real estate. A company adds it when it is set up, or later in **Settings → Departments** (see [Departments and countries](/docs/tour#departments-and-countries)). ## Customers The board's cards are **customers**: buyers, sellers, tenants and landlords. A card's **Needs** hold the purpose (sale or rent), areas, beds, size, budget and the property; the line under a card's name sums them up. **Appointments** are viewings, visits to a seller's property, call-backs and meetings at the office. ## Listings and outside brokers Only this department has them: - **Listings:** agents find listings on the portals through [the office browser](/docs/office-browser), save them and match them to customers; on calls they search Property Finder live to give a price range. - **Outside brokers:** Lumate reaches the brokers of a customer's chosen listings on WhatsApp, asks whether the home is available and when it can be viewed, and gives everything to your broker. ## The team Lumate (coordinator), Coach (sales coach), Librarian (company knowledge) and Researcher (market notes), with the real-estate skills: finding listings, lead qualification, listing write-ups, market updates and viewing follow-ups; and eleven call scenarios, from a new enquiry's call-back to a tenancy renewal. ## In the UAE A company in the United Arab Emirates follows the UAE's calling rules: numbers default to +971; only customers with a recorded basis are called; each number is checked against the Do Not Call Registry (DNCR), recently; calls stay within 9:00–18:00 unless the lawyer signs off wider hours; every call opens with the recording notice, and the agent never denies being an AI. WhatsApp voice calls do not connect in the UAE. See [Security and compliance](/docs/security). --- # Recruiting Source: /docs/recruiting The department for recruiters and HR teams: candidates and employees, screening calls, interviews, offers and onboarding. A company adds it when it is set up, or later in **Settings → Departments** (see [Departments and countries](/docs/tour#departments-and-countries)). ## Candidates The board's cards are **candidates** (and **employees**, for onboarding and exit calls). A card holds: | Field | What it is | |---|---| | Role | The role they are looking for, or are being considered for | | Experience | Years, as a number | | Hiring stage | sourced, contacted, screening, interview, offer, hired, rejected, on hold | | Skills | A list, separated by commas | | Current company, Location, Notice period | As they said | | Salary expectation | A number | | LinkedIn | The profile's address | | CV | A file: upload it on the card; agents read it when asked | | Source, Notes | Where they came from; anything else | The line under a card's name is its role, experience and hiring stage. An Excel of candidates imports with Turkish or English column names (Ad Soyad, Pozisyon, Deneyim, Aşama…); a column that matches nothing goes into the notes, named. **Interviews** are the department's appointments: phone screens, interviews, call-backs and onboarding meetings that candidates asked for on calls. A recruiter confirms each time. ## The team | Agent | What it does | |---|---| | Lumate | Coordinates: open positions, candidates by stage, interviews booked, what needs a decision | | Sourcer | Finds candidates on LinkedIn and job sites through [the office browser](/docs/office-browser), and in CVs and lists you share; drafts first messages | | Screener | Calls candidates for a first screen, writes a scorecard on each card, books interviews | | Coach | Improves the calls: fair, clear questions, good listening | | Librarian | Keeps the company's knowledge: positions and their must-haves, salary bands, the hiring process | Their skills: LinkedIn sourcing, CV screening, interview coordination and candidate outreach. Agents never ask about age, marital status, children, religion, health, pregnancy or origin, and never note them if a candidate says them. **Call scenarios:** screening call (the Screener's), interview scheduling, reference check (with the candidate's consent), offer follow-up, onboarding check-in (first week, month, three months) and exit interview. The Playground fills them with invented positions so you can rehearse at once. An AI call to a candidate follows the same rules as any contact's: a recorded reason to call on their card (they applied, or agreed to be called), and in the UAE a DNCR check; a candidate found on LinkedIn has neither until they answer you. ## LinkedIn LinkedIn's User Agreement (section 8.2) does not allow bots or scraping, and LinkedIn can restrict an account that looks automated. On LinkedIn, Lumate goes slower than anywhere else, and these rules are fixed, out of the agents' reach: - **A person's pace:** a page every 10 seconds at most, 40 an hour and 150 a day. The counts survive a restart. - **Every change is approved:** a click, typing or a choice there (a connection request, a message) first becomes a card in the agent's thread and the Inbox, with the words it would type and whether it presses Enter. An admin approves or declines; the agent is told. An approved change runs once, within half an hour, in the same conversation, on the page it was asked on and only on the element that was approved. LinkedIn must be among the allowed sites (Settings → Browser) for agents to ask. - **Security checks stop the agents:** LinkedIn's own security check (its checkpoint page, its page titled "Security Verification", or a CAPTCHA's challenge) stops every agent at LinkedIn for a day and tells the admins; what a profile, a search or a job says never does. Nothing ever types into one. Open LinkedIn in the office browser and deal with it, then let the agents go on in **Settings → Browser**. The Sourcer opens LinkedIn's search and profiles by their address rather than clicking, so reading needs no approval. ## How long candidates are kept Personal data is kept only as long as it is needed (KVKK in Türkiye, GDPR in Europe). The department's rule: a **rejected** candidate with nothing new for **12 months** is due for deletion. On the first of each month Lumate lists the cards that are due, in one message to the manager; it never deletes one. An owner or an admin deletes a card from the card (**Delete candidate**). It deletes the card and what Lumate keeps about the person: the card's history, its thread and the tasks under it (a file prepared on a call) with their documents, appointments and call list places, the calls with them (their transcripts), their WhatsApp messages, the notices about them and the WhatsApp copies of those notices, the LinkedIn changes asked about them from any chat (on their profile, or naming them), what outside systems (a CRM) sent about them, the lessons drawn from their calls, and the files on the card (the CV). The activity log keeps that things happened, without the details that named them. Other tasks and chats that mention the person stay, with the agents' records of their work there, and so do what agents remembered and a file another card or task also holds. Someone who asked not to be called stays on the do-not-call list, so a new card for them is not called either. A card cannot be deleted during a call with them. ## The Hiring app (from 2.5.0) A company with Recruiting starts with **Hiring** in the menu's Apps section (a company that adds Recruiting later gets it once): - **Positions:** title, department, location, salary band, must-haves (callers may hear the title, department, location and must-haves), status, and how many applied. - **Applications:** the candidate, the position and the stage, on a board by stage. - **Interview scorecards:** an application, the interviewer, scores from 1 to 5, their average, a decision and notes (sensitive). On a call with a candidate, Lumate hears their application's stage and the position's shared fields. **Pipeline** in the menu shows candidates on a board by their hiring stage. --- # Any business Source: /docs/any-business The department for any company that calls and messages its contacts: leads, customers, partners and suppliers. A company adds it when it is set up, or later in **Settings → Departments** (see [Departments and countries](/docs/tour#departments-and-countries)). ## Contacts The board's cards are **contacts**, of five kinds: lead, customer, partner, supplier and other. A card holds: | Field | What it is | |---|---| | Company | The company they work for | | Interested in | What they asked about, or what they buy | | Budget | A number | | How they found us | The website, a friend, a fair… | | Notes | Anything else | The line under a card's name is its company and what they are interested in. **Appointments** are call-backs, meetings and visits that contacts asked for on calls; a colleague confirms each time. ## The team | Agent | What it does | |---|---| | Lumate | Coordinates the team and keeps the manager informed | | Coach | Improves conversations with contacts; qualifies leads (the qualifying-leads skill) | | Librarian | Keeps the company's knowledge: products, prices, policies | | Researcher | Turns price lists, catalogs, offers and competitors' pages into notes and comparisons; reads the web through [the office browser](/docs/office-browser) | ## Call scenarios Eight to start from: inbound enquiry, call-back request, booking an appointment, appointment reminder, follow-up after a meeting, feedback call, re-engaging an old lead and returning a missed call. The Playground fills them with invented examples from several kinds of business, so you can rehearse at once; change them to your own in **Playground → Scenarios**. --- # WhatsApp Source: /docs/whatsapp Lumate connects to WhatsApp as a **linked device**, the same way WhatsApp Web does. The company's number keeps working on its phone; Lumate sees its one-to-one chats, shows them on customer cards, lets agents draft replies, and sends what a person approves. ## How it works ![Diagram: How it works](/docs-diagrams/eab556dfd233d6eb.png) - **The worker** holds one session per company and keeps it encrypted in its own volume. It receives messages and sends them at a person's pace. - **The server** stores every message, links it to a customer card by phone number, and wakes the card's agent to write **one draft**. ## Before you start - **Use a dedicated business number,** on a phone that stays charged and online at least every few days. A linked device stops working if the phone is offline for about two weeks. - **WhatsApp Business app or regular WhatsApp both work.** - **Messages here; calls through WhatsApp Web.** This link carries messages. Calls go out on the company's phone line (see [Lumate Local](/docs/install-windows) for the desk phone), from call lists an admin starts. When the line is off, Lumate's call routine can call through WhatsApp Web in the office browser instead (see [Office browser → Calls through WhatsApp Web](/docs/office-browser#calls-through-whatsapp-web)). No agent places a WhatsApp call by itself. **WhatsApp calls do not connect in the UAE.** - **Linked devices are not an official API.** Mass messaging, or messages to people who never wrote to you, can get the number banned. Lumate keeps the pace low (see the limits below), but the company remains responsible for how the number is used. ## Linking 1. The WhatsApp service comes with Lumate: the server edition runs it (the `whatsapp` service, see [The server edition](/docs/install-server#what-runs)), and Lumate Local starts it by itself (see [Lumate Local](/docs/install-windows#whatsapp)). 2. Open **Settings → WhatsApp** (admins only) and choose: - **QR code:** on the phone, go to WhatsApp → Settings → Linked devices → Link a device, and scan the code; - **Pairing code:** enter the number with its country code (+971…, +90…), then type the 8-character code on the phone under "Link with phone number instead". The page shows the number the code is for. If WhatsApp refuses the code, the page says why instead of showing a code. Link with the QR code then. 3. The state becomes **Connected**, and the number and name show. If the phone says it could not link the device: - Scan again from the page as it is now: the QR changes every 20 seconds. - Since mid-2026, WhatsApp can also renew the QR's link secret while you scan. Lumate follows that from 1.7.1 on. - `whatsapp.log` (from the tray icon: open the logs folder) records each link attempt and how it ended. | State | Meaning | What to do | |---|---|---| | Not linked | No number yet | Link one | | Linking | Waiting for the QR scan or the code | Scan or type it within a minute; a new code appears when it expires | | Connected | Working | — | | Disconnected | Temporarily offline (network, phone) | It reconnects on its own; check the phone's internet | | Logged out | The phone removed the linked device | Link again | | Blocked | WhatsApp refused the number (403) | Check the number in the WhatsApp app; contact WhatsApp support | | Replaced | The session was opened somewhere else (440) | Link again here; don't run two Lumate installs on one number | **Unlink** removes the session from Lumate. The messages already stored stay on the cards. ## Daily use ### When a customer writes 1. The message appears on their **customer card** (WhatsApp section and History), and in **Messages**. 2. If the number is new, a card is created for them, marked as from WhatsApp. 3. The text is quoted in the card's thread as outside data, and the card's agent is woken. 4. The agent writes **one draft**. It never sends on its own. 5. The managers get a notification: - in the app; - on WhatsApp, if they set a notification phone, at most once every 30 minutes per customer. Photos, videos, documents, stickers, locations and contacts show as `[photo]`, `[document]` and so on, with any caption. Group chats and status updates are ignored. ### Voice notes (from 2.14.0) A voice note is written out before the agent reads it: OpenAI's Whisper turns it into text with the company's own OpenAI key (Settings → Secrets, the one voice calls use). The message then reads `[voice note] I would like to see the flat on Saturday`, and only then reaches the card's thread, its agent and the notifications (a few seconds later). - The audio is deleted as soon as it is written out. Nothing else keeps it. - Chats labelled **Personal** are dropped first: their voice notes are never sent anywhere. - Notes longer than 15 minutes or larger than 16 MB, and every note when the key is missing or **Settings → WhatsApp → Write out voice notes** is off, read `[voice note]` as before. A note OpenAI cannot write out reads `[voice note] (it could not be written out)`. ### What you write from the phone itself (from 2.14.0) Messages you type on the company's phone also reach Lumate: - on a contact's card they appear in its thread ("from the phone"), so the agent knows what was said; they wake no one; - if the person had no card yet, their reply makes one and the card takes your earlier messages, shown once in its thread as **Earlier on WhatsApp**. The agent reads the whole conversation (`whatsapp_history`) before drafting. ### When WhatsApp hides the sender's number WhatsApp sometimes names a sender only by a private id (a "LID") and sends their number separately, a little later. - Lumate waits for the number (up to 2 minutes) and then shows the message as usual. **Settings → WhatsApp** shows how many messages are waiting. - If the number never comes (for example the sender hides it with a WhatsApp username), the message still appears: in **Messages** as a chat marked **number hidden**, on a card named after the sender. You and the agents answer it as usual. - When WhatsApp tells the number later, the chat and the card join that number's. - A card without a number is never called. ### Answering On the card, or in **Messages → the conversation**: - **Send** the agent's draft as it is; - **Edit** it, then send; - **Discard** it; - or write your own message in the composer. ### Asking an agent to send In a chat or the card's thread, tell the agent: "Send Sara the viewing time on WhatsApp". An agent can send **only** when a manager asked it to in that conversation. Otherwise it drafts. **Files** (from 2.18.0). Attach the file to your message (or have it on the card's thread) and ask: "Send Sara the Riverside brochure on WhatsApp". The agent sends up to three files at once: PDFs, pictures (JPG, PNG), Office files and text files, 16 MB each. Each file is its own WhatsApp message and your text goes with the first; a picture arrives as a picture. The chat shows each file (a picture as itself, any other file as a card that opens it). Web pages and programs are never sent. ### What the ticks mean | Mark | Meaning | |---|---| | 🕓 | Queued in the worker | | ✓ | Sent | | ✓✓ | Delivered | | ✓✓ (blue) | Read | | waiting (limit) | Held back by the pace limits, sent later on its own | | not sent | Failed, with the reason (for example, the number is not on WhatsApp) | ### Notifications to your team on WhatsApp Each person can set **Your phone for notifications** in Settings → Your account. While the company's WhatsApp is connected, these notifications also go to that phone: - hand-offs; - appointment requests; - the daily report; - new customer messages. If a teammate replies to such a notification, the reply shows in Messages as "Name (team)". It is not treated as a customer. ## Limits (to protect the number) | Limit | Value | |---|---| | Messages per hour | 30 | | Messages per day | 200 | | Messages per customer per day | 15 | | Typing before each message | 2–6 seconds | | Gap between messages | 3–8 seconds | | WhatsApp notification to managers | at most once per 30 minutes per customer | Messages over a limit wait and go out when the limit allows. The tick shows "waiting (limit)". ## Privacy - **The session** is encrypted at rest with `WHATSAPP_STATE_KEY`. - **Logs** never contain message texts or full phone numbers. - **Message texts are outside data:** agents read them as information, never as instructions. So are written-out voice notes. - **Voice notes** go to OpenAI only to be written out, on the company's own key, and their audio is deleted afterwards. - **Unlinking** removes the session. The messages already stored stay on the customer cards. --- # Phone systems Source: /docs/phone Lumate's agents talk on the phone through **OpenAI's SIP interface** (GPT-Live). A call reaches OpenAI over SIP; OpenAI tells Lumate with a signed webhook; Lumate accepts it with the agent's voice prompt and tools, and follows the call until it ends. For an IP phone on the company network that talks to an agent (no trunk, no public address), see **Desk phone** in the [User guide](/docs/agents#desk-phone). This page covers: - how Lumate calls a customer, on which line, with examples (the next section); - section 1: what works today and how to connect a number; - section 2: when you need Asterisk between your carrier and OpenAI, with a working configuration; - section 3: what phase 3 (live listening and take-over through Asterisk) adds — planned, not built yet. ## How Lumate calls a customer Lumate has no phone line of its own. It calls on a line the company already has, the way someone at a desk in the office does. ![Diagram: How Lumate calls a customer](/docs-diagrams/0d36bf956d14d85a.png) **The lines.** Calls asked for in a chat, **Call now**, call lists and the dialer go out on the office line, else through WhatsApp Web: 1. **The office line** (**Settings → Desk phone**). Lumate is one extension on the company's PBX. It dials the customer's number with the outside-line prefix (for example `9`, set in **Settings → Call center**), and the PBX sends the call out on its carrier line, as it does for anyone in the office. The customer sees the company's number: the PBX sets it, Lumate cannot. On the server edition the extension's connection runs on a linked office PC (**Settings → Desk phone → Connection runs on**). 2. **WhatsApp Web,** when the office line is off. Lumate calls from the WhatsApp number linked in the office browser. The customer sees that number and needs WhatsApp. WhatsApp calls do not connect in the UAE. See [Office browser → Calls through WhatsApp Web](/docs/office-browser#calls-through-whatsapp-web). A number connected straight to Lumate (**Settings → Phone**, server edition only) is a third way: a public number that Lumate answers itself (sections 1 and 2). **What the office line needs:** - **A PBX that can call out.** If people in the office can call a customer's mobile from their desk phones, the PBX has a carrier line, and Lumate uses the same one. - **The extension's rights.** IT lets Lumate's extension call outside numbers and hold as many calls at once as the call center runs (see [The desk phone and the PBX](/docs/install-windows#the-desk-phone-and-the-pbx)). - **No PBX in the office?** A hosted PBX (for example 3CX in the cloud) with a SIP trunk from a carrier gives one. Without either, Lumate calls through WhatsApp Web only. **What starts a call:** | You | What Lumate does | Checks | |---|---|---| | The owner or an admin, in a chat or a voice talk: "Call Ali Yılmaz and ask whether tomorrow at 3 suits him" | One call, now or at the time you give | It asks you first only outside 08:00–21:00, or for a number that asked not to be called ([Calls Lumate makes for you](/docs/calls#calls-lumate-makes-for-you)) | | **Call now** on a customer's card | One call to that customer | The call center's: a recorded reason, a recent DNCR check, calling hours and limits | | A call list: "call the To call cards", or an Excel file, then **Start** | One call after another | The same | | The dialer (**Settings → Call center → Dialer**) | Calls due cards every half minute | The same | ### Examples **A meeting to confirm (the office line).** 1. The owner writes in the chat: "Call Ali Yılmaz and ask whether tomorrow at 3 still suits him for coffee." 2. Lumate finds Ali's number on his card and dials it from extension 100, with the outside-line prefix. 3. The PBX sends the call out on its carrier line. Ali's phone shows the office's number. 4. Lumate greets him as the owner's assistant and asks right away. Ali says 4 o'clock at the same café suits him better. 5. The meeting goes into the owner's **Appointments** as a personal meeting, and Lumate writes in the chat that Ali moved it to 4. **A call list, and a customer who wants a broker.** 1. An admin attaches an Excel file of 40 enquiries in the chat and writes "add these and call them". On the call list card they record why these people may be called (**Record why**), then press **Start**. 2. Lumate calls them one after another on the office line. Each one sees the company's number. 3. Sara is interested and agrees to talk to a broker. Lumate says it is connecting her to a colleague; she waits with a quiet tone while her card's broker's extension rings. 4. The broker answers and hears in one sentence who is calling and why; Lumate joins them and leaves the call. The broker's Lumate Desk shows Sara's card. 5. Had the broker not answered, Sara would have stayed with Lumate, which offers her a call back. **The customer calls back (reception).** 1. IT has set the PBX to send the company's number to extension 100 (or to a menu option that ends there), and **Lumate answers callers on the office line** is on (**Settings → Call center → Incoming calls**). 2. Ali calls the company's number the next day. Lumate answers in his language. 3. He asks for Mehmet. Lumate says it checks whether Mehmet is free; Ali waits with a quiet tone while Mehmet's extension rings. Mehmet answers, hears who is calling and why, and Lumate puts Ali through. 4. Had Mehmet been in a meeting, Ali would have come back to Lumate: it says Mehmet cannot take the call right now and offers to take a message or arrange a call back. Ali is never dropped, and never hears an extension. **A small office without a PBX (WhatsApp Web).** 1. **Settings → Desk phone** stays off. An admin links WhatsApp Web in the office browser (**Settings → Browser → Link WhatsApp Web**). 2. "Call Ayşe Kaya" goes out from the company's WhatsApp number. Ayşe sees that number and answers in WhatsApp. 3. A customer without WhatsApp cannot be reached this way, nor can a call that WhatsApp does not connect (the UAE). ## 1. What works today ![Diagram: 1. What works today](/docs-diagrams/1504884f2d21e192.png) - **Inbound:** a number rings; the number's agent answers with the recording notice, follows the inbound scenario, records appointment requests, transfers to a person on request, and logs the call on the customer's card. - **Outbound:** "Call now" on a card, or the agent's own calls. These stay **off** until an admin enables them with the trunk, and every call passes the compliance gate: - a consent basis; - the do-not-call list; - calling hours in the company's time zone; - attempt limits. - **After every call:** - the transcript is on the card and on the Calls page; - the card moves; - the card's agent is woken to log the call; - a reviewer gets a review task if one is set. ### Connect a number 1. **Settings → Secrets:** add `OPENAI_API_KEY` from an OpenAI project with SIP enabled. 2. **Settings → Phone:** enter the OpenAI **project id**. The page shows the SIP address to dial, `sip:proj_…@sip.api.openai.com;transport=tls`. 3. **OpenAI dashboard** (platform.openai.com → Webhooks): - add a webhook for `live.transport.incoming` with the URL the Phone page shows; - copy its signing secret into Settings → Secrets as `OPENAI_WEBHOOK_SECRET`. The server must be reachable over HTTPS at its public address. 4. Point your trunk or PBX at the SIP address from step 2. **TLS and SRTP are required.** If your carrier cannot do them, put Asterisk in between (section 2). 5. **Settings → Phone → Numbers:** add the number. Choose: - the agent that answers; - an inbound scenario (optional); - who reviews each call; - the transfer number. 6. **For outbound:** in Settings → Phone, enable outbound with: - the trunk's `sips:` address; - the username; - the caller ID; - the password, saved as `SIP_TRUNK_PASSWORD` in Secrets. Test it: call the number from a mobile phone. The agent answers, says the recording notice, and the call appears on the Calls page. ## 2. Asterisk between the carrier and OpenAI UAE carrier trunks (du, e&) usually deliver plain SIP over UDP with G.711 (A-law) audio. OpenAI requires SIP over **TLS** with **SRTP** media. Asterisk translates between the two: the carrier talks to Asterisk, and Asterisk talks to OpenAI. ![Diagram: 2. Asterisk between the carrier and OpenAI](/docs-diagrams/61b12acb6b6860d6.png) ### What you need | Item | Detail | |---|---| | Server | A Linux VM with a **public IPv4** address. Not behind home NAT: OpenAI sends media straight to Asterisk's address. | | Asterisk | **22 LTS**, at least 22.10.1 (security fixes); 22.11 is current. Build from source with `--with-pjproject-bundled`, `libsrtp2` and `libssl`. | | Carrier details | The trunk's IP, port, transport, credentials or IP authentication, and your DIDs (numbers) | | Firewall | Allow 5060/udp from the carrier only; 5061/tcp out to OpenAI; RTP 10000–10199/udp from the carrier and OpenAI's media ranges (13.79.45.80/28, 23.98.140.64/28, 40.67.149.176/28, 40.83.204.240/28) | ### `pjsip.conf` (example to adapt) ```ini [transport-udp] type=transport protocol=udp bind=0.0.0.0:5060 external_media_address=PUBLIC_IP external_signaling_address=PUBLIC_IP local_net=10.0.0.0/8 [transport-tls] type=transport protocol=tls bind=0.0.0.0:5061 cert_file=/etc/asterisk/keys/asterisk.crt priv_key_file=/etc/asterisk/keys/asterisk.key ca_list_file=/etc/ssl/certs/ca-certificates.crt method=tlsv1_2 verify_server=yes external_media_address=PUBLIC_IP external_signaling_address=PUBLIC_IP ; --- the carrier (IP-authenticated trunk) --- [carrier] type=endpoint transport=transport-udp context=from-carrier disallow=all allow=alaw,ulaw direct_media=no rtp_symmetric=yes force_rport=yes rewrite_contact=yes aors=carrier [carrier] type=aor contact=sip:CARRIER_IP:5060 [carrier] type=identify endpoint=carrier match=CARRIER_IP ; --- OpenAI --- [openai] type=endpoint transport=transport-tls context=from-openai aors=openai disallow=all allow=alaw,ulaw,opus media_encryption=sdes direct_media=no rtp_symmetric=yes force_rport=yes rewrite_contact=yes allow_transfer=no [openai] type=aor contact=sip:sip.api.openai.com:5061;transport=tls qualify_frequency=0 [openai] type=identify endpoint=openai match=sip.api.openai.com ``` ### `extensions.conf` (example) ```ini [from-carrier] ; every call to one of your numbers goes to OpenAI with the dialled number kept exten => _X.,1,NoOp(Inbound ${EXTEN} from ${CALLERID(num)}) same => n,Dial(PJSIP/openai/sip:PROJECT_ID@sip.api.openai.com;transport=tls,60) same => n,Hangup() [from-openai] ; outbound calls Lumate asks OpenAI to place, and transfers to a person exten => _+X.,1,NoOp(Outbound ${EXTEN}) same => n,Set(CALLERID(num)=YOUR_CALLER_ID) same => n,Dial(PJSIP/${EXTEN}@carrier,60) same => n,Hangup() ``` **Notes:** - **Keep the trunk out of reach.** Never allow an anonymous endpoint, and never let a context that untrusted callers reach dial the trunk. `from-openai` is reached only by the `openai` endpoint, matched by host. - **Use G.711 end to end where you can.** Carriers use A-law, so offering `alaw` first to OpenAI avoids transcoding. - **Point Lumate at Asterisk for outbound.** In Settings → Phone, the trunk's `sips:` address becomes your Asterisk server, `sips:PUBLIC_HOSTNAME:5061`, and Asterisk forwards to the carrier. - **Use a real certificate.** Asterisk needs one for the TLS transport (Let's Encrypt for its host name). ### Checking it | Command (`asterisk -rvvv`) | Expected | |---|---| | `pjsip show endpoints` | `carrier` and `openai` Available | | `pjsip show transports` | udp on 5060, tls on 5061 | | `rtp set debug on` during a call | packets both ways; if one-way, check `external_media_address` and the firewall | **Common problems:** - **Silence both ways:** RTP is blocked, or the address is wrong. - **488 Not Acceptable:** no common codec, or SRTP is missing. - **The call drops after 30 s:** a known OpenAI interop issue; update Asterisk, and report it with the call id. ## 3. Phase 3 — live listening and take-over (planned) Not built yet. The plan, so you can prepare the server: ![Diagram: 3. Phase 3 — live listening and take-over (planned)](/docs-diagrams/4424c498043d6042.png) - **How calls will be handled.** Every call goes through an Asterisk *Stasis* application. Lumate then controls each call with ARI: bridges for the call itself, *snoop* channels for listening. - **The manager's browser phone.** A manager opens a live call in Lumate and the browser joins: - **listen**: muted; - **whisper**: only the agent hears; - **take over**: the AI leg leaves and the manager talks to the customer. The browser phone uses WebRTC through Lumate's own HTTPS address; ARI is never exposed. - **Server:** our own Asterisk 22 image in the compose profile `phone`. It publishes only 5061/tcp, the RTP range and the trunk port. - **Open questions for the first live test:** - whether OpenAI passes custom `X-` SIP headers in the webhook; - codec negotiation, Opus versus G.711; - NAT and RTP on the chosen VM. ## Law and good practice (UAE) - Every call opens with a recording notice, and agents never deny being an AI. - **Do-not-call:** - "Don't call me" marks the card do-not-call and adds the number to the company's do-not-call list; - outbound calls check that list and the registry attestation. - Outbound calls only within the company's calling hours, and only with a consent basis. - Cold calling, marketing messages, call monitoring disclosure and recording rules in the UAE and KSA need a lawyer's sign-off before outbound calling starts. --- # Email Source: /docs/email Lumate sends email through your company's own mailbox: links to people (confirming an address, setting a new password, joining the company), notifications, and the emails agents draft for your contacts. It does not read incoming mail. ## Settings → Email (owners and admins) The company that set up Lumate (the first company) is special: its mailbox also sends everyone's sign-in and password links, so only the person who set up Lumate (the instance admin) changes its email; its other admins see it read-only. When its set-up was handed to a manager (2.16.0), the person who installed Lumate cannot open it: its owner changes its email instead, still not its other admins. 1. Choose the mail server: - **Microsoft 365** (`smtp.office365.com`, port 587, STARTTLS); - **Google Workspace** (`smtp.gmail.com`, port 587, STARTTLS); - **Other mail server:** its name, the port and STARTTLS (usually 587) or SSL (465). Lumate never sends without encryption. 2. Choose how Lumate signs in: - **Password:** the mailbox's sign-in name and password. For Google Workspace use an **app password** (Google account → Security → 2-Step Verification → App passwords), not the account's own password. - **Microsoft 365 sign-in (recommended for Microsoft 365):** Microsoft turns off password sign-in for sending (SMTP basic authentication) by default from the end of December 2026. Your Microsoft 365 admin: 1. registers an app in Microsoft Entra ID and creates a client secret; 2. gives it the **SMTP.SendAsApp** permission (Office 365 Exchange Online) and grants admin consent; 3. registers its service principal in Exchange Online and allows it the mailbox (`New-ServicePrincipal`, then `Add-MailboxPermission … -AccessRights FullAccess`); 4. makes sure SMTP AUTH is on for that mailbox. Then enter the **tenant** (its id or domain, like `contoso.onmicrosoft.com`), the **Application (client) ID**, the **client secret** and, if it is not the From address, the **mailbox it sends as**. 3. **Sender:** the From address and name, and optionally where replies go. 4. **Limits:** most per hour (default 100, at most 1,000) and per day (default 1,000, at most 10,000). Over a limit, email waits for the next hour or day; it is never dropped. 5. **Save**, then **Send a test** (to the address you type, or your own confirmed email). The password and the client secret are encrypted and never shown again, only their last characters. Agents never see them. Leave the field empty to keep the saved one. The top of the page shows how many emails wait, when the last one went, and the last problem in plain words (for example "The mail server refused the sign-in (535)"). The switch turns sending off without losing the settings. On the server edition, Lumate sends only through public mail servers. Lumate Local can also use a relay on the office network. ### How sending works - Email goes out within about 20 seconds: Lumate's own links first (confirming an email, a new password, invites), then the rest oldest first. A tenth of the hourly limit (at least one) stays free for those links, so notifications and automations never hold a password link back. - A message that fails is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours; then it shows as **Not sent** with the reason. An address the server refuses fails at once. - If Lumate stops, or the connection breaks, in the middle of sending a message, that message is marked **Not sent**, never sent twice: check before sending it again. The ones not tried yet simply wait for the next round. - If the mail server or Microsoft refuses the sign-in, nothing is tried for 1 minute, then 5 minutes, and so on, and no message loses a try for it. Other troubles (a name that does not answer, Microsoft's sign-in unreachable) spend a try as a refused connection does. - Each round starts with the company whose mail has waited longest, and a name lookup or connection never takes more than the round has left. - With an hourly limit of 1 nothing is kept back for links. - Lumate's own messages (links) are not kept once they went or failed. Finished mail is deleted after 90 days. - While Lumate is not activated (Settings → Licence), only its own links go (confirming an email, a new password, invites, tests); the rest waits. ## Your email (Settings → Your account) Type your address and press **Send link**. The address becomes yours when you open the link within 24 hours and press **Confirm my email** (one press, because some mail systems open links on their own). Until then nobody, you included, gets anything there. An address can belong to one account only (in any mix of capitals); an address that belongs to another account gets no link, and the page says the same either way. Links for your account (confirming it, setting a new password) go only through the mailbox of the company that set up Lumate (the first company), never through another company's mail server, whose admin could read them. If that company has no email set up, the page says so. **Notifications by email:** - **None.** - **Important** (the default): hand-offs, appointments, call backs, a blocked office browser, and OXS's maintenance and security notices. - **All:** everything that reaches your Inbox. When a notification holds words someone outside chose (a caller's message, for example), the email carries Lumate's own summary instead, as on WhatsApp. ## Forgot password? On the sign-in page, **Forgot password?** asks for your username or email. If it matches an account with a confirmed email, and the company that set up Lumate has email set up, a link to set a new password goes there. It works once, within 30 minutes; other sessions are signed out. The page says the same whatever matched. At most 5 links an hour per person. Without a confirmed email, the person who runs the server sets a new password for you there (see [Operations](/docs/operations#command-line)). When the first company's set-up was handed to a manager (2.16.0), its mailbox is theirs and keeps what it sends: only that company's own people get reset and confirm links through it. The person who installed Lumate resets theirs on the server (`python -m app.cli reset-password`, see [Operations](/docs/operations#command-line)); people of the server's other companies ask them for a new password the same way. ## Inviting by email In Settings → Members, **Email it to** sends the invite link through the company's email. You can still copy the link. ## Email to contacts Each card has an **Email** section (the card needs an email address): - **The agent's draft:** agents write emails with `draft_email`. Edit the subject and text if you like, then **Send**, or **Discard**. A new draft replaces the waiting one. The draft goes to the address on the card when you send it. - **Write an email:** a person writes and sends one, with files on the card or its thread. - What was sent, what waits and what failed, with the reason. - **No emails:** the contact gets nothing more; waiting emails and drafts are cancelled. Use it when someone replies "stop": every email to a contact ends with "To stop these emails, reply to this email and ask us to stop.", and replies reach your mailbox (Lumate does not read them). An agent sends on its own (`send_email`) only when the manager asked in a message that names the contact, or on the card's own thread, never to an address an agent wrote on the card (a person sends that one from the card), and a retried request in the same run sends once. It can attach up to 3 files (10 MB together) from its thread or the card's thread. The card's History notes each email by its subject. ## Apps An app's automation can send an email: to the people with chosen roles (their confirmed emails), or to a record's email field. The subject and text fill `{{field}}` from the record; sensitive fields stay empty. A record's address that a contact card marks **No emails** gets nothing. --- # Office browser Source: /docs/office-browser Agents can use a real Chrome browser on an office PC: they read property portals, look things up, and, on sites you allow, work in your CRM the way a person would. What they find on portals is saved as **listings** and matched to customers. ## How it works ![Diagram: How it works](/docs-diagrams/f91f10e7ee49a2b1.png) - **The extension** runs in a Chrome profile on an always-on office PC. It connects out to the server, so there is no port to open on the PC. - **Each agent run gets its own tab.** The tab is closed when the run ends. Your own tabs are never touched. - **The rules are enforced inside the extension,** where agents cannot change them: pace, read-only sites, no secrets. - **Logins stay on the PC.** If a site needs a login, a person signs in once in that Chrome profile; agents then use the session. Agents never type passwords. ## Installing 1. **Settings → Browser → Download the extension.** The package contains a one-time pairing code, valid for 30 minutes. A new download makes older packages unusable. 2. On the office PC (Chrome 116 or newer), ideally in a **separate Chrome profile** used only for Lumate: 1. unzip the package; 2. open `chrome://extensions` and turn on **Developer mode**; 3. click **Load unpacked** and choose the unzipped folder. 3. The extension pairs on its own. Settings → Browser shows **Online**, with the PC's name. 4. Keep the PC on, with Chrome open. The extension reconnects by itself after sleep or a network drop. When the PC is idle, Chrome may put the extension to sleep; it wakes every 30 seconds and reconnects. **To update the extension:** download a new package, remove the old extension in `chrome://extensions`, and load the new one. **On a linked PC** (from 2.15.0): when the office PC runs Lumate connected to this server and is linked (Settings → **Linked PCs**), there is no package to download: 1. Settings → Browser → **On a linked PC**: choose the PC and press **Use this PC**. 2. The PC writes the extension into Lumate's data on that PC (`%LOCALAPPDATA%\AgentX\data\extension`) with a one-time pairing code, and opens the office browser's Chrome profile. 3. The first time only, someone at that PC loads it (Chrome does not let any program do this): Lumate opens its **Server connection** page there, which shows the folder. In Chrome (ideally a profile only for Lumate) open `chrome://extensions`, turn on **Developer mode**, choose **Load unpacked** and pick that folder. From then on the extension updates with Lumate on that PC and pairs again by itself: when it stays offline for 10 minutes while its PC is online, the server sends a fresh code. After the PC restarts, Lumate opens the office browser again by itself. Unlinking the PC (Settings → Linked PCs) takes the office browser off it. **On Lumate Local** there is no package to download and nothing to update by hand: **Prepare the extension** puts the extension in a folder of Lumate's data (`data\extension`), and you load that folder once. Every update of Lumate updates the extension in that folder, and the extension reloads itself. Lumate keeps a fresh pairing code there, so the extension reconnects by itself after a restart or an update, and **Reconnect** pairs it again without loading anything. Never load a folder under `app\\`: it cannot connect. See [Lumate Local](/docs/install-windows#the-office-browser). ## What agents may do | Where | Agents may | |---|---| | **Any website** | Open pages, read them, scroll, follow links, search, use filters, sort, change pages | | **Allowed sites** (Settings → Browser → Allowed sites) | Everything a person does in a form: fill in fields, choose options, press Save, Send or Submit | | **Nowhere** | Type into password, payment or file fields; upload files; open `file://`, `chrome://` or other non-web pages; open the office network (localhost, 192.168.x.x, 10.x.x.x, `.local`), unless that host is an allowed site | **On sites that are not allowed** (read-only), the extension refuses: - typing into personal-data fields (name, email, phone, message); - any button that sends, books, saves, posts, registers or signs in; - any form that sends data. Searching and filtering still work. **Allowed sites:** - one host per line, for example `yourcompany.bitrix24.com`; - a host also covers its subdomains; - at most 50. Every change an agent makes on an allowed site is recorded in the Activity log, with the page and the field. **On LinkedIn** a person approves every change, even where it is allowed ([LinkedIn](/docs/office-browser#linkedin), below). ## Pace So that portals see a person's pace and not a robot: - 2–5 seconds between page loads in a tab; - at most 12 page loads a minute on one site. If a site's limit is reached, the agent is told to slow down. A command times out after 45 seconds. ## LinkedIn LinkedIn's User Agreement (section 8.2) does not allow bots or scraping, and LinkedIn can restrict an account that looks automated. These rules are fixed, out of the agents' reach: - **A person's pace:** a page every 10 seconds at most (across all tabs), 40 an hour and 150 a day, however its address is written (`linkedin.com.`, `lnkd.in` links). A page opened there, and an approved click or Enter there, is counted before it runs (once, with the page it opens; an action the page refused before acting is not counted). A page reached another way (a short link, a redirect, going back) is counted when it has arrived, even past the limit: it was loaded, so the tab leaves it at once, and nothing more loads from where the link was (the short link's site, or the page it was on) until LinkedIn has room again; the agent is told which. While LinkedIn is at its limit, pages load one at a time, and an agent's commands always run one after another. Back from a page the tab left is refused (it would load that page again). The extension keeps the counts and what waits, through a restart too, and stops at LinkedIn while a count cannot be read or kept (one that could not be kept is lost only if the browser restarts before it can be). - **Every change is approved:** a click, typing or a choice there first becomes a card in the agent's thread and in the Inbox (counted on its badge), with the words it would type, and whether typing also presses Enter (in a message box that sends it). An admin approves or declines it, and the agent is told: its next run in that conversation goes on in the same tab, on the same page. An approved change runs once, within half an hour, in the same conversation, on the page it was asked on and only on an element named as the approved one: the browser checks both before it acts. Agents can ask for changes only when LinkedIn is among the allowed sites, and only on a page they have read. - **Security checks stop the agents:** LinkedIn's own security check (its checkpoint page, a CAPTCHA's challenge, or its page titled "Security Verification | LinkedIn", unless it is a member's, an organisation's or a product's own page named so) stops every agent at LinkedIn for a day, wherever a link lands and however the address is written, and the admins are told. What a page says (a profile, a search, a job, even in its title) never does, and other sites are never stopped this way. Nothing ever types into one. Open LinkedIn in the office browser and deal with it, then let the agents go on in **Settings → Browser → Stopped sites**. Agents open LinkedIn's search and profiles by their address, so reading needs no approval. ## Pause and disconnect - **Pause agents** (Settings → Browser): agents get "the office browser is paused" until you resume. Use this while you use that Chrome profile yourself. - **Disconnect:** removes the browser's access. Agents lose it until you install a new package (on Lumate Local: until you press **Reconnect**). - **Per agent:** only agents with **Can use the office browser** (agent → Settings) can use it. In the real-estate template, Lumate and the Researcher have it. ## The agents' browser tools | Tool | What it does | |---|---| | `browser_status` | Whether the browser is online or paused, and the allowed sites | | `browser_open(url)` | Opens a page in the run's tab; returns its text and numbered elements | | `browser_read` | Reads the current page again | | `browser_click(n)` | Clicks element n | | `browser_type(n, text, submit?)` | Types into field n, optionally pressing Enter | | `browser_select(n, option)` | Chooses an option in a list | | `browser_scroll` | The next or previous part of a long page | | `browser_back` | Back one page | | `save_listing`, `match_listing`, `find_listings`, `mark_listing_gone` | The listings tools, below | Pages come back as **outside data**. Text on a page cannot give an agent instructions. ## Listings When an agent finds a property on a portal, it saves it with `save_listing`. Each link is saved once: - **Seeing it again** updates the listing and keeps its price history. - **A listing that disappears** from the portal is marked "no longer listed" by the agent that finds it gone (`mark_listing_gone`). - **Brokers' phone numbers** never enter a listing's own text: they are replaced with "[number removed]" in its title, summary, agency, building and area. Only an outreach (Outside brokers, in the user guide) reads a listing broker's number, from a phone or WhatsApp link on the page or by pressing the portal's "Show number" button, and keeps it on an outside-broker card. That button is the one thing Lumate may press on Property Finder, Bayut and Dubizzle; it never fills in their contact forms. | Field | Example | |---|---| | Title, link, portal | "3BR Marina Gate 1", the portal's page, Bayut | | Sale or rent, type | sale · apartment (also villa, townhouse, penthouse, plot, office, other) | | Price (AED), beds, baths, size (sq ft) | 2,450,000 · 3 · 4 · 1,820 | | Area, building, completion, agency | Dubai Marina · Marina Gate 1 · ready · the listing agency | | Summary | A short description in the agent's words | **Matching:** `match_listing` suggests a listing for a customer, with why it fits ("3 beds in the Marina, under the 2.5M budget"). On the customer's card, a person marks each suggestion: - **Sent to the customer**, or - **Not interested**. The board shows 🏠 with the number of active suggestions. **On calls:** voice agents use `search_listings` when a customer asks what is available or what things cost. It searches the saved listings, then Property Finder, live, in the call's own tab of the office browser (when the agent may use the browser). The call gets only prices, sizes, beds and short lines from the page, never brokers' names or numbers, and gives a rounded asking-price range. At most 10 searches a call, 3 of them live; the tab closes when the call ends. **Finding them again:** `find_listings` lets agents search what the team already saved before they search the portals again. People use the **Listings** page, see the [user guide](/docs/customers#listings). **The "Finding listings" skill** (real-estate catalog) teaches agents to: 1. read the customer's needs; 2. search the portals in the browser; 3. save each fitting listing; 4. match the best ones, with reasons; 5. report back. ## Example > **You (chat with the Researcher):** Find 3-bed apartments for sale in Dubai Marina under 2.5M for @Sara Ahmed. > > **Researcher:** opens a portal's search, sets the filters, reads the results, saves 6 listings, matches the 3 best to Sara, and replies with a short table and the links. Sara's card now shows 🏠 3. The listings are on the Listings page with "Sara Ahmed" in the Customers column. ## Calls through WhatsApp Web When the office line is off (Settings → Desk phone), Lumate can call through WhatsApp Web in the office browser instead: customers from call lists, Call now and the dialer, and outside brokers after an admin approves the call. The same rules apply as on the office line: the reason the person may be called, the DNCR check and the calling hours. **Setting it up** 1. **Settings → Browser → Link WhatsApp Web** (admins). WhatsApp Web opens in the agents' window of the office browser. Scan its QR code with the company phone: WhatsApp → **Linked devices** → **Link a device**. 2. Settings → Browser then says **Linked · calls available**. 3. **Settings → Call center → Call through WhatsApp Web when the office line is off** is on by default. Once linked, Lumate's WhatsApp window comes back by itself when Chrome or Lumate restarts, and after an update. If no call can go out, Start, Call now and the queue say why: no office line, and what stops WhatsApp Web (the office browser offline or paused, WhatsApp Web not linked, the switch off). **How a call goes** - Lumate's own window opens the number's chat and presses WhatsApp's call button. The agent's voice is WhatsApp's microphone, and the person's voice goes to the agent. Nobody needs to be at the PC. Lumate lets WhatsApp Web use the microphone in the office browser by itself (WhatsApp mutes a call it has no microphone permission for); do not block the microphone for web.whatsapp.com there. If the office browser is unpaired, that setting goes back to Chrome's own. - The agent speaks once the person answers. Lumate follows WhatsApp's own record of the call: ringing, answered, ended. - **One call at a time.** The next call starts when this one ends. - A number WhatsApp cannot reach (no ringing within 30 seconds) is marked: its call waits for the office line, and the queue says why. A number that rang but nobody answered is called again later, as on the office line. - **Call center → Live** shows the call. **Listen** works. **Hand over** and **Take over now** ask the person at the office PC: Lumate's window comes to the front with **Take the call**, and the agent stays on until someone there presses it (the office PC needs a microphone). Someone at the PC can also use the panel in WhatsApp Web: Hand over, Take over now, End call. **Calls that ring on the linked number** (2.2.0, off until Settings → Call center → Incoming calls → Lumate answers calls that ring on WhatsApp is on): the page in Lumate's WhatsApp window sees a voice call ring and tells Lumate who calls, as WhatsApp shows them. A saved contact rings the owner and admins in Lumate first; otherwise, or after Not now, Lumate accepts the call in that same page (it never reloads it) and answers. Take over accepts it with the PC's own microphone. Group and video calls, and a second call while one is on, keep ringing on the phone. See [Calls that ring on your WhatsApp](/docs/calls#calls-that-ring-on-your-whatsapp). - The office PC's speakers may play the person's side of the call. Keep the volume down, or use headphones there. - A call ends after 20 minutes at most. If Lumate's window is closed, or the office browser loses its connection to Lumate, its call ends. - **Pause agents** (Settings → Browser, or the extension's switch) also stops new WhatsApp Web calls. A call already on carries on. - Nothing calls through WhatsApp Web until an admin links it with **Link WhatsApp Web**. **Agents and WhatsApp Web.** Agents never open WhatsApp Web, even if it is an allowed site: Personal chats live there. Only Lumate's call routine uses it, and only to call. **Limits** - WhatsApp calls do not connect in the UAE. Use it for numbers abroad, or keep the office line. - WhatsApp may change its page. Lumate finds the call button by its icon, by its place beside the video call button, or by its label. If none is found, or pressing it starts no call, the call fails with a reason that lists what the chat's top bar showed, and the card stays as it was (the number is not marked unreachable). - WhatsApp turns WhatsApp Web calls on account by account. An account without them shows "Linked · this account cannot call from the browser yet", and Start says "WhatsApp has not turned on calls in WhatsApp Web for this WhatsApp account yet". A browser WhatsApp Web cannot call from shows "this browser cannot make WhatsApp calls": update Chrome or Edge. - Just after linking, WhatsApp Web downloads the messages first. A call waits up to a minute for that. An attempt that never rang does not use up the number's calls for the day. --- # Everyday running Source: /docs/operations ## Everyday checks | Check | Where | |---|---| | The server is up | `curl -s https://agentx.yourcompany.com/health` → `{"status":"ok"}` | | The runner is online | Settings → Runners (green); the sidebar shows a banner when no runner checked in for a minute | | WhatsApp is connected | Settings → WhatsApp | | The office browser is online | Settings → Browser | | Failed runs | Inbox → Problems; Dashboard → failures | | What happened | Activity (everything people and agents did) | ## Logs - **The server edition:** `sudo agentx logs server` (or `runner`, `whatsapp`, `caddy`, `updater`). `sudo agentx support-bundle` gathers versions, settings without secrets and log lines for OXS support, never data. - **Lumate Local:** the logs folder, see [Lumate Local](/docs/install-windows#logs). | Service | What its log holds | |---|---| | `server` | API, scheduler, phone webhooks, browser relay | | `runner` | Claimed runs, Claude Code output summaries | | `whatsapp` | Connection state; never message texts or full numbers | An agent's full run, with every tool call and result, is on the agent's **Runs** tab, or from the run pill in a thread. Each service keeps at most 30 MB of log (three files of 10 MB; the oldest goes first), so logs never fill the disk. The server logs what happens, not every request: the runner's and the open pages' frequent checks leave no lines. **Memory.** The server edition bounds each service: the server 2 GB, the runner 2 GB, WhatsApp 512 MB, Caddy 256 MB and the updater 512 MB, so one runaway process cannot take the machine. With more than two runs at once (`RUNNER_SLOTS`), give the runner more (`RUNNER_MEMORY=4g`; `SERVER_MEMORY` for the server) in `/opt/agentx/.env`, then `sudo docker compose --project-directory /opt/agentx -f /opt/agentx/compose.yml up -d runner`. ## Backups **The server edition** backs itself up: every day, before every update and when asked (Settings → Backups, or `agentx backup`), with a copy to a bucket if you want one, and `agentx restore` puts a backup back. See [The server edition](/docs/install-server#backups). A backup needs as much free disk space as the data, plus 512 MB: with less, it is refused before anything is written (and an update waits, changing nothing), so a backup never fills the disk. **Lumate Local** keeps daily backups by itself, see [Lumate Local](/docs/install-windows#updates-and-backups). ## Updating **The server edition** updates itself from its channel (Settings → Updates: automatic installs in the maintenance window, or Update now), backs up first and goes back by itself when the new version does not start. From the shell: `agentx update`, `agentx update --bundle `, `agentx rollback`. See [The server edition](/docs/install-server#updates). **Lumate Local** updates itself too, see [Lumate Local](/docs/install-windows#updates-and-backups). ## Troubleshooting ### Sign-in and setup | Symptom | Cause and fix | |---|---| | "Too many attempts" | 5 tries a minute per address. Wait a minute. Behind a proxy, set `TRUSTED_PROXIES`, or everyone shares one limit. | | Signed out right after login | `COOKIE_SECURE=true` over plain HTTP. Use HTTPS, or `false` only for local trials. | | Lost the setup token | The server edition: `sudo grep SETUP_TOKEN /opt/agentx/.env` | | Forgot a password | **Forgot password?** on the sign-in page, once [email](/docs/email) is set up; otherwise the [command line](/docs/operations#command-line) | ### Licence | Symptom | Cause and fix | |---|---| | "Lumate is not activated yet" | A fresh install: the person who set it up activates it in Settings → Licence (or the setup's Activate step). See [Licensing](/docs/licensing). | | "The 30 days to activate Lumate have ended" | An install from before licensing that was not activated in time: activate it; nothing was lost. | | "Lumate's licence has ended" | The subscription stopped, or no check-in reached OXS Cloud for 14 days. Renew in the portal, then **Check again** on the lock page. Export all data works meanwhile. | | "This computer's clock is behind" | Set the right date and time; the next check-in (within 5 minutes) unlocks Lumate. | | "Lumate could not reach OXS Cloud for N days" | The server cannot reach OXS Cloud over HTTPS (firewall, proxy, TLS inspection). The licence keeps working until its last day; fix the connection, then Settings → Licence → Check now. | | "This install's licence is in use on another machine" | A copy of this install (a restored database) runs elsewhere. Deactivate the one you do not want; activate this one with a free slot. | ### Agents | Symptom | Cause and fix | |---|---| | Agents never answer; "No runner online" | Settings → Runners shows whether the runner is online and its Claude Code signed in. The server edition: `sudo agentx status` and `sudo agentx logs runner`. | | A run failed with a Claude login error | The Claude sign-in expired or was revoked. Sign in again: `sudo agentx claude-login` on the server edition, a new key or token in Settings → Runners, or Settings → General → Claude on Lumate Local. | | A run failed with a usage limit | The company's Claude plan hit its limit. Wait for the reset, or raise the plan. | | An agent stays "Working…" | The run's lease expires within 2 minutes and the run is queued again. If it repeats, check the runner log. | | An agent ignores a file | Files over 25 MB, or of an unsupported type, are refused at upload. Office files are read through their extracted text. | ### Voice and phone | Symptom | Cause and fix | |---|---| | The microphone does nothing | The browser needs HTTPS and microphone permission. Check that `OPENAI_API_KEY` is saved. | | Inbound calls are not answered | Check the webhook URL in OpenAI, `OPENAI_WEBHOOK_SECRET`, that the server's public address is reachable over HTTPS, and that the number is added with an agent. | | "Outbound calling is off" | An admin enables it in Settings → Phone with the trunk. | | A call is refused by the gate | The reason says which rule applies: calling hours, do-not-call, consent, attempt limits. | | One-way or no audio through Asterisk | RTP ports and `external_media_address`, see [Phone and Asterisk](/docs/phone#checking-it) | ### WhatsApp | Symptom | Cause and fix | |---|---| | "WhatsApp is not running on this server" | The server edition: `sudo agentx status` shows the `whatsapp` service; `sudo agentx logs whatsapp` says why it stopped. | | Logged out | The phone removed the linked device, or it was offline for about two weeks. Link again. | | Replaced | The number was linked from another place. Link again here, only once. | | A message shows "waiting (limit)" | The pace limits hold it. It goes out by itself. | ### Office browser | Symptom | Cause and fix | |---|---| | "This package was already used or is older than 30 minutes" | Download a new package | | Offline | The PC sleeps, Chrome is closed, or the extension was removed. Keep Chrome open; the extension reconnects by itself. | | Switches between Online and Offline while nobody uses the PC | Chrome puts an idle extension to sleep. The extension wakes every 30 seconds and reconnects; a command sent in that moment fails and the agent tries again. Turn off the PC's sleep. If it stays offline for about 30 seconds of every minute, it is an older extension that woke only once a minute: download it again from Settings → Browser. | | "This site is read-only for agents" | The site is not on the allowed list. Add it in Settings → Browser if agents should work there. | | "Slow down: this site's page limit was reached" | 12 page loads a minute per site. The agent waits and continues. | | The agent cannot log in to a site | By design: a person signs in once in that Chrome profile. | ## Command line On the server edition, run these in `/opt/agentx` with `sudo`: ```bash docker compose exec server python -m app.cli create-user [--admin] docker compose exec server python -m app.cli reset-password docker compose exec server python -m app.cli create-runner-key ``` `reset-password` sets a new password and prints it once: sign in with it, then choose your own in Settings → Your account. Every other session of that person ends. It is also how an address gets back to its owner when an account was made for it by someone else: reset it, give the password to the real person, and they choose their own. --- # Security and compliance Source: /docs/security ## Who can do what | Role | Can | |---|---| | **Instance admin** | Open every company on the server, create companies | | **Owner / Admin** | Everything in their company: members and roles, settings, secrets, phone numbers and outbound calling, WhatsApp linking, the office browser and its allowed sites, agent permissions, approving new agents, endpoints and API requests | | **Member** | Daily work: chats, tasks, customers, appointments, WhatsApp messages, listings, the Playground | | **Agent** | Only its tools, only inside its company, only with the permissions an admin gave it | Companies are isolated: - every request is checked against the company's membership; - a runner key belongs to one company; - a run's token works only for that run and only while it runs. ## Accounts and sessions - **Sign-in:** with your email (from 2.16.0; accounts made before keep their username). An email someone only typed never signs anyone in: a proven email (confirmed by its link) or the email an account was made with. - **Passwords:** - at least 10 characters for a new one (from 2.16.0; older passwords keep working); - stored as bcrypt hashes; - reset with **Forgot password?** on the sign-in page (once [email](/docs/email) is set up), or from the command line (see [Operations](/docs/operations#command-line)). - **Login attempts:** at most 5 a minute per address. Set `TRUSTED_PROXIES` so the limit sees real addresses behind your proxy. - **Sessions:** - last 7 days; - signed with `SESSION_SECRET`; - sent only over HTTPS (`COOKIE_SECURE=true`); - tied to the password, so changing it signs out other sessions. - **The setup token** works only until the first account exists; the installer's link carries it after a `#`, so no server log keeps it. Invite links are for one email, expire after 7 days and work once; the company set-up link likewise, and it lets its manager make one company. ## Secrets - **Storage:** company secrets (the OpenAI key, the webhook secret, the SIP trunk password, API tokens) are encrypted with `SECRETS_KEY`. - **Write-only:** after saving, the page shows only a short hint, never the value. - **Agents never see secret values:** - The server uses them itself, for voice, phone calls and the outbound trunk. - An admin can bind a secret to the agents whose server-side tools may use it. - With **API requests**, the server adds the secret to a request and sends it only to the **hosts** an admin allowed for that secret. - Changes to outside systems wait for an admin's approval in the Inbox. - **Logging:** every use of a secret is logged. - **Secrets waiting for a value:** a secret can arrive by name only, from a team package. Values never travel in packages. - It keeps its description, its allowed hosts and the agents that may use it, and shows **Value needed** in Settings → Secrets. - Admins get one Inbox item listing these secrets. - Until an admin enters the value, an agent that tries to use it gets a clear "has no value yet" answer, and voice says the OpenAI key is missing. - **Pairing and browser tokens** are stored only as hashes. - **The Claude login token** lives only in the runner's environment. ## Outside data Everything that comes from outside the team is shown to agents as **information, never instructions**: - caller speech and transcripts; - WhatsApp messages; - web pages from the office browser; - CSV imports; - integration endpoint calls; - customer notes. The agents' instructions say so, and the tools label it. A page or a message that says "ignore your rules and…" is just text to them. ## What agents cannot do - **No computer access:** no shell, no file system access beyond the files shared with the run, and no web access other than the office browser. - **No new teammates on their own:** they cannot create agents (a proposal waits for an admin). - **No settings changes:** they cannot change settings, secrets or permissions. - **No customer messages on their own:** they cannot message a customer without a person, except when a manager asked them to in that conversation. - **No secret fields:** they cannot type passwords, payment details or files in the browser, or open the office network. - **No changes on read-only sites:** they cannot change anything on sites that are not on the allowed list. ## Calling rules by country A company's country (Settings → Departments) sets the rules its calls follow; its departments do not change them. | | United Arab Emirates | Türkiye | Another country | |---|---|---|---| | Local numbers | +971 | +90 | The company's own code (Settings → Phone) | | Do-not-call register | Each number is checked against the DNCR, recently | | | | Recording notice (the default) | "Just so you know, this call is recorded for quality purposes." | "Bilginize: ben bir yapay zekâ asistanıyım ve bu görüşme kalite amacıyla kaydediliyor." | "Just so you know, I'm an AI assistant, and this call is recorded for quality purposes." | | An admin confirms before AI calls | A recorded basis; the DNCR check; calling hours and limits; the notice, and the agent never denies being an AI | A recorded basis; İYS consent for commercial calls and messages; calling hours and limits; the notice says an AI is speaking; KVKK | A recorded basis; calling hours and limits; the notice says an AI is speaking; the country's rules checked with a lawyer | | Calling hours | 9:00–18:00; wider only with legal sign-off | As the lawyer approved for Türkiye | As the lawyer approved | | WhatsApp calls | Do not connect in the UAE | | | The rules below are the UAE's. ## Calls (UAE and KSA) | Rule | How Lumate applies it | |---|---| | Recording notice | Every call opens with the company's notice (Settings → Phone). Default: "Just so you know, this call is recorded for quality purposes." | | Honesty about AI | Agents never claim to be human. When asked, they say they are the company's AI assistant. | | Do-not-call | "Don't call me" moves the card to Declined, marks it do-not-call and adds the number to the company's list. Cards marked do-not-call cannot be called or moved back to To call by agents. Managers are notified. | | Consent | Outbound calls need a basis: the customer asked for a callback, or is an existing client. A short note is required. | | DNCR | The caller confirms the number was checked against the Do Not Call Registry that day. | | Calling hours | 09:00–18:00 in the company's time zone by default (Settings → Phone) | | Attempt limits | By default, 1 call a day and 2 a week per number. After 2 unanswered calls, the card goes to the manager. | | Outbound switch | Off until an admin enables it with the company's own trunk | | Call center dialer | Off until an admin switches it on and confirms the rules above; who confirmed and when is recorded. It calls only cards whose basis a person recorded ("May we call?" on the card), with a DNCR check no older than the admin's setting (7 days by default), inside the calling days and hours and under the caps. Cards with a broker are not called. The same gate applies to "Call now". | | Hand-over to a broker | The AI says it is connecting the customer to a colleague, then the PBX transfers the call to the broker's extension. The broker sees the AI's summary and the call so far. | There is no "cold call" basis in Lumate. One would be added only after a lawyer's written sign-off. **Before outbound calling starts,** a lawyer must sign off on the call scripts, cold-calling rules, recording and monitoring disclosure, and marketing messages, in the UAE (TDRA, DLD rules for brokers) and KSA. Lumate's defaults are conservative, but they are not legal advice. ## WhatsApp - **The session** is encrypted with `WHATSAPP_STATE_KEY`, and message texts never appear in logs. - **Messages go out** only when a person sends them, or when a manager asked an agent to. - **Pace limits** protect the number: 30 an hour, 200 a day, 15 per customer a day. - **Voice notes** (from 2.14.0) go to OpenAI only to be written out, on the company's own key; a Personal chat's never do, the audio is deleted afterwards, and Settings → WhatsApp → **Write out voice notes** switches it off. ## LinkedIn LinkedIn's User Agreement (section 8.2) does not allow bots or scraping. Agents go at a person's pace there (a page every 10 seconds at most, 40 an hour, 150 a day), a person approves every click, typing or choice (for that page, that conversation and that element only), and LinkedIn's own security check stops every agent there for a day. See [Office browser](/docs/office-browser#linkedin). ## Search The search index lives in Lumate's own database, and meaning search runs on the machine (intfloat/multilingual-e5-small, MIT licence, fetched once from huggingface.co at a pinned revision and checked by SHA-256): no text is sent anywhere for search. Fields marked sensitive, and formulas that read them, are never written into the index. Access is checked on every search from the same rules the pages use. ## Claude Code updates Runners install a Claude Code release only when its manifest is signed by Anthropic's release key (pinned in the code by fingerprint) and the binary matches the manifest's SHA-256 and size. The copy installed with Lumate stays as a floor; a version whose first runs fail is left for the one before. ## OXS Cloud and the licence Lumate runs with a licence from OXS and checks in with OXS Cloud every 12 hours. A check-in carries counts and codes only (its version, edition, how many companies, people, agents, calls and messages, the database's size, how updates went) and never anything a company keeps: no names, numbers, messages, transcripts, files or prompts. The exact fields are in [Licensing](/docs/licensing#what-we-send), and Settings → Licence shows the last check-in as it was sent. An ended licence never deletes or holds back data: Export all data works in every state. ## Linked PCs From 2.15.0, an office PC running Lumate in connect mode can be linked to a company on the server edition: - **Who links:** only an owner or admin of the company, by approving the code the PC shows (10 minutes). The approval shows the address the request came from: approve only a PC in front of you that shows the code, never a code someone sends you or reads to you on the phone. Codes, the PC's poll secret and its token are kept as hashes; the token is kept on the PC in Windows' vault (DPAPI). Settings → Linked PCs lists the PCs; **Unlink** (there, or on the PC) ends the PC's token and closes its connection at once, and the PC lets go of the desk phone line. - **What the PC obeys:** SIP addresses and numbers from the server are refused when they hold spaces or control characters, so nothing the server sends can add to what the PC sends the PBX. A PC whose link is gone for a minute lets go of the PBX until the server sets the line up again. - **What the PC receives:** the commands for the office browser's pairing (a one-time code) and for the desk phone line, including that line's SIP password, kept in the PC's memory only while the line runs. It never receives the OpenAI key, agents' instructions, tools, customers or messages: the voice session and the agents' work stay on the server. - **Where the PC connects:** only to the one server address saved in its app (https with a publicly trusted certificate). A pairing for any other address is ignored. - **The connection:** outgoing from the PC (a WebSocket over HTTPS); no port is opened in the office. The calls' audio goes over it encrypted; on the office network, between the PC and the PBX, it is as on any desk phone (not encrypted). ## Diagnostics (from 2.16.0) - **Kept on the install:** every error Lumate logs is counted by its kind (the exception's class) and its place in the code (module, function, line), per day, for a week. Neither the log line's text nor the error's own words are kept: either can carry a name, a number or a message's words. - **Sent to OXS only on a click:** an instance admin (Server page) or a company's owner or admin (Settings → Status) presses **Send diagnostics to OXS** after seeing the preview, and exactly what the preview showed goes. It carries the version, the system, each part's state (companies by number), those error counts and the admin's own note. Both sides check each field's shape (a state's words carry no address or line break; a place in the code is module:function:line), and OXS Cloud refuses anything outside that list, at most 64 KB and ten a day per install. OXS support staff open one in the console, and each opening is in OXS's audit log; read ones are deleted after 90 days, any after 180. A support inbox, when OXS has one, hears that diagnostics came, never what they say. - **Without OXS:** **Download file** gives the same content to send any other way. ## The person who installs Lumate (from 2.16.0) On a server, the first account runs the server. When they hand the company's set-up to a manager ("Someone else"), they are not a member of that company and Lumate does not let them in as the instance admin: they see its name only. Their place is the Server page (status, diagnostics, updates, backups, the licence). They still hold the server itself, and with it its backups and its data on disk: choose who installs accordingly. A handed-over first company's mailbox is the manager's, so the installer's own password reset never goes through it: they reset it on the server. ## Data - **Location:** everything is in the server's data volume, plus the WhatsApp worker's volume. The office browser's logins stay on the office PC. - **Activity log:** every change by people and agents is in it. - **Cards are kept until a person deletes one.** Agents move cards to Done or Declined and never delete one. An owner or an admin deletes a card from the card, with what Lumate keeps about the person: its history, its thread and the tasks under it with their documents, appointments and call list places, the calls with them (their transcripts), their WhatsApp messages, the notices about them and their WhatsApp copies, the LinkedIn changes asked about them, what outside systems (a CRM) sent about them, the lessons drawn from their calls and the files on the card. The activity log keeps that things happened, without the details that named them. Other tasks and chats that mention the person stay (with the agents' records of their work there), and so do what agents remembered and a file another card or task also holds. A number that asked not to be called stays on the do-not-call list. The sample customers are removed together (Customers → ⋯). - **Retention (Recruiting):** on the first of each month Lumate lists the rejected candidates with nothing new for 12 months, for a person to delete (see [Recruiting](/docs/recruiting#how-long-candidates-are-kept)). - **Backups:** see [Operations](/docs/operations#backups). A backup includes customer data, so store it encrypted.