ConvertCoreAyuda

Embebe el widget de reservas en tu sitio

El widget es una pieza de código que pegas en tu sitio web (WordPress, Webflow, sitio custom, lo que sea) para que tus clientes agenden citas solos. La cita aparece en tu calendar al instante y dispara los workflows que tengas configurados.

Antes de seguir, asegúrate de tener al menos un service calendar configurado. Si no, lee primero Configura tu calendario y evita el double-booking.

Cómo funciona

El widget es un script JavaScript que ConvertCore AI sirve desde nuestros servidores. Lo pegas en tu sitio una sola vez. Cuando un visitante hace click en el botón, se abre un modal con el flujo de reserva:

  1. Elegir tipo de cita (qué service calendar).
  2. Elegir servicio dentro del calendar.
  3. Ver horarios disponibles según working hours y citas existentes.
  4. Elegir un slot.
  5. Llenar datos de contacto (nombre, correo, teléfono).
  6. Confirmar.

La cita queda creada en tu workspace. Se dispara cualquier workflow que tengas con trigger appointment booked. El cliente recibe el correo o WhatsApp de confirmación que tengas configurado.

Paso 1. Genera una API key

Ve a Settings → API Keys en el dashboard. Pulsa Generar nueva API key.

Te pide un nombre descriptivo. Usa algo claro: widget sitio principal, widget landing page agosto, widget WordPress. El nombre solo es para que tú la identifiques después.

Al confirmar verás algo así:

cck_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Importante: este es el único momento en que ConvertCore AI te muestra la API key en texto plano. La base de datos solo guarda el hash SHA-256. Si cierras esa pantalla sin copiar, no hay forma de recuperarla. Tendrás que generar otra.

Copia la key completa al portapapeles. ConvertCore AI te lo recuerda con un botón de Copiar.

Paso 2. Copia el snippet

Justo debajo de la key, ConvertCore AI te muestra el código listo para pegar:

<script src="https://convertcoreai.com/embed.js/cck_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"></script>
<button data-convertcore-booking>Reserva tu cita</button>

Hay dos elementos:

  • <script>: carga el widget. Va una sola vez por página, idealmente justo antes de cerrar </body>.
  • <button data-convertcore-booking>: el botón que abre el modal. Puede ser un <a>, <button>, o cualquier elemento. El atributo data-convertcore-booking es lo que el script detecta.

Paso 3. Pega en tu sitio

En WordPress

  1. Editor del tema → Apariencia → Editor de tema → footer.php. Pega el <script> justo antes de </body>.
  2. Donde quieras que aparezca el botón, usa un bloque de HTML personalizado y pega el <button>.

Alternativa con plugin: instala Insert Headers and Footers y pega el script ahí. Para el botón, usa el bloque HTML del editor de Gutenberg.

En Webflow

  1. Project Settings → Custom Code → Footer Code. Pega el <script>.
  2. En el diseñador, agrega un componente Embed donde quieras el botón y pega el <button>.

En sitio custom (Next.js, Astro, HTML plano)

Pega el <script> antes del cierre de </body> (o en el Head del framework con strategy="afterInteractive" si es Next.js). Pega el <button> donde corresponda en el JSX/HTML.

Ejemplo Next.js

import Script from "next/script";

export default function Page() {
  return (
    <>
      <button data-convertcore-booking>Reserva tu cita</button>
      <Script
        src="https://convertcoreai.com/embed.js/cck_live_..."
        strategy="afterInteractive"
      />
    </>
  );
}

Paso 4. Personaliza el botón

El botón es un elemento HTML normal. Puedes estilizarlo con CSS como cualquier otro:

<button
  data-convertcore-booking
  style="background:#0a0a0a;color:#fff;padding:12px 24px;border-radius:8px;border:none;cursor:pointer"
>
  Agenda tu valoración
</button>

Si tu sitio tiene un sistema de diseño, simplemente aplica las clases que ya usas. El widget no impone estilos al botón.

Paso 5. Personaliza el modal

El modal del widget acepta atributos data- para personalización básica:

<script
  src="https://convertcoreai.com/embed.js/cck_live_..."
  data-color="#ff6b9d"
  data-locale="es"
  data-default-calendar="valoracion"
></script>
AtributoQué haceDefault
data-colorColor primario del modal (botones, acentos)El color del workspace
data-localeIdioma del modal (es o en)es
data-default-calendarSlug del service calendar a preseleccionarEl primero

Paso 6. Prueba el flujo completo

Antes de enviar tráfico real:

  1. Abre tu sitio en una ventana de incógnito.
  2. Haz click en el botón.
  3. Completa una reserva con tu propio correo.
  4. Confirma que aparece en Calendar del dashboard con el color correcto.
  5. Confirma que recibiste el correo o WhatsApp de confirmación.
  6. Cancela esa cita de prueba desde el calendar.

Si los seis pasos pasan, el widget está vivo.

Seguridad: la API key es pública, ¿es seguro?

Sí. La key plain text que el navegador del visitante carga es pública por diseño, igual que las public keys de Stripe o de Maps. Lo que la protege es:

  • Solo permite operaciones de booking (crear cita, listar disponibilidad). No expone contactos, deals, ni nada del workspace.
  • El hash SHA-256 vive en la base de datos. La key plana nunca se guarda. Si alguien hackea nuestra DB, no encuentra tus keys.
  • Rate limit por IP y por key.
  • Revocable en un click. Si la filtras o sospechas abuso, vas a Settings → API Keys, revocas, generas otra y actualizas tu sitio.

Lo único que pasa si tu key se filtra: alguien podría agendar citas falsas. La solución es revocar y rotar. Toma 30 segundos.

Troubleshooting

"No aparece el botón." El data-convertcore-booking es case-sensitive. Tiene que ser exactamente así. También revisa que el script esté cargando — abre las DevTools del navegador (F12), pestaña Network, y busca embed.js. Tiene que devolver 200, no 404.

"El botón aparece pero no abre nada." Casi siempre es CSP (Content Security Policy) bloqueando el script externo. Agrega convertcoreai.com a tu script-src y frame-src.

"El modal carga pero no muestra horarios." El service calendar no tiene staff con working hours configuradas. Vuelve a Configura tu calendario.

"El cliente reserva pero no recibe correo." Configura el template en Settings → Communications → Templates → Confirmación de reserva y conecta tu cuenta de Resend (correo) o Twilio (WhatsApp/SMS). Sin canal configurado, no se envía nada.

"¿Puedo tener varios botones en la misma página?" Sí. Cualquier elemento con data-convertcore-booking se vuelve disparador. Puedes tener un botón en hero, otro en mid-page y otro en footer, todos abren el mismo modal.

"¿Y si quiero un botón distinto que abra un calendar específico?" Usa data-convertcore-booking="slug-del-calendar":

<button data-convertcore-booking="valoracion">Agenda valoración</button>
<button data-convertcore-booking="servicios-spa">Reserva tu spa</button>

Cuándo rotar la API key

  • Si despides a alguien que tenía acceso al código del sitio.
  • Si migras a un nuevo dominio o nueva agencia.
  • Si ves actividad rara: muchas reservas falsas, citas con datos extraños, alertas de rate limit.
  • Cada 6 a 12 meses como buena práctica.

Rotar es: generar nueva key → actualizar el <script src=...> en tu sitio → revocar la vieja en el dashboard. Sin downtime si haces el orden correcto.

Guías relacionadas