Recordatorios

Introducción

Los Pools de Recordatorios permiten programar el envío automático de mensajes de WhatsApp (plantillas o encuestas de satisfacción) antes o después de un evento/cita de un contacto. Cuando el origen de eventos del pool es API Externa, Plazbot genera un API Key único (con prefijo rpk_) para que puedas crear, actualizar, eliminar y listar eventos desde tu propio sistema (ERP, agenda médica, e-commerce, etc.). En esta guía encontrarás:

Cómo autenticarte con el API Key.
Cómo se crean los contactos automáticamente.
Cómo se interpretan las fechas y zonas horarias.
Los 5 endpoints disponibles con ejemplos en curl.

Obtener el API Key

Ve a Automatizaciones → Recordatorios.
Crea o edita un pool de recordatorios.
En Origen de eventos selecciona API Externa.
Copia el API Key generado (formato rpk_...) y el ID del pool que aparece en las URLs de la documentación del modal.

El API Key es secreto. No lo expongas en código del lado del cliente (navegador, apps móviles). Úsalo únicamente desde tu backend.

Autenticación

Todos los endpoints requieren el header x-api-key con el API Key del pool:

-H "x-api-key: rpk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Si el API Key no corresponde al pool indicado en la URL, la API responde 401 UNAUTHORIZED.

Creación automática de contactos

Al crear un evento, Plazbot busca el contacto por su número de teléfono (contactPhone) dentro del workspace:

Si el contacto existe, el evento se agrega a su calendario.
Si el contacto NO existe, se crea automáticamente con estos datos:

Campo	Valor
Nombre	`contactName` del request (si no se envía, se usa el teléfono)
Número de WhatsApp	`contactPhone` del request
Canal	WhatsApp
Visible en el chat	Sí (aparece en el Chat en línea y en la lista de contactos)
Agente asignado	Sin asignar
Etiquetas / Segmentación	Vacías

✅ El contacto creado por la API se comporta igual que cualquier contacto de WhatsApp: aparece en el módulo de Chats, puedes asignarle agentes, etiquetas y verás sus eventos en el calendario del contacto.

Fechas y zona horaria

Las fechas se envían en formato ISO 8601 y se interpretan así:

Sin sufijo Z (ej: "2026-03-15T10:00:00"): se interpretan en la zona horaria del workspace y se convierten internamente a UTC.
Con sufijo Z (ej: "2026-03-15T15:00:00Z"): se consideran ya en UTC y se usan tal cual.
Si no envías endDate, se usa automáticamente startDate + 30 minutos.

Ejemplo: si tu workspace está en UTC-5 (Lima/Bogotá) y envías "2026-03-15T10:00:00", el evento queda registrado a las 10:00 a.m. hora local (15:00 UTC).

Endpoints

La URL base es:

https://api.plazbot.com/api/reminders/{poolId}

Método	Ruta	Descripción
`POST`	`/events`	Crear un evento
`POST`	`/events/bulk`	Crear eventos en lote (máx. 100)
`PUT`	`/events/{eventId}`	Actualizar un evento
`DELETE`	`/events/{eventId}`	Eliminar un evento
`GET`	`/events`	Listar eventos del pool

Crear evento

Crea un evento/cita para un contacto. Si el contacto no existe, se crea automáticamente. Campos del body:

Campo	Tipo	Requerido	Descripción
`contactPhone`	string	✅ Sí	Teléfono de WhatsApp con código de país (ej: `+51999888777`)
`contactName`	string	No	Nombre del contacto (usado solo si el contacto no existe)
`title`	string	✅ Sí	Título del evento
`description`	string	No	Descripción del evento
`startDate`	datetime	✅ Sí	Fecha/hora de inicio
`endDate`	datetime	No	Fecha/hora de fin (por defecto `startDate + 30 min`)

curl -X POST "https://api.plazbot.com/api/reminders/{poolId}/events" \
  -H "Content-Type: application/json" \
  -H "x-api-key: rpk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "contactPhone": "+573001234567",
    "contactName": "Juan Pérez",
    "title": "Cita odontológica",
    "description": "Limpieza dental",
    "startDate": "2026-03-15T10:00:00",
    "endDate": "2026-03-15T10:30:00"
  }'

Respuesta exitosa:

{
  "success": true,
  "code": 200,
  "message": "Evento creado correctamente.",
  "data": {
    "eventId": "a1b2c3d4-...",
    "contactId": "e5f6g7h8-..."
  }
}

Guarda el eventId que retorna la API: lo necesitarás para actualizar o eliminar el evento después.

Crear eventos en lote

Crea múltiples eventos en una sola solicitud. Máximo 100 eventos por request. Los eventos se agrupan por teléfono, por lo que puedes crear varios eventos para el mismo contacto.

curl -X POST "https://api.plazbot.com/api/reminders/{poolId}/events/bulk" \
  -H "Content-Type: application/json" \
  -H "x-api-key: rpk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "events": [
      {
        "contactPhone": "+573001234567",
        "contactName": "Juan Pérez",
        "title": "Cita odontológica",
        "startDate": "2026-03-15T10:00:00"
      },
      {
        "contactPhone": "+573009876543",
        "contactName": "María López",
        "title": "Control mensual",
        "startDate": "2026-03-16T14:00:00",
        "endDate": "2026-03-16T14:30:00"
      }
    ]
  }'

Respuesta: un arreglo con el resultado de cada evento. Si un evento falla la validación (falta title o startDate), no bloquea al resto:

{
  "success": true,
  "code": 200,
  "message": "2 evento(s) creado(s) correctamente.",
  "data": [
    {
      "eventId": "a1b2c3d4-...",
      "contactId": "e5f6g7h8-...",
      "contactPhone": "+573001234567",
      "title": "Cita odontológica",
      "success": true
    },
    {
      "contactPhone": "+573009876543",
      "title": "Control mensual",
      "success": false,
      "error": "title y startDate son requeridos."
    }
  ]
}

Actualizar evento

Actualiza los datos de un evento existente. Solo envía los campos que deseas cambiar; los demás conservan su valor.

curl -X PUT "https://api.plazbot.com/api/reminders/{poolId}/events/{eventId}" \
  -H "Content-Type: application/json" \
  -H "x-api-key: rpk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "title": "Cita reprogramada",
    "startDate": "2026-03-20T15:00:00Z"
  }'

Respuesta exitosa:

{
  "success": true,
  "code": 200,
  "message": "Evento actualizado correctamente.",
  "data": { "eventId": "a1b2c3d4-..." }
}

Eliminar evento

Elimina un evento y cancela sus recordatorios pendientes.

curl -X DELETE "https://api.plazbot.com/api/reminders/{poolId}/events/{eventId}" \
  -H "x-api-key: rpk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Eliminar un evento NO elimina el contacto. El contacto permanece en tu CRM y en el Chat en línea; solo se elimina el evento de su calendario y dejan de enviarse los recordatorios asociados a ese evento.

Listar eventos

Obtiene todos los eventos registrados en el pool.

curl -X GET "https://api.plazbot.com/api/reminders/{poolId}/events" \
  -H "x-api-key: rpk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta:

{
  "success": true,
  "code": 200,
  "data": [
    {
      "eventId": "a1b2c3d4-...",
      "contactId": "e5f6g7h8-...",
      "contactName": "Juan Pérez",
      "contactPhone": "+573001234567",
      "title": "Cita odontológica",
      "description": "Limpieza dental",
      "startDate": "2026-03-15T15:00:00Z",
      "endDate": "2026-03-15T15:30:00Z",
      "eventStatus": "pending",
      "creationDate": "2026-03-01T18:22:10Z"
    }
  ]
}

Las fechas en las respuestas siempre se devuelven en UTC (con sufijo Z).

Envío de recordatorios

Una vez creado el evento, Plazbot envía los recordatorios configurados en el pool de forma automática:

Cada recordatorio define cuándo enviarse: X minutos/horas/días antes del inicio del evento o después de su finalización.
El tipo de acción puede ser una Plantilla de WhatsApp aprobada o una Encuesta de satisfacción.
Cada recordatorio se envía una sola vez por evento (no hay reenvíos duplicados).
El pool debe estar Habilitado para que los recordatorios se envíen.

✅ Puedes combinar recordatorios: por ejemplo, una plantilla de confirmación 24 horas antes de la cita y una encuesta de satisfacción 1 hora después de finalizada.

Códigos de error

Código	Error	Descripción
`200`	—	Operación exitosa
`101`	`MISSING_FIELDS`	Faltan campos requeridos (`contactPhone`, `title`, `startDate` o el header `x-api-key`)
`194`	`DATA_NOT_FOUND`	El evento no existe en este pool
`401`	`UNAUTHORIZED`	API Key inválido o no corresponde al pool
`5000`	`ERROR`	Error interno del servidor

Ejemplo de respuesta de error:

{
  "success": false,
  "code": 401,
  "errorCode": "UNAUTHORIZED",
  "message": "API Key inválida o pool no encontrado.",
  "data": null
}

Introducción

Primeros Pasos

Contactos

Agente de IA

Marketing

Partners Marca Blanca

Legal

Introducción

Obtener el API Key

Autenticación

Creación automática de contactos

Fechas y zona horaria

Endpoints

Crear evento

Crear eventos en lote

Actualizar evento

Eliminar evento

Listar eventos

Envío de recordatorios

Códigos de error

​Introducción

​Obtener el API Key

​Autenticación

​Creación automática de contactos

​Fechas y zona horaria

​Endpoints

​Crear evento

​Crear eventos en lote

​Actualizar evento

​Eliminar evento

​Listar eventos

​Envío de recordatorios

​Códigos de error

Introducción

Obtener el API Key

Autenticación

Creación automática de contactos

Fechas y zona horaria

Endpoints

Crear evento

Crear eventos en lote

Actualizar evento

Eliminar evento

Listar eventos

Envío de recordatorios

Códigos de error