Inbound Call Agent
Audience: Sales · Management · QA · Support · Engineering · Where in app: Settings → AI Agents → Inbound Call Agent (per-agent tabs: AI Engine, Behavior, Phone Numbers, Call Forwarding, Call Screening, Working Hours, Post-call Tags, Webhook) · Plan availability: Per-company admin gate ai_inbound_call_allowed — see Plan & limits
The Inbound Call Agent answers your incoming phone calls with a natural-sounding AI voice — greeting the caller, answering questions about your business, qualifying the lead, booking a meeting if there's interest, and transferring to a human when asked. It runs on real phone numbers (Twilio, imported into the platform) and is deployed to ElevenLabs Conversational AI. A company can run multiple inbound agents, each with its own prompt, voice, language, working-hours rules, phone numbers, and post-call webhook. The reserved agent_key default maps to the legacy company.ai_inbound_call object; additional agents are slots in company.ai_inbound_call_agents.
What it does
- Answers inbound phone calls with a configurable AI voice persona (name, instructions, greeting), auto-switching among ~70 preset languages (
language_detection; the configured language is the greeting). The default prompt has the agent admit it is an AI when asked (a5ebca159/ frontend9d2e906e, 2026-11-12 — previously "Never reveal that you are an AI" / "human representative"); saved prompts are not rewritten. - Picks the voice (from the ElevenLabs voice catalog, with audio previews and gender/accent/language filters), the agent language, and the AI model (curated inner-LLM list).
- Rings real phones first via Call Forwarding (
routing_priorities) — up to 10 numbers in order, each with its own ring timeout, falling through to the AI. - Forwards to a human on request via a per-agent human-handoff number (falls back to the company number).
- Optionally transfers in-hours calls straight to a human via a per-day Working Hours schedule (outside hours, or when disabled, the AI answers).
- Buys numbers in-app (US/CA/GB/AU, local/toll-free/mobile, paid from the telephony wallet) or imports BYO Twilio and Telnyx numbers so incoming calls route to the AI.
- Tags the GHL contact after the call (
post_call_tags: built-insbooked/qualified+ AI-matched custom rules). - POSTs a post-call webhook (transcript,
transcript_text,call_sentiment, signedrecording_url, phone numbers, direction, duration) to your URL when a call finishes. - Books meetings, looks up products, transfers, sends follow-ups, and (for trade companies) can log a Simpro job via voice tools — see Call Agent and How it works.
How it works
- Create an agent. From the agent list (
AgentList.vue) you create an agent with a name (POST /ai-inbound-agents). Thedefaultagent always exists; extras are additional slots. Agents can be cloned. - Configure across the tabs (each save goes through
PATCH /ai-inbound-agents/:agent_key):- AI Engine — voice + language + AI model.
- Behavior — agent name, greeting/opening script, and agent instructions.
- Phone Numbers — the human-handoff number + in-app number purchase + imported Twilio/Telnyx numbers.
- Call Forwarding — ordered ring-first numbers (
routing_priorities). - Call Screening — optional keypress gate against auto-dialers + the screened-call log.
- Working Hours — optional in-hours human transfer.
- Post-call Tags — GHL outcome tagging rules.
- Webhook — optional post-call POST.
- Deploy to ElevenLabs. Saving Behavior, AI Engine, or the handoff number triggers
useInboundAgentSync→POST {aiUrl}/elevenlabs/sync-inbound-agent, which creates/updates the ElevenLabs agent and re-binds the inbound numbers to thisagent_key. Without this sync, incoming calls on imported numbers are not routed to any AI agent. Since backendf0716b4c7thePATCHitself deploys: a save touching a live field (DEPLOY_FIELDS— enable, model/provider, voice, language, setting, instructions incl. S2S, opening scripts, agent name,use_memory,authentication_required,transfer_number) callssyncInboundAgentserver-side and returnsdeploy: {attempted, ok, reason}(no_live_fields,agent_not_found,not_enabled, or the sync error). A failed deploy never fails the save. Agents never enabled are skipped (ms-ai's sync would create and bill an ElevenLabs agent). The frontend (037f3f69) attachesdeploynon-enumerably to the returned agent and AI Engine skips its own sync only whendeploy.ok === true. The sync sends: company id,agent_key, timezone,company_phone(handoff destination),voice,first_message,max_duration(900s),model_name,system_prompt,agent_availability(availableif a company phone exists, elseno_human_agents), andagent_language. - System prompt assembly (
useInboundAgentSync.buildSystemPrompt): inadvancedmode the savedagent_instructionsare used with[agent_name]substituted; otherwise a default inbound prompt is built fromcompany_name,tone, andresponse_size. The opening usesopening_script(advanced) or a default greeting. - Runtime. A call lands on a bound Twilio/Telnyx number (ms-ai matches the called number digits-only —
phone-number-match.tsPhoneNumberEquals, since rows are stored as+1 938…,(938) …etc. — and prefers the row withmeta.purpose: 'inbound'when a number carries inbound and outbound bindings) → wallet gate (app-bought numbers) → Call Forwarding chain (if configured) → working-hours check → ElevenLabs runs the agent → voice tools (book meeting, product lookup,escalateToHuman, follow-up, knowledge-base search, Simpro job for trade companies) execute via the tool-call protocol → ms-ai/ms-communication. On finish, the transcript is saved, sentiment/outcome classified, GHL tags applied, and the optional post-call webhook fires. See Call Agent and Telephony.
Configuration & options
AI Engine tab (AIEngine.vue)
| Field | Stored as | Notes |
|---|---|---|
| Agent Voice | agent_voice_id | ElevenLabs catalog (GET {aiUrl}/elevenlabs/voices) with in-row preview and gender/accent/language filters — or, for an S2S model, the vendor's own voice set (useProviderAwareVoices.js; static preview clips). Changing the model clears a voice the new model can't play. |
| Agent Language | agent_language | Default '' = Same as organization (AgentLanguagePicker.vue, searchable) — resolved agent_language → company.language → en by inboundAgentSync / useInboundAgentSync; changing company.language re-deploys inheriting agents (backend de172c75a). Otherwise a code from AI_CALL_SUPPORTED_LANGUAGES. |
| Model | model / model_provider | Options are the agent_type: 'call' rows from ms-ai GET /ai-model-pricing/estimates/:company_id (curated CALL_MODEL_CATALOG in src/elevenlabs/call-models.ts: claude-sonnet-4-5 default-first, GPT/Gemini rows, GLM 5.3 Flash, and S2S rows filtered by buildCallModelOptions). New agents default to claude-sonnet-4-5 (backend create, 184010eaa). Ids outside ElevenLabs' Llm enum silently fall back to ELEVENLABS_INNER_LLM. An S2S model (GPT Live 1 / Gemini 3.8 Live / Gemini 3.8 Live Extended Thinking, open to every company; Grok Voice for companies with xai on — phone over SIP when ms-comm XAI_SIP_ENABLED; retired GPT Realtime / older Gemini ids are refused at save) routes the inbound role to the speech-to-speech path — Voice Engine; syncInboundAgent stamps voice_provider on the Twilio VoiceUrl and keeps an ElevenLabs standby agent. Background sound + speech settings are hidden for it. |
| Reasoning Model (GPT-Live) | gpt_live_reasoning_model | Only when the model is gpt-live-1. Options from frontend GPT_LIVE_REASONING_MODELS (GPT-6 Luna default, GPT-6 Sol, GPT-6.1 Sol, GPT-5.6 Terra) = ms-ai LIVE_BACKEND_MODELS; sent by backend gptLiveInstructionsField. See Voice Engine › GPT-Live. |
| Background sound | background_sound | ElevenLabs-native ambience (BackgroundSoundSettings component): enable, preset track (default office1), volume (default 25, sent as /100), crossfade loop. Per-agent Mixed block on the sync DTO. |
| Speech settings | speech_settings | SpeechSettings component: responsiveness (turn-eagerness buckets), interruption sensitivity (default 0.5), backchannel, audio normalization. Same shape as ai_config.call_speech_settings on the widget agent. |
| Continue previous conversation | continue_previous_conversation | Returning callers (matched on caller_number) get an LLM-personalized opener built from the last call's transcript — see Telephony › Cross-call memory. Persist fix (32b27df90): ai_inbound_call is a strict subdoc, so the then-undeclared field was silently dropped and the toggle reverted — fields added to the default agent must be declared in CompanyModel. |
| Require User Authentication | authentication_required | Shown as an Authentication tab only when the super-admin ai_agent_authentication_allowed flag is on. Third gate of caller verification — see Telephony › Caller authentication. Second strict-subdoc lesson: the default agent saves as a whole ai_inbound_call object, so a stale tab's $set erased it (and webhook_secret) — fixed by preserveInboundAgentFields, not by declaring the field. |
| Use memory | use_memory | Default true (absent = on). Off suppresses read and write of caller memory; resolved in ms-comm via AgentMemoryFlagHelper (fails open) and ANDed into continue_previous_conversation. See Telephony › Agent memory gating. |
Behavior tab (Behavior.vue)
| Field | Stored as | Notes |
|---|---|---|
| Recording & AI disclosure | call_disclosure: { enabled, text } | CallDisclosureSetting.vue card above the form, saved on its own (Save; inbound re-syncs). Off unless enabled (absent = off). Text ≤300 chars, control chars/whitespace collapsed, {{/}} stripped; default "Just so you know, this call may be recorded and you're speaking with an AI assistant." Backend lib/callDisclosure validates; ms-ai (elevenlabs/call-disclosure.ts) fetches it at every telephony agent sync via backend POST /internal/ai-call/disclosure and prepends it word for word to the ElevenLabs first message (bridged, Direct connect, outbound). ms-comm CallDisclosureHelper strips and re-applies it when the opener is rewritten for a returning caller, and the Grok SIP path speaks it as a non-interruptible opener. |
| Agent Name | agent_name | Default {branding} Assistant. Substituted into the prompt's You are [agent_name], prefix. |
| Greeting Message | opening_script | First line spoken when answering. Default: [enthusiastic warmly] Hi, thanks for calling {company_name}. How can I help you today? |
| Agent Instructions | agent_instructions | Required. Stored with a You are [agent_name], prefix re-attached on save; the UI strips it for editing. Inbound agents are always saved as setting: 'advanced'. Copy from Widget Voice Agent fills whichever box is showing. |
| Agent Instructions for speech-to-speech (S2S) models | agent_instructions_s2s | Shown instead of the box above when the agent's model is an S2S model the company is permitted; Use default S2S prompt loads the generic prompt. Used at call time via backend agentInstructionsFor (empty → standard instructions). See Voice Engine › Instructions. |
| Greeting Message for speech-to-speech (S2S) models | opening_script_s2s | Replaces Greeting Message for an S2S model (no expression tags); resolved by backend openingScriptFor (empty → opening_script). |
| Speech model instructions (GPT-Live 1) / Reasoning model instructions | agent_instructions_gpt_live_speech / agent_instructions_gpt_live_reasoning | Replace the S2S box on gpt-live-1; both required, each with a Use default … button (gptLiveDefaultPrompts.js). Sent to ms-ai as gpt_live_instructions on sync / call. |
Phone Numbers tab (PhoneNumber.vue)
- Human-handoff number (
transfer_number): where this agent forwards callers who ask for a human. Blank → falls back to the company number. Saving re-deploys to ElevenLabs so the escalation tool picks up the new value. At runtime the bridge reads it live from Mongo, presents the original caller's number as caller-ID (retrying with the owned number on carrier reject), and resolves Twilio credentials per dialed number — BYO and platform-bought numbers mix freely. See Telephony › Human escalation. - Buy a number in-app (
GET {aiUrl}/elevenlabs/available-phone-numbers/twilio→POST {aiUrl}/elevenlabs/buy-phone-number/twilio/inbound): country picker US/CA/GB/AU, type local/toll-free/mobile, area-code/contains filters. The buy is gated on the telephony wallet covering the marked-up price (markup_percent); the first month is charged at purchase and the number lands in the company's Twilio subaccount. The tab shows the wallet balance and a "Top up wallet" link. See Telephony › Number lifecycle. - Import a Twilio number (
POST {aiUrl}/elevenlabs/import-phone-number/twilio/inbound): requires the E.164 number, Twilio SID, and Twilio Auth Token. The import stamps this agent's handoff number (or company number) on the number's meta for runtime transfer resolution. Numbers are scoped to the agent'sagent_keyand filtered topurpose: 'inbound'. Delete is confirmed and irreversible. - Import a Telnyx number (
POST {aiUrl}/elevenlabs/import-phone-number/telnyx/inbound): BYOtelnyx_api_key+telnyx_connection_id(TeXML app); ms-ai points the TeXML app's voice URL at the ms-communication bridge.
Call Forwarding tab (CallForwarding.vue → routing_priorities)
Ordered list of real phone numbers to ring before the Voice AI — each row { number, ring_timeout } (timeout 5–120s, default 20s; max 10 rows; reorder/remove inline). Empty list = every call straight to the AI. Sanitized server-side in AiInboundAgentController._sanitizeRoutingPriorities; ms-communication dials the chain in order and falls through to the AI on exhaustion or any error. Applies regardless of working hours; the telephony wallet gate runs before the chain. Saving does not redeploy to ElevenLabs.
Call Screening tab (CallScreening.vue → call_screening)
Optional keypress gate that answers with a Twilio <Gather> before anything that costs money (no forwarding leg, no ElevenLabs stream) — auto-dialers talk but almost never send DTMF. Runs ahead of Call Forwarding so spam doesn't ring humans either. Twilio numbers only.
| Field | Stored as | Notes |
|---|---|---|
| Enable | call_screening.enabled | Default off — agents predating the feature are untouched. |
| Prompt | call_screening.prompt_text | ≤200 chars (spoken by Twilio TTS on every screened call — length is billed airtime). {digit} placeholder is substituted with a fresh random digit 1–9 per call; a prompt without the placeholder gets Press N. appended. Default Press {digit} to continue. |
| Wait | call_screening.wait_seconds | Clamped 3–20, default 6. |
Sanitized in AiInboundAgentController._sanitizeCallScreening (mirrored in ms-comm _normalizeCallScreening). Wrong digit / no input logs to screened_calls (TTL 90d) — the tab shows the log via GET /ai-inbound-agents/:agent_key/screened-calls. Screening never blocks a number; each call gets a fresh prompt. Fails open on any error. Full mechanics: Telephony › Inbound call screening.
Post-call Tags tab (PostCallTags.vue → post_call_tags)
Tags the caller's GHL/LeadConnector contact with the call outcome. Built-in scenarios (fixed description, editable tag): booked, qualified — inbound callers are live humans, so no voicemail/no-answer built-ins (that's the outbound set). Plus custom rules (description + tag, AI-matched against the transcript). Applied by the backend via /internal/ai-call/contact-extracted; mirrors AiOutboundAgentController._sanitizePostCallTags.
Working Hours tab (WorkingHours.vue → working_hours)
When enabled, calls during these hours are transferred straight to a human (the transfer number below); outside these hours — or when disabled — the AI answers. (Note the polarity: in-hours = human, off-hours = AI.)
| Field | Stored as | Notes |
|---|---|---|
| Enable working hours | working_hours.enabled | Off = AI handles every call. |
| Transfer number | working_hours.transfer_number | In-hours forwarding destination; blank → company number. |
| Timezone | working_hours.timezone | Hours evaluated in this timezone (default company timezone / UTC). |
| Per-day schedule | working_hours.days.{mon..sun} | Each { enabled, start, end }. Defaults: weekdays 09:00–17:00 enabled, weekends closed. "Apply to all days" copies a row's times. |
Webhook tab (Webhook.vue)
| Field | Stored as | Notes |
|---|---|---|
| Webhook URL | post_call_webhook_url | Optional; must start with http:///https:// (≤2048 chars). On call end we POST the full call under a next_level_call namespace: transcript + transcript_text, summary, call_sentiment, signed recording_url, phone numbers, direction, duration, agent_key. Held until the ElevenLabs analysis lands; backend PostCallWebhookFallbackJob fires it after 5 min if the analysis never arrives (exactly-once). Blank disables. |
| Custom header | post_call_webhook_header | Optional single line Name: value (≤1024 chars), e.g. Authorization: Bearer …. |
For QA/Support: every tab tracks unsaved edits and prompts before navigation. Saves surface toasts; ElevenLabs deploy failures show "Failed to deploy … to ElevenLabs" without blocking the DB save.
Behaviors & edge cases
- Deploy-on-save is essential. Behavior, AI Engine, and handoff-number saves re-deploy to ElevenLabs. The sync deliberately does not gate on
model(the inner LLM is server-pinned), so agents created before the model default still deploy. defaultagent is special. It maps to the legacycompany.ai_inbound_callobject and cannot be deleted (no delete button); it can be cloned.- Working-hours polarity. In-hours → human transfer, off-hours → AI. This is the opposite of the usual "open = staffed" intuition; it's designed for "let humans take calls during the day, AI covers after hours." Call Forwarding's
routing_prioritiesring before this check and apply regardless of working hours. - Wallet gate on app-bought numbers. When the telephony wallet is empty, inbound calls on platform-purchased numbers are answered with "This number is temporarily unavailable. Goodbye." (fail-open on errors; BYO numbers never gated).
- Agency pause gate (ms-comm
InboundCallController,e7eebfc). A company withpaused_atset (agency paused the client, usually an unpaid invoice) never reaches the AI: the call dials the first routing-priority number, else the working-hours transfer number, else the agent'stransfer_number, elsecompany.phone_number; with none configured the caller hears "This number is temporarily unavailable. Goodbye." Runs before screening, routing priorities and working hours; fails open. WhatsApp inbound is ingested but the AI stays muted the same way. - Handoff fallbacks. Both the per-agent handoff number and the working-hours transfer number fall back to
company.phone_numberwhen blank. agent_availability. Sent asavailableonly if the company has a phone number; otherwiseno_human_agents(affects whether the agent offers a human transfer).- Per-agent number scoping. Imported numbers are bound to a specific
agent_keyand filtered bypurpose: 'inbound'; the Phone Numbers query is scoped server-side.
Plan & limits
- Gating flag: the Inbound card and config are gated on
company.ai_inbound_call_allowed(admin-controlled per company; default off).Agents.vueuseshasInboundCallAgent. - Agent cap:
company.ai_inbound_call_agents_allowed(defaults to1— the default agent — when unset; admins raise it from the company detail page). The "Create agent" tile hides when the cap is reached or the package allows zero. - AI credits: inbound voice calls consume credits per minute (faster than chat) — both ElevenLabs voice minutes and the LLM brain count. Logged in
AICreditLogModel(sourcevoice_call). See AI Credits. - Telephony costs: app-purchased numbers bill the telephony wallet (=
remaining_purchased_ai_credits, 1 credit = $0.01): monthly rental (daily 06:00 UTC cron), per-call Twilio cost (10-min sweep, subaccount-metered), all with the globaltelephony_markup_percentapplied. Plan AI credits never pay telephony. Wallet < 0 → suspend → warnings day 3/6 → release after ~7d. BYO numbers bill the client's own carrier account. See Telephony subsystem.
Technical implementation
- Frontend:
frontend/src/views/settings/ai/agents/InboundCallAgent/—index.vue(tabs),AgentList.vue(list/create/clone/delete + cap),AIEngine.vue(voice/language/model + speech settings + background sound + continuation toggle),Behavior.vue(name/greeting/instructions),PhoneNumber.vue(handoff + buy + Twilio import),CallForwarding.vue(routing priorities),CallScreening.vue(keypress gate + log),WorkingHours.vue(per-day schedule),PostCallTags.vue(GHL tags),Webhook.vue(post-call),useInboundAgentSync.js(ElevenLabs deploy). Card:InboundCallAgentCard.vue. Composables:useInboundAgent.js,useTelephonyMarkup.js. - Backend:
backend/app/routes/aiInboundAgentRoutes.js→AiInboundAgentController(list,create,show,update,destroy,rotateSecret,clone; sanitizers_sanitizeRoutingPriorities,_sanitizePostCallTags). Config persists incompany.ai_inbound_call(default agent) andcompany.ai_inbound_call_agents[]. - ms-ai (ElevenLabs):
ms-ai/src/elevenlabs/—elevenlabs.controller.ts(POST /sync-inbound-agent,POST /import-phone-number/twilio/inbound,GET /voices),elevenlabs.service.ts(prompt/tool assembly, voicemail/transfer handling, Simpro job-booking section). Entities:elabs-agents.entity.ts,elabs-phone-numbers.entity.ts(both carry theagent_keydiscriminator). Voice tools inms-ai/src/knox-voice/. See ms-ai. - Runtime bridge & monitoring: calls route through ms-communication so the dashboard can monitor/take over. Nox reports call config/outcomes but doesn't place calls — see Nox assistant.
Related
- Call Agent (shared voice tools, post-call enrichment, quality scoring)
- Voice Engine (speech-to-speech models, routing, billing)
- Outbound Call Agent
- Telephony subsystem (carriers, number lifecycle, wallet, escalation)
- AI Credits
- ms-ai service
- ms-communication service