Agendamiento personalizado — conecta tu propio sistema de citas

Qué es

El Agendamiento personalizado permite que la IA agende citas en tu propio sistema: un calendario que no es Calendly ni GoHighLevel, un CRM a medida, una agenda interna o cualquier herramienta a la que puedas poner un par de endpoints delante. Para el lead, la experiencia es la misma que con los otros proveedores: ve los huecos disponibles dentro de la conversación, elige uno, deja su nombre y su email, y la cita queda creada donde tú la gestionas.

Solo necesitas exponer dos URLs HTTPS:

• una URL de disponibilidad, a la que ZeroChats pregunta qué huecos hay libres en un rango de fechas;
• una URL de reserva, a la que ZeroChats manda el hueco elegido y los datos del lead para crear la cita.

Todo lo demás —cuándo ofrecer horarios, cómo presentarlos, recoger los datos y pedir confirmación— lo hace la IA igual que en Programación de citas. Esta página describe la parte que te toca a ti: configurar la pestaña y programar los dos endpoints.

Un proveedor de citas a la vez

Calendly, GoHighLevel y el agendamiento personalizado se excluyen entre sí. Si ya tienes un evento de Calendly o un calendario de GoHighLevel configurado, elimínalo antes de guardar tus endpoints, y al revés.

Cómo se configura

1. Ve a Enlaces de venta en el menú lateral y abre Agendar Automáticamente.

2. Entra en la pestaña Personalizado, junto a las de Calendly y GoHighLevel. Desde ahí, el enlace Ver documentación de los endpoints te trae a esta página.

3. Rellena la URL de disponibilidad y la URL de reserva. Las dos tienen que ser URLs públicas HTTPS. Una dirección localhost, una IP privada o una red interna se rechazan al guardar; para desarrollar en local, expón tu servidor con un túnel (ngrok o similar) y usa la URL que te dé.

4. Añade la API key (opcional). Si la pones, ZeroChats la envía en cada petición como Authorization: Bearer <api key>, y tu servidor puede rechazar cualquier llamada que no la traiga. Se guarda cifrada y no se vuelve a mostrar: después de guardar solo verás una pista con sus últimos caracteres. Para cambiarla, escribe una nueva; también puedes eliminarla.

5. Escribe la Condición de agendamiento. Es la misma regla en lenguaje natural que con Calendly o GoHighLevel: indica cuándo debe la IA ofrecer horarios. Sigue los consejos de cómo redactar la condición.

6. Pulsa Guardar endpoints.

7. Prueba los dos endpoints con Probar disponibilidad y Probar reserva antes de dejar que la IA agende con leads reales. Más abajo tienes qué hace cada prueba.

La API key solo se muestra una vez

En cuanto guardas, la clave desaparece de la pantalla y ZeroChats solo enseña sus últimos caracteres para que sepas cuál está activa. Si la pierdes, escribe una nueva y actualízala en tu servidor.

Probar los endpoints

• Probar disponibilidad llama a tu URL de disponibilidad con un rango de fechas real y te muestra cuántos huecos han vuelto y una muestra de ellos. Si el número no cuadra con tu calendario, revisa el formato de las fechas y el rango que estás leyendo.
• Probar reserva toma el primer hueco que devuelve tu URL de disponibilidad y llama a tu URL de reserva con "test": true y unos datos de contacto de prueba: nombre ZeroChats Test, email [email protected]. Si declaras preguntas, responde las obligatorias con valores de ejemplo (la primera opción, un teléfono de prueba o el texto ZeroChats Test). Tu endpoint puede hacer dos cosas: crear la cita de verdad —y entonces la cancelas tú después— o, cuando test es true, limitarse a validar la petición y responder 2xx sin crear nada.

En los dos casos el resultado muestra el estado HTTP y el message que haya devuelto tu endpoint, para que quien lo programa pueda depurar sin salir de ZeroChats.

Cómo funciona durante la conversación

1. La IA evalúa la condición de agendamiento en cada mensaje.
2. Cuando se cumple, pide huecos a tu URL de disponibilidad y presenta unos pocos, repartidos en distintos días.
3. Recoge el nombre y el email del lead —y las respuestas a tus preguntas, si las declaras— y pide confirmación explícita.
4. Con la confirmación, llama a tu URL de reserva para crear la cita.
5. El lead pasa a Agendado, igual que con Calendly o GoHighLevel.

Si alguno de tus endpoints deja de responder, la IA sigue contestando a los leads, solo que sin ofrecer horarios, y el panel de problemas de tu cuenta te avisa. En cuanto el endpoint vuelve, el agendamiento se reanuda solo.

Contrato de los endpoints

Lo común a los dos

• Método POST con el cuerpo en JSON.
• Cabeceras que envía ZeroChats: Content-Type: application/json, Accept: application/json, User-Agent: ZeroChats-Scheduling/1 y, solo si has configurado una API key, Authorization: Bearer <api key>.
• Tiempo de espera de 10 segundos. Si tu endpoint tarda más, la llamada cuenta como fallida.
• Sin redirecciones. ZeroChats no sigue un 3xx: se trata como un error. Apunta directamente a la URL final.
• La respuesta tiene que ser JSON. Un cuerpo vacío en la reserva vale; un HTML o un texto plano, no.
• Todas las fechas son cadenas ISO 8601. ZeroChats envía instantes en UTC (2026-09-14T09:00:00.000Z). Tu endpoint puede responder con cualquier marca ISO 8601 que lleve desplazamiento horario o Z.
• timezone es la zona horaria IANA configurada en tu negocio (Europe/Madrid, por ejemplo). Se envía por comodidad, por si tu sistema quiere calcular los huecos en hora local.

Endpoint de disponibilidad

Es la URL de disponibilidad. ZeroChats le pide los huecos libres dentro de un rango.

Petición

{
  "start": "2026-09-14T00:00:00.000Z",
  "end": "2026-09-20T23:59:59.000Z",
  "timezone": "Europe/Madrid"
}

ZeroChats pide ventanas de hasta 7 días, empezando mañana. Solo pide semanas posteriores cuando las anteriores han devuelto pocos huecos, hasta aproximadamente un mes vista.

Respuesta

Estado HTTP 200 con la lista de huecos:

{
  "slots": [
    { "start": "2026-09-14T09:00:00.000Z" },
    { "start": "2026-09-14T10:00:00.000Z" },
    { "start": "2026-09-15T16:30:00.000Z" }
  ]
}

Reglas de la respuesta:

• slots es obligatorio. Una lista vacía significa que no hay disponibilidad, y es una respuesta válida.
• Cada elemento necesita start. Cualquier otro campo que añadas se ignora.
• Los huecos fuera del rango pedido, o ya pasados, se descartan.
• La IA no enseña la lista entera: propone unos pocos huecos repartidos en distintos días.

Si el endpoint responde con un estado que no sea 2xx, con un cuerpo que no sea JSON o sin una lista slots válida, la IA no ofrece agendar en esa respuesta y sigue con la conversación.

Preguntas antes de agendar

Si quieres que la IA haga unas preguntas antes de reservar —presupuesto, tipo de negocio, teléfono…—, decláralas en la respuesta de disponibilidad con un campo questions opcional. La IA las hace dentro de la conversación, una por mensaje y en el orden de la lista, no reserva hasta tener las obligatorias y te manda las respuestas en la petición de reserva (campo answers).

{
  "slots": [{ "start": "2026-09-14T09:00:00.000Z" }],
  "questions": [
    {
      "id": "budget",
      "label": "¿Cuál es tu presupuesto mensual?",
      "type": "single_select",
      "required": true,
      "options": ["Menos de 1.000 €", "Entre 1.000 y 5.000 €", "Más de 5.000 €"]
    },
    { "id": "company", "label": "¿Cómo se llama tu empresa?" }
  ]
}

Campo	Qué es
id	Obligatorio. Identificador estable de la pregunta; vuelve tal cual en answers.
label	Obligatorio. La pregunta, como quieres que la entienda la IA.
type	text (por defecto), phone, email, number, date, single_select o multi_select.
required	true si la reserva no puede hacerse sin ella. Por defecto false.
options	Respuestas permitidas de single_select y multi_select. La IA traduce lo que diga el lead a una de ellas y te envía el texto exacto.

• Como máximo 20 preguntas. Si questions no tiene la forma descrita, la respuesta entera se considera inválida y la IA no ofrece agendar.
• ZeroChats usa las preguntas de la primera ventana que pide; repítelas igual en todas.
• Probar disponibilidad te dice cuántas preguntas ha leído.

Endpoint de reserva

Es la URL de reserva. ZeroChats la llama una vez el lead ha confirmado un hueco y ha dejado sus datos.

Petición

{
  "start": "2026-09-14T09:00:00.000Z",
  "timezone": "Europe/Madrid",
  "name": "María García",
  "email": "[email protected]",
  "leadId": "b3f6c1f2-4d0e-4c8a-9d5e-1a2b3c4d5e6f",
  "test": false,
  "answers": [
    { "id": "budget", "question": "¿Cuál es tu presupuesto mensual?", "answer": "Entre 1.000 y 5.000 €" }
  ]
}

Campo	Qué es
start	El hueco elegido, tal como lo devolvió tu endpoint de disponibilidad, normalizado a UTC.
timezone	La zona horaria del negocio.
name	Nombre que ha dado el lead.
email	Email que ha dado el lead.
leadId	Identificador del lead en ZeroChats, el mismo que usa la API de ZeroChats. Es null en las reservas de prueba.
test	true solo cuando la petición viene del botón Probar reserva. Úsalo para validar sin crear nada.
answers	Respuestas a las preguntas que declaraste: un { "id", "question", "answer" } por pregunta respondida. Lista vacía si no declaraste ninguna. En multi_select, una opción por línea.

Respuesta

Estado HTTP 200 o 201. El cuerpo puede ir vacío o incluir enlaces opcionales:

{ "cancelUrl": "https://...", "rescheduleUrl": "https://..." }

Códigos de error

Cuando la reserva no puede completarse, responde con el estado que mejor describa el motivo. La IA reacciona de forma distinta a cada uno:

Estado	Qué significa para ZeroChats	Qué hace la IA
409	El hueco ya no está libre.	Se lo dice al lead y le ofrece otros horarios.
422	Los datos de contacto no son válidos (normalmente el email).	Pide al lead que revise sus datos.
401 / 403	Falta la API key o no es correcta.	No agenda; el problema aparece en el panel.
400	Rechazada por otro motivo.	Le dice al lead que la reserva no se ha completado y le ofrece otros horarios.
5xx, tiempo de espera agotado, cuerpo sin JSON	El sistema no está disponible.	No agenda por ahora.

Cualquier respuesta de error puede incluir { "message": "..." }. ZeroChats lo guarda para el resultado de la prueba y para el diagnóstico, pero nunca se lo enseña al lead: escríbelo pensando en quien mantiene el endpoint.

Ejemplo de flujo

Un centro de fisioterapia gestiona sus citas en un sistema propio y quiere que la IA agende primeras visitas desde Instagram.

1. Configura la condición: «cuando el lead pregunte por disponibilidad o pida cita para una primera visita».
2. Un lead escribe: «¿Tenéis hueco esta semana para una primera visita?».
3. ZeroChats llama a la URL de disponibilidad con el rango de los próximos 7 días. El sistema responde con los huecos libres de las agendas de los fisios.
4. La IA propone tres horarios en días distintos. El lead elige el martes a las 10:00 y deja su nombre y su email.
5. ZeroChats llama a la URL de reserva con ese hueco y los datos. El sistema comprueba que sigue libre, crea la cita y responde 201.
6. La IA confirma la cita en el chat y el lead pasa a Agendado.

Si otro paciente hubiera cogido ese hueco entre el paso 3 y el 5, el sistema respondería 409 y la IA ofrecería alternativas sin que el lead tuviera que empezar de cero.

Buenas prácticas

• Comprueba que el hueco sigue libre antes de responder 2xx. Entre que la IA lo propone y el lead confirma pueden pasar minutos; si ya está ocupado, responde 409 y la IA lo resuelve sola.
• Haz la reserva idempotente. Si tu propia infraestructura reintenta una petición, la misma combinación de leadId y start no debería crear dos citas.
• Responde rápido. Tienes 10 segundos por llamada. Si tu sistema es lento consultando disponibilidad, cachea los huecos unos minutos.
• Trata test: true sin efectos secundarios. Valida la petición y responde 2xx sin crear la cita; así puedes probar la integración cuantas veces quieras sin ensuciar tu calendario.
• Configura la API key aunque la URL sea difícil de adivinar. Sin ella, cualquiera que la descubra puede crear citas en tu sistema.
• Devuelve un message útil en los errores. Lo verás en el resultado de las pruebas y ahorra mucho tiempo de depuración.
• Vuelve a probar con Probar disponibilidad y Probar reserva cada vez que cambies de zona horaria, de URLs o de API key.