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, en Settings → API Keys, ConvertCore AI te muestra el código listo para pegar. Son dos líneas:

<script src="https://convertcoreai.com/embed.js" data-key="cck_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" async></script>
<button data-convertcore-book>Reservar cita</button>

Hay dos elementos:

  • <script>: carga el widget. Va una sola vez por página, idealmente justo antes de cerrar </body>. Tu API key va en el atributo data-key, no en la URL del script.
  • <button data-convertcore-book>: el botón que abre el modal. Puede ser un <a>, <button>, o cualquier elemento. El atributo data-convertcore-book es lo que el script detecta para abrir la reserva.

El atributo es data-convertcore-book (sin "ing" al final). Tiene que estar escrito exactamente así o el botón no abre nada.

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-book>Reserva tu cita</button>
      <Script
        src="https://convertcoreai.com/embed.js"
        data-key="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-book
  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. Cómo se ve el modal

El modal de reserva hereda automáticamente la identidad de tu workspace:

  • Usa el color primario de tu workspace en botones y acentos. Lo cambias en Settings → Workspace, no en el código del botón.
  • Muestra el nombre de tu negocio en la cabecera.
  • Lista todos tus service calendars y el visitante elige el que quiere al iniciar la reserva.

No tienes que configurar nada extra en el snippet: con pegar el script y el botón, el modal ya sale con la cara de tu negocio.

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.

Alternativa: enlace de página completa

Si no quieres embeber nada, también puedes mandar a tus clientes directo a la página de reserva en pantalla completa. La URL es:

https://convertcoreai.com/embed/TU_API_KEY

Sirve para poner en el link de Instagram, en un botón de WhatsApp, o en cualquier lugar donde no puedas pegar un script. Es el mismo flujo de reserva, pero como página propia en lugar de modal.

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 botón es tu propio HTML — revisa que lo pegaste donde querías. Si el botón aparece pero no hace nada, sigue el punto de abajo.

"El botón aparece pero no abre nada." Tres causas, en orden de probabilidad:

  1. El atributo está mal escrito. Tiene que ser exactamente data-convertcore-book (sin "ing"). Es case-sensitive.
  2. El script no está cargando. Abre las DevTools del navegador (F12), pestaña Network, y busca embed.js. Tiene que devolver 200, no 404. Revisa también que la API key esté en data-key del <script>.
  3. 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-book se vuelve disparador. Puedes tener un botón en hero, otro en mid-page y otro en footer, todos abren el mismo modal.

"¿Puedo dirigir el botón a un calendar específico?" El modal siempre arranca mostrando tus service calendars para que el visitante elija. Si quieres un botón que lleve directo a un solo calendar, hoy la mejor opción es usar el enlace de página completa de ese flujo. Escríbenos si lo necesitas y te ayudamos.

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 data-key del <script> en tu sitio → revocar la vieja en el dashboard. Sin downtime si haces el orden correcto.

Guías relacionadas