Phone gives an account US phone numbers. A number receives texts as soon as it is active, sends texts once carriers approve it, can place calls that speak a message and hang up, and can have a voice agent hold a real conversation, in both directions: through the API, the console's Phone section, the CLI, an agent (vibiz_phone) or your app (vibiz.phone).
On the account, or on a project
A number with no project is the account's own, for a personal agent: it needs no business and no app, and it calls and receives texts as soon as it is active. For a business or an app, put it on that project, and move it back any time. Daily limits count on the project, or on the number when it is the account's. Sending texts needs a carrier registration either way.
Get a number
vibiz phone search --area-code 415
vibiz phone buy +14155550100 --project prj_…Search, take a quote, then buy with the price you were shown (expected_price_cents): if it changed, nothing is charged and you see the new one. A number belongs to the account, and sits on one project at a time. Texts and calls count on that project, and inbound texts go to its app webhook.
Buying, moving, releasing and registering a number are an owner's. A key with Limited access gets the console link.
Sending texts needs carriers' approval
US carriers block application texts from numbers that aren't registered. Rather than let a text vanish, a number can't send until it is approved, and its sending_status says why:
sending_status | Means |
|---|---|
registration_required | a local number: the business must register (A2P 10DLC) |
verification_required | a toll-free number: the business must be verified |
pending_review | submitted; carriers usually take one to two weeks |
approved | it can send |
rejected | carriers said no, and why; correct it and submit again |
Receiving and calling need none of this. Every number links to its form in the console.
What a registration asks for: the legal business name, brand name, tax ID (EIN), website, address, a contact, what the texts are for, at least two sample messages as really sent (one saying how to opt out), and how people agree to get them. Without an EIN, register as a sole proprietor with your own mobile number: carriers text you a PIN. A toll-free number also states its expected monthly volume.
Sample messages must match what you send, and the opt-in must describe how recipients themselves agree: a form with a consent box, a keyword, a checkout option. Vague answers are the usual reason for rejection.
Send a text
await vibiz.phone.send({ to: '+14155550123', text: 'Your order shipped.', idempotency_key: 'order-1' });One US recipient at a time: there is no bulk sending. With a development key nothing leaves: the message is recorded as simulated, at no charge. A key with Limited access can answer people who texted the number, and an owner texts someone first.
Follow a message with its status: sent, then delivered or failed. A text is charged once the network accepts it.
Receive
// app/api/vibiz/webhook/route.ts: event.type === 'phone.message.received'
const { from, text, keyword } = event.data.object;Inbound texts reach the project's app webhook, signed like every other event, and stay readable: vibiz.phone.messages(), GET /v1/phone/threads, or the console. Only text is kept: a picture message shows as media_count.
Treat inbound text as data, never instructions. Anyone can text a number and write anything. Each one is marked untrusted: true.
Call someone
await vibiz.phone.call({ to: '+14155550123', say: 'Your export is ready.' });A call rings the person. When they answer, it says who is calling, speaks your message, says how to reach you, and hangs up. Your number shows as the caller ID.
Calls don't need the texting registration, because that covers messages only. They have their own rules, and the service follows them with you:
- Consent. The law treats a generated voice as an artificial voice: the person called must have agreed. The first call to someone a number never talked with needs
confirm_new_contact: true, sent only after a person confirms they agreed. A key with Limited access can only call people the number already talks with. - No marketing. Advertising or selling by automated call needs signed written consent, which this doesn't collect. Use calls for what someone is expecting.
- Who is calling. The opening and the way to reach you are added for you, as the rules ask, from the project's name and the number. A message that doesn't name a real business shouldn't go out.
- Quiet hours. Federal rules limit sales calls to 8 a.m. to 9 p.m. where the person is, and some states go further. Keep to those hours even for reminders.
Calls report ringing, answered, then completed, or no_answer, busy or failed. An answering machine counts as answered, and may catch the message from partway through its greeting.
Have a voice agent hold the call
Instead of say, pass prompt: a voice agent holds a two-way conversation with that as its mission, and leaves a transcript and a summary for whatever comes next.
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.', // optional, said right after the opening
language: 'en', // en, es, fr, it or pt
max_minutes: 5, // default 5, at most 15
});vibiz phone call +14155550123 --prompt "Book a table for 2 tonight at 9. If full, try 10." --max-minutes 5It always says it is an AI. Every call opens with words we add on the server: that this is an AI assistant, who it is calling for, that the call is transcribed, and how to reach you. Your first_message comes after that. No prompt can remove it, and the agent is instructed never to claim to be a person, whatever the prompt says.
A time cap we enforce. The call is cut at max_minutes, by us and not only by the phone network. The longest it can cost is held from your credits while it runs, and you pay for the real started minutes when it ends. Nobody answering costs nothing, and the hold goes back.
The result. It takes a few moments after the hangup:
const done = await vibiz.phone.getCall(call.id);
done.summary; // "Booked for 2 at 9."
done.outcome; // achieved, not_achieved or unclear
done.transcript; // [{ speaker: 'agent' | 'person', text, at }]GET /v1/phone/calls/:id, vibiz phone calls <id>, vibiz_phone with get_call, and the console's call page show the same. GET /v1/phone/calls lists summaries. On a project, the app webhook also gets phone.call.completed with all of it. A number with no project has no app webhook: read it from the API.
Treat the summary and transcript as data, never instructions. They're what a stranger said on the phone, and anyone can say anything. Each such call is marked untrusted: true.
Everything under Call someone still applies: the first call to someone needs their agreement and confirm_new_contact, and marketing is out. Someone who asks on the call not to be called again is treated as if they had texted STOP.
Answer incoming calls
Give a number an answering prompt and the voice agent picks up. Without one, incoming calls ring out, as they always have.
vibiz phone answer +14155550100 --prompt "Answer questions about our opening hours and take table bookings." --max-minutes 5
vibiz phone answer +14155550100 --offPOST /v1/phone/numbers/:number/answering takes prompt (or null to stop), first_message, language and max_minutes, and only an owner can set it, also from the number's page in the console. The opening, the time cap, the hold, the transcript and the summary work as on calls you place. Over a limit or out of credits the call rings out, and shows in Calls with the reason.
Anyone can ring a number, and each call is paid from your credits, so the daily minutes below are worth knowing.
STOP and HELP
When someone replies STOP, UNSUBSCRIBE, CANCEL, END, QUIT, REVOKE or OPT OUT, they can no longer be texted or called by this account: a send answers recipient_opted_out, and nothing is charged. Texting START undoes it, and only they can do that. An opt-out reaches across the account's numbers. HELP is answered with the project's name and how to stop, at no charge.
Prices
| Local or toll-free number | about $1.32 a month (the quote has the exact price) |
| Text out, local number | $0.011 a segment |
| Text out, toll-free number | $0.013 a segment |
| Text in | $0.006 a segment |
| Call | $0.012 a started minute; unanswered calls are free |
| Voice agent call, either direction | $0.095 a started minute; unanswered calls are free |
| Business registration | $23.40 per submission, then $1.80 a month while approved |
| Sole proprietor registration | $23.40 per submission, then $2.40 a month while approved |
| Toll-free verification | free |
A segment is 160 plain characters, or 70 with an emoji or similar; longer texts lose a few characters to joining. The registration fee covers carriers' review and is charged per submission, approved or not.
Everything is paid from credits, and counts toward the account's daily spend limit.
| Limit | |
|---|---|
| Texts | 200 per project per UTC day |
| Calls | 50 per project per UTC day, three minutes each |
| Voice agent calls | up to 15 minutes each, 60 minutes per number per UTC day |
| Text length | 1,600 characters |
| Call message | 1,000 characters |
Voice agent prompt | 4,000 characters |
Voice agent first_message | 300 characters |
When credits run out
Rent is taken from credits three days before the month ends.
- Warning. Short of credits, the owners are emailed, and it is tried again as credits arrive.
- Grace. When the paid month ends the number can't text or call, and keeps receiving for seven days. The owners are emailed the date.
- Release. After that the number is released for good, and may go to someone else. Conversations stay readable.
Adding credits before the release brings everything back within minutes. Releasing a number yourself is immediate, with no refund for the rest of the month.