Del artículo de ayuda a la acción: convierte tus 3 tareas más repetidas en código

Toma el artículo de ayuda que más envías y convierte sus pasos numerados en una función que registra tu página. El título del artículo se vuelve el nombre y la descripción de la acción, cada paso se vuelve una línea de código, y el último paso, el botón que envía, se queda en manos del cliente. A partir de ahí, cuando un cliente lo pide, el asistente hace los pasos en lugar de mandarle el enlace.

Esta guía lo hace una vez, de principio a fin, con “cómo invitar a un compañero”, y luego muestra cómo aplicar la misma receta a tus dos tareas siguientes.

¿Qué artículos de ayuda conviene convertir en acciones?

Solo los que guían a alguien para hacer una tarea, no todos los artículos de ayuda. Un artículo que explica cómo funciona algo (“¿qué diferencia hay entre administrador y miembro?”) es una pregunta, y el asistente puede responderla con tu documentación tal como está. Un artículo que guía a alguien para hacer algo (“cómo invitar a un compañero”) es una tarea, y las tareas son las que acaban en una llamada contigo.

Si todavía no has separado tu bandeja así, Preguntas o tareas: clasifica tu bandeja de soporte en 20 minutos explica cómo. Del montón de tareas, elige tres que sean:

• Repetidas. Las hiciste a mano más de una vez este mes.
• En una pantalla, o casi. Los pasos ocurren en tu app, no en un email a su equipo de sistemas.
• Terminadas en un botón. Hay un momento claro en el que el cliente guarda, envía o confirma.

No des por hecho que el artículo falló porque nadie lo leyó. Harvard Business Review publicó en 2017 que el 81 % de los clientes intenta resolver las cosas por su cuenta antes de contactar con una persona. Normalmente encontraron tu artículo. Se atascaron entre leerlo y hacerlo.

Antes: el artículo

Imagina que tu centro de ayuda tiene este artículo. Es un ejemplo, pero seguramente tienes uno igual:

Cómo invitar a un compañero

1. Ve a Ajustes → Equipo.
2. Haz clic en Invitar miembro.
3. Escribe el email de tu compañero.
4. Elige un rol: Administrador, Miembro o Lector.
5. Haz clic en Enviar invitación.

Cinco pasos, una captura por paso, y aun así uno de los mensajes más frecuentes de tu bandeja. Léelo otra vez como desarrollador y ya es una función: navegar, abrir un diálogo, escribir un email, elegir un rol, pulsar un botón.

¿Cómo se convierte cada paso del artículo en código?

Cada paso se convierte en una línea, porque el SDK de aside tiene una función para cada tipo de paso. La tabla es toda la traducción:

Paso del artículo	Lo que es en realidad	En la acción
1. Ve a Ajustes → Equipo	Navegación	aside.navigate('/settings/team')
2. Haz clic en Invitar miembro	Un clic inofensivo que abre un diálogo	Una función de tu app, o aside.press(...)
3. Escribe el email	Escribir en un campo	aside.fill(..., email)
4. Elige un rol	Un <select> nativo	aside.fill(..., role)
5. Haz clic en Enviar invitación	Envía algo	aside.highlight(...): lo pulsa el cliente

El paso cinco es el que cambia. El artículo le dice al cliente que haga clic en Enviar; la acción lo señala y se detiene. Una acción prepara y el cliente confirma lo que guarda, envía o borra. El porqué está en Preparar, no confirmar.

Marca los controles

Antes de escribir la función, dale a cada elemento que toca un atributo data-aside estable. Las clases cambian en cada rediseño y el texto de los botones cambia con las traducciones; un atributo se queda donde lo pusiste y, si falta, la acción falla de forma visible en lugar de pulsar lo que no es.

<button data-aside="team-invite-open" type="button">Invitar miembro</button>
<input  data-aside="invite-email" type="email" />
<select data-aside="invite-role">
  <option value="admin">Administrador</option>
  <option value="member">Miembro</option>
  <option value="viewer">Lector</option>
</select>
<button data-aside="invite-send" type="submit">Enviar invitación</button>

Después: la acción

Este es el artículo convertido en acción. openInviteDialog representa la función que tu página de Equipo ya llama cuando alguien hace clic en Invitar miembro; el nombre es ilustrativo, usa el que tenga tu app. La función se ejecuta en la página, así que puede llamar a tu propio código directamente.

import { openInviteDialog } from './team/inviteDialog.js'; // la función que ya tiene tu app

const ROLES = ['admin', 'member', 'viewer'];

const actions = [{
  name: 'invite_teammate',
  description: 'Abre el diálogo de invitación en la página de Equipo y rellena el email y el rol. '
    + 'No envía la invitación: el usuario la revisa y pulsa Enviar invitación.',
  inputSchema: {
    type: 'object',
    properties: {
      email: { type: 'string', description: 'El email del compañero' },
      role: { type: 'string', enum: ROLES, description: 'Su rol; member si el usuario no lo dijo' },
    },
    required: ['email'],
  },
  label: 'invitar a un compañero',
  run: async ({ email, role = 'member' }, aside) => {
    if (!email.includes('@')) throw new Error(`"${email}" no es un email. Pídeselo otra vez al usuario.`);
    aside.navigate('/settings/team');
    await aside.waitFor('[data-aside="team-invite-open"]');
    openInviteDialog();
    await aside.fill(await aside.waitFor('[data-aside="invite-email"]'), email);
    await aside.fill('[data-aside="invite-role"]', role);
    aside.highlight('[data-aside="invite-send"]', 12000);
    return { filled: { email, role }, next: 'el usuario la revisa y pulsa Enviar invitación' };
  },
}];

if (window.aside) window.aside.register(actions);
else window.addEventListener('aside:ready', () => window.aside.register(actions), { once: true });

Línea a línea, es el artículo:

• navigate es el paso uno. La página no está lista en el instante en que navegas, así que waitFor espera a que la pantalla del equipo se pinte, y otra vez a que aparezca el campo del diálogo.
• openInviteDialog() es el paso dos, hecho por tu propio código en lugar de un clic simulado. Si prefieres el clic, await aside.press(await aside.waitFor('[data-aside="team-invite-open"]')) también sirve: abrir un diálogo es inofensivo.
• Las dos llamadas a fill son los pasos tres y cuatro. Escriben de forma visible, así que el cliente ve cómo se rellena el formulario en vez de encontrárselo relleno.
• highlight es el paso cinco, convertido en un anillo alrededor del botón. Lo pulsa el cliente.

Hay dos líneas que no están en el artículo, y son importantes. El throw valida el argumento en el borde y le da al modelo una frase que puede repetirle al cliente. El return le dice al modelo lo que falta, así que dice “revisa los datos y pulsa Enviar invitación” en vez de “listo”.

Escribe la descripción para el modelo

Tres campos de ese objeto llegan al modelo: name, description e inputSchema. El modelo elige una acción solo con eso, así que escríbelos como si le explicaras la tarea a un colega:

• El nombre es la intención, no el gesto. invite_teammate, no click_invite_button.
• La descripción dice cuándo usarla y lo que no hace. “No envía la invitación” es la frase que evita que el modelo le diga al cliente que ya está hecho.
• El esquema cierra lo que puede. Un enum para el rol significa que el modelo no puede inventarse un rol “Superadmin”.

label es para personas: aparece como sugerencia en la portada del panel y el modelo nunca la ve. Escríbela como lo pediría el cliente.

La misma receta para la segunda y la tercera tarea

Cuando una acción funciona, las siguientes llevan menos tiempo, porque el patrón no cambia. Esta es la plantilla rellena para dos tareas comunes más. De nuevo, es ilustrativa: usa tus pantallas y tus nombres.

Artículo de ayuda	Nombre de la acción	Argumentos	Lo que rellena la acción	Lo que pulsa el cliente
Cómo invitar a un compañero	invite_teammate	email, rol	Email y rol en el diálogo de invitación	Enviar invitación
Cómo cambiar de plan	change_plan	plan (enum)	El selector de plan en facturación	Confirmar
Cómo conectar alertas de Slack	connect_slack_webhook	URL del webhook, canal	La URL y el canal en la página de la integración	Guardar

La función completa de change_plan está en Preparar, no confirmar.

Para cada una, copia los pasos del artículo en la primera columna de la tabla de traducción, marca los controles y escribe la función. Si un paso nombra algo que existe, como un proyecto o un compañero, búscalo con coincidencia exacta y lanza un error con la lista de candidatos cuando no haya ninguno o haya más de uno. Una coincidencia laxa del tipo “contiene” es como “Jon” acaba siendo “Mary Jones”.

Compruébalo antes que un cliente

No puedes hablar con el asistente desde una terminal, pero sí puedes comprobar cada pieza:

1. En la consola del navegador, window.aside.version devuelve 1: el widget cargó.
2. Llama a la función directamente para verla funcionar sin el modelo. Exporta el array desde su módulo y ejecuta actions.find(a => a.name === 'invite_teammate').run({ email: 'test@example.com' }, window.aside). La página debería navegar, abrir el diálogo y rellenar los dos campos.
3. Luego pídeselo al asistente con palabras: “invita a ana@example.com como lector”.

Busca también press en tus funciones. Cada llamada debería ser sobre una pestaña, un diálogo o un botón de “siguiente”, nunca sobre algo que envía, guarda o borra.

¿Hay que borrar el artículo de ayuda después?

No, no borras el artículo de ayuda. Sigue respondiendo “¿qué puede hacer un lector?”, y aside responde ese tipo de preguntas con tu documentación, con una etiqueta script y sin código. Lo que cambia es la tarea: en lugar de enlazar cinco pasos, el asistente los ejecuta y deja el último clic al cliente. Responder con la documentación no necesita más código que la etiqueta script; las acciones necesitan a alguien que sepa escribir una función, porque lo que se ejecuta es tu código.

El propio dashboard de aside está hecho así: le dices en una frase cómo quieres tu agente y lo configura por ti, con acciones que registra el dashboard, del mismo tipo que las de este post.

Para el panorama completo, con qué funciones exponer y qué no automatizar nunca, lee Cómo dejar que un asistente actúe en tu app sin darle las llaves. Después elige tus tres artículos y empieza por el que más enviaste esta semana.