# Make Agent Fast documentation (es)

---

# Registro de cambios

Source: /es/docs/account/changelog.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Plataforma&#x22;, icon: &#x22;spark&#x22; }, { label: &#x22;API&#x22;, icon: &#x22;code&#x22; }, { label: &#x22;Documentación&#x22;, icon: &#x22;book&#x22; }]" />

## 2026-08-27 [#2026-08-27]

* Se documentó el lanzamiento desde una URL: la espera durante la generación, **Review & publish**, **Approve & publish** y la activación con el primer chat de un visitante o el primer lead.
* Se documentó la diferencia entre **Usar sitio web** y Claro/Oscuro en Aspecto, y que al guardar el aspecto se actualiza el embed en vivo (y las páginas alojadas que hayan quedado) sin necesidad de volver a publicar.
* Se alinearon los fragmentos de embed con los atributos actuales de `embed.js` y con el parámetro `?v=` del panel, que se usa para evitar la caché.
* Se documentó la conversación por voz en vivo en el probador de la plataforma frente al sitio publicado y al embed.
* Se eliminaron como producto el dominio personalizado, la compra de dominios y los ajustes de subdominio. Inserta el agente en el sitio web que ya tiene tu cliente. Los eventos del complemento de dominio de Polar que hayan quedado se seguirán ignorando o cancelando.

## 2026-07-28 [#2026-07-28]

* Se simplificó el historial de uso para mostrar los créditos finales consumidos en lugar de filas separadas de reserva y reembolso en el registro; el uso mínimo ahora se muestra como `<0.001`.
* Se hizo que las esquinas de selección del menú de acciones de la documentación se adapten a contenido de varias líneas, manteniendo la geometría del activador y del menú.
* Se ampliaron las guías en inglés, coreano y uzbeko sobre la facturación de llamadas en vivo, la entrada de contenido multimedia en el constructor visual, los cambios de subdominio alojado, los controles de privacidad y seguridad de la cuenta, y el feed de eventos de Notificaciones.

## 2026-07-15 [#2026-07-15]

* Se presentó la plataforma de documentación bilingüe de Make Agent Fast.
* Se añadieron, por página, Markdown, descargas, búsqueda y acciones para ChatGPT y Claude.
* Se añadieron `/docs/llms.txt`, `/docs/llms-full.txt` y las rutas canónicas `.md`.
* Se documentaron la API pública, el contrato del SDK, los webhooks, los embeds, los conectores, las operaciones, los precios, la seguridad y la privacidad.
* Se añadieron guías de implementación para los principales frameworks y creadores de sitios web.

## Política de versiones [#política-de-versiones]

Las correcciones de la documentación y los campos adicionales de la API pueden publicarse de forma continua. Los cambios incompatibles en la API pública requieren una nueva ruta principal o un período de migración documentado.

---

# Planes y precios

Source: /es/docs/account/pricing.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ label: &#x22;Launch&#x22;, icon: &#x22;layers&#x22; },
{ label: &#x22;Operate&#x22;, icon: &#x22;spark&#x22; },
{ label: &#x22;Scale&#x22;, icon: &#x22;bolt&#x22; },
{ label: &#x22;Paquetes de créditos&#x22;, icon: &#x22;layers&#x22; }
]"
/>

<TutorialVideo episode="ep08" start="132" />

## Comparación de planes [#comparación-de-planes]

| Plan    | Facturación mensual | Total anual | Créditos mensuales |                    Agents | Voz en vivo | Distintivo de marca |
| ------- | ------------------: | ----------: | -----------------: | ------------------------: | ----------: | ------------------- |
| Launch  |             $15/mes |    $144/año |               1000 |                         1 | No incluida | Obligatorio         |
| Operate |             $35/mes |    $336/año |               3000 |                         3 |  30 min/mes | Se puede quitar     |
| Scale   |             $79/mes |    $758/año |               8000 | Ilimitados, uso razonable |  90 min/mes | Se puede quitar     |

La facturación anual es un 20 % más barata que pagar el precio mensual doce veces. Launch y Operate comienzan con una prueba gratuita de siete días sin tarjeta de crédito; añade una tarjeta después del día 7 para mantener el agente activo. Scale comienza a facturarse de inmediato y no tiene prueba. Cuando se necesita una tarjeta, el proceso de pago muestra el precio exacto, el periodo de renovación, los impuestos y las condiciones antes de la compra.

Launch es un agente integrable y funcional esta misma semana. Operate es el siguiente paso cuando los clientes ya están conversando: voz en vivo, un widget más completo y canales de mensajería. Scale es el estudio completo: todos los controles de Look, roles de equipo y tus propias claves de proveedor.

## Escalera de funciones [#escalera-de-funciones]

| Capacidad               | Launch                                       | Operate                                                  | Scale                                                       |
| ----------------------- | -------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------- |
| Agents                  | 1                                            | 3                                                        | Ilimitados, uso razonable                                   |
| Estudio de widget       | Color de acento, posición, claro/oscuro      | + etiqueta del lanzador, preajustes, colores adicionales | Todos los controles (radio, sombra, borde, fuente, cristal) |
| Idiomas de voz          | 1                                            | 2                                                        | Todos los compatibles                                       |
| Ingesta de conocimiento | Pegar, URL, archivos                         | + YouTube, podcast, RSS                                  | Igual que Operate                                           |
| Canales de mensajería   | Las conexiones existentes siguen funcionando | Nuevas conexiones                                        | Nuevas conexiones                                           |
| Claves propias (BYOK)   | Las claves existentes siguen funcionando     | Las claves existentes siguen funcionando                 | Guardar claves nuevas                                       |
| Invitaciones de equipo  | Los miembros existentes se mantienen         | Los miembros existentes se mantienen                     | Nuevas invitaciones con roles                               |

No vendemos ni asociamos dominios de clientes. Integra el agente en el sitio web que ya tienes.

## Incluido en todos los planes [#incluido-en-todos-los-planes]

Todos los planes actuales incluyen:

* Una integración en el sitio web que ya tienes (`embed.js` + `data-agent`).
* Chat de texto, mensajes de voz, voces predefinidas, recuperación de conocimiento, FAQs y productos estructurados, y captura de leads.
* Integración en sitios web con controles de origen exactos.
* Acceso a la API pública con claves con alcance limitado, OAuth para aplicaciones revisadas, OpenAPI y límites de frecuencia que escalan según el plan.
* Analíticas, conversaciones, seguimiento de uso y la posibilidad de comprar paquetes de créditos.

La asignación de la API pública es de 120 solicitudes por clave de API por minuto en Launch, 600 en Operate y 1800 en Scale. Estos límites de solicitudes no sustituyen los derechos sobre recursos, las comprobaciones de créditos, la idempotencia ni los límites específicos de cada proveedor. Consulta [Límites de frecuencia](/es/docs/api/rate-limits).

## Cómo funcionan los créditos [#cómo-funcionan-los-créditos]

Los créditos pagan el trabajo de IA medido, como la generación, los turnos del agente, los embeddings de conocimiento, la transcripción y la síntesis de voz. No equivalen a un número fijo de mensajes: el proveedor, el modelo, la longitud de entrada y salida, la duración del contenido multimedia y el tipo de operación modifican el coste.

Los créditos mensuales del plan se renuevan en cada periodo de facturación. La asignación mensual no utilizada se acumula durante un ciclo adicional y después caduca. Los créditos de recarga comprados no caducan mientras la suscripción esté activa. Un saldo de créditos positivo no desbloquea una función exclusiva de un plan, como las llamadas en vivo, los sitios adicionales o la eliminación del distintivo.

Las claves de proveedor propias generan cargos aparte de OpenRouter (texto) o Speko (voz), los dos proveedores para los que se puede añadir una clave nueva; las claves directas de proveedores anteriores que ya estén guardadas siguen funcionando hasta que se revoquen. Guardar una clave es exclusivo de Scale. Con tu propia clave, cada acción cuesta una tarifa fija de plataforma (1 crédito por respuesta de chat) en lugar del cargo basado en tokens. BYOK no convierte las facturas del proveedor en créditos de Make Agent Fast ni elimina las comprobaciones de derechos de la plataforma. Consulta [Claves de proveedores de IA](/es/docs/account/provider-keys).

## Derechos de voz [#derechos-de-voz]

Los mensajes de voz están incluidos en todos los planes, pero su transcripción, modelo y síntesis de voz pueden consumir créditos. La voz en tiempo real en vivo usa una asignación mensual de minutos independiente: ninguno en Launch, 30 minutos en Operate y 90 minutos en Scale.

## Agents y marca [#agents-y-marca]

Launch admite un agente de cara al cliente y Operate admite hasta tres. La descripción de agentes ilimitados de Scale está sujeta a uso razonable y no es una invitación a crear un volumen abusivo o automatizado de tenants. Un agente incluye su conocimiento, la configuración de integración, los conectores, las analíticas y los datos de conversación. Cada agente recibe un Agent link, una página de chat pública en su propio subdominio. Las páginas de demostración alojadas que se conservan siguen mostrándose en subdominios; los agentes nuevos no obtienen una página de marketing alojada.

El distintivo de referencia «Made with Make Agent Fast» permanece en Launch. Los owners de Operate y Scale pueden quitarlo de los sitios publicados que tengan ese derecho.

## Paquetes de créditos [#paquetes-de-créditos]

| Compra          |      Precio | Qué cambia                                                   |
| --------------- | ----------: | ------------------------------------------------------------ |
| Paquete pequeño |  $8 una vez | Añade 1000 créditos que no caducan mientras estés suscrito   |
| Paquete mediano | $35 una vez | Añade 5000 créditos que no caducan mientras estés suscrito   |
| Paquete grande  | $90 una vez | Añade 15 000 créditos que no caducan mientras estés suscrito |

Las recargas solo añaden capacidad de uso. No aumentan el número de sitios, los límites de solicitudes de la API, los minutos en vivo ni los permisos de marca.

## Pruebas, renovación y cancelación [#pruebas-renovación-y-cancelación]

La prueba gratuita de Launch y Operate no se convierte automáticamente en una suscripción de pago: el día 7 el agente se pausa hasta que añadas una tarjeta. Una vez registrada una tarjeta, cancelar o un fallo en la renovación puede eliminar el acceso activo tras el periodo o la transición de estado aplicable del proveedor. Las integraciones, los conectores, los clientes de la API y las llamadas de voz pueden dejar de funcionar aunque los datos almacenados del espacio de trabajo se conserven.

## Elige un plan [#elige-un-plan]

* Elige **Launch** para un agente integrado con texto, mensajes de voz y un widget básico.
* Elige **Operate** cuando los clientes empiecen a conversar: llamadas en vivo, canales de mensajería, un widget personalizado, voz en dos idiomas o eliminación del distintivo.
* Elige **Scale** cuando varios agentes estén en producción: todos los controles del widget, voz en todos los idiomas compatibles, roles de equipo y tus propias claves de API.

Haz tus estimaciones a partir de pruebas de aceptación reales, no solo del número de mensajes. Publica un agente representativo, mide el uso de texto, voz y conocimiento, proyecta el tráfico y añade margen para reintentos, conectores, automatizaciones y picos de lanzamiento.

## Fuente de verdad de la facturación [#fuente-de-verdad-de-la-facturación]

El proceso de pago en vivo y el panel de facturación son la fuente de verdad para una compra concreta. Los impuestos, la presentación de la moneda, los métodos de pago, la elegibilidad para la prueba y la redacción del proveedor pueden variar según la ubicación y el estado de la cuenta. Si el proceso de pago difiere de esta página, detente y usa las condiciones del pago o contacta con soporte antes de pagar.

---

# Privacidad y datos

Source: /es/docs/account/privacy.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Datos de los visitantes&#x22;, icon: &#x22;account&#x22; }, { label: &#x22;Retención&#x22;, icon: &#x22;book&#x22; }, { label: &#x22;Controles&#x22;, icon: &#x22;shield&#x22; }]" />

El propietario del sitio decide qué conocimiento, qué datos introducidos por los visitantes y qué integraciones se utilizan en su experiencia. Make Agent Fast procesa los datos de la plataforma para prestar el servicio, conforme a los términos aplicables y al aviso de privacidad.

## Aviso al visitante [#aviso-al-visitante]

Explica el uso de IA, la grabación, la captura de leads, las analíticas y el seguimiento con un lenguaje adecuado a la experiencia y a los requisitos locales. No pidas al agente que recopile datos que no necesites.

## Ciclo de vida de los datos [#ciclo-de-vida-de-los-datos]

Eliminar una fuente afecta a las recuperaciones futuras. Eliminar una credencial detiene el acceso autorizado. Las conversaciones históricas, las exportaciones, los datos de canales externos y los registros de proveedores pueden tener comportamientos de retención independientes.

## Controles del propietario [#controles-del-propietario]

La página **Analíticas** del sitio puede exportar los leads capturados como JSON y eliminar un lead individual. Los informes de analíticas también se pueden exportar como Markdown, Excel o una vista de impresión/PDF. Una exportación crea una copia nueva bajo tu control; eliminar el registro de la plataforma no borra una descarga anterior, una conversación relacionada, un registro de un proveedor externo ni los datos conservados por un requisito legal.

Usa **Configuración de la cuenta** para cerrar sesión en todos los dispositivos o eliminar la cuenta de forma permanente. La eliminación de la cuenta intenta primero detener la suscripción a la plataforma, las suscripciones sobrantes de complementos de dominio de Polar y los recursos de los conectores; después elimina los sitios, agentes, conocimiento, conversaciones, leads, credenciales de API/OAuth, sesiones e historial de facturación almacenado localmente de la cuenta. Si no se puede confirmar que la facturación externa se ha detenido, la eliminación falla de forma segura y deja la cuenta intacta para que puedas reintentarlo sin riesgo o para una revisión del equipo de soporte.

## Solicitudes [#solicitudes]

Usa los controles de autoservicio cuando se ajusten a tu solicitud. Para una solicitud más amplia de acceso, rectificación, exportación o eliminación, recurre al soporte de la cuenta y al proceso descrito en la Política de privacidad vigente. Verifica la identidad de quien realiza la solicitud antes de revelar datos de la cuenta, e incluye las exportaciones posteriores y los proveedores externos en el plan de respuesta.

---

# Claves de proveedores de IA

Source: /es/docs/account/provider-keys.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;spark&#x22;, title: &#x22;Generación de texto&#x22;, description: &#x22;Una sola clave de OpenRouter financia la generación de texto del agente en todos sus modelos.&#x22; },
{ icon: &#x22;voice&#x22;, title: &#x22;Voz&#x22;, description: &#x22;Una sola clave de Speko financia la transcripción y la síntesis de voz.&#x22; },
{ icon: &#x22;shield&#x22;, title: &#x22;Almacenamiento cifrado&#x22;, description: &#x22;Las claves completas se cifran y nunca se vuelven a mostrar después de guardarlas.&#x22; }
]"
/>

Con tu propia clave (BYOK) puedes hacer que las solicitudes de IA compatibles usen tu cuenta con el proveedor de IA. No necesitas una clave: la plataforma proporciona los modelos de forma predeterminada. Guardar una clave requiere el plan Scale. Las claves que ya estén guardadas siguen funcionando en Launch y Operate. Sigues pagando el plan de Make Agent Fast más una tarifa fija de plataforma por acción; el proveedor te factura directamente el uso de sus modelos.

## Proveedores compatibles [#proveedores-compatibles]

Solo se pueden añadir claves nuevas de dos proveedores: uno para texto y otro para voz:

| Proveedor  | Se usa para                                                                | Crear o revisar una clave                                 |
| ---------- | -------------------------------------------------------------------------- | --------------------------------------------------------- |
| OpenRouter | Generación de texto del agente con los modelos a los que OpenRouter enruta | [Claves de API de OpenRouter](https://openrouter.ai/keys) |
| Speko      | Conversión de voz a texto y de texto a voz                                 | [Plataforma de Speko](https://platform.speko.ai)          |

### Claves heredadas [#claves-heredadas]

Las claves directas de proveedores guardadas antes del cambio a OpenRouter y Speko aparecen en **Claves heredadas**. Siguen funcionando hasta que las revoques y todavía puedes revocarlas, pero no puedes añadir ni reemplazar ninguna:

| Proveedor heredado                              | Se usa para                                                                  | Referencia del proveedor                                                                                                                                                                                                                                              |
| ----------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Anthropic, OpenAI, Google Gemini, xAI, DeepSeek | Generación de texto del agente                                               | [Documentación de la API de Anthropic](https://platform.claude.com/docs/en/api/overview), [Guía de inicio rápido de la API de OpenAI](https://developers.openai.com/api/docs/quickstart), [Claves de la API de Gemini](https://ai.google.dev/gemini-api/docs/api-key) |
| Deepgram                                        | Conversión de voz a texto cuando Deepgram es el proveedor de STT configurado | [Claves de API de Deepgram](https://developers.deepgram.com/docs/create-additional-api-keys)                                                                                                                                                                          |
| ElevenLabs                                      | Conversión de texto a voz cuando ElevenLabs está configurado                 | [Autenticación de ElevenLabs](https://elevenlabs.io/docs/api-reference/authentication)                                                                                                                                                                                |

La disponibilidad de proveedores también depende de los proveedores de texto, voz y tiempo real configurados en la plataforma. Guardar una clave válida no obliga a que todas las funciones usen ese proveedor.

<Callout title="BYOK es distinto de una clave de API de Make Agent Fast">
  Una clave de proveedor autoriza cargos y llamadas a modelos en el proveedor de IA externo. Una clave `maf_live_...` autoriza a tu software a llamar a la API pública de Make Agent Fast. Nunca pegues una en el campo de la otra.
</Callout>

## Añadir una clave de proveedor [#añadir-una-clave-de-proveedor]

1. Crea una clave en la consola de OpenRouter o de Speko y activa la facturación del proveedor o un límite de gasto si es necesario.
2. Abre **Panel → Ajustes → Claves de proveedores de IA**. Solo el propietario de facturación de un espacio de trabajo Scale puede guardar una clave.
3. Pega la clave en la tarjeta de **OpenRouter** o de **Speko**.
4. Selecciona **Probar y guardar**.
5. Espera el resultado de la validación y luego prueba la función que usa el proveedor.

Make Agent Fast realiza una solicitud de validación en vivo antes de guardar una clave; no se consumen tokens de modelo ni créditos de la plataforma. La clave no debe contener espacios ni saltos de línea y debe tener entre 16 y 512 caracteres. Las claves de OpenRouter deben empezar por `sk-or-`; las de Speko deben empezar por `sk_speko_` o `sk_live_`. La validación en vivo es la que decide.

Guardar otra clave válida del mismo proveedor reemplaza el valor almacenado anteriormente. Una clave que no supera la validación no se guarda, así que la clave que ya estaba guardada sigue funcionando. El panel solo conserva datos de identificación seguros, como los últimos cuatro caracteres, la fecha de validación y el estado.

## Cómo se selecciona el proveedor de texto [#cómo-se-selecciona-el-proveedor-de-texto]

Para la generación de texto, tiene prioridad una clave activa de OpenRouter. Si no hay ninguna, Make Agent Fast busca una clave heredada activa que coincida con el proveedor de texto configurado en la plataforma y después las demás claves heredadas de texto (Anthropic, OpenAI, Gemini, xAI, DeepSeek) en ese orden. Si no existe ninguna clave BYOK adecuada, usa el proveedor de la plataforma cuando el plan y la implementación lo permitan.

Las claves de voz son específicas de cada proveedor. Una clave de Speko se usa cuando la voz se procesa a través de Speko. Una clave heredada de Deepgram solo se usa cuando el proveedor activo de voz a texto es Deepgram; una clave heredada de ElevenLabs solo se usa cuando la conversión de texto a voz está configurada con ElevenLabs.

Las claves BYOK actualmente no reemplazan las credenciales de embeddings de conocimiento de la plataforma. La ingesta y la recuperación de conocimiento siguen usando el proveedor de embeddings configurado en la implementación.

## Facturación y créditos [#facturación-y-créditos]

* El proveedor externo cobra el uso de tokens de IA a la cuenta que emitió la clave.
* Make Agent Fast sigue cobrando la suscripción más una tarifa fija de plataforma por cada acción que se ejecuta con tu clave: 1 crédito por respuesta de chat en lugar del cargo basado en tokens. La tarifa cubre la recuperación, la orquestación y el alojamiento que rodean la llamada, y no es un porcentaje de tu factura de tokens.
* La tarifa se aplica por cada llamada al proveedor. Los pasos de voz que financia la plataforma (por ejemplo, la transcripción cuando solo tienes una clave de texto) se cobran a la tarifa normal, y las llamadas en vivo siempre usan la tarifa de la plataforma.
* Si se agota la cuota del proveedor, una solicitud puede fallar aunque aún te queden créditos de Make Agent Fast.

Revisa tanto **Uso y créditos** en Make Agent Fast como el panel de uso del propio proveedor.

## Estados de la clave y gestión de errores [#estados-de-la-clave-y-gestión-de-errores]

| Estado    | Significado                                             | Qué hacer                                                                                                                                                |
| --------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `active`  | La validación en vivo fue correcta                      | Prueba la función de destino y supervisa el uso en el proveedor                                                                                          |
| `invalid` | El proveedor rechazó posteriormente la clave almacenada | Revisa la facturación, las restricciones, la cuota y el estado de revocación en el proveedor; después guarda una clave de reemplazo (OpenRouter o Speko) |
| `revoked` | La clave está desactivada en Make Agent Fast            | Guarda una nueva clave de OpenRouter o Speko si quieres que la función siga usando BYOK                                                                  |

Si una solicitud falla porque un proveedor rechaza la credencial o la cuota, Make Agent Fast puede marcar la clave almacenada como no válida. Corregir la clave en el proveedor no revela ni reescribe el secreto almacenado; en el caso de una clave de OpenRouter o Speko, usa **Probar conexión** para volver a comprobarla o guarda de nuevo la clave que funciona. Una clave heredada que pasa a ser no válida no se puede reemplazar por otra clave heredada: en su lugar, migra ese proveedor a OpenRouter o Speko.

## Rotar una clave de proveedor [#rotar-una-clave-de-proveedor]

1. Crea una nueva clave de proveedor sin eliminar la anterior.
2. Guarda la nueva clave en Make Agent Fast y confirma que pasa a estar activa.
3. Prueba el chat de texto o los mensajes de voz, según cuál use ese proveedor.
4. Revoca la clave anterior en la consola del proveedor.
5. Revisa los registros del proveedor por si hubiera un uso inesperado de la clave anterior.

Si una clave queda expuesta en el control de versiones o en código del navegador, revócala de inmediato en el proveedor. Eliminarla únicamente de Make Agent Fast no impide que otra persona que la tenga siga usándola directamente con el proveedor.

---

# Seguridad

Source: /es/docs/account/security.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;shield&#x22;, title: &#x22;Credenciales&#x22;, description: &#x22;Las claves, los secretos de OAuth y los tokens de los conectores permanecen en el servidor.&#x22; },
{ icon: &#x22;embed&#x22;, title: &#x22;Listas de orígenes permitidos para la incrustación&#x22;, description: &#x22;Controla qué orígenes pueden cargar el widget de tu agent.&#x22; },
{ icon: &#x22;link&#x22;, title: &#x22;Webhooks&#x22;, description: &#x22;Verifica las firmas antes de confiar en los eventos entrantes.&#x22; }
]"
/>

## Acceso a la cuenta [#acceso-a-la-cuenta]

Usa una contraseña única, protege la cuenta de correo electrónico que utilizas para la recuperación, cierra las sesiones que no reconozcas y limita quién puede acceder a los sitios en producción.

Verifica el correo electrónico de tu cuenta desde el enlace que se envía después del registro. Las cuentas con contraseña pueden usar **¿Olvidaste tu contraseña?** en la página de inicio de sesión; un restablecimiento correcto revoca las sesiones existentes. En **Configuración de la cuenta** puedes cambiar una contraseña local, vincular Google de forma explícita cuando esté habilitado y cerrar sesión en todos los dispositivos. Las cuentas que solo usan OAuth no tienen una contraseña local que cambiar, y un inicio de sesión normal nunca vincula en silencio una identidad nueva.

## Secretos [#secretos]

Las claves de API, los tokens de los conectores, los secretos de las aplicaciones, los secretos de los webhooks y las claves de los proveedores de voz son credenciales. Guárdalos en un gestor de secretos aprobado, nunca en el código del cliente, y rótalos si quedan expuestos.

## Mínimo privilegio [#mínimo-privilegio]

Elige ámbitos de API acotados, aplicaciones dedicadas en las plataformas externas, orígenes de incrustación precisos y claves distintas para cada sistema. Elimina las credenciales e integraciones que no uses.

## Contenido y privacidad [#contenido-y-privacidad]

Sube solo los datos que el agente tenga permitido usar. Prueba las negativas y las rutas de escalado, y aplica reglas de retención a las exportaciones de conversaciones y de leads.

## Reportes [#reportes]

Si reportas una posible vulnerabilidad, incluye la URL o el componente afectado, el impacto y los pasos para reproducirla, sin acceder a los datos de otros usuarios.

---

# Solución de problemas

Source: /es/docs/account/troubleshooting.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Publicar&#x22;, icon: &#x22;globe&#x22; }, { label: &#x22;Incrustar&#x22;, icon: &#x22;embed&#x22; }, { label: &#x22;Conectores&#x22;, icon: &#x22;connectors&#x22; }]" />

## Empieza con un caso reproducible [#empieza-con-un-caso-reproducible]

Antes de cambiar la configuración, anota:

* El espacio de trabajo/sitio, la ruta pública o el endpoint de la API, y la hora exacta con zona horaria.
* El resultado esperado y el resultado real.
* El navegador/dispositivo o el canal del proveedor externo.
* Si el fallo afecta a la vista previa del propietario, a una página de demostración alojada antigua, al widget incrustado, al conector y/o a la API.
* El texto de estado/error seguro, el `x-request-id` de la respuesta, el último error del conector o el ID del evento de entrega del proveedor.
* La última hora en la que funcionaba y el cambio reciente más pequeño.

No incluyas credenciales en texto plano de la API, del proveedor o del conector, secretos de webhook, datos privados de clientes, cabeceras de autorización completas ni contenido de conversaciones que no sea necesario.

## Los cambios del sitio no aparecen [#los-cambios-del-sitio-no-aparecen]

1. Confirma que la URL del dashboard corresponde al sitio y al espacio de trabajo correctos.
2. Confirma que la acción de guardado indicó que se completó correctamente.
3. Las instrucciones y el conocimiento indexado se aplican a las nuevas conversaciones sin necesidad de volver a publicar. Si el propio widget está oculto, actívalo de nuevo en el menú **Ponlo en marcha** de la página del Agent → **Widget para sitio web** (o en la tarjeta **En tu sitio web** de la pestaña **Resumen**).
4. En los ajustes de **Visualización** (y en la insignia de marca), los cambios se guardan automáticamente y ya actualizan el widget en vivo: no hace falta volver a publicar; abre una ventana privada.
5. Abre un widget incrustado real (o un slug alojado antiguo, si aún tienes alguno) en una ventana privada.
6. Si solo la vista previa social está desactualizada, usa la caché o el depurador de esa plataforma.

Despublicar y editar son cosas distintas. Un conector de mensajería conectado puede seguir respondiendo aunque el widget esté desactivado.

## La respuesta del agente es débil o incorrecta [#la-respuesta-del-agente-es-débil-o-incorrecta]

Haz exactamente la misma pregunta en el probador del propietario y en una conversación pública nueva. Confirma que la fuente de conocimiento relevante está indexada, contiene una respuesta explícita, está actualizada y no entra en conflicto con otra fuente. Revisa las reglas de idioma/personalidad por si hay algún límite que impida la respuesta.

Cuando la fuente no tiene respuesta, mejora el comportamiento de respaldo/escalado en lugar de indicarle al agente que adivine. Usa [Fuentes de conocimiento](/es/docs/build/knowledge) para crear un conjunto de aceptación con preguntas directas, parafraseadas y de límites.

## El lanzador del widget no aparece o está bloqueado [#el-lanzador-del-widget-no-aparece-o-está-bloqueado]

Confirma que el sitio está publicado, que la incrustación está habilitada, que el script tiene el slug exacto del sitio y que el origen padre final del navegador (incluidos esquema, nombre de host y puerto) está en la lista de permitidos. En DevTools, inspecciona la solicitud de `embed.js`, los errores de CSP, el estado del gestor de consentimiento, la solicitud del iframe y la presencia de una única raíz `data-maf-embed`.

Si el texto funciona pero el micrófono no, comprueba HTTPS, el permiso del navegador, el permiso `allow` del iframe y la Permissions Policy del sitio anfitrión. Sigue la guía completa de [Resumen de la incrustación](/es/docs/embed/overview) y [Seguridad y CSP](/es/docs/embed/security).

## La voz no funciona [#la-voz-no-funciona]

Separa el modo que falla: mensaje de voz, llamada en vivo o voz del conector. Que la vía de texto funcione solo demuestra que la clave del modelo de lenguaje es correcta.

Comprueba por separado las claves del proveedor de transcripción, de TTS y de tiempo real; después revisa el derecho del plan, el saldo de créditos, la asignación de minutos en vivo, el permiso del navegador y los idiomas configurados. Prueba con una grabación corta y limpia antes de investigar un archivo largo o con ruido.

## El conector no recibe mensajes [#el-conector-no-recibe-mensajes]

Usa la guía del canal y compara ambos lados. Confirma que el conector está habilitado, que las credenciales siguen validándose, que la URL de webhook/interacción/skill del proveedor es la actual, que el evento/Página/número/bloque necesario está suscrito, que el modo de la aplicación incluye al usuario de prueba y que la entrega por HTTPS público funciona.

Que la verificación del webhook tenga éxito no demuestra que la suscripción a eventos en tiempo de ejecución ni los permisos de salida sean correctos. Compara los registros de entrega del proveedor con **Último mensaje** y con el error guardado del conector. Prueba primero el texto y después la voz.

## No se ofrecen dominios personalizados [#no-se-ofrecen-dominios-personalizados]

No vendemos ni asociamos dominios de customers. Coloca el agente en el sitio que ya tienes mediante la [incrustación](/es/docs/embed/overview). Los eventos antiguos del complemento de dominio de Polar se ignoran o se cancelan y nunca generan credits.

## Falla una solicitud a la API [#falla-una-solicitud-a-la-api]

Registra el método, la ruta con versión, el estado, el código de error estable, el `x-request-id` de la respuesta y las cabeceras de límite de frecuencia relevantes. Después clasifica:

| Estado | Acción más probable                                                                                  |
| ------ | ---------------------------------------------------------------------------------------------------- |
| `400`  | Corrige la forma del JSON/formulario o los detalles de validación; no reintentes sin cambios         |
| `401`  | Usa una credencial MAF válida, no caducada ni revocada; nunca uses una clave de proveedor            |
| `403`  | Añade el scope necesario o restablece el acceso al plan/recurso                                      |
| `404`  | Confirma que el ID pertenece al espacio de trabajo autenticado y que la ruta es correcta             |
| `409`  | Resuelve el conflicto de estado o reenvía la misma clave de idempotencia/carga útil                  |
| `415`  | Envía el tipo de contenido documentado                                                               |
| `429`  | Respeta las cabeceras `retry-after`/de restablecimiento con jitter; no hagas bucles de espera activa |
| `500`  | Reintenta una solicitud segura/idempotente y conserva el ID de la solicitud y la hora                |

Usa [Credenciales y tokens](/es/docs/api/credentials), [Scopes y errores](/es/docs/api/scopes-errors) y [Límites de frecuencia](/es/docs/api/rate-limits). Nunca resuelvas un error de la API moviendo una credencial de servidor al código del navegador.

## La facturación o el uso parecen incorrectos [#la-facturación-o-el-uso-parecen-incorrectos]

Distingue entre acceso a la plataforma, créditos mensuales, créditos comprados, número de sitios, minutos en vivo, frecuencia de la API, canales de mensajería (Operate+) y BYOK/team members (Scale). Una recarga solo cambia los credits. Los cargos del proveedor con BYOK son independientes de la facturación de Make Agent Fast.

Ante un uso inesperado, contén la fuente probable antes de investigar: desactiva un conector, revoca una clave, elimina un origen de incrustación no deseado o detén un bucle de reintentos de la API. Conserva el intervalo de tiempo y los ID de solicitud/proveedor sin exponer secretos.

## Reúne detalles seguros para el soporte [#reúne-detalles-seguros-para-el-soporte]

Si sigues bloqueado, usa el control de comentarios de la guía más relevante o contacta con soporte desde el dashboard con:

* El identificador del sitio/espacio de trabajo y la función afectada.
* La marca de tiempo exacta con zona horaria y los pasos reproducibles.
* El resultado esperado frente al real.
* La URL pública sin secretos, cuando sea relevante.
* El estado HTTP, el código de error estable, el `x-request-id` o el ID del evento del proveedor.
* Una captura de pantalla censurada o una carga útil mínima sin secretos ni datos personales.

Indica lo que ya has comprobado. Así evitas que te repitan consejos de configuración y se delimita claramente dónde está el fallo.

---

# Autenticación

Source: /es/docs/api/authentication.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;shield&#x22;, title: &#x22;Claves de API&#x22;, description: &#x22;Credenciales bearer con permisos limitados para una cuenta y un servidor que tú controlas.&#x22; },
{ icon: &#x22;account&#x22;, title: &#x22;OAuth&#x22;, description: &#x22;Autorización revisada para aplicaciones que se conectan a varias cuentas de clientes.&#x22; },
{ icon: &#x22;layers&#x22;, title: &#x22;Mínimo privilegio&#x22;, description: &#x22;Cada operación indica el permiso exacto de lectura o escritura que necesita.&#x22; }
]"
/>

Usa una clave de API para tu propio backend o para automatizaciones. Usa OAuth cuando tu aplicación pida a otros usuarios de Make Agent Fast que le concedan acceso. Ambos tipos de credenciales llaman a los mismos recursos de `/api/v1` y respetan los mismos permisos, derechos del plan, aislamiento entre tenants y límites de frecuencia.

## Claves de API [#claves-de-api]

Se requiere un plan de pago activo para crear y usar una clave de API pública.

1. Abre **Panel → Ajustes → Desarrollador**.
2. Introduce un nombre que identifique el servicio y el entorno, como `Production lead export`.
3. Selecciona los permisos mínimos que necesita el servicio.
4. Elige una caducidad: 30 días, 90 días, un año o sin caducidad.
5. Crea la clave y copia de inmediato el valor `maf_live_...`.

Make Agent Fast almacena un hash SHA-256 en lugar de texto plano recuperable. Más adelante, el panel muestra un prefijo seguro, los permisos, la caducidad, la fecha de último uso y el estado de revocación.

```http
Authorization: Bearer maf_live_...
```

Envía el encabezado desde código de servidor:

```bash
curl --fail-with-body https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"
```

Si faltan las credenciales, se devuelve `401 authentication_required`. Las claves no válidas, caducadas o revocadas devuelven `401 invalid_api_key`. Una clave cuya cuenta ya no tiene un plan de pago activo devuelve `403 subscription_required`.

### Rotar o revocar una clave [#rotar-o-revocar-una-clave]

Crea una clave de reemplazo antes de revocar la anterior. Despliega la nueva clave, haz una solicitud real, verifica su `x-request-id` y después haz clic en **Revocar** en la clave anterior. La revocación es inmediata y no se puede deshacer.

En los ajustes de **Desarrollador**, **Editar** te permite cambiar el nombre y los permisos de una clave activa; el cambio se aplica de inmediato a esa misma clave. No se pueden cambiar su caducidad ni su token: crea una clave de reemplazo para obtener una nueva caducidad o un token rotado.

## Aplicaciones OAuth [#aplicaciones-oauth]

OAuth está pensado para software que se conecta a cuentas que pertenecen a otros usuarios de Make Agent Fast. Utiliza Authorization Code con PKCE (`S256`) y no emite ni requiere un client secret. El client ID es público; los códigos de autorización, los tokens de acceso, los tokens de actualización y el verificador PKCE son información sensible.

### 1. Registra la aplicación [#1-registra-la-aplicación]

Abre **Panel → Ajustes → Desarrollador → Aplicaciones OAuth**. Añade:

* Un nombre de aplicación de entre 2 y 100 caracteres.
* Entre 1 y 10 URL de redirección exactas.
* Los permisos máximos que tu aplicación puede solicitar.

Las URL de redirección en producción deben usar HTTPS y no pueden contener credenciales ni fragmentos. El URI completo debe coincidir con un valor registrado durante la autorización y el intercambio del token. Las aplicaciones recién enviadas tienen el estado `pending`; la autorización solo funciona después de que la aplicación se revise y se marque como `approved`.

El propietario de la plataforma revisa los client ID pendientes con el flujo auditado `oauth:review`. Conserva el client ID que se muestra tras el envío; su estado es visible en la página de Desarrollador, y las aplicaciones rechazadas incluyen la decisión de revisión antes de poder volver a enviarse.

### 2. Genera los valores PKCE [#2-genera-los-valores-pkce]

Genera un verificador nuevo para cada intento de autorización y guárdalo en la misma sesión protegida y de corta duración que `state`.

```ts
import { createHash, randomBytes } from "node:crypto";

const verifier = randomBytes(48).toString("base64url");
const challenge = createHash("sha256").update(verifier).digest("base64url");
const state = randomBytes(24).toString("base64url");
```

El verificador debe contener entre 43 y 128 caracteres PKCE seguros para URL. Solo se acepta `code_challenge_method=S256`.

### 3. Redirige al usuario para que dé su consentimiento [#3-redirige-al-usuario-para-que-dé-su-consentimiento]

```text
https://makeagent.fast/oauth/authorize
  ?client_id=maf_app_...
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
  &response_type=code
  &scope=sites%3Aread%20leads%3Aread
  &state=RANDOM_STATE
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256
```

El usuario inicia sesión, revisa los permisos solicitados y permite o deniega el acceso. Si lo permite, Make Agent Fast redirige al URI registrado exacto con `code` y el `state` original. Si lo deniega, envía `error=access_denied` y el `state` original cuando se haya proporcionado uno.

Rechaza el callback si `state` no coincide exactamente con el valor almacenado para esa sesión del navegador.

### 4. Intercambia el código de autorización [#4-intercambia-el-código-de-autorización]

El código de autorización caduca a los 10 minutos y solo puede usarse una vez.

```bash
curl --fail-with-body https://makeagent.fast/api/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=maf_app_..." \
  --data-urlencode "code=$AUTHORIZATION_CODE" \
  --data-urlencode "redirect_uri=https://app.example.com/oauth/callback" \
  --data-urlencode "code_verifier=$PKCE_VERIFIER"
```

```json
{
  "access_token": "maf_live_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "maf_refresh_...",
  "scope": "sites:read leads:read"
}
```

El token de acceso dura una hora. El token de actualización dura hasta 90 días, salvo que se rote o se revoque antes.

### 5. Rota el token de actualización [#5-rota-el-token-de-actualización]

Cada actualización correcta revoca tanto el token de actualización enviado como su token de acceso anterior, y devuelve un nuevo par. Guarda el nuevo par de forma atómica antes de descartar el estado de la respuesta anterior.

```bash
curl --fail-with-body https://makeagent.fast/api/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=maf_app_..." \
  --data-urlencode "refresh_token=$REFRESH_TOKEN"
```

Reutilizar un código de autorización o un token de actualización ya rotado devuelve `invalid_grant`. El endpoint de tokens de OAuth devuelve respuestas de estilo OAuth `{ "error", "error_description" }` en lugar del envoltorio de errores de la API pública, y permite 30 solicitudes de token por dirección IP del solicitante por minuto.

## Nunca autentiques solicitudes de gestión en código de navegador [#nunca-autentiques-solicitudes-de-gestión-en-código-de-navegador]

No incluyas una clave de API secreta, un token de acceso ni un token de actualización en componentes cliente de React, JavaScript estático, web móvil, Webflow, Framer, Wix ni Shopify Liquid. Usa tu backend autenticado. La inserción pública del sitio web utiliza un slug de sitio no secreto y una lista de orígenes permitidos, no credenciales de la API de gestión.

Consulta [Credenciales y tokens](/es/docs/api/credentials), [Permisos y errores](/es/docs/api/scopes-errors) y [Guía de inicio rápido de la API](/es/docs/api/quickstart).

---

# Credenciales y tokens

Source: /es/docs/api/credentials.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;shield&#x22;, title: &#x22;Credenciales de servidor&#x22;, description: &#x22;Las claves de API y los tokens de OAuth autorizan el acceso a la API pública.&#x22; },
{ icon: &#x22;connectors&#x22;, title: &#x22;Credenciales de canal&#x22;, description: &#x22;Los tokens de bot y los secretos de aplicación conectan proveedores de mensajería externos.&#x22; },
{ icon: &#x22;voice&#x22;, title: &#x22;Claves de proveedor&#x22;, description: &#x22;Las credenciales BYOK pagan a los proveedores de IA desde tu propia cuenta de proveedor.&#x22; }
]"
/>

Make Agent Fast utiliza varios tipos de credenciales. No son intercambiables. Antes de copiar un valor, identifica qué sistema lo emitió, qué sistema lo recibe y si es seguro exponerlo en un navegador.

## Mapa de credenciales [#mapa-de-credenciales]

| Credencial                                        | Se crea en                                         | La utiliza                                     | ¿Es secreta? | Formato o valor habitual                |
| ------------------------------------------------- | -------------------------------------------------- | ---------------------------------------------- | ------------ | --------------------------------------- |
| Slug del sitio publicado                          | Panel del sitio                                    | Cargador del código incrustado en el sitio web | No           | `my-agent`                              |
| Clave de API de Make Agent Fast                   | **Ajustes → Desarrollador**                        | Tu backend o automatización                    | Sí           | `maf_live_...`                          |
| ID de cliente de OAuth                            | **Ajustes → Desarrollador**                        | Aplicación multicuenta                         | No           | `maf_app_...`                           |
| Token de acceso de OAuth                          | Endpoint de tokens de OAuth                        | El backend de tu aplicación                    | Sí           | Token Bearer, con una hora de validez   |
| Token de actualización de OAuth                   | Endpoint de tokens de OAuth                        | Tu almacén seguro de tokens                    | Sí           | `maf_refresh_...`, se rota con cada uso |
| Clave de API de proveedor de IA (opcional, Scale) | OpenRouter (texto) o Speko (voz)                   | Backend de Make Agent Fast                     | Sí           | `sk-or-...` o `sk_speko_...`            |
| Token de conector o secreto de aplicación         | Telegram, Meta, Discord o Kakao                    | Servicio de conectores de Make Agent Fast      | Sí           | Depende del proveedor                   |
| Secreto de firma de webhook                       | Creación del endpoint de webhook de la API pública | Tu receptor de webhooks                        | Sí           | `whsec_...`                             |

<Callout title="El código incrustado en el sitio web no usa una clave de API">
  El cargador del código incrustado necesita un slug de sitio público y un origen de sitio web permitido. No añadas nunca una clave de API de Make Agent Fast, una clave de proveedor, un token de conector ni un secreto de webhook a la etiqueta script.
</Callout>

## Elige el método de autorización adecuado [#elige-el-método-de-autorización-adecuado]

Usa una **clave de API de Make Agent Fast** para un servidor que controles y una única cuenta de Make Agent Fast. Elige solo los permisos (scopes) que ese servidor necesite.

Usa **OAuth Authorization Code con PKCE** cuando tu producto conecte cuentas que pertenecen a otros usuarios de Make Agent Fast. Las aplicaciones OAuth requieren revisión antes de que la autorización en producción se complete correctamente.

Usa una **clave de proveedor de IA** solo cuando quieras que Make Agent Fast llame a ese proveedor de IA con cargo a tu cuenta de proveedor. Una clave de proveedor no autoriza la API pública de Make Agent Fast.

Usa las **credenciales de conector** únicamente en el formulario de conector correspondiente o en la solicitud a la API del conector. Un token de bot de Telegram no puede autorizar solicitudes a Discord, Meta ni a la API de Make Agent Fast.

## Almacena los secretos de forma segura [#almacena-los-secretos-de-forma-segura]

Para el desarrollo local, coloca los secretos en un archivo de entorno ignorado por Git o en el entorno de tu shell:

```bash
export MAF_API_KEY="maf_live_..."
```

Para el despliegue, usa el gestor de secretos cifrado de tu proveedor de alojamiento. No pongas secretos en:

* Commits de Git, descripciones de incidencias, capturas de pantalla, propiedades de analítica ni mensajes de soporte.
* `NEXT_PUBLIC_*`, `VITE_*` u otras variables incluidas en el JavaScript del navegador.
* Webflow, Framer, Wix, Shopify Liquid, HTML de WordPress ni un bundle web móvil.
* Cadenas de consulta (query strings). Las URL suelen conservarse en el historial del navegador, en proxies y en registros.

Realiza las llamadas a la API a través de tu backend autenticado. El navegador debe llamar a tu backend, y tu backend debe adjuntar el secreto.

```ts
const response = await fetch("https://makeagent.fast/api/v1/sites", {
  headers: { Authorization: `Bearer ${process.env.MAF_API_KEY}` },
});
```

## Reglas de los secretos de un solo uso [#reglas-de-los-secretos-de-un-solo-uso]

Las claves de API, los secretos de firma de webhook y los tokens de actualización de OAuth recién emitidos deben copiarse en el momento en que se muestran. El valor completo en texto plano no se puede recuperar más tarde. Si lo pierdes, crea uno de reemplazo en lugar de pedir al soporte que te lo revele.

Las credenciales de proveedores de IA y de conectores se cifran antes de almacenarse y no se devuelven a través de las API de listado. El panel puede mostrar una etiqueta, un prefijo, los últimos cuatro caracteres, el estado de validación o la hora del último uso para que puedas identificar una credencial sin exponerla.

## Lista de comprobación para la rotación [#lista-de-comprobación-para-la-rotación]

1. Crea la credencial de reemplazo con los mismos permisos mínimos (scopes) o permisos de proveedor.
2. Actualiza un despliegue o receptor a la vez.
3. Verifica que una solicitud real se realiza correctamente y registra su `x-request-id`.
4. Revoca la credencial anterior.
5. Confirma que las solicitudes antiguas fallan con `401 invalid_api_key` o con el error equivalente del proveedor.

En el caso de OAuth, guarda el nuevo token de actualización que devuelve cada respuesta de actualización antes de descartar el token anterior. Para la rotación del secreto de webhook, ejecuta los endpoints antiguo y nuevo en paralelo hasta que todos los emisores y receptores usen el de reemplazo.

## Si un secreto queda expuesto [#si-un-secreto-queda-expuesto]

Revócalo o rótalo de inmediato. Eliminarlo del último commit de Git no es suficiente, porque puede permanecer en el historial, en cachés, en registros o en forks. Revisa la actividad tanto en Make Agent Fast como en el proveedor que emitió la credencial, y reemplaza cualquier credencial que compartiera la misma ubicación de almacenamiento o el mismo entorno de despliegue.

Continúa con [Autenticación](/es/docs/api/authentication), [Permisos y errores](/es/docs/api/scopes-errors) o [Claves de proveedor de IA](/es/docs/account/provider-keys).

---

# Descripción general de la API

Source: /es/docs/api/overview.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/api/authentication&#x22;, label: &#x22;Autenticación&#x22;, icon: &#x22;shield&#x22; },
{ href: &#x22;/es/docs/api/quickstart&#x22;, label: &#x22;Inicio rápido&#x22;, icon: &#x22;bolt&#x22; },
{ href: &#x22;/es/docs/api/reference&#x22;, label: &#x22;Referencia&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/es/docs/api/webhooks&#x22;, label: &#x22;Webhooks&#x22;, icon: &#x22;link&#x22; },
{ href: &#x22;/es/docs/api/sdks&#x22;, label: &#x22;SDK&#x22;, icon: &#x22;code&#x22; }
]"
/>

La API pública utiliza JSON orientado a recursos sobre HTTPS bajo `/api/v1`. Está disponible en los planes de pago y utiliza los mismos derechos de acceso a sitios, créditos y funcionalidades que el panel de control.

## Qué puedes automatizar [#qué-puedes-automatizar]

* Sitios y estado de publicación
* Configuración del agente, preguntas frecuentes, productos y conocimiento
* Conversaciones (incluidas las respuestas del propietario, la pausa y la reanudación), leads, analíticas, notificaciones y difusiones
* Creación de leads y consentimiento, pipelines de oportunidades, resultados de CRM y recuperación de sincronización
* Connectors, monetización, tickets, equipo, uso e información de la cuenta
* Suscripciones a webhooks firmados para los eventos compatibles

Las acciones sensibles utilizan endpoints de acción explícitos en lugar de una modificación sin restricciones de la base de datos. Los secretos de los connectors se aceptan al escribir, pero nunca se devuelven.

Esta es una **API de gestión y sincronización**. Puede crear y actualizar leads,
aceptarlos en un pipeline de oportunidades, importar resultados de CRM ganados o perdidos
con atribución de origen, reintentar las importaciones de resultados fallidas y responder a un visitante
como el negocio, pausando y reanudando el agente en esa conversación. Enviar mensajes como el visitante
sigue siendo una operación del widget; las analíticas y el uso siguen siendo de solo lectura. Los dominios
personalizados se han eliminado y las rutas `/domains` devuelven `409`.

## Empieza de forma segura [#empieza-de-forma-segura]

Crea una clave con alcance limitado en el panel de control, llama al endpoint de la cuenta actual y después desarrolla sobre un sitio de prueba antes de tocar el contenido de producción.

```bash
curl https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer maf_live_YOUR_KEY"
```

Consulta [Autenticación](/es/docs/api/authentication), el [inicio rápido de la API](/es/docs/api/quickstart) y la [referencia de la API](/es/docs/api/reference).

---

# Guía de inicio rápido de la API

Source: /es/docs/api/quickstart.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;10 minutos&#x22;, icon: &#x22;bolt&#x22; }, { label: &#x22;Solo servidor&#x22;, icon: &#x22;shield&#x22; }, { label: &#x22;REST&#x22;, icon: &#x22;code&#x22; }]" />

Esta guía de inicio rápido verifica que un backend pueda autenticarse y leer tu cuenta. Necesitas un plan de pago activo, una terminal con `curl` y acceso a **Panel → Ajustes → Desarrollador**.

La API v1 actual gestiona y sincroniza recursos. No es un medio de transporte
para chats personalizados: no puedes enviar mensajes como si fueras un visitante. Los leads se pueden crear, actualizar
y aceptar (`leads:write`), y un propietario puede responder a una conversación, pausarla o reanudarla
(`conversations:write`).

## 1. Crea una clave con privilegios mínimos [#1-crea-una-clave-con-privilegios-mínimos]

Crea una clave llamada `Local API quickstart`, selecciona `account:read` y `sites:read`, y elige una caducidad corta. Copia la clave en texto plano de inmediato; no se volverá a mostrar.

No uses una clave de proveedor de IA, como una clave de OpenRouter o de Speko. La API pública requiere una clave de Make Agent Fast que comience por `maf_live_`.

## 2. Guárdala para esta terminal [#2-guárdala-para-esta-terminal]

```bash
export MAF_API_KEY="maf_live_..."
```

Confirma que la variable existe sin imprimir el secreto:

```bash
test -n "$MAF_API_KEY" && echo "MAF_API_KEY is set"
```

No incluyas la clave en `.env`, en ejemplos del historial de la shell, en datos de prueba ni en un bundle del navegador. Para el código desplegado, usa el gestor de secretos de tu proveedor de alojamiento.

## 3. Inspecciona la cuenta [#3-inspecciona-la-cuenta]

```bash
curl --fail-with-body --include https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"
```

Estado esperado: `200 OK`. El cuerpo contiene `data.id`, información del plan y de los derechos de uso, y un resumen del monedero. La respuesta también incluye `x-request-id`; conserva ese valor al reportar una solicitud fallida.

```json
{
  "data": {
    "id": "ACCOUNT_ID",
    "email": "owner@example.com",
    "plan": { "id": "pro", "status": "active" },
    "entitlements": { "site_limit": 3, "live_voice": true },
    "wallet": { "balance": 151 }
  }
}
```

Se pueden añadir campos sin cambiar la ruta `/v1`. Ignora los campos desconocidos en lugar de rechazar la respuesta.

## 4. Lista los sitios [#4-lista-los-sitios]

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites?limit=20" \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"
```

Las respuestas de colecciones usan esta estructura:

```json
{
  "data": [],
  "has_more": false,
  "next_cursor": null
}
```

Si `has_more` es true, envía el valor exacto de `next_cursor` como parámetro de consulta `cursor` en la siguiente solicitud. No decodifiques ni construyas cursores.

## 5. Gestiona un error estructurado [#5-gestiona-un-error-estructurado]

Quita temporalmente el encabezado Authorization y repite la solicitud a `/me`. La respuesta debería ser `401` con un código estable:

```json
{
  "error": {
    "code": "authentication_required",
    "message": "Provide an API key in the Authorization bearer header.",
    "request_id": "6c0b2f2e-..."
  }
}
```

El código de producción debe ramificarse según `error.code`, no comparar `message`. Registra la operación, el estado HTTP y el ID de solicitud sin registrar la clave.

## 6. Realiza la primera escritura de forma segura [#6-realiza-la-primera-escritura-de-forma-segura]

Crea una clave aparte que además tenga `sites:write`, `agents:write` y `knowledge:write`; no amplíes la clave de lectura de esta guía. Sigue las [recetas de la API](/es/docs/api/recipes) para crear un sitio, añadir conocimiento fundamentado y publicarlo usando claves de idempotencia explícitas.

## Errores habituales en la primera solicitud [#errores-habituales-en-la-primera-solicitud]

| Resultado                     | Causa                                                                             | Solución                                                              |
| ----------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `401 authentication_required` | Falta el encabezado o no tiene el formato `Bearer TOKEN`                          | Añade el encabezado Authorization exacto desde el código del servidor |
| `401 invalid_api_key`         | Error tipográfico, clave caducada, clave revocada o tipo de credencial incorrecto | Crea y copia una nueva clave de API de Make Agent Fast                |
| `403 subscription_required`   | No hay un plan de pago activo                                                     | Restablece la suscripción de la cuenta                                |
| `403 insufficient_scope`      | La clave no incluye el scope de la operación                                      | Crea una clave de reemplazo con el scope mínimo que falta             |
| `403 account_paused`          | El acceso a la API se pausó para esta cuenta                                      | Reanuda el acceso a la API o contacta con el propietario de la cuenta |
| `429 rate_limit_exceeded`     | Se agotó el límite de un minuto de la clave                                       | Espera el tiempo indicado en `Retry-After` y reduce la concurrencia   |

Continúa con [Scopes y errores](/es/docs/api/scopes-errors), la [referencia de la API](/es/docs/api/reference) y los [límites de frecuencia](/es/docs/api/rate-limits).

---

# Límites de frecuencia

Source: /es/docs/api/rate-limits.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Por clave&#x22;, icon: &#x22;shield&#x22; }, { label: &#x22;Un minuto&#x22;, icon: &#x22;bolt&#x22; }, { label: &#x22;Retry-After&#x22;, icon: &#x22;code&#x22; }]" />

La API pública aplica un contenedor de solicitudes con ventana deslizante de un minuto a cada clave de API o token de acceso de OAuth. Crear más claves para eludir un límite no está permitido y puede dar lugar a restricciones en las credenciales o en la cuenta.

## Límites por plan [#límites-por-plan]

| Plan activo | Solicitudes por clave por minuto |
| ----------- | -------------------------------: |
| Launch      |                              120 |
| Operate     |                              600 |
| Scale       |                            1,800 |

Una credencial cuya cuenta no tenga un plan de pago activo recibe `403 subscription_required` antes de que se le asigne capacidad de límite de frecuencia. Make Agent Fast puede introducir límites más bajos específicos para ciertos endpoints en operaciones especialmente costosas; cuando eso ocurra, la referencia del endpoint los indicará de forma explícita.

## Una respuesta con límite de frecuencia [#una-respuesta-con-límite-de-frecuencia]

Cuando el contenedor se agota, la API devuelve `429 rate_limit_exceeded` con:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-Request-Id: 6c0b2f2e-...
Content-Type: application/json
```

`Retry-After` es el número mínimo de segundos que debes esperar. Cada respuesta autenticada incluye además `X-RateLimit-Limit`, `X-RateLimit-Remaining` y `X-RateLimit-Reset` (una marca de tiempo Unix), de modo que las aplicaciones pueden limitar su ritmo antes de recibir un `429`.

## Implementación de reintentos [#implementación-de-reintentos]

Usa un retroceso exponencial con jitter aleatorio, respeta un `Retry-After` mayor y limita el número total de intentos.

```ts
async function requestWithRetry(url: string, init: RequestInit, attempts = 4) {
  for (let attempt = 0; attempt < attempts; attempt += 1) {
    const response = await fetch(url, init);
    if (response.status !== 429 && response.status < 500) return response;

    if (attempt === attempts - 1) return response;
    const retryAfter = Number(response.headers.get("retry-after") ?? 0) * 1_000;
    const exponential = 500 * 2 ** attempt;
    const jitter = Math.random() * 250;
    await new Promise((resolve) =>
      setTimeout(resolve, Math.max(retryAfter, exponential + jitter)),
    );
  }
  throw new Error("unreachable");
}
```

En `POST`, `PATCH` y `DELETE`, conserva la misma `Idempotency-Key` válida en todos los reintentos por errores de red o de servidor. Una nueva clave de idempotencia puede repetir un efecto secundario que ya se completó.

## Reduce el volumen de solicitudes [#reduce-el-volumen-de-solicitudes]

* Almacena en caché las lecturas de cuenta, sitio y configuración que no necesiten estar actualizadas en tiempo real.
* Solicita hasta `100` registros por página en lugar de pedir repetidamente páginas muy pequeñas.
* Procesa los eventos de webhook en lugar de consultar periódicamente conversaciones, leads o difusiones.
* Limita la concurrencia de los workers por clave de API; una ráfaga de muchas invocaciones serverless comparte el mismo contenedor.
* Usa claves distintas para servicios distintos con fines de aislamiento y auditoría, no para multiplicar la capacidad de una misma carga de trabajo.

## Tabla de reintentar y no reintentar [#tabla-de-reintentar-y-no-reintentar]

| Respuesta                            | ¿Reintentar?    | Condición                                                                                                         |
| ------------------------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------- |
| `429`                                | Sí              | Espera el tiempo de `Retry-After`, añade jitter y limita los intentos                                             |
| `500`                                | A veces         | Lecturas seguras o mutaciones protegidas por la misma clave de idempotencia                                       |
| `409` por conflicto de procesamiento | Sí              | Espera según su encabezado `Retry-After: 2` y conserva la misma clave de idempotencia                             |
| Otros `409`                          | No de inmediato | Lee el estado actual del recurso y resuelve el conflicto                                                          |
| `503` `outcome_unknown`              | No              | Es posible que la mutación se haya completado; comprueba el recurso antes de usar una nueva clave de idempotencia |
| `400`, `401`, `403`, `404`, `415`    | No              | Corrige primero los datos de entrada, las credenciales, los permisos, la ruta o el tipo de contenido              |

Si una carga de trabajo sostenida supera legítimamente el contenedor de tu plan, reduce las consultas periódicas, agrupa el trabajo en lotes o contacta con soporte aportando ID de solicitud representativos y el tráfico esperado, en lugar de añadir un bucle de reintentos sin límite.

---

# Recetas de API

Source: /es/docs/api/recipes.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Crear&#x22;, icon: &#x22;site&#x22; }, { label: &#x22;Fundamentar&#x22;, icon: &#x22;book&#x22; }, { label: &#x22;Publicar&#x22;, icon: &#x22;globe&#x22; }]" />

Estas recetas usan REST sin procesar, por lo que funcionan incluso antes de instalar un SDK público. Define `MAF_API_KEY` en el entorno del servidor y sustituye los IDs devueltos por los pasos anteriores.

## Receta: crear y publicar un agente fundamentado [#receta-crear-y-publicar-un-agente-fundamentado]

Crea una clave de API con `sites:write`, `agents:write` y `knowledge:write`. Añade `sites:read` si la automatización también lista o verifica sitios.

### 1. Crear el sitio [#1-crear-el-sitio]

```bash
curl --fail-with-body https://makeagent.fast/api/v1/sites \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-site-2026-01" \
  -d '{
    "title": "Acme support",
    "slug": "acme-support",
    "type": "business",
    "template": "minimal",
    "content": {
      "headline": "Ask Acme support"
    },
    "persona_mode": "assistant",
    "languages": ["en"]
  }'
```

Una respuesta correcta es `201 Created`, incluye el sitio en `data` y devuelve su ruta de recurso canónica en el encabezado `Location`. Guarda `data.id` como `SITE_ID`.

### 2. Configurar el agente y la política de incrustación [#2-configurar-el-agente-y-la-política-de-incrustación]

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/agent" \
  -X PATCH \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-agent-2026-01" \
  -d '{
    "display_name": "Acme guide",
    "persona_mode": "assistant",
    "instructions": "Answer only from confirmed Acme sources. If the answer is missing, say that a teammate will follow up.",
    "languages": ["en"],
    "embed_enabled": true,
    "allowed_origins": ["https://www.acme.example", "https://staging.acme.example"]
  }'
```

Los orígenes permitidos son orígenes exactos: esquema, nombre de host y puerto opcional. No incluyas una ruta ni un comodín al final.

### 3. Añadir una fuente de conocimiento de texto [#3-añadir-una-fuente-de-conocimiento-de-texto]

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/knowledge" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-returns-2026-01" \
  -d '{
    "name": "Returns policy 2026-01",
    "text": "Customers may request a return within 30 days of delivery. Contact support before sending an item back."
  }'
```

El texto pegado debe tener entre 5 y 200 000 caracteres. El mismo endpoint también puede rastrear un sitio web con `{ "url", "max_pages", "refresh_hours" }` (`max_pages` hasta 40) o importar `{ "kind": "youtube" | "podcast" | "feed", "url" }`; esas fuentes multimedia requieren Operate o Scale y devuelven `409` en Launch. La subida de archivos solo está disponible en el panel.

### 4. Añadir unas preguntas frecuentes estructuradas [#4-añadir-unas-preguntas-frecuentes-estructuradas]

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/faqs" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-faq-returns-2026-01" \
  -d '{
    "question": "How long do I have to return an order?",
    "answer": "You may request a return within 30 days of delivery.",
    "approved": true
  }'
```

### 5. Publicar [#5-publicar]

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/publish" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-publish-2026-01" \
  -d '{"published": true}'
```

La respuesta debería contener `{"data":{"id":"...","status":"published"}}`. Abre una incrustación real y haz una pregunta cuya respuesta aparezca en la fuente. Publicar demuestra que el estado del agente cambió; no demuestra que la calidad de la fuente o el origen de la incrustación sean correctos.

## Receta: paginar leads de forma segura [#receta-paginar-leads-de-forma-segura]

Usa una clave con `leads:read`. Trata `next_cursor` como un valor opaco y codifícalo como URL.

```ts
const base = `https://makeagent.fast/api/v1/sites/${siteId}/leads`;
let cursor: string | null = null;

do {
  const url = new URL(base);
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.MAF_API_KEY}` },
  });
  if (!response.ok) throw await response.json();

  const page = await response.json();
  for (const lead of page.data) await exportLead(lead);
  cursor = page.next_cursor;
} while (cursor);
```

No decodifiques, edites, ordenes ni reutilices un cursor en una colección distinta.

## Receta: desactivar una incrustación durante un incidente [#receta-desactivar-una-incrustación-durante-un-incidente]

Usa `agents:write` y conserva la misma clave de idempotencia en todos los reintentos por fallos de red:

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/agent" \
  -X PATCH \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: incident-2026-07-embed-off" \
  -d '{"embed_enabled": false}'
```

Cuando la respuesta sea correcta, verifica que el lanzador ya no se inicializa en un host permitido. Vuelve a activarlo con una nueva clave de resolución del incidente después de corregir el problema de origen, contenido o credenciales.

## Lista de verificación para producción [#lista-de-verificación-para-producción]

* Usa una clave distinta por servicio y por entorno.
* Guarda los IDs de recursos y las claves de idempotencia antes de enviar una mutación.
* Configura tiempos de espera de conexión y de respuesta.
* Respeta `Retry-After` y limita el número de reintentos.
* Registra el nombre de la operación, el estado HTTP y el ID de la solicitud, sin registrar secretos ni datos personales.
* Prueba en un sitio que no sea de producción antes de conceder permisos de escritura en producción.

---

# Referencia de la API

Source: /es/docs/api/reference.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;v1&#x22;, icon: &#x22;code&#x22; }, { label: &#x22;123 operaciones&#x22;, icon: &#x22;layers&#x22; }, { label: &#x22;JSON&#x22;, icon: &#x22;book&#x22; }]" />

El contrato canónico legible por máquina es el [OpenAPI JSON](/api/openapi.json). Esta página es el índice de operaciones legible para personas y explica las reglas comunes a todos los endpoints.

## URL base y versión [#url-base-y-versión]

```text
https://makeagent.fast/api/v1
```

La versión mayor forma parte de la ruta. Pueden aparecer campos adicionales sin cambiar la versión mayor, así que ignora los campos de respuesta que no conozcas. Todas las solicitudes de gestión usan HTTPS y una clave de API bearer o un token de acceso OAuth.

## Encabezados comunes [#encabezados-comunes]

```http
Authorization: Bearer maf_live_...
Accept: application/json
Content-Type: application/json
Idempotency-Key: your-stable-operation-key
```

`Content-Type` es obligatorio en los cuerpos JSON de `POST` y `PATCH`, incluso cuando el cuerpo es `{}`. `Idempotency-Key` es opcional, pero se recomienda encarecidamente en todos los `POST`, `PATCH` y `DELETE`.

## Cuenta y sitios [#cuenta-y-sitios]

| Método   | Ruta                         | Scope          | Finalidad                                                                                                                                                                                              |
| -------- | ---------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GET`    | `/me`                        | `account:read` | Leer el resumen de cuenta, plan, derechos de uso y monedero                                                                                                                                            |
| `GET`    | `/sites`                     | `sites:read`   | Listar los sitios propios                                                                                                                                                                              |
| `POST`   | `/sites`                     | `sites:write`  | Crear un sitio y su agente predeterminado                                                                                                                                                              |
| `GET`    | `/sites/{site_id}`           | `sites:read`   | Obtener un sitio propio                                                                                                                                                                                |
| `PATCH`  | `/sites/{site_id}`           | `sites:write`  | Actualizar campos seguros del sitio                                                                                                                                                                    |
| `DELETE` | `/sites/{site_id}`           | `sites:write`  | Eliminar el sitio y los recursos dependientes                                                                                                                                                          |
| `POST`   | `/sites/{site_id}/publish`   | `sites:write`  | Publicar o despublicar con `{ "published": boolean }`                                                                                                                                                  |
| `GET`    | `/sites/{site_id}/agent`     | `agents:read`  | Leer la configuración del agente                                                                                                                                                                       |
| `PATCH`  | `/sites/{site_id}/agent`     | `agents:write` | Actualizar el modo de persona, la finalidad, el nombre visible, las instrucciones, la voz, los idiomas, el modelo, la apariencia, el chrome del embed, la insignia, el estado del embed o los orígenes |
| `GET`    | `/sites/{site_id}/billing`   | `account:read` | Leer el plan, el período, el monedero, los complementos y los enlaces de facturación del panel                                                                                                         |
| `PATCH`  | `/sites/{site_id}/workspace` | `team:write`   | Cambiar el nombre de la empresa propietaria del agente                                                                                                                                                 |
| `PATCH`  | `/sites/{site_id}/retention` | `team:write`   | Definir cuánto tiempo se conservan las conversaciones                                                                                                                                                  |

Para crear un sitio se requieren `title` y `content.headline`. Los campos opcionales son `slug`, `type`, `template`, contenido adicional, `persona_mode` y de uno a cuatro idiomas entre `en`, `ko`, `uz` y `ru`.

`PATCH /agent` aplica a `model`, `appearance`, `embed_chrome` y `badge_hidden` las mismas comprobaciones de plan que el panel; `badge_hidden: true` requiere un plan elegible o el complemento de la insignia.

## Instalación y widget del sitio web [#instalación-y-widget-del-sitio-web]

| Método  | Ruta                             | Scope          | Finalidad                                                                                                  |
| ------- | -------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------- |
| `GET`   | `/sites/{site_id}/install`       | `agents:read`  | Leer el destino de instalación, el estado del embed, los orígenes permitidos y la evidencia de instalación |
| `PATCH` | `/sites/{site_id}/install`       | `agents:write` | Definir la página en la que debe instalarse el widget                                                      |
| `POST`  | `/sites/{site_id}/install/check` | `agents:write` | Comprobar si el fragmento de embed está activo en la página de destino                                     |

## Conocimiento y preguntas frecuentes [#conocimiento-y-preguntas-frecuentes]

| Método             | Ruta                                                           | Scope                                | Finalidad                                                                                                                                |
| ------------------ | -------------------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `GET`              | `/sites/{site_id}/knowledge`                                   | `knowledge:read`                     | Listar las sources de conocimiento                                                                                                       |
| `POST`             | `/sites/{site_id}/knowledge`                                   | `knowledge:write`                    | Ingerir texto pegado, rastrear un sitio web o importar una source de YouTube, pódcast o feed                                             |
| `PATCH`            | `/sites/{site_id}/knowledge/{source_id}`                       | `knowledge:write`                    | Definir `refresh_hours` o el `approval_status` del buyer pack                                                                            |
| `POST`             | `/sites/{site_id}/knowledge/{source_id}/recrawl`               | `knowledge:write`                    | Poner en cola una nueva lectura de una source obtenida; devuelve `202`                                                                   |
| `DELETE`           | `/sites/{site_id}/knowledge/{source_id}`                       | `knowledge:write`                    | Eliminar una source de las consultas futuras                                                                                             |
| `GET`              | `/sites/{site_id}/faqs`                                        | `knowledge:read`                     | Listar las preguntas frecuentes estructuradas                                                                                            |
| `POST`             | `/sites/{site_id}/faqs`                                        | `knowledge:write`                    | Crear `{ "question", "answer", "approved" }`                                                                                             |
| `POST`             | `/sites/{site_id}/faqs/generate`                               | `knowledge:write`                    | Redactar borradores de preguntas frecuentes a partir del conocimiento del agente                                                         |
| `POST`             | `/sites/{site_id}/faqs/approve-all`                            | `knowledge:write`                    | Aprobar y publicar todas las preguntas frecuentes en borrador                                                                            |
| `PATCH`            | `/sites/{site_id}/faqs/{faq_id}`                               | `knowledge:write`                    | Actualizar la pregunta, la respuesta o el estado de aprobación                                                                           |
| `DELETE`           | `/sites/{site_id}/faqs/{faq_id}`                               | `knowledge:write`                    | Eliminar una pregunta frecuente                                                                                                          |
| `GET` / `PATCH`    | `/sites/{site_id}/fact-sheet`                                  | `knowledge:read` / `knowledge:write` | Leer la ficha de datos del negocio extraída, o corregir los datos que la extracción haya interpretado mal                                |
| `POST`             | `/sites/{site_id}/fact-sheet/reextract`                        | `knowledge:write`                    | Volver a leer el sitio web y reconstruir la ficha de datos                                                                               |
| `POST`             | `/sites/{site_id}/qa`                                          | `knowledge:write`                    | Publicar pares de preguntas y respuestas seleccionados                                                                                   |
| `POST`             | `/sites/{site_id}/answers/revise`                              | `knowledge:write`                    | Enseñar al agente la respuesta que debería haber dado                                                                                    |
| `GET`              | `/sites/{site_id}/knowledge-connections`                       | `knowledge:read`                     | Listar las conexiones de conocimiento de Notion, Drive y MCP                                                                             |
| `GET`              | `/sites/{site_id}/knowledge-connections/connect-links`         | `knowledge:read`                     | Obtener las URL del panel que inician una conexión de Notion o Drive                                                                     |
| `PATCH` / `DELETE` | `/sites/{site_id}/knowledge-connections/{connection_id}`       | `knowledge:write`                    | Definir la frecuencia de sincronización, los elementos seleccionados o la herramienta de importación; o desconectar y purgar la conexión |
| `GET`              | `/sites/{site_id}/knowledge-connections/{connection_id}/items` | `knowledge:read`                     | Listar las páginas, bases de datos o archivos que una conexión puede importar                                                            |
| `POST`             | `/sites/{site_id}/knowledge-connections/{connection_id}/sync`  | `knowledge:write`                    | Poner en cola una sincronización de una conexión de conocimiento                                                                         |

`POST /knowledge` acepta tres cuerpos: `{ "name", "text" }` con entre 5 y 200 000 caracteres; `{ "url", "max_pages", "refresh_hours" }` para rastrear un sitio web (`max_pages` de 1 a 40, `refresh_hours` de 1 a 8760 o `null`); y `{ "kind": "youtube" | "podcast" | "feed", "url", "refresh_hours" }`. Las sources de YouTube, pódcast y feed requieren Operate o Scale; en Launch devuelven `409 conflict`. La subida de archivos sigue siendo un flujo exclusivo del panel.

## Conversaciones, leads, analítica y uso [#conversaciones-leads-analítica-y-uso]

| Método  | Ruta                                                      | Scope                 | Finalidad                                                                       |
| ------- | --------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------- |
| `GET`   | `/sites/{site_id}/conversations`                          | `conversations:read`  | Listar los hilos de conversación                                                |
| `GET`   | `/sites/{site_id}/conversations/{conversation_id}`        | `conversations:read`  | Obtener un hilo y sus mensajes paginados                                        |
| `POST`  | `/sites/{site_id}/conversations/{conversation_id}/reply`  | `conversations:write` | Responder a un visitante en nombre del negocio                                  |
| `POST`  | `/sites/{site_id}/conversations/{conversation_id}/pause`  | `conversations:write` | Pausar el agente en esta conversación y asumir el control                       |
| `POST`  | `/sites/{site_id}/conversations/{conversation_id}/resume` | `conversations:write` | Devolver la conversación al agente                                              |
| `GET`   | `/sites/{site_id}/leads`                                  | `leads:read`          | Listar los leads capturados                                                     |
| `POST`  | `/sites/{site_id}/leads`                                  | `leads:write`         | Crear un lead canónico con consentimiento y preferencias de contacto explícitos |
| `GET`   | `/sites/{site_id}/leads/{lead_id}`                        | `leads:read`          | Obtener un lead                                                                 |
| `PATCH` | `/sites/{site_id}/leads/{lead_id}`                        | `leads:write`         | Actualizar, calificar o cambiar la política de contacto de un lead              |
| `POST`  | `/sites/{site_id}/leads/{lead_id}/accept`                 | `leads:write`         | Aceptar un lead en el pipeline de oportunidades                                 |
| `POST`  | `/sites/{site_id}/leads/{lead_id}/followup`               | `leads:write`         | Enviar el mensaje de seguimiento a un lead                                      |
| `POST`  | `/sites/{site_id}/leads/{lead_id}/followup/draft`         | `leads:write`         | Redactar de nuevo el mensaje de seguimiento sin enviarlo                        |
| `GET`   | `/sites/{site_id}/analytics`                              | `analytics:read`      | Listar los eventos de analítica                                                 |
| `GET`   | `/sites/{site_id}/report`                                 | `analytics:read`      | Leer el informe de analítica agregado                                           |
| `POST`  | `/sites/{site_id}/report/unanswered-faq`                  | `knowledge:write`     | Responder una pregunta sin respuesta como una nueva pregunta frecuente          |
| `GET`   | `/sites/{site_id}/usage`                                  | `usage:read`          | Listar los eventos de uso medido                                                |

Estas colecciones de eventos y actividad aceptan `limit` y `cursor`. Los registros devueltos pueden contener datos personales; almacénalos y expórtalos conforme a tus obligaciones de privacidad.

Se admiten las respuestas del owner: `reply`, `pause` y `resume` toman el control de un hilo web o de un chat de Telegram, WhatsApp, Messenger o Instagram igual que lo hace el panel. Enviar mensajes como si fueras el visitante no es una operación pública de la API.
Se admite la modificación de leads; no establezcas `consent_status: granted` a menos que tu sistema
tenga un registro de consentimiento defendible. Los leads con consentimiento desconocido se excluyen de los envíos masivos.

## Pipeline de oportunidades y resultados de CRM [#pipeline-de-oportunidades-y-resultados-de-crm]

| Método          | Ruta                                                                                                          | Scope                              | Finalidad                                                                                                                                         |
| --------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET` / `POST`  | `/sites/{site_id}/pipeline/stages`                                                                            | `pipeline:read` / `pipeline:write` | Listar o configurar las etapas                                                                                                                    |
| `GET` / `POST`  | `/sites/{site_id}/pipeline/accounts`                                                                          | `pipeline:read` / `pipeline:write` | Listar o crear cuentas de empresa                                                                                                                 |
| `GET`           | `/sites/{site_id}/pipeline/accounts/{account_id}`                                                             | `pipeline:read`                    | Obtener una cuenta de empresa                                                                                                                     |
| `GET` / `POST`  | `/sites/{site_id}/pipeline/opportunities`                                                                     | `pipeline:read` / `pipeline:write` | Listar o crear oportunidades                                                                                                                      |
| `GET` / `PATCH` | `/sites/{site_id}/pipeline/opportunities/{opportunity_id}`                                                    | `pipeline:read` / `pipeline:write` | Leer la actividad o actualizar la asignación, el valor, la etapa, la siguiente acción y la respuesta humana                                       |
| `POST`          | `/sites/{site_id}/pipeline/outcomes`                                                                          | `pipeline:write`                   | Importar de forma idempotente un resultado de ganado o perdido procedente del CRM                                                                 |
| `GET`           | `/sites/{site_id}/pipeline/sync-records`                                                                      | `pipeline:read`                    | Listar el estado de sincronización, los intentos y los errores                                                                                    |
| `POST`          | `/sites/{site_id}/pipeline/sync-records/{sync_record_id}/retry`                                               | `pipeline:write`                   | Reintentar un resultado fallido a partir de su payload almacenado                                                                                 |
| `GET` / `PATCH` | `/sites/{site_id}/pipeline-workflow`                                                                          | `pipeline:read` / `pipeline:write` | Leer o actualizar la política de respuesta de ventas                                                                                              |
| `GET` / `POST`  | `/sites/{site_id}/pilots`                                                                                     | `pipeline:read` / `pipeline:write` | Listar o iniciar pilotos guiados                                                                                                                  |
| `GET`           | `/sites/{site_id}/pilots/{pilot_id}`                                                                          | `pipeline:read`                    | Leer un piloto, su etapa, sus recuentos y su lista de trabajo                                                                                     |
| `POST`          | `/sites/{site_id}/pilots/{pilot_id}/setup`, `/start`, `/stop`, `/review`, `/decision`, `/complete`, `/delete` | `pipeline:write`                   | Llevar un piloto por la configuración, la medición, la revisión, la decisión y el cierre, o eliminarlo junto con su evidencia (siete operaciones) |
| `POST`          | `/sites/{site_id}/pilots/{pilot_id}/outcomes`, `/bookings`                                                    | `pipeline:write`                   | Registrar el resultado de un lead o el resultado de una reserva (dos operaciones)                                                                 |
| `POST`          | `/sites/{site_id}/pilots/{pilot_id}/report/approve`, `/report/revoke`                                         | `pipeline:write`                   | Aprobar o revocar el informe del piloto que se puede compartir (dos operaciones)                                                                  |
| `GET` / `POST`  | `/sites/{site_id}/buyer-packs`                                                                                | `pipeline:read` / `pipeline:write` | Listar los buyer packs o crear uno a partir de sources aprobadas                                                                                  |
| `PATCH`         | `/sites/{site_id}/buyer-packs/{pack_id}`                                                                      | `pipeline:write`                   | Reemplazar el título, la audiencia, el resumen, las sources y las secciones de un pack                                                            |
| `POST`          | `/sites/{site_id}/buyer-packs/{pack_id}/approve`, `/revoke`                                                   | `pipeline:write`                   | Activar o desactivar el enlace para compartir del pack (dos operaciones)                                                                          |

El `provider` del CRM, el ID externo y la clave de idempotencia que proporciones permanecen en el
registro de auditoría. Un reintento solo toma un registro fallido y nunca convierte una escritura
externa en curso en un éxito falso.

## Connectors [#connectors]

| Método   | Ruta                                          | Scope              | Finalidad                                                                                                                           |
| -------- | --------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `GET`    | `/sites/{site_id}/connectors`                 | `connectors:read`  | Listar el estado de los connectors sin secretos                                                                                     |
| `POST`   | `/sites/{site_id}/connectors`                 | `connectors:write` | Conectar un channel: validar las credenciales en vivo, aprovisionar su webhook y devolver la lista de comprobación de configuración |
| `PATCH`  | `/sites/{site_id}/connectors/{connector_id}`  | `connectors:write` | Definir `status` o `reply_with_voice`                                                                                               |
| `DELETE` | `/sites/{site_id}/connectors/{connector_id}`  | `connectors:write` | Desaprovisionar y eliminar un connector                                                                                             |
| `POST`   | `/sites/{site_id}/concierge`                  | `connectors:write` | Pedir a la plataforma que conecte un canal de mensajería por ti                                                                     |
| `GET`    | `/sites/{site_id}/domains`                    | `domains:read`     | Eliminado: devuelve `409`. No se ofrecen dominios personalizados                                                                    |
| `POST`   | `/sites/{site_id}/domains`                    | `domains:write`    | Eliminado: devuelve `409`                                                                                                           |
| `PATCH`  | `/sites/{site_id}/domains/{domain_id}`        | `domains:write`    | Eliminado: devuelve `409`                                                                                                           |
| `POST`   | `/sites/{site_id}/domains/{domain_id}/verify` | `domains:write`    | Eliminado: devuelve `409`                                                                                                           |
| `DELETE` | `/sites/{site_id}/domains/{domain_id}`        | `domains:write`    | Eliminado: devuelve `409`                                                                                                           |

La creación de un connector usa un cuerpo discriminado por channel. Los campos de credenciales difieren para `telegram`, `whatsapp`, `messenger`, `instagram`, `discord` y `kakao`; usa la guía del connector correspondiente antes de enviar secretos.

## Envíos masivos, notificaciones y monetización [#envíos-masivos-notificaciones-y-monetización]

| Método   | Ruta                                                  | Scope                 | Finalidad                                                                  |
| -------- | ----------------------------------------------------- | --------------------- | -------------------------------------------------------------------------- |
| `GET`    | `/sites/{site_id}/broadcasts`                         | `broadcasts:read`     | Listar los envíos masivos                                                  |
| `POST`   | `/sites/{site_id}/broadcasts`                         | `broadcasts:write`    | Crear un borrador de envío masivo de Kakao                                 |
| `POST`   | `/sites/{site_id}/broadcasts/{broadcast_id}/send`     | `broadcasts:write`    | Poner en cola un borrador existente; devuelve `202`                        |
| `GET`    | `/sites/{site_id}/notifications`                      | `notifications:read`  | Listar las notificaciones del propietario                                  |
| `POST`   | `/sites/{site_id}/notifications/read-all`             | `notifications:write` | Marcar como leídas todas las notificaciones del propietario de este agente |
| `PATCH`  | `/sites/{site_id}/notifications/{notification_id}`    | `notifications:write` | Marcar como leída o no leída con `{ "read": boolean }`                     |
| `GET`    | `/sites/{site_id}/alerts`                             | `notifications:read`  | Leer el estado del canal de alertas del propietario y su enlace del panel  |
| `GET`    | `/sites/{site_id}/monetization/products`              | `monetization:read`   | Listar los productos del sitio                                             |
| `POST`   | `/sites/{site_id}/monetization/products`              | `monetization:write`  | Crear un producto de tipo `access`, `consult`, `tip` o `digital`           |
| `PATCH`  | `/sites/{site_id}/monetization/products/{product_id}` | `monetization:write`  | Actualizar los campos del producto y su estado activo                      |
| `DELETE` | `/sites/{site_id}/monetization/products/{product_id}` | `monetization:write`  | Eliminar un producto                                                       |

Actualmente, la creación de envíos masivos solo acepta el canal `kakao`. La puesta en cola falla con `409 conflict` cuando no hay destinatarios alcanzables o cuando el envío masivo ya no es un borrador.

## Acciones, tickets y equipo [#acciones-tickets-y-equipo]

| Método             | Ruta                                                | Scope                          | Finalidad                                                                                                |
| ------------------ | --------------------------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------- |
| `GET` / `PATCH`    | `/sites/{site_id}/actions`                          | `agents:read` / `agents:write` | Leer o configurar los procedimientos, el webhook público, el enlace de reservas y los tickets de soporte |
| `GET`              | `/sites/{site_id}/tickets`                          | `tickets:read`                 | Listar los tickets de soporte                                                                            |
| `GET`              | `/sites/{site_id}/tickets/{ticket_id}`              | `tickets:read`                 | Leer un ticket y sus mensajes                                                                            |
| `PATCH`            | `/sites/{site_id}/tickets/{ticket_id}`              | `tickets:write`                | Definir el estado, la prioridad y, opcionalmente, el responsable asignado                                |
| `POST`             | `/sites/{site_id}/tickets/{ticket_id}/messages`     | `tickets:write`                | Añadir una nota interna, o establecer `internal: false` para responder al cliente por correo electrónico |
| `GET`              | `/sites/{site_id}/team`                             | `team:read`                    | Leer los miembros, las invitaciones y los eventos de auditoría permitidos                                |
| `POST`             | `/sites/{site_id}/team/invitations`                 | `team:write`                   | Crear un enlace de invitación sin enviar correo electrónico                                              |
| `DELETE`           | `/sites/{site_id}/team/invitations/{invitation_id}` | `team:write`                   | Revocar una invitación pendiente                                                                         |
| `PATCH` / `DELETE` | `/sites/{site_id}/team/members/{membership_id}`     | `team:write`                   | Cambiar el rol de un miembro que no sea propietario, o eliminar al miembro                               |

## Webhooks para desarrolladores y herramientas de configuración [#webhooks-para-desarrolladores-y-herramientas-de-configuración]

| Método   | Ruta                               | Scope                          | Finalidad                                                                                                                                                                                                       |
| -------- | ---------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET`    | `/webhook-endpoints`               | `webhooks:read`                | Listar el estado de los endpoints sin secretos de firma                                                                                                                                                         |
| `POST`   | `/webhook-endpoints`               | `webhooks:write`               | Registrar una URL HTTPS pública y mostrar su secreto de firma una sola vez                                                                                                                                      |
| `DELETE` | `/webhook-endpoints/{endpoint_id}` | `webhooks:write`               | Eliminar un endpoint y detener las entregas futuras                                                                                                                                                             |
| `GET`    | `/setup/tools`                     | Cualquier credencial válida    | Descubrir las herramientas de configuración para integraciones de API, MCP y GitHub                                                                                                                             |
| `POST`   | `/setup/tools/{tool_name}`         | Específico de cada herramienta | Ejecutar una herramienta de configuración; las solicitudes de plataforma necesitan los scopes de sus endpoints, la inspección de GitHub usa `integrations:read` y la preparación de PR usa `integrations:write` |

Las URL de webhook deben usar HTTPS, no pueden incluir credenciales ni un puerto personalizado, y deben resolverse únicamente a direcciones IP públicas.

## Paginación [#paginación]

Las colecciones paginadas aceptan `limit` de `1` a `100`; el valor predeterminado es `50`. Usa el `next_cursor` opaco devuelto únicamente con la misma colección y los mismos filtros.

```json
{
  "data": [],
  "has_more": false,
  "next_cursor": null
}
```

Algunas colecciones de configuración pequeñas devuelven el mismo envelope con `has_more: false` y no necesitan cursor.

## Idempotencia [#idempotencia]

Una clave de idempotencia debe tener entre 8 y 200 caracteres, formados por letras, números, `.`, `_`, `:` y `-`. Los resultados se conservan durante 24 horas y se asocian al propietario de la credencial.

* Misma clave y mismo método, ruta, query y cuerpo: devuelve la respuesta almacenada con `x-idempotent-replayed: true`.
* Misma clave con una entrada distinta: devuelve `409 conflict`.
* Misma clave mientras la primera solicitud aún se está procesando: devuelve `409 conflict` y `Retry-After: 2`.

Guarda la clave antes de enviar la mutación y reutilízala solo para reintentos de esa misma operación lógica.

## Respuestas y errores [#respuestas-y-errores]

Las respuestas correctas envuelven su recurso en `data`. Las operaciones de creación normalmente devuelven `201`; los envíos masivos puestos en cola devuelven `202`; las demás operaciones correctas devuelven `200`. Todas las respuestas incluyen `x-request-id` y usan `Cache-Control: no-store` para los datos de la API.

Consulta [Scopes y errores](/es/docs/api/scopes-errors) para ver la tabla completa de códigos de error y [Recetas de la API](/es/docs/api/recipes) para flujos de trabajo que puedes copiar.

## Clientes MCP [#clientes-mcp]

Conecta un cliente MCP de Streamable HTTP a `https://makeagent.fast/api/mcp`. Los clientes compatibles con el descubrimiento de OAuth abren el navegador para el inicio de sesión y el consentimiento. Verifica la identidad del cliente, la empresa y los scopes solicitados antes de aprobar. La primera aprobación solicita los scopes que usan las herramientas (`sites:read`, `sites:write`, `agents:write`, `analytics:read`, `conversations:read`, `conversations:write`, `leads:read`, `leads:write`, `knowledge:write`); a una credencial a la que le falte alguno de ellos se le pide que vuelva a autorizar. Se requiere un plan activo.

Para los clientes que usan credenciales configuradas manualmente, crea una clave de API con scopes limitados en [Ajustes de desarrollador](/dashboard/settings/developer) y envíala como encabezado `Authorization: Bearer ...`. Mantén las credenciales fuera del control de versiones y del código del navegador. Revoca las claves de API o las autorizaciones de OAuth desde los ajustes de desarrollador.

Herramientas de lectura: `list_agents`, `get_agent`, `get_report`, `list_unanswered_questions`, `list_conversations`, `get_conversation`, `list_leads`. Herramientas de escritura: `create_agent_from_website`, `create_agent_from_notes`, `test_agent`, `add_knowledge`, `save_answer`, `reply_to_customer`, `update_lead`, `set_website_widget`. Cada herramienta de agente recibe un `agent_id` obtenido de `list_agents`. `test_agent` consume créditos como una respuesta normal; `reply_to_customer` envía un mensaje al cliente y pausa el agente en esa conversación; `set_website_widget` activa o desactiva el widget de chat del sitio web; los canales de mensajería se gestionan en el panel. Los clientes con MCP Apps habilitado (de forma predeterminada, la conexión autenticada de Claude) también obtienen `list_pending_approvals`, `list_action_runs` y `decide_approval`, que aprueba o rechaza un cambio confirmado por el cliente; los demás clientes solo ven las 15 herramientas anteriores. Para las herramientas de configuración y de integración con GitHub, usa el asistente de configuración de la aplicación o `/api/v1/setup/tools`.

Las revisiones del protocolo compatibles son `2026-07-28`, `2025-11-25` y `2025-06-18`. El transporte devuelve JSON; no ofrece SSE heredado ni sesiones de servidor. Los tokens OAuth de MCP solo autorizan `/api/mcp`, no solicitudes REST directas. Los tokens de acceso OAuth duran una hora; las credenciales de actualización rotan y caducan a los 90 días. Las claves de API creadas manualmente usan la caducidad con la que se configuraron.

---

# Permisos y errores

Source: /es/docs/api/scopes-errors.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;33 permisos&#x22;, icon: &#x22;shield&#x22; }, { label: &#x22;Códigos estables&#x22;, icon: &#x22;code&#x22; }, { label: &#x22;ID de solicitud&#x22;, icon: &#x22;link&#x22; }]" />

Cada operación de la API pública requiere un permiso (scope) explícito. Una credencial válida que no tenga ese permiso recibe `403 insufficient_scope`; nunca se amplía de forma silenciosa a un acceso más amplio.

## Referencia de permisos [#referencia-de-permisos]

| Permiso (scope)       | Permite                                                                                                                                 |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `account:read`        | Leer la cuenta autenticada, el plan, los derechos de uso y el resumen del monedero                                                      |
| `tickets:read`        | Leer los tickets de soporte y sus mensajes                                                                                              |
| `tickets:write`       | Actualizar tickets, asignar compañeros de equipo y añadir notas internas o respuestas a clientes                                        |
| `team:read`           | Leer los miembros del equipo, las invitaciones pendientes y los eventos de auditoría permitidos                                         |
| `team:write`          | Crear o revocar invitaciones y gestionar los roles de los miembros del equipo que no son propietarios                                   |
| `integrations:read`   | Consultar las instalaciones y los repositorios autorizados de GitHub App                                                                |
| `integrations:write`  | Preparar cambios de integración y crear pull requests en borrador                                                                       |
| `sites:read`          | Listar y obtener sitios                                                                                                                 |
| `sites:write`         | Crear, actualizar, publicar, despublicar y eliminar sitios                                                                              |
| `agents:read`         | Leer la configuración del agente                                                                                                        |
| `agents:write`        | Actualizar el comportamiento, el idioma, la voz y la configuración de incrustación del agente                                           |
| `knowledge:read`      | Listar las fuentes de conocimiento y las preguntas frecuentes                                                                           |
| `knowledge:write`     | Crear, actualizar y eliminar fuentes de conocimiento y preguntas frecuentes                                                             |
| `conversations:read`  | Listar conversaciones y obtener sus mensajes                                                                                            |
| `conversations:write` | Tomar el control de una conversación: responder a un visitante en nombre del negocio, pausar el agente en ella y devolvérsela           |
| `leads:read`          | Listar los leads capturados                                                                                                             |
| `leads:write`         | Crear, actualizar, calificar y aceptar leads en el embudo de oportunidades                                                              |
| `pipeline:read`       | Leer etapas, cuentas, oportunidades, actividades, atribución y el estado de sincronización del CRM                                      |
| `pipeline:write`      | Configurar etapas; crear o actualizar oportunidades y cuentas; importar o reintentar resultados del CRM                                 |
| `analytics:read`      | Leer los eventos de analíticas del sitio                                                                                                |
| `connectors:read`     | Listar el estado de los conectores sin devolver secretos                                                                                |
| `connectors:write`    | Crear, actualizar, activar, desactivar y eliminar conectores                                                                            |
| `domains:read`        | Eliminado. Se mantiene solo por compatibilidad; todas las rutas `/domains` devuelven `409` porque no se ofrecen dominios personalizados |
| `domains:write`       | Eliminado. Se mantiene solo por compatibilidad; todas las rutas `/domains` devuelven `409`                                              |
| `broadcasts:read`     | Listar difusiones y el estado de entrega                                                                                                |
| `broadcasts:write`    | Crear borradores y poner en cola el envío de una difusión                                                                               |
| `notifications:read`  | Listar las notificaciones del propietario                                                                                               |
| `notifications:write` | Marcar notificaciones como leídas o no leídas                                                                                           |
| `monetization:read`   | Listar los productos de monetización                                                                                                    |
| `monetization:write`  | Crear, actualizar, activar, desactivar y eliminar productos                                                                             |
| `usage:read`          | Leer los eventos de uso medido                                                                                                          |
| `webhooks:read`       | Listar los endpoints de webhook y el estado de entrega                                                                                  |
| `webhooks:write`      | Crear y eliminar endpoints de webhook                                                                                                   |

Usa permisos de lectura para los trabajos de generación de informes. Añade un permiso de escritura solo cuando la integración realice esa modificación. Por ejemplo, una exportación de leads normalmente necesita `sites:read` y `leads:read`, no `sites:write` ni `agents:write`.

## Fallos de permisos [#fallos-de-permisos]

```json
{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key does not grant the required scope.",
    "details": { "required": ["sites:write"] },
    "request_id": "6c0b2f2e-..."
  }
}
```

Añade el permiso que falta a la clave en **Ajustes → Desarrollador → Editar**, o crea una clave de reemplazo y actualiza el secreto del servidor. Al editar se cambian en el mismo lugar el nombre y los permisos de la clave; su caducidad y su token no cambian. Las claves emitidas mediante OAuth no se pueden editar; vuelve a conectar la aplicación para cambiar lo que se le concedió.

## Estructura del error [#estructura-del-error]

Todos los errores de la API usan la misma estructura de nivel superior:

```ts
type ApiError = {
  error: {
    code: string;
    message: string;
    details?: unknown;
    request_id: string;
  };
};
```

Basa tu lógica en `error.code`, no en el `message` en inglés. Los mensajes pueden mejorar sin que cambie la versión. Registra `error.request_id` y el encabezado de respuesta `x-request-id` junto con el nombre de la operación, el estado y el número de reintento, pero nunca registres el encabezado de autorización ni los secretos de la solicitud.

## Referencia de estados y códigos [#referencia-de-estados-y-códigos]

| HTTP  | Código estable            | Significado                                                                                                                | Respuesta habitual                                                                                                                     |
| ----- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `invalid_request`         | La validación falló o un campo no es compatible                                                                            | Corrige los campos indicados en `details`; no reintentes con los mismos datos                                                          |
| `400` | `invalid_json`            | El cuerpo no es un objeto JSON o contiene JSON no válido                                                                   | Serializa un único objeto JSON válido                                                                                                  |
| `401` | `authentication_required` | Falta el encabezado Bearer                                                                                                 | Adjunta una credencial desde el servidor                                                                                               |
| `401` | `invalid_api_key`         | La clave no es válida, ha caducado, se ha revocado o su propietario ya no existe                                           | Sustituye o rota la clave                                                                                                              |
| `403` | `subscription_required`   | El propietario no tiene un plan de pago activo                                                                             | Restablece la suscripción antes de reintentar                                                                                          |
| `403` | `insufficient_scope`      | La credencial no tiene el permiso de la operación                                                                          | Crea una credencial de reemplazo con el mínimo privilegio                                                                              |
| `403` | `account_paused`          | El acceso a la API está en pausa para la cuenta                                                                            | Reanuda el acceso a la API o contacta con el propietario de la cuenta                                                                  |
| `404` | `not_found`               | No se encontró el endpoint o el recurso propio                                                                             | Verifica la ruta y el ID perteneciente al tenant                                                                                       |
| `409` | `conflict`                | El estado actual del recurso impide la acción                                                                              | Consulta el estado actual antes de reintentar                                                                                          |
| `413` | `payload_too_large`       | El cuerpo JSON supera el límite de 256 KB por solicitud                                                                    | Envía un cuerpo más pequeño; divide los contenidos grandes en varias solicitudes                                                       |
| `415` | `invalid_request`         | El cuerpo de la modificación no es `application/json`                                                                      | Envía `Content-Type: application/json`                                                                                                 |
| `429` | `rate_limit_exceeded`     | Se agotó el límite del plan de la clave para el período de un minuto                                                       | Espera el tiempo indicado en `Retry-After` y aplica jitter                                                                             |
| `500` | `internal_error`          | No se pudo completar la solicitud                                                                                          | Reintenta una operación segura o idempotente e informa del ID de solicitud                                                             |
| `503` | `outcome_unknown`         | Es posible que una modificación se haya completado, pero no se pudo registrar su resultado; `details.retryable` es `false` | No reintentes. Consulta el recurso para ver si el cambio se realizó; la misma clave de idempotencia seguirá devolviendo este resultado |

Los recursos que no pertenecen a la cuenta del propietario de la credencial pueden devolver `404` en lugar de revelar si existe el ID de otro tenant.

## Detalles de validación [#detalles-de-validación]

La validación de campos devuelve rutas que puedes mostrar junto a tus propios controles de formulario:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed.",
    "details": [
      { "path": "content.headline", "message": "String must contain at least 1 character(s)" }
    ],
    "request_id": "6c0b2f2e-..."
  }
}
```

Los cuerpos de las modificaciones deben ser objetos JSON. Se rechazan las matrices, los cuerpos vacíos, los datos de formulario y el JSON enviado con un tipo de contenido de texto.

## Decisiones de reintento [#decisiones-de-reintento]

* Reintenta `429` después del número de segundos indicado en `Retry-After`.
* Reintenta `500` solo en lecturas seguras o en escrituras protegidas por la misma `Idempotency-Key`.
* Reintenta el `409` de idempotencia en curso después de su encabezado `Retry-After: 2`.
* Nunca reintentes `503 outcome_unknown` a ciegas. Comprueba primero el recurso; usa una nueva clave de idempotencia solo después de confirmar que el cambio no se realizó.
* No reintentes `400`, `401`, `403`, `404`, `413` ni un conflicto de estado hasta que cambie la causa.

Consulta [Límites de frecuencia](/es/docs/api/rate-limits) para conocer el comportamiento del backoff y la [Referencia de la API](/es/docs/api/reference) para ver el permiso requerido en cada operación.

---

# Estado del SDK

Source: /es/docs/api/sdks.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;REST disponible&#x22;, icon: &#x22;globe&#x22; }, { label: &#x22;OpenAPI&#x22;, icon: &#x22;code&#x22; }, { label: &#x22;SDK en versión preliminar&#x22;, icon: &#x22;bolt&#x22; }]" />

La API REST versionada es hoy la única superficie de integración pública compatible de forma oficial. El código fuente de los clientes de JavaScript, Python y de frameworks existe en el repositorio del producto, pero los paquetes no están publicados actualmente en npm ni en PyPI.

## Disponibilidad [#disponibilidad]

| Cliente                            | Estado                                                   | Cómo usarlo                                                                                                          |
| ---------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| REST sobre HTTPS                   | **Disponible**                                           | Llama a `https://makeagent.fast/api/v1` desde cualquier cliente HTTP del lado del servidor                           |
| Documento OpenAPI                  | **Disponible**                                           | Descarga [/api/openapi.json](/api/openapi.json) e inspecciónalo antes de generar un cliente                          |
| `@make-agent-fast/sdk`             | **Versión preliminar en código fuente: no está en npm**  | No añadas esta importación a un proyecto de producción hasta que aquí se enlace una versión publicada en un registro |
| Paquete de Python `makeagentfast`  | **Versión preliminar en código fuente: no está en PyPI** | Usa `requests`, `httpx` o la biblioteca estándar de Python hasta que aquí se enlace una versión publicada en PyPI    |
| Adaptadores de React, Vue y Svelte | **Versión preliminar en código fuente: no están en npm** | Es preferible usar el patrón documentado de carga mediante script para tu framework                                  |
| Componente web                     | **Versión preliminar en código fuente: no está en npm**  | Es preferible usar el cargador estándar `embed.js`                                                                   |

<Callout title="Una carpeta de código fuente no es una versión publicada de un paquete" tone="warning">
  No ejecutes `npm install @make-agent-fast/sdk` ni `pip install makeagentfast` basándote únicamente en un ejemplo de importación. Esta página incluirá la URL del registro, la versión, las indicaciones de integridad y el comando de instalación cuando se publique un paquete público.
</Callout>

## JavaScript sin SDK [#javascript-sin-sdk]

```ts
const response = await fetch("https://makeagent.fast/api/v1/sites?limit=100", {
  headers: {
    Authorization: `Bearer ${process.env.MAF_API_KEY}`,
    Accept: "application/json",
  },
});

const body = await response.json();
if (!response.ok) {
  console.error(body.error.code, body.error.request_id);
  throw new Error(`Make Agent Fast request failed (${response.status})`);
}

for (const site of body.data) console.log(site.id, site.title);
```

Mantén la clave de API en el servidor. Un bundle de navegador de React, Vue o Svelte debe llamar a tu propio backend o instalar el cargador público de inserción (embed); no debe llamar a la API de administración con un secreto.

## Python sin SDK [#python-sin-sdk]

```python
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://makeagent.fast/api/v1/sites?limit=100",
    headers={
        "Authorization": f"Bearer {os.environ['MAF_API_KEY']}",
        "Accept": "application/json",
    },
)

with urllib.request.urlopen(request, timeout=20) as response:
    payload = json.load(response)

for site in payload["data"]:
    print(site["id"], site["title"])
```

En producción, captura `urllib.error.HTTPError` y analiza su cuerpo JSON usando el [formato de error estable](/es/docs/api/scopes-errors).

## Clientes generados [#clientes-generados]

La generación a partir de OpenAPI solo resulta útil cuando el documento contiene las operaciones y los esquemas de los que depende tu aplicación. Fija la especificación descargada, genera el cliente en un directorio revisable e inspecciona cada diferencia antes de actualizar.

```bash
curl --fail-with-body https://makeagent.fast/api/openapi.json \
  --output make-agent-fast.openapi.json
```

No regeneres ni despliegues automáticamente un cliente a partir de la URL en vivo. Un nuevo campo añadido no debería romper un cliente, pero el comportamiento del generador y los nombres de los métodos generados aún pueden cambiar.

## Qué debe incluir una versión pública del SDK [#qué-debe-incluir-una-versión-pública-del-sdk]

Antes de marcar como disponible cualquier cliente en versión preliminar, debe contar con lo siguiente:

* Una página pública en un registro y una versión semántica inmutable.
* Instrucciones de instalación, actualización y entornos de ejecución compatibles.
* Modelos tipados de solicitud y respuesta generados a partir del contrato completo de la API.
* Errores estructurados que conserven el estado HTTP y el ID de la solicitud.
* Utilidades de paginación que traten los cursores como opacos.
* Compatibilidad explícita con claves de idempotencia en las operaciones que modifican datos.
* Pruebas de CI contra el contrato actual de `/api/v1` y un registro de cambios publicado.

Hasta que se cumplan estas condiciones, usa los ejemplos de REST de la [guía de inicio rápido de la API](/es/docs/api/quickstart) y las [recetas de la API](/es/docs/api/recipes).

---

# Webhooks

Source: /es/docs/api/webhooks.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;HMAC-SHA256&#x22;, icon: &#x22;shield&#x22; }, { label: &#x22;Al menos una vez&#x22;, icon: &#x22;bolt&#x22; }, { label: &#x22;8 intentos&#x22;, icon: &#x22;layers&#x22; }]" />

Los webhooks para desarrolladores envían a tu servidor los eventos de tu cuenta, de modo que no necesitas hacer polling. La entrega es de al menos una vez: los eventos pueden duplicarse, retrasarse o llegar desordenados.

## Registrar un endpoint [#registrar-un-endpoint]

Crea una clave con `webhooks:write` y luego registra un receptor HTTPS público junto con el conjunto mínimo de eventos que necesites.

```bash
curl --fail-with-body https://makeagent.fast/api/v1/webhook-endpoints \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: webhook-production-v1" \
  -d '{
    "url": "https://api.example.com/webhooks/make-agent-fast",
    "events": ["lead.created", "conversation.started"]
  }'
```

La URL debe usar HTTPS, no puede incluir usuario, contraseña, fragmento ni puerto personalizado, y debe resolver únicamente a direcciones IP públicas. Durante la entrega no se siguen las redirecciones.

La respuesta `201` revela una sola vez un secreto de firma `whsec_...`. Guárdalo en el gestor de secretos del receptor antes de cerrar la respuesta. Si más adelante listas los endpoints, obtendrás la URL, los eventos, el estado, la última entrega y el último error, pero no el secreto.

## Tipos de eventos [#tipos-de-eventos]

| Evento                         | Se emite cuando                                                                       |
| ------------------------------ | ------------------------------------------------------------------------------------- |
| `site.published`               | Un sitio pasa a estar publicado                                                       |
| `site.unpublished`             | Un sitio vuelve al estado de borrador                                                 |
| `lead.created`                 | El agente captura un nuevo lead                                                       |
| `lead.qualified`               | El agente califica un lead, o un lead se acepta en el pipeline de ventas              |
| `booking.requested`            | Un visitante solicita o reserva un horario                                            |
| `handoff.requested`            | El agente transfiere una conversación a una persona (handoff)                         |
| `opportunity.created`          | Un lead se convierte en una oportunidad del pipeline                                  |
| `opportunity.updated`          | Cambia la asignación, el valor, la siguiente acción u otros campos de una oportunidad |
| `opportunity.stage_changed`    | Una oportunidad pasa a otra etapa                                                     |
| `opportunity.won`              | Una oportunidad se cierra como ganada                                                 |
| `opportunity.lost`             | Una oportunidad se cierra como perdida                                                |
| `conversation.started`         | Comienza un nuevo hilo de conversación                                                |
| `conversation.message.created` | Se añade un mensaje a una conversación                                                |
| `knowledge.ready`              | Una fuente de conocimiento termina de procesarse                                      |
| `broadcast.sent`               | Un broadcast termina su flujo de envío                                                |
| `domain.activated`             | Retirado: no se ofrecen dominios personalizados; este evento nunca se emite           |

## Formato de la solicitud [#formato-de-la-solicitud]

Make Agent Fast envía un `POST` con `Content-Type: application/json`, `User-Agent: MakeAgentFast-Webhooks/1.0` y estas cabeceras:

```http
maf-event-id: evt_...
maf-event-type: lead.created
maf-signature: t=1784210566,v1=HEX_HMAC_SHA256
```

El cuerpo JSON tiene un envelope estable. Los campos dentro de `data` dependen del evento y pueden recibir campos adicionales.

```json
{
  "id": "evt_2c34...",
  "type": "lead.created",
  "created_at": "2026-07-16T10:02:46.000Z",
  "data": {
    "site_id": "SITE_ID",
    "lead_id": "LEAD_ID"
  }
}
```

Usa el `id` del cuerpo o `maf-event-id` como clave de deduplicación. No uses la hora de entrega ni un ID de base de datos generado.

## Verificar la firma en Node.js [#verificar-la-firma-en-nodejs]

Lee los bytes exactos sin procesar antes de parsear el JSON. El valor firmado es `TIMESTAMP + "." + RAW_BODY`.

```ts
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWebhook(rawBody: Buffer, header: string, secret: string) {
  const values = Object.fromEntries(header.split(",").map((part) => part.split("=", 2)));
  const timestamp = values.t;
  const supplied = values.v1;
  if (!timestamp || !supplied || !/^[a-f0-9]{64}$/.test(supplied)) return false;

  const age = Math.abs(Date.now() / 1_000 - Number(timestamp));
  if (!Number.isFinite(age) || age > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest("hex");
  return timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(supplied, "hex"));
}
```

Rechaza las firmas mal formadas y las marcas de tiempo anteriores a tu ventana de repetición aceptada; cinco minutos es un valor predeterminado razonable. Compara bytes de longitud fija en tiempo constante.

## Verificar la firma en Python [#verificar-la-firma-en-python]

```python
import hashlib
import hmac
import time

def verify_webhook(raw_body: bytes, header: str, secret: str) -> bool:
    values = dict(part.split("=", 1) for part in header.split(",") if "=" in part)
    timestamp = values.get("t", "")
    supplied = values.get("v1", "")
    try:
        if abs(time.time() - int(timestamp)) > 300:
            return False
    except ValueError:
        return False

    signed = timestamp.encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, supplied)
```

Parsea y procesa el JSON solo después de que la verificación de la firma haya sido correcta.

## Confirmar y procesar [#confirmar-y-procesar]

1. Verifica la firma y la marca de tiempo.
2. Inserta el ID del evento en una tabla con una restricción de unicidad.
3. Si ya existe, devuelve `204` sin repetir el efecto secundario.
4. Confirma el evento (commit) o encola tu tarea interna.
5. Devuelve rápidamente una respuesta `2xx`.

El emisor de Make Agent Fast agota el tiempo de espera a los 10 segundos. Solo considera correcta una respuesta `2xx` y no sigue redirecciones.

## Comportamiento de los reintentos [#comportamiento-de-los-reintentos]

Las entregas fallidas se encolan hasta un máximo de ocho intentos. El backoff comienza en unos dos segundos, se duplica con jitter y tiene un tope de una hora; la hora real de entrega puede ser posterior cuando los workers están ocupados. Como los reintentos pueden sobrevivir a la solicitud que los originó y llegar desordenados, nunca dependas de que un evento llegue inmediatamente antes que otro.

Devuelve una respuesta que no sea 2xx solo cuando quieras que Make Agent Fast reintente. Si un evento tiene una versión que ya no se admite de forma permanente o el destino fue eliminado, acepta y registra el evento, o elimina el endpoint, en lugar de generar fallos transitorios interminables.

## Rotar un secreto de firma [#rotar-un-secreto-de-firma]

Los secretos de firma no se pueden revelar ni editar. Para rotarlos de forma segura:

1. Crea un segundo endpoint que apunte a una ruta de receptor temporal o con versión.
2. Guarda el secreto recién revelado.
3. Acepta y deduplica los eventos de ambos endpoints.
4. Comprueba que el nuevo endpoint recibe entregas válidas.
5. Elimina el endpoint antiguo con `DELETE /webhook-endpoints/{endpoint_id}`.

Si la URL del receptor se mantiene igual, haz que la aplicación receptora acepte ambos secretos durante el periodo de solapamiento y utiliza los IDs de evento para evitar efectos secundarios duplicados.

## Solución de problemas [#solución-de-problemas]

| Síntoma                    | Qué revisar                                                                                                                                               |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No hay entregas            | Estado del endpoint, eventos seleccionados, DNS público, certificado HTTPS y si el evento realmente ocurrió                                               |
| La firma no coincide       | Acceso al cuerpo sin procesar, concatenación exacta de `timestamp.body`, secreto correcto del endpoint y transformaciones del cuerpo por parte de proxies |
| Entregas repetidas         | Código de respuesta, tiempo de espera de 10 segundos, excepciones internas y unicidad del ID de evento                                                    |
| Error de dirección privada | Los registros DNS deben resolver solo a direcciones públicas; localhost y los rangos internos se rechazan                                                 |
| Fallo por redirección      | Registra directamente la URL HTTPS final; las redirecciones no se siguen                                                                                  |

Nunca incluyas el secreto de firma, la clave bearer ni el payload completo de un visitante en un mensaje a soporte. Incluye el ID del endpoint, el ID del evento, la hora del fallo y los logs del receptor sanitizados.

---

# Pantalla

Source: /es/docs/build/appearance.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Tema&#x22;, icon: &#x22;spark&#x22; }, { label: &#x22;Chat&#x22;, icon: &#x22;chat&#x22; }, { label: &#x22;Llamada en vivo&#x22;, icon: &#x22;voice&#x22; }]" />

La apariencia del widget da estilo al **chat** y a la **llamada en vivo** del visitante a la vez: colores, tema, esquinas, sombra, efecto cristal y fuentes. No crea una página de marketing alojada. Los agentes nuevos se publican como un embed en tu sitio web actual.

Abre la página **Agente** del agente y elige la pestaña **Pantalla**. Cada control se aplica a ambas superficies, y el lienzo en vivo junto a la pestaña muestra el widget real.

<TutorialVideo episode="ep02" start="108" />

## Los cambios se publican automáticamente [#los-cambios-se-publican-automáticamente]

No hay botón de guardar. Los textos y los controles deslizantes se guardan tras una breve pausa; los interruptores, los ajustes preestablecidos y las opciones se guardan al instante, y junto al control aparece un aviso **Guardado**. Cada guardado actualiza el registro del agente y refresca el embed (y cualquier página alojada heredada), de modo que los visitantes ven el cambio sin esperar a una nueva publicación. Compruébalo en una ventana privada sobre un embed real.

Ocultar o mostrar la insignia en los planes Operate y Scale usa la misma actualización en vivo.

## Usar el sitio web vs. Claro u Oscuro [#usar-el-sitio-web-vs-claro-u-oscuro]

**Tema del agente** tiene tres opciones:

| Opción                | Efecto                                                                                                                                             |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Usar el sitio web** | Sigue el modo claro u oscuro de cada visitante (primero el de la página anfitriona y luego el del sistema operativo). Es la opción predeterminada. |
| **Claro**             | Fija el chat y la llamada en vivo a la paleta clara.                                                                                               |
| **Oscuro**            | Fija el chat y la llamada en vivo a la paleta oscura.                                                                                              |

**Usar el sitio web** equivale a `auto`. Si fijas Claro u Oscuro, tanto el chat como la llamada en vivo quedan fijos para todos los visitantes. Edita las paletas clara y oscura por separado; el interruptor de la vista previa solo cambia la paleta que estás editando.

En un embed, el cargador todavía puede pasar `data-theme="light"` o `data-theme="dark"` como ajuste forzado desde la página anfitriona. Consulta la [descripción general del embed](/es/docs/embed/overview).

## Colores, ajustes preestablecidos y tipografía [#colores-ajustes-preestablecidos-y-tipografía]

* **Ajustes preestablecidos** (Sharp, Soft, Glass, Minimal): definen a la vez las esquinas, la sombra, el borde y el efecto cristal.
* **Color principal**: burbujas del visitante, acentos de la llamada y acciones principales. **Auto (acento del sitio)** hereda el acento de marca detectado al rastrear tu sitio, que se usa para el widget.
* Ajusta con precisión el color secundario, el fondo, la superficie del panel, las esquinas, la sombra, el borde, el efecto cristal y la fuente.
* **Igualar al sitio** en la fuente se aplica cuando el agente está insertado en un sitio externo; **Predeterminada del widget** mantiene la tipografía del widget.

Usa un contraste suficiente y asegúrate de que los estados interactivos se distingan bien. Haz la vista previa en anchos de escritorio y reducidos, incluidas las etiquetas en coreano y en inglés.

## Conversación en vivo en la vista previa de Pantalla [#conversación-en-vivo-en-la-vista-previa-de-pantalla]

El lienzo junto a la pestaña **Pantalla** muestra el widget real, así que el chat y la llamada en vivo aparecen con la paleta clara u oscura seleccionada y con el mismo aspecto de interfaz del visitante que en el embed. Hablar con el agente ahí sigue siendo una prueba del propietario; consulta [Voz y llamadas en vivo](/es/docs/build/voice).

## Insignia de marca [#insignia-de-marca]

Quitar la insignia está disponible en los planes Operate y Scale. Los sitios del plan Launch conservan la insignia de recomendación de Make Agent Fast. Al cambiar el ajuste de la insignia (**Mostrar la insignia “Made with”**), también se actualiza el embed en vivo sin necesidad de volver a publicar.

---

# Reservas con Cal.com

Source: /es/docs/build/cal-com.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/build/change-actions&#x22;, label: &#x22;Confirmaciones y recibos&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/es/docs/operate/conversations&#x22;, label: &#x22;Conversaciones&#x22;, icon: &#x22;book&#x22; }
]"
/>

## Conecta tu calendario [#conecta-tu-calendario]

Abre **Agente → Acciones → Cal.com**. Introduce una clave de API de Cal.com que empiece por `cal_`, el ID numérico positivo del tipo de evento y una zona horaria IANA, como `Asia/Seoul`. Elige **Guardar conexión**. Cada agente tiene su propia conexión. La clave se cifra en el servidor; el panel solo muestra sus últimos cuatro caracteres. Si actualizas una conexión existente, deja la clave en blanco para conservarla.

Elige **Probar conexión** para leer hasta tres horarios próximos de los siguientes siete días con los ajustes introducidos. Esta prueba no guarda la conexión ni crea ninguna reserva. Que no aparezcan horarios puede significar simplemente que el tipo de evento no tiene disponibilidad en ese periodo. Si la prueba falla, revisa en Cal.com la clave, el tipo de evento y el horario. Si eliminas la conexión, el agente deja de crear nuevas reservas en Cal.com, pero no cancela las reservas existentes.

Los pagos quedan fuera del alcance. [Google Calendar](/es/docs/build/google-calendar) es una opción independiente que todavía no está disponible de forma general.

## De los horarios a la reserva [#de-los-horarios-a-la-reserva]

1. El agente llama a `find_slots` para obtener disponibilidad futura real. Muestra hasta ocho horarios en la zona horaria configurada. El rango predeterminado va desde hoy hasta siete días después; el intervalo máximo de fechas es de 14 días. Si solo hay un horario disponible, se muestra solo.
2. El cliente elige un horario y proporciona su nombre, su correo electrónico y, opcionalmente, una nota. El agente vuelve a comprobar que el horario sigue libre y que se ofreció en esta conversación. Las ofertas de horarios caducan a los 15 minutos.
3. Una tarjeta de confirmación muestra la fecha, la hora, la zona horaria y los datos del asistente. El cliente debe pulsar **Confirmar**. Un mensaje en el chat o la selección de un horario, por sí solos, no reservan nada. La propuesta caduca a los 15 minutos y no bloquea el horario.
4. Solo después de la confirmación, el adaptador solicita la reserva a Cal.com. Un resultado `accepted` de Cal.com pasa a `done`, con el UID de la reserva como referencia. `pending` o `awaiting_host` permanece como pendiente; un rechazo o una cancelación pasa a fallido.

En los canales de mensajería, las propuestas de reserva solo funcionan en chats privados. El ensayo no llama a Cal.com ni crea ninguna reserva. Sin una conexión con Cal.com, sigue disponible el flujo actual de solicitud de reserva, que no demuestra que se haya reservado un hueco en el calendario. Si cambias la clave, el tipo de evento o la zona horaria, el destino de ejecución de la propuesta deja de ser válido, así que empieza de nuevo después de cambiar la conexión.

## Si un horario ya está ocupado o el resultado es incierto [#si-un-horario-ya-está-ocupado-o-el-resultado-es-incierto]

Otro cliente puede ocupar un horario antes de que termine la confirmación. Si el horario ya no está libre, el agente informa de que no está disponible; si Cal.com lo rechaza durante la creación, el recibo muestra un fallo. Pide horarios nuevos y confirma una propuesta nueva. El recibo de fallo no adjunta automáticamente nuevas opciones.

Un tiempo de espera agotado en la red no demuestra ni un fallo ni un éxito. El recibo muestra un resultado desconocido mientras el servicio vuelve a comprobarlo. El endpoint de creación de Cal.com no tiene un contrato documentado de clave de idempotencia, por lo que el adaptador guarda el ID de ejecución en `metadata.maf_run` y busca esa reserva en todos los estados y páginas antes de reintentar la creación. Una búsqueda incompleta nunca permite enviar otra solicitud de creación. Esto reduce el riesgo de duplicados, pero no es una garantía de ejecución exactamente una vez respaldada por el proveedor. Antes de hacer otra reserva tras agotar los reintentos, comprueba Cal.com.

La aprobación del anfitrión en Cal.com es independiente de la aprobación del propietario en las acciones de cambio personalizadas. Esta integración no actualiza automáticamente una reserva pendiente de Cal.com; comprueba su estado final en Cal.com. El widget web puede consultar periódicamente el recibo de ejecución almacenado, y los canales privados compatibles reciben los recibos diferidos según sus ventanas de servicio. Consulta la [entrega de recibos](/es/docs/build/change-actions#customer-confirmation-and-receipts).

## Versiones de la API y comprobaciones previas al lanzamiento [#versiones-de-la-api-y-comprobaciones-previas-al-lanzamiento]

El adaptador envía autenticación Bearer y estos valores de `cal-api-version` específicos de cada endpoint, verificados con la documentación oficial el **2026-10-13**:

| Operación         | Versión      | Referencia                                                                                              |
| ----------------- | ------------ | ------------------------------------------------------------------------------------------------------- |
| Leer horarios     | `2024-09-04` | [GET /v2/slots](https://cal.com/docs/api-reference/v2/slots/get-available-time-slots-for-an-event-type) |
| Crear reserva     | `2026-02-25` | [POST /v2/bookings](https://cal.com/docs/api-reference/v2/bookings/create-a-booking)                    |
| Conciliar reserva | `2026-05-01` | [GET /v2/bookings](https://cal.com/docs/api-reference/v2/bookings/get-all-bookings)                     |

Antes de usarlo con clientes, prueba una reserva controlada, verifica el UID en Cal.com, intenta reservar un horario ocupado y comprueba los recibos en cada canal previsto. Una prueba de conexión correcta solo demuestra una lectura de horarios, no una reserva real ni que todo esté listo para producción.

---

# Acciones de cambio

Source: /es/docs/build/change-actions.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/build/lookups&#x22;, label: &#x22;Consultas de solo lectura&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/es/docs/build/cal-com&#x22;, label: &#x22;Reservas con Cal.com&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/es/docs/embed/security&#x22;, label: &#x22;Clientes con sesión iniciada&#x22;, icon: &#x22;shield&#x22; }
]"
/>

<TutorialVideo episode="ep06" start="134" />

## Define un cambio [#define-un-cambio]

Usa una acción de cambio para actualizar un registro en tu propio sistema, por ejemplo para cancelar un pedido. Abre **Agente → Acciones**, configura el secreto de tu agente en **Clientes con sesión iniciada** y después añade una **Acción de cambio**: un nombre único, una descripción de cuándo usarla, un endpoint HTTPS público y entradas de texto declaradas. Un nombre como `cancel_order` se convierte en la herramienta del modelo `change_cancel_order`. Las ediciones existentes se guardan automáticamente; espera a que aparezca el indicador de guardado.

Mantén activada la opción **Requiere cliente con sesión iniciada** para los registros privados. Tu endpoint debe seguir autorizando el registro solicitado con respecto al ID de cliente verificado. Un nombre, un correo electrónico o un ID de pedido escrito en el chat no es una prueba de identidad. Si desactivas esta opción, `customer` puede ser null: permite únicamente los cambios apropiados para visitantes anónimos. Los pagos quedan fuera del alcance de esta función.

## Elige la aprobación del propietario [#elige-la-aprobación-del-propietario]

La confirmación del cliente es obligatoria en todos los modos:

| Modo                                   | Después de que el cliente confirme                                                                                                                                |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sin aprobación (`none`)                | Se ejecuta sin una decisión adicional del propietario.                                                                                                            |
| Aprobar siempre (`always`)             | Espera al propietario.                                                                                                                                            |
| Por encima de un límite (`over_limit`) | Espera cuando una entrada numérica declarada es estrictamente mayor que el límite; la igualdad no requiere aprobación. Una entrada numérica no válida se rechaza. |

Revisa las solicitudes en espera en **Agente → Acciones → Aprobaciones**. El propietario del sitio puede aprobar o rechazar. Si tienes vinculadas las alertas privadas de Telegram para el propietario, la alerta también incluye los botones **Aprobar / Rechazar**. Solo el chat privado del propietario vinculado puede usarlos; los toques caducados o repetidos no pueden ejecutar la acción de nuevo. La aprobación caduca 24 horas después de la confirmación del cliente. El cliente recibe el resultado, incluido un rechazo o una caducidad. Las ejecuciones recientes muestran el estado, las marcas de tiempo, la referencia y el ID del cliente.

## Qué recibe tu endpoint [#qué-recibe-tu-endpoint]

No se envía ninguna solicitud cuando el modelo propone el cambio. Tras la confirmación del cliente y la aprobación del propietario, si se requiere, Make Agent Fast envía:

```http
POST /agent/cancel-order HTTP/1.1
Content-Type: application/json
x-maf-timestamp: <unix-seconds>
x-maf-signature: v1=<64-lowercase-hex-characters>
x-maf-idempotency-key: c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b
```

```json
{
  "version": 1,
  "action": "cancel_order",
  "runId": "c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b",
  "requestId": "c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b",
  "siteId": "YOUR_SITE_ID",
  "input": { "order_id": "A128" },
  "customer": { "id": "customer_123", "email": "customer@example.com" }
}
```

`action` no incluye el prefijo `change_`. Ambos ID y la cabecera de idempotencia se mantienen iguales en los reintentos. `input` contiene únicamente cadenas declaradas y sin espacios sobrantes; `customer` es null o el objeto verificado con `id` y, opcionalmente, `email`/`name`.

Usa el [verificador de firma de las consultas](/es/docs/build/lookups#verify-the-signature): HMAC-SHA256 con el secreto de tu agente sobre `"maf-webhook-v1:" + timestamp + "." + rawBody`, en hexadecimal en minúsculas con el prefijo `v1=`. Verifica los bytes originales, la vigencia de la marca de tiempo, el sitio y la acción esperados, y la pertenencia del registro al cliente antes de escribir. **Deduplica de forma atómica `x-maf-idempotency-key` junto con tu cambio y conserva el resultado.** Una solicitud repetida debe devolver el resultado guardado sin modificar el registro de nuevo. El bloqueo de la plataforma no puede sustituir la deduplicación en tu sistema.

## Devuelve un resultado [#devuelve-un-resultado]

Devuelve un JSON con código 2xx que incluya el campo obligatorio `status` (`done`, `pending` o `failed`) y, opcionalmente, `message`, `reference` y `card`:

```json
{
  "status": "done",
  "message": "Order cancelled.",
  "reference": "A128",
  "card": {
    "kind": "status",
    "title": "Order A128",
    "fields": [{ "label": "Order", "value": "A128" }]
  }
}
```

La tarjeta de estado opcional requiere `title` y `fields`; `kind: "status"` es opcional. Admite `status: { label, tone }`, `reference`, `asOf` y `link: { label, url }`, como en las [consultas](/es/docs/build/lookups#return-a-response). Los tonos son `neutral`, `success`, `warning` o `danger`; los enlaces deben ser URL HTTPS seguras. Los campos que no estén en el esquema se rechazan. Mantén el texto breve y sencillo. El `status` externo determina el resultado; el texto de la tarjeta no puede convertir un resultado pendiente en un éxito.

Usa `done` solo cuando el cambio esté completado, `pending` cuando aún se esté procesando y `failed` para un fallo conocido. Los tiempos de espera agotados, los errores de red, los 5xx y las respuestas no válidas se tratan como inciertos (`unknown`). La reconciliación reintenta tras un minuto y luego tras cinco minutos, con un máximo de tres intentos de ejecución y la misma clave; la programación de la cola puede retrasar estos tiempos. Un HTTP 4xx falla sin reintento. Si se agota la incertidumbre, la ejecución falla y se notifica al propietario, pero eso no demuestra que tu sistema no haya realizado ningún cambio. Investígalo antes de iniciar otra ejecución. `pending` no desencadena otra ejecución.

## Envía un callback final firmado [#envía-un-callback-final-firmado]

Cuando una ejecución `pending` o `unknown` se resuelva, envía mediante POST una respuesta final a `https://makeagent.fast/api/agent/actions/RUN_ID/callback`. Envía el mismo contrato de respuesta con `status: "done"` o `"failed"`; aquí no se acepta `pending`.

Contrato de callback actualizado el 2026-10-14: firma `maf-callback-v1:` + runId + `:` + timestamp + `.` + rawBody. Si el cuerpo incluye `runId`, debe coincidir con el ID de ejecución de la ruta; si no coincide, se devuelve 400. Las firmas de otra ejecución o del formato anterior sin vinculación devuelven 403.

```js
import { createHmac } from "node:crypto";

const body = JSON.stringify({ status: "done", reference: "A128" });
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = createHmac("sha256", agentSecret)
  .update(`maf-callback-v1:${runId}:${timestamp}.${body}`)
  .digest("hex");
const response = await fetch(
  `https://makeagent.fast/api/agent/actions/${encodeURIComponent(runId)}/callback`,
  {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-maf-timestamp": timestamp,
      "x-maf-signature": `v1=${signature}`,
    },
    body,
  },
);
```

Usa el secreto del agente almacenado en tu servidor y el ID de ejecución recibido en la solicitud original. El callback usa **`maf-callback-v1:`**, no el espacio de nombres de la solicitud saliente. El desfase de la marca de tiempo debe ser de cinco minutos como máximo. Las firmas no válidas devuelven 403; los cuerpos no válidos devuelven 400; una ejecución ya terminada o incompatible devuelve 409. Un callback repetido no sobrescribe el resultado final. Rota este secreto junto con la configuración de identidad y de firma de tu endpoint.

## Confirmación del cliente y recibos [#confirmación-del-cliente-y-recibos]

El cliente revisa las entradas exactas y pulsa **Confirmar** o **Cancelar** en la propuesta. Una propuesta caduca a los 15 minutos; una nueva propuesta para la misma acción y conversación reemplaza a la anterior. La confirmación usa un token vinculado a esa ejecución, sitio y visitante. Escribir «sí» o hacer clic en una tarjeta de confirmación genérica no autoriza el cambio. Los botones del ensayo están inactivos y no llaman a tu endpoint.

En la web, el widget abierto consulta periódicamente los recibos no finalizados, al principio cada cinco segundos y después cada 30 segundos, durante un máximo de 24 horas. Un recibo puede mostrar los estados solicitado, esperando al propietario, en ejecución, pendiente, comprobando un resultado desconocido, completado, fallido, rechazado, cancelado o caducado. Solo `done` confirma la finalización.

Las propuestas en los canales funcionan **solo en chats privados**, nunca en grupos ni en canales. Los recibos diferidos usan el buzón de salida duradero: se admiten los mensajes directos normales de bots de Telegram; WhatsApp, Messenger, Instagram y Telegram Business requieren un mensaje entrante registrado en las últimas 24 horas, que se vuelve a comprobar en el momento del envío. El envío diferido no está disponible para las consultas de invitados de Telegram, Discord ni KakaoTalk. Las ventanas cerradas y las conexiones desactivadas pueden impedir la entrega; el historial de ejecuciones sigue registrando el resultado.

## Límites y pruebas [#límites-y-pruebas]

| Elemento                                                             | Límite                                                                                                                     |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Acciones de cambio                                                   | 5 por agente; los nombres deben ser únicos entre cambios y consultas                                                       |
| Nombres                                                              | Acción: `^[a-z][a-z0-9_]{2,39}$`; entrada: `^[a-z][a-z0-9_]{1,31}$`; los nombres de acción reservados no están disponibles |
| Descripciones                                                        | 300 caracteres                                                                                                             |
| Entradas                                                             | 3 cadenas declaradas, de 200 caracteres como máximo cada una                                                               |
| Endpoint                                                             | HTTPS público, hasta 500 caracteres, sin credenciales en la URL, direcciones privadas ni redirecciones                     |
| Tiempo de espera de ejecución / respuesta / cuerpo del callback      | 8 segundos / 32 KiB / 32 KiB                                                                                               |
| Título de la tarjeta de estado / etiqueta del campo / valor / campos | 80 / 40 / 200 caracteres / 8 campos                                                                                        |
| Caducidad de la propuesta / de la aprobación                         | 15 minutos / 24 horas después de la confirmación                                                                           |

Usa un endpoint controlado para verificar la confirmación, la cancelación, la aprobación, el tiempo de espera agotado, la gestión de claves duplicadas y los callbacks finales. Comprueba sus registros, no solo el texto del recibo. El ensayo demuestra que no se realiza ninguna escritura externa; no es una prueba de ejecución del endpoint. Prueba cada canal privado previsto antes de confiar en los recibos.

---

# Crear un agente

Source: /es/docs/build/create-agent.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/build/persona&#x22;, label: &#x22;Personalidad&#x22;, icon: &#x22;account&#x22; },
{ href: &#x22;/es/docs/build/knowledge&#x22;, label: &#x22;Conocimiento&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/es/docs/build/voice&#x22;, label: &#x22;Voz&#x22;, icon: &#x22;voice&#x22; },
{ href: &#x22;/es/docs/build/appearance&#x22;, label: &#x22;Aspecto&#x22;, icon: &#x22;spark&#x22; }
]"
/>

El primer agente parte de la **URL de un sitio web**. Rastreamos las páginas públicas a las que podemos acceder, redactamos un borrador del agente (incluido el estilo del widget a partir de esos datos) y lo mantenemos fuera de tu sitio web hasta el último paso de la incorporación. El chat para construir está desactivado. No existe ninguna función para generar un sitio ni un constructor de secciones.

<TutorialVideo episode="ep01" start="14" />

## Pega una URL [#pega-una-url]

En la página de inicio, pega la URL y continúa. El registro y el inicio de sesión conservan `next=/onboarding/launch?url=…`, así que no se te pedirá pegarla de nuevo. `/try` permite a los visitantes pegar una URL y hablar con un borrador con marca de agua (solo texto y con límite) antes de reclamarlo al registrarse.

Si ya tienes sitios, una URL pegada sigue creando un **nuevo** borrador sin publicar. Si la misma URL ya está en curso, se reanuda en lugar de duplicarse. Un sitio de primera configuración ya terminado no se reutiliza.

No pegues contraseñas, datos privados de clientes ni tokens de conectores en el campo de la URL.

## Espera en la pantalla de generación [#espera-en-la-pantalla-de-generación]

Mientras se crea el borrador, la pantalla de generación muestra el progreso real de ingesta, composición y examen, no un indicador de carga falso:

| Paso                    | Qué hace                                                                  |
| ----------------------- | ------------------------------------------------------------------------- |
| **Leyendo el sitio**    | Obtiene las páginas públicas de la URL                                    |
| **Creando el agente**   | Compone el agente y el estilo del widget a partir de los datos rastreados |
| **Probando respuestas** | Ejecuta una autoevaluación con ese conocimiento                           |

La espera habitual es de unos segundos; un sitio más grande puede tardar hasta aproximadamente un minuto. Si el rastreo aporta poco, el borrador usa igualmente lo que se haya encontrado. Puedes añadir fuentes después de la revisión.

El borrador nunca se publica automáticamente. Los agentes nuevos no tienen una página de marketing alojada.

## Conoce al agente y publícalo [#conoce-al-agente-y-publícalo]

Una vez creado el borrador, la incorporación muestra dos pantallas más:

* **Conoce a tu agente**: el chat real junto a tres comprobaciones rápidas. Pregunta, lee la respuesta y acéptala o corrígela. El ensayo por texto consume créditos; las solicitudes de contacto y las acciones se simulan.
* **Ponlo donde están tus clientes**: el último paso. Activa el widget del sitio web para el sitio que pegaste y activa el **Enlace del agente** (una página de chat pública en la dirección propia de tu agente) para que puedas probarlo en tu teléfono en **Pruébalo en tu teléfono**. Añade el código de instalación a tu sitio y pulsa **Comprobar mi sitio**.

Después, el agente se abre en su página **Agente**, el primer elemento de la barra lateral del agente: las pestañas **Resumen**, **Pantalla**, **Voz** y **Acciones** junto a un lienzo en vivo que muestra el widget real en la esquina que elegiste. Pregúntale lo que preguntaría un cliente justo ahí. En **Resumen**, **Comprobación de respuestas** → **Ejecutar una comprobación** evalúa las respuestas según tu conocimiento.

Hablar con el agente en el panel es una prueba del propietario. No se publica y no cuenta para la activación.

Para poner el widget en tu sitio web más adelante, abre **Publicar** → **Widget del sitio web** en la página Agente. Si el widget aún no está activado, elige **Activar incrustación**. Una vez activado, la misma hoja muestra el código de instalación, el interruptor **Mostrar en mi sitio web** y **Direcciones web permitidas**. Puedes ocultar el widget en cualquier momento con ese interruptor o con la tarjeta **En tu sitio web** de la pestaña **Resumen**.

## Activación [#activación]

Cuando ya estés en línea, añade la incrustación o conecta un canal. El sitio queda **activado** con la primera conversación de un visitante o el primer lead captado. Las pruebas del panel nunca cuentan.

## Edita después del primer borrador [#edita-después-del-primer-borrador]

No hay chat para construir. Después de la revisión, actualiza:

* Las instrucciones en la pestaña **Resumen** de la página Agente, y **Voz** y **Pantalla** en sus pestañas contiguas.
* **Conocimiento** en su propia página en la barra lateral del agente.
* Los cambios de **Pantalla** se guardan automáticamente y actualizan la incrustación en vivo sin necesidad de volver a publicar.

## Empieza sin la URL de un sitio web [#empieza-sin-la-url-de-un-sitio-web]

Si envías el formulario de la página de inicio vacío, **Probar** se abre igualmente. Los visitantes anónimos pueden pegar allí una URL y hablar con un borrador; reclámalo al registrarte para continuar con la incorporación. Una URL pegada siempre sigue el camino de la pantalla de generación descrito arriba.

---

# Preguntas frecuentes y productos

Source: /es/docs/build/faqs-products.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Preguntas frecuentes&#x22;, icon: &#x22;book&#x22; }, { label: &#x22;Productos&#x22;, icon: &#x22;layers&#x22; }, { label: &#x22;Conocimiento&#x22;, icon: &#x22;link&#x22; }]" />

## Usa preguntas frecuentes para las respuestas de referencia [#usa-preguntas-frecuentes-para-las-respuestas-de-referencia]

Crea una pregunta frecuente por cada intención del visitante. Redacta la pregunta con el lenguaje que usan tus clientes y asegúrate de que la respuesta sea completa por sí sola, sin depender de otra pregunta frecuente.

## Usa productos para los datos del catálogo [#usa-productos-para-los-datos-del-catálogo]

Los productos son ideales para una oferta con nombre y campos como descripción, precio, disponibilidad o enlace. Mantén actualizados los datos transaccionales y evita prometer inventario o plazos de entrega, a menos que tu fuente se actualice de forma fiable.

## Evita la duplicación [#evita-la-duplicación]

No mantengas el mismo precio en una nota, una pregunta frecuente, una sección de página y un registro de producto. Elige una única fuente de referencia y enlázala o menciónala en el resto de lugares.

## Verifica el comportamiento de cara al cliente [#verifica-el-comportamiento-de-cara-al-cliente]

Después de cada cambio, hazle al agente la pregunta frecuente con varias formulaciones distintas y confirma que el enlace y el precio del producto son correctos.

---

# Seguimientos y recordatorios

Source: /es/docs/build/follow-ups.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/build/page-actions&#x22;, label: &#x22;Acciones de página&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/es/docs/build/lookups&#x22;, label: &#x22;Consultas&#x22;, icon: &#x22;book&#x22; }
]"
/>

## Ofrece ayuda en el momento adecuado [#ofrece-ayuda-en-el-momento-adecuado]

Abre **Agente → Acciones → Seguimientos**. Añade hasta cinco reglas para una visita a una página, un visitante inactivo, una intención de salida, un error de formulario o un evento personalizado. Elige un patrón de ruta, un retraso opcional, un mensaje de hasta 200 caracteres y hasta tres respuestas rápidas. Los ajustes se guardan automáticamente. La vista previa muestra el mensaje sin contactar con ningún cliente ni añadir datos al experimento.

Usa `/pricing` para una sola ruta, `/products/*` para un segmento o `/products/**` para rutas anidadas. Las consultas (query) y los fragmentos quedan excluidos. El retraso por inactividad predeterminado es de 30 segundos y el tiempo de espera entre apariciones (cooldown) predeterminado es de siete días. Un disparador no interrumpirá una intervención humana (handoff) ni una conversación activa abierta, no se repetirá en la misma sesión y no volverá a aparecer tras descartarlo en esa sesión.

El código de inserción (embed) informa de las visitas a páginas, la inactividad y la intención de salida. Tu desarrollador puede informar de eventos personalizados con `MakeAgentFast.track`; consulta [Acciones de página](/es/docs/build/page-actions). El informe automático de errores de formulario está desactivado a menos que el embed use `data-auto-form-error="true"` o `MakeAgentFastSettings.autoFormError = true`. Informa del ID del formulario, nunca de los valores de los campos.

## Interpreta los resultados del grupo de control [#interpreta-los-resultados-del-grupo-de-control]

De forma predeterminada, el 10 % de los visitantes elegibles se asigna a un grupo de control estable y no ve ningún mensaje. La asignación pertenece al visitante y a la regla; las visitas repetidas no inflan la muestra. El panel compara las tasas de conversión de los visitantes elegibles del grupo con mensaje y del grupo de control, y muestra el aumento absoluto en puntos porcentuales.

Una conversión es un lead, una reserva, una acción completada o una consulta exitosa registrados dentro de las 24 horas siguientes a una exposición elegible. Las aperturas y las respuestas se muestran por separado. Los eventos informados desde el navegador no pueden declarar conversiones. Con menos de 50 visitantes por grupo, el panel indica que no hay datos suficientes; a partir de ese umbral muestra un intervalo del 95 % sencillo. Las diferencias pequeñas no demuestran que el mensaje haya generado más ventas.

## Avisa a un cliente cuando algo cambie [#avisa-a-un-cliente-cuando-algo-cambie]

Los clientes pueden pedir «Avísame cuando haya un horario disponible» o «Avísame cuando cambie el estado de mi pedido». Una vigilancia (watch) monitoriza la disponibilidad de un calendario conectado o un campo/estado en una [consulta](/es/docs/build/lookups) configurada. Las vigilancias de consultas requieren un cliente con sesión iniciada y verificado. No monitorizan páginas arbitrarias ni programan recordatorios recurrentes.

El agente propone una vigilancia con su destino y su fecha de finalización. El cliente debe pulsar el botón de confirmación en un plazo de 15 minutos. Los visitantes del sitio web y de llamadas en directo, además, introducen un correo electrónico y marcan en pantalla la casilla de consentimiento para el correo; un «sí» escrito o hablado no es suficiente. El correo contiene un aviso genérico y un enlace de corta duración para volver. Ese enlace no inicia sesión al destinatario ni concede acceso a los registros del cliente.

Cada visitante puede tener tres vigilancias activas o pendientes, con un máximo de 50 por agente y una duración máxima de 14 días. Las comprobaciones empiezan a los 15 minutos y después se espacian a una hora y a seis horas. Cada vigilancia envía un único intento de notificación y después se detiene. Cancélala desde los controles de la propia vigilancia o desde la lista de Seguimientos del owner. Cambiar la configuración de la consulta o del calendario subyacente puede detener una vigilancia. Una entrega incierta no se reenvía automáticamente.

## Haz seguimiento en los chats y consúltate cuando el agente se atasque [#haz-seguimiento-en-los-chats-y-consúltate-cuando-el-agente-se-atasque]

Abre **Agente → Acciones → Seguimientos → Seguimientos de chat**. Estos dos interruptores se aplican a los chats de Telegram, WhatsApp, Messenger e Instagram.

**Hacer seguimiento cuando un cliente deja de responder** está activado de forma predeterminada para los agentes de ventas y desactivado para los demás tipos de agente. Cuando un cliente deja de responder tras una respuesta, el agente vuelve a leer el chat y, o bien envía un mensaje breve, o bien espera un poco más, o bien lo deja en paz. Un agente de ventas avanza hacia la compra, un agente de atención comprueba que el problema se haya resuelto y un agente de reservas ofrece un horario. Solo usa tus fuentes de conocimiento aprobadas y la conversación, y se detiene cuando el cliente responde, rechaza o pide que no le escriban. Los canales de Meta solo aceptan mensajes automatizados durante las 24 horas posteriores al último mensaje del cliente, por lo que ahí el seguimiento llega dentro de ese día; un chat con un bot de Telegram puede recibir hasta dos seguimientos a lo largo de varios días. Cada seguimiento se factura como una respuesta.

**Consultarme cuando el agente no pueda responder** está activado de forma predeterminada. En lugar de pedir un correo electrónico, el agente le dice al cliente que lo está consultando con el equipo y te avisa con un enlace a la conversación. Responde ahí o guarda la respuesta en las fuentes de conocimiento, y el agente se la enviará al cliente en su idioma. Instagram y Messenger aceptan tu respuesta durante las 24 horas posteriores al último mensaje del cliente, o hasta 7 días una vez que tu app de Meta tenga el permiso Human Agent.

## Entrega y disponibilidad [#entrega-y-disponibilidad]

| Destino                        | Límite actual                                                                                                                                         |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sitio web / llamada en directo | Correo electrónico con consentimiento explícito; sin notificaciones push en segundo plano desde el widget                                             |
| Telegram                       | Chat privado existente con el bot; un chat privado de Business también requiere una ventana de 24 horas abierta                                       |
| WhatsApp                       | Mensaje libre dentro de las 24 horas posteriores a un mensaje entrante del cliente; fuera de ese plazo se requiere una plantilla de utilidad aprobada |
| Messenger / Instagram          | Solo dentro de las 24 horas posteriores a un mensaje entrante del cliente                                                                             |
| Discord / KakaoTalk            | Transporte de vigilancias no disponible; la política de Kakao además exige una plantilla de AlimTalk y excluye de 20:50 a 08:00 KST                   |

Las restricciones de cada canal se comprueban de nuevo en el momento de la entrega. Una vigilancia con consentimiento no las anula ni garantiza que el mensaje se entregue.

---

# Google Calendar

Source: /es/docs/build/google-calendar.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/build/cal-com&#x22;, label: &#x22;Cal.com&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/es/docs/build/follow-ups&#x22;, label: &#x22;Alertas de disponibilidad&#x22;, icon: &#x22;book&#x22; }
]"
/>

## Disponibilidad de la función [#disponibilidad-de-la-función]

**Google Calendar aún no está disponible de forma general.** Hasta que se habilite, **Agente → Acciones → Google Calendar** muestra «próximamente» y la conexión no está disponible; un ajuste del agente no puede activarla. [Cal.com](/es/docs/build/cal-com) sigue siendo una opción independiente.

## Conectar un calendario [#conectar-un-calendario]

Cuando esté habilitado, abre el panel de Google Calendar y elige **Conectar**. Inicia sesión en Google y revisa los permisos solicitados para los eventos del calendario y la disponibilidad libre/ocupado. Esta conexión es independiente del inicio de sesión en Make Agent Fast. El servidor almacena el refresh token cifrado; ni el panel ni el agente lo reciben.

Los scopes solicitados son `calendar.events`, `calendar.freebusy` y los no sensibles `openid` y `email`. El callback requiere un correo electrónico verificado y lo almacena cifrado para resolver `primary` al mismo ID de calendario que su escritura explícita con el correo. No se solicita ningún scope de perfil. Las conexiones antiguas sin correo verificado deben desconectarse y volver a conectarse antes de poder reservar.

Un agente usa un solo proveedor de calendario a la vez. Desconecta el proveedor existente antes de cambiar. Elige el ID del calendario (`primary` para el calendario principal de la cuenta conectada) y su zona horaria IANA, por ejemplo `Asia/Seoul`. Un calendario compartido debe ser accesible con los permisos de la cuenta conectada. Al desconectar, se revoca la autorización de Google y se elimina la conexión; no se cancelan los eventos existentes.

## Definir el horario laboral [#definir-el-horario-laboral]

Las conexiones nuevas no tienen horario laboral, por lo que no se ofrecerán franjas hasta que lo añadas. Añade ventanas de apertura y cierre para cada día laborable. Un día vacío se considera cerrado; varias ventanas que no se solapen permiten una pausa para comer. Los horarios se interpretan en la zona horaria seleccionada. Los ajustes se guardan automáticamente.

| Ajuste                               | Rango admitido                                             |
| ------------------------------------ | ---------------------------------------------------------- |
| Duración de la franja                | 5–240 minutos                                              |
| Margen alrededor de eventos ocupados | 0–120 minutos                                              |
| Antelación mínima                    | 0–43 200 minutos                                           |
| Horizonte de reserva                 | 1–90 días                                                  |
| Ventanas de trabajo                  | Hasta 28 ventanas sin solapamiento a lo largo de la semana |

La disponibilidad es el horario laboral menos los bloques ocupados del calendario seleccionado, el margen, la antelación mínima y el horizonte. Define los horarios en la zona horaria prevista del calendario y revisa los cambios de horario de verano cuando corresponda. Que no haya franjas puede significar horario cerrado u horas ocupadas, y no necesariamente un error de conexión.

## De la disponibilidad a una reserva [#de-la-disponibilidad-a-una-reserva]

El agente usa el mismo flujo `find_slots` y `book_slot` que Cal.com: ofrece hasta ocho horarios disponibles, recopila nombre y correo electrónico y una nota opcional, vuelve a comprobar la franja elegida y luego muestra una tarjeta de confirmación. Las ofertas y propuestas caducan a los 15 minutos; ninguna reserva la franja. Solo el toque del cliente en el botón autoriza la reserva. Un «sí» dicho durante una llamada en directo no puede reservarla.

Tras la confirmación, Google recibe un evento con un ID determinista vinculado a la ejecución de la acción y envía invitaciones a los asistentes. Un evento confirmado y validado genera un comprobante completado; los eventos provisionales permanecen pendientes. Si una franja ya está ocupada, solicita nuevos horarios y confirma de nuevo. Un resultado de red incierto se comprueba usando el mismo ID de evento; no consideres un tiempo de espera agotado como un éxito ni crees otra reserva a ciegas. Los cambios de configuración invalidan las ofertas y propuestas anteriores.

Para recibir un aviso cuando se libere un horario, usa un [seguimiento](/es/docs/build/follow-ups) con consentimiento. Antes de abrirlo a los clientes, verifica una reserva y su invitación reales en Google, prueba una franja ocupada y comprueba la desconexión y reconexión, así como el canal de mensajería previsto.

---

# Fuentes de conocimiento

Source: /es/docs/build/knowledge.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;message&#x22;, title: &#x22;Pegar texto&#x22;, description: &#x22;Datos y políticas redactados por el owner, de hasta 200 000 caracteres.&#x22; },
{ icon: &#x22;link&#x22;, title: &#x22;URLs y feeds&#x22;, description: &#x22;Obtén páginas públicas o contenido web que se actualiza de forma recurrente.&#x22; },
{ icon: &#x22;book&#x22;, title: &#x22;Archivos&#x22;, description: &#x22;Extrae texto de archivos PDF, Word, Excel, PowerPoint, HWP, OpenDocument, RTF y de texto.&#x22; },
{ icon: &#x22;voice&#x22;, title: &#x22;Multimedia&#x22;, description: &#x22;Usa los subtítulos disponibles de YouTube o transcribe audio de podcast compatible.&#x22; }
]"
/>

El conocimiento le da al agente material de origen que puede recuperar. Al añadir una fuente, se extrae el texto sin formato, se divide en pasajes, se crean embeddings y se asocian esos pasajes con el sitio actual. En el momento de responder, el agente recupera los pasajes relevantes en lugar de recibir todas las fuentes en cada prompt.

<TutorialVideo episode="ep01" start="168" />

## Elige el tipo de fuente adecuado [#elige-el-tipo-de-fuente-adecuado]

| Fuente            | Ideal para                                                                                                                                                                                          | Comportamiento importante                                                                                                                                                          |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Pegar texto**   | Políticas, datos de contacto, notas internas breves                                                                                                                                                 | De 5 a 200 000 caracteres; sin actualización automática                                                                                                                            |
| **Desde URL**     | Páginas públicas que se mantienen en otro lugar                                                                                                                                                     | Una página por defecto; opcionalmente, rastrea 5, 10, 20 o 40 páginas del mismo sitio                                                                                              |
| **Subir archivo** | PDF, Word (`.docx`, `.doc`), Excel (`.xlsx`, `.xls`), PowerPoint (`.pptx`), Hancom `.hwp` y `.hwpx`, OpenDocument (`.odt`, `.ods`, `.odp`), `.rtf`, `.txt`, `.md`, `.csv`, `.tsv`, `.json`, `.html` | Máximo 20 MB; se rechazan los archivos protegidos con contraseña y los que tienen macros habilitadas; los PDF escaneados que solo contienen imágenes no tienen texto seleccionable |
| **YouTube**       | Vídeos públicos con contenido hablado útil                                                                                                                                                          | Operate o Scale. Intenta primero los subtítulos y después la transcripción disponible; mejor esfuerzo                                                                              |
| **Podcast**       | La URL del audio de un episodio público o un feed compatible                                                                                                                                        | Operate o Scale. Requiere audio accesible y un proveedor de transcripción disponible                                                                                               |
| **Blog / RSS**    | Actualizaciones públicas de un blog o podcast en RSS/Atom                                                                                                                                           | Operate o Scale. Extrae como texto los elementos del feed disponibles; mejor esfuerzo                                                                                              |

Usa **FAQ y productos** para campos previsibles de pregunta/respuesta o de catálogo, en lugar de enterrarlos en un documento largo. Consulta [FAQs y productos](/es/docs/build/faqs-products).

## Añadir una fuente [#añadir-una-fuente]

1. Abre la página **Conocimiento** del agente desde su barra lateral y selecciona **Añadir fuente**.
2. Selecciona **Pegar texto**, **Desde URL** o **Subir archivo**. **YouTube**, **Podcast** y **Blog / RSS** se encuentran en **Más tipos de fuente** y requieren Operate o Scale; en Launch aparecen con un candado.
3. Introduce el contenido o elige un archivo.
4. En **Desde URL**, elige **Páginas a rastrear** (1, 5, 10, 20 o 40). En las fuentes obtenidas de la web, puedes configurar opcionalmente **Actualización automática** como **Diaria**, **Semanal** o **Nunca**.
5. Selecciona **Añadir al conocimiento** y espera el resultado, que muestra el número de fragmentos indexados.
6. Haz una pregunta cuya respuesta solo aparezca en la nueva fuente.

La ingesta de conocimiento consume créditos porque se generan embeddings de los pasajes de la fuente. Se rechaza cuando el espacio de trabajo no tiene acceso activo o un saldo de créditos utilizable.

## Rastrea páginas públicas de forma segura [#rastrea-páginas-públicas-de-forma-segura]

El rastreador acepta contenido HTTP/HTTPS público y bloquea los destinos de redes privadas que no son seguros. Empieza con una sola página canónica. Aumenta el número de páginas solo cuando las páginas enlazadas formen parte del mismo conjunto de información útil; un rastreo más grande puede incorporar navegación, textos legales genéricos, texto duplicado o archivos obsoletos que empeoran la recuperación.

El número seleccionado es un máximo, no una garantía. El comportamiento de robots, la autenticación, el renderizado solo en el cliente, las redirecciones, el tipo de contenido, el tamaño de la respuesta y la estructura de enlaces pueden reducir el número de páginas obtenidas. La respuesta de una página está limitada a 5 MB y debe contener suficiente texto extraíble.

Para datos importantes que están tras un inicio de sesión, pega un resumen aprobado o sube una exportación depurada en lugar de intentar rastrear una página autenticada.

## Usa archivos y contenido multimedia [#usa-archivos-y-contenido-multimedia]

Los archivos subidos deben contener texto extraíble. No se aplica OCR a un PDF escaneado que solo contiene imágenes; conviértelo a texto con capacidad de búsqueda antes de subirlo. Las hojas de cálculo se leen hoja por hoja y las filas de las tablas mantienen sus celdas juntas (`Coffee | 3000`); el resto del diseño se aplana en orden de lectura, así que procura que las tablas sean sencillas. Quita la contraseña de un documento antes de subirlo y guarda los archivos de Office con macros habilitadas (`.docm`, `.xlsm`, `.pptm`) como archivos normales `.docx`, `.xlsx` o `.pptx` antes de subirlos. Se rechaza un archivo cuyo contenido no coincide con su extensión.

La ingesta de YouTube prefiere una pista de subtítulos disponible. Si no hay subtítulos, la transcripción depende del proveedor y de la red. El audio de un podcast debe ser accesible públicamente. Los resultados de un feed dependen de cuánto texto de artículo o episodio exponga el feed. Después de cualquier importación de contenido multimedia, revisa el título de la fuente y el número de fragmentos, y prueba con un dato concreto en lugar de dar por hecho que se capturó la grabación completa.

## Planifica la actualización y el reemplazo [#planifica-la-actualización-y-el-reemplazo]

Las programaciones diaria y semanal están disponibles para fuentes de URL, YouTube, podcast y feed. El sistema vuelve a obtener el origen guardado de la fuente y reemplaza sus pasajes recuperables cuando un rastreo programado se completa correctamente. La lista de fuentes muestra la frecuencia de actualización y la hora de la última actualización.

Las fuentes pegadas y subidas son instantáneas. Para corregir o reemplazar una, elimínala y añade el contenido actualizado. Al eliminar una fuente, sus pasajes dejan de recuperarse en el futuro; esto no modifica los mensajes anteriores que ya citaron o resumieron la versión antigua.

Usa una única fuente de referencia clara para precios, políticas y horarios. Si dos fuentes activas se contradicen, la recuperación puede mostrar cualquiera de las dos afirmaciones. Elimina las versiones obsoletas en lugar de añadir copias «nuevas» junto a ellas.

## Redacta contenido que el agente pueda recuperar [#redacta-contenido-que-el-agente-pueda-recuperar]

* Indica el tema en cada sección: «Política de cancelación del plan Pro» se recupera mejor que «Más detalles».
* Pon la respuesta en lenguaje sencillo cerca del encabezado correspondiente.
* Incluye unidades, moneda, zona horaria, fecha de entrada en vigor y excepciones cuando sean relevantes.
* Usa URLs canónicas estables y nombres de archivo descriptivos.
* Separa la información pública de las instrucciones internas o los registros privados.
* Mantén el comportamiento de la personalidad en [Personalidad e instrucciones](/es/docs/build/persona), no dentro del material de origen factual.

## Prueba las respuestas basadas en fuentes [#prueba-las-respuestas-basadas-en-fuentes]

Crea un pequeño conjunto de pruebas de aceptación antes de publicar:

1. Una pregunta directa cuya respuesta sea explícita en la fuente.
2. Una paráfrasis que use palabras distintas.
3. Una pregunta límite que la fuente no responda.
4. Un dato que haya cambiado recientemente.
5. Una variante de idioma para cada idioma configurado del agente.

El resultado correcto no siempre es una respuesta segura. Cuando la fuente no contiene el dato, el agente debe seguir sus instrucciones de respaldo o de escalado en lugar de inventarlo. Revisa **Conversaciones** después del lanzamiento para detectar preguntas sin respuesta repetidas y convierte las respuestas validadas en una fuente o en una FAQ estructurada.

## Solución de problemas [#solución-de-problemas]

| Síntoma                                                                             | Qué comprobar                                                                                                                                             |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| La URL indica que no hay texto utilizable                                           | Acceso público, tipo de contenido compatible, texto renderizado en el servidor, destino de la redirección y tamaño de la página                           |
| El PDF indica que no hay texto seleccionable                                        | Si es un escaneo; aplícale OCR o expórtalo a un PDF con capacidad de búsqueda o a un archivo de texto                                                     |
| Archivo rechazado por estar protegido con contraseña o por no coincidir con su tipo | Quita la contraseña y vuelve a guardar el archivo en su formato real en lugar de cambiarle el nombre; guarda los archivos de Office con macros sin macros |
| Falla la importación de YouTube/podcast                                             | URL pública, disponibilidad de subtítulos/audio, clave del proveedor de transcripción y restricciones de obtención                                        |
| Se ignora un dato correcto                                                          | Resultado del procesamiento, redacción, fuentes en conflicto, antigüedad de la fuente y la pregunta de prueba exacta                                      |
| El agente revela demasiado                                                          | Elimina de inmediato la fuente privada y refuerza los límites de la personalidad y el acceso a la cuenta                                                  |
| Persiste una respuesta antigua                                                      | Elimina o reemplaza la fuente obsoleta, espera a que se reindexe e inicia una nueva conversación de prueba                                                |

Nunca subas credenciales, claves privadas, exportaciones de clientes sin restricciones, historiales médicos ni ningún contenido que el agente público nunca deba revelar.

---

# Consultas

Source: /es/docs/build/lookups.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/embed/security&#x22;, label: &#x22;Clientes con sesión iniciada&#x22;, icon: &#x22;shield&#x22; },
{ href: &#x22;/es/docs/build/knowledge&#x22;, label: &#x22;Fuentes de conocimiento&#x22;, icon: &#x22;book&#x22; }
]"
/>

## Cuándo usar una consulta [#cuándo-usar-una-consulta]

Usa una consulta para obtener el estado actual de un pedido, una reserva existente o el registro de la cuenta de un cliente. Mantén las políticas estables y la información de productos en [Conocimiento](/es/docs/build/knowledge). Una consulta lee tu sistema; no debe cobrar, cancelar, reservar ni modificar de ningún otro modo un registro. Las tarjetas genéricas de elección y confirmación solo envían un mensaje del visitante. Para escrituras confirmadas, usa [Acciones de cambio](/es/docs/build/change-actions); para reservas de calendario, usa [Reservas con Cal.com](/es/docs/build/cal-com). Solo las tarjetas de confirmación respaldadas por una ejecución autorizan esas operaciones.

## Configura la acción [#configura-la-acción]

Abre **Agente → Acciones**. Crea el secreto en **Clientes con sesión iniciada**, guárdalo en tu servidor e implementa la [identificación de clientes](/es/docs/embed/security#identify-signed-in-customers). En **Consultas**, añade un nombre como `order_status`, explica cuándo debe usarla el agente e introduce tu endpoint HTTPS público. Declara solo las entradas que necesites, por ejemplo una cadena `order_id`. El agente ve la herramienta como `lookup_order_status`.

Mantén activada la opción **Requiere cliente con sesión iniciada** para registros privados (es el valor predeterminado). Si la desactivas, las solicitudes pueden contener `customer: null`; devuelve solo información apropiada para un visitante anónimo. Un ID mencionado en el chat o extraído de una foto es una entrada, no una identidad autenticada.

Los campos existentes se guardan automáticamente; espera al indicador de guardado antes de probar. Puedes activar o desactivar, editar o eliminar una consulta. El panel requiere un secreto configurado. Estas acciones se configuran en el panel; la primera fase no expone la gestión de consultas a través de la API pública.

## La solicitud que recibes [#la-solicitud-que-recibes]

Make Agent Fast envía un POST JSON a la URL que configuraste. Los ejemplos siguientes usan valores de firma de marcador de posición:

```http
POST /agent/order-status HTTP/1.1
Content-Type: application/json
x-maf-timestamp: <unix-seconds>
x-maf-signature: v1=<64-lowercase-hex-characters>
```

```json
{
  "version": 1,
  "action": "order_status",
  "requestId": "c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b",
  "siteId": "YOUR_SITE_ID",
  "input": { "order_id": "A128" },
  "customer": { "id": "customer_123", "email": "customer@example.com" }
}
```

`action` es el nombre configurado sin el prefijo `lookup_`. `requestId` identifica ese intento; `siteId` identifica tu sitio. `input` contiene únicamente los parámetros de tipo cadena declarados. `customer` es null o el objeto `{ id, email?, name? }` verificado por el servidor; las entradas del visitante o del modelo no pueden sustituirlo. La **Prueba** del panel usa deliberadamente el cliente de ejemplo introducido por un propietario autorizado.

## Verifica la firma [#verifica-la-firma]

La firma es un HMAC-SHA256 en hexadecimal en minúsculas que usa tu **secreto del agente**, con el prefijo `v1=`. Firma exactamente `"maf-webhook-v1:" + timestamp + "." + rawBody`. Conserva los bytes recibidos; analizar y volver a serializar el JSON antes de comprobar la firma puede alterarlos. Esta función auxiliar acepta un `Request` estándar del lado del servidor, aplica una ventana de validez de cinco minutos y fija el sitio:

```js
import { createHmac, timingSafeEqual } from "node:crypto";

export async function verifyLookupRequest(request, expectedSiteId) {
  const secret = process.env.MAF_SECRET_KEY;
  if (!secret) throw new Error("MAF_SECRET_KEY is required");
  const timestamp = request.headers.get("x-maf-timestamp");
  const signature = request.headers.get("x-maf-signature");
  const now = Math.floor(Date.now() / 1000);
  if (!timestamp || !/^\d+$/.test(timestamp) ||
      !Number.isSafeInteger(Number(timestamp)) ||
      Math.abs(now - Number(timestamp)) > 300) {
    throw new Error("Invalid timestamp");
  }
  if (!signature || !/^v1=[a-f0-9]{64}$/.test(signature)) {
    throw new Error("Invalid signature");
  }
  const rawBody = Buffer.from(await request.arrayBuffer());
  const expected = createHmac("sha256", secret)
    .update(`maf-webhook-v1:${timestamp}.`)
    .update(rawBody)
    .digest();
  const actual = Buffer.from(signature.slice(3), "hex");
  if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
    throw new Error("Invalid signature");
  }
  const body = JSON.parse(rawBody.toString("utf8"));
  if (body?.version !== 1 || body.siteId !== expectedSiteId) {
    throw new Error("Invalid lookup scope");
  }
  return body;
}
```

Llámala antes de que tu analizador de cuerpo consuma la solicitud. Tu controlador debe rechazar los errores de verificación, validar la acción esperada y la forma de las entradas, y comprobar la propiedad del registro con `body.customer.id` antes de devolver cualquier dato privado. Por ejemplo, selecciona el pedido A128 **dentro de los pedidos de ese cliente**, no solo por el ID del pedido. Nunca uses `input.customer_id`, un correo electrónico proporcionado en el chat ni una foto como autorización. Exige un cliente no nulo en los endpoints privados. Limita el tamaño del cuerpo entrante en tu servidor y registra `requestId` dentro de la ventana de validez si necesitas rechazar repeticiones; la comprobación de la marca de tiempo por sí sola no rechaza una repetición dentro de esa ventana.

Usa HTTPS y mantén este endpoint en modo de solo lectura aunque el transporte sea POST. Tras rotar el secreto del agente, actualiza tanto el servidor que firma la identidad como el verificador de consultas.

## Devuelve una respuesta [#devuelve-una-respuesta]

Responde con un estado 2xx correcto y un JSON que cumpla este contrato. El primer ejemplo es un registro encontrado; el segundo es un resultado normal sin coincidencias:

```json
{
  "found": true,
  "card": {
    "title": "Order #A128",
    "status": { "label": "Shipped", "tone": "success" },
    "fields": [{ "label": "Carrier", "value": "DHL" }],
    "reference": "A128",
    "asOf": "2026-10-12T09:00:00Z",
    "link": { "label": "Track", "url": "https://shop.example.com/orders/A128" }
  },
  "facts": { "order_id": "A128", "status": "shipped", "carrier": "DHL" }
}
```

```json
{ "found": false }
```

`found` es obligatorio. Con `found: true`, incluye `card`, `facts` o ambos. Una tarjeta requiere `title` y `fields` (se permite un array vacío). Los campos opcionales son `status`, `reference`, `asOf` y `link`. No añadas `kind` a la tarjeta de la respuesta. Los tonos de estado son `neutral`, `success`, `warning` y `danger`. Usa una marca de tiempo ISO para `asOf` y un enlace HTTPS sin credenciales incrustadas. Los enlaces opcionales no válidos se omiten.

`facts` es un objeto plano cuyos valores son cadenas, números finitos, booleanos o null; los objetos anidados y los arrays se rechazan. Los campos desconocidos en el esquema de la respuesta o de la tarjeta se rechazan. Devuelve solo la información necesaria para responder: el modelo recibe datos escapados y acotados, marcados como no confiables, no instrucciones. El contenido de la tarjeta es texto sin formato, no HTML.

## Límites y comportamiento ante fallos [#límites-y-comportamiento-ante-fallos]

| Elemento                                            | Límite                                                                                                                      |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Consultas por agente                                | 5; nombres e IDs únicos                                                                                                     |
| Nombre                                              | `^[a-z][a-z0-9_]{2,39}$`; los nombres de acciones reservados no están disponibles                                           |
| Descripción                                         | 300 caracteres                                                                                                              |
| Entradas declaradas                                 | 3; nombres únicos que cumplan `^[a-z][a-z0-9_]{1,31}$`                                                                      |
| Descripciones / valores de entradas                 | 300 / 200 caracteres; los valores se recortan                                                                               |
| Endpoint                                            | HTTPS público, hasta 500 caracteres, sin credenciales; direcciones privadas/internas bloqueadas; no se siguen redirecciones |
| Tiempo de espera / cuerpo de la respuesta           | 8 segundos / 32 KiB (32 768 bytes)                                                                                          |
| Datos para el modelo                                | 2000 caracteres, independientes de la tarjeta del visitante                                                                 |
| Título / etiquetas / valores de campo de la tarjeta | 80 / 40 / 200 caracteres                                                                                                    |
| Campos de la tarjeta                                | 8; como máximo 3 tarjetas por turno del agente                                                                              |

Si falta la identidad del cliente, se muestra un aviso para iniciar sesión sin llamar a tu endpoint. Si faltan entradas obligatorias, se las solicita al visitante. `found: false` muestra una tarjeta neutral de sin coincidencias. Los tiempos de espera agotados, los estados distintos de 2xx, el JSON o esquema no válido y las respuestas demasiado grandes muestran un estado de fallo e indican al modelo que no adivine. Devuelve `found: false` con un 2xx para un registro inexistente habitual, en lugar de un HTTP 404. Mantén concisos los datos importantes: las cadenas de la tarjeta y los datos del modelo que excedan el límite se recortan.

## Prueba desde el panel [#prueba-desde-el-panel]

1. Guarda la consulta y abre **Prueba**. Introduce un ID de cliente de ejemplo, un correo electrónico opcional y todas las entradas obligatorias. Usa una cuenta que controles.
2. Ejecuta la **Prueba**. Esto envía una solicitud firmada real, incluso si la consulta está desactivada para los visitantes; el chat de ensayo normal nunca llama al endpoint. El panel limita los intentos de prueba por owner.
3. Revisa la tarjeta o el resumen validados, o el error, el ID de solicitud, la duración y el estado HTTP cuando estén disponibles. Revisa los registros de tu endpoint sin guardar secretos ni tokens de clientes.
4. Prueba los casos de encontrado, no encontrado, cuenta incorrecta, entrada faltante y tiempo de espera agotado. Después, prueba el embed real con dos clientes autenticados; un ejemplo del panel no demuestra el aislamiento de identidad en el navegador ni la selección real de herramientas por parte del modelo.

El widget muestra tarjetas de estado; los toques en tarjetas genéricas de elección o confirmación envían sus etiquetas como mensajes. Las confirmaciones de cambios y reservas respaldadas por una ejecución usan en su lugar el flujo de ejecución protegido. Los conectores adaptan las tarjetas a texto o tarjetas nativos y a botones, respuestas rápidas o listas, con texto alternativo según los límites de cada canal. Prueba cada canal previsto antes de confiar en la entrega.

---

# Tus propias herramientas (MCP)

Source: /es/docs/build/mcp-tools.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/build/change-actions&#x22;, label: &#x22;Confirmaciones y aprobaciones&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/es/docs/embed/security&#x22;, label: &#x22;Identidad del cliente&#x22;, icon: &#x22;book&#x22; }
]"
/>

## Conectar y descubrir [#conectar-y-descubrir]

Abre **Agente → Acciones → Tus herramientas (MCP)**. Conecta tu servidor remoto mediante su flujo de OAuth o una credencial de tipo bearer, o usa una conexión MCP existente. Selecciona **Descubrir** para leer el catálogo de herramientas. Revisa la descripción, los parámetros y las anotaciones de cada herramienta antes de activarla. El descubrimiento no ejecuta ninguna herramienta; las herramientas recién descubiertas quedan desactivadas.

Puedes configurar tres servidores de herramientas y activar un total de 20 herramientas. Las credenciales permanecen en el servidor. Eliminar la asignación de una herramienta detiene esa asignación, pero no revoca la conexión de conocimiento compartida ni su autorización OAuth; gestiona esa conexión por separado. El servidor MCP de gestión para owners de Make Agent Fast no se puede exponer como servidor de herramientas para clientes. Para gestionar tus agentes desde Claude, consulta [Usar Claude y ChatGPT](/es/docs/operate/ai-assistants).

## Elegir lectura o escritura [#elegir-lectura-o-escritura]

| Efecto    | Comportamiento                                                                                                               |
| --------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Lectura   | Llama directamente a la herramienta y trata el texto o los datos estructurados devueltos como datos de negocio no confiables |
| Escritura | Crea una propuesta; el cliente debe confirmar los datos exactos con los botones de la tarjeta antes de la ejecución          |

La lectura solo está disponible si el servidor declara `readOnlyHint: true`, no declara `destructiveHint: true` y mantienes la herramienta clasificada como lectura. De lo contrario, trátala como escritura. Revisa lo que el servidor hace realmente; las anotaciones no son un sistema de autorización.

Por defecto, las escrituras requieren la aprobación del propietario cada vez. Puedes elegir no exigir aprobación adicional del propietario o exigirla solo por encima de un límite en un parámetro numérico. La confirmación del cliente sigue siendo obligatoria en todos los modos. La aprobación del propietario usa la lista de Aprobaciones y los comprobantes existentes. Los ajustes se guardan automáticamente. El ensayo del propietario nunca llama al servidor remoto.

## Vincular al cliente que ha iniciado sesión [#vincular-al-cliente-que-ha-iniciado-sesión]

Por defecto, las herramientas requieren un cliente verificado. Usa la [identidad firmada del cliente](/es/docs/embed/security) en tu sitio web; un ID escrito en el chat no es una verificación. Para registros específicos de un cliente, elige el parámetro de tipo cadena de la herramienta que identifica al cliente. El servidor lo rellena con el ID del cliente verificado y lo elimina de los datos de entrada del modelo. Los parámetros enum no se pueden usar para esta vinculación.

Por ejemplo, vincula `customer_id` en una herramienta que consulta un pedido. El modelo puede proporcionar la referencia de pedido declarada, pero no puede sustituirla por el ID de otro cliente. El servidor remoto debe seguir comprobando que el pedido pertenece a ese cliente. Exigir el inicio de sesión sin vincular un parámetro no limita por sí solo todos los registros a los que puede acceder la herramienta remota.

## Límites y resultados inciertos [#límites-y-resultados-inciertos]

Los esquemas admitidos son objetos planos con hasta diez parámetros de tipo cadena, número, entero, booleano o enum. Los objetos anidados, los arrays y las reglas de esquema no admitidas siguen sin estar disponibles. Las cadenas están limitadas a 200 caracteres; las llamadas remotas tienen un tiempo de espera de 10 segundos y los resultados visibles para el modelo se limitan a 4 KB. El contenido de los resultados son datos, nunca instrucciones para el agente.

MCP no ofrece ninguna garantía general de idempotencia. Una escritura se llama una sola vez tras la confirmación o aprobación. Si se desconoce su resultado, Make Agent Fast no reintenta automáticamente y avisa al owner. Comprueba el sistema remoto antes de crear otra propuesta. Cambiar la configuración revisada de la herramienta invalida cualquier propuesta anterior.

Prueba cada lectura y escritura previstas con tu propio servidor antes de que los clientes lo usen.

---

# Acciones de página

Source: /es/docs/build/page-actions.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/embed/html&#x22;, label: &#x22;Instala el embed&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/es/docs/build/follow-ups&#x22;, label: &#x22;Seguimientos&#x22;, icon: &#x22;book&#x22; }
]"
/>

## Registra una acción del sitio [#registra-una-acción-del-sitio]

Las acciones de página permiten que el sitio web abra su propia interfaz o navegue a una página aprobada. Instala el embed actual y ejecuta el registro después de que se haya cargado el script. Mantén los controladores (handlers) en tu aplicación; el agente recibe sus nombres, descripciones y definiciones de parámetros, pero nunca el código del controlador.

```js
MakeAgentFast.registerAction("show_details", {
  description: "Show the details section on this page",
  params: { section: { type: "string", description: "Use delivery or returns" } },
  confirm: true
}, async ({ section }) => {
  const sections = {
    delivery: document.getElementById("delivery-details"),
    returns: document.getElementById("returns-details")
  };
  if (!Object.hasOwn(sections, section) || !sections[section]) {
    throw new Error("Unknown section");
  }
  sections[section].scrollIntoView({ block: "start" });
  return { shown: section };
});

// Run when the page component unmounts:
// MakeAgentFast.unregisterAction("show_details");
```

Ambos métodos devuelven un valor booleano que indica si se aceptó el registro o la eliminación. Los nombres usan letras minúsculas, dígitos y guiones bajos, empiezan con una letra y tienen entre 2 y 40 caracteres. Hay nueve espacios de registro personalizados, además de la acción integrada `open_page`. Cada definición admite cinco parámetros de tipo cadena; todos los parámetros declarados son obligatorios, con valores de hasta 200 caracteres. Las descripciones están limitadas a 200 caracteres. Un controlador puede devolver una cadena o un valor serializable en JSON de hasta 2 KB en un plazo de 10 segundos.

## Aprueba las acciones en el panel [#aprueba-las-acciones-en-el-panel]

Abre el sitio web donde has instalado el embed para que informe de los nombres y las descripciones de sus acciones; después, abre **Agente → Acciones → Acciones de página**. Activa la función y permite cada acción que quieras habilitar. Las descripciones reportadas son metadatos del sitio web no verificados; detectar una acción no aprueba nada. Los ajustes se guardan automáticamente.

El agente solo puede proponer acciones que estén registradas en ese momento y además permitidas. El cliente ve una tarjeta antes de la ejecución. Se requiere confirmación a menos que el propietario marque la acción como segura; `confirm: true` en el código del sitio siempre exige un toque del cliente. `confirm: false` por sí solo no omite la política del propietario. Reserva el modo seguro para cambios inofensivos en la interfaz.

La acción integrada `open_page` no necesita controlador. Permítela en el panel; acepta una ruta relativa o una URL HTTP(S) dentro de los orígenes de sitio web permitidos del agente. Las rutas relativas también requieren que el origen actual del sitio web esté permitido. No puede navegar a un destino externo arbitrario.

## Informa de un evento con track [#informa-de-un-evento-con-track]

```js
MakeAgentFast.track("form_error", { formId: "contact" });
MakeAgentFast.track("checkout_help", { step: "delivery" });
```

Llama a estas funciones después de que se cargue el embed y cuando el evento correspondiente ocurra realmente. Configura un nombre de evento equivalente en [Seguimientos](/es/docs/build/follow-ups). Los nombres siguen el mismo formato de 2 a 40 caracteres; los datos opcionales deben ser un objeto JSON de como máximo 1 KB. No envíes valores de campos, credenciales ni datos de pago. Las reglas coinciden por evento, ruta y retraso; los metadatos no se almacenan, no se envían al modelo ni se usan como prueba de conversión. Un retorno `true` significa que el cargador aceptó el evento, no que se haya mostrado un mensaje.

## Seguridad y verificación [#seguridad-y-verificación]

Las acciones de página funcionan en el widget del sitio web en producción, no en los canales de mensajería, ni en los ensayos del propietario, ni en la voz en vivo. El cargador y el marco comprueban el origen, la fuente, el slug y los ID de solicitud pendientes. Los resultados vuelven al chat como datos del navegador no confiables, no como prueba de que se haya modificado un registro en el servidor. Mantén la autenticación y la autorización en tus propios controladores o backend; usa [Acciones de cambio](/es/docs/build/change-actions) para escrituras de negocio con consecuencias.

Un tiempo de espera agotado no cancela el controlador ni demuestra que no haya ocurrido nada. No reintentes automáticamente una acción cuyo resultado sea incierto. Cancela el registro de los controladores cuando el componente de su página deje de mostrarse. Los embeds almacenados en caché necesitan la versión actual del cargador, `20261014-page-actions`, para usar esta API.

Esta API no gestiona pagos ni ofrece un conector de Shopify.

---

# Personalidad e instrucciones

Source: /es/docs/build/persona.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Reglas de personalidad&#x22;, icon: &#x22;account&#x22; }, { label: &#x22;Límites&#x22;, icon: &#x22;shield&#x22; }, { label: &#x22;Idiomas&#x22;, icon: &#x22;globe&#x22; }]" />

## Separa la identidad del conocimiento [#separa-la-identidad-del-conocimiento]

No existe una página de personalidad independiente. Escribe las instrucciones del agente en la pestaña **Resumen** de la página del agente, en **Instrucciones**; se guardan automáticamente.

La personalidad explica quién es el agente y cómo se comporta. El conocimiento aporta los datos. Incluye «Habla como el asistente de soporte de Acme» en la personalidad; coloca el período de garantía vigente en una fuente de conocimiento.

## Orden de las instrucciones [#orden-de-las-instrucciones]

Escribe las instrucciones en este orden:

1. Identidad y rol
2. Objetivo principal del visitante
3. Tono y longitud de las respuestas
4. Acciones y preguntas obligatorias
5. Afirmaciones prohibidas y temas sensibles
6. Condiciones de escalado y captura de leads

## Límites [#límites]

Indícale al agente cuándo debe decir que no sabe algo, cuándo debe citar o matizar una respuesta y cuándo debe ofrecer ayuda humana. Nunca le indiques que oculte la incertidumbre o que invente datos que faltan.

## Prueba los cambios [#prueba-los-cambios]

Los cambios en la personalidad pueden afectar a todos los canales. Vuelve a probar las preguntas habituales, las negativas, la captura de leads y los idiomas compatibles antes de publicar un cambio importante.

---

# Voz y llamadas en vivo

Source: /es/docs/build/voice.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ label: &#x22;Voces predefinidas&#x22;, icon: &#x22;voice&#x22; },
{ label: &#x22;Mensajes de voz&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;Llamadas en vivo&#x22;, icon: &#x22;bolt&#x22; }
]"
/>

## Entiende los tres modos de interacción [#entiende-los-tres-modos-de-interacción]

| Modo                               | Experiencia del visitante                                                                              | Derechos del plan y uso                                                                                                                    |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Chat de texto**                  | Escribe un mensaje y recibe texto                                                                      | Siempre activado; consume créditos de IA normales                                                                                          |
| **Mensajes de voz**                | Graba un mensaje, espera la transcripción, el agente y la síntesis de voz (TTS) y recibe una respuesta | Incluido en todos los planes; la transcripción, el modelo y la voz consumen créditos                                                       |
| **Llamada en vivo en tiempo real** | Mantiene una conversación hablada de baja latencia                                                     | Operate: 30 min/mes; Scale: 90 min/mes; Launch: no disponible; además cobra créditos por adelantado según el límite de llamada configurado |

El texto no se puede desactivar. Los interruptores de mensajes de voz y de tiempo real controlan qué superficies adicionales pueden usar los visitantes. Un interruptor de tiempo real guardado no anula los derechos del plan del espacio de trabajo ni suple una configuración de proveedor que falte.

## Configura el comportamiento de la interacción [#configura-el-comportamiento-de-la-interacción]

1. Abre la página **Agent** del sitio y busca **Voice**.
2. Mantén activado **Text chat** y elige **Voice messages** y/o **Live real-time voice**.
3. Si el agente tiene varios idiomas, activa opcionalmente el reflejo de idioma en vivo.
4. Define el límite automático por llamada.
5. Selecciona una voz predefinida.
6. Guarda y prueba cada modo activado por separado.

El límite de llamada admite desde 30 segundos hasta 20 minutos, en pasos de 30 segundos; el valor predeterminado es de 3 minutos. Finaliza una llamada individual y protege la asignación mensual, pero no aumenta los minutos en vivo que le quedan al plan.

## Elige idiomas y una voz [#elige-idiomas-y-una-voz]

Los agentes pueden configurarse en inglés, coreano, uzbeko, ruso, francés, español, alemán y árabe. El primer idioma es el principal. Un agente de un solo idioma sigue respondiendo en ese idioma. Un agente de texto multilingüe refleja el idioma del visitante cuando este usa uno de los idiomas configurados.

En las llamadas en vivo, el reflejo de idioma es una opción explícita que solo aparece con dos o más idiomas. Cuando está desactivado, las llamadas en vivo usan el idioma principal. La voz en uzbeko funciona actualmente con el mejor esfuerzo, ya que la cobertura de voz de los proveedores es menos completa; pruébala con tu proveedor y tu audiencia exactos antes del lanzamiento.

Las voces predefinidas incluyen opciones centradas en inglés, multilingües y nativas en coreano. La etiqueta de idioma describe la entrega seleccionada, no una garantía absoluta. Escucha una vista previa de la voz elegida cuando el control de vista previa del panel esté disponible, y prueba siempre nombres, abreviaturas, monedas, números de teléfono y terminología especializada en el flujo real del visitante.

## Claves de proveedor y respaldo [#claves-de-proveedor-y-respaldo]

La voz requiere algo más que una clave de modelo:

* La conversión de voz a texto usa el proveedor de transcripción configurado en la plataforma.
* Los mensajes de voz y las respuestas de audio de los conectores necesitan el proveedor de síntesis de voz (TTS) configurado.
* Las llamadas en tiempo real necesitan el proveedor de tiempo real configurado y una asignación del plan.

La voz gestionada por la plataforma usa los proveedores configurados por la plataforma; no necesitas una clave. Los propietarios con plan Scale pueden añadir opcionalmente una clave de Speko para la transcripción y la síntesis de voz en **Settings → AI provider keys** y seguir [Claves de proveedor](/es/docs/account/provider-keys). Las llamadas en vivo siempre se facturan a la tarifa de la plataforma. Un chat de texto que funciona solo demuestra que la ruta del modelo funciona; no demuestra que funcionen la transcripción, la síntesis de voz, la subida de archivos multimedia ni la creación de sesiones en tiempo real.

## Enrutamiento de voz y respaldo [#enrutamiento-de-voz-y-respaldo]

Elige un modelo en **Voice models** para la transcripción, la síntesis de voz y las llamadas en vivo. Cada opción identifica el modelo y a su creador; **Auto** permite que lo elijamos nosotros. El alojamiento y el enrutamiento los gestiona Make Agent Fast, por lo que no hay una elección de plataforma por separado. La voz predefinida exacta puede variar según el modelo seleccionado.

Si un servicio de voz no está disponible, puede usarse una alternativa disponible. Si falla la voz, el texto sigue disponible.

Las llamadas en vivo transmiten audio nativo del proveedor en vivo seleccionado con su voz integrada. La recuperación de conocimiento, las reglas de idioma, la interrupción, las asignaciones de minutos en vivo y los cargos por adelantado de la llamada siguen aplicándose. Las respuestas en vivo no generan una solicitud de TTS adicional.

## Prueba los mensajes de voz [#prueba-los-mensajes-de-voz]

Usa un embed real o el Agent link, no solo una vista previa del propietario. Concede acceso al micrófono, graba una pregunta corta y confirma que el significado de la transcripción y la respuesta hablada o de texto sean correctos. Después, prueba:

* entornos silenciosos y ruidosos;
* Safari y Chrome en móvil, cuando sea relevante;
* una pregunta larga cercana al límite público de 25 MB de audio;
* el permiso de micrófono denegado;
* audio no compatible o de baja calidad;
* cada idioma configurado.

En los sitios con embed, la CSP y la Permissions Policy de la página principal deben permitir el uso del micrófono. Consulta [Seguridad y CSP](/es/docs/embed/security).

## Conversación en vivo en la plataforma frente al sitio publicado [#conversación-en-vivo-en-la-plataforma-frente-al-sitio-publicado]

La conversación en vivo usa los mismos controles de llamada en dos lugares:

| Superficie                        | Dónde                                                                                                           | Aspecto                                                   | ¿Cuenta como activación?                                 |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------- |
| **Lienzo del estudio del agente** | El widget en vivo junto a las pestañas de la página **Agent**                                                   | El aspecto del widget del visitante, mostrado en el panel | No: las pruebas del propietario nunca activan            |
| **Sitio publicado y embed**       | El iframe de `embed.js`, el widget en el Agent link y cualquier página de demostración alojada que haya quedado | Aspecto del tenant / widget                               | Sí: una llamada de un visitante es una conversación real |

El lienzo junto a la pestaña **Display** muestra el mismo aspecto que ve el visitante. Prueba un embed real antes del lanzamiento; una prueba correcta en el panel no demuestra el permiso de micrófono del embed, la CSP de la página anfitriona ni la activación.

**Use website** en **Agent theme**, en la pestaña **Display**, sigue el modo claro u oscuro del visitante en la página anfitriona y en el embed. Si fijas Light o Dark, se aplica tanto al chat como a la llamada en vivo. Consulta [Aspecto](/es/docs/build/appearance).

## Prueba las llamadas en vivo [#prueba-las-llamadas-en-vivo]

Confirma que el plan tiene minutos en vivo sin usar, que el sitio es accesible y que la clave del proveedor de tiempo real se valida. Empieza con una llamada corta, interrumpe al agente, cambia de idioma solo cuando el reflejo de idioma esté activado y deja que el límite de llamada configurado termine una sesión de prueba. Repite una llamada en un embed real, no solo en el lienzo de la página del Agent.

Los minutos en vivo son un derecho mensual independiente de los créditos normales. Al emitir el token en vivo se cobran créditos por la duración máxima autorizada por el servidor y se reserva esa duración de la asignación mensual en vivo. Como el contenido multimedia fluye directamente entre el navegador y el proveedor, no se puede verificar una llamada más corta informada por el cliente, y el tiempo no usado no se reembolsa parcialmente tras la entrega del token. Los fallos al generar el token en el servidor se liberan; las sesiones abandonadas se cobran según su límite autorizado. Finaliza las pruebas correctamente y usa el límite de llamada configurado al hacer tus previsiones. Consulta [Créditos y uso](/es/docs/operate/usage).

## Acciones de voz en vivo [#acciones-de-voz-en-vivo]

**Agent → Actions → Live call actions** (**Let the agente take actions during live calls**) controla el uso de herramientas durante las llamadas en vivo, que se ejecutan en Gemini 3.8 Live en todos los idiomas. Está activado de forma predeterminada (`voice.liveActions`); si lo desactivas, la fundamentación en el conocimiento sigue disponible. Se siguen aplicando los requisitos de plan, proveedor y acceso de la voz en vivo.

Las llamadas pueden mostrar resultados de consultas, opciones, propuestas de cambios, huecos y reservas de calendario, seguimientos programados y handoff a una persona. Los cambios en el negocio, las reservas y los seguimientos requieren los botones de las tarjetas en pantalla; un «sí» dicho o escrito nunca confirma una escritura. Un seguimiento además necesita el consentimiento por correo electrónico en pantalla. Las tarjetas y los resultados de las herramientas permanecen en el historial de la conversación. Las acciones de página y tus propias herramientas MCP no forman parte del subconjunto en vivo. La facturación de la llamada sigue siendo solo por reserva, sin reembolso del tiempo de llamada no usado tras la entrega del token.

Prueba tanto el resultado hablado como la confirmación en pantalla antes de usarlo con clientes. Consulta [Seguimientos](/es/docs/build/follow-ups) y [Acciones de cambio](/es/docs/build/change-actions).

## Divulgación y seguridad [#divulgación-y-seguridad]

Informa a quienes llaman de que están interactuando con una IA y con voz sintética. Define cómo se conservan y eliminan las grabaciones, las transcripciones y los datos de los proveedores posteriores.

## Solución de problemas [#solución-de-problemas]

| Síntoma                                             | Qué revisar                                                                                                                            |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| El texto funciona, pero los controles de voz fallan | Claves de los proveedores de transcripción/TTS/tiempo real, interruptor de la función, plan, saldo de créditos y permiso del navegador |
| La grabación no puede iniciarse                     | HTTPS, permiso de micrófono, entrada del dispositivo, Permissions Policy del embed y compatibilidad del navegador                      |
| La transcripción es inexacta                        | Calidad del audio, conjunto de idiomas elegido, acento/terminología y cobertura del proveedor de transcripción                         |
| La respuesta hablada suena mal                      | Voz seleccionada, texto de origen, puntuación, etiqueta de idioma y disponibilidad del proveedor                                       |
| La llamada en vivo termina de inmediato             | Minutos restantes, límite por llamada, clave del proveedor, red y estado de las sesiones simultáneas                                   |

Trata la voz como una superficie de lanzamiento independiente: las pruebas de aceptación del texto son necesarias, pero no suficientes.

---

# Discord

Source: /es/docs/connectors/discord.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/connectors/overview&#x22;, label: &#x22;Todos los conectores&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/es/docs/operate/conversations&#x22;, label: &#x22;Bandeja de entrada&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;Discord&#x22;, icon: &#x22;discord&#x22; }
]"
/>

<TutorialVideo episode="ep09" start="89" />

## Crea la aplicación de Discord [#crea-la-aplicación-de-discord]

Sigue la [guía de inicio rápido de aplicaciones](https://docs.discord.com/developers/quick-start/getting-started) y la [introducción a las interacciones](https://docs.discord.com/developers/interactions/overview) oficiales de Discord. Crea una aplicación en el Discord Developer Portal y reúne los siguientes datos:

| Campo de Make Agent Fast | Ubicación en Discord | Finalidad                                                                                |
| ------------------------ | -------------------- | ---------------------------------------------------------------------------------------- |
| **Application ID**       | General Information  | Identifica la aplicación y el comando                                                    |
| **Public Key**           | General Information  | Verifica las interacciones firmadas con Ed25519; exactamente 64 caracteres hexadecimales |
| **Bot token**            | Página Bot           | Valida la aplicación y registra `/ask`; manténlo en secreto                              |

Al restablecer un token de bot, el anterior deja de ser válido de inmediato. La Public Key no es secreta, pero debe pertenecer a la misma aplicación que el token del bot.

## Conecta y registra `/ask` [#conecta-y-registra-ask]

Abre la página **Canales** del agente, elige **Discord**, introduce los tres valores y selecciona **Conectar**.

Make Agent Fast valida el token del bot con el endpoint de aplicación de Discord y rechaza una Public Key que no coincida con la aplicación. Si el Application ID tiene un error de escritura, lo normaliza al ID real de la aplicación autenticada y, a continuación, crea o actualiza el comando global `/ask question` sin eliminar otros comandos de la aplicación.

Tras guardar, copia la **Interactions Endpoint URL** que se muestra en **General Information → Interactions Endpoint URL** en Discord y guarda los cambios. Discord envía un `PING` firmado; Make Agent Fast valida la firma y devuelve el `PONG` requerido.

## Instala y prueba [#instala-y-prueba]

Usa los ajustes de instalación de Discord para autorizar la aplicación en un servidor de prueba con los permisos necesarios para los comandos de aplicación. La propagación de los comandos globales puede tardar un tiempo.

Ejecuta `/ask`, completa la opción obligatoria `question` y envíala. Make Agent Fast confirma la interacción antes del breve plazo límite de Discord, ejecuta el agente y luego edita la respuesta original diferida. El historial de conversación se limita a cada usuario de Discord, de modo que las siguientes solicitudes de `/ask` puedan conservar el contexto.

El conector actual solo admite texto. No lee canales de voz, archivos adjuntos, mensajes ordinarios de canal ni mensajes directos; solo la interacción `/ask` registrada llega al agente.

## Rota o desconecta [#rota-o-desconecta]

Si el token del bot queda expuesto, restablécelo en Discord, actualiza el conector y verifica `/ask` de nuevo. Si cambia la propia aplicación, actualiza los tres valores y la Interactions Endpoint URL correspondiente a esa aplicación.

Al desactivar o eliminar el conector no se borran la aplicación de Discord ni el comando global. Quita la aplicación de los servidores y elimina por separado las credenciales obsoletas del proveedor cuando la des instales definitivamente.

## Solución de problemas [#solución-de-problemas]

| Síntoma                                              | Solución                                                                                                                                          |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| El conector rechaza los campos                       | Usa el token del bot y la Public Key de 64 caracteres de la misma aplicación                                                                      |
| Discord rechaza el endpoint                          | Confirma que sea HTTPS público, pega el endpoint generado y vuelve a guardar las credenciales antes de reintentar                                 |
| Falta `/ask`                                         | Confirma la instalación/autorización del comando, espera a la propagación global y vuelve a conectar para registrarlo de nuevo                    |
| La interacción indica que la aplicación no respondió | Comprueba que el conector esté activado y revisa los errores de Make Agent Fast/Discord; la validación de la firma del endpoint debe ser correcta |
| Se ignoran otros mensajes del chat                   | Es lo esperado; la integración solo gestiona `/ask`                                                                                               |
| La respuesta aparece truncada                        | Las respuestas en mensajes de Discord están limitadas a 2000 caracteres                                                                           |

Nunca expongas el token del bot en código de cliente, repositorios, registros ni capturas de pantalla.

---

# Instagram

Source: /es/docs/connectors/instagram.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/connectors/overview&#x22;, label: &#x22;Todos los conectores&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/es/docs/operate/conversations&#x22;, label: &#x22;Bandeja de entrada&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;Instagram&#x22;, icon: &#x22;instagram&#x22; }
]"
/>

<TutorialVideo episode="ep05" />

## Qué hace este conector [#qué-hace-este-conector]

Los clientes envían un **mensaje directo** a tu cuenta profesional de Instagram. Make Agent Fast responde con el mismo agente basado en tus datos que usas en la incrustación de tu sitio web, a través de la [API de Instagram con inicio de sesión de Instagram](https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login) oficial de Meta.

También puede responder a los **comentarios** en tus publicaciones y reels, de forma pública o con un mensaje directo privado (consulta [Comentarios y respuestas guardadas](#comentarios-y-respuestas-guardadas)). Además, responde a las respuestas a tus historias (consulta [Historias](#historias)). Quedan fuera de alcance el scraping y dar «me gusta» a publicaciones o comentarios. La API oficial de Instagram no permite dar «me gusta» a ningún contenido, así que el agente nunca lo hace.

Cada cuenta de Instagram es su propia fila de canal, de modo que la facturación, los hilos de la bandeja de entrada y el enrutamiento de mensajes permanecen separados. Un agente puede gestionar hasta cinco cuentas de Instagram.

## Antes de empezar [#antes-de-empezar]

Necesitas:

1. Una cuenta **profesional** de Instagram (Empresa o Creador). Las cuentas personales no se pueden conectar; cambia el tipo de cuenta en Instagram desde **Configuración → Tipo de cuenta y herramientas**.
2. El nombre de usuario y la contraseña de Instagram de la cuenta, o una aplicación de Instagram con la sesión ya iniciada en esa cuenta en este navegador.
3. El plan Operate o Scale para añadir un canal nuevo.

**No** necesitas una cuenta de Facebook, una página de Facebook, un portfolio empresarial de Meta ni una aplicación de desarrollador de Meta.

## Conecta tu cuenta [#conecta-tu-cuenta]

### 1. Abre la tarjeta de Instagram [#1-abre-la-tarjeta-de-instagram]

En el panel, abre tu agente y ve a **Canales → Instagram**.

### 2. Inicia sesión y permite el acceso [#2-inicia-sesión-y-permite-el-acceso]

Selecciona **Conectar con Instagram**. Instagram abre su propia página de inicio de sesión. Inicia sesión en la cuenta profesional para la que quieres que responda el agente, comprueba que la ventana muestra esa cuenta y selecciona **Permitir**. Deja activada la opción **Acceder a los mensajes y gestionarlos**; sin ella, el agente no puede leer ni responder mensajes directos. La opción **Acceder a los comentarios y gestionarlos** solo se usa si más adelante activas las respuestas a comentarios.

Instagram te devuelve a la tarjeta de Instagram, que ahora muestra la cuenta como conectada. Para conectar otra cuenta, vuelve a seleccionar **Conectar con Instagram** e inicia sesión en esa cuenta.

### 3. Envía un mensaje de prueba [#3-envía-un-mensaje-de-prueba]

Desde una cuenta de Instagram **diferente**, envía un mensaje directo nuevo a la cuenta conectada. Comprueba que:

1. El mensaje aparece en tu bandeja de entrada de Instagram.
2. La tarjeta de Instagram muestra un evento nuevo y **Conversaciones** tiene un hilo nuevo.
3. El paso de verificación de la tarjeta se completa correctamente.

### 4. Activa las respuestas con IA [#4-activa-las-respuestas-con-ia]

Cuando la prueba sea correcta, activa las respuestas con IA en la tarjeta. A partir de ese momento, el agente responde a los mensajes directos nuevos. Los mensajes de texto y las notas de voz compatibles se responden con texto. Tus propios mensajes, las imágenes y otros archivos adjuntos no compatibles se ignoran. Cuando respondes tú mismo desde la bandeja de **Conversaciones**, el agente se pausa en esa conversación.

## Comentarios y respuestas guardadas [#comentarios-y-respuestas-guardadas]

Activa **Responder a comentarios** en la sección **Comentarios** de la tarjeta de Instagram. Los comentarios nuevos de nivel superior en tus publicaciones y reels se responden entonces en este orden:

1. **Tus respuestas guardadas.** Escribe una respuesta para una publicación concreta o para **Todas las publicaciones**, y elige las palabras clave que la activan (por ejemplo, `precio, cuánto cuesta`). Deja las palabras clave vacías para responder a todos los comentarios de esa publicación. Cada respuesta guardada puede publicar una respuesta pública bajo el comentario, enviar un mensaje directo privado, o ambas cosas. `{name}` se sustituye por el @usuario de quien comenta. Las respuestas propias de una publicación tienen prioridad sobre las de **Todas las publicaciones**, y las respuestas con palabras clave tienen prioridad sobre las generales. Las respuestas guardadas no usan IA ni créditos.
2. **La IA, si lo permites.** En **Cuando ninguna respuesta guardada encaja**, elige **Mantener silencio**, **Respuestas de la IA** (una o dos frases breves, publicadas de forma pública) o **La IA envía un mensaje directo** (la respuesta va a los mensajes directos de quien comentó, con tu línea pública opcional bajo el comentario). El texto de la publicación se proporciona al agente como contexto. Las respuestas de la IA consumen créditos igual que la respuesta a un mensaje directo.

El agente nunca responde a sus propios comentarios, ni dentro de un hilo de comentarios, ni a comentarios que solo etiquetan a amigos o que contienen únicamente emojis, ni a preguntas para las que no tiene una respuesta aprobada. Las conversaciones de comentarios aparecen en **Conversaciones** en modo de solo lectura; respóndelas en Instagram. Instagram permite un único mensaje directo privado por comentario, dentro de los 7 días siguientes.

## Historias [#historias]

Las historias llegan al agente como mensajes directos:

* **Una respuesta escrita a tu historia** la responde la IA como cualquier mensaje directo. Cuando la historia es una foto, el agente la ve, así que una pregunta como «¿cuánto cuesta esto?» recibe una respuesta sobre lo que muestra la historia. Las historias en vídeo se responden solo a partir del texto.
* **Una mención en la historia de alguien** y **una reacción solo con emoji a tu historia** no contienen ninguna pregunta, por lo que la IA nunca las responde. En la sección **Historias** de la tarjeta de Instagram, escribe una respuesta breve para cada una, o déjala vacía para no responder. Estas respuestas no usan IA ni créditos, y una persona recibe como máximo una respuesta de reacción al día.

Las tres aparecen en **Conversaciones**. Instagram no avisa a las aplicaciones cuando alguien da «me gusta» a una historia, y ninguna aplicación puede dar «me gusta» a historias ni comentarlas.

## Disponibilidad [#disponibilidad]

**Conectar con Instagram** aparece en la tarjeta una vez que Meta haya aprobado el acceso de Make Agent Fast a la mensajería de Instagram. Hasta entonces, es posible que la tarjeta no lo ofrezca, y Instagram solo entrega mensajes de las cuentas con las que Meta permite probar la aplicación. Si tu tarjeta aún no muestra el botón, usa el método avanzado que se describe más abajo o vuelve a comprobarlo más tarde.

## Desconectar o reconectar [#desconectar-o-reconectar]

Make Agent Fast renueva el inicio de sesión automáticamente. Si las respuestas se detienen y la tarjeta muestra un error de conexión, por ejemplo tras cambiar la contraseña, selecciona **Reconectar con Instagram** e inicia sesión de nuevo. Para desconectar, elimina la conexión en la tarjeta. También puedes quitar Make Agent Fast en Instagram desde **Configuración → Aplicaciones y sitios web**; el agente dejará de responder en esa cuenta de inmediato.

## Avanzado: tu propia aplicación de Meta [#avanzado-tu-propia-aplicación-de-meta]

Los desarrolladores que gestionan su propia aplicación de Meta pueden seguir conectando con un token de acceso de página de Facebook. Para ello se necesita una cuenta profesional de Instagram vinculada a una página de Facebook, una aplicación de desarrollador de Meta con `instagram_basic`, `instagram_manage_messages`, `pages_manage_metadata`, `pages_messaging` y `pages_show_list`, y la [configuración de webhooks](https://developers.facebook.com/docs/instagram-platform/instagram-api-with-facebook-login/webhooks/) de Meta.

Pega el **token de acceso de la página** y el **secreto de la aplicación** en el formulario avanzado de la tarjeta; después, usa la **URL del webhook** y el **token de verificación** que muestra para el webhook de Instagram (campo `messages`). Suscribe la propia página con el token de la página:

```text
POST /me/subscribed_apps?subscribed_fields=messages
```

Tu propia aplicación solo responderá al público cuando supere la revisión de aplicaciones de Meta con acceso avanzado.

## Solución de problemas [#solución-de-problemas]

| Síntoma                                                                 | Solución                                                                                                   |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| No aparece el botón **Conectar con Instagram**                          | La aprobación de Meta sigue pendiente; consulta [Disponibilidad](#disponibilidad)                          |
| Instagram indica que la cuenta no se puede usar                         | Cámbiala a una cuenta profesional (Empresa o Creador) e inténtalo de nuevo                                 |
| «Ya está conectada a otro agente»                                       | Desconéctala primero de ese agente y luego conéctala aquí                                                  |
| Conectada, pero no hay eventos nuevos tras un mensaje directo de prueba | Envía un mensaje directo nuevo desde otra cuenta; los mensajes enviados antes de conectar no se reproducen |
| Llega un mensaje directo pero no hay respuesta                          | Activa las respuestas con IA después del paso de verificación y revisa si la tarjeta muestra algún error   |
| Los comentarios no se responden                                         | Activa **Responder a comentarios** y añade una respuesta guardada o permite las respuestas de la IA        |
| Un mensaje de voz recibe una respuesta de texto                         | Es lo esperado; las respuestas de voz en Instagram no son compatibles                                      |
| La tarjeta muestra un error de conexión                                 | Selecciona **Reconectar con Instagram** e inicia sesión de nuevo                                           |

No compartas nunca tu contraseña de Instagram con nadie, ni siquiera con el soporte; la conexión usa el inicio de sesión propio de Instagram.

---

# KakaoTalk

Source: /es/docs/connectors/kakao.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/connectors/overview&#x22;, label: &#x22;Todos los conectores&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/es/docs/operate/conversations&#x22;, label: &#x22;Bandeja de entrada&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;KakaoTalk&#x22;, icon: &#x22;kakao&#x22; }
]"
/>

<TutorialVideo episode="ep09" start="145" />

## Lista de verificación de configuración [#lista-de-verificación-de-configuración]

La tarjeta de KakaoTalk en Make Agent Fast muestra esta lista con tus propios valores ya rellenados, así que la mayoría de los propietarios trabajan directamente desde ahí. Todos los pasos se realizan en la consola de Kakao, excepto los dos campos que se indican más abajo.

1. **Crea un bot** en Kakao i Open Builder. Un bot contiene todos los bloques de escenario con los que responde el canal; omite este paso si el canal ya tiene un bot que puedas editar.
2. **Añade una skill** y establece su URL con la **Skill URL** del conector; después añade un encabezado de solicitud personalizado `X-Kakao-Bot-Secret` con tu **Bot secret**. Kakao no firma las solicitudes de las skills, así que ese encabezado es la única prueba de que una llamada procede de tu bot.
3. **Apunta el bloque de respaldo (fallback) a la skill** para que todas las preguntas que tus escenarios no gestionen lleguen al agente. Conecta un bloque de escenario con nombre a la misma skill si también quieres que lo responda el agente.
4. **Activa la opción de callback** para ese bloque. Kakao descarta la respuesta de una skill que tarda más de cinco segundos; con el callback activado, Make Agent Fast devuelve de inmediato una burbuja de espera y publica la respuesta final en `userRequest.callbackUrl` dentro del minuto durante el cual consideramos válida esa URL de un solo uso.
5. **Conecta el canal de KakaoTalk** al bot y pega después ese mismo ID de canal en el campo **Channel ID** del conector en Make Agent Fast.
6. **Despliega el bot.** Los cambios en Open Builder solo llegan a los visitantes tras un despliegue, y cada cambio posterior en una skill o un bloque requiere otro.

El resto de esta página es la versión detallada de estos mismos seis pasos.

## Prepara los recursos de Kakao [#prepara-los-recursos-de-kakao]

Crea o selecciona la aplicación de Kakao Developers, el canal de KakaoTalk y el bot de Kakao i Open Builder que serán los propietarios de la integración. Consulta la [documentación oficial de Open Builder](https://i.kakao.com/docs/key-concepts-block#skill) de Kakao sobre skills y bloques.

Reúne o crea estos valores:

| Campo de Make Agent Fast | Origen                                        | Finalidad                                                               |
| ------------------------ | --------------------------------------------- | ----------------------------------------------------------------------- |
| **Channel ID**           | ID público/de búsqueda del canal de KakaoTalk | Asocia el conector con el canal previsto                                |
| **REST API key**         | Claves de la aplicación en Kakao Developers   | Valida la aplicación de Kakao                                           |
| **Bot secret**           | Un secreto aleatorio largo que generas tú     | Autentica las solicitudes entrantes de la skill en `X-Kakao-Bot-Secret` |

El Bot secret es obligatorio en los entornos desplegados de Make Agent Fast porque las llamadas de las skills de Kakao no incluyen una firma de la plataforma. Genera un valor único y de alta entropía, y no reutilices la REST API key como secreto.

## Guarda el conector [#guarda-el-conector]

Abre la página **Canales** del agente, elige **KakaoTalk Channel**, introduce los tres valores y selecciona **Conectar**. Make Agent Fast valida la REST API key siempre que los permisos de Kakao lo permitan y, tras guardar, muestra la **Webhook URL** única del conector.

Make Agent Fast no puede crear la skill de Open Builder ni asociarla a un bloque por ti; el resto del trabajo se hace en la consola de Kakao.

## Configura la skill de Open Builder [#configura-la-skill-de-open-builder]

1. En Kakao i Open Builder, crea una skill para el bot correspondiente.
2. Establece la URL de la skill con la **Webhook URL** copiada del conector.
3. Añade un encabezado de solicitud personalizado llamado `X-Kakao-Bot-Secret` cuyo valor coincida exactamente con el **Bot secret**.
4. Conecta la skill al bloque de respaldo o de escenario que deba invocar al agente.
5. Activa la opción de callback de ese bloque para que las respuestas lentas superen el límite de cinco segundos de las skills de Kakao.
6. Guarda y despliega/publica la configuración del bot según el flujo de trabajo de Kakao.

El encabezado no distingue mayúsculas de minúsculas según las reglas de HTTP, pero el valor del secreto debe ser exacto. Cualquiera que conozca la URL del webhook pero no este secreto recibirá una respuesta de no autorizado.

## Prueba las capacidades [#prueba-las-capacidades]

Usa primero la herramienta de prueba de Open Builder y después el canal de KakaoTalk conectado. Envía una pregunta de texto realista en coreano o en otro idioma compatible y confirma la respuesta en línea, el **Último mensaje** y el hilo en **Conversaciones**.

La tarjeta del conector copia el cuerpo de solicitud que aparece a continuación; ese mismo cuerpo funciona con `curl` contra la Skill URL. No incluye `callbackUrl`, por lo que la respuesta llega en línea, que es lo más sencillo de verificar primero.

```json
{
  "intent": {
    "id": "5a56ec0cf65e53002d34e0f4",
    "name": "Fallback block"
  },
  "userRequest": {
    "timezone": "Asia/Seoul",
    "utterance": "What are your opening hours?",
    "lang": "kr",
    "user": {
      "id": "kakao-test-user",
      "type": "botUserKey",
      "properties": {
        "plusfriendUserKey": "kakao-test-user"
      }
    },
    "block": {
      "id": "5a56ec0cf65e53002d34e0f4",
      "name": "Fallback block"
    }
  },
  "bot": {
    "id": "5a56ec0cf65e53002d34e0f2",
    "name": "Your bot"
  },
  "action": {
    "id": "5a56ec0cf65e53002d34e0f6",
    "name": "Make Agent Fast skill",
    "params": {},
    "detailParams": {},
    "clientExtra": {}
  }
}
```

Una skill en buen estado responde dentro del límite de cinco segundos con una única salida `simpleText`:

```json
{
  "version": "2.0",
  "template": {
    "outputs": [
      {
        "simpleText": {
          "text": "We are open 9:00–18:00 on weekdays."
        }
      }
    ]
  }
}
```

Cuando la opción de callback del bloque está activada, Open Builder añade `userRequest.callbackUrl` a la solicitud. Make Agent Fast responde entonces primero con una burbuja de espera y envía por POST la respuesta final a esa URL de un solo uso:

```json
{
  "version": "2.0",
  "useCallback": true,
  "data": {
    "text": "One moment — I am looking that up."
  }
}
```

El contrato actual de la skill es solo de texto. La respuesta del agente es un único `skillResponse` de Kakao versión `2.0` con una salida `simpleText`, limitada por debajo del máximo de texto de Kakao, que se devuelve en línea o a través de la URL de callback. No se admiten voz, archivos, imágenes ni audio saliente por separado.

## Rotar o desconectar [#rotar-o-desconectar]

Para rotar el Bot secret, actualiza el conector y el encabezado personalizado de Open Builder como un único cambio coordinado y prueba de inmediato. Si no coinciden, se detienen todas las solicitudes entrantes. Rota la REST API key en Kakao Developers y en Make Agent Fast antes de revocar la clave anterior.

Desactivar o eliminar el conector no borra la skill ni el bloque de Open Builder. Elimina o desvincula esos objetos del lado del proveedor cuando des de baja definitivamente la integración.

## Solución de problemas [#solución-de-problemas]

| Síntoma                                                                          | Solución                                                                                                            |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| El conector requiere un Bot secret                                               | Genera uno; los entornos desplegados rechazan un webhook de Kakao sin autenticar                                    |
| Se rechaza la REST API key                                                       | Usa la REST API key de la aplicación de Kakao correcta y confirma los permisos de su canal                          |
| Open Builder recibe un error de no autorizado                                    | Añade o actualiza `X-Kakao-Bot-Secret` para que coincida exactamente con el valor del conector                      |
| La herramienta de prueba muestra un bloque de respaldo en lugar de una respuesta | Confirma que el bloque invoca la URL de la skill guardada y revisa los registros de solicitudes/respuestas de Kakao |
| Las solicitudes agotan el tiempo de espera                                       | Activa la opción de callback del bloque; sin ella, Kakao concede cinco segundos a la skill                          |
| Se ignoran la voz o las imágenes                                                 | Es lo esperado; el conector actual solo acepta texto                                                                |

No expongas la REST API key ni el Bot secret en código de cliente ni en documentación pública.

---

# Messenger

Source: /es/docs/connectors/messenger.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/connectors/overview&#x22;, label: &#x22;Todos los conectores&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/es/docs/operate/conversations&#x22;, label: &#x22;Bandeja de entrada&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;Messenger&#x22;, icon: &#x22;messenger&#x22; }
]"
/>

<TutorialVideo episode="ep09" start="31" />

## Prepara la app de Meta y la página [#prepara-la-app-de-meta-y-la-página]

Sigue la [guía oficial de introducción a Messenger Platform](https://developers.facebook.com/docs/messenger-platform/get-started) de Meta. Añade Messenger a una app de Meta, conecta la página de Facebook que debe recibir los mensajes y asegúrate de que tu cuenta pueda administrar ambos recursos.

Reúne los valores de la misma app y de la misma página:

| Campo de Make Agent Fast         | Valor del proveedor                                    | Finalidad                                              |
| -------------------------------- | ------------------------------------------------------ | ------------------------------------------------------ |
| **Token de acceso de la página** | Token emitido para la página seleccionada              | Lee la identidad de la página y envía las respuestas   |
| **Secreto de la app**            | Secreto hexadecimal de 32 caracteres de la app de Meta | Verifica las solicitudes de webhook entrantes firmadas |

No uses un token de acceso de usuario ni un token que pertenezca a otra página. El estado de desarrollo y revisión de la app de Meta determina qué personas pueden usar la integración.

## Guarda y valida las credenciales [#guarda-y-valida-las-credenciales]

Abre la página **Canales** del agente, selecciona **Messenger**, introduce el token de acceso de la página y el secreto de la app, y selecciona **Conectar**.

Make Agent Fast llama a la Graph API con `appsecret_proof`, obtiene el ID y el nombre de la página, y vincula los eventos entrantes exactamente a esa página. A continuación, la tarjeta del conector muestra su **URL del webhook** y su **Token de verificación**.

## Configura el webhook de la página [#configura-el-webhook-de-la-página]

En la misma app de Meta:

1. Abre la configuración del webhook de Messenger.
2. Pega la **URL del webhook** y el **Token de verificación** del conector.
3. Completa el desafío de verificación.
4. Selecciona la suscripción al evento de mensajes que requiera tu flujo de trabajo de Messenger.
5. Suscribe la página de Facebook correspondiente a la app.
6. Confirma que la suscripción de la página y el modo de la app permiten a tu usuario de prueba.

El token de verificación solo se usa en el desafío inicial. Los eventos en tiempo de ejecución deben incluir una firma que coincida con el secreto de la app. Make Agent Fast también rechaza los eventos dirigidos a una página distinta, aunque provengan de la misma app de Meta.

## Prueba las capacidades [#prueba-las-capacidades]

Envía un mensaje normal a la página desde una cuenta de prueba permitida que no sea administradora y confirma la respuesta y el hilo en **Conversaciones**. Después, prueba un archivo de audio adjunto si la voz entrante es importante para tu flujo de trabajo.

Se procesan el texto y el audio entrante compatible. En el conector actual de Messenger, las respuestas son solo de texto, incluso cuando el mensaje original era de voz. Se ignoran los acuses de entrega y lectura, los ecos de los mensajes de la propia página, las imágenes y otros archivos adjuntos no compatibles.

## Preparación para producción [#preparación-para-producción]

Completa los pasos de permisos, revisión de la app, verificación de empresa, URL de privacidad y publicación de la página que Meta exige para tu audiencia. Que todo funcione en modo de desarrollo con una cuenta con rol en la app no demuestra que el público pueda escribir a la integración de la página.

Documenta para los operadores la app de Meta propietaria y el ID de la página. Un token de página puede dejar de funcionar cuando cambian su propietario, los permisos, la asociación con la empresa o las políticas del proveedor.

## Rota o desconecta [#rota-o-desconecta]

Genera el token de página de reemplazo, actualiza el conector, haz una prueba con un usuario permitido y, después, invalida el token anterior. Actualiza Make Agent Fast inmediatamente después de rotar el secreto de la app.

Desactivar o eliminar el conector no cancela la suscripción de la página en Meta. Elimina la suscripción de la página y la credencial del proveedor que ya no uses cuando desmantelues la integración de forma permanente.

## Solución de problemas [#solución-de-problemas]

| Síntoma                                               | Solución                                                                                                                      |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Token rechazado                                       | Confirma que es un token de página de la página correcta y que el secreto de la app pertenece a la misma app                  |
| Falla la verificación del webhook                     | Copia exactamente la URL y el token de verificación actuales; usa HTTPS público                                               |
| La verificación funciona, pero los mensajes no llegan | Suscribe la página y el evento de mensajes, y revisa el modo de la app, el rol del usuario y los registros de entrega de Meta |
| Las solicitudes no están autorizadas                  | Corrige el secreto de la app; las solicitudes POST firmadas no usan el token de verificación                                  |
| Aparece el mensaje entrante, pero no hay respuesta    | Revisa la validez del token de página, los permisos de mensajería, el error de envío del proveedor y el estado del conector   |
| La voz recibe una respuesta de texto                  | Es el comportamiento esperado; actualmente no se admite la voz saliente en Messenger                                          |

Las credenciales del proveedor solo deben introducirse en el formulario autenticado del conector o en una llamada a la API de servidor de confianza.

---

# Resumen de conectores

Source: /es/docs/connectors/overview.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/connectors/telegram&#x22;, label: &#x22;Telegram&#x22;, icon: &#x22;telegram&#x22; },
{ href: &#x22;/es/docs/connectors/whatsapp&#x22;, label: &#x22;WhatsApp&#x22;, icon: &#x22;whatsapp&#x22; },
{ href: &#x22;/es/docs/connectors/messenger&#x22;, label: &#x22;Messenger&#x22;, icon: &#x22;messenger&#x22; },
{ href: &#x22;/es/docs/connectors/instagram&#x22;, label: &#x22;Instagram&#x22;, icon: &#x22;instagram&#x22; },
{ href: &#x22;/es/docs/connectors/discord&#x22;, label: &#x22;Discord&#x22;, icon: &#x22;discord&#x22; },
{ href: &#x22;/es/docs/connectors/kakao&#x22;, label: &#x22;KakaoTalk&#x22;, icon: &#x22;kakao&#x22; }
]"
/>

Los conectores reciben eventos de una plataforma de mensajería externa, normalizan el texto o el audio compatible, ejecutan el mismo agente del sitio y devuelven una respuesta adecuada para el canal. Cada usuario externo tiene un historial de conversación propio del canal, visible en **Conversaciones**.

Conectar un canal **nuevo** requiere el plan Operate o Scale. Las conexiones existentes siguen funcionando en Launch.

<TutorialVideo episode="ep09" start="15" />

## Matriz de capacidades [#matriz-de-capacidades]

| Canal     | Texto entrante      | Voz entrante | Texto saliente              | Voz saliente | Configuración en el proveedor tras guardar                               |
| --------- | ------------------- | ------------ | --------------------------- | ------------ | ------------------------------------------------------------------------ |
| Telegram  | Sí                  | Sí           | Sí                          | Opcional     | El webhook se registra automáticamente                                   |
| WhatsApp  | Sí                  | Sí           | Sí                          | Opcional     | Añade el webhook de Meta y la suscripción a `messages`                   |
| Messenger | Sí                  | Sí           | Sí                          | No           | Añade el webhook de Meta y suscribe la Página                            |
| Instagram | Sí                  | Sí           | Sí                          | No           | Añade el webhook de Instagram de Meta y suscribe `messages`              |
| Discord   | Pregunta con `/ask` | No           | Respuesta a `/ask`          | No           | Pega el endpoint de interacciones; el registro del comando es automático |
| KakaoTalk | Sí                  | No           | Respuesta de skill en línea | No           | Añade la URL de la skill, el encabezado y el bloque en Open Builder      |

«Voz entrante» significa que se descarga y se transcribe un mensaje de voz o audio compatible. «Voz saliente» requiere un proveedor de voz que funcione y la opción **Responder con voz** del conector. Los adjuntos no compatibles, como imágenes y ubicaciones, se ignoran en lugar de interpretarse como instrucciones para el agente.

## Antes de conectar [#antes-de-conectar]

1. Prueba el agente que quieres usar en el panel. Un conector en borrador también puede responder.
2. No necesitas una clave de modelo: la plataforma proporciona los modelos. Las claves de proveedor son opcionales y exclusivas del plan Scale; consulta [Claves de proveedor](/es/docs/account/provider-keys).
3. Crea una app, un bot, un número o un canal dedicado en el proveedor externo. No reutilices una credencial que pertenezca a una integración de producción sin relación.
4. Confirma que tu despliegue tiene una URL base HTTPS pública para el conector. Los webhooks de los proveedores no pueden entregar a `localhost` sin un túnel de desarrollo seguro.
5. Abre la página **Canales** del agente y elige el canal.

Al guardar, Make Agent Fast llama al proveedor para validar la credencial enviada. La etiqueta de conectado significa que la validación de la credencial y cualquier aprovisionamiento automático se completaron; no demuestra que se haya completado un paso manual en la consola de Meta, Discord o Kakao.

## Gestión de credenciales [#gestión-de-credenciales]

Los formularios de conector solo aceptan credenciales de proveedor desde el panel autenticado o desde la API pública del lado del servidor. Los secretos se cifran en reposo y nunca se devuelven en las respuestas de listado de conectores. Trata los siguientes valores como contraseñas:

* Token del bot de Telegram
* Tokens de acceso de Meta y secreto de la app
* Token del bot de Discord
* Clave de la REST API de Kakao y secreto del bot

No los coloques en JavaScript del navegador, capturas de pantalla, tickets de soporte ni control de código fuente. La URL del webhook y el token de verificación de Meta son valores de configuración pensados para copiarse en la consola del proveedor correspondiente; no sustituyen a las credenciales del proveedor.

## Conectar mediante la API [#conectar-mediante-la-api]

Usa una clave de API de MAF guardada en el servidor con `connectors:write`. El objeto `credentials` específico del canal es de solo escritura. La respuesta omite los secretos en texto plano e incluye la URL del webhook necesaria para la configuración manual en el proveedor.

```bash
curl -X POST "https://makeagent.fast/api/v1/sites/$SITE_ID/connectors" \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: connector-telegram-v1" \
  -d '{
    "channel": "telegram",
    "credentials": { "bot_token": "'$TELEGRAM_BOT_TOKEN'" },
    "reply_with_voice": false
  }'
```

`reply_with_voice` y el campo opcional `display_label` son campos de nivel superior, no van dentro de un objeto `config`. Guardar de nuevo el mismo bot o cuenta actualiza su credencial y su configuración conservando su token de enrutamiento. En Telegram e Instagram, un bot o una cuenta distintos añaden una nueva conexión (hasta cinco por agente); en los demás canales, guardar reemplaza la conexión existente. Consulta [Autenticación de la API](/es/docs/api/authentication), [Ámbitos y errores](/es/docs/api/scopes-errors) y la [Referencia de la API](/es/docs/api/reference) para conocer las reglas de integración en producción.

## Probar y supervisar [#probar-y-supervisar]

Usa un usuario de prueba del proveedor y una pregunta realista que dependa del conocimiento del agente. Confirma todo lo siguiente:

* El proveedor acepta o verifica el endpoint del webhook.
* Un mensaje llega al agente y recibe la respuesta esperada.
* **Último mensaje** cambia en la tarjeta del conector.
* La conversación aparece en **Conversaciones** con el canal correcto.
* Se entiende cualquier restricción de revisión o de modo de desarrollo del proveedor antes del lanzamiento público.
* La voz se prueba por separado del texto cuando el canal la admite.

La tarjeta del conector muestra el último error del proveedor o de entrega. Los paneles de los proveedores también conservan registros de entrega; compara las marcas de tiempo y los identificadores de evento cuando solo uno de los lados informe de la solicitud.

## Desactivar, rotar o eliminar [#desactivar-rotar-o-eliminar]

**Desactivar** detiene el procesamiento pero conserva el registro del conector. El webhook de Telegram permanece registrado mientras la conexión está desactivada (Make Agent Fast no llama a `deleteWebhook`) y los mensajes entrantes se ignoran; al activarla, el webhook se registra de nuevo. Las suscripciones configuradas en la consola del proveedor se mantienen y, si es necesario, también deben pausarse desde el lado del proveedor. **Eliminar** borra el conector de Make Agent Fast e intenta desmontar lo configurado en el proveedor en la medida de lo posible, pero no elimina la app externa, no revoca su credencial ni borra el historial de conversaciones existente.

Para rotar una credencial, crea el nuevo token en el proveedor, actualiza el conector, pruébalo y después revoca el token anterior. Si una credencial quedó expuesta, revócala primero en el proveedor y trata el intervalo de exposición como un incidente de seguridad.

## Fallos comunes [#fallos-comunes]

| Síntoma                                          | Qué comprobar                                                                                                                                         |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Las credenciales no se validan                   | App o bot correctos, tipo de token, caducidad, permiso requerido del proveedor y caracteres copiados                                                  |
| Falla la verificación del webhook                | URL HTTPS pública, token de verificación exacto, producto del proveedor correcto y secreto de firma de solicitudes                                    |
| La verificación funciona pero no llegan mensajes | Suscripción a eventos, asociación de Página/número/canal, modo de la app del proveedor y estado de activación del conector                            |
| El texto funciona pero la voz falla              | Capacidad del canal, clave de voz/transcripción, audio compatible, permiso de medios y caducidad de la descarga del proveedor                         |
| Las respuestas se detienen tras la rotación      | Nueva credencial guardada, credencial anterior revocada solo después de probar, y suscripción manual del proveedor que sigue apuntando a este webhook |

Continúa con la guía del canal para ver los campos exactos del proveedor y la secuencia en su consola.

---

# Telegram

Source: /es/docs/connectors/telegram.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/connectors/overview&#x22;, label: &#x22;Todos los conectores&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/es/docs/operate/conversations&#x22;, label: &#x22;Bandeja de entrada&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;Telegram&#x22;, icon: &#x22;telegram&#x22; }
]"
/>

<TutorialVideo episode="ep03" />

## Configuración rápida [#configuración-rápida]

Si **Crear con QR** está disponible en el conector de Telegram, selecciónalo, escanea el código QR o elige **Abrir Telegram**, y toca **Crear bot** en el bot de configuración. Vuelve a Make Agent Fast, revisa el nombre de usuario del bot y selecciona **Conectar este bot**. No necesitas copiar ningún token. La configuración caduca a los 15 minutos; puedes cancelarla y reiniciarla.

Si la configuración rápida no está disponible, usa **Conectar con un token de bot** más abajo. Ambos métodos usan las mismas comprobaciones de conexión y la misma confirmación de reemplazo.

El formulario de creación sugiere el nombre visible de tu agente y un nombre de usuario con el formato `maf_<agent>_<random>_bot`. Ambos son editables; la parte aleatoria reduce las colisiones de nombres, pero Telegram realiza la comprobación final de disponibilidad. Los bots existentes no se renombran.

Tras la creación, el bot de configuración envía un botón **Conectar este bot** que abre la revisión de conexión autenticada de tu agente. Crear el bot por sí solo no lo conecta. Cuando la confirmación se completa correctamente, **Abrir bot** te lleva a la conversación para probarlo. `/start` o `/help` restablece una configuración activa o muestra botones del panel y de la guía.

## Crear y preparar un bot manualmente [#crear-y-preparar-un-bot-manualmente]

Sigue la [Introducción a los bots](https://core.telegram.org/bots) y la [guía de BotFather](https://core.telegram.org/bots/features#botfather) oficiales de Telegram:

1. Abre la cuenta verificada **@BotFather** en Telegram.
2. Ejecuta `/newbot`, elige un nombre visible y elige un nombre de usuario único que termine en `bot`.
3. Copia el token del bot. Cualquiera que tenga este token controla el bot.
4. Opcionalmente, configura en BotFather la foto, la descripción, el texto "Acerca de" y la ayuda de comandos localizada antes del lanzamiento.

El token es para la API de Bot de Telegram; no es un código de inicio de sesión de Telegram, ni un API ID, ni un API hash.

## Conectar en Make Agent Fast [#conectar-en-make-agent-fast]

Abre la página **Canales** del agente, elige **Telegram**, pega el **Token del bot**, decide si las respuestas compatibles también deben enviarse por voz y selecciona **Conectar**.

Make Agent Fast llama a `getMe` de Telegram para validar el token y mostrar el nombre de usuario del bot. Después llama a `setWebhook` con la URL HTTPS pública del conector, un token secreto de verificación y `message`, `callback_query` y `my_chat_member` como tipos de actualización aceptados. Las actualizaciones pendientes existentes no se descartan.

Normalmente no se requiere ningún paso manual para el webhook. Detén cualquier servicio de polling antes de conectar. Si el bot tiene otro receptor de webhook, revisa y confirma su reemplazo; Make Agent Fast no lo toma de forma silenciosa. Un agente puede responder en hasta cinco bots de Telegram a la vez; cada bot es su propia conexión. Guardar un bot distinto añade una nueva conexión en lugar de reemplazar la actual. Un bot que ya esté asociado a otro agente debe desconectarse primero allí.

## Probar la conversación [#probar-la-conversación]

1. Abre el enlace `t.me` del bot desde una cuenta de Telegram que no sea la del propietario.
2. Selecciona **Iniciar**; los bots no pueden iniciar una conversación con un usuario.
3. Envía una pregunta de texto basada en el conocimiento.
4. Envía una nota de voz si la voz está activada.
5. Confirma que llegan las respuestas, que **Último mensaje** cambia y que el hilo aparece en **Conversaciones**.

Los mensajes privados son públicos por defecto: los visitantes no necesitan la aprobación del propietario. Las respuestas en grupos están desactivadas hasta que el propietario active **Responder en grupos cuando se mencione o se responda al bot**. El modo de privacidad de Telegram y los permisos del grupo siguen aplicándose. Prueba primero los mensajes directos.

## Comportamiento de la voz [#comportamiento-de-la-voz]

Telegram admite voz entrante y voz saliente en este conector. La voz entrante se descarga y se transcribe antes del turno del agente. Con **Responder con voz** activado y un proveedor de voz disponible, Make Agent Fast envía una respuesta de voz o audio además del texto. Si falla la transcripción o la síntesis de voz, pide al usuario que lo intente de nuevo por texto y revisa el error del conector.

## Rotar, desactivar o eliminar [#rotar-desactivar-o-eliminar]

Si el token queda expuesto, genéralo o revócalo de inmediato en BotFather, actualiza el conector con el nuevo token y vuelve a probar. Actualizar las credenciales del mismo bot conserva sus ajustes y su estado de pausa. Reemplazarlo por un bot distinto requiere confirmación y mantiene separado el historial del bot anterior.

Desactivar detiene las respuestas localmente; eliminar archiva la conexión y conserva su historial. Ninguna de las dos acciones borra el bot de Telegram ni llama a `deleteWebhook`, lo que podría interrumpir un receptor más reciente. Las conexiones archivadas ignoran los mensajes entrantes. Los bots creados con la configuración rápida pueden actualizar sus credenciales tras eventos del ciclo de vida del gestor, pero un bot en pausa permanece en pausa y un cambio de propiedad desactiva la conexión para su revisión.

## Solución de problemas [#solución-de-problemas]

| Síntoma                                              | Solución                                                                                                                                      |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| El token se rechaza al guardar                       | Copia el token actual de BotFather; elimina los espacios en blanco y asegúrate de que pertenece a este bot                                    |
| Los mensajes llegan a un servicio anterior           | Detén allí el polling, vuelve a conectar aquí y confirma de forma explícita cualquier reemplazo de receptor                                   |
| Los mensajes directos funcionan pero los de grupo no | Activa las respuestas en grupos, menciona al bot o responde a su mensaje, y revisa el modo de privacidad de Telegram y los permisos del grupo |
| El bot no escribe primero a un usuario nuevo         | Es el comportamiento esperado de Telegram; pide al usuario que abra el bot y seleccione **Iniciar**                                           |
| El texto funciona pero la voz falla                  | Revisa las claves del modelo, de transcripción y de voz, y vuelve a intentarlo con una nota de voz de Telegram compatible                     |

Nunca pegues un token activo en documentación, código fuente, analítica ni capturas de pantalla de soporte.

---

# WhatsApp

Source: /es/docs/connectors/whatsapp.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/connectors/overview&#x22;, label: &#x22;Todos los conectores&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/es/docs/operate/conversations&#x22;, label: &#x22;Bandeja de entrada&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;WhatsApp&#x22;, icon: &#x22;whatsapp&#x22; }
]"
/>

<TutorialVideo episode="ep04" />

## Prepara la app de Meta y el número [#prepara-la-app-de-meta-y-el-número]

Usa la [guía de inicio de la API de WhatsApp Cloud](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started) oficial de Meta para crear o seleccionar una app de Meta, añadir el producto WhatsApp y asociar una cuenta de WhatsApp Business y un número de teléfono.

Reúne estos tres valores de la misma app y del mismo número:

| Campo de Make Agent Fast      | Valor del proveedor                                  | Notas                                                                                                                   |
| ----------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **ID del número de teléfono** | ID numérico del número de teléfono (Phone Number ID) | No es el número visible con `+` ni el ID de la WABA                                                                     |
| **Token de acceso**           | Token de acceso de la Cloud API                      | Los tokens temporales del panel caducan; para producción usa un token de usuario del sistema de larga duración adecuado |
| **Secreto de la app**         | Secreto de la app de Meta                            | Un secreto hexadecimal de 32 caracteres que se usa para verificar la firma del webhook                                  |

Concede únicamente los permisos necesarios para el número y el flujo de mensajería. Mantén los recursos de desarrollo y pruebas separados del número de producción.

## Guarda y valida las credenciales [#guarda-y-valida-las-credenciales]

Abre la página **Canales** del agente, selecciona **WhatsApp**, introduce los tres valores, elige **Responder con voz** si lo necesitas y selecciona **Conectar**.

Make Agent Fast valida el número a través de la Graph API usando el token de acceso junto con `appsecret_proof`; así se detecta un número, un token o un secreto de la app incorrectos antes de que empiece el tráfico del webhook. Después, la tarjeta del conector muestra una **URL del webhook** y un **Token de verificación** únicos.

## Configura el webhook de Meta [#configura-el-webhook-de-meta]

En la misma app de Meta:

1. Abre la configuración del webhook de WhatsApp.
2. Pega la **URL del webhook** del conector como URL de devolución de llamada.
3. Pega el **Token de verificación** del conector exactamente como aparece; distingue entre mayúsculas y minúsculas.
4. Completa la verificación.
5. Suscribe la cuenta de WhatsApp Business o el número al campo de webhook `messages`.
6. Confirma que la app y los recursos de negocio están disponibles para los usuarios de prueba o de producción previstos.

El token de verificación demuestra la propiedad durante el desafío de verificación GET. Las solicitudes POST en tiempo de ejecución se autentican por separado con la firma del secreto de la app de Meta; no sustituyas una por otra.

## Prueba texto y voz [#prueba-texto-y-voz]

Envía primero un mensaje desde un número de prueba permitido. En el modo de desarrollo de Meta, es posible que los usuarios no registrados no puedan comunicarse con la app. Confirma el hilo y el canal en **Conversaciones** y observa **Último mensaje** en la tarjeta del conector.

Se admiten texto y voz entrantes. Con **Responder con voz** activado y la voz configurada, Make Agent Fast sube el audio generado a través de la Cloud API y lo envía junto con la respuesta de texto. Las imágenes, ubicaciones, contactos y otros tipos de mensaje no compatibles se ignoran.

## Preparación para producción [#preparación-para-producción]

Antes de dar a conocer el número, completa la verificación de empresa de Meta, la revisión de la app, el nombre para mostrar, las plantillas y los pasos de la política de mensajería que exija tu caso de uso. Estos requisitos los controla Meta y pueden cambiar con independencia de Make Agent Fast.

Usa una credencial de producción con un responsable definido y un procedimiento de caducidad y rotación. Anota qué app de Meta, usuario del sistema, WABA y Phone Number ID pertenecen a este conector para que un operador pueda rotarlo sin adivinar.

## Rota o desconecta [#rota-o-desconecta]

Crea un token de reemplazo con el mismo acceso a los recursos, actualiza el conector, envía un mensaje de prueba y solo entonces revoca el token anterior. Si cambia el secreto de la app, actualízalo de inmediato en Make Agent Fast o todos los webhooks entrantes firmados fallarán.

Desactivar o eliminar el conector no cancela la suscripción ni borra la configuración del webhook en Meta. Elimina también la suscripción del proveedor cuando des de baja el número de forma definitiva.

## Solución de problemas [#solución-de-problemas]

| Síntoma                                              | Solución                                                                                                                                                           |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Credenciales rechazadas                              | Confirma que el token puede leer el Phone Number ID exacto y que el secreto de la app pertenece a la misma app                                                     |
| Meta no puede verificar la devolución de llamada     | Usa la URL HTTPS copiada y el token de verificación exacto; comprueba que el conector sigue existiendo                                                             |
| La verificación se completa, pero no llegan mensajes | Suscribe `messages` y revisa la asociación de la WABA y el número, el modo de la app, el acceso de los usuarios de prueba y los registros de entrega del proveedor |
| Los webhooks devuelven «unauthorized»                | Vuelve a introducir el secreto de la app correcto; las firmas POST de Meta no usan el token de verificación                                                        |
| Fallan las respuestas salientes                      | Revisa la caducidad del token, los permisos del número, la política o ventana del destinatario y los errores de la Graph API                                       |
| El texto funciona, pero el audio falla               | Revisa las claves del proveedor de transcripción o de voz y el acceso del token a la subida y descarga de contenido multimedia                                     |

No expongas nunca el token de acceso ni el secreto de la app en código del navegador. Usa la API pública solo desde un servidor de confianza cuando automatices la creación de conectores.

---

# Astro

Source: /es/docs/embed/astro.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/embed/overview&#x22;, label: 'Resumen de la incrustación', icon: &#x22;embed&#x22; },
{ label: &#x22;Astro&#x22;, icon: &#x22;astro&#x22; },
{ href: &#x22;/es/docs/embed/security&#x22;, label: 'Seguridad y CSP', icon: &#x22;shield&#x22; }
]"
/>

## Prepara el origen de despliegue [#prepara-el-origen-de-despliegue]

Activa **Mostrarlo en mi sitio web** para el agente de Make Agent Fast (página del agente → **Ponlo en marcha** → **Widget para sitio web**) y añade los orígenes exactos de desarrollo, vista previa y producción de Astro en **Direcciones de sitio web permitidas**. Lo que importa es el esquema, el nombre de host y el puerto finales que se ven en el navegador, no el host de compilación ni la URL del repositorio.

## Añádelo a un layout compartido [#añádelo-a-un-layout-compartido]

Coloca el cargador externo estándar justo antes de `</body>` en el layout de Astro que deba encargarse del lanzador.

```astro
---
// src/layouts/BaseLayout.astro
---

<html lang="en">
  <body>
    <slot />

    <script
      is:inline
      src="https://makeagent.fast/embed.js?v=20261022-open"
      data-agent="YOUR_SITE_SLUG"
      data-position="right"
      data-label="Ask us"
      async
    ></script>
  </body>
</html>
```

`is:inline` le indica a Astro que conserve la etiqueta de script externa y sus atributos `data-*` en lugar de empaquetarla o transformarla. El cargador sigue siendo público e independiente del framework; no lo importes en un módulo de servidor.

## Limítalo a páginas seleccionadas [#limítalo-a-páginas-seleccionadas]

Usa un layout anidado o incluye la etiqueta solo en determinadas páginas `.astro`. Evita colocar la misma etiqueta tanto en un layout base como en una página. El cargador ignora una raíz duplicada con el mismo slug, pero el HTML duplicado dificulta entender la navegación y el desmontaje.

Si las transiciones de vista del lado del cliente de Astro están activadas, prueba tanto las cargas directas de página como la navegación dentro de la aplicación. Para un agente en todo el sitio, es preferible un layout compartido persistente. Para un comportamiento específico por ruta, elimina tanto el script como `maf-embed-root-YOUR_SITE_SLUG` al salir de la ruta, antes de insertar un script nuevo más adelante.

## Configura CSP y consentimiento [#configura-csp-y-consentimiento]

Las cabeceras del alojamiento estático siguen controlando el navegador. Permite `https://makeagent.fast` en `script-src`, `frame-src` y en la política de conexión correspondiente. Si un gestor de consentimiento bloquea el script, carga la etiqueta solo después de obtener el consentimiento necesario, en lugar de debilitar la CSP o eludir el consentimiento.

## Verifica el resultado compilado [#verifica-el-resultado-compilado]

1. Ejecuta la compilación de producción de Astro e inspecciona el HTML generado para comprobar que se conserva la etiqueta con `data-agent`.
2. Abre la página desplegada en una ventana privada.
3. Confirma que hay una sola raíz de incrustación y que las solicitudes del cargador y del iframe se completan correctamente.
4. Navega entre rutas de Astro y confirma que la persistencia es la esperada.
5. Envía un mensaje real y prueba el comportamiento en móvil y con el micrófono.

## Solución de problemas [#solución-de-problemas]

| Síntoma                                                           | Solución                                                                  |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------- |
| El HTML compilado omite o modifica atributos                      | Añade `is:inline` al script externo                                       |
| Se generan dos etiquetas de script                                | Mantén la instalación en un único layout o página responsable             |
| La navegación del cliente se comporta distinto a la carga directa | Prueba las transiciones de vista y elige un layout compartido persistente |
| Funciona en desarrollo pero no en el alojamiento estático         | Añade el origen exacto de producción y las cabeceras CSP del alojamiento  |
| La voz falla                                                      | Configura HTTPS, el permiso del navegador y la Permissions Policy         |

Actualmente no se publica ningún adaptador de Astro en npm; usa el cargador alojado que se muestra aquí.

---

# Cafe24

Source: /es/docs/embed/cafe24.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/embed/overview&#x22;, label: 'Resumen de la integración', icon: &#x22;embed&#x22; },
{ label: &#x22;Cafe24&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/es/docs/embed/security&#x22;, label: 'Seguridad y CSP', icon: &#x22;shield&#x22; }
]"
/>

Cafe24 (카페24) es una plataforma de comercio electrónico coreana cuyo diseño de tienda se edita en HTML. Instala el lanzador en el diseño compartido (layout) del diseño que tienes activo. Actualmente no existe una app de Make Agent Fast en la tienda de apps de Cafe24. Los nombres de los menús que aparecen aquí corresponden a 2026-09; si alguna etiqueta ha cambiado de lugar, busca el ajuste por lo que hace y no por su ruta exacta.

## Añade el loader [#añade-el-loader]

1. En el panel de Make Agent Fast, abre **Ponlo en marcha** → **Widget para sitio web** en la página del agente, activa **Mostrar en mi sitio web** y añade en **Direcciones de sitio web permitidas** todos los orígenes de tu tienda: la dirección de la tienda en `cafe24.com` y tu dominio personalizado, además de la dirección móvil si es distinta.
2. Abre la gestión de diseño e inicia la edición HTML del diseño que está activo. Duplica el diseño o haz una copia de seguridad antes; estás editando el código fuente de la tienda.
3. En el archivo de layout compartido que incluyen todas las páginas, pega el fragmento generado justo antes de la etiqueta de cierre `</body>`.
4. Guarda, aplica el diseño a la tienda y repite el proceso en el diseño móvil si tu tienda mantiene por separado los diseños para PC y móvil.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Si no encuentras el archivo de layout, pega el fragmento en el bloque de pie de página de tu tema: sirve cualquier módulo que se muestre en todas las páginas, siempre que se incluya una sola vez.

## Verifica [#verifica]

1. Abre la tienda en una ventana privada, tanto en la dirección de PC como en la móvil.
2. Confirma que el origen de la barra de direcciones es el que añadiste a la lista de permitidos, incluido `www` si el dominio redirige a él.
3. Confirma que `embed.js` devuelve `200` en el panel Network y que existe un único elemento `data-maf-embed="YOUR_SITE_SLUG"`.
4. Haz una pregunta realista y comprueba que el mensaje aparece en **Conversaciones**.

## Solución de problemas [#solución-de-problemas]

| Síntoma                                               | Causa probable                                    | Solución                                                            |
| ----------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------- |
| Funciona en PC pero no en móvil                       | El diseño móvil tiene su propio archivo de layout | Añade el fragmento también al diseño móvil                          |
| El lanzador desapareció tras un cambio de diseño      | Se aplicó un diseño que no contiene el fragmento  | Vuelve a añadirlo al layout del diseño que está sirviendo la tienda |
| El lanzador tapa el carrito o una barra fija inferior | Dos elementos fijos comparten la misma esquina    | Cambia la esquina del lanzador con `data-position`                  |

No incluyas una clave de API, un número de pedido ni datos de clientes en ningún atributo `data-*`. [Seguridad y CSP](/es/docs/embed/security) explica cómo configurar la lista de permitidos y la Content Security Policy en las tiendas que usan una.

---

# Framer

Source: /es/docs/embed/framer.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/embed/overview&#x22;, label: 'Resumen de la incrustación', icon: &#x22;embed&#x22; },
{ label: &#x22;Framer&#x22;, icon: &#x22;framer&#x22; },
{ href: &#x22;/es/docs/embed/security&#x22;, label: 'Seguridad y CSP', icon: &#x22;shield&#x22; }
]"
/>

## Disponibilidad del componente de código [#disponibilidad-del-componente-de-código]

Copia `integrations/framer/MakeAgentFast.tsx` en un componente de código de Framer y elige el agente publicado. El código fuente expone controles para la URL de la plataforma, la posición y la etiqueta. Se trata de código fuente que se copia manualmente, no de un componente publicado en el Framer Marketplace. Aquí aparecerá la URL de un listado solo cuando un propietario autorizado lo publique y lo verifique.

## Código personalizado [#código-personalizado]

Añade el cargador estándar en **Site settings → Custom code**, al final del body.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Publica el sitio antes de probar. El lienzo y el host de vista previa de Framer pueden usar orígenes distintos al del nombre de host publicado en producción.

---

# Ghost

Source: /es/docs/embed/ghost.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/embed/overview&#x22;, label: 'Resumen de la integración', icon: &#x22;embed&#x22; },
{ label: &#x22;Ghost&#x22;, icon: &#x22;ghost&#x22; },
{ href: &#x22;/es/docs/embed/security&#x22;, label: 'Seguridad y CSP', icon: &#x22;shield&#x22; }
]"
/>

Abre **Settings → Code injection** (**Configuración → Inyección de código**) y añade el script en el pie de página del sitio.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Usa la inyección de código a nivel de publicación solo cuando quieras que el agente aparezca en publicaciones concretas. Si en cambio modificas un tema, coloca el cargador en `default.hbs` antes de `</body>` y vuelve a comprobarlo después de cada actualización del tema.

Añade a la lista de orígenes permitidos el origen público de la publicación y borra cualquier caché de borde antes de probar un slug modificado.

---

# HTML y JavaScript

Source: /es/docs/embed/html.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/embed/overview&#x22;, label: 'Resumen del embed', icon: &#x22;embed&#x22; },
{ label: &#x22;HTML&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/es/docs/embed/security&#x22;, label: 'Seguridad y CSP', icon: &#x22;shield&#x22; }
]"
/>

## Prepara el sitio [#prepara-el-sitio]

En la página **Agente** de tu agente, abre **Publícalo** → **Widget para sitio web**, activa **Mostrarlo en mi sitio web** y añade el origen final de la página anfitriona en **Direcciones de sitio web permitidas**. Añade desarrollo y producción por separado; `http://localhost:3000`, `https://example.com` y `https://www.example.com` no coinciden entre sí.

## Instala el script [#instala-el-script]

Pega el cargador justo antes de la etiqueta de cierre `</body>` en cada página que deba mostrar el lanzador. Sustituye únicamente el slug público del sitio y los valores opcionales de presentación.

```html
<script
  src="https://makeagent.fast/embed.js?v=20261022-open"
  data-agent="YOUR_SITE_SLUG"
  data-position="right"
  async
></script>
```

`data-agent` es obligatorio. El slug es público; en esta etiqueta no debe ir ninguna clave de API. Conserva el parámetro `?v=` del fragmento del panel. Los atributos opcionales `data-label`, `data-accent` (`#RGB` / `#RRGGBB`), `data-locale` (`en` | `ko` | `uz` | `ru`) y `data-theme` (`light` | `dark`) están documentados en [Resumen del embed](/es/docs/embed/overview). Omítelos para heredar los ajustes guardados en **Apariencia** y el comportamiento automático del tema.

## Elige entre colocación en todo el sitio o en páginas específicas [#elige-entre-colocación-en-todo-el-sitio-o-en-páginas-específicas]

Si usas una plantilla compartida del lado del servidor, coloca el script en el diseño o pie de página global. Para páginas concretas, inclúyelo solo en esas plantillas. Carga el mismo slug una sola vez por documento; las etiquetas duplicadas con el mismo slug se ignoran, pero eliminarlas hace que la propiedad y el desmontaje sean más predecibles.

No pegues el fragmento en un sanitizador de HTML ni en un campo de texto enriquecido que elimine `<script>`. Comprueba que el código fuente de la página renderizada o el panel Elements sigan conteniendo la etiqueta.

## Elimina o vuelve a montar en una SPA [#elimina-o-vuelve-a-montar-en-una-spa]

Eliminar el script después de que se ejecute no elimina el lanzador que ya creó. Una aplicación cliente específica de una ruta debe eliminar tanto el script como la raíz propia del slug antes de volver a montarlo:

```js
const slug = "YOUR_SITE_SLUG";
document.getElementById("maf-agent")?.remove();
document.getElementById(`maf-embed-root-${slug}`)?.remove();
```

Es preferible mantener una única raíz global montada durante la navegación del lado del cliente para que la conversación activa no se pierda. Si eliminas la raíz, añade un nuevo script `embed.js` para crearla de nuevo.

## Verifica en el navegador [#verifica-en-el-navegador]

1. Abre la página desplegada en una ventana privada.
2. Confirma que `embed.js` devuelve `200` y que no lo bloquean la CSP ni el consentimiento.
3. Confirma que existe una sola raíz `[data-maf-embed="YOUR_SITE_SLUG"]`.
4. Abre el lanzador y confirma que el iframe `/embed/YOUR_SITE_SLUG` se carga.
5. Envía una pregunta y confirma la conversación en **Conversaciones**.
6. Prueba el ancho móvil y el permiso del micrófono cuando la voz esté activada.

## Solución de problemas [#solución-de-problemas]

| Síntoma                                       | Solución                                                                                 |
| --------------------------------------------- | ---------------------------------------------------------------------------------------- |
| La consola advierte de que falta `data-agent` | Coloca el atributo en la etiqueta exacta de `embed.js`                                   |
| El script existe, pero el lanzador no aparece | Revisa el interruptor del embed, el origen exacto, la CSP y el estado del consentimiento |
| Funciona solo en un nombre de host            | Añade cada esquema/host/puerto real a la lista de permitidos                             |
| El estilo no es el esperado                   | Revisa `data-accent`, `data-theme` y la apariencia del sitio guardada                    |
| La voz falla dentro del iframe                | Permite el micrófono en el navegador y en la Permissions Policy del sitio anfitrión      |

Nunca uses un proxy ni copies el cargador en una bifurcación local sin revisar; usa el script alojado para que la validación de origen y las correcciones se mantengan al día.

---

# Imweb

Source: /es/docs/embed/imweb.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/embed/overview&#x22;, label: 'Resumen del embed', icon: &#x22;embed&#x22; },
{ label: &#x22;Imweb&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/es/docs/embed/security&#x22;, label: 'Seguridad y CSP', icon: &#x22;shield&#x22; }
]"
/>

Imweb (아임웹) es un creador de sitios web coreano utilizado por muchas tiendas y estudios pequeños. Instala el lanzador con el ajuste de inserción de código propio de Imweb. No existe ninguna aplicación de Make Agent Fast en un catálogo de Imweb. Los nombres de menú que aparecen aquí corresponden a 2026-09; si alguna etiqueta ha cambiado de lugar, busca el ajuste por lo que hace y no por su ruta exacta.

## Añade el loader [#añade-el-loader]

1. En el panel de Make Agent Fast, abre **Publícalo** → **Widget para sitio web** en la página del agente, activa **Mostrarlo en mi sitio web** y añade a **Direcciones web permitidas** todos los orígenes que sirve Imweb: tu dominio personalizado y la dirección gratuita `imweb.me` si todavía la usas.
2. Abre los ajustes del sitio y busca el área de inserción de código: los campos que añaden código al `<head>` de todas las páginas o al final del body. La disponibilidad depende de tu plan de Imweb.
3. Pega el fragmento generado en el campo del head. El loader es `async`, por lo que funciona tanto en el head como al final del body.
4. Guarda y aplica el cambio al sitio en vivo; después recarga la tienda en una pestaña nueva.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Si no encuentras ese ajuste, pega el fragmento en el bloque de pie de página de tu tema: un widget HTML colocado en una sección de pie de página se ejecuta en todas las páginas que usan esa sección.

## Verifica [#verifica]

1. Abre la URL publicada en una ventana privada, no en el editor de Imweb. Los modos de editor y vista previa pueden suprimir los scripts inyectados.
2. Confirma que el origen de la barra de direcciones es el que añadiste a la lista de permitidos, incluido `www` si el dominio redirige a esa versión.
3. Confirma que `embed.js` devuelve `200` en el panel Network y que existe un único elemento `data-maf-embed="YOUR_SITE_SLUG"`.
4. Haz una pregunta realista y confirma que el mensaje aparece en **Conversaciones**.

## Solución de problemas [#solución-de-problemas]

| Síntoma                                                     | Causa probable                                                                        | Solución                                                 |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| No se carga nada en el dominio personalizado                | Solo se permitió la dirección `imweb.me`                                              | Añade también el origen exacto del dominio personalizado |
| El lanzador aparece dos veces                               | El fragmento está tanto en el campo del head como en un widget HTML del pie de página | Conserva una sola copia, en el campo del head            |
| El lanzador se superpone con un botón flotante de la tienda | Dos elementos fijos comparten la misma esquina                                        | Cambia la esquina del lanzador con `data-position`       |

Si la tienda usa un banner de consentimiento o un bloqueador de scripts, clasifica el embed según tu política de consentimiento y cárgalo en consecuencia. [Seguridad y CSP](/es/docs/embed/security) enumera los orígenes que debes permitir.

---

# Notion y Linktree

Source: /es/docs/embed/notion-linktree.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/embed/overview&#x22;, label: 'Resumen de la integración', icon: &#x22;embed&#x22; },
{ label: &#x22;Notion&#x22;, icon: &#x22;notion&#x22; },
{ href: &#x22;/es/docs/embed/security&#x22;, label: 'Seguridad y CSP', icon: &#x22;shield&#x22; }
]"
/>

Las páginas de Notion y los perfiles de Linktree no ofrecen una superficie para ejecutar JavaScript arbitrario en todo el sitio, por lo que no admiten el widget flotante. En su lugar, comparte el **Agent link** de tu agente: una página de chat pública en la dirección propia del agente.

## Añade un enlace [#añade-un-enlace]

1. En el último paso de la configuración inicial, activa **Agent link** en **Prueba en tu teléfono**. El mismo interruptor está en la pestaña **Visualización** de la página del agente.
2. Copia la URL real del Agent link que muestra Make Agent Fast. No inventes el slug del agente ni el dominio.
3. Añade un enlace o marcador en Notion, o un enlace en Linktree, por ejemplo **Chatea con nuestro agente**.
4. Abre el enlace en tu teléfono. Cualquier persona con el enlace puede chatear mientras la página esté activada; si la desactivas, la página deja de estar disponible.

El sitio web de tu cliente no necesita el script para que este enlace funcione. Si prefieres enlazar a tu propio sitio web, instala primero el widget allí y usa la URL de esa página. Un enlace normal es más fiable que colocar la página dentro del iframe de otra plataforma, que puede restringir el acceso al micrófono y afectar al diseño.

---

# Descripción general del embed

Source: /es/docs/embed/overview.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/embed/html&#x22;, label: &#x22;HTML&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/es/docs/embed/react-next&#x22;, label: &#x22;React&#x22;, icon: &#x22;react&#x22; },
{ href: &#x22;/es/docs/embed/vue-nuxt&#x22;, label: &#x22;Vue&#x22;, icon: &#x22;vue&#x22; },
{ href: &#x22;/es/docs/embed/sveltekit&#x22;, label: &#x22;SvelteKit&#x22;, icon: &#x22;svelte&#x22; },
{ href: &#x22;/es/docs/embed/astro&#x22;, label: &#x22;Astro&#x22;, icon: &#x22;astro&#x22; },
{ href: &#x22;/es/docs/embed/wordpress&#x22;, label: &#x22;WordPress&#x22;, icon: &#x22;wordpress&#x22; },
{ href: &#x22;/es/docs/embed/shopify&#x22;, label: &#x22;Shopify&#x22;, icon: &#x22;shopify&#x22; },
{ href: &#x22;/es/docs/embed/webflow&#x22;, label: &#x22;Webflow&#x22;, icon: &#x22;webflow&#x22; },
{ href: &#x22;/es/docs/embed/framer&#x22;, label: &#x22;Framer&#x22;, icon: &#x22;framer&#x22; },
{ href: &#x22;/es/docs/embed/wix&#x22;, label: &#x22;Wix&#x22;, icon: &#x22;wix&#x22; },
{ href: &#x22;/es/docs/embed/squarespace&#x22;, label: &#x22;Squarespace&#x22;, icon: &#x22;squarespace&#x22; },
{ href: &#x22;/es/docs/embed/ghost&#x22;, label: &#x22;Ghost&#x22;, icon: &#x22;ghost&#x22; },
{ href: &#x22;/es/docs/embed/notion-linktree&#x22;, label: &#x22;Notion&#x22;, icon: &#x22;notion&#x22; },
{ href: &#x22;/es/docs/embed/tilda&#x22;, label: &#x22;Tilda&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/es/docs/embed/imweb&#x22;, label: &#x22;Imweb&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/es/docs/embed/cafe24&#x22;, label: &#x22;Cafe24&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/es/docs/embed/security&#x22;, label: &#x22;CSP&#x22;, icon: &#x22;shield&#x22; }
]"
/>

<TutorialVideo episode="ep02" />

## Cómo funciona el embed [#cómo-funciona-el-embed]

`embed.js` añade un único lanzador fijo al documento anfitrión. Puede precargar el iframe oculto desde `https://makeagent.fast` para evaluar los activadores de la página antes del primer clic; el visitante abre el chat completo desde el lanzador o desde un activador. El CSS del sitio anfitrión no puede cambiar el estilo del chat. Los cambios en la página anfitriona solo se ejecutan mediante [controladores de acciones de página](/es/docs/build/page-actions) registrados y aprobados por el propietario.

El cargador es público y **no** usa una clave de API. El acceso se controla con el interruptor **Mostrar en mi sitio web** del agente y con la lista de permitidos de orígenes padre exactos (**Direcciones de sitio web permitidas**). El slug del sitio es un identificador, no un secreto.

## Requisitos previos [#requisitos-previos]

Antes de copiar el código:

1. Crea y prueba un agente en el panel.
2. Usa el fragmento generado del agente; no es necesario activar su **Agent link** independiente.
3. En la página **Agente** del agente, abre **Publicar** → **Widget para sitio web**. Si el widget aún no está activado, elige **Activar embed**; después confirma que **Mostrar en mi sitio web** esté activado.
4. En **Direcciones de sitio web permitidas**, añade cada origen padre que mostrará el lanzador.
5. Selecciona **Guardar ajustes del embed** y luego copia el fragmento generado.

Un origen contiene solo el esquema, el nombre de host y, opcionalmente, el puerto. Nunca incluye una ruta. Estos son cuatro orígenes distintos y deben añadirse por separado cuando los uses:

```text
https://example.com
https://www.example.com
https://staging.example.com
http://localhost:3000
```

No introduzcas `https://example.com/pricing`, `*.example.com` ni un comodín al final. Si en producción el dominio sin `www` redirige a `www`, añade a la lista de permitidos el origen que permanece en la barra de direcciones del navegador después de la redirección.

## Instala el cargador [#instala-el-cargador]

Coloca un script antes de la etiqueta de cierre `</body>`, o usa el ciclo de vida solo para navegador que recomiende la guía de tu framework.

La hoja **Widget para sitio web** (página Agente → **Publicar**) copia esta estructura (slug del sitio, posición, etiqueta opcional y el `?v=` para invalidar la caché). Conserva `async`. Conserva la consulta `?v=` del fragmento para que los sitios anfitriones no fijen un cargador obsoleto.

```html
<script
  src="https://makeagent.fast/embed.js?v=20261022-open"
  data-agent="YOUR_SITE_SLUG"
  data-position="right"
  async
></script>
```

Solo `data-agent` es obligatorio. Atributos opcionales que el cargador realmente lee:

```html
<script
  src="https://makeagent.fast/embed.js?v=20261022-open"
  data-agent="YOUR_SITE_SLUG"
  data-position="right"
  data-label="Ask us"
  data-accent="#6d5ce7"
  data-locale="en"
  data-theme="light"
  async
></script>
```

No pongas una clave de API de MAF, una clave de proveedor, un token de conector, la identidad del visitante ni datos privados de clientes en ningún atributo `data-*`. No inventes atributos como `data-api-key`, `data-z-index`, `data-offset` o `data-delay`. `data-maf-bootstrapped` lo establece el cargador.

## Configura los atributos [#configura-los-atributos]

Se leen solo desde la etiqueta de `embed.js`. El iframe acepta únicamente acentos en formato hexadecimal.

| Atributo               | Valor aceptado                                                                                                        | Predeterminado                                       | Efecto                                                                                                                                                                                  |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-agent`           | Slug del sitio del agente                                                                                             | Obligatorio                                          | Selecciona el sitio y el agente. Si falta → aviso en la consola, sin lanzador                                                                                                           |
| `data-position`        | `bottom-left`, `bottom-right`, `top-left`, `top-right` (`left` / `right` siguen significando las esquinas inferiores) | `right` (bottom-right)                               | Cualquier otro valor se trata como bottom-right                                                                                                                                         |
| `data-label`           | Texto sin formato                                                                                                     | Solo icono                                           | Texto visible del lanzador y nombre accesible. Escapa `"`, `<`. La interfaz del panel limita a 40 caracteres                                                                            |
| `data-accent`          | `#RGB` o `#RRGGBB`                                                                                                    | Apariencia guardada del sitio                        | Anulación del anfitrión para el lanzador; los valores que no sean hexadecimales se ignoran en el iframe                                                                                 |
| `data-locale`          | `en`, `ko`, `uz` o `ru`                                                                                               | Idioma principal del agente                          | Idioma con el que el agente inicia en esta página anfitriona, elegido entre sus idiomas habilitados                                                                                     |
| `data-theme`           | `light` o `dark`                                                                                                      | Fondo del anfitrión; si no, el del sistema operativo | Se ignoran otros valores                                                                                                                                                                |
| `data-auto-form-error` | `true`                                                                                                                | Desactivado                                          | Activa los eventos de activación por error de formulario; informa del ID del formulario, nunca de los valores de los campos                                                             |
| `data-analytics`       | `off` (también `false`, `0`, `no`)                                                                                    | Activado                                             | Úsalo cuando tu visitante no haya dado su consentimiento para analíticas: el marco del chat no carga analíticas de página ni envía la señal de visualización. El chat sigue funcionando |

El elemento raíz generado también usa `data-maf-open` internamente para saber si el chat está abierto. No es un ajuste de la etiqueta script ni un comando público para abrir el widget. Consulta [Seguimientos](/es/docs/build/follow-ups) para conocer el comportamiento de los activadores.

Sin `data-theme`, el cargador toma una muestra del fondo del sitio anfitrión y, si no, recurre a la preferencia del sistema operativo del visitante. También pasa al marco la familia tipográfica del anfitrión y obtiene la última apariencia del lanzador. Si la solicitud de apariencia falla, el lanzador no se bloquea; conserva el estilo seguro predeterminado. Los cambios en **Pantalla** en el panel actualizan esta consulta sin necesidad de volver a publicar el sitio.

## Comportamiento en ejecución [#comportamiento-en-ejecución]

* Carga el script una sola vez por documento. Repetir el mismo slug es idempotente y sigue generando una única raíz `maf-embed-root-YOUR_SITE_SLUG`.
* Pueden coexistir distintos agentes en un mismo documento. El cargador marca cada script procesado con `data-maf-bootstrapped` para que un respaldo asíncrono inicialice cada etiqueta `data-agent` distinta exactamente una vez.
* El iframe puede precargarse para los activadores de página. Permanece oculto hasta que aparece un activador o el visitante abre el chat; las sesiones que ya usaron un activador mantienen la ruta de apertura diferida. El micrófono, la reproducción automática y la escritura en el portapapeles siguen sujetos al modelo de permisos de iframe del navegador.
* En una aplicación con enrutamiento del lado del cliente, monta el cargador en el diseño de nivel más alto que deba contenerlo para que los cambios de ruta no recarguen la conversación.
* Eliminar solo el elemento script no elimina un lanzador ya creado. Para desmontarlo en una ruta específica, elimina también el elemento `maf-embed-root-...` correspondiente. Vuelve a cargar el script después del desmontaje para montarlo de nuevo.
* El marco y el cargador intercambian mensajes con espacio de nombres sobre ciclo de vida, identidad, activadores y acciones de página. El cargador rechaza los mensajes que no procedan del origen de Make Agent Fast y del slug del sitio actual.

## Verifica la instalación [#verifica-la-instalación]

Prueba la página publicada, no solo la vista previa del editor de un creador de sitios web:

1. Abre la URL desplegada en una ventana privada y confirma que su origen exacto está en la lista de permitidos.
2. Confirma que `https://makeagent.fast/embed.js?v=20261022-open` devuelve `200` en el panel Red.
3. Confirma que existe un único elemento con `data-maf-embed="YOUR_SITE_SLUG"`.
4. Abre el lanzador y confirma que la solicitud del iframe a `/embed/YOUR_SITE_SLUG` se realiza correctamente.
5. Envía una pregunta realista y confirma que aparece en **Conversaciones**.
6. Prueba en una ventana de visualización móvil estrecha y, si está habilitado, el permiso del micrófono.

## Diagnostica un lanzador que no aparece [#diagnostica-un-lanzador-que-no-aparece]

| Síntoma                                     | Causa probable                                                        | Solución                                                                                          |
| ------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| La consola avisa `missing data-agent`       | El atributo del slug no está o se encuentra en otro script            | Pon `data-agent` en la etiqueta de `embed.js`                                                     |
| `embed.js` está bloqueado                   | Una CSP o un gestor de consentimiento rechazó el script               | Permite el origen del script o cárgalo después del consentimiento requerido                       |
| El lanzador aparece pero el marco no carga  | El embed está desactivado o el origen padre no coincide               | Revisa de nuevo **Mostrar en mi sitio web** y **Direcciones de sitio web permitidas** en el panel |
| Funciona en localhost pero no en producción | Solo el origen de desarrollo está en la lista de permitidos           | Añade el origen HTTPS exacto del sitio desplegado                                                 |
| Aparecen dos agentes distintos              | El documento carga dos slugs diferentes                               | Conserva solo el slug del sitio deseado                                                           |
| El chat se abre pero la voz no funciona     | El permiso del navegador o la Permissions Policy bloquea el micrófono | Sigue [Seguridad y CSP](/es/docs/embed/security)                                                  |

## Elige una guía de instalación [#elige-una-guía-de-instalación]

Usa [HTML y JavaScript](/es/docs/embed/html) para una etiqueta script normal. Para React, Vue, SvelteKit, Astro, WordPress, Shopify, Webflow, Framer, Wix, Squarespace o Ghost, elige la guía correspondiente en la barra lateral. Las plataformas que no permiten JavaScript arbitrario, como muchas superficies de Notion y Linktree, pueden enlazar al **Agent link** del agente: una página de chat pública en la dirección propia del agente, que se activa en el último paso de la incorporación (**Pruébalo en tu teléfono**) y en la pestaña **Pantalla** de la página Agente. Otra opción es un sitio web de cliente con el embed.

## Para agentes de programación [#para-agentes-de-programación]

¿Vas a instalarlo en el sitio de un cliente con Claude Code, Cursor o Codex? Copia `skills/embed-agent/SKILL.md` del repositorio de Make Agent Fast en `.cursor/skills/embed-agent/` o `.claude/skills/embed-agent/`. Ese archivo es la receta de instalación (atributos, CSP, ubicación). Esta página sigue siendo la guía para personas.

---

# React y Next.js

Source: /es/docs/embed/react-next.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/embed/overview&#x22;, label: 'Resumen de la integración', icon: &#x22;embed&#x22; },
{ label: &#x22;React&#x22;, icon: &#x22;react&#x22; },
{ href: &#x22;/es/docs/embed/security&#x22;, label: 'Seguridad y CSP', icon: &#x22;shield&#x22; }
]"
/>

## Prepara los orígenes y el alcance [#prepara-los-orígenes-y-el-alcance]

Activa **Mostrarlo en mi sitio web** para el agente (página del agente → **Ponlo en marcha** → **Widget para sitio web**) y añade los orígenes exactos de local, vista previa y producción en **Direcciones de sitio web permitidas**. Decide si el lanzador debe mantenerse en todas las navegaciones del cliente (layout raíz) o existir solo en rutas concretas (layout o componente anidado).

## Next.js App Router [#nextjs-app-router]

Usa `next/script` en un componente que renderice el layout propietario del lanzador. El slug es seguro de exponer; no uses una clave de API ni una variable de entorno secreta.

```tsx
import Script from "next/script";

export function AgentEmbed() {
  return (
    <Script
      id="maf-agent"
      src="https://makeagent.fast/embed.js?v=20261022-open"
      strategy="afterInteractive"
      data-agent="YOUR_SITE_SLUG"
      data-position="right"
      data-label="Ask us"
    />
  );
}
```

Renderiza `<AgentEmbed />` una sola vez en `app/layout.tsx` para un agente en todo el sitio, o en un layout anidado para un grupo de rutas. No renderices una copia independiente desde cada componente de página. `afterInteractive` evita el acceso al DOM desde el servidor y no bloquea el análisis inicial del HTML.

En el Pages Router de Next.js, renderiza el mismo componente una sola vez desde `pages/_app.tsx` para que funcione en todo el sitio. Renderizarlo desde una página individual solo es apropiado cuando salir de esa página deba eliminar el agente; en ese caso usa el patrón explícito de efecto/limpieza que se muestra más abajo, porque un script externo ya cargado ha creado DOM fuera del árbol de React.

## React sin Next.js [#react-sin-nextjs]

Crea el script dentro de un efecto. Un ID de script estable evita la inserción duplicada con el Strict Mode de desarrollo. Si el componente está limitado a una ruta, la limpieza debe eliminar tanto el script como la raíz creada por el loader.

```tsx
import { useEffect } from "react";

const slug = "YOUR_SITE_SLUG";

export function AgentEmbed() {
  useEffect(() => {
    if (document.getElementById(`maf-embed-root-${slug}`)) return;

    const script = document.createElement("script");
    script.id = "maf-agent";
    script.src = "https://makeagent.fast/embed.js?v=20261022-open";
    script.dataset.agent = slug;
    script.dataset.position = "right";
    script.async = true;
    document.body.appendChild(script);

    return () => {
      script.remove();
      document.getElementById(`maf-embed-root-${slug}`)?.remove();
    };
  }, []);

  return null;
}
```

Para un lanzador en todo el sitio, monta este componente por encima del router y omite el desmontaje según la ruta. Conservar la raíz mantiene el iframe y la conversación durante la navegación.

## Configuración del entorno [#configuración-del-entorno]

Una variable pública de tiempo de compilación puede contener el **slug**, ya que no es secreto. Valídalo antes de renderizar y mantén las claves de API de MAF y las credenciales de proveedores reales solo en el servidor. Si falta el slug, el loader muestra una advertencia y termina en lugar de crear un lanzador.

Si tu aplicación sirve a distintos clientes (tenants) desde una misma compilación de React, no cambies `data-agent` en un script que ya se ha ejecutado. Asigna al tenant actual un único slug estable, elimina la raíz del slug anterior durante un cambio de tenant autenticado y después monta un script nuevo. Nunca permitas que un parámetro de consulta no confiable elija un slug de otro tenant.

## Verifica la hidratación y la navegación [#verifica-la-hidratación-y-la-navegación]

1. Carga directamente una ruta pública y confirma que hay un solo lanzador.
2. Navega en el cliente por las rutas que deben conservarlo.
3. En una instalación anidada o limitada a rutas, sal de la ruta y confirma que desaparecen tanto el script como la raíz; luego vuelve y confirma que aparece un único lanzador nuevo.
4. Inspecciona Network/CSP y prueba un mensaje real.
5. Ejecuta la compilación de producción; el Strict Mode de desarrollo por sí solo no refleja el comportamiento final.

## Solución de problemas [#solución-de-problemas]

| Síntoma                                              | Solución                                                                               |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `document is not defined`                            | El código del DOM se ejecutó durante el SSR; muévelo a `useEffect` o usa `next/script` |
| Aparecen dos lanzadores/agentes                      | Hay varios slugs o componentes montados; mantén un único layout propietario            |
| El lanzador permanece tras salir de la ruta          | Elimina `maf-embed-root-SLUG` en la limpieza, no solo el script                        |
| El lanzador desaparece en cada navegación            | Móntalo más arriba en el árbol del layout o del router                                 |
| Funciona en local pero no en vista previa/producción | Añade a la lista de permitidos el origen exacto de cada despliegue                     |

Actualmente no se publica ningún adaptador de React/Next en npm; estos ejemplos usan el loader público compatible, independiente de la API REST.

---

# Seguridad y CSP

Source: /es/docs/embed/security.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/embed/overview&#x22;, label: 'Resumen de la incrustación', icon: &#x22;embed&#x22; },
{ href: &#x22;/es/docs/embed/security&#x22;, label: 'Seguridad y CSP', icon: &#x22;shield&#x22; },
{ href: &#x22;/es/docs/build/appearance&#x22;, label: 'Aspecto', icon: &#x22;spark&#x22; }
]"
/>

## Lista de orígenes permitidos [#lista-de-orígenes-permitidos]

La incrustación falla por defecto (fail closed) a menos que esté habilitada y el origen padre exacto del navegador esté permitido. Un origen es `scheme://hostname[:port]`; las rutas y las cadenas de consulta no forman parte de él.

| Página anfitriona                       | Valor de la lista de permitidos    |
| --------------------------------------- | ---------------------------------- |
| `https://example.com/pricing`           | `https://example.com`              |
| `https://www.example.com/help`          | `https://www.example.com`          |
| `https://preview.example.com:8443/demo` | `https://preview.example.com:8443` |
| `http://localhost:3000`                 | `http://localhost:3000`            |

Añade por separado los orígenes de producción, de vista previa y locales. No añadas un comodín para resolver un error de instalación: de lo contrario, cualquiera que copie un slug público podría incrustar el agente y consumir los créditos del sitio.

## Content Security Policy [#content-security-policy]

El cargador necesita permiso de script, el widget necesita permiso de frame y la solicitud de aspecto del cargador puede necesitar permiso de conexión. Combina estas fuentes con las directivas existentes del sitio anfitrión; no sustituyas una política consolidada por este ejemplo mínimo.

```http
Content-Security-Policy:
  default-src 'self';
  script-src 'self' https://makeagent.fast;
  frame-src https://makeagent.fast;
  connect-src 'self' https://makeagent.fast;
```

Si el sitio usa `script-src-elem`, añade también `https://makeagent.fast` ahí. El cargador externo no requiere `unsafe-inline`, pero el framework del propio sitio anfitrión puede tener requisitos independientes de nonce o hash. Una política en modo solo informe es útil durante las pruebas:

```http
Content-Security-Policy-Report-Only:
  script-src 'self' https://makeagent.fast;
  frame-src https://makeagent.fast;
  connect-src 'self' https://makeagent.fast;
```

Cuando la consola del navegador informe de una infracción de CSP, modifica la directiva indicada (no `default-src` de forma amplia) y vuelve a probar la página pública.

## Micrófono y permisos del navegador [#micrófono-y-permisos-del-navegador]

El cargador crea el iframe con `allow="microphone; autoplay; clipboard-write"`. Una Permissions Policy más estricta a nivel del sitio anfitrión puede anular ese permiso. Si la voz está habilitada, permite el origen del frame de Make Agent Fast en la respuesta del sitio anfitrión:

```http
Permissions-Policy: microphone=(self "https://makeagent.fast")
```

El visitante también debe conceder acceso al micrófono en el navegador. Prueba desde HTTPS; los navegadores normalmente restringen el acceso al micrófono en orígenes públicos no seguros. El chat de texto no requiere permiso de micrófono.

## Límite de mensajes y frames [#límite-de-mensajes-y-frames]

El cargador solo acepta `maf:ready`, `maf:open`, `maf:close` y los mensajes del ciclo de vida del tema asociados al slug del sitio actual. Los mensajes entrantes del frame se comprueban contra `https://makeagent.fast`. No copies el cargador en tu propio bundle ni elimines esta validación de origen.

El código de la página anfitriona no debe intentar acceder al DOM del iframe. El frame es de origen cruzado por diseño, y la superficie de integración compatible es el cargador, sus atributos `data-*` documentados y los métodos de identidad que se describen más abajo.

## Secretos e identidad del visitante [#secretos-e-identidad-del-visitante]

El slug del sitio y la URL del cargador son públicos. Todo lo demás debe quedar fuera del código fuente de la página:

* Nunca añadas al snippet una clave de API de MAF, un token de OAuth, una clave de proveedor de IA, un token de conector ni un secreto de webhook.
* Nunca incluyas un secreto en un bundle de JavaScript ni lo expongas mediante `NEXT_PUBLIC_*`, `VITE_*` u otras variables de entorno del navegador similares.
* Usa una integración de API del lado del servidor cuando tu aplicación deba crear sitios, actualizar agentes u obtener datos privados del espacio de trabajo.
* No pongas direcciones de correo, ID de cuenta ni otros datos del visitante en `data-label`, `data-locale` ni en parámetros de consulta.

## Identificar a los clientes con sesión iniciada [#identificar-a-los-clientes-con-sesión-iniciada]

En **Agente → Acciones → Clientes con sesión iniciada**, crea un secreto y cópialo cuando se muestre. Guárdalo únicamente en tu servidor como `MAF_SECRET_KEY`; nunca lo pongas en código del navegador, en variables de entorno públicas ni en un repositorio. Este secreto del agente es independiente de la clave de API del espacio de trabajo. La rotación invalida los tokens antiguos y cambia la clave de firma de [Lookups](/es/docs/build/lookups); eliminarlo desactiva la identidad verificada del cliente y las consultas hasta que se configure de nuevo un secreto.

Usa la URL actualizada del cargador `https://makeagent.fast/embed.js?v=20261022-open` en tu snippet existente. Las URL con versiones anteriores pueden permanecer en caché durante un año y no incluyen este SDK. Mantén la lista de orígenes permitidos y las protecciones de CSP.

Tu servidor autenticado debe emitir el token usando el cliente de su propia sesión. Nunca aceptes un ID de cliente arbitrario del navegador como la identidad que se va a firmar. Este helper se ejecuta **únicamente en el servidor**:

```js
import { createHmac } from "node:crypto";

export function signCustomerIdentity(customer) {
  const secret = process.env.MAF_SECRET_KEY;
  if (!secret) throw new Error("MAF_SECRET_KEY is required");
  const encode = (value) => Buffer.from(JSON.stringify(value)).toString("base64url");
  const now = Math.floor(Date.now() / 1000);
  const header = encode({ alg: "HS256", typ: "JWT" });
  const payload = encode({
    sub: customer.id,
    email: customer.email,
    name: customer.name,
    iat: now,
    exp: now + 3600,
  });
  const body = `${header}.${payload}`;
  const signature = createHmac("sha256", secret).update(body).digest("base64url");
  return `${body}.${signature}`;
}
```

Exige el encabezado `alg: "HS256"` y `typ: "JWT"`. `sub` es una cadena estable no vacía de hasta 128 caracteres; `exp` es una marca de tiempo Unix entera en segundos, en el futuro y como máximo 24 horas por delante. `iat` opcional es un entero; `email` opcional debe ser válido y tener como máximo 160 caracteres; `name` opcional tiene como máximo 120. El token completo debe caber en 2048 caracteres. Omite los claims opcionales que no necesites. Los payloads de JWT están firmados, no cifrados.

Devuelve únicamente el token a esa sesión autenticada del navegador a través de HTTPS, con `Cache-Control: no-store`. No lo registres en logs, no lo añadas a las URL ni lo guardes en localStorage. Una vez cargado `embed.js`, pasa ese token de la respuesta al widget:

```js
window.MakeAgentFast.identify(token);
```

Para la inicialización antes de que se ejecute el cargador, define en su lugar `window.MakeAgentFastSettings = { identityToken: token }` en el arranque de tu aplicación. El cargador conserva el token más reciente en memoria y lo reenvía cuando el frame está listo. Actualiza el token desde tu servidor autenticado antes de que caduque y vuelve a llamar a `identify`. Cada solicitud de chat lo incluye; las solicitudes de conversación usan `x-maf-identity`. Una identidad verificada del sitio anfitrión nunca depende de una cookie `af_xid`.

Cuando tu aplicación cierre sesión, llama a esto antes de mostrar el chat de otra cuenta y borra cualquier token de arranque que tu aplicación haya conservado:

```js
window.MakeAgentFast.logout();
```

Esto restablece la identidad del widget y la caché local de conversaciones; no cierra la sesión del cliente en tu propia aplicación ni revoca un token copiado. El `sub` de un cliente distinto también borra la caché del widget. Los tokens no válidos, caducados o de otro agente no pueden acceder al historial de ese cliente con sesión iniciada y recurren a la ruta ordinaria de visitante. Usa caducidades cortas y mantén separado el secreto de cada agente. El ensayo del propietario ignora los tokens de identidad; comprueba el aislamiento en la incrustación real usando dos cuentas de prueba distintas.

## Consentimiento, privacidad y retención [#consentimiento-privacidad-y-retención]

Clasifica la incrustación según tu política de privacidad y consentimiento. Si tu gestor de consentimiento bloquea los scripts de terceros no esenciales, carga `embed.js` solo después del consentimiento correspondiente. Hasta entonces, muestra un enlace normal o un marcador de posición deshabilitado en lugar de eludir el gestor.

Informa a los visitantes cuando la experiencia use IA, grabación de micrófono, captura de leads, analíticas o un proveedor de mensajería externo, según lo exijan tu política y la legislación aplicable. Confirma el flujo de retención y eliminación de conversaciones de tu sitio antes del lanzamiento; desconectar o eliminar la incrustación no borra por sí solo las conversaciones existentes.

## Lista de comprobación de seguridad para el lanzamiento [#lista-de-comprobación-de-seguridad-para-el-lanzamiento]

* El sitio web del cliente está desplegado y su agente incrustado está habilitado y probado.
* Solo están en la lista de permitidos los orígenes padre exactos y previstos.
* La CSP del sitio anfitrión permite el script, el frame y la solicitud de aspecto sin comodines amplios.
* El micrófono solo se permite si la voz está habilitada y se ha probado a través de HTTPS.
* Ninguna credencial ni valor privado del visitante aparece en el HTML, en la salida del bundle ni en los logs del navegador.
* El comportamiento del gestor de consentimiento se prueba antes y después del consentimiento.
* Un snippet copiado falla en un origen que no está en la lista de permitidos.

---

# Shopify

Source: /es/docs/embed/shopify.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/embed/overview&#x22;, label: 'Resumen de la incrustación', icon: &#x22;embed&#x22; },
{ label: &#x22;Shopify&#x22;, icon: &#x22;shopify&#x22; },
{ href: &#x22;/es/docs/embed/security&#x22;, label: 'Seguridad y CSP', icon: &#x22;shield&#x22; }
]"
/>

## Disponibilidad de la extensión de tema [#disponibilidad-de-la-extensión-de-tema]

El código fuente de la extensión de tema de app se encuentra en `integrations/shopify`. Es una plantilla de desarrollo, no una aplicación pública de la Shopify App Store. Una cuenta de Partner autorizada debe incluirla en un contenedor de app, desplegarla y completar la revisión de Shopify antes de que los comerciantes puedan instalarla desde la App Store.

## Custom Liquid [#custom-liquid]

En **Online Store → Themes → Customize**, añade un bloque de Custom Liquid donde sea compatible, o edita `theme.liquid` y coloca el script antes de `</body>`.

```liquid
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Añade a la lista de orígenes permitidos el origen canónico de tu tienda. Los nombres de host de la vista previa pueden diferir del dominio `myshopify.com` en producción o del nombre de host propio de la tienda, y deben añadirse por separado para hacer pruebas.

## Cambios de tema [#cambios-de-tema]

Vuelve a comprobar la incrustación de la app después de publicar un tema nuevo. Prueba el lanzador junto a los carritos laterales, los banners de consentimiento y la navegación móvil para que los elementos fijos no se superpongan.

---

# Squarespace

Source: /es/docs/embed/squarespace.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/embed/overview&#x22;, label: 'Resumen de la integración', icon: &#x22;embed&#x22; },
{ label: &#x22;Squarespace&#x22;, icon: &#x22;squarespace&#x22; },
{ href: &#x22;/es/docs/embed/security&#x22;, label: 'Seguridad y CSP', icon: &#x22;shield&#x22; }
]"
/>

Para un lanzador en todo el sitio, pega el fragmento en **Ajustes → Avanzado → Inyección de código → Pie de página** si tu plan de Squarespace lo admite.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Para páginas concretas, usa un bloque de código compatible o la inyección de código específica de página. Prueba el resultado después de guardar y en el dominio público; el modo de edición puede impedir que se ejecuten los scripts personalizados.

Si la configuración de consentimiento de cookies bloquea los scripts de terceros, clasifica y carga la integración según tu política de consentimiento.

---

# SvelteKit

Source: /es/docs/embed/sveltekit.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/embed/overview&#x22;, label: 'Resumen de la integración', icon: &#x22;embed&#x22; },
{ label: &#x22;SvelteKit&#x22;, icon: &#x22;svelte&#x22; },
{ href: &#x22;/es/docs/embed/security&#x22;, label: 'Seguridad y CSP', icon: &#x22;shield&#x22; }
]"
/>

## Prepara el origen [#prepara-el-origen]

Activa **Mostrarlo en mi sitio web** para el agente (página del agente → **Ponerlo en marcha** → **Widget para sitio web**) y añade cada origen exacto de SvelteKit de desarrollo, vista previa y producción en **Direcciones de sitio web permitidas**. Usa un layout raíz para un lanzador en todo el sitio, o un layout o componente de página anidado para rutas concretas.

## Crea el componente [#crea-el-componente]

`onMount` se ejecuta solo en el navegador. Devuelve una función de limpieza cuando el layout o componente que lo contiene pueda desmontarse.

```svelte
<script lang="ts">
  import { onMount } from "svelte";

  const slug = "YOUR_SITE_SLUG";

  onMount(() => {
    if (document.getElementById(`maf-embed-root-${slug}`)) return;

    const script = document.createElement("script");
    script.id = "maf-agent";
    script.src = "https://makeagent.fast/embed.js?v=20261022-open";
    script.dataset.agent = slug;
    script.dataset.position = "right";
    script.async = true;
    document.body.appendChild(script);

    return () => {
      script.remove();
      document.getElementById(`maf-embed-root-${slug}`)?.remove();
    };
  });
</script>
```

Monta el componente una sola vez desde `src/routes/+layout.svelte` para toda la aplicación. Para un grupo de rutas, colócalo en el `+layout.svelte` de ese grupo; la limpieza elimina el lanzador cuando el visitante sale del grupo.

## Usa la configuración de forma segura [#usa-la-configuración-de-forma-segura]

El slug público del sitio puede ser un valor de entorno público de SvelteKit porque no es una credencial. No uses `$env/static/public` ni código del navegador para las claves de API de MAF, las claves de proveedores de IA ni los secretos de los conectores. Guárdalos en módulos o rutas exclusivos del servidor.

## Conserva o restablece el estado de la conversación [#conserva-o-restablece-el-estado-de-la-conversación]

Mantener el componente en el layout raíz conserva el mismo iframe entre navegaciones del lado del cliente. La limpieza por ruta descarta deliberadamente ese iframe y su estado actual en la página. Elige un único comportamiento en lugar de volver a montar el componente en cada página.

## Verifica la compilación de producción [#verifica-la-compilación-de-producción]

1. Ejecuta el adaptador o la compilación de producción de SvelteKit.
2. Carga directamente la ruta pública y confirma que hay un único lanzador/raíz.
3. Navega hacia dentro y hacia fuera del layout que lo contiene.
4. Inspecciona la red/CSP y el origen exacto del sitio padre.
5. Prueba un mensaje real, una ventana de visualización estrecha y el micrófono, si está activado.

## Solución de problemas [#solución-de-problemas]

| Síntoma                                                            | Solución                                                                                             |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| Error de `document` durante el SSR                                 | Mantén todo el código del cargador dentro de `onMount`                                               |
| El lanzador persiste después de salir del layout                   | Devuelve la función de limpieza y elimina la raíz generada                                           |
| La conversación se restablece en cada página                       | Móntalo en un `+layout.svelte` padre persistente                                                     |
| La protección contra lanzadores duplicados impide un nuevo montaje | Asegúrate de que la limpieza anterior haya eliminado la raíz antigua antes de añadir un nuevo script |
| Solo falla en producción                                           | Añade a la lista de permitidos el origen HTTPS final e inspecciona las cabeceras CSP del adaptador   |

Actualmente no se publica ningún adaptador de SvelteKit en npm; el script alojado es la superficie de integración compatible.

---

# Tilda

Source: /es/docs/embed/tilda.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/embed/overview&#x22;, label: 'Resumen de la integración', icon: &#x22;embed&#x22; },
{ label: &#x22;Tilda&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/es/docs/embed/security&#x22;, label: 'Seguridad y CSP', icon: &#x22;shield&#x22; }
]"
/>

Tilda publica una exportación estática, por lo que el lanzador se instala con la función de código personalizado de Tilda. No existe ninguna aplicación de Make Agent Fast en un catálogo de Tilda. Los nombres de los menús que aparecen aquí corresponden a 2026-09; si alguna etiqueta ha cambiado de lugar, busca el ajuste por lo que hace y no por su ruta exacta.

## Añade el cargador [#añade-el-cargador]

1. En el panel de Make Agent Fast, abre **Ponlo en vivo** → **Widget para sitio web** en la página del agente, activa **Mostrarlo en mi sitio web** y añade en **Direcciones de sitio web permitidas** todos los orígenes desde los que Tilda sirve tu sitio: tu dominio personalizado y, mientras haces pruebas, la dirección de vista previa `tilda.ws` del proyecto.
2. Abre los ajustes del sitio del proyecto y busca la zona de código personalizado o inyección de HTML: los campos que insertan código en el `<head>` de todas las páginas o justo antes de la etiqueta de cierre del body. La disponibilidad depende de tu plan de Tilda.
3. Pega el fragmento generado en el campo del head. El cargador es `async`, así que funciona tanto en el head como al final del body.
4. Guarda y vuelve a publicar las páginas que deben mostrar el lanzador. Tilda sirve una exportación estática, por lo que el código global solo llega a los visitantes después de volver a publicar.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Si no encuentras ese ajuste, pega el fragmento en el bloque de pie de página de tu tema: el bloque de código HTML de Tilda añade el lanzador únicamente a la página que lo contiene, que además es la forma de limitar el agente a una sola landing page.

## Verifica [#verifica]

1. Abre la URL publicada en una ventana privada, no en el editor de Tilda. Los modos de editor y de vista previa pueden suprimir los scripts inyectados.
2. Confirma que el origen de la barra de direcciones es el que añadiste a la lista de permitidos, incluido `www` si el dominio redirige a esa versión.
3. Confirma que `embed.js` devuelve `200` en el panel Network y que existe un único elemento `data-maf-embed="YOUR_SITE_SLUG"`.
4. Haz una pregunta realista y confirma que el mensaje aparece en **Conversaciones**.

## Solución de problemas [#solución-de-problemas]

| Síntoma                                                          | Causa probable                                                                         | Solución                                                                            |
| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| El lanzador aparece en el editor, pero no en la página publicada | Las páginas no se volvieron a publicar tras guardar el código global                   | Vuelve a publicar todas las páginas que deban incluir el lanzador                   |
| El lanzador carga, pero el marco del chat no se abre             | El origen publicado no está en la lista de permitidos, o la inserción está desactivada | Añade el origen publicado exacto y vuelve a comprobar **Mostrarlo en mi sitio web** |
| El fragmento aparece solo en una página                          | Se añadió mediante un bloque HTML a nivel de página                                    | Muévelo al campo de inyección global del head                                       |

Las opciones de consentimiento de cookies y de velocidad de página de Tilda pueden retrasar la carga de scripts de terceros. Si el control de consentimiento está activado, carga el widget en la categoría que tu política le asigne, y consulta [Seguridad y CSP](/es/docs/embed/security) para ver los orígenes que debes permitir.

---

# Vue y Nuxt

Source: /es/docs/embed/vue-nuxt.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/embed/overview&#x22;, label: 'Resumen de la incrustación', icon: &#x22;embed&#x22; },
{ label: &#x22;Vue&#x22;, icon: &#x22;vue&#x22; },
{ href: &#x22;/es/docs/embed/security&#x22;, label: 'Seguridad y CSP', icon: &#x22;shield&#x22; }
]"
/>

## Prepara la incrustación [#prepara-la-incrustación]

Activa **Mostrarlo en mi sitio web** para el agente (página del agente → **Ponlo en marcha** → **Widget para sitio web**) y añade el origen exacto de cada despliegue local, de vista previa y de producción en **Direcciones de sitio web permitidas**. Decide si el agente pertenece a toda la aplicación o solo a determinados componentes de ruta.

## Plugin de Nuxt para todo el sitio [#plugin-de-nuxt-para-todo-el-sitio]

Crea un plugin `.client.ts` para que no se ejecute código del DOM durante el renderizado en el servidor. Nuxt lo carga una sola vez en el navegador, lo que mantiene estables el lanzador y la conversación durante la navegación en el cliente.

```ts
// plugins/make-agent-fast.client.ts
const slug = "YOUR_SITE_SLUG";

export default defineNuxtPlugin(() => {
  if (document.getElementById(`maf-embed-root-${slug}`)) return;

  const script = document.createElement("script");
  script.id = "maf-agent";
  script.src = "https://makeagent.fast/embed.js?v=20261022-open";
  script.dataset.agent = slug;
  script.dataset.position = "right";
  script.dataset.label = "Ask us";
  script.async = true;
  document.body.appendChild(script);
});
```

No pongas ningún secreto en `runtimeConfig.public`; en el navegador solo deben ir el slug público del sitio y los ajustes visuales. Las claves reales de la API de MAF y de los proveedores se quedan en la configuración privada del entorno de ejecución del servidor.

El plugin para todo el sitio no incluye limpieza al desmontar de forma intencionada: pertenece al ciclo de vida de la aplicación Nuxt. Durante el reemplazo de módulos en caliente (HMR) en desarrollo, una raíz anterior puede permanecer hasta que se haga una recarga completa; la comprobación de la raíz evita que aparezca un segundo lanzador. Verifica el comportamiento final con una compilación de producción limpia, en lugar de editar el plugin repetidamente en una misma pestaña de larga duración.

## Componente de Vue limitado a rutas [#componente-de-vue-limitado-a-rutas]

Para rutas concretas, monta el loader en `onMounted` y elimina tanto el script como la raíz generada en `onBeforeUnmount`.

```vue
<script setup lang="ts">
import { onBeforeUnmount, onMounted } from "vue";

const slug = "YOUR_SITE_SLUG";
let script: HTMLScriptElement | null = null;

onMounted(() => {
  if (document.getElementById(`maf-embed-root-${slug}`)) return;
  script = document.createElement("script");
  script.id = "maf-agent";
  script.src = "https://makeagent.fast/embed.js?v=20261022-open";
  script.dataset.agent = slug;
  script.async = true;
  document.body.appendChild(script);
});

onBeforeUnmount(() => {
  script?.remove();
  document.getElementById(`maf-embed-root-${slug}`)?.remove();
});
</script>
```

Usa un único componente responsable. Varios componentes con slugs distintos crean varios agentes a propósito, algo que rara vez es deseable.

Si una aplicación Vue cambia de tenant autenticado sin recargar la página por completo, trátalo como un desmontaje y remontaje explícitos. Elimina la raíz del slug anterior, valida el slug público del nuevo tenant a partir de un estado de la aplicación de confianza y luego añade un nuevo script. Cambiar `script.dataset.agent` después de que el loader se haya ejecutado no redirige el iframe existente.

Las cabeceras de seguridad del host se siguen aplicando a la salida de Nuxt/Vue. Añade el origen del loader y del frame a la CSP y permite el micrófono solo cuando la voz esté activada; un plugin exclusivo del cliente no puede anular una política del navegador definida a nivel de respuesta.

## Verifica el SSR y el enrutamiento [#verifica-el-ssr-y-el-enrutamiento]

1. Ejecuta la compilación de producción de Nuxt/Vue y confirma que no aparece el error `document is not defined`.
2. Carga directamente una ruta que tenga la incrustación y confirma que hay una sola raíz.
3. Navega en el cliente y comprueba el comportamiento para todo el sitio frente al limitado a rutas.
4. Inspecciona `embed.js`, el iframe, la CSP y el origen exacto.
5. Envía un mensaje y prueba el comportamiento en móvil y con el micrófono.

## Solución de problemas [#solución-de-problemas]

| Síntoma                                   | Solución                                                                                         |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------ |
| El SSR falla                              | Cambia el nombre del plugin de Nuxt a `.client.ts` o mantén el trabajo con el DOM en `onMounted` |
| El lanzador permanece al salir de la ruta | Elimina la raíz específica del slug en `onBeforeUnmount`                                         |
| El lanzador se reinicia en cada ruta      | Usa el plugin o layout de cliente para todo el sitio en lugar de un componente de página         |
| Falla el dominio de vista previa          | Añade ese origen HTTPS exacto por separado                                                       |
| El script se inserta dos veces            | Usa un único responsable estable y una comprobación de raíz/ID                                   |

Actualmente no se publica ningún adaptador de npm para Vue/Nuxt; esta guía usa directamente el loader alojado compatible.

---

# Webflow

Source: /es/docs/embed/webflow.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/embed/overview&#x22;, label: 'Resumen de la incrustación', icon: &#x22;embed&#x22; },
{ label: &#x22;Webflow&#x22;, icon: &#x22;webflow&#x22; },
{ href: &#x22;/es/docs/embed/security&#x22;, label: 'Seguridad y CSP', icon: &#x22;shield&#x22; }
]"
/>

## Disponibilidad [#disponibilidad]

La integración compatible es mediante código personalizado. Hoy no existe una app pública de Make Agent Fast en el Webflow Marketplace. La carpeta `integrations/webflow` del repositorio contiene el mismo fragmento para el pie de página que se muestra más abajo, no una aplicación nativa de Webflow.

## Código personalizado [#código-personalizado]

Añade el script generado en **Site settings → Custom code → Footer code** y publica el sitio.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Es posible que el código personalizado no se ejecute en la vista previa del Webflow Designer. Prueba los dominios publicados de staging y de producción, y añade a la lista de permitidos cada origen que utilices.

---

# Wix

Source: /es/docs/embed/wix.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/embed/overview&#x22;, label: 'Resumen del embed', icon: &#x22;embed&#x22; },
{ label: &#x22;Wix&#x22;, icon: &#x22;wix&#x22; },
{ href: &#x22;/es/docs/embed/security&#x22;, label: 'Seguridad y CSP', icon: &#x22;shield&#x22; }
]"
/>

## Disponibilidad del elemento personalizado [#disponibilidad-del-elemento-personalizado]

Usa el elemento personalizado de `integrations/wix/make-agent-fast.js` o la superficie de código personalizado aprobada de Wix para el final del `body`. Esta fuente no es una aplicación pública del Wix App Market. Aquí solo aparecerá una URL de listado cuando una revisión externa apruebe y publique una.

## Código personalizado [#código-personalizado]

En la configuración del sitio, añade el loader generado como código personalizado al final del `body` y aplícalo a las páginas que quieras.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Wix puede servir los sitios de vista previa y en vivo desde hosts distintos. Añade solo los hosts que necesites en **Direcciones de sitios web permitidas** y vuelve a publicar después de cada cambio.

---

# WordPress

Source: /es/docs/embed/wordpress.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/embed/overview&#x22;, label: 'Resumen de la incrustación', icon: &#x22;embed&#x22; },
{ label: &#x22;WordPress&#x22;, icon: &#x22;wordpress&#x22; },
{ href: &#x22;/es/docs/embed/security&#x22;, label: 'Seguridad y CSP', icon: &#x22;shield&#x22; }
]"
/>

## Código fuente del plugin para instalación manual [#código-fuente-del-plugin-para-instalación-manual]

El código fuente del plugin que se puede instalar manualmente se encuentra en `integrations/wordpress/make-agent-fast`. No está incluido en el directorio de WordPress.org. Comprime esa carpeta en un archivo ZIP, súbela desde **Plugins → Añadir nuevo → Subir plugin** y luego configura el slug publicado en **Ajustes → Make Agent Fast**. Aquí aparecerá un enlace al directorio solo cuando una revisión externa lo apruebe.

## HTML personalizado [#html-personalizado]

Si lo instalas manualmente, añade el script estándar mediante un tema hijo, una herramienta de confianza para insertar scripts en el encabezado o el pie de página, o un bloque de HTML personalizado que permita tu plan de WordPress.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

Añade a la lista de orígenes permitidos del panel tanto el origen de producción como cualquier origen de preproducción independiente. Vacía las cachés de la página y de la CDN después de modificar el fragmento de código.

<Callout title="Evita editar un tema padre">
  Una actualización del tema padre puede sobrescribir las ediciones directas. Usa el plugin manual o un tema hijo para lograr una instalación duradera.
</Callout>

---

# Conceptos clave

Source: /es/docs/getting-started/concepts.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;site&#x22;, title: &#x22;Sitio&#x22;, description: &#x22;La unidad del espacio de trabajo: agente, apariencia del widget, conocimiento, código de inserción, Agent link y puntos de entrada de mensajería. El slug es el id de inserción.&#x22; },
{ icon: &#x22;chat&#x22;, title: &#x22;Agente&#x22;, description: &#x22;Identidad, instrucciones, idiomas y la personalidad de voz y texto con la que se encuentran los visitantes.&#x22; },
{ icon: &#x22;book&#x22;, title: &#x22;Conocimiento&#x22;, description: &#x22;URL, archivos, notas, preguntas frecuentes y productos en los que se basan las respuestas.&#x22; },
{ icon: &#x22;connectors&#x22;, title: &#x22;Canales&#x22;, description: &#x22;Códigos de inserción y conectores de mensajería que llevan el mismo agente a otros lugares.&#x22; },
{ icon: &#x22;layers&#x22;, title: &#x22;Créditos&#x22;, description: &#x22;Unidades medidas para el uso de modelos, voz y plataforma según tu plan.&#x22; }
]"
/>

## Espacio de trabajo [#espacio-de-trabajo]

Tu cuenta es el límite del espacio de trabajo para los sitios, la facturación, las credenciales de API y la gestión del equipo. El acceso a un espacio de trabajo nunca da acceso a otro.

## Sitio [#sitio]

Un sitio es la unidad del espacio de trabajo. Contiene su agente, la configuración de apariencia del widget, el conocimiento, los conectores, las analíticas y las conversaciones. Un plan puede limitar cuántos sitios puedes mantener activos. No se ofrecen dominios personalizados. El slug público es el id de inserción (`data-agent`) y la dirección de la página de chat del **Agent link** del agente; no es un dominio que tú configures.

## Agente [#agente]

El agente es el comportamiento conversacional asociado a un sitio. Su personalidad y sus instrucciones determinan cómo habla; su conocimiento determina en qué datos puede basar sus respuestas.

## Conocimiento [#conocimiento]

Las fuentes de conocimiento son material indexado, como notas, URL, archivos, preguntas frecuentes y productos. Respaldan las respuestas, pero no sustituyen las instrucciones de comportamiento. Actualiza la fuente cuando cambie un dato.

## Canal [#canal]

Un canal es el lugar donde un visitante habla con el agente: un widget insertado en tu sitio web actual, páginas de demostración alojadas que ya no se usan, voz, Telegram, WhatsApp, Messenger, Instagram, Discord o KakaoTalk. Las funciones varían según el canal.

## Créditos y derechos del plan [#créditos-y-derechos-del-plan]

Las operaciones de IA consumen créditos. Los minutos de voz en directo, el número de sitios y los controles de marca tienen derechos del plan independientes. Las solicitudes a la API que desencadenan trabajo de IA usan los mismos límites de cuenta subyacentes.

## Estado de publicación [#estado-de-publicación]

Al lanzar desde una URL se crea un borrador sin publicar. **Mostrarlo en mi sitio web** en **Ponlo donde están tus clientes** (o en la página del agente) activa el código de inserción en tu sitio web actual; **Comprobar mi sitio** confirma que el código realmente está ahí. Los agentes nuevos no tienen una página de marketing alojada. Las pruebas del propietario nunca se publican.

La **activación** es la primera conversación de un visitante o el primer lead capturado, no una prueba del propietario.

Los cambios de **apariencia** (y la insignia de marca) se guardan automáticamente y actualizan el código de inserción en vivo sin necesidad de volver a publicar. Las instrucciones también se guardan automáticamente; el conocimiento se aplica una vez que se indexa una fuente. El comportamiento de los conectores y del código de inserción usa el estado actual publicado o configurado del agente, como se describe en cada guía de funciones.

---

# Recorrido por el panel

Source: /es/docs/getting-started/dashboard.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;layers&#x22;, title: &#x22;Inicio del espacio de trabajo&#x22;, description: &#x22;Lista de sitios, estado del plan y punto de entrada para nuevos proyectos.&#x22; },
{ icon: &#x22;build&#x22;, title: &#x22;Controles del agente&#x22;, description: &#x22;Resumen de lanzamiento, agente, apariencia y ajustes de instalación de un agente.&#x22; },
{ icon: &#x22;chart&#x22;, title: &#x22;Herramientas de operación&#x22;, description: &#x22;Bandeja de entrada, analíticas, difusiones, monetización y uso.&#x22; },
{ icon: &#x22;code&#x22;, title: &#x22;Ajustes para desarrolladores&#x22;, description: &#x22;Claves de API, webhooks, aplicaciones OAuth y credenciales de integración.&#x22; }
]"
/>

El panel está organizado por sitios. Usa el selector de sitios antes de cambiar contenido, credenciales o ajustes operativos. Al pegar la URL de un sitio web, el primer borrador se crea en la pantalla de generación, no en esta lista de inicio; consulta [Crear un agente](/es/docs/build/create-agent).

## Agente [#agente]

**Agente** se abre en el resumen de lanzamiento (qué se ha revisado, dónde está instalado, si algún cliente ha hablado con él y cuándo termina la prueba), con el widget en vivo a su lado. Sus pestañas son **Resumen** (instrucciones, estado del conocimiento, verificación de respuestas y visibilidad en el sitio web), **Apariencia** (aspecto del widget; los cambios se guardan automáticamente y actualizan el código incrustado en vivo), **Voz** y **Acciones**. El menú **Publicar** contiene el código de instalación del **Widget para sitio web** y enlaces a cada canal de mensajería. **Conocimiento** reúne todo lo que el agente usa para responder. **Canales** conecta los canales de mensajería. Una breve lista de **Primeros pasos** permanece hasta la primera conversación con un cliente.

## Sitio [#sitio]

No hay una página de Incrustación independiente: el código de instalación y las **Direcciones web permitidas** de un sitio web existente están en **Agente → Publicar → Widget para sitio web**. El interruptor del **Enlace del agente** está en la pestaña **Apariencia**. No existe ninguna función de creación de sitios mediante chat ni de generación de sitios. Las páginas alojadas que pudieran quedar de antes no forman parte del producto de creación.

## Actividad [#actividad]

**Conversaciones** reúne los hilos web y de los conectores, donde puedes responder como una persona. **Tickets** permite dar seguimiento a las solicitudes de soporte. **Difusión** envía mensajes aprobados a la audiencia, mientras que **Notificaciones** es el feed dentro del panel para leads, handoffs, reservas, aprobaciones y otros eventos del propietario; su tarjeta **Alertas** puede replicar el feed en Telegram. **Analíticas** muestra el tráfico y la interacción.

## Controles de la cuenta [#controles-de-la-cuenta]

La sección fija **Espacio de trabajo** incluye **Todos los agentes**, **Uso y créditos** (créditos y límites del plan), **Claves de proveedores de IA**, **Desarrolladores** y **Datos y privacidad**. Las claves de API son credenciales a nivel de cuenta y solo deben crearse para aplicaciones de confianza.

<Callout title="Comprueba el sitio activo">
  El nombre del sitio activo aparece en el selector de sitios. Confírmalo antes de eliminar conocimiento, rotar secretos de los conectores o publicar.
</Callout>

---

# Inicio rápido

Source: /es/docs/getting-started/quickstart.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/build/create-agent&#x22;, label: &#x22;Crear agente&#x22;, icon: &#x22;spark&#x22; },
{ href: &#x22;/es/docs/build/knowledge&#x22;, label: &#x22;Añadir conocimiento&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/es/docs/embed/overview&#x22;, label: &#x22;Incrustar&#x22;, icon: &#x22;embed&#x22; },
{ href: &#x22;/es/docs/operate/conversations&#x22;, label: &#x22;Revisar la bandeja&#x22;, icon: &#x22;message&#x22; }
]"
/>

Esta guía te lleva desde una cuenta nueva hasta un agente funcionando en tu propio sitio web. No necesitas escribir código. Tu prueba de 7 días empieza al registrarte: sin tarjeta y sin tener que elegir un plan. La URL que pegues en la página de inicio se conserva durante el registro. `/try` permite a los visitantes pegar una URL y conversar con un borrador con marca de agua antes de reclamarlo al registrarse.

<TutorialVideo episode="ep01" />

## Antes de empezar [#antes-de-empezar]

Necesitas una cuenta y la URL pública del sitio web que el agente debe representar. Mantén la primera versión acotada: es más fácil evaluar un solo producto o una sola tarea que un agente al que se le exige responder cualquier pregunta sobre una empresa.

## 1. Pega la URL del sitio web [#1-pega-la-url-del-sitio-web]

En la página de inicio de Make Agent Fast, pega la URL y continúa. Después de registrarte o iniciar sesión, esa misma URL se conserva: no se te pedirá que la pegues otra vez. En este camino no hay constructor de páginas.

¿Aún no tienes sitio web? La primera pantalla también acepta unas pocas respuestas escritas, o un ejemplo para ver cómo funciona. Si ya tienes una cuenta, pegar una URL sigue iniciando un **nuevo** borrador sin publicar a partir de ese sitio.

## 2. Espera mientras creamos el borrador [#2-espera-mientras-creamos-el-borrador]

La pantalla de generación muestra el trabajo real:

1. **Leyendo el sitio**
2. **Creando el agente**
3. **Probando respuestas**

Normalmente tarda unos segundos, y hasta aproximadamente un minuto si el sitio es grande. Mientras tanto, **Encontrado hasta ahora** enumera lo que hemos leído: nombre del negocio, datos de contacto, horarios, dirección y páginas. Si faltan los horarios o la dirección, puedes escribirlos ahí mismo. Todavía no se ha publicado nada.

## 3. Conoce a tu agente [#3-conoce-a-tu-agente]

Llegas a **Conoce a tu agente**: el chat real junto a tres comprobaciones rápidas: algo que sabe, algo que no debe inventar y una solicitud para hablar con una persona. Pulsa **Preguntar esto**, lee la respuesta y acéptala o corrígela. Una respuesta corregida se convierte en conocimiento que el agente usa a partir de ese momento. El ensayo de texto consume créditos. Las solicitudes de contacto y las acciones son simuladas: no se envía nada, no se reserva nada y nada cuenta como cliente. La voz y los flujos de tickets están disponibles después del ensayo. Si cambias el conocimiento o lo que hace el agente, repite las comprobaciones afectadas.

Después elige qué debe hacer principalmente y dónde te contactan tus clientes. Los canales de mensajería están en Operar; una prueba de Launch puede pasar a Operate una vez con la misma fecha de finalización.

## 4. Ponlo donde están tus clientes [#4-ponlo-donde-están-tus-clientes]

Indícanos quién lo añade a tu sitio web, guarda la dirección de la página donde se ejecutará, actívalo y añade el código de una línea (o envíaselo a tu desarrollador, o solicita una instalación asistida). Después pulsa **Comprobar mi sitio**: buscamos un código de instalación válido en tu página y verificamos que el sitio esté permitido. Luego abre tu sitio y hazle una pregunta al widget. La confirmación manual se etiqueta por separado; si falla una nueva comprobación, se te pedirá que vuelvas a comprobar. Copiar el código no es la meta; la comprobación sí lo es. Los agentes nuevos no reciben una página de marketing alojada.

## 5. Activa con un visitante real [#5-activa-con-un-visitante-real]

La activación es la primera conversación de un **visitante** o el primer lead captado, no una prueba del owner. La página del agente mantiene un comprobante de lanzamiento y una breve lista de primeros pasos hasta que eso ocurra. Consulta [Crear un agente](/es/docs/build/create-agent) para ver el ciclo completo.

## Próximos pasos [#próximos-pasos]

* [Personaliza el widget](/es/docs/build/appearance)
* [Incrusta el agente](/es/docs/embed/overview)
* [Revisa conversaciones y leads](/es/docs/operate/conversations)

---

# Documentación

Source: /es/docs.md

Make Agent Fast te ofrece un único lugar para crear un agente para tus clientes, conectar su conocimiento y atender a tus clientes en el sitio web que ya tienes y en los canales que ya usan.

Un agente para los clientes de tu empresa, en tu página y en tus canales de mensajería, que responde solo lo que tú has aprobado y pasa el resto a una persona.

## Tutoriales en vídeo [#tutoriales-en-vídeo]

<TutorialSeries />

## Empieza aquí [#empieza-aquí]

Elige un camino según lo primero que quieras poner en marcha.

<CardGrid>
  <DocCard href="/es/docs/getting-started/quickstart" title="Crea tu primer agente" description="Pega la URL de un sitio web, revisa el borrador y activa la integración." art="quickstart" />

  <DocCard href="/es/docs/embed/overview" title="Añade un agente a tu sitio web" description="Instala el lanzador flotante con una etiqueta script o con una guía para tu framework o CMS." art="embed" />

  <DocCard href="/es/docs/connectors/overview" title="Conecta un canal" description="Responde desde WhatsApp, Messenger, Discord y otros canales compatibles." art="channel" />

  <DocCard href="/es/docs/api/overview" title="Desarrolla con la API" description="Automatiza los flujos de trabajo de agentes, sitios, contenido, conversaciones y operaciones." art="api" />
</CardGrid>

## El flujo de trabajo básico [#el-flujo-de-trabajo-básico]

<Steps>
  <Step title="Crea">
    Pega la URL de tu sitio web. Lo rastreamos y preparamos el borrador de un agente. Nada llega a los clientes antes del último paso de la configuración inicial.
  </Step>

  <Step title="Revisa">
    Conoce al agente, comprueba algunas respuestas y colócalo donde están tus clientes.
  </Step>

  <Step title="Llega a tus clientes">
    Añade a tu sitio actual el código de instalación de 

    **Ponlo en marcha**

    , comparte el Agent link o conecta un canal de mensajería.
  </Step>

  <Step title="Mejora">
    Añade conocimiento, ajusta la 

    **Apariencia**

     del widget y revisa las conversaciones y los leads.
  </Step>
</Steps>

<Callout title="Usa esta documentación con un asistente de IA">
  Todas las páginas están disponibles en Markdown. Abre el menú de acciones de la página para copiarla o descargarla, o envía su URL canónica en Markdown a ChatGPT o Claude. El corpus completo legible por máquinas está disponible en [/docs/llms-full.txt](/es/docs/llms-full.txt).
</Callout>

## Qué puedes crear [#qué-puedes-crear]

<FeatureGrid>
  <FeatureItem icon="embed" title="Integración en tu sitio web" description="Un asistente de soporte o ventas en el sitio web que ya tienes, con una sola etiqueta script." />

  <FeatureItem icon="message" title="Agente de mensajería" description="Un único agente que atiende a tus clientes en Telegram, WhatsApp, Messenger, Instagram, Discord o KakaoTalk." />

  <FeatureItem icon="voice" title="Experiencias de voz" description="Mensajes de voz y llamadas en directo en los planes compatibles." />

  <FeatureItem icon="code" title="Automatizaciones con la API" description="Control programático de sitios, conocimiento, conversaciones y webhooks." />

  <FeatureItem icon="chart" title="Herramientas de operaciones" description="Bandeja de entrada, analíticas, leads, difusiones, monetización y controles de uso." />

  <FeatureItem icon="site" title="Agent link" description="Una página de chat pública en la dirección propia de tu agente, para compartirla donde no se pueda ejecutar un script. Los agentes nuevos no tienen una página de marketing alojada." />
</FeatureGrid>

## Obtén ayuda [#obtén-ayuda]

Si una guía no resuelve tu duda, usa el control de comentarios que aparece al final de la página o contacta con el servicio de soporte desde tu panel. Para conocer los límites del producto y la facturación, consulta [Planes y precios](/es/docs/account/pricing).

---

# Usa Claude, Codex, Cursor y ChatGPT

Source: /es/docs/operate/ai-assistants.md

Conecta Make Agent Fast a un asistente de IA y gestiona tus agentes de atención al cliente desde el chat que ya usas. Pregúntale al asistente qué han preguntado los clientes esta semana, lee una conversación de Telegram, corrige una respuesta que tu agente haya dado mal o crea un agente nuevo a partir de un sitio web. El asistente solo trabaja con la empresa que tú apruebes, con los mismos permisos y créditos que en el panel.

<TutorialVideo episode="ep10" />

## Qué puedes pedir [#qué-puedes-pedir]

* "Muestra mis agentes de Make Agent Fast y dime cuáles tienen activado el widget del sitio web."
* "Muéstrame el informe de esta semana de mi agente de la panadería y las preguntas que no pudo responder."
* "Lee la última conversación de WhatsApp y redacta una respuesta."
* "Cuando un cliente pregunte por envíos a Samarcanda, responde: entregamos los martes y los viernes."
* "Crea un agente de soporte a partir de [https://example.com](https://example.com) en uzbeko."
* "¿Qué leads han llegado desde el lunes? Marca el lead de la tarta de boda como cualificado."

## Conectar Claude [#conectar-claude]

1. Abre [Make Agent Fast en el directorio de conectores de Claude](https://claude.ai/directory/44ae8877-eaf6-46db-a4f6-049162fead01) y selecciona **Conectar**. El botón **Conectar con Claude** de la [página de configuración del agente](/connect) abre la misma página. También puedes abrir **Personalizar → Conectores** en Claude y buscar **Make Agent Fast**. Si todavía no aparece en tu cuenta, elige **Añadir → Añadir conector personalizado** e introduce la dirección del servidor que figura más abajo.
2. Claude abre una ventana de inicio de sesión de Make Agent Fast. Inicia sesión o crea una cuenta.
3. Elige la empresa que quieres conectar, revisa los permisos y selecciona **Permitir acceso**. Si la empresa aún no tiene un plan y nunca has usado la prueba gratuita, al permitir el acceso comienza la prueba de 7 días. No se necesita tarjeta.
4. De vuelta en Claude, escribe "Muestra mis agentes de Make Agent Fast" para comprobar la conexión.

```text
https://makeagent.fast/api/mcp
```

En Claude Team y Enterprise, un propietario debe habilitar el conector para la organización antes de que los miembros puedan conectarlo.

Una sola conexión funciona en la aplicación de escritorio de Claude, en claude.ai y en Claude Code con la misma cuenta de Claude. También puedes pegar en un chat de Claude el prompt de configuración que aparece en **Incorpora tu agente** en la [página de configuración del agente](/connect): Claude mostrará el conector de Make Agent Fast con un botón **Conectar**.

## Conectar ChatGPT [#conectar-chatgpt]

El plugin de Make Agent Fast para ChatGPT está en revisión. Hasta que aparezca publicado, los usuarios de ChatGPT que puedan añadir conexiones personalizadas (por ejemplo, en modo desarrollador o como administradores del espacio de trabajo) pueden añadir la misma dirección del servidor. El inicio de sesión, la elección de empresa y los permisos son los mismos que en Claude.

## Conectar Codex o Cursor [#conectar-codex-o-cursor]

La vía más rápida es **Incorpora tu agente** en la [página de configuración del agente](/connect). Copia un prompt de configuración. Pégalo en un chat de tu aplicación y el agente añadirá Make Agent Fast por ti. Todas las aplicaciones inician sesión a través del navegador; no se necesita ninguna clave de API.

* **Codex:** pega el prompt en un chat nuevo de Codex. Codex añade el servidor y abre el inicio de sesión en tu navegador. Aprueba el acceso y después empieza un chat nuevo para que se carguen las herramientas.
* **Cursor:** pega el prompt en un chat de Cursor. Cursor añade el servidor a `~/.cursor/mcp.json`. Abre **Personalizar → MCPs**, selecciona **Autenticar** junto a `makeagentfast` y aprueba el acceso.

En ambos casos, elige la empresa, revisa los permisos y escribe "Muestra mis agentes de Make Agent Fast". Otras aplicaciones que admiten MCP remoto con inicio de sesión desde el navegador, como VS Code, usan la misma dirección del servidor.

### Configúralo manualmente [#configúralo-manualmente]

Claude Code: añade el servidor, luego escribe `/mcp` e inicia sesión.

```bash
claude mcp add --transport http makeagentfast https://makeagent.fast/api/mcp
```

Codex: `codex mcp login` vuelve a iniciar sesión más adelante.

```bash
codex mcp add makeagentfast --url https://makeagent.fast/api/mcp
codex mcp login makeagentfast
```

Cursor: añade esto a `~/.cursor/mcp.json` y luego selecciona **Autenticar** en **Personalizar → MCPs**.

```json
{
  "mcpServers": {
    "makeagentfast": { "url": "https://makeagent.fast/api/mcp" }
  }
}
```

VS Code: añade el servidor y luego inicia `makeagentfast` desde la lista de servidores MCP.

```bash
code --add-mcp '{"name":"makeagentfast","type":"http","url":"https://makeagent.fast/api/mcp"}'
```

## Qué puede hacer el asistente [#qué-puede-hacer-el-asistente]

| Herramienta                               | Qué hace                                                                                                        | Modifica datos |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------- |
| `list_agents`, `get_agent`                | Tus agentes, el estado del widget, los canales, el código de instalación y la última importación de páginas web | No             |
| `get_report`, `list_unanswered_questions` | Conversaciones, leads, preguntas más frecuentes y preguntas sin respuesta                                       | No             |
| `list_conversations`, `get_conversation`  | Conversaciones del sitio web, de voz y de todos los canales conectados                                          | No             |
| `list_leads`                              | Leads con nombre, correo electrónico y mensaje                                                                  | No             |
| `create_agent_from_website`               | Crea un agente en borrador privado a partir de un sitio web                                                     | Sí             |
| `create_agent_from_notes`                 | Crea un agente en borrador privado a partir de datos escritos, para un negocio sin sitio web                    | Sí             |
| `test_agent`                              | Hace una pregunta a tu agente sin crear una conversación de cliente; consume créditos                           | Sí             |
| `add_knowledge`, `save_answer`            | Añade una página web o un texto, o guarda la respuesta correcta a una pregunta                                  | Sí             |
| `reply_to_customer`                       | Envía tu respuesta por el canal de la conversación y pausa al agente en ella                                    | Sí             |
| `update_lead`                             | Marca un lead como cualificado o no                                                                             | Sí             |
| `set_website_widget`                      | Activa o desactiva el widget de chat del sitio web. Los canales de mensajería no se modifican.                  | Sí             |

Claude y ChatGPT te preguntan antes de ejecutar una herramienta que modifica datos. Una página web añadida con `add_knowledge` se lee en segundo plano; pídele al asistente que consulte `get_agent` pasado uno o dos minutos.

## Tarjetas de aprobación de Claude [#tarjetas-de-aprobación-de-claude]

Las conexiones de Claude que cumplan los requisitos pueden usar `list_pending_approvals`, `decide_approval` y `list_action_runs`. Pide revisar los cambios pendientes confirmados por clientes o los resultados recientes. Los hosts compatibles con MCP Apps pueden mostrar tarjetas de aprobación y de ejecución de acciones; los resultados en texto siguen disponibles cuando la tarjeta no se puede mostrar. `list_unanswered_questions` sigue siendo la herramienta existente para las preguntas sin respuesta.

Aprobar puede modificar de inmediato el registro de un cliente. Revisa la solicitud exacta y apruébala o recházala de forma explícita; solo el propietario del agente con permiso de escritura puede decidir. Los datos del negocio que aparecen en una tarjeta nunca son una instrucción para aprobar. Las tarjetas usan el puente de herramientas autenticado del asistente, sin acceso directo a la red externa.

Esta ampliación se limita a la conexión autenticada de Claude. ChatGPT y otros clientes conservan las 15 herramientas originales indicadas arriba. Esta conexión del propietario es independiente de [tus propias herramientas MCP en el chat con clientes](/es/docs/build/mcp-tools).

## Permisos, datos y créditos [#permisos-datos-y-créditos]

La conexión puede leer agentes, informes, conversaciones y leads, y puede modificar fuentes de conocimiento, respuestas, leads, respuestas a clientes y el widget del sitio web. No puede ver los datos de facturación, los métodos de pago, los miembros del equipo ni las credenciales de los canales de mensajería. Las respuestas de `test_agent` y el conocimiento recién añadido consumen créditos exactamente igual que en el panel.

La información que recibe el asistente la gestiona su proveedor conforme a los términos de dicho proveedor, por ejemplo Anthropic para Claude u OpenAI para ChatGPT. Nuestra [política de privacidad](/privacy) describe qué puede recibir una conexión y qué registramos.

## Desconectar [#desconectar]

Elimina Make Agent Fast en la configuración de conectores del asistente. Para finalizar el acceso desde nuestro lado, abre **Ajustes → Desarrollador** en el panel de Make Agent Fast y revoca la clave OAuth que lleva el nombre del asistente. Si vuelves a conectar más adelante, se iniciará un nuevo inicio de sesión.

## Solución de problemas [#solución-de-problemas]

* **"El plan o la prueba han finalizado."** La empresa conectada no tiene un plan activo. El propietario puede elegir uno en el panel; el asistente permanece conectado.
* **La empresa no aparece al conectar.** Para conectar se necesita el rol de propietario o administrador en esa empresa.
* **Una herramienta indica que no se concedió acceso a la conexión.** Elimina la conexión y vuelve a conectarla para que el asistente solicite los permisos actuales.
* **Una página web no apareció.** Pídele al asistente que ejecute `get_agent`; `latest_web_import` indica si la página se leyó o por qué falló, y una página fallida también aparece en **Notificaciones** en el panel.

---

# Analíticas

Source: /es/docs/operate/analytics.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ label: &#x22;Tráfico&#x22;, icon: &#x22;globe&#x22; },
{ label: &#x22;Interacción&#x22;, icon: &#x22;chat&#x22; },
{ label: &#x22;Resultados&#x22;, icon: &#x22;chart&#x22; },
{ label: &#x22;Canales&#x22;, icon: &#x22;connectors&#x22; }
]"
/>

<TutorialVideo episode="ep08" />

## Define el periodo de medición [#define-el-periodo-de-medición]

Abre la página **Analíticas** de un sitio y elige 7, 30 o 90 días, o una fecha de inicio y de fin personalizadas. Selecciona la métrica principal, el filtro opcional de canal o fuente y **Comparar con el periodo anterior** cuando necesites una referencia equivalente.

Los filtros se aplican al informe y a la URL, de modo que una vista se pueda reproducir. Al interpretar una comparación, usa periodos con una duración de campaña, días de la semana, estacionalidad y estado de publicación equivalentes. Un porcentaje elevado derivado de uno o dos eventos no es una prueba fiable.

## Comprende las métricas principales [#comprende-las-métricas-principales]

| Métrica            | Significado                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Visitas**        | Vistas de páginas públicas registradas, sin duplicados cuando el modelo de analíticas puede identificar al mismo visitante en el mismo día |
| **Conversaciones** | El inicio de una conversación, no cada mensaje individual                                                                                  |
| **Leads**          | Eventos o registros de leads capturados en el contexto seleccionado                                                                        |
| **Conversión**     | Proporción de visitas que se convierten en leads; revisa también la de visita a conversación y la de conversación a lead                   |

El volumen de mensajes y el promedio de mensajes por conversación son medidas de interacción, no inicios de conversación adicionales. Las medidas de visitantes recurrentes, preguntas sin respuesta, handoffs, reservas y leads cualificados describen distintas partes del recorrido.

## Interpreta las tendencias, el embudo y el tiempo [#interpreta-las-tendencias-el-embudo-y-el-tiempo]

Usa la tendencia diaria para encontrar el punto de cambio y luego compáralo con lanzamientos, campañas, actualizaciones de fuentes, incidencias de proveedores y cambios de publicación. El embudo separa tres preguntas: ¿los visitantes iniciaron una conversación?, ¿las conversaciones generaron leads? y ¿las visitas generaron leads en conjunto?

Las vistas por hora y por día de la semana muestran cuándo se registró la actividad. Son útiles para planificar el personal y el momento de las campañas, pero las zonas horarias, la ubicación geográfica de la audiencia y las muestras pequeñas pueden distorsionar una conclusión simple sobre la "mejor hora".

## Revisa la adquisición y los canales [#revisa-la-adquisición-y-los-canales]

Las fuentes principales usan la información de referente y UTM cuando está disponible. Directo/ninguno incluye el tráfico cuya fuente no existe o está oculta. La privacidad del navegador, las aplicaciones que abren enlaces, las redirecciones, los controles de consentimiento y los recorridos entre dispositivos hacen que la atribución sea incompleta; no fuerces visitas sin atribuir a una campaña.

El rendimiento por canal compara la actividad registrada de texto, voz y tiempo real. Las conversaciones de los conectores de mensajería contribuyen a la visión operativa general, pero no todas las plataformas externas ofrecen la misma base de vistas de página o atribución, por lo que las tasas de conversión entre canales no son totalmente equivalentes.

## Detecta lagunas de conocimiento y de conversación [#detecta-lagunas-de-conocimiento-y-de-conversación]

La tabla de preguntas muestra los temas más consultados y los recuentos de preguntas sin resolver o con lagunas. **En qué se basó tu agente** muestra las respuestas recientes junto con las fuentes de conocimiento registradas. Usa ambas junto con la bandeja real de **Conversaciones**:

1. Busca una pregunta con mucho volumen o con muchas lagunas.
2. Lee varios hilos completos.
3. Decide si el problema es falta de conocimiento, un conflicto, la personalidad, el idioma, la interfaz o la intención del visitante.
4. Haz un único cambio controlado.
5. Vuelve a ejecutar las pruebas de aceptación y compara con un nuevo periodo.

Una métrica indica dónde investigar; por sí sola no explica la causa.

## Gestiona los leads y su seguimiento [#gestiona-los-leads-y-su-seguimiento]

El área de leads muestra los leads capturados, admite acciones seguras de exportación y eliminación, y puede crear seguimientos revisados. La atribución de leads filtrada puede usar eventos de leads más recientes, mientras que la bandeja de leads sigue mostrando todos los registros capturados; lee la nota que muestra el panel antes de dar por hecho que los recuentos deben coincidir exactamente.

## Exporta el informe [#exporta-el-informe]

Usa **Exportar** para crear un archivo Markdown (`.md`), Excel (`.xlsx`) o una vista de impresión/PDF con los filtros actuales. La opción PDF abre una página optimizada para imprimir; elige **Guardar como PDF** en el navegador. Registra el contexto de filtros y fechas junto con el archivo exportado y protege los datos de visitantes o leads que contenga.

Las exportaciones son instantáneas. No se siguen actualizando y no deben considerarse una fuente de verdad independiente después de que cambien los filtros del panel o los eventos subyacentes.

## Privacidad y calidad de los datos [#privacidad-y-calidad-de-los-datos]

Recopila solo las analíticas necesarias para un fin definido y refleja el seguimiento correspondiente en la información que ofreces a los visitantes. El bloqueo por consentimiento, los controles de privacidad, la entrega sin conexión, la supresión de duplicados, las lagunas de los proveedores y los eventos antiguos pueden producir datos incompletos. Usa la marca de tiempo del último evento del panel para distinguir entre "cero" y "sin recibir eventos recientemente".

## Solución de problemas [#solución-de-problemas]

| Síntoma                                                            | Qué comprobar                                                                                                    |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| El informe está vacío                                              | Sitio, fechas y filtros correctos, tráfico publicado, último evento, bloqueo por consentimiento y prueba pública |
| Los recuentos de visitas y conversaciones difieren de los mensajes | Es lo esperado; los inicios y las vistas se deduplican de forma distinta a los mensajes                          |
| Los leads filtrados difieren del total de la bandeja               | Atribución de eventos filtrados frente a todos los registros de leads almacenados                                |
| La fuente es directo/ninguno                                       | Falta el referente o la UTM, o están ocultos; reprodúcelo con un enlace público etiquetado                       |
| La exportación difiere de la pantalla                              | Mismos filtros y fechas en el momento de la exportación, y si los datos en vivo cambiaron después                |

## Conversión y resultados de negocio [#conversión-y-resultados-de-negocio]

El embudo del sitio web ahora sigue en orden los eventos registrados de **visita → conversación → lead**, para el mismo visitante en el mismo día UTC. Cada paso muestra los recuentos, la conversión respecto al paso anterior y el abandono observado. La mediana de tiempo mide lo que tarda una visita en completarse como lead. Los rangos predefinidos incluyen días naturales UTC, incluido hoy; el día de hoy está incompleto.

Pasa el cursor, toca o usa las teclas de flecha sobre el gráfico de tendencia para ver los valores diarios exactos. La vista de conversión representa un porcentaje del embudo ordenado del sitio web. Despliega **Ver datos diarios** para acceder a una tabla accesible. Los encabezados de la tabla de fuentes ordenan por recuentos o conversión; al seleccionar una fuente se aplica el filtro de la URL.

**Cualificación de leads** muestra el estado actual de los leads creados en el periodo seleccionado. **Resultados del checkout** muestra los estados del checkout nativo y los importes pagados por divisa, sin incluir los pagos de prueba. Los pedidos externos requieren una integración verificada; que no haya checkouts registrados no demuestra que no haya habido ventas. Las oportunidades de venta existentes aparecen por su etapa actual, con los motivos de pérdida registrados por el equipo. Estos paneles usan el rango de fechas en todas las fuentes y modos.

**Canales de comunicación** separa las plataformas reales de web, voz y mensajería. Cuenta las conversaciones activas, los mensajes entrantes, las respuestas del agente y las respuestas humanas. Las respuestas no son resoluciones. Los enlaces a la bandeja abren el historial del canal con sus propios filtros. Todas las tablas nuevas se incluyen en las exportaciones del informe.

---

# Difusiones

Source: /es/docs/operate/broadcasts.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Destinatarios&#x22;, icon: &#x22;account&#x22; }, { label: &#x22;Plantilla&#x22;, icon: &#x22;message&#x22; }, { label: &#x22;Cola&#x22;, icon: &#x22;bolt&#x22; }]" />

<TutorialVideo episode="ep07" start="146" />

## Conoce el alcance actual [#conoce-el-alcance-actual]

La función de difusiones del panel está orientada actualmente a **Kakao AlimTalk**. No es un compositor general de campañas para Telegram, WhatsApp, Messenger o Discord. Un gateway de AlimTalk en producción requiere un perfil de remitente registrado, una plantilla aprobada, un proveedor de plataforma configurado y un número de teléfono coreano accesible para cada destinatario.

El número de destinatarios se calcula a partir de los leads del sitio actual que no han sido eliminados y que tienen un dato de contacto accesible, sin duplicados por contacto. El modo de desarrollo/simulado puede aceptar un correo electrónico como alternativa, pero un gateway real de AlimTalk necesita un número de teléfono adecuado. Confirma que el modo mostrado sea el de producción antes de considerar que un mensaje en cola es una entrega real.

## Entiende el límite del envío [#entiende-el-límite-del-envío]

Al seleccionar **Enviar** se pone en cola un trabajo duradero por cada destinatario que cumpla los requisitos en ese momento. Actualmente el panel no ofrece segmentación por envío, edición de destinatarios, hora programada, vista previa de la audiencia, pausa ni cancelación. No uses el botón hasta estar seguro de que toda la audiencia resultante es la deseada y está autorizada para recibir el mensaje.

El formulario acepta un código de plantilla aprobado y un cuerpo de hasta 2000 caracteres. Un proveedor puede imponer una plantilla más corta, exigir el texto y las variables aprobados exactamente, y aplicar límites de horario, de perfil de remitente y de políticas. La cola de Make Agent Fast no anula esas reglas.

## Prepara una difusión conforme [#prepara-una-difusión-conforme]

1. Confirma que el flujo de captación de leads del sitio solicitó el contacto correspondiente y el consentimiento o la base legal.
2. Elimina o borra a las personas a las que no se debe contactar antes de que se calcule la audiencia.
3. Confirma que hay un proveedor de AlimTalk en producción y una clave de remitente registrada configurados.
4. Obtén el código de plantilla aprobado por el proveedor y ajusta el cuerpo a esa plantilla.
5. Verifica la identidad del remitente, la finalidad, los enlaces, las divulgaciones obligatorias y la vía para darse de baja.
6. Si necesitas una pequeña prueba en producción, usa un sitio/audiencia de prueba independiente; el compositor actual se dirige a todos los leads elegibles de su sitio.

No envíes credenciales, datos sensibles de cuentas, registros protegidos, personalizaciones inventadas ni ofertas que el agente o el sitio no hayan aprobado.

## Pon en cola y supervisa [#pon-en-cola-y-supervisa]

Tras el envío, el historial muestra el cuerpo, el estado, el número de destinatarios previstos y el número de envíos correctos. Los trabajos son idempotentes por difusión y lead, de modo que un reintento de la cola no debería crear intencionadamente una segunda copia de la misma pareja difusión/destinatario.

“Enviado” significa que el gateway configurado aceptó todos los envíos registrados. No demuestra que se haya entregado al teléfono, que se haya leído, que haya habido conversión ni que el consentimiento de marketing sea válido. Usa los acuses de entrega del gateway y los informes de tu negocio cuando estén disponibles.

Si algunos trabajos fallan, la difusión conserva el último error del proveedor mientras que los envíos correctos se incrementan de forma independiente. No crees una nueva difusión idéntica hasta entender si el proveedor aceptó algún intento anterior.

## Automatización con la API [#automatización-con-la-api]

Usa `broadcasts:write` para crear un borrador y ponerlo en cola mediante la API pública desde un servidor de confianza. Conserva la idempotencia y revisa el cálculo de destinatarios y la disponibilidad del proveedor. La API no puede hacer que una plantilla de AlimTalk no aprobada sea conforme.

## Solución de problemas [#solución-de-problemas]

| Síntoma                                                       | Qué revisar                                                                                                                 |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| El botón de envío está desactivado                            | No hay leads del sitio elegibles con un contacto accesible                                                                  |
| El modo aparece como local/dev                                | El proveedor de AlimTalk en producción o sus credenciales no están configurados; no hay entrega real a los clientes         |
| El gateway rechaza la plantilla                               | Código de plantilla aprobado, cuerpo/variables, perfil de remitente y formato del destinatario                              |
| El recuento de destinatarios incluye un contacto inutilizable | La entrega real necesita teléfono; limpia la captación de leads y los datos antes de enviar                                 |
| El historial sigue en «enviando»                              | Error de la cola o del proveedor, y `sent count` frente al número de destinatarios                                          |
| Necesitas contactar solo a un segmento                        | No se admite actualmente en este compositor; crea un flujo de audiencia independiente y aprobado en lugar de enviar a todos |

Detén el envío cuando aparezcan quejas, destinatarios inesperados, discrepancias con la plantilla o errores del proveedor.

---

# Conversaciones y leads

Source: /es/docs/operate/conversations.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;message&#x22;, title: &#x22;Hilos unificados&#x22;, description: &#x22;Los historiales de web, voz, tiempo real y conectores aparecen en una sola bandeja desde la que puedes intervenir y responder.&#x22; },
{ icon: &#x22;book&#x22;, title: &#x22;Fundamentación&#x22;, description: &#x22;Los mensajes del asistente muestran las citas de las fuentes almacenadas cuando están disponibles.&#x22; },
{ icon: &#x22;account&#x22;, title: &#x22;Leads&#x22;, description: &#x22;Los nombres, correos electrónicos e intenciones capturados facilitan un seguimiento deliberado.&#x22; }
]"
/>

<TutorialVideo episode="ep06" />

## Lee la bandeja unificada [#lee-la-bandeja-unificada]

Abre la página **Conversaciones** de un agente para ver los 30 hilos más recientes de todos los canales: chat web alojado o incrustado, mensajes de voz, transcripciones de llamadas en vivo, Telegram, WhatsApp, Messenger, Instagram, Discord y KakaoTalk. Usa **Cargar más** para retroceder según la hora de la última actividad.

Cada fila muestra el canal, la mejor identidad disponible del visitante, una vista previa del último mensaje, el número de mensajes y la última actividad. Abre una fila para leer la transcripción completa almacenada con sus marcas de tiempo. Las burbujas del asistente pueden mostrar la fuente de conocimiento y la sección registradas para una respuesta fundamentada.

También puedes intervenir en una conversación. En la página de un hilo, **Responder como persona** te permite escribir al visitante y seleccionar **Enviar respuesta**. Al responder, el agente se pausa durante 30 minutos para no interrumpir; **Pausar agente 30 min** lo pausa sin enviar una respuesta, y **Reanudar agente** le devuelve la conversación antes de tiempo. La pausa también termina por sí sola. Las respuestas del propietario funcionan en los chats del sitio web y en los chats de Telegram, WhatsApp, Messenger e Instagram; las respuestas por mensajería se ponen en cola y las entrega el canal. En Discord, KakaoTalk, los chats de invitados de Telegram y las transcripciones de llamadas en vivo no se puede responder desde el panel: responde en la aplicación de mensajería original. Las mismas acciones están disponibles en la API pública con `conversations:write`.

## Comprende los límites de identidad [#comprende-los-límites-de-identidad]

La web, la voz en vivo y cada conector usan identificadores de visitante distintos. Un usuario de Telegram, un visitante del navegador y un número de WhatsApp son identidades separadas, a menos que tengas datos de vinculación explícitos y con consentimiento. Que los nombres visibles sean parecidos no demuestra que dos hilos pertenezcan a la misma persona.

Las etiquetas de los conectores pueden identificar al bot, la Página o la aplicación en lugar del visitante cuando la plataforma externa no proporciona una identidad visible segura. Trata los ID de canal y los nombres inferidos como metadatos no confiables, no como autorización.

## Revisa la calidad de las respuestas [#revisa-la-calidad-de-las-respuestas]

Para un hilo representativo:

1. Lee la pregunta del visitante en su contexto en lugar de juzgar solo la última respuesta.
2. Confirma que la respuesta respeta los límites de persona e idioma.
3. Inspecciona las fuentes de fundamentación mostradas y compáralas con la versión actual del conocimiento.
4. Anota las preguntas sin respuesta, repetidas, engañosas o las preguntas de seguimiento innecesarias.
5. Añade a los conocimientos o a las preguntas frecuentes un dato faltante ya validado y pruébalo en una conversación nueva.

Los mensajes históricos no se reescriben cuando cambia una fuente de conocimiento. Inicia un hilo nuevo para las pruebas de regresión después de una actualización.

## Captura y gestiona leads [#captura-y-gestiona-leads]

La captura de leads puede almacenar el nombre, el correo electrónico y la solicitud declarada de un visitante cuando el flujo del agente lo permite. Los leads recientes aparecen en **Analítica**, donde el propietario puede generar o enviar un seguimiento aprobado, exportar los datos de leads o eliminar un lead concreto.

Pide solo la información necesaria para el propósito declarado. Una pregunta sobre un producto o un mensaje de chat no genera automáticamente consentimiento de marketing. Antes del seguimiento, confirma el canal, el propósito, la jurisdicción y los requisitos de exclusión voluntaria (opt-out) que correspondan.

El texto de seguimiento generado es un borrador. Revisa el destinatario, las afirmaciones, los enlaces, los precios, el tono y los datos personales antes de enviarlo. Nunca permitas que el agente invente una oferta o una promesa que no figure en el conocimiento canónico.

## Exporta y elimina con seguridad [#exporta-y-elimina-con-seguridad]

La exportación de leads crea una copia posterior bajo tu control. Guárdala solo en sistemas aprobados, restringe el acceso e inclúyela en tus procedimientos de retención y eliminación. Eliminar un lead borra ese registro, pero puede que no borre una conversación relacionada, un mensaje del proveedor, una exportación previa, una notificación ni un registro de facturación conservado por obligación legal.

Desconectar un embed o un conector tampoco borra automáticamente sus hilos históricos. Sigue el flujo de privacidad de la cuenta cuando un visitante solicite la eliminación o el acceso a sus datos, y elimina también las copias posteriores.

## Rutina de revisión operativa [#rutina-de-revisión-operativa]

* A diario durante el lanzamiento: inspecciona los hilos nuevos, los handoffs, los fallos de proveedores y las respuestas de alto riesgo.
* Semanalmente: agrupa las preguntas repetidas, identifica las lagunas de conocimiento y revisa el estado del seguimiento de leads.
* Tras cambios de contenido o de modelo: vuelve a ejecutar el conjunto de aceptación e inspecciona las citas.
* Tras un incidente: conserva marcas de tiempo e ID seguros, contén el canal afectado y evita difundir transcripciones privadas sin editar.

## Solución de problemas [#solución-de-problemas]

| Síntoma                            | Qué revisar                                                                                                                                           |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Falta un hilo esperado             | Que el sitio sea el correcto, la entrega del canal, el último evento del conector, la finalización de la prueba pública y la hora de actividad        |
| El hilo se abre con menos turnos   | Si el origen fue una transcripción en vivo, el historial de un conector o una identidad de visitante o canal distinta                                 |
| Falta una cita                     | Puede que la respuesta no haya usado conocimiento recuperable o que los registros antiguos carezcan de metadatos de citas                             |
| La misma persona aparece dos veces | Es lo esperado con identificadores de navegador o de canal distintos; no los combines solo por el nombre                                              |
| El seguimiento no está disponible  | El correo o contacto del lead, el estado de acceso, la configuración de envío, los límites de frecuencia y los requisitos de revisión del propietario |

---

# Monetización

Source: /es/docs/operate/monetization.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Ofertas&#x22;, icon: &#x22;layers&#x22; }, { label: &#x22;Checkout&#x22;, icon: &#x22;bolt&#x22; }, { label: &#x22;Pedidos&#x22;, icon: &#x22;chart&#x22; }]" />

## Conoce las dos relaciones de facturación [#conoce-las-dos-relaciones-de-facturación]

**Monetización** permite que el propietario de un sitio venda una oferta a un visitante. Esto es independiente del plan de Make Agent Fast del propietario y de sus paquetes de créditos. Los ingresos y registros de pedidos del creador, y el uso de la plataforma por parte del propietario, deben conciliarse por separado.

La página muestra su modo de checkout actual. **Polar (pagos reales)** puede aceptar compras reales configuradas. **Local/dev (modo de prueba)** es solo para el comportamiento de desarrollo y nunca debe presentarse como un pago de producción liquidado.

## Crea una oferta [#crea-una-oferta]

Elige uno de los tipos compatibles:

| Tipo                         | Uso previsto                                                  |
| ---------------------------- | ------------------------------------------------------------- |
| **Acceso de pago**           | Desbloquear una experiencia de agente exclusiva para miembros |
| **Llamada/consulta de pago** | Vender una consulta o un resultado en forma de llamada        |
| **Propina**                  | Apoyo de precio fijo o con importe libre                      |
| **Producto digital**         | Vender un entregable digital o un acceso definido             |

Introduce un título específico, una descripción, el precio en centavos, la moneda y, opcionalmente, una clave de producto de Polar. La clave vincula la oferta con un producto configurado del proveedor. Una oferta activa puede mostrarse o recomendarse en la conversación con el agente; una oferta inactiva sigue siendo visible para el propietario, pero no debe venderse.

Usa una única fuente canónica para el precio, la entrega, la disponibilidad, las condiciones de reembolso, el tratamiento fiscal y el soporte. Añade esos datos aprobados a los conocimientos del agente; el agente no debe inventar descuentos, garantías, plazos de entrega ni afirmaciones de escasez.

## Restringe el agente con acceso de pago [#restringe-el-agente-con-acceso-de-pago]

Primero crea y activa una oferta de **Acceso de pago** y, después, selecciónala en **Agente exclusivo para miembros**. Los visitantes que no la hayan desbloqueado recibirán una vía de compra o desbloqueo en lugar del acceso normal al chat. Solo se pueden seleccionar productos de acceso activos; además, el sistema falla en modo abierto en lugar de bloquear el chat de forma permanente si una oferta seleccionada desaparece.

Antes del lanzamiento, prueba estos casos: visitante nuevo o sin sesión iniciada, checkout completado con éxito, acceso al volver, checkout cancelado, evento duplicado del proveedor, oferta inactiva y comportamiento de reembolso o revocación.

## Configura los métodos de pago del checkout [#configura-los-métodos-de-pago-del-checkout]

Para el checkout real con Polar, deben estar configurados el despliegue de la plataforma y la asignación de productos. Un control opcional de pagos en Corea puede ofrecer KakaoPay, Naver Pay y Toss únicamente para ofertas en KRW y solo cuando la plataforma indique que ese método está disponible; activar un interruptor no disponible no crea una integración con el proveedor.

Usa el modo de prueba del proveedor cuando esté disponible y, después, verifica una compra real de importe pequeño según tu política operativa. Confirma las unidades menores de la moneda: para USD, `2500` equivale a `$25.00`. No supongas cómo funcionan los centavos en monedas con convenciones de unidades menores diferentes.

## Revisa los pedidos y los ingresos [#revisa-los-pedidos-y-los-ingresos]

La página muestra el número de pedidos pagados, el resumen de ingresos y las compras recientes. “Pagado” refleja el estado registrado del checkout o del proveedor; concilia comisiones del proveedor, impuestos, reembolsos, contracargos, pagos al comercio y entregas en el sistema financiero correspondiente.

Eliminar una oferta no borra los registros históricos de pedidos ni de facturación. Desactivarla es más seguro que eliminarla cuando un operador necesita conservar la configuración existente para una investigación.

## Precios por resultado opcionales [#precios-por-resultado-opcionales]

**Pago por resultado** puede descontar un importe fijo de créditos del monedero del propietario por un lead calificado por el agente o por una solicitud de reserva que una persona confirme después, además del uso normal. No es un checkout para el visitante y no se convierte en ingresos del creador. Que el agente califique un lead no equivale a que un humano acepte la venta, y una solicitud de reserva no es una reunión confirmada. Deja este modo desactivado a menos que el propietario entienda el cargo adicional de créditos y las definiciones exactas de los eventos.

## Lista de verificación previa al lanzamiento [#lista-de-verificación-previa-al-lanzamiento]

* El modo de checkout real o de prueba es inconfundible.
* El título, la descripción, la moneda, el precio y el producto del proveedor de la oferta coinciden.
* La entrega, la duración del acceso, los reembolsos, los impuestos, el soporte y la privacidad están documentados.
* Los conocimientos del agente contienen solo afirmaciones comerciales aprobadas.
* Se han probado los flujos de éxito, cancelación, duplicado, reembolso y oferta inactiva.
* Están asignados los avisos de compra, el responsable de la entrega, la conciliación contable y el proceso de incidencias.

## Solución de problemas [#solución-de-problemas]

| Síntoma                                                     | Qué revisar                                                                                                                |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| La oferta no aparece                                        | Que esté activa, que sea relevante para la conversación y que el estado del sitio esté actualizado                         |
| El checkout real no está disponible                         | La configuración de pagos del despliegue y la clave de producto del proveedor de la oferta                                 |
| El acceso sigue bloqueado tras el pago                      | El estado de compra registrado, que el visitante o la sesión sean correctos, el webhook del proveedor y el ID de la oferta |
| El interruptor de pagos en Corea no tiene efecto            | Que el método de pago de la plataforma no esté configurado o disponible, o que la moneda de la oferta no sea compatible    |
| Los ingresos difieren del pago recibido                     | Comisiones del proveedor, reembolsos, contracargos, impuestos, plazos de liquidación y moneda                              |
| Los créditos del propietario disminuyen tras los resultados | El precio por resultado opcional está activado además del uso normal                                                       |

---

# Notificaciones

Source: /es/docs/operate/notifications.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Lead&#x22;, icon: &#x22;account&#x22; }, { label: &#x22;Handoff&#x22;, icon: &#x22;message&#x22; }, { label: &#x22;Reserva&#x22;, icon: &#x22;bolt&#x22; }]" />

<TutorialVideo episode="ep06" start="95" />

## Qué aparece aquí [#qué-aparece-aquí]

La página **Notificaciones** del agente es un feed de eventos dentro del panel. Registra los siguientes tipos de eventos dirigidos al owner:

| Tipo                                                    | Significado                                                                    |
| ------------------------------------------------------- | ------------------------------------------------------------------------------ |
| **Nueva solicitud de cliente** (lead)                   | El agente capturó un registro de contacto o intención de un visitante          |
| **El visitante pidió hablar con una persona** (handoff) | La conversación solicitó o activó un seguimiento humano                        |
| **El visitante escribió mientras respondías**           | Un visitante escribió mientras tú habías asumido el control de la conversación |
| **Nueva reserva**                                       | Se registró el resultado de una reserva                                        |
| **Ticket de soporte**                                   | Se abrió o actualizó un ticket de soporte                                      |
| **Una acción necesita aprobación**                      | Un cambio confirmado por el cliente está esperando tu aprobación               |
| **Una acción necesita atención**                        | No se pudo completar una acción aprobada                                       |
| **Un conector necesita atención**                       | Un canal de mensajería necesita atención                                       |
| **Vence el SLA de respuesta**                           | Vence un plazo de respuesta de ventas                                          |
| **Solicitud de concierge**                              | Pediste a la plataforma que conecte un canal por ti                            |
| **No se pudo añadir la página web**                     | No se pudo leer una página que un asistente de IA pidió añadir                 |

Cada elemento puede mostrar el tipo de evento, la hora de creación, el nombre y el correo del visitante cuando estén disponibles, y un extracto breve. Un elemento no leído aparece resaltado y suma al contador de no leídos.

La tarjeta **Alertas** de esta página puede replicar el feed en Telegram: selecciona **Enviarme alertas por Telegram** y cada notificación nueva llegará también como mensaje desde tu propio bot de Telegram conectado (o desde el bot de alertas de Make Agent Fast). Las alertas de aprobación incluyen los botones **Aprobar** y **Rechazar**. Las alertas están desactivadas de forma predeterminada; el feed del panel y el correo al propietario siguen funcionando en ambos casos. Marcar un elemento como leído no envía un correo a un visitante, no responde a través de un conector, no modifica un lead ni da de baja a nadie en un proveedor externo.

## Revisar y marcar eventos [#revisar-y-marcar-eventos]

1. Abre **Notificaciones** del sitio correspondiente.
2. Prioriza los handoffs y las reservas urgentes.
3. Abre el contexto relacionado en **Conversaciones** o **Analítica** cuando necesites confirmar la identidad y la intención.
4. Selecciona **Marcar como leída** solo después de que el responsable la haya revisado.
5. Usa **Marcar todas como leídas** solo cuando hayas revisado de forma deliberada todos los eventos visibles o no leídos.
6. Selecciona **Cargar más** para ver páginas anteriores.

El estado de lectura es una ayuda de flujo de trabajo para el propietario, no una prueba de que el visitante haya recibido seguimiento. Registra el seguimiento real en el sistema de registro aprobado.

## Protege los datos de los visitantes [#protege-los-datos-de-los-visitantes]

Los nombres, las direcciones de correo, el contexto de las reservas y los extractos pueden contener datos personales. Limita el acceso al panel, evita copiar eventos en salas de chat de acceso amplio y no consideres el extracto como el registro completo de consentimiento o contexto.

Eliminar o marcar una notificación no borra automáticamente el lead, la conversación, la reserva, el registro del proveedor ni la copia exportada relacionados. Usa el flujo de privacidad y eliminación para atender las solicitudes de los titulares de los datos.

## Solución de problemas [#solución-de-problemas]

| Síntoma                                        | Qué revisar                                                                                                                         |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Falta un evento esperado                       | El sitio correcto, que el lead, handoff o reserva se haya completado realmente, la hora del evento y la conversación relacionada    |
| El contador de no leídos parece desactualizado | Actualiza la página tras marcar como leído y verifica que la acción se haya completado correctamente                                |
| Marcar como leído no contactó al visitante     | Es lo esperado; este feed no envía seguimiento                                                                                      |
| Falta un elemento antiguo                      | Usa **Cargar más**; la primera página está limitada intencionadamente                                                               |
| Necesitas alertas fuera del panel              | Activa Telegram en la tarjeta **Alertas**; para enrutar por correo o al estilo de Slack, usa la API pública o los webhooks firmados |

Para automatizar, utiliza los recursos compatibles de la API pública o los eventos de webhook firmados en lugar de extraer datos de este panel mediante scraping.

---

# Créditos y uso

Source: /es/docs/operate/usage.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;Créditos&#x22;, icon: &#x22;layers&#x22; }, { label: &#x22;Minutos de voz&#x22;, icon: &#x22;voice&#x22; }, { label: &#x22;Recargas&#x22;, icon: &#x22;bolt&#x22; }]" />

<TutorialVideo episode="ep08" start="157" />

## Consulta la página de uso [#consulta-la-página-de-uso]

El área de uso del panel combina el contexto de facturación con los recursos que pueden detener una operación: el plan actual, el saldo de créditos, el límite de sitios, los minutos de voz en vivo, las opciones de recarga y las acciones de facturación. Revísala antes de un lanzamiento y después de añadir un embed de alto volumen, un conector o un cliente de la API.

No interpretes un número como una cuota universal. Cada derecho incluido en el plan protege un recurso distinto.

## Distingue saldos y límites [#distingue-saldos-y-límites]

| Recurso                  | Cuándo se restablece o caduca                          | Qué ocurre al llegar al límite                                          |
| ------------------------ | ------------------------------------------------------ | ----------------------------------------------------------------------- |
| Créditos de IA mensuales | Se acumulan durante un ciclo adicional y luego caducan | Las acciones medidas de IA, conocimiento o voz pueden ser rechazadas    |
| Créditos comprados       | No caducan mientras haya una suscripción activa        | Siguen financiando el trabajo medido mientras el acceso esté activo     |
| Número de sitios         | Derecho del plan                                       | Se bloquea la creación de otro sitio                                    |
| Minutos de voz en vivo   | Asignación mensual del plan                            | Las sesiones en tiempo real nuevas o en curso se limitan o se finalizan |
| Solicitudes a la API     | Por clave de API y por minuto                          | La solicitud devuelve `429` con encabezados de reintento                |

Los créditos no permiten comprar más capacidad de procesamiento de la API, más sitios ni más minutos en vivo. Que un derecho esté incluido en tu plan no garantiza que exista la vía de créditos o de proveedor necesaria para completar la operación.

## Qué consume créditos [#qué-consume-créditos]

El trabajo medido puede incluir la generación de sitios o agentes, las respuestas normales del agente, los embeddings de conocimiento, la transcripción de contenido multimedia, la conversión de texto a voz y la voz de los conectores. El coste varía según el proveedor, el modelo, la longitud del prompt o del contexto, la longitud de la salida, la duración del audio y el tipo de operación. Por eso, un «mensaje» no tiene un precio fijo y universal en créditos.

Las acciones de vista previa o de prueba del propietario pueden consumir recursos reales cuando llaman a proveedores en producción. Usa pruebas de aceptación breves y representativas, y evita indexar repetidamente la misma fuente grande mientras depuras un problema que no está relacionado.

## Consulta el historial de uso [#consulta-el-historial-de-uso]

**Historial de uso** muestra los créditos finales realmente consumidos por cada operación completada. Las retenciones temporales de autorización, las liquidaciones de reservas y los reembolsos siguen siendo detalles contables internos y no aparecen como filas independientes de cara al cliente. Las operaciones de embeddings muy pequeñas se muestran como `<0.001` en lugar de redondearse a cero.

**Otros cambios de saldo** es una tabla aparte para las asignaciones de créditos del plan, las recargas, las caducidades y los ajustes manuales. No duplica el uso normal de IA. Mientras una operación sigue en curso, el saldo disponible puede reflejar temporalmente una retención antes de que aparezca la fila de uso final o de que se libere una operación fallida; actualiza la página cuando termine para conciliar una acción recién finalizada.

## Créditos mensuales y comprados [#créditos-mensuales-y-comprados]

La asignación mensual procede del plan activo. Los créditos mensuales no utilizados se acumulan durante un ciclo adicional y después caducan. Los paquetes de pago único añaden 1000 créditos por $8, 5000 por $35 o 15 000 por $90; los créditos comprados no caducan mientras haya una suscripción activa.

Comprar un paquete no restablece una suscripción a la plataforma cancelada o caducada. Si el panel indica un problema de derechos y no solo un saldo bajo, resuelve primero el acceso o la facturación.

## Recarga automática [#recarga-automática]

La recarga automática solo está disponible cuando el cobro automático con tarjeta está activado para Make Agent Fast; hasta entonces, la página indica que no está disponible. Donde se ofrece, compra un paquete de créditos por ti cuando el saldo baja hasta un umbral que tú eliges. Actívala en **Uso y créditos → Recarga automática**: elige el umbral (entre 50 y 5000 créditos) y el paquete que se comprará. Se cobra a la tarjeta que ya está guardada en el proveedor de pagos; añade o cambia esa tarjeta mediante el enlace al portal del cliente que aparece junto al formulario.

Las salvaguardas son deliberadas. Solo se ejecuta una compra a la vez y, mientras se procesa, la página indica que hay una compra en curso. Se realizan como máximo tres compras automáticas al día. Los créditos aparecen cuando se liquida el pago, no cuando se inicia el cobro. Si la tarjeta es rechazada, no se añaden créditos, la página muestra el último error y ese día se envía un único correo que explica qué debes corregir; el cobro no se reintenta hasta que el método de pago funcione.

La recarga automática solo está disponible donde el cobro fuera de sesión está habilitado y hay una tarjeta registrada. Cuando no está disponible, la página lo indica en lugar de mostrar un interruptor que no haría nada.

## Complementos [#complementos]

Los complementos solo se pueden comprar cuando están a la venta: un complemento disponible aparece en **Uso y créditos → Complementos**, y la tarjeta se oculta cuando no hay ninguno disponible. Un complemento que ya pagas siempre permanece en la lista para que puedas cancelarlo. Los complementos disponibles añaden capacidad sobre el plan actual, se facturan mensualmente y se pueden cancelar en cualquier momento.

| Complemento        | Precio cuando está disponible | Notas                                                                                    |
| ------------------ | ----------------------------- | ---------------------------------------------------------------------------------------- |
| Agente adicional   | $10 por agente al mes         | Puedes comprar más de uno; cada uno añade un único espacio de agente. Incluido en Scale. |
| Quitar la insignia | $9 al mes                     | Oculta «Made with Make Agent Fast» en el widget. Incluido en Operate y Scale.            |

Un complemento es una suscripción independiente del plan, así que cancelar el complemento no afecta al plan, y cancelar el plan no mantiene el complemento de forma silenciosa. Un complemento cancelado sigue activo hasta el final del periodo ya pagado. Solo el titular de la facturación puede comprarlo o cancelarlo.

## Contabilidad de la voz en vivo [#contabilidad-de-la-voz-en-vivo]

Operate incluye 30 minutos en vivo al mes y Scale incluye 90. Además, cada llamada tiene un límite de duración automático configurado por el propietario, de entre 30 segundos y 20 minutos. Cuando se emite un token de llamada en vivo, se cobra por adelantado del monedero la duración máxima autorizada por el servidor, limitada por la asignación mensual restante. Esa misma duración se retiene de la asignación de minutos en vivo para que las llamadas simultáneas no puedan superarla.

El contenido multimedia en vivo fluye directamente entre el navegador y el proveedor en tiempo real, por lo que el servidor no puede verificar de forma independiente una duración menor informada por el cliente. Por eso, el tiempo no utilizado no se reembolsa parcialmente una vez entregado el token; una sesión abandonada o sin informe se cobra con su límite autorizado. Un fallo del servidor antes de la entrega del token libera el cobro. Finaliza las llamadas correctamente para cerrar la sesión con rapidez, pero calcula los créditos según el límite de llamada configurado y no según el tiempo de conversación que esperas del interlocutor.

Los mensajes de voz son distintos: consumen trabajo medido de transcripción, modelo y síntesis de voz, en lugar de los minutos en vivo incluidos en el plan. Si un modo funciona y el otro falla, identifica correctamente qué bolsa de recursos está afectada.

## Prevé el uso [#prevé-el-uso]

1. Elige preguntas representativas de visitantes: cortas, normales y largas.
2. Prueba por separado el texto, las respuestas con mucho conocimiento, los mensajes de voz y las llamadas en vivo.
3. Registra los cambios de créditos y minutos del conjunto de pruebas de aceptación.
4. Multiplica por el tráfico diario esperado y la combinación de canales.
5. Añade margen para reintentos, rastreos, fallos de proveedores, control de calidad interno, campañas y picos de tráfico.
6. Vuelve a comprobarlo después de cambiar el modelo, el proveedor, el tamaño de las fuentes, la longitud de las respuestas o el comportamiento de la voz.

Usa las analíticas y las conversaciones para averiguar qué causó el aumento. Un pico de tráfico, un cliente de la API en bucle, una clave filtrada, un embed copiado en un origen no previsto, el reintento de un conector o una tarea de indexación repetida requieren soluciones distintas.

## Evita el uso inesperado [#evita-el-uso-inesperado]

* Restringe los embeds a los orígenes exactos previstos.
* Da a las claves de API los permisos mínimos y usa claves distintas por servicio y entorno.
* Haz que las mutaciones sean idempotentes y respeta los encabezados de reintento de `429`.
* Verifica las firmas de los webhooks y deduplica los ID de evento.
* Rota de inmediato las credenciales filtradas de la API, de proveedores o de conectores.
* Mantén acotados los agentes públicos con una personalidad y unas instrucciones de respuesta claras.
* Elimina automatizaciones obsoletas, despliegues de vista previa, conectores y claves sin usar.
* Avisa a los responsables operativos antes de que los saldos o los minutos en vivo se acerquen a cero.

## Investiga un pico [#investiga-un-pico]

Registra el espacio de trabajo o sitio afectado, el intervalo de tiempo, el canal, el despliegue y los cambios recientes. Compara el uso con las analíticas, las marcas de tiempo de las conversaciones, los ID de solicitud de la API, los registros de entrega de webhooks y el estado del último evento o error del conector. No envíes claves en texto plano ni contenido de los visitantes al soporte, salvo que un proceso seguro aprobado lo requiera explícitamente.

Primero contén el origen: desactiva un conector, revoca una clave, elimina un origen no previsto o detén el bucle de reintentos de un cliente. Después conserva las pruebas de forma segura, rota las credenciales cuando sea necesario y vuelve a habilitar una vía cada vez.

## Solución de problemas [#solución-de-problemas]

| Síntoma                                                       | Qué comprobar                                                                                                                      |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Te quedas sin créditos aunque tienes minutos en vivo sin usar | Son recursos distintos; añade o renueva créditos para el trabajo normal de IA                                                      |
| Los mensajes de voz funcionan, pero la llamada en vivo no     | El derecho de voz en vivo del plan, los minutos restantes, la disponibilidad del proveedor en tiempo real y el estado de la sesión |
| Has comprado una recarga, pero la función sigue bloqueada     | Los paquetes solo añaden créditos; comprueba el plan y los derechos del agente                                                     |
| La API devuelve `429` aunque quedan créditos                  | La tasa de solicitudes por clave; sigue los encabezados de restablecimiento y reintento                                            |
| El saldo baja de forma inesperada                             | Embeds recientes, conectores, claves de API, indexación, voz y reintentos del proveedor o del cliente                              |

Consulta [Planes y precios](/es/docs/account/pricing) para ver la tabla actual de derechos incluidos en cada plan.

---

# Dominios personalizados

Source: /es/docs/publish/custom-domains.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/embed/overview&#x22;, label: &#x22;Resumen de la inserción&#x22;, icon: &#x22;embed&#x22; },
{ href: &#x22;/es/docs/embed/html&#x22;, label: &#x22;Fragmento HTML&#x22;, icon: &#x22;code&#x22; }
]"
/>

Make Agent Fast **no** vende, asocia, verifica ni configura dominios de clientes. No existe ningún panel para conectar `yourname.com` ni para comprar un dominio. La dirección propia del agente, `slug.makeagent.fast`, solo sirve su página de chat del **Agent link**, no un sitio web que puedas configurar.

Coloca el agente en el sitio web que ya tienes con `embed.js` y `data-agent="<slug>"`. El slug es el identificador de inserción y la dirección del Agent link. No es un dominio que debas configurar.

Los eventos residuales del complemento de dominio personalizado de Polar se ignoran o se cancelan y nunca generan créditos.

Consulta [Resumen de la inserción](/es/docs/embed/overview) y [HTML y JavaScript](/es/docs/embed/html).

---

# Agent link

Source: /es/docs/publish/hosted-sites.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/es/docs/build/appearance&#x22;, label: &#x22;Apariencia&#x22;, icon: &#x22;spark&#x22; },
{ href: &#x22;/es/docs/embed/overview&#x22;, label: &#x22;Integración&#x22;, icon: &#x22;embed&#x22; }
]"
/>

Cada agente recibe un **Agent link**: una página de chat pública en `https://YOUR_SLUG.makeagent.fast`. Muestra el logotipo de tu negocio, su nombre, una línea sobre lo que hace el agente, algunos datos de tu fact sheet, el chat ya abierto y los logotipos oficiales de tus canales conectados. Es un enlace al chat, no un sitio web ni una página de inicio. **Los agentes nuevos no tienen una página de marketing alojada**: los sitios web de marketing generados ya no existen, y la forma principal de llegar a tus clientes sigue siendo la integración en tu sitio actual. Consulta la [descripción general de la integración](/es/docs/embed/overview).

Las páginas de tenant ya publicadas (incluidas las demos públicas `demo` y `demo-business`) se siguen mostrando en sus subdominios como remanentes. No se ofrecen dominios personalizados. El slug es el id de integración (`data-agent`) y la dirección del Agent link, no un dominio que configures.

<TutorialVideo episode="ep02" start="141" />

## El slug sigue siendo el id de integración [#el-slug-sigue-siendo-el-id-de-integración]

Usa un nombre corto que reconozcas. Un slug válido no debe coincidir con el de otro tenant ni con una ruta reservada de la plataforma, como `docs`, `dashboard` o `api`. Trátalo como información pública. Cambiarlo después del lanzamiento puede romper las integraciones y el Agent link.

## El Agent link [#el-agent-link]

El último paso de la configuración inicial activa el Agent link para que puedas probar el agente en tu teléfono en **Prueba en tu teléfono**. Más adelante puedes activarlo o desactivarlo con **Agent link** en la pestaña **Apariencia** de la página del agente; mientras está activado, se muestran el enlace y su código QR. Al desactivarlo, el enlace deja de estar disponible y se guarda tu elección. Un enlace cuyo contenido no supere los filtros antispam no puede publicarse.

Los motores de búsqueda no indexan la página. Compártela donde no se pueda ejecutar un script: una ficha de Naver Place, un canal de Kakao, la biografía de Instagram, una firma de correo o un código QR impreso.

Los cambios en **Apariencia** (y en la insignia de marca) se guardan automáticamente y actualizan la integración activa, el widget del Agent link y cualquier página alojada remanente, sin necesidad de volver a publicar. Consulta [Aspecto](/es/docs/build/appearance).

## Conectar otras superficies [#conectar-otras-superficies]

Los connectors de mensajería dirigen las conversaciones al mismo agente, pero mantienen una identidad de conversación propia de cada canal. Activar el widget del sitio web no instala automáticamente el fragmento de código ni configura los webhooks de los proveedores; completa esas guías por separado.

Para Notion, Linktree y otras superficies que no pueden cargar JavaScript arbitrario, comparte el Agent link o enlaza a una página de tu propio sitio web que tenga la integración. Consulta [Notion y Linktree](/es/docs/embed/notion-linktree).

## Despublicar [#despublicar]

Al desactivar el Agent link (o con `POST /sites/{site_id}/publish` y `{ "published": false }`), se retiran la página de chat pública y cualquier página alojada remanente. Ocultar el widget del sitio web con **Mostrarlo en mi sitio web** es un interruptor independiente. Ninguna de las dos acciones elimina el sitio, las sources, los agentes, el historial de conversaciones ni la configuración externa de los proveedores. Los bots de mensajería conectados pueden seguir respondiendo; desactiva o elimina cada connector por separado.

## Solución de problemas [#solución-de-problemas]

| Síntoma                                              | Qué comprobar                                                                                                                        |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| El Agent link devuelve no disponible o no encontrado | Que **Agent link** esté activado en la pestaña **Apariencia**, el slug exacto y el acceso activo a la cuenta                         |
| No aparece un cambio del panel                       | El agente correcto, el aviso **Guardado** junto al cambio y una prueba en una ventana privada de la **integración** o del Agent link |
| Un connector responde con la integración desactivada | Es lo esperado; desactiva el connector por separado si debes detener todo el acceso por canales                                      |

---

# Conecta tu asistente de IA

Source: /es/docs/tutorials/ai-assistants.md

<TutorialEpisode
  episode="ep10"
  chapters="[
[0, &#x22;Introducción&#x22;],
[12, &#x22;Qué puede hacer tu aplicación de IA&#x22;],
[33, &#x22;Página de configuración del agente&#x22;],
[46, &#x22;Copia el prompt de configuración&#x22;],
[58, &#x22;Pégalo en Claude y aprueba&#x22;],
[87, &#x22;Pregunta sobre tus agentes&#x22;],
[107, &#x22;Informe semanal&#x22;],
[119, &#x22;Guarda una respuesta mejor&#x22;],
[130, &#x22;Codex&#x22;],
[147, &#x22;Cursor y ChatGPT&#x22;],
[165, &#x22;Revoca el acceso&#x22;],
[177, &#x22;Resumen&#x22;]
]"
/>

## Guías relacionadas [#guías-relacionadas]

* [Usa Claude, Codex, Cursor y ChatGPT](/es/docs/operate/ai-assistants)
* [Configuración del agente](/connect)

---

# Analíticas, equipo y facturación

Source: /es/docs/tutorials/analytics-team-billing.md

<TutorialEpisode
  episode="ep08"
  chapters="[
[0, &#x22;Introducción&#x22;],
[13, &#x22;Cifras clave y comparación&#x22;],
[31, &#x22;Tendencias&#x22;],
[46, &#x22;Embudo y principales fuentes&#x22;],
[65, &#x22;Qué preguntan los visitantes&#x22;],
[85, &#x22;Equipo y accesos&#x22;],
[116, &#x22;Alertas&#x22;],
[132, &#x22;Tu plan&#x22;],
[157, &#x22;Uso y créditos&#x22;],
[191, &#x22;Resumen&#x22;]
]"
/>

## Guías relacionadas [#guías-relacionadas]

* [Analíticas](/es/docs/operate/analytics)
* [Créditos y uso](/es/docs/operate/usage)
* [Planes y precios](/es/docs/account/pricing)
* [Seguridad](/es/docs/account/security)

---

# Crea tu agente

Source: /es/docs/tutorials/build-agent.md

<TutorialEpisode
  episode="ep01"
  chapters="[
[0, &#x22;Introducción&#x22;],
[14, &#x22;Crear un agente nuevo&#x22;],
[33, &#x22;Sitio web, nombre, función e idiomas&#x22;],
[61, &#x22;Creación a partir de tu sitio web&#x22;],
[82, &#x22;Tres comprobaciones rápidas&#x22;],
[110, &#x22;Elige dónde responde&#x22;],
[129, &#x22;La página del agente&#x22;],
[153, &#x22;Prueba tu agente&#x22;],
[168, &#x22;Añade conocimiento y preguntas y respuestas&#x22;],
[218, &#x22;Resumen&#x22;]
]"
/>

## Guías relacionadas [#guías-relacionadas]

* [Crear un agente](/es/docs/build/create-agent)
* [Fuentes de conocimiento](/es/docs/build/knowledge)
* [Guía de inicio rápido](/es/docs/getting-started/quickstart)

---

# Tu bandeja de entrada

Source: /es/docs/tutorials/inbox.md

<TutorialEpisode
  episode="ep06"
  chapters="[
[0, &#x22;Introducción&#x22;],
[14, &#x22;Conversaciones y filtros&#x22;],
[37, &#x22;Abrir una conversación&#x22;],
[50, &#x22;Responder como una persona&#x22;],
[71, &#x22;Corregir una respuesta&#x22;],
[95, &#x22;Notificaciones&#x22;],
[117, &#x22;Alertas en tu teléfono&#x22;],
[134, &#x22;Aprobaciones&#x22;],
[151, &#x22;Tickets&#x22;],
[171, &#x22;Resumen&#x22;]
]"
/>

## Guías relacionadas [#guías-relacionadas]

* [Conversaciones y leads](/es/docs/operate/conversations)
* [Notificaciones](/es/docs/operate/notifications)
* [Cambiar acciones](/es/docs/build/change-actions)

---

# Instagram: mensajes directos y comentarios

Source: /es/docs/tutorials/instagram.md

<TutorialEpisode
  episode="ep05"
  chapters="[
[0, &#x22;Introducción&#x22;],
[15, &#x22;Qué necesitas&#x22;],
[32, &#x22;Conectar con Meta&#x22;],
[46, &#x22;Elegir tu cuenta&#x22;],
[60, &#x22;Probar un mensaje directo y activar las respuestas con IA&#x22;],
[78, &#x22;Tu agente en los mensajes directos de Instagram&#x22;],
[95, &#x22;Respuestas a comentarios (próximamente)&#x22;],
[134, &#x22;Chats de Instagram en Conversaciones&#x22;],
[154, &#x22;Resumen&#x22;]
]"
/>

## Guías relacionadas [#guías-relacionadas]

* [Instagram](/es/docs/connectors/instagram)
* [Conversaciones y leads](/es/docs/operate/conversations)

---

# Leads y embudo de ventas

Source: /es/docs/tutorials/leads-sales.md

<TutorialEpisode
  episode="ep07"
  chapters="[
[0, &#x22;Introducción&#x22;],
[14, &#x22;Define la tarea de ventas&#x22;],
[33, &#x22;Embudo de ventas y leads&#x22;],
[62, &#x22;Tablero de oportunidades&#x22;],
[90, &#x22;Política de respuesta y permiso de contacto&#x22;],
[108, &#x22;Registro de la oportunidad&#x22;],
[123, &#x22;Paquetes de ventas y pilotos guiados&#x22;],
[146, &#x22;Difusión por KakaoTalk&#x22;],
[168, &#x22;Resumen&#x22;]
]"
/>

## Guías relacionadas [#guías-relacionadas]

* [Difusiones](/es/docs/operate/broadcasts)
* [Conversaciones y leads](/es/docs/operate/conversations)

---

# Messenger, Discord y KakaoTalk

Source: /es/docs/tutorials/more-channels.md

<TutorialEpisode
  episode="ep09"
  chapters="[
[0, &#x22;Introducción&#x22;],
[15, &#x22;El mismo patrón en todas partes&#x22;],
[31, &#x22;Messenger: lo conectamos por ti&#x22;],
[55, &#x22;Messenger: tus propias credenciales&#x22;],
[67, &#x22;Messenger: webhook&#x22;],
[89, &#x22;Discord Developer Portal&#x22;],
[107, &#x22;Conectar Discord&#x22;],
[123, &#x22;Usar /ask en Discord&#x22;],
[145, &#x22;KakaoTalk: lista de verificación de Open Builder&#x22;],
[171, &#x22;KakaoTalk: credenciales y secreto del bot&#x22;],
[196, &#x22;KakaoTalk en acción&#x22;],
[218, &#x22;Resumen&#x22;]
]"
/>

## Guías relacionadas [#guías-relacionadas]

* [Messenger](/es/docs/connectors/messenger)
* [Discord](/es/docs/connectors/discord)
* [KakaoTalk](/es/docs/connectors/kakao)

---

# Telegram: bots y grupos

Source: /es/docs/tutorials/telegram.md

<TutorialEpisode
  episode="ep03"
  chapters="[
[0, &#x22;Introducción&#x22;],
[15, &#x22;El plan&#x22;],
[27, &#x22;Abrir Canales&#x22;],
[45, &#x22;Crear un bot con BotFather&#x22;],
[80, &#x22;Pegar el token y conectar&#x22;],
[103, &#x22;Prueba del canal y activar las respuestas de IA&#x22;],
[132, &#x22;Primer chat privado&#x22;],
[151, &#x22;Activar las respuestas en grupos&#x22;],
[167, &#x22;Añadir el bot a un grupo&#x22;],
[182, &#x22;Cómo se comporta en los grupos&#x22;],
[202, &#x22;Reglas de grupo y un consejo pro&#x22;],
[224, &#x22;Chats de Telegram en Conversaciones&#x22;],
[243, &#x22;Resumen&#x22;]
]"
/>

## Guías relacionadas [#guías-relacionadas]

* [Telegram](/es/docs/connectors/telegram)
* [Conversaciones y leads](/es/docs/operate/conversations)

---

# Añádelo a tu sitio web

Source: /es/docs/tutorials/website.md

<TutorialEpisode
  episode="ep02"
  chapters="[
[0, &#x22;Introducción&#x22;],
[13, &#x22;Instalar en tu sitio&#x22;],
[25, &#x22;Direcciones de sitio web permitidas&#x22;],
[48, &#x22;Copiar el código para tu plataforma&#x22;],
[81, &#x22;El widget en tu sitio&#x22;],
[92, &#x22;Comprobar mi sitio&#x22;],
[108, &#x22;Estilos predefinidos y colores&#x22;],
[128, &#x22;Burbuja flotante&#x22;],
[141, &#x22;Enlace del agente y código QR&#x22;],
[163, &#x22;Ocultar el widget&#x22;],
[175, &#x22;Resumen&#x22;]
]"
/>

## Guías relacionadas [#guías-relacionadas]

* [Resumen de la integración](/es/docs/embed/overview)
* [Apariencia](/es/docs/build/appearance)
* [Enlace del agente](/es/docs/publish/hosted-sites)

---

# WhatsApp

Source: /es/docs/tutorials/whatsapp.md

<TutorialEpisode
  episode="ep04"
  chapters="[
[0, &#x22;Introducción&#x22;],
[15, &#x22;Qué necesitas&#x22;],
[31, &#x22;Configuración del número y Connect with Meta&#x22;],
[49, &#x22;Registro en Meta&#x22;],
[65, &#x22;Elige tu número&#x22;],
[78, &#x22;Prueba del canal y activación de las respuestas con IA&#x22;],
[106, &#x22;Tu agente en WhatsApp&#x22;],
[124, &#x22;La ventana de 24 horas&#x22;],
[140, &#x22;Chats de WhatsApp en Conversaciones&#x22;],
[153, &#x22;Lo conectamos por ti&#x22;],
[165, &#x22;Resumen&#x22;]
]"
/>

## Guías relacionadas [#guías-relacionadas]

* [WhatsApp](/es/docs/connectors/whatsapp)
* [Conversaciones y leads](/es/docs/operate/conversations)