Eventos en la línea de tiempo

ResumenPuntos de terminación

Las extensiones de CRM permiten que la información de otros sistemas aparezca en los objetos de contacto, empresa o negocio de HubSpot. Los puntos de terminación de los eventos de línea de tiempo te permiten hacer esto creando eventos de línea de tiempo personalizados. Si quieres que tus datos sean editables por los usuarios, pero ninguno de los objetos CRM predeterminados satisface tus necesidades, puedes considerar el uso de objetos personalizados.

event_expanded-2Por ejemplo, supongamos que deseas segmentar mejor tus contactos según sus interacciones con tu empresa y su contenido. Para ello, necesitas más información sobre ellos. Tu aplicación puede crear eventos personalizados (contactos que se registraron, pero no asistieron a un webinario reciente, qué variante de un flujo de registro completó un contacto, etc.) que te proporcionen más contexto sobre las interacciones que los contactos tengan con tu empresa.

Creación de una plantilla de eventos

Antes de comenzar a crear eventos, debes crear una plantilla de evento. Las plantillas de eventos describen las acciones que tu aplicación agregará a la línea de tiempo de un objeto de contacto, empresa o negocio en HubSpot. Ejemplos de estas acciones incluyen ver un video, registrarse para un webinario o completar una encuesta. Una sola aplicación puede crear hasta 750 plantillas de eventos.

Las plantillas de eventos se crean para contactos por opción predeterminada, pero pueden crearse para empresas o negocios usando el campo objectType. Ver la creación de una plantilla de evento de la línea de tiempo para más detalles.

Cada plantilla de eventos tiene su propio conjunto de tokens y plantillas. Puedes usar eventos creados para contactos como criterio al crear listas o workflows para contactos nuevos, tales como 'Crear una lista de todos los contactos con un Video similar cuyo nombre contenga las letras XYZ’, en el que la plantilla de video se denomina «Video similar» y tiene un token de evento denominado «nombre de video».

Creación de plantillas de eventos a través de la API

Para este ejemplo, crearemos una nueva plantilla de evento «Ejemplo de Registro en Webinario». Para autenticación, usa la clave de API de desarrolladores que se encuentra en tu cuenta de desarrollador de aplicaciones.

curl -X POST -H "Content-Type: application/json" -d ' { "name": "Example Webinar Registration", "objectType": "contacts" }' \ 'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates?hapikey=<<developerAPIkey>>''

Asegúrate de reemplazar <<appId>> con tu propio ID de aplicación, que se puede encontrar tanto en las páginas de Mis aplicaciones como en las de detalles de la aplicación en tu cuenta de desarrollador. También tendrás que reemplazar <<developerHapikey>> con tu propia clave de API de desarrollador, que puedes encontrar navegando a Aplicaciones > Obtener la clave API de HubSpot.

Las propiedades headerTemplate y detailTemplate también se pueden proporcionar aquí. (Ver «Definición de plantillas» a continuación)

Esta solicitud POST devolverá la definición completa de la plantilla de eventos guardada. Asegúrate de tener en cuenta la propiedad id en esta respuesta. Este es el ID de la plantilla de eventos, que necesitarás para hacer cualquier actualización de esta plantilla o tokens de evento en el futuro.

Puedes ver todas las plantillas de eventos definidas para una aplicación mediante este comando GET, que también devolverá los ID de las plantillas de eventos:

curl -X GET 'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates?hapikey=<<developerAPIkey>>'

Creación de plantillas de eventos en HubSpot

Además de usar la API para crear y administrar plantillas de eventos de línea de tiempo, también puedes administrar plantillas de eventos en tu cuenta de desarrollador de HubSpot.

En la configuración de tu aplicación, navega a Eventos de la línea de tiempo y usa el botón “Crear tipo de evento” para crear una nueva plantilla de evento para esta aplicación. Si has creado plantillas de eventos antes, también las verás aquí.

image (3)-Jul-23-2020-10-02-24-50-PM

Comenzarás con un borrador de tu nueva plantilla de eventos. Una vez que hayas establecido el tipo de objeto y las plantillas de detalles y encabezado para el evento, haz clic en «Crear».

image (4)-Jul-23-2020-10-02-24-66-PM

Cuando creas o editas tu plantilla de eventos, establece los tokens que deseas usar con la plantilla en la pestaña Datos.

data-tab-1

Nota: Si eliminas una plantilla, una vez eliminada, los eventos existentes que usen esa plantilla se eliminarán permanentemente de las cuentas con tu aplicación conectada. Ya no podrás crear nuevos eventos de este tipo, pero aún verás los datos de eventos ya existentes en listas e informes. Puede tardar varias horas para ver estos cambios reflejados en HubSpot.

Definir tokens de eventos

Una vez que hayas definido una plantilla de evento, probablemente desees definir sus tokens. Los tokens de plantillas de eventos te permiten adjuntar datos personalizados a eventos que se pueden mostrar en la línea de tiempo o usar para segmentación y automatización de listas. Puedes crear hasta 500 tokens por plantilla de evento de línea de tiempo.

Nota: los eventos de empresa y negocio no se pueden utilizar en la segmentación o automatización de listas.

Creación de tokens de eventos a través de la API

Usando el ID de plantilla de evento creado en el paso 1, agregaremos algunos tokens para identificar el webinario para el que se registraron nuestros contactos.

curl -X POST -H "Content-Type: application/json" -d ' { "name": "webinarName", "label": "Webinar Name", "type": "string" }' \ 'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates/<<eventTemplateId>>/tokens?hapikey=<<developerHapikey>>' curl -X POST -H "Content-Type: application/json" -d ' { "name": "webinarId", "label": "Webinar Id", "type": "string" }' \ 'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates/<<eventTemplateId>>/tokens?hapikey=<<developerHapikey>>' curl -X POST -H "Content-Type: application/json" -d ' { "name": "webinarType", "label": "Webinar Type", "type": "enumeration", "options": [ { "value": "regular", "label": "Regular" }, { "value": "ama", "label": "Ask me anything" } ] }' \ 'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates/<<eventTemplateId>>/tokens?hapikey=<<developerHapikey>>'

De manera similar, un GET devolverá todos los tokens definidos en una plantilla de evento:

curl -X GET -H "Content-Type: application/json" 'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates/<<eventTemplateId>>?hapikey=<<developerHapikey>>'

Los tipos de token admitidos incluyen:

  • string
  • number
  • enumeration — Una de las opciones. Ver el ejemplo del webinario anterior.
  • date — Todas las fechas deben estar en milisegundos en tiempo Unix.

Nota: los tokens de eventos no se pueden denominar log o lookup. Estos tokens están reservados como apoyo por Handlbars.js, la biblioteca utilizada para eventos dentro de la aplicación. Para obtener más información, echa un vistazo a los documentos de Handlebars.js aquí.

Definición de las plantillas de encabezado y de detalles

Las plantillas de encabezado y de detalles definen cómo mostrar un evento de línea de tiempo. Puedes especificar documentos de Markdown con plantillas Handlebars. La plantilla de encabezado debe ser una descripción de una línea del evento; y la plantilla de detalles es la vista detallada del evento (ejemplos a continuación).

Los tokens de eventos se pasan como datos a las plantillas. Usando nuestro ejemplo, puedes hacer referencia al token webinarName en la plantilla usando .

Los extraData de un evento (que se comentan abajo en «Comprender extraData») solo pueden ser referenciados en la plantilla de detalles.

Definición de las plantillas de encabezado y de detalles a través de la API

Las plantillas de encabezado y de detalles pueden definirse en las plantillas de eventos a través de los puntos de terminación de plantillas de eventos. Por ejemplo, podemos agregar plantillas a nuestro «Ejemplo de Registro en Webinario» mediante su modificación con un PUT:

curl -X PUT -H "Content-Type: application/json" -d ' { "id": "<<eventTemplateId>>", "name": "Example Name Change", "headerTemplate": "Registered for [{{webinarName}}](https://mywebinarsystem/webinar/{{webinarId}})", "detailTemplate": "Registration occurred at {{#formatDate timestamp}}{{/formatDate}}" }' \ 'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates/<<eventTemplateId>>?hapikey=<<developerHapikey>>'

Nota que el uso de la directiva #formatDate — Es algo que definimos para dar formato de fecha sencillo para los usuarios.

Una vez que se crea un evento para un contacto usando esto (ver «Creación de un evento» abajo), aquí se mostrará lo que aparecerá en la línea de tiempo de ese contacto:

event_collapsed.png

Al hacer clic en «Mostrar detalles», muestra la plantilla de detalles:

event_expanded.png

Para establecer el icono que se muestra junto a los eventos, consulta «Configuración de un icono personalizado» abajo.

El texto «Ejemplo de nombre de aplicación» anterior es el nombre de la aplicación. En la línea de tiempo del CRM, los eventos se pueden filtrar por la aplicación.

 

Definición de todos los aspectos de una plantilla de eventos en una única llamada

Ahora que has visto cómo se define progresivamente cada aspecto de una plantilla de eventos, puedes definirlo todo al mismo tiempo en una llamada POST. 

curl -X POST -H "Content-Type: application/json" -d ' { "name": "Another Webinar Registration", "objectType": "contacts", "headerTemplate": "Registered for [{{webinarName}}](https://mywebinarsystem/webinar/{{webinarId}})", "detailTemplate": "Registration occurred at {{#formatDate timestamp}}{{/formatDate}}", "tokens": [ { "name": "webinarName", "label": "Webinar Name", "type": "string" }, { "name": "webinarId", "label": "Webinar Id", "type": "string" }, { "name": "webinarType", "label": "Webinar Type", "type": "enumeration", "options": [ { "value": "regular", "label": "Regular" }, { "value": "ama", "label": "Ask me anything" } ] } ] }' \ 'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates?hapikey=<<developerAPIkey>>'

Crear un evento

Ahora que una plantilla de evento está configurada con tokens y plantillas, estamos listos para crear eventos para los contactos, empresas, negocios y tickets de nuestros clientes. Los ejemplos a continuación asumen que estamos trabajando con la plantilla de eventos de contactos creados anteriormente. Si la plantilla de evento anterior no está configurada para tener los tokens webinarName y webinarId, recibirás un error al intentar crear el evento. Este es un ejemplo POST para crear un evento:

Nota: las claves API de desarrollador y los tokens de acceso a aplicaciones privadas no se pueden utilizar como autenticación al crear eventos. Para crear un evento, la cuenta de HubSpot asociada debe otorgar acceso a tu aplicación a través de OAuth. Una vez que obtengas un token de acceso de OAuth, puedes usarlo para agregar eventos a la cuenta.
curl -X POST -H "Content-Type: application/json" \ -H "Authorization: Bearer <<OAuth2AccessToken>>" \ -d ' { "eventTemplateId": "<<eventTemplateId>>", "email": "a.test.contact@email.com", "tokens": { "webinarName": "A Test Webinar", "webinarId": "001001", "webinarType": "regular" } }' \ 'https://api.hubapi.com/crm/v3/timeline/events'

Esto genera un evento en la línea de tiempo de a.test.contact@email.com (asumiendo las plantillas de «Definición plantillas» anteriores):

event_collapsed.png

Establecer la marca de tiempo del evento

La marca de tiempo del evento determina dónde aparecerá el evento en la línea de tiempo del objeto. Por opción predeterminada, la marca de tiempo del evento es cuando se envía el comando POST. Puedes personalizar la hora del evento proporcionando la solicitud en el cuerpo de la solicitud de una propiedad de marca de tiempo:

curl -X POST -H "Content-Type: application/json" \ -H "Authorization: Bearer <<OAuth2AccessToken>>" \ -d ' { "eventTemplateId": "<<eventTemplateId>>", "email": "a.test.contact@email.com", "timestamp": "2020-03-18T15:30:32Z", "tokens": { "webinarName": "A Test Webinar", "webinarId": "001001", "webinarType": "regular" } }' \ 'https://api.hubapi.com/crm/v3/timeline/events'

Este método es preferido si se conoce la hora exacta a la que ocurrió una acción. En este ejemplo, si tenemos la marca de tiempo para este registro de webinario, deberíamos proporcionarla en este POST.

Las marcas de tiempo pueden estar en milisegundos de hora Epoch o en formato ISO 8601.

Asociación de un evento con un objeto de CRM

Para crear un evento, debes poder asociar el evento con un contacto, empresa o negocio en la cuenta del cliente.

En los ejemplos anteriores, el objectType se estableció en contacto y usamos correo para asociar el evento con un contacto. Las direcciones de correo electrónico deben ser únicas para los contactos en HubSpot, por lo que si hay un contacto existente con el correo electrónico proporcionado, ese contacto se actualizará. Si no hay un contacto existente, se creará uno nuevo. Por opción predeterminada, este nuevo contacto solo tendrá la propiedad de contacto de correo electrónico proporcionada. Más información sobre marcación de los datos del evento en las propiedades del contacto para agregar datos adicionales a las propiedades de contactos.

// { "eventTemplateId": "<<eventTemplateId>>", "email": "a.test.contact@email.com", "tokens": { "webinarName": "A Test Webinar", "webinarId": "001001", "webinarType": "regular" } }

Si estás trabajando con contactos conocidos, también puedes usar el vid del contacto para asociar el evento. En esos casos, usarías objectId en la solicitud JSON. Debes incluir el vid de un contacto existente, ya que no podrás crear nuevos contactos usando objectId. Este ejemplo usa el objectId en lugar de correo electrónico:

// { "eventTemplateId": "<<eventTemplateId>>", "objectId": "29851", "tokens": { "webinarName": "A Test Webinar", "webinarId": "001001", "webinarType": "regular" } }

También puedes asociar un evento con un contacto por usertoken o utk. El usertoken es usado por el código de seguimiento de HubSpot para hacer seguimiento a los visitantes y se almacena en la cookie de hubspotutk. Usa el parámetro utk para asociar un evento con un contacto por usertoken. Nota: no es posible asociar eventos con visitantes anónimos usando usertoken, por lo que si el evento está asociado con solo el utk, y el usertoken proporcionado no está asociado ya con un contacto, no se creará un nuevo contacto y el evento no se sería visible en HubSpot. Sin embargo, el evento aparecerá en la línea de tiempo si un nuevo contacto se asoció con el usertoken a través de otro medio (generalmente a través de un envío de formulario incluido el hutk o a través del método de identificación de la API del código de seguimiento). Por esta razón, recomendamos incluir el correo electrónico además de los utk para asegurarnos de que el evento se asocia con un contacto nuevo o existente.

Si estás trabajando con una plantilla de evento para contactos, es posible incluir varios parámetros de identificación con el evento, por lo que cualquier combinación de los parámetros de correo electrónico, objectId y utk puede incluirse. Si se incluyen varios parámetros, el objectId (vid) tendrá la mayor prioridad al determinar qué contacto asociar con el evento, seguido de utk, siendo correo electrónico el de la prioridad más baja. Esto significa que puedes actualizar la dirección de correo electrónico de un objeto existente incluyendo una nueva dirección de correo electrónico en el parámetro vid de un objeto conocido en objectId. Este ejemplo usa la dirección de correo electrónico y el usertoken:

// { "eventTemplateId": "<<eventTemplateId>>", "email": "a.test.contact@email.com", "utk": "89b5afb740d41f4cd6651ac5237edf09" "tokens": { "webinarName": "A Test Webinar", "webinarId": "001001", "webinarType": "regular" }

Además de trabajar con contactos, también es posible crear plantillas de eventos para empresas y negocios. Para esas plantillas de eventos, debes usar objectId para asociar el evento con la empresa o negocio. Para empresas, el objectId debe establecerse en companyId de la empresa que deseas asociar con el evento, y para negocios debes establecer el objectId en el dealId del objeto del negocio.

En el siguiente ejemplo, asumiendo que la plantilla de evento se configuró en COMPANY objectType, este evento se asociaría con el objeto de la empresa con un companyId 528253914:

// { "eventTemplateId": "<<eventTemplateId>>", "objectId": "3001", "tokens": { "dealProperty": "Custom property for deal" } }

Extensiones de línea de tiempo

La característica extensiones de línea de tiempo se puede usar para mostrar datos de un sistema externo usando un iFrame. Cuando se incluyan, el evento mostrará un enlace que abra una ventana modal mostrando el contenido iFrame cuando se hace clic. Los detalles de iFrame se establecen en el campo timelineIFrame, que es un objeto que contiene los siguientes campos:

  • linkLabel - El texto utilizado para mostrar el enlace que mostrará el IFrame.
  • headerLabel - La etiqueta de la ventana modal que muestra el contenido de IFrame. 
  • url - La url del contenido de IFrame.
  • width - El ancho de la ventana modal.
  • height - La altura de la ventana modal.

Por ejemplo, usar estos datos para un evento:

// { "eventTemplateId": "<<eventTemplateId>>", "email": "a.test.contact@email.com", "tokens": { "webinarName": "A Test Webinar", "webinarId": "001001", "webinarType": "regular" }, "timelineIFrame": { "linkLabel":"View external data", "headerLabel":"Example iframe", "url":"https://www.example.com", "width":800, "height":300 } }

Crearía este evento, incluyendo el enlace «Ver datos externos»:

external_data_link.png

Al hacer clic en ese enlace, se abrirá una ventana modal mostrando la página establecida en la url:

iframe_modal.png

Marcación de los datos de eventos en las propiedades de objetos de CRM

En muchos casos, deberás modificar las propiedades para los contactos, empresas o negocios a los que estás agregando eventos. Esto suele suceder en casos en los que se creará un contacto al agregar el evento, probablemente deseas actualizar las propiedades de nombre y apellido en el contacto para que no solo crees un contacto con una dirección de correo electrónico y un evento.

Puedes marcar datos al objeto asociado desde un evento asignando tus tokens de evento personalizados a las propiedades de contactos, empresas o negocios.

Considera este comando PUT para actualizar una plantilla de evento personalizada, ten en cuenta el campo objectPropertyName:

curl -X PUT -H "Content-Type: application/json" -d ' { "label" : "Updated Webinar Name", "objectPropertyName": "zz_webinar_name" }' \ 'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates/<<eventTemplateId>>/tokens/<<tokenName>>?hapikey=<<developerHapikey>>'

Esto usa objectPropertyName para asignar este token de evento personalizado al objeto del contacto en la propiedad zz_webinar_name . Esto significa que cuando creamos un evento nuevo que especifique un token webinarName, la propiedad zz_webinar_name del contacto asociado también se establecerá. Puedes establecer estas propiedades de HubSpot en valores personalizados o predefinidos.

Por ejemplo, supongamos que ya creamos un token companyName que hace referencia a una propiedad personalizada zz_company_name en el contacto. Luego, crear un evento como este hace que las propiedades zz_company_name y zz_webinar_name se establezcan en el contacto con la dirección de correo electrónico. a.test.contact@email.com:

curl -X POST -H "Content-Type: application/json" \ -H "Authorization: Bearer <<OAuth2AccessToken>>" \ -d ' { "eventTemplateId": "<<eventTemplateId>>", "email": "a.test.contact@email.com", "tokens": { "webinarName": "Test Webinar will update contact property", "companyName": "TestCo", "webinarId": "001001", "webinarType": "regular" } }' \ 'https://api.hubapi.com/crm/v3/timeline/events'

set_property.png

Nota: si un token de evento se marca en una propiedad personalizada y esa propiedad personalizada no está presente para una cuenta de HubSpot, el valor seguirá establecido para el evento, pero será ignorado para el objeto correspondiente.

Comprender extraData

Es posible que debas agregar datos detallados a un evento que no se ajusta a la sencilla estructura token-valor utilizada por los tokens de las plantilla de eventos. Es posible que debas agregar una lista o algunos desgloses jerárquicos a un evento de integración. Aquí es donde entra extraData.

Puedes agregar un atributo extraData al cuerpo JSON del evento. El valor de este extraData puede ser cualquier JSON válido. Por ejemplo:

curl -X POST -H "Content-Type: application/json" \ -H "Authorization: Bearer <<OAuth2AccessToken>>" \ -d ' { "eventTemplateId": "<<eventTemplateId>>", "email": "a.test.contact@email.com", "tokens": { "webinarName": "Test Webinar will update contact property", "companyName": "TestCo", "webinarId": "001001", "webinarType": "regular" }, "extraData": { "pollData": [ { "question": "How excited are you for this webinar?", "answer":"Quite!" }, { "question": "How frequently do you use our product?", "answer":"Daily" } ], "coWorkers": [ { "name": "Joe Coworker", "email":"joe.coworker@testco.com" }, { "name": "Jane Coworker", "email":"jane.coworker@testco.com" } ] } }' \ 'https://api.hubapi.com/crm/v3/timeline/events'

Un ejemplo del uso de extraData en una plantilla de detalles:

// Registration occurred at {{#formatDate timestamp}}{{/formatDate}} #### Poll Questions {{#each extraData.pollData}} **{{question}}**: {{answer}} {{/each}} #### Co-Workers {{#each extraData.coWorkers}} * {{name}} {{/each}}

Esto creará un evento de línea de tiempo que luce como esto:

extra_data.png

Nota: solo se puede hacer referencia al atributo extraData en la plantilla de detalles de un evento. No se puede usar ni en la plantilla de encabezado ni en la segmentación de listas.

Configurar un icono personalizado

Para agregar un atractivo visual a tus elementos de línea de tiempo, deberás agregar un icono personalizado.

Este archivo de imagen para este icono debe:

  • Tener dimensiones aproximadamente cuadradas
  • Tener un fondo transparente
  • Tener el contenido en el centro del icono
  • Poder reducir el tamaño de hasta 30 x 30 píxeles
  • Tener un tamaño de archivo de 5 MB o menos

Para establecer el icono utilizado para eventos de línea de tiempo, navega a Eventos de línea de tiempo. Haz clic en la imagen del marcador de posición o el icono existente para configurarlo o actualizarlo.

timeline_assets

Una vez que establezcas el(los) ícono(s), se mostrarán junto a todos los eventos de la línea de tiempo asociados con esta aplicación:

timeline_icon.png

Documentos relacionados

Comprender el CRM

Tarjetas CRM

¿Te resultó útil este artículo?
Con este formulario puedes enviar tu opinión sobre nuestros documentos para desarrolladores. Si tienes comentarios sobre el producto de HubSpot, puedes enviarlos al Foro de ideas.