Segmentados DocsSegmentados Docs

HubSpot

Conecta HubSpot con una única Service Key (clave de servicio). Permite activar segmentos en listas estáticas (usar una existente o crear una nueva al activar), traer contactos y empresas hacia la plataforma, y traer el engagement de email (aperturas, clics, rebotes) como actividad de cada contacto.

Ideal para: Para campañas, workflows y personalización en HubSpot, importar tu base de contactos/empresas, y enriquecer los segmentos con el comportamiento de email.

Datos que necesita

  • Service Key * — La clave de servicio de HubSpot (Settings → Integrations → Service Keys). Es lo único que se carga en la conexión; qué lista usar o qué entidad importar se elige después. (También funciona con un Private App token legacy: ambos son bearer tokens.)

Cómo conectarlo

  1. En HubSpot, creá una Service Key con los scopes indicados y copiá la clave.
  2. En Segmentados (Setup → Integraciones → HubSpot), creá una conexión y pegá la Service Key.
  3. Probá la conexión; luego usá “Traer datos", “Ingesta de engagement" y/o la activación de segmentos.

Permisos (scopes)

crm.lists.readListar las listas estáticas existentes (elegir destino al activar).
crm.lists.writeCrear listas nuevas y agregar/quitar contactos al activar un segmento.
crm.objects.contacts.readLeer contactos al “traer datos".
crm.objects.contacts.writeModificar la membresía de listas por contacto (activación).
crm.objects.companies.readLeer empresas al “traer datos".
crm.schemas.contacts.readDescubrir las propiedades de contacto para el mapeo de campos.
crm.schemas.companies.readDescubrir las propiedades de empresa para el mapeo de campos.
content (solo engagement)Traer aperturas/clics/rebotes de email. Requiere Marketing Hub; si no, omitilo y el resto funciona igual.

Guía paso a paso

A — Generar las credenciales en HubSpot (Service Key)

  1. Tu usuario de HubSpot debe ser Super Admin. La clave es por cuenta (portal): si manejás varias cuentas, repetí esto en cada una.
  2. Arriba a la derecha, hacé clic en el ícono de engranaje ⚙ (Settings).
  3. En el menú lateral izquierdo, andá a Integrations → Service Keys (o desde la barra principal: Development → Keys → Service Keys).
  4. Hacé clic en Create a service key.
  5. Ponele un nombre identificable (por ejemplo, “Segmentados").
  6. Agregá los scopes de la tabla de arriba (agregá “content" solo si vas a usar la ingesta de engagement).
  7. Creá la clave y, al instante, copiala (HubSpot la muestra una sola vez). Guardala de forma segura: es secreta, equivale a una contraseña.
  8. Nota: HubSpot ahora recomienda Service Keys en lugar de Private Apps para acceso de una sola cuenta. Si tu cuenta solo te ofrece Private Apps, el token de una Private App también sirve (se pega en el mismo campo).

B — Cargar y probar la conexión en Segmentados

  1. Andá a Setup → Integraciones y hacé clic en la tarjeta HubSpot.
  2. Hacé clic en + Nueva conexión.
  3. Nombre: una etiqueta interna (por ejemplo, “HubSpot — Cuenta principal").
  4. Private App Token: pegá el token pat-... y guardá.
  5. Hacé clic en Probar: debe decir “Conexión OK". Si falla (401/403), revisá el token y los scopes.
  6. Para actualizar el token más adelante: Editar la conexión, pegar el nuevo token y guardar (si dejás el campo en blanco, se conserva el anterior).

C — Traer datos (contactos y empresas)

  1. En el detalle del conector HubSpot, panel “Traer datos" → + Nuevo import.
  2. Entidad a importar: Contactos (destino por defecto CustomerProfiles) o Empresas (destino: un custom object existente).
  3. Objeto destino: confirmá/elegí la tabla destino en Segmentados.
  4. Campo clave (origen) → Columna clave (destino): definen el upsert. Ejemplo para contactos: email → Email.
  5. Mapeo de campos: agregá pares HubSpot → Segmentados (por ejemplo firstname → FirstName, lastname → LastName, phone → Phone).
  6. Frecuencia: Manual, Cada hora, Diaria o Semanal. Las no-manuales corren solas (~cada 15 min).
  7. Crear import. Para traer datos al instante, usá “Ejecutar ahora". Los registros quedan disponibles para reglas de segmento y campañas.

D — Traer engagement (aperturas/clics)

  1. En el panel “Ingesta de engagement", hacé clic en “Ejecutar ingesta ahora" (o dejá que corra el proceso automático, ~cada 6 h).
  2. Se traen los eventos de email (SENT, OPEN, CLICK, BOUNCE, etc.) y se asocian a cada contacto por email.
  3. Importante: el evento solo se guarda si el contacto ya existe en Segmentados; conviene correr primero el import de contactos.
  4. Requiere Marketing Hub y el scope “content".

E — Activar un segmento en HubSpot

  1. Abrí un segmento y agregá un destino de activación.
  2. Plataforma: HubSpot (aparece solo si ya hay una conexión).
  3. Conexión: elegí la conexión HubSpot.
  4. Destino: “Usar uno existente" (elegí una lista del desplegable) o “Crear uno nuevo en el destino" (ingresá un nombre; se crea la lista en HubSpot y se guarda su id).
  5. Guardá. La sincronización agrega/quita contactos de la lista según la membresía del segmento.

Solución de problemas

  • “Probar" devuelve 401 (Unauthorized): La Service Key es inválida o está mal pegada. Copiala de nuevo desde HubSpot (Service Keys) y actualizá la conexión.
  • Una acción devuelve 403 (Forbidden): Falta un scope en la Service Key. Agregá el scope correspondiente, guardá en HubSpot y reintentá.
  • La ingesta de engagement falla: La cuenta debe tener Marketing Hub y la Service Key el scope “content".
  • No aparecen propiedades en el mapeo: Falta crm.schemas.contacts.read / crm.schemas.companies.read.
  • HubSpot no aparece al activar un segmento: Primero creá (y probá) una conexión HubSpot en Setup → Integraciones.

💡 Sugerencia: En Segmentados primero creás la conexión (solo el token). Qué lista usar o qué importar se elige después y se puede cambiar sin volver a cargar credenciales.