Enviar ocurrencias de eventos (BETA)

Tras definir un esquema de tipo de evento y recuperar su fullyQualifiedName, puedes enviar datos de ocurrencia de eventos a través de la API de eventos de la aplicación. Cuando envíes datos de eventos, tendrás que respetar el esquema que creaste anteriormente. Las solicitudes que no coincidan con el esquema fallarán en la validación y no serán capturadas por la aplicación.

Envío de ocurrencias de eventos

Enviar una ocurrencia única
Enviar un lote de ocurrencias

Para enviar una ocurrencia de evento única, haz una solicitud de POST a /integrators/timeline/v4/events.En el cuerpo de la solicitud, incluye los datos del evento siguiendo el esquema definido para el tipo de evento junto con el valor fullyQualifiedName en un campo eventTypeName.

{
  "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
  "objectId": "123456",
  "id": "login-1",
  "properties": {
    "customerName": "Mark S.",
    "loginLocation": "mobileApp"
  }
},

Para enviar un lote de ocurrencias, haz una solicitud de POST a /integrators/timeline/v4/events/batch.En el cuerpo de la solicitud, incluye hasta 500 objetos de ocurrencias de eventos separadas por comas dentro de una matriz inputs. Si alguna ocurrencia no se valida, las ocurrencias validadas con éxito seguirán aceptándose y persistiendo.

{
  "inputs": [
    {
      "EventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
      "id": "login_event_100",
      "objectId": "769851",
      "properties": {
        "customerName": "Tim",
        "loginLocation": "mobileApp"
      },
      "extraData": {
        "surveyData": [
          {
            "question": "How was your login experience?",
            "answer": "Fine!"
          },
          {
            "question": "How likely are you to recommend logging in to a co-worker?",
            "answer": "Extremely likely"
          }
        ]
      }
    },
    {
      "EventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
      "id": "login_event_101",
      "objectId": "769851",
      "properties": {
        "customerName": "Tim",
        "loginLocation": "website"
      },
      "extraData": {}
    }
  ]
}

Los campos marcados con * son obligatorios.

Campo	Tipo	Descripción
`eventTypeName`*	Cadena	El nombre completo del tipo de evento, que utilizarás para identificarlo a través de la API. Este valor lo establece automáticamente HubSpot y se puede obtener a través de la API después de crear el tipo de evento. Este valor no se puede cambiar después de la creación.
`objectId`*	Cadena	El ID del registro del CRM a asociar con la ocurrencia del evento. Este campo puede utilizarse para todos los tipos de registros de CRM, y es el identificador recomendado. Más información sobre la asociación de registros del CRM.
`email`	Cadena	Para la asociación de contactos, puedes proporcionar la dirección de correo electrónico del contacto a asociar. Más información sobre la asociación de registros del CRM.
`utk`	Cadena	Para la asociación de contactos, puedes proporcionar la ficha de usuario de un contacto existente para asociarlo. Más información sobre la asociación de registros del CRM.
`domain`	Cadena	Incluye este campo además de `objectId` para establecer el valor de la propiedad `domain` de la empresa. Más información sobre la asociación de registros del CRM.
`timestamp`	Cadena	Establece la hora de ocurrencia del evento (formatoISO 8601). Si no se proporciona, HubSpot utilizará por defecto la marca de tiempo de cuando se envían los datos de ocurrencia del evento.
`properties`	Objeto	Pares clave-valor de nombres y valores de propiedades que has configurado para el tipo de evento. Más información sobre las propiedades del evento.
`extraData`	Objeto	Información adicional que estará disponible para las plantillas de representación de la cronología. Debe estar en formato JSON válido.
`timelineIFrame`	Objeto	Cuando se incluya, la tarjeta de cronología incluirá un hipervínculo que permitirá a los usuarios abrir los contenidos enlazados en un iframe. Más información sobre el uso de iframes.
`id`	Cadena	Un identificador único para la ocurrencia del evento. Debe ser único dentro del tipo de evento. Si no se proporciona, HubSpot generará un UUID aleatorio. Cuando varios eventos tengan el mismo ID, se aceptará el primero y se rechazarán todos los demás.

Asociación de registros del CRM

Cada suceso debe estar asociado a un registro del CRM, con el tipo de objeto del CRM definido por el esquema de tipo de evento. La API de eventos de la aplicación incluye múltiples campos para asociar los datos de ocurrencia de eventos con los registros del CRM. Para todos los objetos del CRM compatibles, se recomienda utilizar el campo objectId. Sin embargo, hay algunas situaciones en las que puede que quieras utilizar los otros campos.

utk/email: si no conoces el ID del contacto, utiliza el campo utk y/o email para identificarlo. Proporcionar estos dos identificadores también te permite crear y actualizar contactos. Por ejemplo:
- Si utk coincide con un contacto existente pero email no coincide, HubSpot actualizará el contacto (mediante utk) con la nueva dirección de correo electrónico.
- Si no se proporciona objectId, el evento se asociará a un contacto existente que coincida con utk/email, o HubSpot creará un nuevo contacto si no se encuentra ninguna coincidencia.
- Ten en cuenta que utk por sí solo no puede crear nuevos contactos. Siempre debes incluir email con utk para garantizar una asociación adecuada.
domain: para la asociación de empresas, debes proporcionar la dirección objectId, pero también puedes incluir domain para actualizar la propiedad domain de esa empresa.

A continuación se muestra el orden de prioridad de las propiedades de la asociación de registros del CRM, siendo el número más bajo el de mayor prioridad:

Campo	Prioridad	Descripción
`objectId`	1	El ID del registro del CRM (recomendado).
`utk`	2	La ficha de usuario del contacto (solo contactos).
`email`	3	La dirección de correo electrónico del contacto (solo contactos).
`domain`	4	Dominio de la empresa (solo empresas).

Envío de datos adicionales

Además de enviar datos a las propiedades de los eventos y actualizar las propiedades de CRM a través de las ocurrencias de los eventos, puedes incluir datos adicionales para la representación de la cronología a través del objeto extraData.

El objeto extraData solo puede contener JSON válido. Si el JSON está malformado, la ocurrencia será rechazada y recibirás una respuesta de error.

Se puede acceder a los valores del campo extraData del tipo de evento detailTemplate utilizando la sintaxis {{extraData.fieldName}}. Todos los niveles de atributo de extraData están disponibles a través de la notación por puntos, como {{extraData.person1.preferredName}}. Por ejemplo, las plantillas siguientes utilizan los datos de las propiedades customerName y loginLocation, junto con el campo surveyData de extraData enviado a través de la ocurrencia del evento. Captura de pantalla que muestra el aspecto de la plantilla de representación del ejemplo siguiente en la cronología de contactos.

Captura de pantalla que muestra el aspecto de la plantilla de representación del ejemplo siguiente en la cronología de contactos.

Datos de la ocurrencia de evento
Configuración de la plantilla de cronología

{
  "eventTemplateId": "5488733",
  "objectId": "769851",
  "tokens": {
    "customerName": "Tim",
    "loginLocation": "mobileApp"
  },
  "extraData": {
    "surveyData": [
      {
        "question": "How was your login experience?",
        "answer": "Fine!"
      },
      {
        "question": "How likely are you to recommend logging in to a co-worker?",
        "answer": "Extremely likely"
      }
    ]
  }
}

"headerTemplate": "{{customerName}} logged in via the {{loginLocation}}.",
"detailTemplate": "#### Post-login survey\n{{#each extraData.surveyData}}\n- **{{question}}**: {{answer}}\n{{/each}}",

Crear aplicaciones

Agregar funciones

Publicar en el mercado de HubSpot

Enviar ocurrencias de eventos (BETA)

Envío de ocurrencias de eventos

Asociación de registros del CRM

Envío de datos adicionales

​Envío de ocurrencias de eventos

​Asociación de registros del CRM

​Envío de datos adicionales

Envío de ocurrencias de eventos

Asociación de registros del CRM

Envío de datos adicionales