Eventos de marketing

Un evento de marketing es un objeto de CRM, similar a los contactos y las empresas, que te permite hacer seguimiento y asociar eventos de marketing, como un webinario, a otros objetos de CRM de HubSpot. A continuación, obtén más información sobre cómo trabajar con la API de eventos de marketing para integrarlos en una aplicación.

• Requisitos de alcance
• Puntos de terminación de asistencia a eventos
• Configurar valores de la aplicación
  • Paso 1: Crea una API en tu aplicación
  • Paso 2: Proporciona a HubSpot la ruta de URL a tu API

Para realizar una solicitud de API a uno de los puntos de terminación de eventos de marketing, se requieren los siguientes alcances:

• crm.objects.marketing_events.read: otorga permiso para recuperar datos de eventos de marketing y asistencia.
• crm.objects.marketing_events.write: otorga permisos para crear, eliminar o realizar cambios en la información del evento de marketing.

Al autenticar las llamadas realizadas por tu aplicación, puedes usar un token de acceso privado a la aplicación u OAuth. Más información sobre métodos de autentificación. Para obtener la lista completa de puntos de terminación disponibles, haz clic en la pestaña Puntos de terminación en la parte superior de este artículo.

Puedes crear o actualizar eventos de marketing realizando una solicitud POST al punto de terminación /marketing/v3/marketing-events/events/upsert. Puedes incluir customProperties que correspondan a los eventos que quieres actualizar en el campo inputs del cuerpo de tu solicitud, junto con cualquier otro detalle de tu evento (incluido el nombre, hora de inicio y descripción).

Si ya existe un evento de marketing con el ID especificado en tu solicitud, se actualizará. De lo contrario, se creará un nuevo evento.

Por ejemplo, la siguiente solicitud crearía un evento con un ID de 4 llamado "Virtual cooking class":

Puedes revisar una lista completa de todos los campos disponibles que puedes incluir en tu solicitud haciendo clic en la pestaña Puntos de terminación en la parte superior de este artículo.

Los puntos de terminación de estado de asistencia a eventos te permiten registrar un estado de suscripción entre un contacto de HubSpot y un evento de marketing. Por ejemplo, puedes usar este punto de terminación para registrar que un contacto de HubSpot se registró para un evento de marketing.

Hay dos puntos de terminación que puedes usar para actualizar el estado de asistencia de un contacto. Si anteriormente usabas los puntos de terminación /upsert o /email-upsert para actualizar el estado de un asistente, puedes usar los puntos de terminación que se enumeran a continuación para mantener la misma funcionalidad y al mismo tiempo completar la duración de la asistencia del contacto en la cronología del contacto:

• Si deseas usar los ID de contacto de los contactos existentes:
  • Haz una solicitud POST a /marketing/v3/marketing-events/attendance/{externalEventId}/{subscriberState}/create, utilizando el ID del evento desde tu aplicación externa como el externalEventId.
  • En el cuerpo de la solicitud, proporciona un objeto inputs que incluya los siguientes campos:
    • interactionDateTime: la fecha y la hora en que el contacto se suscribió al evento.
    • vid: el ID de contacto de un contacto existente.
• Si quieres usar la dirección de correo electrónico de uno de los asistentes al evento:
  • Haz una solicitud POST a /marketing/v3/marketing-events/attendance/{externalEventId}/{subscriberState}/email-create.
  • En el cuerpo de la solicitud, proporciona un objeto inputs que incluya los siguientes campos:
    • interactionDateTime: la fecha y la hora en que el contacto se suscribió al evento.
    • email: la dirección de correo electrónico del asistente como el valor del campo de correo electrónico dentro de una entrada 
  • Si la dirección de correo electrónico que incluyes no coincide con la dirección de un contacto existente, se creará un nuevo contacto.

Para ambos puntos de terminación anteriores, proporciona los siguientes valores para los parámetros de ruta correspondientes:

• externalEventId: el ID del evento de marketing.
•  subscriberState: una enumeración que coincide con el nuevo estado de asistencia del contacto:
  • REGISTERED:  indica que el contacto de HubSpot se registró para el evento.
  • ATTENDED: indica que el contacto de HubSpot asistió al evento. Si estás actualizando el estado de un contacto a ATTENDED, también puedes incluir las marcas de tiempo joinedAt y leftAt como parámetros en el cuerpo de la solicitud, especificados en el formato ISO8601 Instant.
  • CANCELLED: indica que el contacto de HubSpot, que se había registrado previamente para el evento, ahora ha cancelado su registro para el evento.

Una vez que tu evento se haya completado, puedes marcar el evento como completo y calcular las métricas de asistencia (por ejemplo, la duración de la asistencia para todos los asistentes) haciendo una solicitud POST a /marketing/v3/marketing-events/events/{externalEventId}/complete. Ten en cuenta que esta acción es irreversible, por lo que solo debes invocar este punto de terminación una vez que ya se hayan producido todos los eventos de cambio de estado de asistencia. 

Se requiere cierta configuración para permitir que los eventos de marketing se sincronicen correctamente con HubSpot.

Si envías a HubSpot un cambio de estado del suscriptor (por ejemplo, un registro o evento cancelado), HubSpot primero comprobará si existe un evento de marketing para el ID de evento especificado. Si no es así, HubSpot llamará al punto de conexión configurado de tu aplicación para recuperar los detalles del evento de marketing, luego creará el evento en HubSpot y, a continuación, publicará el cambio de estado del suscriptor.

Esto se proporciona por conveniencia; sin embargo, se recomienda que crees los Eventos de marketing tu mismo a través de nuestros métodos CRUD proporcionados en la pestaña Puntos de terminación en la parte superior de este artículo y no confíes en esta funcionalidad para crear tus eventos de marketing en HubSpot.

Para respaldar esto, HubSpot requiere que cada aplicación que use Eventos de marketing defina una API para obtener información sobre un evento de marketing específico.

Requisitos:

• Acepta:
  • externalAccountId: un parámetro de consulta que especifica el accountId del cliente en la aplicación externa.
  • appId: un parámetro de consulta que especifica el id de la aplicación de HubSpot que solicita los detalles del evento. Este será el ID de tu aplicación.
  • externalEventId: un parámetro de ruta en la URL de la solicitud que especifica el ID del evento en la aplicación externa sobre la que HubSpot requiere detalles.
• Devuelve:
  • Un objeto JSON que proporciona detalles para el evento de marketing, que incluye los siguientes campos detallados en la siguiente tabla:

HubSpot también enviará un encabezado X-HubSpot-Signature-v3 que puedes usar para verificar que la solicitud proviene de HubSpot. Más información sobre las firmas de solicitud para obtener detalles adicionales sobre la firma y cómo validarla.

Ahora que has creado la API en tu aplicación que devolverá un objeto que proporciona los detalles de un evento de marketing específico, deberás proporcionar a HubSpot la ruta de URL a tu API realizando una solicitud POST a /marketing/v3/marketing-events/{appId}/settings. Esto permitirá a HubSpot determinar cómo realizar solicitudes a tu aplicación para obtener los detalles de un evento de marketing.

En el cuerpo de tu solicitud POST, especifica tu URL utilizando el campo eventDetailsURL. El eventDetailsURL debe cumplir con los siguientes requisitos:

• Contener por lo menos una secuencia de caracteres %s, los cuales usamos para sustituir en el id del evento (externalEventId) como parámetro de ruta.
• Debe ser la ruta completa al recurso API, incluido el prefijo https:// y el nombre de dominio (por ejemplo, my.event.app).

Por ejemplo, si configuras un eventDetailsURL de https://my.event.app/events/%s y necesitas hacer una solicitud para obtener detalles de un evento con id 1234-event-XYZ, para la aplicación HubSpot con id app-101 y la cuenta con id ABC-account-789, HubSpot hará una solicitud GET a:

https://my.event.app/events/1234-event-XYZ?appId=app-101&externalAccountId=ABC-account-789