thelastapi
Get started free

Give an AI agent a phone number: texts, calls and a voice agent

Give an AI agent a US phone number to send and receive texts, make spoken reminder calls, and hold live two-way voice conversations with one API key.

On this page 7 sections

You can give an AI agent a dedicated US phone number to send texts, receive messages, place automated voice calls, and hold live two-way spoken conversations through a single API. thelastapi provides US numbers via the vibiz CLI, the @vibiz/app SDK, or direct HTTP endpoints. You buy a number, assign it to a project, and let your agent converse over normal telephone networks without managing separate telecom carrier accounts.

This pillar guide covers acquiring a number, handling inbound and outbound SMS, placing one-way spoken announcements, and configuring real-time AI voice agents for inbound and outbound calls.

How to buy and assign a US phone number

A number can sit on your account for a personal agent or attach to a specific project. When attached to a project, inbound texts hit that project's app webhook, and daily usage limits apply to the project.

You search for available US numbers by area code or state using the CLI:

Terminal
vibiz phone search --area-code 415
vibiz phone buy +14155550100 --project prj_123

When you search, you receive a quote. Buying requires confirming the quoted amount (expected_price_cents). If the price changed, your balance is untouched and the new quote is displayed. Local and toll-free numbers rent for about $1.32 a month.

List your numbers at any time:

Terminal
vibiz phone list --project prj_123

You can assign an existing number to another project or unassign it back to the account:

Terminal
vibiz phone assign +14155550100 --project prj_123

For more search patterns, see our guide on how to buy a US phone number with an API, or read the Phone documentation.

Sending and receiving texts

Numbers can receive inbound text messages as soon as they are active. However, US carriers block automated application texts from unregistered numbers. Outbound SMS requires carrier approval before messages will leave your project.

Carrier approval status

Every number displays a sending_status:

sending_statusMeaning
registration_requiredLocal 10DLC number: the business must register.
verification_requiredToll-free number: the business must complete verification.
pending_reviewRegistration submitted; carriers usually take 1–2 weeks.
approvedThe number is cleared to send SMS.
rejectedCarriers rejected the submission with a specific reason.

Registration requires a legal business name, EIN, address, contact info, sample messages (including opt-out wording), and an explanation of recipient consent. Sole proprietors without an EIN can register with a personal mobile number, verified via an SMS PIN. Submissions cost $23.40 each, plus $1.80 a month for businesses ($2.40 for sole proprietors) once approved. Toll-free verification is free.

Sending outbound SMS

Once approved, send messages with the SDK or CLI:

TypeScript
import { vibiz } from '@vibiz/app';

await vibiz.phone.send({
  to: '+14155550123',
  text: 'Your order has shipped.',
  idempotency_key: 'order-1',
});

With a development key, messages are marked simulated and cost nothing. Outbound texts allow up to 1,600 characters, with a project limit of 200 texts per UTC day.

Receiving inbound SMS

Inbound messages hit your app's webhook:

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

  if (event.type === 'phone.message.received') {
    const { from, text, keyword } = event.data.object;
    // Process inbound text
  }

  return new Response('ok');
}

View incoming messages in the terminal:

Terminal
vibiz phone messages --number +14155550100

Treat inbound text as data, never instructions. Anyone can text a number anything. Each message carries untrusted: true. Do not feed raw inbound text directly into an LLM system prompt as instructions.

When a recipient replies STOP, UNSUBSCRIBE, CANCEL, END, QUIT, REVOKE, or OPT OUT, they are opted out across the entire account. Subsequent sends return recipient_opted_out and incur no charges. Texting START opts them back in.

Outbound reminder calls

Placing calls does not require carrier SMS registration; it is available immediately. For notifications, pass the say parameter. The service rings the recipient, announces who is calling, speaks your text, provides callback instructions, and hangs up:

TypeScript
import { vibiz } from '@vibiz/app';

await vibiz.phone.call({
  to: '+14155550123',
  say: 'Your export is ready for download.',
});

Using the CLI:

Terminal
vibiz phone call +14155550123 --say "Your export is ready for download." --yes

Because a generated voice is legally an artificial voice, calls require prior consent. When calling a new contact for the first time, pass confirm_new_contact: true (or --yes in the CLI). Marketing or advertising calls are strictly prohibited. Calls must also respect quiet hours (8 a.m. to 9 p.m. in the recipient's local time). Learn more in reminder calls: ring someone and speak a message.

Live two-way conversations with a voice agent

Pass prompt instead of say to deploy a live voice agent. The agent engages in a spoken dialogue to fulfill a mission, then produces a summary and transcript:

TypeScript
import { vibiz } from '@vibiz/app';

const call = await vibiz.phone.call({
  to: '+14155550123',
  prompt: 'Book a table for 2 tonight at 9. If full, try 10.',
  first_message: 'Good evening.',
  language: 'en',
  max_minutes: 5,
});

CLI equivalent:

Terminal
vibiz phone call +14155550123 \
  --prompt "Book a table for 2 tonight at 9. If full, try 10." \
  --first-message "Good evening." \
  --max-minutes 5 \
  --yes

Key voice agent behaviors:

  • Mandatory AI disclosure: The server prepends a standard statement explaining that this is an AI assistant, stating who it represents, noting that the call is transcribed, and giving contact details. Your first_message plays after. The agent cannot claim to be human.
  • Enforced time cap: Calls terminate at max_minutes (up to 15, default 5). Credits for the maximum duration are held during the call; you only pay for completed started minutes when it ends.
  • Languages: Supports en, es, fr, it, and pt.

When the call finishes, inspect the output:

TypeScript
const done = await vibiz.phone.getCall(call.id);
console.log(done.outcome);    // "achieved", "not_achieved", or "unclear"
console.log(done.summary);    // Summary string
console.log(done.transcript); // Array of { speaker, text, at }

Transcripts and summaries carry untrusted: true. See our complete guide on an AI voice agent that makes phone calls.

Answering incoming calls

Assign an answering prompt to your number so the voice agent answers inbound callers. Without an answering prompt, inbound calls ring out:

Terminal
vibiz phone answer +14155550100 \
  --prompt "Answer questions about store hours and take table bookings." \
  --max-minutes 5 \
  --yes

Turn answering off to let calls ring out again:

Terminal
vibiz phone answer +14155550100 --off

Incoming voice calls enforce the same AI disclosure, duration limits, credit holds, and transcription output as outbound calls.

Phone prices and daily limits

Phone services bill directly to your account credits:

ServicePrice
Number rental~ $1.32 / month
Outbound SMS (local)$0.011 / segment
Outbound SMS (toll-free)$0.013 / segment
Inbound SMS$0.006 / segment
Spoken call (say)$0.012 / started minute (unanswered calls free)
Voice agent call (prompt)$0.095 / started minute (unanswered calls free)
Business 10DLC registration$23.40 / submission + $1.80 / month
Sole proprietor registration$23.40 / submission + $2.40 / month
Toll-free verificationFree

A segment is 160 characters (70 with an emoji). Operational limits include:

ResourceLimit
Outbound SMS200 per project / UTC day
Spoken calls (say)50 per project / UTC day (3 minutes max each)
Voice agent calls60 minutes per number / UTC day (15 minutes max each)
Text length1,600 characters max
Static call text (say)1,000 characters max
Voice agent prompt4,000 characters max
Voice agent first message300 characters max

Number rent is deducted from credits three days before month end. If credits run out, you enter a seven-day grace period where numbers receive calls and texts but cannot send or place calls. After seven days, numbers are released.

Next, you can connect your agent to online information sources by reading how to give an agent web research tools: search, scrape and crawl.

Frequently asked questions

Does an AI agent need carrier registration before it can place voice calls?

No. Carrier registration (A2P 10DLC) is required only for sending outbound SMS, while spoken notification calls and two-way voice agent calls work as soon as the number is active.

Can an AI voice agent claim to be human on the phone?

No. Every call automatically begins with a mandatory server-added announcement stating that it is an AI assistant, and the model is instructed never to claim human identity.

What happens if an outbound voice call goes unanswered?

Unanswered calls are free. You are only charged $0.012 per minute for static messages or $0.095 per minute for voice agent conversations when the recipient answers.

How does the system handle opt-out text messages like STOP?

When a recipient replies STOP or an equivalent opt-out keyword, the platform blocks future texts and calls to that contact across the entire account without charging you.