Appointment Reminders with confirmation replies

Learn how to build an appointment reminder workflow with the Mobile Text Alerts API

This guide shows how to build a complete appointment reminder workflow with the Mobile Text Alerts API. This includes scheduling a personalized reminder ahead of time, letting the recipient respond by replying, and keeping your appointment records in sync with the user response. This use case uses multiple API endpoints, this guide shows how to use them together in one worked example.

Appointment reminder workflow overview

The following is the typical appointment reminder workflow:

Schedule a personalized reminder ahead of an appointment The recipient can reply to confirm, change or cancel the appointment Update your system for any appointment changes

Implementation steps:

1. An appointment is created in your system.

2. You schedule a reminder message to send ahead of the appointment. This is personalized with the recipient's name, time, and location.

3. Mobile Text Alerts sends the reminder message at the scheduled time (in the recipient's local time).

4. The recipient replies — to confirm, cancel, or ask to reschedule.

5. Your webhook endpoint receives this reply and then updates the appointment record in your system.

6. If the appointment time changes or is cancelled before it is sent, then the scheduled reminder is updated or cancelled.

This user guide walks through these steps, including the request fields and endpoints. It covers scheduledDate, properties, the message-reply webhook, and the Scheduled Messages endpoints.

Prerequisites

Before building this workflow you need to have:

• Completed the steps in Getting Started and have a valid API key.

• A verified sending number. Trial accounts and unverified numbers can only send templated content, which will limit how much you can personalize a reminder.

• A webhook endpoint that is already registered and receiving message-reply events. See Setting up your first webhook if this has not been configured yet.

Store appointment data

Mobile Text Alerts holds the message and schedule, but the appointment itself is your data. At minimum, keep a record per appointment with the following fields:

Field	Purpose
appointmentId	Your own internal identifier for the appointment.
subscriberNumber	The recipient's phone number, in E.164 format.
appointmentDateTime	The appointment date and time.
recipientTimezone	The recipient's local timezone (IANA name, e.g. America/Chicago), used to compute the correct offset for scheduledDate.
externalId	The identifier you sent on the reminder's /send request — typically derived from appointmentId. Used to match an inbound reply back to this appointment.
messageId*	The messageId returned by /send when the reminder was created.
scheduledMessageId*	The scheduled message's own ID, returned when the reminder is created as a future send. Needed to later update or cancel the reminder before it fires.
status	This is the confirmation state, one of the following: pending, confirmed, cancelled, or reschedule_requested.

*Note messageId and scheduledMessageId serve different purposes:

• messageId identifies the message record for reconciliation and delivery status

• scheduledMessageId is used to update or delete the pending send itself

Schedule the reminder

Reminder messages are sent with a POST /send request, using the scheduledDate field as the scheduled delivery time.

Timezone handling

The scheduledDate field is an ISO 8601 string with an explicit UTC offset. For example, "20260615T143000-0500" represents 2:30 PM in a UTC-5 timezone. There is no separate timezone parameter. The offset in the string is the timezone.

Compute the offset for the recipient's local reminder delivery time.

Example scenarios with an offset:

• For a reminder scheduled for 9:00 AM in America/Chicago, scheduledDate needs the America/Chicago offset for that delivery date, not your application server's offset.

• Daylight saving transitions mean the correct offset for a June delivery (-0500 for Central Daylight Time) can differ from the offset in effect in December (-0600 for Central Standard Time). Always resolve the offset against the target delivery date using your timezone library, not a hardcoded value.

Code example:

The following resolves the reminder's local delivery time to scheduledDate and computes the offset for that delivery date.

Node

import { DateTime } from "luxon";

function toScheduledDate(reminderLocalDateTime, timezone) {
  const dt = DateTime.fromISO(reminderLocalDateTime, { zone: timezone });
  // e.g. "20260615T143000-0500"
  return dt.toFormat("yyyyMMdd'T'HHmmssZZ").replace(":", "");
}

const scheduledDate = toScheduledDate("2026-06-15T14:30:00", "America/Chicago");

Python

from zoneinfo import ZoneInfo
from datetime import datetime

def to_scheduled_date(reminder_local_dt: datetime, timezone: str) -> str:
    """Attach the correct offset for the reminder delivery time and format for MTA."""
    tz = ZoneInfo(timezone)
    localized = reminder_local_dt.replace(tzinfo=tz)
    # e.g. "20260615T143000-0500"
    return localized.strftime("%Y%m%dT%H%M%S%z")

scheduled_date = to_scheduled_date(
    datetime(2026, 6, 15, 14, 30, 0),
    "America/Chicago",
)

Send the scheduled reminder

When sending the reminder message you need to set the externalId field to your own appointment identifier so it comes back on any webhook related to this message. Then store the messageId Mobile Text Alerts returns in response.

Use tags to carry extra context

The tags field is a general purpose key/value map of the outbound message and is echoed back on any related webhook event, including the reply. Unlike externalId, which is a single string, tags can hold multiple fields. This is useful for passing metadata your reply handler needs without an extra database lookup, such as appointmentId, locationId, or providerId.

Scheduling a message also creates a scheduled message record you can look up, update, or delete later — see Change or cancel a reminder message below.

Personalize the reminder

The properties field maps each recipient number to a set of Liquid template variables referenced in message with {{variableName}} syntax. Each subscriber gets their own set of values in the same request, which is what makes it possible to send one templated reminder to many recipients with different appointment details.

The following example uses firstName, appointmentTime, providerName, and location, but you can create variables that suit your use case.

Node

const response = await fetch("https://api.mobile-text-alerts.com/v3/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MTA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    subscribers: ["[phone]"],
    message:
      "Hi {{firstName}}, this is a reminder for your appointment with " +
      "{{providerName}} on {{appointmentTime}} at {{location}}. " +
      "Reply C to confirm, R to reschedule, or X to cancel.",
    properties: {
      "[phone]": {
        firstName: "Bob",
        providerName: "Dr. Alvarez",
        appointmentTime: "Tue, Jun 16 at 2:30 PM",
        location: "Downtown Clinic",
      },
    },
    scheduledDate: "20260615T143000-0500",
    externalId: `appt-482910`,
    tags: { appointmentId: "482910" },
  }),
});

const { data } = await response.json();
// Persist data.messageId (and the scheduledMessageId once you retrieve it, see below)

Python

import os
import requests

response = requests.post(
    "https://api.mobile-text-alerts.com/v3/send",
    headers={
        "Authorization": f"Bearer {os.environ['MTA_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "subscribers": ["[phone]"],
        "message": (
            "Hi {{firstName}}, this is a reminder for your appointment with "
            "{{providerName}} on {{appointmentTime}} at {{location}}. "
            "Reply C to confirm, R to reschedule, or X to cancel."
        ),
        "properties": {
            "[phone]": {
                "firstName": "Bob",
                "providerName": "Dr. Alvarez",
                "appointmentTime": "Tue, Jun 16 at 2:30 PM",
                "location": "Downtown Clinic",
            }
        },
        "scheduledDate": "20260615T143000-0500",
        "externalId": "appt-482910",
        "tags": {"appointmentId": "482910"},
    },
)

data = response.json()["data"]
# Persist data["messageId"] (and the scheduledMessageId once you retrieve it, see below)

Message Character Limits

Because properties values vary in length per recipient, the same template can render to different message lengths depending on the data. SMS messages are limited to 160 characters before they split into an additional segment (each segment billed as an additional credit). A long provider name or location string could push some messages into a second segment while others stay in one. To avoid this, keep variable values concise if consistent segment count matters for your use case.

If your reminder content is fixed and only the variables change, such as a standardized clinic reminder format, consider defining it as a reusable message template with templateId instead of inlining message on every request.

See Properties field for custom variables in messages to learn more.

Handle the message reply

How reply attribution works in SMS

It is important to note that SMS is not a threaded medium. There is no concept of a "conversation ID" that a phone enforces, instead replies simply appear in chronological order in the recipient's default messaging app, alongside every other message from that same number. When a subscriber replies, Mobile Text Alerts can only attribute that reply to the most recent outbound message sent to that number, because that is the only attribution the channel itself provides. This is exactly what externalId and tags deliver on the message-reply payload: MTA echoes back the identifying data from that last outbound send.

A subscriber could have more than one appointment reminder outstanding at the same time, such as two appointments in the same week. If they reply, the reply payload alone won't tell you which appointment "confirm" refers to if your message copy doesn't make it unambiguous. So the distinguishing detail has to live in the message text itself:

Example message:

Hi Bob, reminder: your appointment with Dr. Alvarez is Tue 6/16 at 2:30 PM.
Reply C to confirm this Tue 3pm appointment, R to reschedule, or X to cancel.

Referencing a specific day/time in the reply prompt, as shown above, gives the recipient (and your own support team, if they ever look at the thread) an unambiguous anchor — even though your backend will still resolve the reply to a specific appointment via externalId/tags rather than by parsing the message text.

Read the webhook payload

When the recipient replies, Mobile Text Alerts posts a message-reply event to your configured webhook endpoint.

Relevant fields:

Field	Description
fromNumber	The subscriber's number the reply came from.
message	The full text content of the reply.
externalId	The identifier you set on the original outbound reminder — use this to look up the appointment.
tags	The tags object you set on the original outbound reminder.
replyId / messageId	MTA's internal identifier for this inbound reply.
timestamp	UTC ISO 8601 timestamp of the reply.

You need a handler that resolves a reply to the appointment and updates its status based on the recipient's response.

Example:

Node

import express from "express";
const app = express();
app.use(express.json());

app.post("/webhooks/mobile-text-alerts", async (req, res) => {
  const { externalId, tags, fromNumber, message } = req.body;

  // Look up the appointment via externalId (or tags.appointmentId)
  const appointment = await db.appointments.findByExternalId(externalId);
  if (!appointment) {
    // Nothing matched — acknowledge anyway so MTA doesn't retry
    return res.sendStatus(200);
  }

  const normalized = message.trim().toUpperCase();

  if (["C", "CONFIRM", "Y", "YES"].includes(normalized)) {
    await db.appointments.updateStatus(appointment.id, "confirmed");
  } else if (["X", "CANCEL", "N", "NO"].includes(normalized)) {
    await db.appointments.updateStatus(appointment.id, "cancelled");
    // Also cancel the underlying scheduled reminder if it hasn't fired yet
    // (guards against a duplicate/late reminder — see below)
  } else if (["R", "RESCHEDULE"].includes(normalized)) {
    await db.appointments.updateStatus(appointment.id, "reschedule_requested");
    // Kick off your own reschedule flow (agent follow-up, booking link, etc.)
  } else {
    // Unrecognized reply — route to a human, or send a clarifying auto-reply
  }

  res.sendStatus(200);
});

Python

from flask import Flask, request

app = Flask(__name__)

@app.post("/webhooks/mobile-text-alerts")
def handle_reply():
    payload = request.get_json()
    external_id = payload.get("externalId")
    from_number = payload.get("fromNumber")
    message = payload.get("message", "").strip().upper()

    appointment = db.appointments.find_by_external_id(external_id)
    if appointment is None:
        # Nothing matched — acknowledge anyway so MTA doesn't retry
        return "", 200

    if message in ("C", "CONFIRM", "Y", "YES"):
        db.appointments.update_status(appointment.id, "confirmed")
    elif message in ("X", "CANCEL", "N", "NO"):
        db.appointments.update_status(appointment.id, "cancelled")
        # Also cancel the underlying scheduled reminder if it hasn't fired yet
        # (guards against a duplicate/late reminder — see below)
    elif message in ("R", "RESCHEDULE"):
        db.appointments.update_status(appointment.id, "reschedule_requested")
        # Kick off your own reschedule flow (agent follow-up, booking link, etc.)
    else:
        # Unrecognized reply — route to a human, or send a clarifying auto-reply
        pass

    return "", 200

Webhook-driven handling vs. Automated Replies

Handle confirmations through the message-reply webhook, as shown above, rather than with Automated Replies. A confirmation may need to update a record in your system. Automated Replies work well for static information that does not depend on application state, such as a keyword that always responds with clinic hours or a cancellation policy. Anything that needs to change an appointment record belongs in a webhook handler. Note that both Automated Replies and webhook-driven replies can be used on the same number.

Change or cancel a reminder message

Appointments can be updated or cancelled after the reminder has already been scheduled. Because the reminder was created as a scheduled send, you can look it up to update or cancel it — no need to cancel and recreate.

View outstanding scheduled sends

Use the GET /scheduled endpoint to list all scheduled messages on your account, or call GET /scheduled/{scheduledMessageId} if you have the scheduledMessageId for an appointment.

Update a reminder when an appointment time has changed

If the appointment time changes, update the existing scheduled message with PATCH /scheduled/{scheduledMessageId} rather than deleting and re-creating it. This preserves the same scheduled message record and avoids a window where no reminder is scheduled at all.

Node

await fetch(
  `https://api.mobile-text-alerts.com/v3/scheduled/${scheduledMessageId}`,
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${process.env.MTA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      // New scheduledDate computed for the recipient's timezone,
      // as described in Scheduling the reminder above
      scheduledDate: "20260618T100000-0500",
      message:
        "Hi {{firstName}}, your appointment with {{providerName}} has moved " +
        "to {{appointmentTime}} at {{location}}. Reply C to confirm, R to " +
        "reschedule, or X to cancel.",
    }),
  }
);

Python

requests.patch(
    f"https://api.mobile-text-alerts.com/v3/scheduled/{scheduled_message_id}",
    headers={
        "Authorization": f"Bearer {os.environ['MTA_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        # New scheduledDate computed for the recipient's timezone,
        # as described in Scheduling the reminder above
        "scheduledDate": "20260618T100000-0500",
        "message": (
            "Hi {{firstName}}, your appointment with {{providerName}} has moved "
            "to {{appointmentTime}} at {{location}}. Reply C to confirm, R to "
            "reschedule, or X to cancel."
        ),
    },
)

Cancel a reminder message

If the appointment is cancelled outright, cancel the individual scheduled message so the reminder never goes out. Use POST /scheduled/{scheduledMessageId} for the endpoint and request details.

Update your own appointment record's status to cancelled in the same code path, so a webhook reply event arriving after the fact (see below) has a consistent state to check against.

Time between cancellation and delivery messages

Sometimes there is a narrow window where an appointment is cancelled after the reminder has already been handed off for delivery but before your cancellation request reaches Mobile Text Alerts. In this case the recipient gets a reminder for an appointment that no longer exists. This scenario can't be fully eliminated, but you can contain it:

• Check appointment status before acting on a message-reply. If a reminder fires late for an already-cancelled appointment and the recipient replies "C", your webhook handler should see the appointment is already cancelled and avoid flipping it back to confirmed.

• Where the workflow allows it, cancel the scheduled reminder as early as possible in your cancellation flow, rather than as a final step, to minimize the race window.

Recurring reminders

For standing repeating appointments you can use the repeat field on the original /send request instead of scheduling each occurrence individually.

repeat takes boolean flags for each day of the week, a type of week or month, and a frequency:

CUSTOM = -1
NEVER = 0
DAILY = 1
WEEKLY = 2
BIWEEKLY = 3
MONTHLY = 4
ANNUALLY = 5

See Repeat scheduled message sends for the full field reference and behavior details.

Learn More

• Send an SMS Message — this includes the full reference for properties, scheduledDate, and repeat.

• Receive and Reply to Messages — the general pattern for two-way messaging this guide builds on.

• Scheduled Messages — full API endpoint reference for listing, updating, and deleting scheduled sends.

• Webhooks — see this page for event types and payload reference, including message-reply.