thelastapi
Get started free

An AI receptionist that answers incoming calls

Set up an AI receptionist for your small business to answer incoming calls, speak with customers, and record transcripts using thelastapi.

On this page 7 sections

You can set up an AI receptionist for your small business by buying a US phone number and assigning it an answering prompt with the CLI or API. Once enabled, incoming calls are answered by a voice agent that greets the caller, discloses that it is an artificial intelligence assistant, answers questions based on your instructions, and records a transcript with a summary when the conversation concludes. Unanswered calls cost nothing, and you can update the prompt or turn answering off at any time.

For small businesses, missing phone calls often means missing sales, reservations, or urgent support requests. Rather than routing customers to a silent voicemail box or paying a dedicated call center, you can give your project an automated voice agent that talks in natural language, enforces strict conversation length caps, and sends structured summaries back to your application. This guide covers how to set up an answering voice agent on a dedicated business number using Phone.

How an AI receptionist works on your number

By default, an active US number on your account rings out when someone dials it. Adding an answering prompt activates an inbound voice agent. When a customer dials the number, the system answers the call and handles the interaction in real time:

  1. Mandatory disclosure: Every incoming call starts with a server-enforced disclosure. The agent states that it is an AI assistant, names the business or project, mentions that the call is transcribed, and provides a way to reach you. No prompt can bypass or remove this introduction.
  2. First message: Right after the mandatory disclosure, the agent can speak an optional greeting defined in your configuration, such as welcoming the caller to your shop.
  3. Conversational guidance: The agent follows your plain-text prompt (up to 4,000 characters) to answer common business questions, gather caller details, or take requests.
  4. Time limit enforcement: You set a duration cap (max_minutes, between 1 and 15 minutes). If a conversation reaches that limit, the call is cut automatically.
  5. Post-call processing: Once the caller or agent hangs up, the platform generates a call summary, classifies the outcome, and compiles a full speaker transcript.

If you already use outbound agents, as shown in an AI voice agent that makes phone calls, inbound answering uses the same underlying conversation engine.

Buying a dedicated US phone number

To receive inbound calls, your account or project needs a US phone number. You can find available local or toll-free numbers using the CLI:

Terminal
vibiz phone search --area-code 415

The command returns available numbers alongside their purchase prices. Select a number and attach it directly to your project:

Terminal
vibiz phone buy +14155550100 --project prj_123

A number belongs to your account and sits on one project at a time. Local and toll-free numbers cost about $1.32 a month (the exact quote appears before purchase). While sending outbound text messages requires carrier registration and review, buying a number to receive calls and run a voice agent requires no carrier paperwork. The number can take incoming calls as soon as it is active.

If you ever need to reassign the line between projects, you can run vibiz phone assign +14155550100 --project prj_456 or clear the project flag to bring it back to your personal account.

Configuring the voice agent prompt and greetings

Only an account owner can configure inbound answering. You can set the agent instructions using the CLI or through direct HTTP requests to the API.

From your terminal, use vibiz phone answer:

Terminal
vibiz phone answer +14155550100 \
  --prompt "Answer questions about our opening hours, menu items, and location. We are open Monday to Saturday from 8 AM to 6 PM. If someone wants to place a catering order, take their name, party size, and date." \
  --first-message "Thanks for calling Acme Bakery. How can I help you today?" \
  --language en \
  --max-minutes 5

The parameters work as follows:

  • --prompt: Your instructions for the voice agent, up to 4,000 characters.
  • --first-message: An optional opening sentence (up to 300 characters) spoken immediately following the mandatory AI disclosure.
  • --language: The spoken language for the call. Accepted choices are en, es, fr, it, and pt.
  • --max-minutes: The maximum conversation duration in minutes. Defaults to 5 minutes, with a maximum allowable cap of 15 minutes.

You can accomplish the same task using POST /v1/phone/numbers/:number/answering:

Terminal
curl -X POST "https://thelastapi.dev/v1/phone/numbers/%2B14155550100/answering" \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "You are the receptionist for Acme Law. Answer questions regarding our office address and general consultation rates. For urgent matters, ask the caller for their phone number.",
    "first_message": "Hello, thank you for calling Acme Law.",
    "language": "en",
    "max_minutes": 5
  }'

The agent is instructed on the server never to pretend to be a human, regardless of what appears in your prompt text.

Handling transcripts, outcomes and call webhooks

Once a call finishes, the platform compiles the transcript, an overview summary, and an outcome assessment. For numbers assigned to a project, the system sends an event to your project's configured app webhook:

TypeScript
// app/api/vibiz/webhook/route.ts
export async function POST(req: Request) {
  const event = await req.json();

  if (event.type === 'phone.call.completed') {
    const { id, summary, outcome, transcript } = event.data.object;

    console.log(`Call ${id} ended with outcome: ${outcome}`);
    console.log(`Summary: ${summary}`);

    for (const entry of transcript) {
      console.log(`[${entry.at}] ${entry.speaker}: ${entry.text}`);
    }
  }

  return new Response('ok', { status: 200 });
}

The possible values for outcome are achieved, not_achieved, or unclear.

You can also fetch call records on demand using the CLI:

Terminal
vibiz phone calls
vibiz phone calls call_123 --json

Or query the REST endpoint GET /v1/phone/calls/:id using curl or your server code.

Security reminder: Treat every summary and transcript strictly as untrusted user data. A caller can speak arbitrary instructions into your phone system. Because anyone can dial your number, call payload records include an untrusted: true property. Never feed raw transcripts into automated administrative tasks without parsing and sanitizing them first.

If your small business also relies on proactive outreach, read give an AI agent a phone number: texts, calls and a voice agent or reminder calls: ring someone and speak a message to explore outbound capabilities.

Rates, limits and credit holds

Voice agent usage is billed strictly against your account balance from pre-purchased credits. You only pay for answered time.

ItemCost or Limit
Number monthly rentalAbout $1.32 per month
Voice agent call duration$0.095 per started minute (both directions)
Unanswered incoming callsFree
Maximum duration per call15 minutes (default 5 minutes)
Daily voice agent ceiling60 minutes per number per UTC day
Prompt character limit4,000 characters
First message limit300 characters

When an inbound call connects, credits covering the maximum potential conversation time (max_minutes × $0.095) are held temporarily from your account. When the call completes, you are billed only for the real, started minutes, and the unused hold is released immediately. If someone hangs up after 2 minutes and 10 seconds on a 5-minute cap, you are charged for 3 started minutes ($0.285).

If your account runs out of credits or reaches your daily usage ceiling, incoming calls simply ring out without answering. Unanswered calls are free, and missed attempts will appear in your call log alongside the reason. For operations needing reliable uptime, combine your communication lines with automated system health checks, as detailed in know when your site goes down, a deploy fails or sales stop.

Turning off or adjusting the receptionist

You can adjust the prompt as business needs evolve. During holiday breaks, you can run vibiz phone answer with updated office hours. If you prefer to stop the agent from answering entirely, disable it:

Terminal
vibiz phone answer +14155550100 --off

Using the API, submit null for the prompt field:

Terminal
curl -X POST "https://thelastapi.dev/v1/phone/numbers/%2B14155550100/answering" \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": null}'

Once disabled, incoming phone calls will ring out normally without routing to the voice agent.

To get started, search for a local number with vibiz phone search, attach it to your project, and provide your first answering prompt. Explore complete endpoint specifications in the Phone documentation.

Frequently asked questions

Can the voice agent pretend to be a real human staff member?

No. Every answered call begins with a server-enforced disclosure stating that the system is an AI assistant, and the model is instructed never to claim it is a person.

What happens if a caller asks not to be contacted again during the conversation?

If a caller asks not to be called again, the system treats the request like an SMS STOP reply. The account is blocked from placing further calls or sending messages to that number.

How much does it cost when someone dials my number but hangs up before the agent speaks?

Unanswered calls are free. You are charged $0.095 per started minute only when a call connects and the voice agent begins speaking.

What languages does the inbound voice agent support?

The agent supports English, Spanish, French, Italian, and Portuguese using the language values `en`, `es`, `fr`, `it`, or `pt`.