Extender el widget

De serie, el asistente responde y llama a tu API. Registrado a través de window.syncanix puede ir más allá: renderizar tus propios componentes dentro del chat, ejecutar acciones en la página actual y mostrar datos en vivo que se mantienen frescos.

Renderiza tus componentes en el chat

registerComponent entrega al asistente un componente que puede renderizar como parte de una respuesta: una tarjeta de pedido, un gráfico, un formulario. Le das un id, el componente y un esquema Zod para sus props; la descripción opcional le dice al modelo cuándo usarlo.

import { z } from 'zod';
import { OrderCard } from './OrderCard';

const OrderCardProps = z.object({ orderId: z.string() });

window.syncanix?.registerComponent('OrderCard', OrderCard, OrderCardProps, {
  description: 'Shows an order summary',
  propDescriptions: { orderId: 'Which order to show' },
});

Las props que aporta el modelo se validan contra tu esquema antes de renderizar nada: una discrepancia se rechaza con claridad en lugar de renderizar algo a medias.

Dale a los componentes el contexto de tu app

Los componentes registrados se renderizan dentro del widget, así que por defecto carecen de los providers de tu app. registerProviders envuelve cada componente renderizado con tu propio wrapper — cliente de datos, router, tema — para que se comporten igual que en el resto de tu app.

window.syncanix?.registerProviders(({ children }) => (
  <ApolloProvider client={apolloClient}>
    <ThemeProvider theme={theme}>{children}</ThemeProvider>
  </ApolloProvider>
));

Deja que el asistente actúe en la página

registerAction expone una función que el asistente puede llamar en la página actual: navegar a algún lugar, recargar una tabla, abrir un panel. Añade un esquema Zod de parámetros cuando la acción reciba argumentos.

window.syncanix?.registerAction('refetch_orders', () => ordersQuery.refetch(), {
  description: 'Reload the orders table with the latest data',
});

window.syncanix?.registerAction('go_to_invoice', ({ id }) => navigate(`/invoices/${id}`), {
  parameters: z.object({ id: z.string() }),
  parameterDescriptions: { id: 'The invoice id to open' },
  description: 'Navigate to a specific invoice',
});

Limita las acciones a la página: regístralas cuando la superficie se monte y anúlalas al desmontar, así el asistente solo ve lo disponible en ese momento. Para acciones con efecto real, pasa confirm: true para que el usuario apruebe antes de ejecutar.

Vincula datos en vivo

registerDataSource permite al asistente mostrar datos siempre actuales: en lugar de fijar una instantánea en su respuesta, referencia tu fuente y el widget llama a tu fetcher al renderizar. Define pollMs (1000 o más) para activar la actualización automática.

window.syncanix?.registerDataSource(
  'open_orders',
  async (params) => ({ rows: await api.orders({ status: 'open', ...params }) }),
  { description: 'Current open orders', pollMs: 30000 },
);

Dile al asistente dónde está el usuario

setContext alimenta el siguiente turno con la página actual, el plan, el carrito o cualquier otro estado de tu app, para que las respuestas reflejen lo que el usuario está viendo. Llámalo de nuevo al navegar: gana el último valor.

window.syncanix?.setContext({
  user: { id: 'u_1', plan: 'pro' },
  page: { path: '/checkout' },
});

¿Sin React? Usa web components

Si tu app no está construida sobre React, el puente @syncanix/web-components envuelve cualquier custom element nativo para que encaje en el mismo flujo de registerComponent:

npm install @syncanix/web-components

import { defineSyncanixComponent } from '@syncanix/web-components';
import { z } from 'zod';

const StatusBadge = defineSyncanixComponent(
  'status-badge',
  StatusBadgeElement, // your HTMLElement subclass
  z.object({ label: z.string(), tone: z.string() }),
);

window.syncanix?.registerComponent('status-badge', StatusBadge, StatusBadge.propsSchema);

Detección automática de acciones

exposePageActions puede descubrir acciones dentro de un ámbito explícito que tú defines — un mapa de rutas para la navegación y elementos que marcas con data-syncanix-action — en lugar de registrar cada una a mano. Está tras el indicador de Labs auto-detect-actions, y cada acción descubierta se informa a tu panel para revisión antes de poder llamarse: la navegación no pide confirmación, los elementos marcados siempre la piden.

Próximos pasos