Reminder calls: ring someone and speak a message
Place automated reminder calls with an API using thelastapi to ring US numbers, speak text notifications, and handle call status cleanly.
On this page 7 sections
You can place automated reminder calls with an API by calling vibiz.phone.call() with a phone number and your notification text in the say parameter. thelastapi dials the recipient, announces your project name, speaks your message using a synthetic voice, tells the recipient how to contact you, and hangs up. Unlike text messages, voice calls require no carrier campaign registrations, and unanswered calls are never charged.
This guide walks through getting a number, triggering reminder calls from Node.js or the terminal, managing consent rules, and tracking call status.
How automated reminder calls work
A reminder call is a lightweight, one-way phone notification. When your application triggers a call, the service dials the recipient from your project's phone number. When the person answers, the call follows an automated sequence:
- Identification. The call states who is calling using your project's name.
- The message. It speaks the text you provided in the
sayparameter. - Contact info. It states how the recipient can contact you using your phone number.
- Hang up. The call ends automatically once the message finishes.
If an answering machine or voicemail picks up, the system treats the call as answered. The message begins playing when audio is detected, which may catch the reminder partway through the machine's greeting. If the line is busy or rings out without an answer, the call ends with no charge to your account.
Calls use your project's number as the caller ID, so recipients see a consistent, familiar number on their phone screens.
Getting a number and placing a call
To place calls, you need an active US phone number on your project. You can search for and buy a number using the CLI or the console. Full details on acquiring numbers are covered in Buy a US phone number with an API.
# Find a number in your preferred area code
vibiz phone search --area-code 415
# Purchase the number and attach it to your project
vibiz phone buy +14155550100 --project prj_123 --yesOnce the number is active, you can place a reminder call immediately from the terminal:
vibiz phone call +14155550123 \
--say "Hello. This is a reminder that your dental cleaning is tomorrow at 10 AM." \
--yesThe --yes flag confirms that the recipient has agreed to receive calls from your organization.
Calling from your application
In your codebase, use @vibiz/app to dispatch calls. The library reads your project configuration automatically:
import { vibiz } from '@vibiz/app';
async function sendAppointmentReminder(phoneNumber: string, appointmentTime: string) {
const call = await vibiz.phone.call({
to: phoneNumber,
say: `Hello from Acme Clinic. This is a reminder of your appointment scheduled for ${appointmentTime}.`,
});
console.log(`Call initiated with ID: ${call.id}`);
return call;
}If you are using direct HTTP calls instead of the SDK, you can post to the API endpoint:
curl -X POST "https://thelastapi.dev/v1/phone/calls" \
-H "Authorization: Bearer $VIBIZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+14155550123",
"say": "Your package is ready for pickup at the front desk."
}'For more details on call management, review the Phone documentation.
Consent, quiet hours, and opt-outs
Telephony regulations treat computer-generated voices as artificial voices. Because automated calls interrupt people directly, strict rules apply to how and when you place them.
Prior consent and the first call
You must have the recipient's consent before placing an automated call. The service enforces this directly in the API:
- Confirming new contacts. When placing a call to a phone number your account has never interacted with, you must include
confirm_new_contact: truein your API payload (or pass--yesin the CLI). You should only pass this flag after confirming the person agreed to receive notifications. - Limited keys. An API key with Limited access can only trigger calls to recipients your account has previously contacted. Only owner-level keys can place calls to brand-new numbers.
No marketing calls
Automated reminder calls are intended for transactional notices: appointments, account alerts, delivery updates, and verification messages. Under federal rules, advertising, promotional offers, or sales pitches delivered via automated voices require signed written consent, which the API does not collect. Keep messages strictly informational.
Respecting quiet hours
Federal regulations restrict automated calls to the hours between 8:00 AM and 9:00 PM in the recipient's local time zone. Several states enforce narrower windows. Schedule your background jobs to respect these windows, even for urgent reminder notices.
Automatic opt-out handling
Recipients have the right to revoke consent at any time. If someone sends an inbound text message containing words like STOP, UNSUBSCRIBE, CANCEL, END, QUIT, REVOKE, or OPT OUT, thelastapi records the revocation across your entire account:
- Subsequent calls or text attempts to that recipient will fail and return
recipient_opted_out. - Your account is not charged for attempted calls to opted-out numbers.
- A recipient can restore communications only by texting
STARTback to your number.
Tracking call status and results
Calls update through distinct lifecycle states:
| Status | What it means |
|---|---|
ringing | The carrier network is ringing the recipient's device. |
answered | A person or an answering machine picked up the call. |
completed | The spoken message played in full, and the call disconnected. |
no_answer | The line rang until timeout without an answer. Unbilled. |
busy | The destination line returned a busy signal. Unbilled. |
failed | The carrier was unable to route or connect the call. Unbilled. |
To inspect recent calls from your terminal, run:
# List recent calls and their high-level statuses
vibiz phone calls
# Inspect a specific call record
vibiz phone calls call_123 --jsonOn projects with configured webhooks, your application server receives signed events like phone.call.completed when a call finishes, letting you log delivery status directly into your database.
Spoken reminders vs. conversational voice agents
A simple reminder call uses say to speak a one-directional message. If your workflow requires the recipient to interact, confirm, reschedule, or answer questions, you can run a two-way AI voice agent instead by passing prompt rather than say.
| Feature | Spoken message (say) | Voice agent (prompt) |
|---|---|---|
| Interaction | One-way notification | Two-way dynamic conversation |
| Primary use | Reminders, passcodes, alerts | Booking, rescheduling, triage |
| Duration cap | 3 minutes | Up to 15 minutes |
| Opening announcement | Names project and phone number | Names project, states it is an AI, notes transcription |
| Result data | Delivery status | Full transcript, call summary, outcome |
| Price | $0.012 per started minute | $0.095 per started minute |
To learn how to implement two-way conversations, see our guides on An AI voice agent that makes phone calls and how to Give an AI agent a phone number: texts, calls and a voice agent.
Prices and daily limits
Voice operations are billed directly against your project credits:
- US Phone Number: About $1.32 a month (local or toll-free).
- Spoken Calls (
say): $0.012 per started minute. Unanswered, busy, or failed calls are completely free. - Voice Agent Calls (
prompt): $0.095 per started minute.
Standard projects have the following safeguards:
- Volume ceiling: 50 calls per project per UTC day.
- Duration limit: 3 minutes maximum per spoken call.
- Message length: Up to 1,000 characters per message in the
sayparameter.
Because carrier message registrations (A2P 10DLC) apply strictly to SMS, voice reminder calls are functional immediately after purchasing your number.
To set up your first reminder pipeline, create your account at thelastapi.dev/start, claim your API key, search for a local number, and test a reminder call directly from your terminal.
Frequently asked questions
Do I need an A2P 10DLC registration to place automated reminder calls?
No. Carrier 10DLC registration and verification rules apply only to text messages. Voice calling works immediately once your phone number is purchased and active.
What happens if the person does not answer the reminder call?
If a call ends with `no_answer`, `busy`, or `failed`, the call terminates and you are charged nothing. You are only billed for calls that are answered by a person or a voicemail machine.
Can I use automated calls to broadcast sales offers or marketing messages?
No. Automated calls using synthetic voices are restricted to informational and transactional updates where the recipient has given consent. Promotional and sales calls require signed written consent, which thelastapi does not collect.
How long can a reminder message be?
The text string passed to the `say` parameter can contain up to 1,000 characters, and each individual call is capped at three minutes in length.