# Citas y agenda

> Cómo agenda watsi citas por WhatsApp de forma nativa y cómo llevar cada cita agendada, movida o cancelada a tu sistema con los webhooks appointment.*.

Source: https://docs.watsi.ai/guides/calendar-booking

No tienes que construir el flujo de reservas: el agente de watsi ya agenda. Lee la disponibilidad de la agenda de tu equipo, ofrece horarios en la conversación, reserva, reagenda y cancela, y manda los recordatorios. Lo que sí puedes construir es **que cada cita llegue a tu sistema**: tu CRM, tu sistema de turnos o tu propio calendario.

## Cómo funciona

```text
Cliente ── WhatsApp ──▶ agente de watsi ──▶ agenda de watsi
                                              │
                                              └── webhook appointment.* ──▶ tu sistema
```

1. **Configura la agenda en la app**: los tipos de cita, el horario de cada miembro del equipo y quién atiende qué. Desde ahí el agente sabe qué ofrecer.
2. **El agente agenda** en la conversación. Tu equipo ve la cita en la agenda de watsi y puede confirmarla, moverla o cancelarla.
3. **watsi te avisa** con un webhook por cada cambio, sin que tengas que consultar.

## Los eventos

| Evento                          | Cuándo                                                                              |
| ------------------------------- | ----------------------------------------------------------------------------------- |
| `appointment.created`           | Se agendó una cita nueva                                                            |
| `appointment.rescheduled`       | Una reserva nueva reemplazó a una cita existente (`replacedEventId` es la anterior) |
| `appointment.updated`           | Cambió el horario, los detalles o la confirmación de una cita                       |
| `appointment.cancelled`         | Se canceló una cita                                                                 |
| `action.scheduling_book.failed` | El agente intentó agendar y no pudo (por ejemplo, el horario ya se ocupó)           |

Los cuerpos completos están en el [catálogo de eventos](/webhooks/events).

> **Warning**

Hoy un mismo evento de cita llega con **dos formas** según de dónde venga: las citas que agenda o mueve el agente traen claves en camelCase (`eventId`, `startAt`, `customerId`), y los cambios hechos desde la app traen snake_case (`appointment_id`, `status`). Lee las dos, como en el ejemplo de abajo.

## Recíbelos en tu sistema

### Pide que registren tu endpoint

Los endpoints de webhook los registra el equipo de watsi. Escribe a [support@watsi.ai](mailto:support@watsi.ai) con la URL HTTPS de tu endpoint y los eventos que quieres: los cuatro `appointment.*` y, si te interesa enterarte de los intentos fallidos, `action.scheduling_book.failed`. Pide también un secreto de firma. El paso a paso está en el [tutorial de webhooks](/webhooks/tutorial).

### Escribe el receptor

Verifica la firma sobre el cuerpo sin procesar, deduplica por `X-Watsi-Delivery-Id`, responde `2xx` rápido y procesa después.

```javascript Node.js
import express from 'express'
import { verifyWatsiSignature } from './watsi-signature.js' // ver /webhooks/signing

const app = express()
const seen = new Set() // en producción, una tabla con índice único

app.post('/webhooks/watsi', express.raw({ type: 'application/json' }), (req, res) => {
  if (
    !verifyWatsiSignature(req.body, req.get('x-watsi-signature'), process.env.WATSI_WEBHOOK_SECRET)
  ) {
    return res.sendStatus(401)
  }
  const deliveryId = req.get('x-watsi-delivery-id')
  if (seen.has(deliveryId)) return res.sendStatus(200)
  seen.add(deliveryId)

  const event = req.get('x-watsi-event')
  const body = JSON.parse(req.body.toString('utf8'))
  res.sendStatus(200)

  if (event.startsWith('appointment.')) syncAppointment(event, readAppointment(body))
  if (event === 'action.scheduling_book.failed') alertTeam(body.chat_id, body.error)
})

/** Las dos formas de un evento de cita, en una. */
function readAppointment(body) {
  return {
    id: body.eventId ?? body.appointment_id,
    replacedId: body.replacedEventId ?? null,
    startAt: body.startAt ?? null,
    endAt: body.endAt ?? null,
    customerId: body.customerId ?? null,
    assignedUserId: body.assignedUserId ?? null,
    status: body.status ?? null,
  }
}
```

### Aplica cada cambio

- `appointment.created`: crea la cita en tu sistema con su `id`.
- `appointment.rescheduled`: crea la nueva y marca `replacedId` como reemplazada.
- `appointment.updated`: actualiza sólo los campos que trae; un evento puede traer sólo `id` y la lista de campos que cambiaron.
- `appointment.cancelled`: márcala cancelada (no la borres: puede reaparecer como `replacedId`).

## Bueno saberlo

- **Los horarios son UTC** (`2026-11-04T16:00:00.000Z`). Conviértelos a la zona de tu negocio al mostrarlos.
- **Las entregas pueden repetirse**: watsi reintenta si tu endpoint falla o tarda más de 30 segundos, así que el mismo cambio puede llegar más de una vez. Por eso se deduplica.
- **El orden no está garantizado**: un `appointment.updated` puede llegar antes que el `appointment.created` si el primero se reintentó. Si te importa, guarda el último estado que viste por `id`.
- **La agenda y los recordatorios viven en watsi.** Si además quieres la cita en tu propio calendario, créala desde `syncAppointment`.
