integrations: add the Magento connection guide

_i18n/en/integrations/connect-magento.md

@@ -0,0 +1,106 @@
+Connect your Magento store to bring its catalog, customers and orders into Hellotext, record what shoppers do in the store, and show your popups, webchat and WhatsApp widget.
+
+The connection has two parts: install the Hellotext module on the Magento server, then confirm the store in Hellotext. When the screen says **Magento is connected**, Hellotext has verified the store and configured the module; then check the customer import and the activity to confirm everything arrives as expected.
+
+## What the integration syncs
+
+- **Catalog:** the store's simple and configurable products, with their variants. Bundle, grouped, downloadable and virtual products are not imported.
+- **Customers, optional:** the customers of the connected website, with name, email and newsletter status. Addresses, phone numbers, passwords and payment details are not imported.
+- **Orders:** past orders are read when the connection completes; then each new order and each change arrives: confirmation when it is invoiced, shipment when Magento marks it complete, cancellation and refunds, including partial ones. Each order is attached to the customer who placed it.
+- **Storefront activity:** page views, product views, cart changes, checkout started and order placed. A signed-in shopper is identified by their Magento customer ID, which Hellotext verifies with the store.
+- **Widgets:** the popups, webchat and WhatsApp widget you install in Hellotext with **Automatic Installation on Magento** appear in the store without adding code.
+
+Importing a customer or receiving their email does not grant permission to message them. Review the consent for each channel before including them in campaigns.
+
+## Before you connect
+
+Confirm that:
+
+- You are an **Owner** or **Administrator** of the Hellotext business that will receive the store's activity. A business connects one Magento website.
+- The store runs **Magento Open Source 2.4** (tested on 2.4.7) with **PHP 8.2, 8.3 or 8.4**. Magento Inventory (MSI) is optional.
+- The store is published on its own domain with **HTTPS** and a valid certificate, and its `/rest` API responds from the internet. Hellotext does not connect to IP addresses, `localhost` or internal domains.
+- Someone can run commands from the Magento root (`composer` and `bin/magento`) following the store's usual change process: a backup and a maintenance window in production.
+- The server can make outbound HTTPS connections to Hellotext.
+
+## Install the module and link the store
+
+1. In Hellotext, open **Settings > Integrations** and choose **Browse integrations**.
+2. Choose **Magento**. The **Connect your Magento store** screen shows the exact commands for your server.
+3. Copy the command block and run it from the Magento root:
+
+   ```bash
+   composer require hellotext/magento
+   bin/magento module:enable Hellotext_Tracking
+   bin/magento setup:upgrade
+   bin/magento setup:di:compile
+   bin/magento setup:static-content:deploy -f
+   bin/magento cache:flush
+   bin/magento hellotext:connect '<link code>'
+   ```
+
+   The last command carries your business's link code. It works once and expires after one hour; if it expired, reload the Hellotext page to get a new one. Do not share it.
+4. When it finishes, Magento replies `Store linked. Go back to Hellotext to confirm the connection.` The Hellotext page detects the store by itself.
+
+If the module came from the Adobe Commerce Marketplace, or the server cannot run the last command, connect from Magento Admin: open **System > Extensions > Integrations**, choose **Activate** on the **Hellotext** integration, then **Allow**, and confirm in the Hellotext window that Magento opens.
+
+## Confirm the connection
+
+1. In **Confirm the connection**, check that the address is your store's and choose **Confirm connection**. Only confirm a connection you started yourself: the store will send its activity to this business.
+2. If the website has several store views, choose the one Hellotext uses for product names and links. The connection covers the whole website.
+3. Hellotext shows **Verifying Magento** while it configures the module and verifies the store. The page updates by itself.
+4. When it finishes you see **Magento is connected**. **Status** shows the last verification, the module version, the Magento and PHP versions, and the imported products.
+
+## Import your existing customers
+
+1. Choose **Next**. In **Do you want to import your existing customers?**, choose **Yes, import my existing customers into Hellotext** or **Not now. I'll do this later.**
+2. If you import, in **Organize your customers** choose the lists for the new customers and whether to update their existing properties, then choose **Save & Start import**.
+3. The import keeps running if you close the page. It can take a few minutes to start depending on Hellotext's load. When it finishes you see how many customers were imported.
+
+Each import creates a **Magento import** list with the customers it brought in.
+
+## Show your widgets in the store
+
+Once the store is connected, each widget offers to install itself on Magento:
+
+- **Popup:** in the popup's install step, choose **Automatic Installation on Magento** and publish it.
+- **Webchat or WhatsApp widget:** in its installation settings, choose **Automatic Installation on Magento** and install it.
+
+The module loads Hellotext.js on every store page, so the widget appears without adding code. Installing another popup automatically replaces the previous one.
+
+## Check that everything works
+
+- **In the store:** open a product and add it to the cart. A shopper who signs in is identified by their Magento account.
+- **In Hellotext:** open **Audience**, find the customer and review their **Activity**: their orders appear with their Magento reference and total, followed by their confirmation, shipment, cancellation or refund.
+- **On the server:** run `bin/magento hellotext:diagnose --store=<store-view-code>`. It shows the module version, the active integration, whether the installation key and Business ID are configured, the Hellotext API, and whether identification is on. Add `--ping` to check that the server reaches the Hellotext API.
+
+A storefront order is recorded when the shopper reaches the confirmation page. If they close the browser first, it is recorded with its next status change; an order waiting for payment may not appear until it changes.
+
+## Disconnect or uninstall
+
+To disconnect, open **Settings > Integrations**, open the Magento store's menu, choose **Remove** and confirm with **Delete**. Hellotext turns the module off in the store and deletes its credentials: the store stops sending activity and the widgets stop showing. To connect it again, repeat the installation with a new code.
+
+To remove the module from the store, run from the Magento root:
+
+```bash
+bin/magento module:uninstall Hellotext_Tracking --remove-data
+```
+
+From module version 1.0.2, this command also removes the Hellotext integration from Magento, its access token and the module configuration. With version 1.0.1 or earlier, also delete the **Hellotext** integration in **System > Extensions > Integrations**.
+
+## Troubleshoot the connection
+
+- **"The configured Magento URL is not allowed."** The store must use a public domain with HTTPS on port 443. Fix Magento's base URL and connect again.
+- **"Magento could not be reached right now."** Check that the store responds over HTTPS and that no firewall, WAF or CDN blocks requests to `/rest`. Then choose **Apply settings again** or **Verify connection**.
+- **"Magento rejected the authorization credentials."** Hellotext's access was revoked in Magento. Link the store again: run the last command from the Magento screen with a new code, or choose **Reauthorize** on the Hellotext integration in Magento Admin. The connection keeps its installation key.
+- **The link code expired or was refused.** Reload the Hellotext page and run the new last command.
+- **The store records no activity.** Run `bin/magento hellotext:diagnose` and check that the Business ID is configured. Deploy static content and clear the cache after installing or updating the module. If you use Cookie Restriction Mode, activity starts once the visitor accepts cookies.
+- **The customer import does not progress.** It runs in the background and can wait a few minutes in the queue. If it does not finish, give support the time and the business.
+
+When you contact Hellotext support, share the output of `bin/magento hellotext:diagnose --store=<store-view-code>`, the Magento and module versions, the time of the problem and the exact message. Do not share tokens, passwords or the link code.
+
+## Related guides
+
+- [Setup and integrations overview]({% link _integrations/setup-overview.md %})
+- [Product catalog sync]({% link _integrations/product-catalog-sync.md %})
+- [Verify your data and signals after setup]({% link _integrations/verify-data-and-signals.md %})
+- [How customer profiles work]({% link _audience/customer-profiles.md %})

_i18n/en/integrations/setup-overview.md

@@ -36,6 +36,7 @@ Choose the guide that matches your store:
 - [Connect Wix]({% link _integrations/connect-wix.md %})
 - [Connect WooCommerce]({% link _integrations/connect-woo.md %})
 - [Connect VTEX]({% link _integrations/connect-vtex.md %})
+- [Connect Magento]({% link _integrations/connect-magento.md %})
 - [Connect Mercado Libre]({% link _integrations/connect-mercado-libre.md %})
 
 After connecting, choose a known source record and check its data in Hellotext before building playbooks, routes, or campaigns from it. Check the profile, object, and actual event separately: a saved order does not confirm a recorded purchase or attributed sale. Initial scope and processing vary by platform.

_i18n/es/integrations/connect-magento.md

@@ -0,0 +1,106 @@
+Conecta tu tienda Magento para incorporar a Hellotext su catálogo, sus clientes y sus órdenes, registrar lo que hacen los compradores en la tienda y mostrar tus popups, webchat y widget de WhatsApp.
+
+La conexión tiene dos partes: instalar el módulo de Hellotext en el servidor de Magento y confirmar la tienda en Hellotext. Que la pantalla diga **Magento está conectado** confirma que Hellotext verificó la tienda y configuró el módulo; revisa después la importación de clientes y la actividad para confirmar que todo llega como esperas.
+
+## Qué sincroniza la integración
+
+- **Catálogo:** productos simples y configurables de la tienda, con sus variantes. Los productos de tipo bundle, agrupado, descargable o virtual no se importan.
+- **Clientes, opcional:** los clientes del website conectado, con nombre, email y estado de newsletter. No se importan direcciones, teléfonos, contraseñas ni datos de pago.
+- **Órdenes:** las órdenes anteriores se leen al terminar la conexión; luego llega cada orden nueva y cada cambio: confirmación al facturarla, envío cuando Magento la marca como completa, cancelación y reembolsos, también los parciales. Cada orden se asocia al cliente que la hizo.
+- **Actividad en la tienda:** páginas vistas, productos vistos, cambios en el carrito, inicio del checkout y orden realizada. Un comprador que inició sesión se identifica con su ID de cliente de Magento, que Hellotext verifica con la tienda.
+- **Widgets:** los popups, el webchat y el widget de WhatsApp que instales en Hellotext con la opción **Instalación automática en Magento** aparecen en la tienda sin agregar código.
+
+Importar un cliente o recibir su email no acredita permiso para enviarle mensajes. Revisa el consentimiento de cada canal antes de incluirlo en campañas.
+
+## Antes de conectar
+
+Confirma que:
+
+- Eres **Dueño** o **Administrador** del negocio de Hellotext que recibirá la actividad de la tienda. Un negocio se conecta con un solo website de Magento.
+- La tienda usa **Magento Open Source 2.4** (probado en 2.4.7) con **PHP 8.2, 8.3 u 8.4**. Magento Inventory (MSI) es opcional.
+- La tienda se publica en un dominio propio con **HTTPS** y certificado válido, y su API `/rest` responde desde internet. Hellotext no se conecta a direcciones IP, `localhost` ni dominios internos.
+- Alguien puede ejecutar comandos en la raíz de Magento (`composer` y `bin/magento`) siguiendo el proceso habitual de cambios de la tienda: respaldo y ventana de mantenimiento en producción.
+- El servidor puede hacer conexiones HTTPS salientes a Hellotext.
+
+## Instala el módulo y vincula la tienda
+
+1. En Hellotext, abre **Configuración > Integraciones** y elige **Explorar integraciones**.
+2. Elige **Magento**. La pantalla **Conecta tu tienda Magento** muestra los comandos exactos para tu servidor.
+3. Copia el bloque de comandos y ejecútalo desde la raíz de Magento:
+
+   ```bash
+   composer require hellotext/magento
+   bin/magento module:enable Hellotext_Tracking
+   bin/magento setup:upgrade
+   bin/magento setup:di:compile
+   bin/magento setup:static-content:deploy -f
+   bin/magento cache:flush
+   bin/magento hellotext:connect '<código de vinculación>'
+   ```
+
+   El último comando lleva el código de vinculación de tu negocio. Es de un solo uso y vence en una hora; si venció, recarga la página de Hellotext para obtener uno nuevo. No lo compartas.
+4. Cuando termina, Magento responde `Store linked. Go back to Hellotext to confirm the connection.` La página de Hellotext detecta la tienda sola.
+
+Si el módulo vino del Marketplace de Adobe Commerce, o el servidor no puede ejecutar el último comando, conecta desde Magento Admin: abre **System > Extensions > Integrations**, elige **Activate** en la integración **Hellotext**, luego **Allow**, y confirma en la ventana de Hellotext que abre Magento.
+
+## Confirma la conexión
+
+1. En **Confirma la conexión**, revisa que la dirección sea la de tu tienda y elige **Confirmar conexión**. Confirma solo si iniciaste la conexión tú mismo: la tienda enviará su actividad a este negocio.
+2. Si el website tiene varias store views, elige la que Hellotext usará para nombres y enlaces de producto. La conexión cubre todo el website.
+3. Hellotext muestra **Verificando Magento** mientras configura el módulo y verifica la tienda. La página se actualiza sola.
+4. Al terminar verás **Magento está conectado**. En **Estado** aparecen la última verificación, la versión del módulo, la versión de Magento y PHP, y los productos importados.
+
+## Importa tus clientes existentes
+
+1. Elige **Siguiente**. En **¿Quieres importar tus clientes existentes?**, elige **Sí, importar mis clientes existentes a Hellotext** o **Ahora no. Lo haré más tarde.**
+2. Si importas, en **Organiza a tus clientes** elige las listas para los clientes nuevos y si quieres actualizar sus propiedades existentes; luego inicia la importación.
+3. La importación sigue aunque cierres la página. Puede tardar algunos minutos en empezar según la carga de Hellotext. Al terminar verás cuántos clientes se importaron.
+
+Cada importación crea una lista **Magento import** con los clientes que trajo.
+
+## Muestra tus widgets en la tienda
+
+Con la tienda conectada, cada widget ofrece instalarse automáticamente en Magento:
+
+- **Popup:** en el paso de instalación del popup, elige **Instalación automática en Magento** y publícalo.
+- **Webchat o widget de WhatsApp:** en su configuración de instalación, elige **Instalación automática en Magento** e instálalo.
+
+El módulo carga Hellotext.js en todas las páginas de la tienda, así que el widget aparece sin agregar código. Si instalas otro popup automáticamente, reemplaza al anterior.
+
+## Verifica que todo funcione
+
+- **En la tienda:** abre un producto y agrégalo al carrito. Si un comprador inicia sesión, se identifica con su cuenta de Magento.
+- **En Hellotext:** abre **Audiencia**, busca al cliente y revisa su **Actividad**: allí aparecen sus órdenes con su referencia de Magento y su total, y luego su confirmación, envío, cancelación o reembolso.
+- **En el servidor:** ejecuta `bin/magento hellotext:diagnose --store=<código de store view>`. Muestra la versión del módulo, la integración activa, si hay clave de instalación y Business ID configurados, el API de Hellotext y si la identificación está activa. Agrega `--ping` para comprobar que el servidor llega al API de Hellotext.
+
+Una orden de la tienda se registra cuando el comprador llega a la página de confirmación. Si cierra el navegador antes, se registra con su siguiente cambio de estado; una orden con pago pendiente puede no aparecer hasta que cambie.
+
+## Desconecta o desinstala
+
+Para desconectar, abre **Configuración > Integraciones**, abre el menú de la tienda Magento, elige **Eliminar** y confírmalo con **Eliminar**. Hellotext apaga el módulo en la tienda y borra sus credenciales: la tienda deja de enviar actividad y los widgets dejan de mostrarse. Para volver a conectarla, repite la instalación con un código nuevo.
+
+Para quitar el módulo de la tienda, ejecuta en la raíz de Magento:
+
+```bash
+bin/magento module:uninstall Hellotext_Tracking --remove-data
+```
+
+Desde la versión 1.0.2 del módulo, este comando también elimina la integración Hellotext de Magento, su token de acceso y la configuración del módulo. Con la versión 1.0.1 o anterior, elimina además la integración **Hellotext** en **System > Extensions > Integrations**.
+
+## Soluciona problemas
+
+- **"La URL configurada de Magento no está permitida."** La tienda debe usar un dominio público con HTTPS en el puerto 443. Corrige la URL base de Magento y conecta de nuevo.
+- **"Magento no pudo ser contactado en este momento."** Revisa que la tienda responda por HTTPS y que un firewall, WAF o CDN no bloquee las solicitudes a `/rest`. Luego elige **Aplicar la configuración de nuevo** o **Verificar conexión**.
+- **"Magento rechazó las credenciales de autorización."** El acceso de Hellotext se revocó en Magento. Vuelve a vincular la tienda: ejecuta el último comando de la pantalla de Magento con un código nuevo, o elige **Reauthorize** en la integración Hellotext de Magento Admin. La conexión conserva su clave de instalación.
+- **El código de vinculación venció o fue rechazado.** Recarga la página de Hellotext y ejecuta el último comando nuevo.
+- **La tienda no registra actividad.** Ejecuta `bin/magento hellotext:diagnose` y revisa que el Business ID esté configurado. Despliega el contenido estático y limpia la caché después de instalar o actualizar el módulo. Si usas Cookie Restriction Mode, la actividad empieza cuando el visitante acepta las cookies.
+- **La importación de clientes no avanza.** Corre en segundo plano y puede esperar unos minutos en la cola. Si no termina, comparte con soporte la hora y el negocio.
+
+Al pedir ayuda a soporte de Hellotext, comparte la salida de `bin/magento hellotext:diagnose --store=<código de store view>`, la versión de Magento y del módulo, la hora del problema y el mensaje exacto. No compartas tokens, contraseñas ni el código de vinculación.
+
+## Guías relacionadas
+
+- [Resumen de configuración e integraciones]({% link _integrations/setup-overview.md %})
+- [Sincronización del catálogo de productos]({% link _integrations/product-catalog-sync.md %})
+- [Verifica tus datos y señales después de la configuración]({% link _integrations/verify-data-and-signals.md %})
+- [Cómo funcionan los perfiles de clientes]({% link _audience/customer-profiles.md %})

_i18n/es/integrations/setup-overview.md

@@ -36,6 +36,7 @@ Elige la guía que corresponde a tu tienda:
 - [Conecta Wix]({% link _integrations/connect-wix.md %})
 - [Conecta WooCommerce]({% link _integrations/connect-woo.md %})
 - [Conecta VTEX]({% link _integrations/connect-vtex.md %})
+- [Conecta Magento]({% link _integrations/connect-magento.md %})
 - [Conecta Mercado Libre]({% link _integrations/connect-mercado-libre.md %})
 
 Después de conectar, elige un registro conocido de la fuente y comprueba sus datos en Hellotext antes de crear misiones, rutas o campañas basadas en ellos. Revisa por separado el perfil, el objeto y el evento real: un pedido guardado no confirma que se haya registrado una compra ni que se atribuya una venta. El alcance y el procesamiento inicial varían según la plataforma.