Reminders & Reservations API

Overview

The Reminders module automates time-based WhatsApp communication for reservations, appointments, renewals, consultations, and payment deadlines. It bridges your scheduling workflow with WhatsApp Cloud API campaigns, providing:

• REST API Endpoints: Full CRUD operations under /api/v1/reminders/reservations with Bearer token authentication.
• Booking Idempotency: Safe retries using booking_key prevent duplicate appointment bookings.
• Smart Reschedule Lifecycle: Updating appointment times automatically cancels old pending reminder messages and schedules fresh ones, avoiding duplicate alerts.
• Negative Variables: Seamless variable injection (-4 to -10) into WhatsApp campaign templates for date, time, and booking reference.
• MCP Server Tools: AI agents in Claude, Cursor, or Antigravity can list and inspect reservations using the official @codingmantra/wacm-mcp package.
• WhatsApp Chat Sideapp: Customer support agents can view upcoming reservations and schedule new appointments directly inside the WhatsApp team chat sidebar.

How the Scheduling Engine Works

Authentication

All endpoints accept authentication via Laravel Sanctum API tokens:

• Header: Authorization: Bearer YOUR_SANCTUM_TOKEN
• Query Parameter: ?token=YOUR_SANCTUM_TOKEN
• JSON Request Body: {"token": "YOUR_SANCTUM_TOKEN"}

REST API Endpoints

1. Create Reservation

Creates a new reservation for a contact. You can specify a WhatsApp phone number directly (the contact will be located or created automatically) or pass an existing contact_id.

Idempotency: Supply an optional booking_key (e.g., your internal booking UUID). If a reservation with that key already exists, WACM returns the existing record immediately without duplicating reminders or sending duplicate notifications.

curl -X POST "https://app.wacm.in/api/v1/reminders/reservations" \
  -H "Authorization: Bearer YOUR_SANCTUM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+919876543210",
    "source_id": 3,
    "start_date": "2026-10-15 14:30:00",
    "end_date": "2026-10-15 15:30:00",
    "booking_key": "booking-apt-88219",
    "external_id": "EXT-88219",
    "notes": "Consultation with Dr. Sharma"
  }'

{
  "status": "success",
  "message": "Reservation created successfully",
  "data": {
    "id": 142,
    "company_id": 12,
    "source_id": 3,
    "contact_id": 804,
    "start_date": "2026-10-15 14:30:00",
    "end_date": "2026-10-15 15:30:00",
    "booking_key": "booking-apt-88219",
    "external_id": "EXT-88219",
    "notes": "Consultation with Dr. Sharma",
    "status": 1,
    "created_at": "2026-10-11T16:30:00.000000Z",
    "updated_at": "2026-10-11T16:30:00.000000Z"
  }
}

2. Reschedule or Update Reservation

Updates appointment date, time, status, or source. When start_date, end_date, source_id, or status changes, WACM's automatic lifecycle listener cancels all unsent pending reminder messages for the old schedule and re-generates new ones for the revised date.

curl -X PUT "https://app.wacm.in/api/v1/reminders/reservations" \
  -H "Authorization: Bearer YOUR_SANCTUM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 142,
    "start_date": "2026-10-16 11:00:00",
    "end_date": "2026-10-16 12:00:00",
    "notes": "Rescheduled per patient request"
  }'

{
  "status": "success",
  "message": "Reservation updated successfully",
  "data": {
    "id": 142,
    "company_id": 12,
    "source_id": 3,
    "contact_id": 804,
    "start_date": "2026-10-16 11:00:00",
    "end_date": "2026-10-16 12:00:00",
    "booking_key": "booking-apt-88219",
    "external_id": "EXT-88219",
    "notes": "Rescheduled per patient request",
    "status": 1,
    "updated_at": "2026-10-11T16:35:00.000000Z"
  }
}

3. Cancel Reservation

Cancels an appointment reservation. It sets the status to 3 (Cancelled) and immediately purges all pending scheduled messages so the customer will not receive any further reminders.

curl -X DELETE "https://app.wacm.in/api/v1/reminders/reservations" \
  -H "Authorization: Bearer YOUR_SANCTUM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "id": 142 }'

{
  "status": "success",
  "message": "Reservation cancelled successfully",
  "data": {
    "id": 142,
    "status": 3,
    "status_text": "Cancelled"
  }
}

4. List Reservations

Query reservations with filtering by phone number, contact ID, or status code.

curl "https://app.wacm.in/api/v1/reminders/reservations?phone=%2B919876543210&status=1" \
  -H "Authorization: Bearer YOUR_SANCTUM_TOKEN"

{
  "status": "success",
  "data": [
    {
      "id": 142,
      "source_id": 3,
      "contact_id": 804,
      "start_date": "2026-10-16 11:00:00",
      "end_date": "2026-10-16 12:00:00",
      "booking_key": "booking-apt-88219",
      "external_id": "EXT-88219",
      "notes": "Rescheduled per patient request",
      "status": 1,
      "contact": {
        "id": 804,
        "name": "Rohan Patel",
        "phone": "+919876543210"
      },
      "source": {
        "id": 3,
        "name": "Doctor Appointment"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 1
  }
}

5. Get Reservation

Retrieve full details for a single reservation including contact info and source configuration.

curl "https://app.wacm.in/api/v1/reminders/reservations/show?id=142" \
  -H "Authorization: Bearer YOUR_SANCTUM_TOKEN"

6. List Reminder Rules

Fetch active reminder sources and their message rules to determine available booking types.

curl "https://app.wacm.in/api/v1/reminders" \
  -H "Authorization: Bearer YOUR_SANCTUM_TOKEN"

Negative Variables in Message Templates

When a reminder broadcast is prepared from a reservation, WACM maps reservation dates and metadata into template negative variables. You can configure Meta WhatsApp message templates using these variables:

Hi {{1}},

This is a reminder that your appointment is scheduled for {{-4}} at {{-5}}.

Booking Ref: {{-10}}

To reschedule or cancel, please reply to this message directly.
See you soon!

Model Context Protocol (MCP) Integration

The official npm package @codingmantra/wacm-mcp provides 4 specialized read tools for LLM coding and support assistants:

For setup instructions in Claude Desktop, Cursor, VS Code, or Antigravity, see the WACM MCP Setup Guide.

Flowmaker Events

The Reminders module emits events to trigger AI Flow Builder workflows:

WhatsApp Chat Inbox Sideapp

When agents use the WACM WhatsApp Team Inbox, the built-in Reminders Sideapp renders on the right sidebar for the open conversation:

• Displays existing upcoming and past appointments for the active contact.
• Shows status badges (Active, Inactive, Cancelled, Completed) with appointment dates and times.
• Provides a + New Reservation button that pre-populates the customer's details in a modal for one-click scheduling.

Related Documentation

• Model Context Protocol (MCP) Guide — Connect Claude and AI coding agents to WACM
• WhatsApp Business API — Campaigns and message delivery
• AI Flow Builder — Visual flow automation with reminder triggers
• WhatsApp Team Inbox — Multi-agent collaboration and sideapps