Receptionists
BetaCreate an AI receptionist that answers business questions, takes written messages, and connects callers with your team. A receptionist belongs to your company and can serve several business numbers. Create it here, then select its ID in a business-number call flow.
The receptionist model
- Name
id- Type
- string
- Description
- Stable public UUID. Use this as
ai_receptionist_idwhen configuring a number's routing.
- Name
name- Type
- string
- Description
- Required when creating. A nonblank name of up to 100 characters.
- Name
language- Type
- string
- Description
- One of the 32 supported language codes. Defaults to
dawhen creating. The same primary caller language applies to every number using this receptionist.
- Name
voice_id- Type
- string
- Description
- Optional when creating or updating. An ElevenLabs voice ID from the shared voice catalog. Defaults to Simon. Omitting it on update preserves the selected voice.
- Name
configuration- Type
- object
- Description
- The receptionist's greeting, business knowledge, permitted transfer destinations, and optional message-taking settings. See Configuration.
- Name
lock_version- Type
- integer
- Description
- Read the current value and send it with every update. A missing or stale value returns
422.
- Name
knowledge_index- Type
- object or null
- Description
- Website import status, or
nullwhen no website is configured. See Retrieve the knowledge index.
All endpoints use API-key authentication or an authorized OAuth token and are scoped to the authenticated company. Unknown or foreign IDs return 404. The dashboard manages the same resources on the Receptionists page. These operations are also available through MCP.
Supported languages
Receptionists and business numbers offer the same 32 language choices:
| Language | Code | Language | Code |
|---|---|---|---|
| Arabic | ar | Bulgarian | bg |
| Croatian | hr | Czech | cs |
| Danish | da | Dutch | nl |
| English | en | Filipino | fil |
| Finnish | fi | French | fr |
| German | de | Greek | el |
| Hindi | hi | Hungarian | hu |
| Indonesian | id | Italian | it |
| Japanese | ja | Korean | ko |
| Malay | ms | Mandarin Chinese | zh |
| Norwegian | no | Polish | pl |
| Portuguese | pt | Romanian | ro |
| Russian | ru | Slovak | sk |
| Spanish | es | Swedish | sv |
| Tamil | ta | Turkish | tr |
| Ukrainian | uk | Vietnamese | vi |
Choose one primary language per receptionist. Calls do not automatically switch languages. Write configuration.opening_text in that language. Changing the language in the dashboard, API, MCP or Ping does not translate or change your greeting. Have a native speaker review greetings and business information before use.
Private employee introductions use the receptionist's language and voice from the revision captured when the call starts. For example, an English-speaking receptionist on a Danish number introduces calls to employees in English. Updating the receptionist does not change calls already in progress. The business number's language controls number greetings and other number messages, not receptionist introductions. Changing a number's language does not translate saved greeting text. Recorded-call and voicemail transcription detect the spoken language automatically; these settings do not translate transcripts. Voice quality and accents vary by language. Receptionists remain in beta.
Voices
Receptionists use the same voice names and picker as business-number greetings:
| Voice | ID | Style |
|---|---|---|
| Mark | gs0tAILXbY5DNrJrsM6F | Energetic and informative |
| Simon | KH1SQLVulwP6uG4O3nmT | Casual and friendly, the default |
| Ellen | BIvP0GN1cAtSRTxNHnWS | Friendly and conversational |
| Sarah | aMSt68OGf4xUZAnLpTU8 | Clear and professional |
Send voice_id alongside name or language, not inside configuration. All four voices can be selected with any of the 32 supported languages. Voice and language changes leave opening_text unchanged. Write the greeting in the chosen language and review pronunciation with a native speaker.
The dashboard plays your current greeting with the selected voice. For the four catalog voices, previews and Custom/legacy agents use eleven_v4. Realtime Max and Mini keep the selected voice and language, but ElevenLabs manages their speech model, so calls can sound different from previews. Realtime availability depends on the ElevenLabs workspace and its compliance and data-residency settings. Preview synthesis follows the greeting text's language rather than translating it. Provider availability and pronunciation quality are not guaranteed for every voice-language combination. Preview generation is an interactive dashboard action, not an MCP or Ping tool.
Existing receptionists receive Simon as their selected setting when the database migration runs. The migration does not contact ElevenLabs. Saving a receptionist or explicitly deploying it from Admin → Receptionist models prepares and verifies a replacement agent with that voice. A pending voice update can be deployed even when the target model already matches. Current calls retain their published revision. Restoring a revision restores its saved voice, language and configuration too; older revisions can restore a legacy voice. Legacy voices use eleven_v4_turbo for Custom agents, rather than the eleven_v3 model used for their standalone previews.
Access and pricing
Receptionists require Pro regardless of the pro_feature_gates rollout flag, except for companies internally marked as test companies. Test companies can use receptionists without a subscription; this does not grant other Pro entitlements. Active, trialing and past-due subscriptions retain Pro access. Other Free companies see an upgrade prompt; receptionist API and MCP access and AI call execution are unavailable.
AI usage costs $0.29 USD per minute, billed by connected seconds, in addition to the Pro subscription and any phone charges. AI usage is not covered by included local calling hours and is not rounded up to whole minutes. Prices exclude tax. Creating a receptionist automatically queues the AI usage item for the company's active USD subscription. Existing receptionists are also checked when subscriptions change. Trial accounts gain the usage item when their subscription becomes active. Billing requires the deployment's STRIPE_AI_METERED_PRICE_ID; calls before the usage item was added are not billed retroactively.
No company feature flag or environment switch is required. External AI credentials are still required to provision agents and handle calls.
For other Free companies, receptionist API endpoints return 404, new AI routing is rejected, and runtime sessions and tool callbacks are blocked. Existing saved configurations are retained, not deleted. Business-number API responses still identify a saved AiAgentConfig routing type but omit its receptionist ID and configuration while access is unavailable. Its expected_revision_id and corresponding call_flow_revision_ids entry are null, so the saved AI revision identifier is not exposed. Calls attempting an unavailable AI destination use the existing failure/fallback path.
Configuration
- Name
schema_version- Type
- integer
- Description
- Required. Must be
1.
- Name
opening_text- Type
- string
- Description
- Required. Between 1 and 1,000 characters after trimming. Dynamic-variable templates are not allowed. This changes only the first spoken message; Phone.inc controls the instructions and model. Choose the voice separately with
voice_id. Your company is responsible for any required disclosure.
- Name
transfer_targets- Type
- array
- Description
- Optional. Up to ten unique active employees from the same company. Each entry has an
employee_idand adescriptionof 1–300 characters explaining when to transfer to them.
- Name
department_ids- Type
- array
- Description
- Optional. Up to ten unique company department UUIDs. These permit transfers into shared department queues, not employee warm transfers. See Departments.
- Name
knowledge- Type
- object
- Description
- Optional business context, Q&As, exact-page imports and an automatically indexed website. See Business knowledge.
- Name
message_taking- Type
- object
- Description
- Optional. Message taking starts disabled. Set
enabledand thefieldsto collect. See Messages and transfers.
- Name
tone- Type
- string
- Description
- Optional.
friendly_professional(the default) uses warm, courteous conversation;formal_directuses neutral, businesslike sentences without small talk;fun_lightuses upbeat, relaxed wording with restrained playfulness when appropriate. Tone changes wording independently of the selected voice. All tones stay calm and straightforward for complaints, distress, sensitive information and private transfer introductions. Phone.inc safety, privacy, language and tool rules always take priority. The configured opening text is unchanged.
Configuration updates replace the entire object, not individual nested fields. Retrieve it first and preserve settings you want to keep. Omitting configuration from an update preserves it. Unknown configuration keys are rejected. Portraits, receptionist integration grants and remote MCP-server connections are unavailable.
Saving a receptionist creates and validates its ElevenLabs agent, even before it is assigned to a business number. Configuration, imported page content or language changes prepare one replacement immutable version shared by all linked flows, then activate it atomically. A preparation or persistence failure leaves the saved receptionist and previous flows unchanged. Current calls keep their captured version, permissions and usage, except that removed integration tools remain blocked. Renaming does not itself reprovision the voice agent, except when publishing updated system instructions. Existing agents and live sessions remain intact through migration; linked legacy flows converge on one version when the receptionist is next saved.
List receptionists
Returns all company receptionists as a JSON array, ordered by name and ID. There is no pagination wrapper.
Request
curl https://app.phone.inc/api/v1/receptionists -H "X-Api-Key: $PHONE_INC_API_KEY"
Response
[
{
"id": "01a00000-0000-7000-8000-000000000003",
"name": "Customer support",
"language": "en",
"voice_id": "KH1SQLVulwP6uG4O3nmT",
"configuration": {
"schema_version": 1,
"opening_text": "Hello, you are speaking with our AI assistant. How can I help?"
},
"lock_version": 1,
"knowledge_index": null
}
]
Create a receptionist
Send name, a valid configuration, and optionally language and voice_id. Creation publishes the voice agent and returns the receptionist with status 201. It does not assign the receptionist to a number. Use the returned ID in a routing slot.
Invalid attributes or provider preparation failures return 422.
Request
curl https://app.phone.inc/api/v1/receptionists \
-H "X-Api-Key: $PHONE_INC_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"name":"Customer support","language":"en","configuration":{"schema_version":1,"opening_text":"Hello, you are speaking with our AI assistant. How can I help?"}}'
Response
{
"id": "01a00000-0000-7000-8000-000000000003",
"name": "Customer support",
"language": "en",
"voice_id": "KH1SQLVulwP6uG4O3nmT",
"configuration": {
"schema_version": 1,
"opening_text": "Hello, you are speaking with our AI assistant. How can I help?"
},
"lock_version": 1,
"knowledge_index": null
}
Retrieve a receptionist
Returns one receptionist. Read its lock_version before updating and its full configuration before replacing configuration settings.
Request
curl https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003 -H "X-Api-Key: $PHONE_INC_API_KEY"
Response
{
"id": "01a00000-0000-7000-8000-000000000003",
"name": "Customer support",
"language": "en",
"voice_id": "KH1SQLVulwP6uG4O3nmT",
"configuration": {
"schema_version": 1,
"opening_text": "Hello, you are speaking with our AI assistant. How can I help?"
},
"lock_version": 1,
"knowledge_index": null
}
Update a receptionist
Send the current lock_version and any of name, language, voice_id or configuration. Voice changes publish a replacement agent using the currently selected model. Admin model deployments retain the selected voice. The example renames the receptionist without replacing its configuration. Use the lock_version returned by your own retrieve request, not the illustrative value below.
Returns the updated receptionist. Missing or stale versions, validation failures, and provider preparation failures return 422. If a linked call flow changes while the agent is being prepared, the update also fails without replacing the previous version. Reload before retrying.
Request
curl -X PATCH https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003 \
-H "X-Api-Key: $PHONE_INC_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"name":"Support team","lock_version":1}'
Response
{
"id": "01a00000-0000-7000-8000-000000000003",
"name": "Support team",
"language": "en",
"voice_id": "KH1SQLVulwP6uG4O3nmT",
"configuration": {
"schema_version": 1,
"opening_text": "Hello, you are speaking with our AI assistant. How can I help?"
},
"lock_version": 2,
"knowledge_index": null
}
Delete a receptionist
Returns 204 with no body. Remove the receptionist from every business-number call flow before deleting it. An assigned receptionist returns 422. Historical call and revision records are preserved.
Request
curl -X DELETE https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003 -H "X-Api-Key: $PHONE_INC_API_KEY"
Retrieve the knowledge index
Returns { "knowledge_index": null } when no website is configured. Otherwise knowledge_index contains status (queued, crawling, ready or failed), page_count, last_updated_at, next_refresh_at and retry_at. Timestamps are ISO 8601 strings or null. This same object appears on receptionist responses.
Request
curl https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003/knowledge -H "X-Api-Key: $PHONE_INC_API_KEY"
Response
{
"knowledge_index": {
"status": "ready",
"page_count": 12,
"last_updated_at": "2026-11-09T09:00:00Z",
"next_refresh_at": "2026-11-10T09:00:00Z",
"retry_at": null
}
}
Refresh the knowledge index
Queues a manual website refresh and returns 202 with the knowledge-index object. No request body is required. First save a public website as configuration.knowledge.website_url; no configured website returns 422.
Requests during an active import reuse it and return 202. Otherwise, requests within five minutes of the previous refresh request return 429. This endpoint also has a company-wide limit of ten requests per minute. Use retry_at to find when the five-minute refresh interval ends. A 202 response means the import was accepted, not that indexing has completed; retrieve the index to check its status.
Request
curl -X POST https://app.phone.inc/api/v1/receptionists/01a00000-0000-7000-8000-000000000003/knowledge -H "X-Api-Key: $PHONE_INC_API_KEY"
Response
{
"knowledge_index": {
"status": "queued",
"page_count": 12,
"last_updated_at": "2026-11-09T09:00:00Z",
"next_refresh_at": null,
"retry_at": "2026-11-09T10:05:00Z"
}
}
Business knowledge
The optional configuration.knowledge object is supported by the dashboard, REST API, MCP and the in-app assistant. It contains optional context (up to 5,000 characters), website_url (one website for automatic crawling), urls (up to five unique exact-page URLs), and questions (up to twenty objects with a nonblank question of up to 300 characters and answer of up to 2,000 characters). Send an empty knowledge object to clear it while preserving the other fields in your complete configuration. Dynamic-variable templates are not allowed in employee-entered knowledge.
For example, use this as configuration.knowledge inside a complete configuration:
{
"context": "We repair bicycles and sell spare parts in Copenhagen.",
"urls": ["https://yourbusiness.com/services", "https://yourbusiness.com/returns"],
"questions": [
{ "question": "Where can I park?", "answer": "There is free parking behind our building." }
]
}
Each save fetches the exact urls and snapshots their readable text into the immutable agent version. Save again to refresh these imported pages; unchanged page text reuses the version. These exact-page imports do not execute JavaScript or crawl links. URLs must use public HTTPS on port 443 without credentials, query strings or fragments. Requests reject redirects, private/reserved DNS addresses and compressed responses; connections are pinned to verified public addresses. Each page has a five-second timeout, 256 KiB response limit and 10,000-character text limit. The complete prompt knowledge snapshot, including JSON structure, is limited to 40,000 characters. An unreadable, oversized or unavailable exact page rejects the save with 422, preserving the published agent and linked flows.
Context, Q&As and exact-page imports are encrypted with the receptionist configuration and revision snapshot, redacted from request logs and supplied as bounded reference text in the agent prompt. Q&As take priority over context and website content. All imported content remains untrusted: it cannot grant tool permissions or override Phone.inc's instructions. Do not include secrets or unnecessary personal data. Knowledge increases the model's context and may increase provider usage. Existing calls keep their prior prompt knowledge snapshot.
Automatically indexed website
Set configuration.knowledge.website_url to a public HTTPS URL without credentials, query or fragment. Saving queues a Cloudflare Browser Run crawl with JavaScript rendering, sitemap and link discovery, limited to 100 pages on the configured hostname. A verified HTTPS redirect between that host and its www alias is accepted, with source links normalized to the redirected hostname. Redirect verification checks public DNS addresses and pins the connection to a verified address. External sites, other subdomains, account/cart/checkout/login paths and query-string URLs are excluded. Robots and content-use restrictions apply; bot protection may prevent importing a site. This is a bounded crawl, not a guarantee of complete website coverage. Existing urls never silently opt into crawling.
Public website text and document IDs are cached as unencrypted JSON in Rails. Source URLs and crawl identifiers remain encrypted. Text is chunked into an isolated turbopuffer namespace per receptionist, separate from private call/contact search. Up to 100,000 characters per page and 4 MiB of cached page data are accepted. Only changed content is re-embedded. A complete index is published atomically; partial writes are never searchable. Pages confirmed as HTTP 404/410 or disallowed are removed. Missing crawl records are not proof of deletion. Temporary errors preserve the last successful index. Removing the website revokes retrieval immediately and queues external index deletion. Changing the website does not serve the old site's index while the new import is pending.
Successful imports refresh after 24 hours, checked every 15 minutes. Failures retry with exponential backoff from 15 minutes to 24 hours; imports time out locally after 30 minutes. Use the knowledge-index endpoints to check status or request a refresh.
Agents published with a website expose phone_inc_knowledge_search, a read-only tool accepting only a query of 1–500 characters. The authenticated session determines the company and receptionist. It returns at most three source-linked passages within an 8 KiB result budget, or an explicit unavailable response on failure. The current index is read on every search, so successful background refreshes reach active calls without republishing voice agents. Removing or changing the website revokes the old source even on active calls. Searches use the existing encrypted audit trail. Retrieved content and search relevance are not authority; agents must not obey page instructions or invent answers from irrelevant results. Opening hours still come from the live business-hours tool.
Operators must configure CLOUDFLARE_BROWSER_RUN_ACCOUNT_ID, CLOUDFLARE_BROWSER_RUN_API_TOKEN (Browser Run Edit permission), and the existing TURBOPUFFER_API_KEY/region configuration in the backend and job worker. No customer credentials or browser cookies are forwarded. Cloudflare retains crawl results for 14 days; indexed public website text is also sent to turbopuffer's configured embedding provider. Review these processors and content permissions before enabling website imports. Crawling, embeddings and retrieval incur provider costs.
Messages and transfers
Enable conversational message taking with configuration.message_taking. It defaults to disabled:
{
"enabled": true,
"fields": ["name", "email", "company_name", "reference", "callback_time"]
}
The agent asks briefly for selected fields, then saves a Note without requiring a full readback or explicit confirmation. Callers may decline or finish without all details; selected but unavailable values are stored as null, and unselected fields are omitted. Email uncertainty never blocks a save: the agent may ask one short clarification but does not repeatedly validate or spell back an address. Spacing in valid email addresses is normalized; uncertain addresses remain in the Note's details for the team but do not populate a contact's email. reference is an order, booking, or customer reference; callback_time is the caller's preferred time as stated, not a promise. The incoming caller number is used automatically, with no callback-number question. Name, syntactically valid email and company fill only blank contact fields in the same company.
The action is labeled Take a note. Notes appear in the inbox and Notes API, without a recording. Each employee has a separate Note email notification setting for each business number, enabled by default and independent of voicemail email preferences. Notes also support inbox activity and webhooks; no additional delivery channels are introduced.
Disabling the tool revokes new saves on active calls too. Saving a Note does not end the conversation or change the number's whole-call recording settings. Updated conversation instructions apply when a receptionist is saved and its agent version is republished; existing calls keep their captured version.
Phone.inc supplies the selected employees' names alongside their IDs and routing descriptions, so callers can ask for a person by first or full name. The agent is instructed to clarify ambiguous names. Names come from employee records, not configuration arguments, and are captured when publishing an agent version. Reselecting a receptionist only reuses its published version; changing transfer targets or their descriptions publishes a refreshed directory.
The agent can check live availability for those selected employees: available, on another call, do not disturb, ringing, offline, or unknown. It is instructed to check when a caller asks for someone and before offering a transfer, explain unavailability, and offer an alternative or a message. It does not receive details about other callers. AI transfers respect DND and recheck availability after preparing the private introduction, immediately before requesting ringing. Deliberate human-to-human transfers retain their existing DND policy.
Warm transfers contact only selected employees, never repeat a target, and return to the caller between attempts. When transfers are exhausted, the receptionist can offer a written message only if message taking is enabled. Department transfers join a shared queue rather than guaranteeing an answer. Ordinary call-flow voicemail remains a separate recording action.
Call behavior and limits
Each AI session is limited to ten minutes. Calls exceeding that limit use the existing fallback. Media or connection failure runs no-answer once; an AI fallback cannot loop back to itself. Phone.inc does not impose a per-company daily start limit, simultaneous AI call limit or per-call tool-operation cap. Fallback and recording settings remain number-specific. See the customer setup guide for the dashboard workflow.
Every newly published agent includes phone_inc_business_hours. This read-only tool takes no model-supplied arguments and reads the business number from the authenticated call session, so one receptionist can serve numbers with different hours. It returns the number's public ID, timezone, current local timestamp, whether hours are configured, the current open/closed result and a seven-day schedule. Closing time 24:00 means the end of the day. Without any configured hours, open-now is null (unknown), not closed. Configured schedules treat missing weekdays as closed. Hours are live on each invocation and use the same tenant isolation and tool audit path. Opening hours take priority over saved website hours; they are not employee availability and do not include holiday exceptions. Older published agents gain the tool when republished by saving changed receptionist settings.
Newly published agents also include phone_inc_last_conversation. It accepts no arguments: Rails fixes the company and exact incoming caller number from the authenticated session. It returns the latest earlier answered call that is now completed, across the company's business numbers, including outbound callbacks. The result contains the call ID, start time, direction, recorded employee participants and saved summary, not transcripts, recordings, voicemail or SMS. Missed and active calls are excluded. Failed transfer targets are not added as participants. A missing summary is null; the tool does not substitute an older conversation. Summaries are stripped of HTML and limited to 2,000 characters, with summary_truncated indicating incomplete text. An unidentified caller returns unavailable; no matching call returns not_found.
This limited history lookup uses caller ID without verifying identity. Spoofed, shared or reassigned numbers can therefore expose another person's previous summary to the AI provider. The agent is instructed to use it when the caller refers to their last call, treat it as untrusted data, and not recite private details unprompted; these instructions are not an identity-verification boundary. Historical participants do not grant transfer permission. Lookups use the existing independently retained encrypted tool audit trail. Saving a receptionist republishes its agent with the new tool; existing calls keep their version. This is an internal live-call tool, not a new public API or MCP endpoint; authenticated account tools already expose calls separately.
AI audio and transcription follow the number's existing recording and retention settings. ElevenLabs conversation recording and transcript retention are disabled. Tool audits are retained independently of conversational recording and are returned as ai_tools on the call model. The dashboard shows friendly action cards with optional technical details, placed approximately in the transcript rather than aligned to exact speech timestamps.
Integration access
Receptionists cannot fetch caller context from integrations, look up live orders or bookings, execute remote MCP tools, or schedule callbacks. A collected callback time is a preference, not an appointment or promise.
Generic remote MCP-server connections are no longer supported. The former nested mcp_servers endpoints and their four management tools have been removed. Saved legacy grants are excluded from receptionist configuration responses and discarded on the next save. Remote MCP execution is denied even for previously published agents, active call snapshots and cached tool results; actions already dispatched before rollout cannot be undone. Saving a receptionist republishes its agent without remote MCP tools. Historical call and revision records are preserved.
Receptionist integrations are also unavailable. Non-empty configuration.integrations grants are rejected; legacy empty arrays are accepted but omitted from responses. Saved grants cannot fetch caller context or execute integration tools, including on existing calls or through cached results. Saving republishes the agent without integration tools. Company-wide integrations and Phone.inc's authenticated public MCP API remain unchanged.