thelastapi
Get started free

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:

  1. Identification. The call states who is calling using your project's name.
  2. The message. It speaks the text you provided in the say parameter.
  3. Contact info. It states how the recipient can contact you using your phone number.
  4. 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.

Terminal
# 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 --yes

Once the number is active, you can place a reminder call immediately from the terminal:

Terminal
vibiz phone call +14155550123 \
  --say "Hello. This is a reminder that your dental cleaning is tomorrow at 10 AM." \
  --yes

The --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:

TypeScript
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:

Terminal
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.

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.

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: true in your API payload (or pass --yes in 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 START back to your number.

Tracking call status and results

Calls update through distinct lifecycle states:

StatusWhat it means
ringingThe carrier network is ringing the recipient's device.
answeredA person or an answering machine picked up the call.
completedThe spoken message played in full, and the call disconnected.
no_answerThe line rang until timeout without an answer. Unbilled.
busyThe destination line returned a busy signal. Unbilled.
failedThe carrier was unable to route or connect the call. Unbilled.

To inspect recent calls from your terminal, run:

Terminal
# List recent calls and their high-level statuses
vibiz phone calls

# Inspect a specific call record
vibiz phone calls call_123 --json

On 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.

FeatureSpoken message (say)Voice agent (prompt)
InteractionOne-way notificationTwo-way dynamic conversation
Primary useReminders, passcodes, alertsBooking, rescheduling, triage
Duration cap3 minutesUp to 15 minutes
Opening announcementNames project and phone numberNames project, states it is an AI, notes transcription
Result dataDelivery statusFull 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 say parameter.

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.