Usa las guías para desarrolladores cuando necesites conectar Hellotext con tu sitio, backend, CRM, plataforma de comercio o herramientas internas.
Si vas a conectar una tienda propia sin una integración nativa, comienza con Integra una tienda propia con Hellotext. Presenta perfiles, propiedades, productos, pedidos históricos, Hellotext.js, identidad y seguimiento desde el servidor en el orden de implementación correcto.
La mayoría del trabajo técnico con Hellotext cae en seis áreas:
- Integrar una tienda propia de principio a fin.
- Leer la referencia de la API.
- Enviar mensajes desde tu propio sistema.
- Registrar actividad de clientes.
- Definir acciones y objetos específicos del negocio.
- Conectar sesiones no identificadas con perfiles de clientes.
Antes de implementar, decide qué parte ejecutará tu servidor y qué parte ejecutará el navegador:
| Parte de la integración | Datos que usa |
|---|---|
| Servidor | Token privado del negocio para autenticar la API. |
| Navegador | ID público del negocio para inicializar Hellotext.js. |
| Sincronización | IDs de Hellotext y referencias de tu sistema para identificar cada recurso. |
Integración de una tienda propia
La guía para tiendas propias es el punto de partida práctico para un equipo que todavía no sabe qué datos debe enviar mediante la API, qué actividad debe registrar con Hellotext.js o cómo se conectan ambos lados.
Empieza aquí: Integra una tienda propia con Hellotext.
Referencia de la API
La referencia de la API es la fuente de verdad para recursos, atributos, parámetros y endpoints disponibles.
Abre la referencia de la API de Hellotext. Revisa el recurso, método, campos requeridos, tipos de datos, errores y paginación antes de implementar una receta. Guarda los IDs devueltos por Hellotext junto con las referencias de tu propio sistema; un nombre visible no sustituye el ID que pide un endpoint.
Recetas de implementación con la API
Usa las guías prácticas de la API cuando necesites pasar del contrato de un endpoint a un flujo de integración completo:
- Envía mensajes con la API
- Crea y envía plantillas con la API
- Sincroniza productos y entiende la disponibilidad de inventario
- Crea y registra pedidos con la API
- Crea y registra cupones con la API
- Soluciona una integración propia
Autenticación
Las solicitudes a la API privada usan bearer tokens específicos del negocio donde se crearon. Confirma primero que estás en el negocio que quieres integrar.
Abre Ajustes, selecciona Administrar tokens de autorización y luego Crear token nuevo. Asigna un nombre que identifique la integración. El ejemplo muestra únicamente un nombre ficticio sin guardar; no contiene una credencial ni confirma que se haya creado un token.
Después de completar la creación en tu propio negocio, guarda el token en la configuración privada de tu servidor y envíalo en el header Authorization:
Authorization: Bearer TU_TOKEN
Nunca expongas tokens privados en código del navegador, repositorios públicos o scripts del lado del cliente. El ID del negocio usado por Hellotext.js es público y cumple otra función: no autentica las solicitudes de la API privada. No confundas ese ID, el nombre del token y el valor secreto del token.
Envía mensajes desde tu sistema
Usa la API de mensajes cuando tu propio sistema necesite enviar un mensaje individual libre o con plantilla mediante un canal compatible. Comprueba la conexión del canal, los permisos, el consentimiento del destinatario y las reglas de plantillas o de la ventana de conversación que correspondan al canal.
Una respuesta status: received confirma la recepción de la solicitud, no la entrega del mensaje. Verifica su resultado en Hellotext antes de asumir que se envió; no repitas un envío sólo porque tu sistema no recibió una respuesta a tiempo.
Comienza con Envía mensajes con la API. Para conocer longitud, codificación, costos y límites específicos de SMS, consulta Enviar SMS con la API.
Registra actividad de clientes
Usa el seguimiento de eventos cuando quieres que Hellotext entienda acciones desde tu sitio, tienda, backend o integración personalizada.
Registra la navegación y la interacción del visitante con Hellotext.js cuando el origen sea el navegador. Registra desde tu backend los hechos que ese servidor confirma, como un pago. Define una sola fuente por ocurrencia para evitar duplicar el mismo evento.
Los eventos rastreados pueden ayudarte a segmentar audiencias, activar misiones o rutas, atribuir ingresos y darle más contexto al equipo de Bandeja. Cada resultado depende de sus datos y configuración: una solicitud recibida no prueba que el evento ya se haya procesado ni que haya atribuido una venta.
Sigue leyendo: Seguimiento de eventos para entender la inicialización y el registro explícito. Para una instalación nueva con el SDK 2.6.0, sigue también los pasos de instalación y actividad del navegador en la guía de tienda propia enlazada arriba: espera la inicialización y registra page.viewed explícitamente una vez por navegación, sin duplicar la primera vista.
Modela actividad específica del negocio
Usa acciones personalizadas para nombrar actividad que Hellotext no incluye de forma preestablecida. La acción define el tipo de actividad; el evento registra una ocurrencia concreta. Por ejemplo, definir appointment.booked no registra una cita.
En Ajustes > Acciones > Personalizado, el nombre legible «Cita reservada» y el nombre de seguimiento appointment.booked representan la misma definición ficticia. Los eventos usan el nombre de seguimiento exacto; los endpoints que administran la definición usan su ID. Crear acciones personalizadas requiere un plan y permisos compatibles.
Usa una propiedad del perfil cuando el dato describe un estado actual del cliente, como su nivel de fidelidad. Usa objetos cuando la actividad involucra una entidad reutilizable con propiedades y ciclo de vida propios, como una cita con referencia, fecha y estado.
Sigue leyendo: Acciones personalizadas y Objetos.
Conecta sesiones del navegador con perfiles de clientes
Hellotext.js puede crear una sesión para visitantes no identificados. Para conectar su actividad anterior, usa el ID de la sesión real del navegador y el ID del perfil correcto en ese mismo negocio. Verifica la identidad del cliente con tu propio sistema antes de adjuntar la sesión; no asignes un perfil a partir de un ID arbitrario recibido del navegador.
Identificar un perfil y adjuntar una sesión no concede consentimiento para enviar mensajes. Tampoco registra por sí solo una compra ni garantiza atribución: esas operaciones tienen sus propios requisitos.
Sigue leyendo: Seguimiento de clientes no identificados.