Reservas

Una reserva es una reunión que tu agente IA reservó dentro de la conversación, en tu calendario conectado. La API las lista en solo lectura, la franja más reciente primero.

Endpoints

Método	Ruta	Scope
GET	`/bookings`	`bookings:read`

Listar reservas

curl "https://app.whatsetter.com/api/v1/bookings?since=2026-09-01T00:00:00Z&limit=25" \
  -H "Authorization: Bearer ws_live_…"

const res = await fetch(
  'https://app.whatsetter.com/api/v1/bookings?since=2026-09-01T00:00:00Z&limit=25',
  { headers: { Authorization: 'Bearer ws_live_…' } },
);
const { data: bookings, pagination } = await res.json();

import requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/bookings",
    params={"since": "2026-09-01T00:00:00Z", "limit": 25},
    headers={"Authorization": "Bearer ws_live_…"},
)
bookings = r.json()["data"]

{
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0f5",
      "status": "booked",
      "lead_id": "34612345678@c.us",
      "campaign_id": "acme-espana-1-ab12",
      "provider": "calendly",
      "source": "chat",
      "start_at": "2026-09-23T13:00:00.000Z",
      "end_at": "2026-09-23T13:30:00.000Z",
      "timezone": "Europe/Madrid",
      "attendee": {
        "name": "Julien",
        "email": "julien@example.com",
        "phone": "+34612345678"
      },
      "cancel_url": "https://calendly.com/cancellations/…",
      "reschedule_url": "https://calendly.com/reschedulings/…",
      "canceled_at": null,
      "cancellation_reason": null,
      "created_at": "2026-09-18T16:45:00.000Z"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": "66f1a2b3c4d5e6f7a8b9c0f5" }
}

Parámetro	Qué hace
`status`	Coincidencia exacta con un estado de abajo.
`campaign_id`	El slug de la campaña o su `id`.
`since`	Solo las reservas que empiezan a partir de esta fecha ISO 8601.
`limit`, `cursor`	Paginación, de 1 a 100 por página.

Campos y estados

Campo	Significado
`status`	`booked`, `canceled`, `rescheduled`, `failed` o `no_show`.
`lead_id`	El id de WhatsApp del lead (`34612345678@c.us`), el mismo valor que `whatsapp_id` en un lead. Para abrir el lead, llama a `GET /leads?phone=+34612345678`.
`campaign_id`	El slug de la campaña.
`provider`	El proveedor de calendario donde vive la reunión.
`source`	Cómo se reservó: `chat` (por el agente en la conversación), `static_link` (el lead usó el enlace de reserva), `webhook` (comunicada por el proveedor), `manual`.
`start_at`, `end_at`	En UTC. Muéstralos en `timezone`.
`attendee`	Nombre, email y teléfono que dio el lead al reservar.
`canceled_at`, `cancellation_reason`	Rellenos cuando la reunión se canceló.

La lista se ordena por start_at, la franja más reciente primero: las reuniones futuras van antes que las pasadas.

Los enlaces son secretos

cancel_url y reschedule_url son enlaces de capacidad generados por el proveedor de calendario: quien tenga uno puede cancelar o mover la reunión, sin iniciar sesión. Trátalos como contraseñas: guárdalos cifrados, no los registres nunca en logs, no se los muestres nunca a alguien que no pueda actuar sobre la reunión. Son null cuando el proveedor no dio ninguno.

Errores que encontrarás

HTTP	`code`	Cuándo
401	`missing_api_key`, `invalid_api_key`	Clave ausente, desconocida o revocada.
403	`insufficient_scope`	La clave no tiene `bookings:read`.
422	`validation_error`	`since` no es una fecha ISO 8601, `limit` fuera de 1 a 100, cursor inválido o caducado.
429	`rate_limited`	Demasiadas peticiones este minuto. Respeta `Retry-After`.