Calendario y reservas

Endpoints de páginas de reserva (agendas tipo Calendly), sus reuniones agendadas y el grid combinado del calendario. Incluye además la API pública de booking (sin autenticación), que es la que usa la página de reserva que ve el invitado.

Nota

Waiify no tiene un CRUD de “eventos y tareas” de calendario aparte: todo lo que se agenda pasa por una página de reserva y queda como una reunión (booking). Los horarios personales de cada anfitrión y las cuentas de Google conectadas se gestionan desde el dashboard, no por API.

Páginas de reserva

Cuelgan de /workspaces/:workspaceId/calendar/schedulers.

Método	Ruta	Descripción
GET	/calendar/schedulers	Listar páginas de reserva
POST	/calendar/schedulers	Crear una página
GET	/calendar/schedulers/:id	Obtener el detalle completo
PATCH	/calendar/schedulers/:id	Actualizar (parcial)
DELETE	/calendar/schedulers/:id	Eliminar
POST	/calendar/schedulers/:id/duplicate	Duplicar (nace en PAUSED, sin reservas ni vistas)
POST	/calendar/schedulers/:id/default	Marcarla como predeterminada del workspace
PATCH	/calendar/schedulers/:id/status	Cambiar de estado
POST	/calendar/schedulers/bulk-delete	Eliminar varias ({ ids: string[] })
POST	/calendar/schedulers/bulk-status	Activar/pausar varias ({ ids: string[], status: 'ACTIVE' | 'PAUSED' })

Crear una página de reserva

POST /workspaces/:workspaceId/calendar/schedulers Copiar

Cuerpo de la petición

Campo	Tipo	Requerido	Descripción
title	string	Sí	Título de la agenda (máx. 200).
durationMinutes	number	Sí	Duración de la cita en minutos.
hosts	array	Sí	Anfitriones: { userId, role?, priority? }. userId debe ser miembro del workspace.
availabilityRules	array	Sí	Tramos horarios: { weekday (0-6), startMinute, endMinute, hostUserId? }.
type	string	No	INDIVIDUAL (def.) · GROUP · COLLECTIVE · ROUND_ROBIN.
status	string	No	DRAFT (def.) · ACTIVE · PAUSED · ARCHIVED.
slug	string	No	URL de la página pública; se genera del título si se omite.
description	string	No	Descripción visible en la página pública.
color	string	No	Color de la agenda (hex).
timezone	string	No	Zona IANA; cae a la del workspace si se omite.
slotIntervalMinutes	number	No	Cada cuánto se ofrece un horario dentro del tramo.
locationType	string	No	GOOGLE_MEET (def.) · IN_PERSON · PHONE · CUSTOM · NONE.
locationDetail	string	No	Dirección, número o instrucciones según locationType.
bookingWindowType	string	No	ROLLING (def., antelación en días) · RANGE (fechas fijas).
maxAdvanceDays	number	Solo en ROLLING	Hasta cuántos días a futuro se ofrece disponibilidad.
rangeStart / rangeEnd	string	Solo en RANGE	Fechas civiles YYYY-MM-DD del rango fijo.
minAdvanceHours	number	No	Antelación mínima para reservar (def. 4).
bufferBeforeMinutes / bufferAfterMinutes	number	No	Colchón antes/después de cada reunión.
maxBookingsPerDay	number	No	Tope de reservas por día (def. 100).
recurrenceIntervalWeeks	number	No	Cada cuántas semanas se repite la disponibilidad (def. 1 = todas).
availabilityMode	string	No	SHARED (def., un horario para toda la agenda) · PER_HOST.
guestReminderMinutes / hostReminderMinutes	number[]	No	Antelaciones de recordatorio, entre 5 min y 30 días, máx. 5 cada una.
allowGuestInvitees / maxGuestInvitees	boolean / number	No	Si el invitado puede sumar acompañantes por correo.
maxInviteesPerSlot	number	Solo GROUP	Invitados por horario (mínimo 2).
showRemainingSpots	boolean	Solo GROUP	Muestra al invitado cuántas plazas quedan.
roundRobinStrategy	string	Solo ROUND_ROBIN	MAX_AVAILABILITY · EQUAL_DISTRIBUTION (def.).
imbalanceThreshold	number	Solo ROUND_ROBIN con EQUAL_DISTRIBUTION	Reuniones de ventaja toleradas entre anfitriones.
formFields	array	No	Campos del formulario: { label, type?, required?, position?, options? }.
calendarInvitation	boolean	No	Envía invitación de calendario en la confirmación (def. true).

Consejo

Cada tipo de agenda exige un número distinto de anfitriones: INDIVIDUAL y GROUP exactamente uno, COLLECTIVE al menos uno, ROUND_ROBIN al menos dos.

cURL

curl -X POST "https://api.waiify.com/workspaces/WORKSPACE_ID/calendar/schedulers" \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Demo de producto",
    "durationMinutes": 30,
    "hosts": [{ "userId": "user_ab12cd34ef" }],
    "availabilityRules": [
      { "weekday": 1, "startMinute": 540, "endMinute": 1020 }
    ],
    "bookingWindowType": "ROLLING",
    "maxAdvanceDays": 30
  }'

Node

const res = await fetch(
  'https://api.waiify.com/workspaces/WORKSPACE_ID/calendar/schedulers',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer TU_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      title: 'Demo de producto',
      durationMinutes: 30,
      hosts: [{ userId: 'user_ab12cd34ef' }],
      availabilityRules: [
        { weekday: 1, startMinute: 540, endMinute: 1020 },
      ],
      bookingWindowType: 'ROLLING',
      maxAdvanceDays: 30,
    }),
  }
);

const { data: page } = await res.json();

Python

import requests

res = requests.post(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/calendar/schedulers",
    headers={"Authorization": "Bearer TU_API_KEY"},
    json={
        "title": "Demo de producto",
        "durationMinutes": 30,
        "hosts": [{"userId": "user_ab12cd34ef"}],
        "availabilityRules": [
            {"weekday": 1, "startMinute": 540, "endMinute": 1020}
        ],
        "bookingWindowType": "ROLLING",
        "maxAdvanceDays": 30,
    },
)

page = res.json()["data"]

Respuesta 201

{
  "success": true,
  "message": "Agenda creada",
  "data": {
    "id": "sched_ab12cd34ef",
    "workspaceId": "ws_ab12cd34ef",
    "type": "INDIVIDUAL",
    "status": "DRAFT",
    "title": "Demo de producto",
    "slug": "demo-de-producto",
    "durationMinutes": 30,
    "timezone": "America/Mexico_City",
    "hosts": [
      { "id": "shost_ab12cd34ef", "userId": "user_ab12cd34ef", "role": "PRIMARY", "priority": 0 }
    ],
    "availabilityRules": [
      { "id": "rule_ab12cd34ef", "weekday": 1, "startMinute": 540, "endMinute": 1020 }
    ],
    "formFields": []
  }
}

Listar páginas de reserva

GET /workspaces/:workspaceId/calendar/schedulers Copiar

Parámetros de query

Parámetro	Tipo	Descripción
page / pageSize	number	Paginación (pageSize máx. 100).
search	string	Búsqueda por título.
hostUserIds	string	Uno o varios userId de anfitrión.
types	string	Uno o varios tipos (INDIVIDUAL, GROUP, COLLECTIVE, ROUND_ROBIN).
locationTypes	string	Uno o varios locationType.
sortBy	string	createdAt (def.), updatedAt, title, durationMinutes, views.
sortOrder	string	asc (def.) o desc.

cURL

curl "https://api.waiify.com/workspaces/WORKSPACE_ID/calendar/schedulers?status=ACTIVE&page=1" \
  -H "Authorization: Bearer TU_API_KEY"

Node

const res = await fetch(
  'https://api.waiify.com/workspaces/WORKSPACE_ID/calendar/schedulers?page=1',
  { headers: { Authorization: 'Bearer TU_API_KEY' } }
);
const { data: pages, pagination } = await res.json();

Python

import requests

res = requests.get(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/calendar/schedulers",
    headers={"Authorization": "Bearer TU_API_KEY"},
    params={"page": 1},
)
body = res.json()
pages, pagination = body["data"], body["pagination"]

Respuesta 200

{
  "success": true,
  "data": [
    {
      "id": "sched_ab12cd34ef",
      "title": "Demo de producto",
      "slug": "demo-de-producto",
      "type": "INDIVIDUAL",
      "status": "ACTIVE",
      "isDefault": false,
      "durationMinutes": 30,
      "timezone": "America/Mexico_City",
      "locationType": "GOOGLE_MEET",
      "organizer": "Ana Torres",
      "hostCount": 1,
      "views": 42,
      "scheduledMeetings": 5,
      "conversionRate": 12,
      "createdAt": "2026-06-17T10:00:00.000Z",
      "updatedAt": "2026-06-20T10:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 25, "total": 1, "totalPages": 1 }
}

Reuniones agendadas

Cuelgan de /workspaces/:workspaceId/calendar/meetings. Son las reservas creadas por invitados (por la API pública de booking) o directamente por el equipo.

Método	Ruta	Descripción
GET	/calendar/meetings	Listar reuniones
GET	/calendar/meetings/:id	Obtener el detalle
GET	/calendar/meetings/:id/reschedule-availability	Horarios disponibles para reprogramar esta reunión (from, to en query)
PATCH	/calendar/meetings/:id/reschedule	Reprogramar ({ start: string }, ISO)
PATCH	/calendar/meetings/:id/cancel	Cancelar ({ reason?: string })
POST	/calendar/meetings/bulk-cancel	Cancelar varias ({ ids: string[] })
POST	/calendar/meetings/bulk-delete	Eliminar del historial varias — solo CANCELLED o COMPLETED ({ ids: string[] })

Listar reuniones

GET /workspaces/:workspaceId/calendar/meetings Copiar

Parámetros de query

Parámetro	Tipo	Descripción
page / pageSize	number	Paginación (pageSize máx. 100).
skip / take	number	Alternativa a page/pageSize para “cargar más” (tienen prioridad si vienen).
search	string	Busca por nombre/correo del invitado o título de la agenda.
status	string	Uno o varios: CONFIRMED, RESCHEDULED, CANCELLED, NO_SHOW, COMPLETED.
location	string	Uno o varios locationType.
types	string	Tipo de la agenda de origen (INDIVIDUAL, GROUP, ROUND_ROBIN).
hostUserIds	string	Uno o varios userId de anfitrión.
timeframe	string	upcoming (vigentes/futuras, más próxima primero) o past (terminadas, más reciente primero).
sortBy	string	start (def.), duration, guestName, schedulerTitle, createdAt, updatedAt. Se ignora si envías timeframe.
sortOrder	string	asc o desc (def.).

Consejo

Una reunión CONFIRMED o RESCHEDULED cuya hora de fin ya pasó se muestra como COMPLETED aunque el campo status en base de datos siga en su valor original — el estado devuelto (displayStatus) ya viene resuelto.

cURL

curl "https://api.waiify.com/workspaces/WORKSPACE_ID/calendar/meetings?timeframe=upcoming" \
  -H "Authorization: Bearer TU_API_KEY"

Node

const res = await fetch(
  'https://api.waiify.com/workspaces/WORKSPACE_ID/calendar/meetings?timeframe=upcoming',
  { headers: { Authorization: 'Bearer TU_API_KEY' } }
);
const { data: meetings, pagination } = await res.json();

Python

import requests

res = requests.get(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/calendar/meetings",
    headers={"Authorization": "Bearer TU_API_KEY"},
    params={"timeframe": "upcoming"},
)
body = res.json()
meetings, pagination = body["data"], body["pagination"]

Respuesta 200

{
  "success": true,
  "data": [
    {
      "id": "book_ab12cd34ef",
      "pageId": "sched_ab12cd34ef",
      "schedulerTitle": "Demo de producto",
      "schedulerType": "INDIVIDUAL",
      "guestName": "Juan Pérez",
      "guestEmail": "juan@example.com",
      "start": "2026-07-01T15:00:00.000Z",
      "end": "2026-07-01T15:30:00.000Z",
      "durationMinutes": 30,
      "status": "CONFIRMED",
      "locationType": "GOOGLE_MEET",
      "host": "Ana Torres"
    }
  ],
  "pagination": { "page": 1, "limit": 25, "total": 1, "totalPages": 1 }
}

Cancelar una reunión

PATCH /workspaces/:workspaceId/calendar/meetings/:id/cancel Copiar

Cuerpo de la petición

Campo	Tipo	Requerido	Descripción
reason	string	No	Motivo de la cancelación (se incluye en el correo al invitado).

Consejo

No se puede cancelar una reunión cuya hora de fin ya pasó. La cancelación se registra siempre en Waiify aunque el anfitrión tenga la cuenta de Google desconectada; retirar la copia del evento es una consecuencia que se reintenta aparte.

cURL

curl -X PATCH "https://api.waiify.com/workspaces/WORKSPACE_ID/calendar/meetings/MEETING_ID/cancel" \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "El cliente reagendó por otro canal" }'

Node

await fetch(
  'https://api.waiify.com/workspaces/WORKSPACE_ID/calendar/meetings/MEETING_ID/cancel',
  {
    method: 'PATCH',
    headers: {
      Authorization: 'Bearer TU_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ reason: 'El cliente reagendó por otro canal' }),
  }
);

Python

import requests

requests.patch(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/calendar/meetings/MEETING_ID/cancel",
    headers={"Authorization": "Bearer TU_API_KEY"},
    json={"reason": "El cliente reagendó por otro canal"},
)

Respuesta 200

{
  "success": true,
  "message": "Reunión cancelada",
  "data": {
    "id": "book_ab12cd34ef",
    "status": "CANCELLED",
    "cancelledAt": "2026-06-25T12:00:00.000Z",
    "cancelReason": "El cliente reagendó por otro canal"
  }
}

Grid combinado

Vista unificada de reuniones ya agendadas y bloques de disponibilidad libre en un rango, la que alimenta el calendario del dashboard.

GET /workspaces/:workspaceId/calendar/grid Copiar

Parámetros de query

Parámetro	Tipo	Requerido	Descripción
from	string	Sí	Inicio del rango (ISO 8601).
to	string	Sí	Fin del rango (ISO 8601). Máximo 92 días entre ambos.

Consejo

availabilityBlocks ya resta las franjas ocupadas por reuniones existentes — no es la disponibilidad teórica de la agenda, es lo que de verdad queda libre. Si hay muchas agendas activas la respuesta puede venir truncated: true con un tope de 5000 bloques.

cURL

curl "https://api.waiify.com/workspaces/WORKSPACE_ID/calendar/grid?from=2026-07-01T00:00:00Z&to=2026-07-08T00:00:00Z" \
  -H "Authorization: Bearer TU_API_KEY"

Node

const params = new URLSearchParams({
  from: '2026-07-01T00:00:00Z',
  to: '2026-07-08T00:00:00Z',
});
const res = await fetch(
  `https://api.waiify.com/workspaces/WORKSPACE_ID/calendar/grid?${params}`,
  { headers: { Authorization: 'Bearer TU_API_KEY' } }
);
const { data } = await res.json();

Python

import requests

res = requests.get(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/calendar/grid",
    headers={"Authorization": "Bearer TU_API_KEY"},
    params={"from": "2026-07-01T00:00:00Z", "to": "2026-07-08T00:00:00Z"},
)
data = res.json()["data"]

Respuesta 200

{
  "success": true,
  "data": {
    "meetings": [
      {
        "id": "book_ab12cd34ef",
        "type": "meeting",
        "title": "Juan Pérez",
        "schedulerTitle": "Demo de producto",
        "start": "2026-07-01T15:00:00.000Z",
        "end": "2026-07-01T15:30:00.000Z",
        "status": "CONFIRMED",
        "locationType": "GOOGLE_MEET"
      }
    ],
    "availabilityBlocks": [
      {
        "id": "sched_ab12cd34ef:2026-07-01:540",
        "type": "scheduler",
        "schedulerId": "sched_ab12cd34ef",
        "title": "Demo de producto",
        "color": "#2563eb",
        "start": "2026-07-01T09:00:00.000Z",
        "end": "2026-07-01T15:00:00.000Z",
        "accountDisconnected": false
      }
    ],
    "truncated": false
  }
}

Página de reserva pública

Sin autenticación — la usa la página pública que ve el invitado externo (/agendar/:pageId en el dashboard). No lleva Authorization, así que llevan rate limiting propio: 60 solicitudes/minuto en las de lectura, 10 solicitudes/hora en las de escritura (reservar/cancelar).

Método	Ruta	Descripción
GET	/booking/:pageId	Configuración pública de la agenda
GET	/booking/:pageId/availability	Horarios disponibles en un rango
POST	/booking/:pageId	Reservar un horario
GET	/booking/cancel/:token	Obtener una reserva por su token de cancelación
POST	/booking/cancel/:token	Cancelar una reserva por su token

Precaución

pageId es el id de la página de reserva (no el slug ni el workspace), y token es el cancelToken que recibe el invitado al reservar. Solo se resuelven agendas en estado ACTIVE; una DRAFT, PAUSED o ARCHIVED responde 404 en estos endpoints públicos.

Configuración pública de la agenda

GET /booking/:pageId Copiar

Parámetros de ruta

Parámetro	Tipo	Descripción
pageId	string	Id de la página de reserva.

cURL

curl "https://api.waiify.com/booking/PAGE_ID"

Node

const res = await fetch('https://api.waiify.com/booking/PAGE_ID');
const { data: page } = await res.json();

Python

import requests

res = requests.get("https://api.waiify.com/booking/PAGE_ID")
page = res.json()["data"]

Respuesta 200

{
  "success": true,
  "data": {
    "id": "sched_ab12cd34ef",
    "type": "INDIVIDUAL",
    "title": "Demo de producto",
    "description": "Una llamada de 30 minutos para conocer tu caso.",
    "durationMinutes": 30,
    "timezone": "America/Mexico_City",
    "locationType": "GOOGLE_MEET",
    "locationDetail": null,
    "requireGuestEmail": true,
    "bookingPageName": "Ana Torres",
    "bookingPagePhoto": null,
    "allowGuestInvitees": true,
    "maxGuestInvitees": 3,
    "formFields": [
      { "id": "field_ab12cd34ef", "label": "¿Qué te gustaría revisar?", "type": "TEXTAREA", "required": false, "options": [] }
    ]
  }
}

Horarios disponibles

GET /booking/:pageId/availability Copiar

Parámetros de query

Parámetro	Tipo	Requerido	Descripción
from	string	Sí	Fecha inicial (ISO 8601).
to	string	Sí	Fecha final (ISO 8601).

Consejo

Si la agenda es GROUP y tiene showRemainingSpots activado, cada horario incluye además remainingSpots con las plazas que quedan.

cURL

curl "https://api.waiify.com/booking/PAGE_ID/availability?from=2026-07-01&to=2026-07-07"

Node

const params = new URLSearchParams({ from: '2026-07-01', to: '2026-07-07' });
const res = await fetch(
  `https://api.waiify.com/booking/PAGE_ID/availability?${params}`
);
const { data: slots } = await res.json();

Python

import requests

res = requests.get(
    "https://api.waiify.com/booking/PAGE_ID/availability",
    params={"from": "2026-07-01", "to": "2026-07-07"},
)
slots = res.json()["data"]

Respuesta 200

{
  "success": true,
  "data": [
    { "start": "2026-07-01T15:00:00.000Z", "end": "2026-07-01T15:30:00.000Z" },
    { "start": "2026-07-01T15:30:00.000Z", "end": "2026-07-01T16:00:00.000Z" }
  ]
}

Reservar un horario

POST /booking/:pageId Copiar

Cuerpo de la petición

Campo	Tipo	Requerido	Descripción
guestName	string	Sí	Nombre del invitado (máx. 200).
start	string	Sí	Horario elegido, tal cual lo devolvió availability (ISO).
guestEmail	string	Solo si la agenda lo exige (requireGuestEmail)	Correo del invitado.
guestPhone	string	No	Teléfono.
guestNotes	string	No	Notas para el anfitrión (máx. 2000).
guestTimezone	string	No	Zona IANA del invitado, para sus correos/recordatorios.
guestInviteeEmails	string[]	No	Acompañantes por correo (requiere allowGuestInvitees, máx. maxGuestInvitees).
answers	array	No	Respuestas al formulario: { fieldId, value }. Obligatorio para los campos marcados required.

Precaución

El horario se revalida por completo en el servidor (disponibilidad real, antelación mínima, rango, buffers, tope diario y ocupación del anfitrión) — enviar un start fuera de lo que devolvió availability responde 400 o 409.

cURL

curl -X POST "https://api.waiify.com/booking/PAGE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "guestName": "Juan Pérez",
    "guestEmail": "juan@example.com",
    "start": "2026-07-01T15:00:00.000Z"
  }'

Node

const res = await fetch('https://api.waiify.com/booking/PAGE_ID', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    guestName: 'Juan Pérez',
    guestEmail: 'juan@example.com',
    start: '2026-07-01T15:00:00.000Z',
  }),
});

const { data: booking } = await res.json();

Python

import requests

res = requests.post(
    "https://api.waiify.com/booking/PAGE_ID",
    json={
        "guestName": "Juan Pérez",
        "guestEmail": "juan@example.com",
        "start": "2026-07-01T15:00:00.000Z",
    },
)

booking = res.json()["data"]

Respuesta 201

{
  "success": true,
  "message": "Reserva confirmada",
  "data": {
    "id": "book_ab12cd34ef",
    "cancelToken": "cnl_ab12cd34ef",
    "start": "2026-07-01T15:00:00.000Z",
    "end": "2026-07-01T15:30:00.000Z",
    "meetLink": null,
    "guestTimezone": "America/Mexico_City"
  }
}

Cancelar una reserva por token

POST /booking/cancel/:token Copiar

Parámetros de ruta

Parámetro	Tipo	Descripción
token	string	El cancelToken recibido al reservar.

Cuerpo de la petición

Campo	Tipo	Requerido	Descripción
reason	string	No	Motivo de la cancelación.

Consejo

GET /booking/cancel/:token devuelve el mismo resumen de la reserva sin cancelarla, útil para pintar la pantalla de confirmación antes de que el invitado decida cancelar. No se puede cancelar una reunión cuya hora de fin ya pasó.

cURL

curl -X POST "https://api.waiify.com/booking/cancel/CANCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Ya no puedo asistir" }'

Node

const res = await fetch(
  'https://api.waiify.com/booking/cancel/CANCEL_TOKEN',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ reason: 'Ya no puedo asistir' }),
  }
);

const { data: booking } = await res.json();

Python

import requests

res = requests.post(
    "https://api.waiify.com/booking/cancel/CANCEL_TOKEN",
    json={"reason": "Ya no puedo asistir"},
)

booking = res.json()["data"]

Respuesta 200

{
  "success": true,
  "message": "Reserva cancelada",
  "data": {
    "id": "book_ab12cd34ef",
    "title": "Demo de producto",
    "status": "CANCELLED",
    "start": "2026-07-01T15:00:00.000Z",
    "end": "2026-07-01T15:30:00.000Z",
    "durationMinutes": 30,
    "timezone": "America/Mexico_City",
    "guestName": "Juan Pérez",
    "locationType": "GOOGLE_MEET",
    "locationDetail": null,
    "meetLink": null,
    "cancelledAt": "2026-06-25T12:00:00.000Z",
    "cancelReason": "Ya no puedo asistir"
  }
}

Relacionado

• Páginas de reserva · Calendario · Conectar Google Calendar · Experiencia del invitado