6 endpoints
Scheduler experiences and booking callbacks
/scheduler/experiences Return all scheduler experiences configured for booking flows.
This endpoint does not accept parameters.
Default Response
curl -X GET "http://localhost:8080/scheduler/experiences"
No example response available.
/scheduler/experiences Create a new scheduler experience pointing to your availability and booking callbacks.
This endpoint does not accept parameters.
Default Response
curl -X POST "http://localhost:8080/scheduler/experiences" \
-H "Content-Type: application/json"
No example response available.
/scheduler/experiences/{slug} Fetch a single scheduler experience by slug.
slug string Default Response
curl -X GET "http://localhost:8080/scheduler/experiences/{slug}"
No example response available.
/scheduler/experiences/{slug} Update configuration for an existing scheduler experience.
slug string Default Response
curl -X PATCH "http://localhost:8080/scheduler/experiences/{slug}" \
-H "Content-Type: application/json"
No example response available.
/scheduler/experiences/{slug}/availability Call the configured availability callback for a scheduler experience and return available slots.
slug string Default Response
curl -X POST "http://localhost:8080/scheduler/experiences/{slug}/availability" \
-H "Content-Type: application/json"
No example response available.
/scheduler/experiences/{slug}/bookings Call the configured booking callback for a scheduler experience to finalize a meeting.
slug string Default Response
curl -X POST "http://localhost:8080/scheduler/experiences/{slug}/bookings" \
-H "Content-Type: application/json"
No example response available.
When an experience has an availabilityEndpoint, Riposte POSTs every slot lookup to your service using the SchedulerAvailabilityCallbackPayload structure. The payload includes the experience context plus the visitor’s exact filter: date range, durationMinutes, optional attendees, booking-form answers, and any metadata you attached while proxying the widget request.
Your handler must return a SchedulerAvailabilityResponse with a generatedAt timestamp and at least one slots entry (or an explicit empty array). If generatedAt is missing the widget refuses to render and logs generatedAt is required.
import type { SchedulerAvailabilityCallbackPayload, SchedulerAvailabilityResponse,} from '@riposte.co/server/dist/src/scheduler/types'
app.post('/callbacks/riposte/availability', async (req, res) => { const payload = req.body as SchedulerAvailabilityCallbackPayload const { request, experience } = payload const computedAt = new Date()
const slots = await buildAvailability({ range: request.range, durationMinutes: request.durationMinutes, attendees: request.attendees, metadata: request.metadata, experience, })
const response: SchedulerAvailabilityResponse = { generatedAt: computedAt.toISOString(), expiresAt: new Date(computedAt.getTime() + 5 * 60 * 1000).toISOString(), timezone: request.timezone ?? request.range.timezone ?? experience.timezone ?? 'UTC', slots: slots.map((slot) => ({ start: slot.start, end: slot.end, timezone: slot.timezone ?? request.timezone ?? experience.timezone ?? 'UTC', participants: slot.participants, metadata: { hostAccountId: slot.hostAccountId, ...slot.metadata, }, })), }
res.status(200).json(response)})Recommendations:
generatedAt: ISO-8601 string describing when you computed the response; we use it in cache validation.expiresAt: optional ISO-8601 string that forces the widget to refresh stale results (commonly 3–5 minutes after generatedAt).metadata: attach any routing data (for example, hostAccountId) so the booking callback can persist who owned the slot.