Última modificación: 22 de agosto de 2025

Run in Postman

 Las extensiones del CRM permiten que la información de otros sistemas aparezca en los registros de contacto, empresa, negocio o ticket de HubSpot. Los endpoints de eventos de cronología permiten lograrlo mediante la creación de eventos personalizados en la cronología. Si prefieres que los usuarios puedan editar tus datos, pero ninguno de los objetos predeterminados del CRM se ajusta a tus necesidades, puedes considerar el uso de objetos personalizados.
event_expanded-2
Por ejemplo, supongamos que deseas segmentar mejor a los contactos según las interacciones con tu empresa y el contenido. Para hacer esto, necesitas más información sobre ellos. La aplicación puede crear eventos personalizados (por ejemplo, contactos que se registraron pero no asistieron a un webinario reciente, variantes de un flujo de registro que un contacto haya completado, etc.) para proporcionar mayor contexto sobre las interacciones de los contactos con la empresa.

​
Creación de una plantilla de eventos

Antes de comenzar a crear eventos, debes crear una plantilla de evento. Las plantillas de evento describen las acciones que la aplicación agregará a la cronología 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 evento. Las plantillas de evento se crean para los contactos de forma predeterminada, pero pueden crearse para empresas o negocios usando el campo objectType. Puedes encontrar más información en la sección de la creación de una plantilla de evento de cronología. Cada plantilla de evento 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 del video”.”

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

Para este ejemplo, crearemos una nueva plantilla de evento llamada “Ejemplo de registro en webinario”. Para la 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 el ID de tu aplicación, este 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 clave de API de desarrollador, que puedes encontrar en Aplicaciones > Obtener clave de API de HubSpot. Las propiedades headerTemplate y detailTemplate también se pueden encuentran aquí. Para más información, consulta la sección Definir las plantillas de encabezado y detalle 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 para una aplicación mediante el 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 cronología, también puedes administrar plantillas de eventos en tu cuenta de desarrollador de HubSpot. En la configuración de tu aplicación, dirígete a Eventos de cronología, 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í.
example-app
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.
new-timeline-event-template
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 la 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 ver estos cambios reflejados en HubSpot.

​
Definir tokens de eventos

Una vez que hayas definido una plantilla de evento, probablemente quieras definir sus tokens. Los tokens de plantillas de evento te permiten adjuntar datos personalizados a eventos que se pueden mostrar en la cronología o usar en la automatización de workflows. En el caso de los contactos, también pueden utilizarse para la segmentación de listas. Puedes crear hasta 500 tokens por plantilla de evento de cronología.

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

Usando el ID de la 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>>'
Del mismo modo, una solicitud 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 un conjunto de opciones. Consulta el ejemplo anterior de webinarType.
  • 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 para Handlbars.js, la biblioteca 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 cronología. 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 {{webinarName}} El extraData de un evento (que se describe más adelante en “Comprender extraData”) solo se puede referenciar 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 endpoints de plantillas de eventos. Por ejemplo, podemos agregar plantillas a nuestro ‘Ejemplo de registro en un webinario’ modificándolo 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>>'
Ten en cuenta el uso de la directiva #formatDate es algo que hemos definido para permitir un formato de fecha fácil de usar. Una vez que se crea un evento para un contacto usando esto (ver “Creación de un evento” abajo), esto es lo que se mostrará en la cronología del contacto:
event_collapsed.png
Al hacer clic en “Mostrar detalles”, muestra la plantilla de detalles:
event_expanded.png
Para definir el ícono que se muestra junto a los eventos, consulta la “Configuración de un ícono personalizado” abajo. El texto anterior “Ejemplo de nombre de aplicación” es el nombre de la aplicación. En la cronología 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 sola 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 la plantilla de evento está configurada con tokens y plantillas, estamos listos para crear eventos para los contactos, empresas, negocios y tickets de nuestros clientes. En los ejemplos a continuación asume que estamos trabajando con la plantilla de eventos contacts creada 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. Aquí tienes un ejemplo de solicitud POST para crear un evento:

​
Nota:

Las claves API de desarrollador y los tokens de acceso a aplicaciones privadas no se pueden utilizar como método de autenticación al crear eventos. Para crear un evento, la cuenta de HubSpot asociada debe otorgar acceso a la 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 cronología de a.test.contact@email.com (suponiendo que se usan las plantillas de la sección anterior ‘Definición de plantillas’):
event_collapsed.png

​
Establecer la marca de tiempo del evento

La marca de tiempo del evento determina dónde aparecerá el evento en la cronología 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 proporcionándola 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 sugerido si conoces 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 una marca de tiempo EPOCH en milisegundos o el formato ISO 8601.

​
Asociación de un evento con un objeto del CRM

Para crear un evento, debes poder asociar el evento a un contacto, empresa o negocio en la cuenta del cliente. En los ejemplos anteriores, el objectType se estableció como contacto y usamos el correo electrónico para asociar el evento al 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 cómo transferir los datos del evento a las propiedades del contacto para agregar información adicional. 
// {
  "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 utilizar el vid de 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. En este ejemplo, se utiliza el objectId en lugar del 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 hubspotutk. Usa el parámetro utk para asociar un evento a un contacto por usertoken. Ten en cuenta que no es posible asociar eventos con visitantes anónimos usando el usertoken. Si el evento solo está asociado con el utk y el usertoken proporcionado no está asociado con un contacto, no se creará un nuevo contacto y el evento no será visible en HubSpot. Sin embargo, el evento aparecerá en la cronología 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 email además del 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 email, objectId y utk puede incluirse. Si se incluyen varios parámetros, el objectId (vid) tendrá mayor prioridad al determinar qué contacto asociar con el evento, seguido de utk y luego email con 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 email con la 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 utilizar objectId para asociar el evento con la empresa o negocio. Para empresas, el objectId debe establecerse con el companyId de la empresa con la que deseas asociar el evento, y para negocios debes establecer objectId con el dealId del objeto del negocio. En el siguiente ejemplo, suponiendo que la plantilla de evento se configuró en el objectType COMPANY, este evento se asociaría con el objeto de la empresa con companyId 528253914: 
// {
  "eventTemplateId": "<<eventTemplateId>>",
  "objectId": "3001",
  "tokens": {
    "dealProperty": "Custom property for deal"
  }
}

​
Extensiones de cronología

La característica de extensiones de cronología se puede usar para mostrar datos de un sistema externo usando un iFrame. Cuando se incluyan, el evento mostrará un enlace que abrirá una ventana modal con el contenido de iFrame al hacer clic. Los detalles de iFrame se definen 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 del IFrame.
  • url: la URI del contenido del 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 que muestra la página establecida en la url:
iframe_modal.png

​
Transferencia de los datos de eventos a las propiedades de objetos del CRM

En muchos casos, querrás modificar las propiedades de los contactos, empresas y negocios a los que estás agregando eventos. Esto suele suceder en casos cuando la creación del evento genera un nuevo contacto: probablemente quieras actualizar las propiedades de nombre y apellido para no terminar con un contacto que solo tenga una dirección de correo electrónico y un evento asociado. Puedes transferir datos al objeto asociado desde un evento mediante la asignación de los tokens personalizados del evento a propiedades del contacto, empresa o negocio. Considera usar el 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 utiliza objectPropertyName para asignar el token del evento personalizado a la propiedad zz_webinar_name del objeto contact. Esto significa que cuando creamos un nuevo evento que especifique el token webinarName, también se establecerá la propiedad zz_webinar_name del contact asociado. Puedes establecer estas propiedades de HubSpot como personalizadas o predefinidas. Por ejemplo, supongamos que ya creamos el token companyName que hace referencia a la propiedad personalizada zz_company_name en el contacto. La creación de un evento como este hace que se establezcan las propiedades zz_company_name y zz_webinar_name 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 transfiere a una propiedad personalizada y esa propiedad personalizada no está presente en la cuenta de HubSpot, el valor seguirá para el evento, pero será ignorado para el objeto correspondiente.

​
Comprender la extraData

Es posible que debas agregar datos detallados a un evento que no se adapta a la estructura de 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 la extraData. Puedes agregar un atributo extraData al cuerpo JSON de un evento. El valor de 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 de 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 cronología que luce así:
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 ícono personalizado

Para agregar un atractivo visual a la cronología, deberás agregar un ícono personalizado. Este archivo de imagen para este ícono debe:
  • Tener dimensiones aproximadamente cuadradas
  • Tener un fondo transparente
  • Tener el contenido en el centro del ícono
  • Poderse reducir en tamaño hasta 30 x 30 píxeles
  • Tener un tamaño de archivo de 5 MB o menos
Para establecer el ícono para los eventos de cronología, dirígete a la opción Eventos de la cronología. Haz clic en la imagen del marcador de posición o el ícono existente para configurarlo o actualizarlo.
timeline_assets
Una vez que establezcas el o los íconos, se mostrarán junto a todos los eventos de la cronología asociados a esta aplicación:
timeline_icon.png

​
Límites de la instancia del evento

Al crear un evento, cada instancia de evento serializada está sujeta a los siguientes límites de tamaño:
  • 500 bytes para el ID de la instancia del evento
  • 510 KB por propiedad y token
  • 1 MB de tamaño total para la instancia del evento

​
Documentos relacionados

Comprender el CRM Tarjetas del CRM