Developer guide

Introduction

Put your AI agents on any website, let Claude manage your workspaces by chat, and understand how the platform fits together. Everything here works with your LuxeBot account.

Before you start

  • You need a workspace with at least one agent. Create agents under Agents in the dashboard.
  • Your role in a workspace decides what you can do there, in the dashboard and through Claude. See Roles and permissions.
  • IDs (agency, workspace, agent) identify things and are safe to share. Tokens are secrets. See Find your IDs.

What is not available yet

There is no public REST API with API keys yet. To work with your data from outside the dashboard, use the MCP server with Claude.

Developer guide

Platform concepts

Everything you build lives in a workspace, and every workspace belongs to an agency.

ThingWhat it is
AgencyYour company account. Owners and admins manage its team, workspaces, white label and billing.
WorkspaceOne business or client. Agents, numbers, contacts and campaigns belong to a workspace.
Voice agentAn AI agent that answers or makes phone calls. New agents start as drafts until published.
Chat and web agentsText agents for SMS and for the Web Agent on your website.
Visual FlowAutomations that run on triggers, for example when a call ends. Flows start switched off.
Phone numbersNumbers in the workspace and which agents answer them.
Working hoursSchedules agents follow for availability and transfers.
Knowledge baseText, FAQs and web pages agents use to answer questions.
Contacts and listsPeople your agents talk to, grouped in lists, with custom fields.
Variables{{placeholders}} in prompts that are filled per contact, from contact fields, GoHighLevel or Google Sheets.
CampaignsOutbound calling to a list of contacts, in waves.

Drafts and going live

Anything that can reach real people starts safe: voice agents are drafts until you publish them, and flows are off until you turn them on. Campaigns place calls only once started.

Developer guide

Roles and permissions

Agency owners and admins reach every workspace in the agency. Everyone else has a role in each workspace they are a member of.

RoleScopeCan
OwnerAgencyEverything, including deleting workspaces and removing admins.
AdminAgencyEverything in every workspace, team and settings.
Full accessWorkspaceCreate, edit and delete; manage integrations, flows, working hours, the workspace team and audit logs.
EditorWorkspaceCreate and edit agents, contacts, campaigns, settings and templates. Cannot delete or manage integrations and flows.
Read onlyWorkspaceView everything, change nothing.

Roles and Claude

Claude acts as you, so your role is checked on every request. A Read only member can only create Read only connections; Build and manage and Full control need Editor or higher. See Access tokens.

Developer guide

Find your IDs

IDs identify things; they are not secrets.

IDWhere to find itUsed for
Agent IDAgents → the code icon on an agentdata-agent-id in the embed script
Workspace IDSettings → Claude Access, "Your IDs"The default workspace for Claude
Agency ID and user IDSettings → Claude Access, "Your IDs"Support and checking which account a token belongs to

An access token or connector link is a secret: anyone who has it can act as you. Never put one in website code or share it in a ticket.

JavaScript SDK

Embed the Web Agent

Add an AI assistant to any website with one script tag. Visitors can chat, talk by voice, or choose between both. Everything else is set in your dashboard.

The Web Widget is part of every paid plan. Turn it on for the agent first: Agents → the code icon → switch the widget on.

1. Copy your agent ID

Open Agents and click the code icon on your agent. The snippet there already has the ID filled in. The ID is not a secret, so it is safe in your page source.

2. Add the script

Paste it just before </body> on every page where the agent should appear. It loads with defer, so it never blocks your page.

html
<script
  src="https://app.luxebot.ai/web-agent.js"
  data-agent-id="YOUR_AGENT_ID"
  defer>
</script>

3. Style it in the dashboard

The widget reads its settings each time a page loads, so changes show up on your site without editing it. See Appearance and behavior.

4. Limit it to your websites

Under Allowed Domains, list the hostnames that may load the widget, one per line. Subdomains are included: example.com also allows app.example.com. Leave it empty to allow any website.

JavaScript SDK

Chat, voice or both

Set the mode in the widget settings under Mode. New widgets start in Chat.

ModeWhat visitors get
ChatA text conversation. AI replies can use bold, italic and links; visitor messages are plain text.
VoiceA live voice call in the browser. The browser asks for the microphone first.
BothVisitors choose chat or voice inside the widget.

Languages

In chat, the agent replies in the visitor's language automatically. Voice uses the language set on the agent's prompt.

Where conversations show up

Web conversations appear in the dashboard with the page the visitor was on. If the agent learns the visitor's name, it is saved on the contact. Voice minutes count as web agent usage.

JavaScript SDK

Appearance and behavior

All settings live in the dashboard (Agents → code icon), with a live preview and a chat simulator under Test.

Appearance

SettingOptionsDefault
PositionBottom right, bottom center, bottom left, center right, center left, top right, top left, hero (center), sticky headerBottom right
ThemeLight, dark, customLight
Primary colorAny color#3B82F6
ShapeCircle, rounded, square, elliptical, floating bubbleCircle
IconMicrophone, waveform, phone, chat, sparkMicrophone
SizeSmall, medium, largeMedium
Button labelUp to 25 charactersTalk to an agent
Agent avatarPNG, JPEG, SVG or WebP, up to 2 MBGradient

Behavior

SettingWhat it doesDefault
Pulse animationGently animates the button to draw attention.Off
Auto-openOpens the widget when the page loads.Off
Transcript downloadLets visitors download their conversation.On
Branding footerShows the branding text under the widget. Up to 80 characters.On

Pre-chat form

Turn on Ask visitors for their details first to collect a name, email and/or phone before the conversation starts. You can change the form title (up to 80 characters) and the submit button label (up to 25).

JavaScript SDK

Website builders and frameworks

The script is the same everywhere. Only where you paste it changes.

WordPress

Use a header and footer plugin (or your theme's footer code setting) and paste the script into the footer section of every page.

Webflow, Wix, Squarespace and Shopify

Paste the script into the site-wide custom code area for the end of <body> (often called "Footer code" or "Before </body>").

React and Next.js

Load the script once for the whole app. In Next.js, use next/script in your root layout.

jsx
import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://app.luxebot.ai/web-agent.js"
          data-agent-id="YOUR_AGENT_ID"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

JavaScript SDK

Network and security

If your site sets a Content Security Policy, allow these or the widget will not load.

DirectiveAllowWhy
script-srchttps://app.luxebot.aiLoads web-agent.js
connect-srchttps://bot.luxebot.aiWidget settings and chat messages
connect-srcwss: (our voice server)Voice mode only: the live audio connection
img-srchttps:The agent avatar

Voice mode also needs microphone permission. If your site sends a Permissions-Policy header, it must allow microphone.

What visitors share

The widget sends the conversation, the page address, and anything the visitor enters in the pre-chat form. Use Allowed Domains so other websites cannot use your agent.

JavaScript SDK

Troubleshooting

What you seeWhat to check
Nothing appearsThe widget is switched on for the agent, and the script is on the page with the right data-agent-id. Your browser console shows "data-agent-id is required" if the attribute is missing.
It works on one site but not anotherThe site's hostname is in Allowed Domains (or the list is empty).
It loads but never answersA Content Security Policy is blocking requests. See Network and security.
Voice does not startThe visitor allowed the microphone, and the page is on https://.
Changes do not showReload the page; settings are read on each page load.

MCP server

MCP server

Connect your own Claude and build agents, set up flows, add knowledge, import contacts and review calls by chatting. Claude can only do what your role allows, in the workspaces you can already open.

  1. 1

    Create a connection

    In Settings → Claude Access, choose how Claude connects and what it may do. See Access tokens.

  2. 2

    Connect Claude

    Paste one command, config or link into your Claude app. See Connect Claude.

  3. 3

    Ask

    Start with something read only, like "List my workspaces and the agents in each."

Endpoint

The server uses streamable HTTP at https://bot.luxebot.ai/api/mcp, authenticated with an Authorization: Bearer header. Any MCP client that supports remote servers with a custom header works.

What Claude can do

63 tools cover workspaces, voice, chat and web agents, flows, working hours, phone numbers, knowledge, contacts, variables, campaigns, calls and integrations. See the Tool reference.

MCP server

Access tokens

A token lets Claude act as you. Create it in Settings → Claude Access (agency Settings or Workspace Settings, both work the same).

You need a password on your account (accounts that only sign in with Google set one in Profile first). If two-factor is on, you also enter your authenticator code.

1. How will Claude connect?

KindForLasts
Connector linkclaude.ai and Claude Desktop "Add custom connector". Nothing to install. Can never publish, delete or run campaigns.30 days
TokenClaude Code, or Claude Desktop's config file. Stays on your computer. The only kind that allows Full control.90 days

2. What may Claude do?

AccessClaude canClaude cannot
Read onlyLook at agents, flows, contacts, campaigns, calls and settings.Change anything.
Build and manageAlso create and edit agent drafts, chat agents, flows, working hours, knowledge, contacts and lists, import contacts, pause a campaign.Publish, turn flows on, change phone numbers, delete, create or start campaigns.
Full controlAlso publish agents, turn flows on or off, change which agents answer a number, delete, and create, start, resume or stop campaigns. Each of these waits for your approval.Billing, team and roles, branding, payouts. Never available.

Start with Build and manage. Give Full control only to tokens you trust: it can publish agents that take real calls and start campaigns that dial real people.

3. Copy it now

The token or link is shown once. Changing or resetting your password revokes all of them. Revoke one any time from the same page.

MCP server

Connect Claude

Replace YOUR_TOKEN with the token or link from Access tokens. Settings → Claude Access shows these with your token already filled in.

Claude Code

Run this in a terminal, then start Claude Code and check /mcp. It should list luxebot as connected.

bash
claude mcp add --transport http luxebot https://bot.luxebot.ai/api/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Claude Desktop

Claude Desktop uses the small mcp-remote bridge, which needs Node.js. Open Settings → Developer → Edit Config, add this, then fully quit and reopen Claude.

json
{
  "mcpServers": {
    "luxebot": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://bot.luxebot.ai/api/mcp",
        "--header", "Authorization:${LUXEBOT_AUTH}"
      ],
      "env": { "LUXEBOT_AUTH": "Bearer YOUR_TOKEN" }
    }
  }
}

In Claude open Settings → Connectors → Add custom connector, name it LuxeBot and paste your connector link as the server URL.

text
https://bot.luxebot.ai/api/mcp/YOUR_TOKEN?workspace=WORKSPACE_ID

The link contains your token. Treat it like a password: anyone who has it can act as you until you revoke it.

Other MCP clients

Any client that can call a remote streamable HTTP server with an Authorization: Bearer <token> header works with https://bot.luxebot.ai/api/mcp.

Claude apps change their menus between releases. If a step looks different, check the current Claude documentation for adding a remote MCP server.

MCP server

Default workspace

Without a default, Claude asks which workspace to use (it can list them with list_workspaces). With one, it starts there and can still switch when you tell it to.

Pick a workspace under Default workspace in Settings → Claude Access and copy the command again. A token sends it as a header; a connector link uses ?workspace=.

bash
claude mcp add --transport http luxebot https://bot.luxebot.ai/api/mcp \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --header "X-Luxebot-Workspace-Id: WORKSPACE_ID"

Owners and admins reach every workspace in the agency. Everyone else reaches only the workspaces they are a member of, with their role in each.

MCP server

Approving risky actions

With a Full control token, Claude cannot publish, turn a flow on, change phone number agents, delete, or create, start, resume or stop a campaign on its own.

  1. 1

    Claude asks

    The request is saved, you get an email describing it, and Claude is told to wait.

  2. 2

    You decide

    Open Settings → Claude Access. The request is shown in plain words with the token that asked. Click Approve or Decline within 15 minutes. Deleting and creating, starting or resuming campaigns also need your password (and authenticator code).

  3. 3

    Claude continues

    Tell Claude you approved. It sends the same request and it runs once, exactly as saved, within 15 minutes of approval.

Only you, signed in, can approve. A declined request cannot be repeated, and a token can have at most five requests waiting.

Alerts

You are emailed when a connection is created on your account, the first time it is used, and whenever Claude asks for approval. If one was not you, revoke the token.

MCP server

Tool reference

63 tools. Tools that work inside a workspace take a workspaceId, or use your default workspace. Tools marked Full control need a Full control token and your approval.

Workspaces and guides

  • list_workspacesWorkspaces the token can work in, with your role in each.
  • get_agent_guideHow drafts, prompts and variables work, read before creating an agent.
  • get_flow_guideNode, edge and trigger format, read before creating a flow.
  • get_chat_agent_guideHow chat and web agents are set up.
  • get_variables_guideHow variables, mappings and custom fields fit together.

Voice agents

  • list_agentsVoice, chat and web agents in a workspace, drafts included.
  • get_agentOne agent with its settings.
  • create_agentCreate a voice agent as a draft.
  • update_agentEdit an agent.
  • duplicate_agentCopy an agent.
  • publish_agentPublish a draft so it can take real calls.Full control
  • delete_agentDelete an agent.Full control

Chat and web agents

  • create_chat_agentCreate a chat or web agent.
  • update_chat_agentEdit a chat or web agent.

Visual flows

  • list_flowsFlows in a workspace.
  • get_flowOne flow with its nodes and edges.
  • create_flowCreate a flow. It starts switched off.
  • update_flowEdit a flow. Stored secrets are kept.
  • duplicate_flowCopy a flow.
  • set_flow_activeTurn a flow on or off.Full control
  • delete_flowDelete a flow.Full control

Working hours and phone numbers

  • list_working_hoursWorking hours schedules.
  • create_working_hoursCreate a schedule.
  • update_working_hoursEdit a schedule.
  • delete_working_hoursDelete a schedule.Full control
  • list_phone_numbersPhone numbers and the agents that answer them.
  • set_phone_agentsChange which agents answer a number.Full control

Knowledge

  • list_knowledge_sourcesKnowledge sources in a workspace.
  • add_knowledge_textAdd text.
  • add_knowledge_faqAdd questions and answers.
  • add_knowledge_urlAdd a web page.
  • delete_knowledge_sourceDelete a source.Full control

Contacts and lists

  • list_contactsSearch contacts, with their custom field values.
  • create_contactCreate a contact.
  • update_contactEdit a contact, including custom field values.
  • delete_contactMove a contact to Discard.Full control
  • list_contact_listsContact lists.
  • create_contact_listCreate a list.
  • rename_contact_listRename a list.
  • delete_contact_listDelete a list.Full control
  • import_contactsImport up to 100 contacts at a time. Existing numbers are skipped.
  • import_sheet_contactsImport a connected Google Sheet. Previews first, 500 rows per call.

Variables and custom fields

  • list_variablesVariables, their mappings and the agents that use them.
  • create_variableCreate a variable.
  • update_variableEdit a variable.
  • delete_variableDelete a variable.Full control
  • set_variable_mappingMap a variable to a GoHighLevel field or Google Sheet column.
  • remove_variable_mappingRemove a mapping.
  • list_ghl_fieldsGoHighLevel custom values and fields.
  • map_ghl_fieldsMap several GoHighLevel fields to variables at once.
  • list_sheet_columnsColumns of a connected Google Sheet.
  • preview_agent_variablesWhat an agent's {{placeholders}} resolve to for a contact.

Campaigns

  • list_campaignsCampaigns in a workspace.
  • get_campaignOne campaign with its progress.
  • create_campaignCreate a campaign.Full control
  • start_campaignStart a campaign. Places real calls.Full control
  • resume_campaignResume a paused campaign.Full control
  • pause_campaignPause a running campaign.
  • stop_campaignStop a campaign for good.Full control

Calls and integrations

  • list_callsCalls, with filters.
  • get_callOne call with its transcript.
  • get_call_analyticsAnswer rate, outcomes and appointments.
  • list_integrationsWhich integrations are connected.

Not available through Claude

Buying or importing phone numbers, billing, team and roles, branding, payouts, connecting integrations (needs a browser sign-in), playing recordings, uploading files, and sending a test message to a chat agent.

MCP server

Security

  • Claude acts as you: your role in each workspace is checked on every call. Remove or demote a user and their tokens lose that access immediately.
  • Tokens are stored only as a hash, rate limited per minute, and can be revoked any time.
  • Secrets in flows (webhook secrets, request headers, keys in URLs) are shown to Claude as [hidden]; when Claude edits a flow, the stored values are kept.
  • Every change Claude makes is written to the audit log with the token that made it.
  • Text Claude reads (contact notes, knowledge pages, transcripts) can contain instructions written by other people. Review what Claude is about to do, especially with Full control.

MCP server

Troubleshooting

MessageFix
401 "access token is invalid, expired or revoked"Create a new token and check you pasted all of it.
409 "Switch the dashboard to the agency this token was created for"Switch the dashboard back to that agency, or create a token there.
429 "Too many requests"Slow down; the limit is per token per minute.
403 "The default workspace ID is not available to this token"Copy the command again from Settings, or remove the workspace header.
"That workspace is not available to this token"Ask Claude to list_workspaces; you can reach only workspaces you are a member of.
"Your role in this workspace does not allow ..."Your role there is too low for the action.
"... needs the critical scope"Create a Full control token for that action.
"This needs the user's approval" / "Still waiting"Approve it in Settings → Claude Access, then ask Claude to continue.
"This token is for Claude Code or Claude Desktop" / "This is a connector link"Use a connector link for the connector address, or a token for a header.
"OpenAI Key Required"Chat and web agents need an OpenAI key under Workspace → Integrations.
"Agent Limit Reached" or a contact limitPlan limits apply, as in the dashboard.

You have reached the end of the docs.

Connect Claude - MCP server - LuxeBot Docs