Última modificación: 8 de octubre de 2025
La API del centro multimedia permite a los integradores insertar objetos multimedia como archivos de video y audio, y datos de consumo de medios en HubSpot. También crea las siguientes características en la cuenta de HubSpot del usuario:
- Módulos para insertar objetos multimedia en los editores de arrastrar y soltar de HubSpot para páginas y correos electrónicos.
- Eventos de la cronología del CRM que se muestran cuando los prospectos o clientes han interactuado con videos, audio y otros tipos de medios.
- Listas segmentadas para experiencias específicas y personalizadas.
- Workflows para automatizar interacciones basadas en eventos de consumo de contenido multimedia.
- Informes para medir el impacto de los recursos multimedia.
Usar la API del centro multimedia
Necesitas una cuenta de desarrollador de HubSpot para registrar tu aplicación del centro multimedia y configurar las definiciones iniciales de objetos multimedia antes de conectar tu aplicación a la cuenta de un usuario de HubSpot.Crear y personalizar las definiciones de objetos multimedia
Para definir un objeto multimedia, realiza una solicitudPOST a /media-bridge/v1/{appId}/settings/object-definitions. En el cuerpo de la solicitud, incluye cualquiera de los siguientes valores de tipo de medio mediaTypes dentro de la matriz: VIDEO, AUDIO, DOCUMENT, IMAGE o OTHER.
Después de definir los objetos multimedia, crea y modifica las propiedades del objeto multimedia realizando una solicitud PATCH a /media-bridge/v1/{appId}/schemas/{objectType} y una solicitud POST a /media-bridge/v1/{appId}/properties/{objectType}.
Conectar la aplicación del centro multimedia con la cuenta de un usuario de HubSpot
Para conectar tu aplicación del centro multimedia con la cuenta de un usuario de HubSpot, debes crear una definición de aplicación en tu cuenta de desarrollador de HubSpot para la aplicación. Las definiciones de la aplicación incluyen:- Detalles como el logotipo y el texto que se mostrarán al usuario de HubSpot cuando tu integración intente realizar una conexión inicial a su cuenta.
- Permisos que tu integración necesita en la cuenta de HubSpot del usuario.
- Crea una definición de aplicación en tu cuenta de desarrollador para la aplicación del centro multimedia.
- Incluye los siguientes permisos al definir tu aplicación:
media_bridge.readmedia_bridge.write
- Utiliza la autenticación OAuth al autenticar las llamadas realizadas por tu aplicación. Consulta más información sobre los métodos de autenticación.
- Visita
https://app.hubspot.com/media-bridge-demo/{HubID}, y reemplaza el{HubID}con el ID de la cuenta. - En la esquina superior derecha, haz clic en el menú desplegable Aplicación y selecciona la aplicación del centro multimedia.
- En la aplicación, puedes ver los tipos de medios compatibles de la aplicación y crear elementos multimedia de ejemplo.
- Crear objetos multimedia
- Crear módulos del CMS para insertar tus objetos de medios
- Enviar eventos multimedia
Crear objetos multimedia
Después de crear las definiciones de objetos multimedia e instalar tu aplicación del centro multimedia en la cuenta de un usuario, puedes usar el token OAuth para crear y modificar objetos multimedia en la cuenta. Como los objetos multimedia son objetos personalizados, usa los endpoints de la API de objetos personalizados para crearlos:- Haz una solicitud
GETa/media-bridge/v1/{appId}/settings/object-definitions/{mediaType}para encontrarobjectType. - Haz una solicitud
POSTa/crm/v3/objects/{objectType}para crear el objeto multimedia en la cuenta del usuario.
VIDEO y AUDIO, las siguientes tablas enumeran todas las propiedades disponibles:
Los campos marcados con * son obligatorios.
| Parámetro | Tipo | Descripción |
|---|---|---|
id | Número | Un ID utilizado para identificar el contenido multimedia específico en el sistema del centro multimedia de HubSpot. Esto se autogenera por HubSpot y no pueden configurarlo los desarrolladores. |
hs_duration | Número | La duración del contenido multimedia en milisegundos. |
hs_oembed_url* | Cadena | Una URL que debe devolver una respuesta válida oEmbed que sigue la especificación oEmbed. Requiere un tipo video o rich con un iframe en html. |
hs_file_url | Cadena | La URL del archivo multimedia sin formato. Esto puede utilizarse en el futuro para permitir la inserción en redes sociales. |
hs_thumbnail_url | Cadena | URL de una imagen utilizada como miniatura para insertar los elementos multimedia en el contenido. El tamaño ideal para esta miniatura es de 640x480 píxeles. |
hs_poster_url | Cadena | URL de una imagen que representa el contenido multimedia. Esta imagen debe tener las mismas dimensiones que los medios originales y se puede usar en los lugares donde se necesita un parámetro de sustitución de imagen (por ejemplo, cuando se inserta el contenido multimedia en un correo electrónico). |
hs_external_id | Cadena | El ID del contenido multimedia en el sistema de terceros. Esto les da a los integradores la capacidad de recuperar medios del centro multimedia según el ID que usan en su propio sistema. (Este es el endpoint de API que utiliza este mapeo) |
hs_folder_path | Cadena | Una ruta suministrada por el proveedor al objeto, destinada a representar la ubicación del objeto en el sistema de carpetas del tercero (si existe). HubSpot intentará representar la estructura de directorios al mostrar estos objetos al usuario, pero puede anidar los objetos y carpetas de cada proveedor dentro de una carpeta de nivel superior con el nombre del proveedor. |
hs_title* | Cadena | El nombre del contenido multimedia. Esto se mostrará dentro de la interfaz de usuario de HubSpot en lugares como el selector de medios. |
hs_details_page_link | Cadena | Una URL que permite a un usuario ver los elementos multimedia o interactuar con ellos en el sistema del proveedor de elementos multimedia. Esto se utiliza en la interfaz de usuario de HubSpot para dar a los usuarios la capacidad de identificar el contenido multimedia sin depender solo del título. |
IMAGE, las siguientes tablas muestran todas las propiedades disponibles:
Los campos marcados con * son obligatorios.
| Parámetro | Tipo | Descripción |
|---|---|---|
id | Número | Un ID utilizado para identificar el contenido multimedia específico en el sistema del centro multimedia de HubSpot. Esto se autogenera por HubSpot y no pueden configurarlo los desarrolladores. |
hs_oembed_url* | Cadena | Una URL que debe devolver una respuesta válida oEmbed que sigue la especificación oEmbed. Requiere un tipo video o rich con un iframe en html. |
hs_file_url* | Cadena | La URL del archivo de medios sin formato. Esto puede utilizarse en el futuro para permitir la inserción en redes sociales. |
hs_thumbnail_url | Cadena | URL de una imagen que se usará como miniatura al insertar contenido multimedia en ubicaciones como el selector de contenido. El tamaño ideal para esta miniatura es de 640x480 píxeles. |
hs_poster_url | Cadena | URL de una imagen que representa el contenido multimedia. Esta imagen debe tener las mismas dimensiones que los medios originales y se puede usar en los lugares donde se necesita un parámetro de sustitución de imagen (por ejemplo, cuando se inserta el contenido multimedia en un correo electrónico). |
hs_external_id | Cadena | El ID del contenido multimedia en el sistema de terceros. Esto les da a los integradores la capacidad de recuperar medios del centro multimedia según el ID que usan en su propio sistema. (Este es el endpoint de API que utiliza este mapeo) |
hs_folder_path | Cadena | Una ruta suministrada por el proveedor al objeto, destinada a representar la ubicación del objeto en el sistema de carpetas del tercero (si existe). HubSpot intentará representar la estructura de directorios al mostrar estos objetos al usuario, pero puede anidar los objetos y carpetas de cada proveedor dentro de una carpeta de nivel superior con el nombre del proveedor. |
hs_title* | Cadena | El nombre del contenido multimedia. Esto se mostrará dentro de la interfaz de usuario de HubSpot en lugares como el selector de medios. |
hs_details_page_link | Cadena | Una URL que permite a un usuario ver el contenido multimedia o interactuar con ellos en el sistema del proveedor de medios. Esto se utiliza en la interfaz de usuario de HubSpot para dar a los usuarios la capacidad de identificar el contenido multimedia sin depender solo del título. |
Crear módulos del CMS para insertar elementos multimedia
Cada proveedor de aplicación del centro multimedia es responsable de crear su propio módulo para renderizar su contenido multimedia en el CMS de HubSpot. Cuando se instala una aplicación del centro multimedia en una cuenta de HubSpot, el campo insertar en el módulo tiene un tipo de origen de integración de elementos multimedia adicional. Esto le permite al usuario seleccionar elementos multimedia de la aplicación instalada para insertarlos en la página de su sitio web. Después de que el usuario selecciona el elemento multimedia específico que se va a insertar, el contenido multimediaoembed_url y oembed_response están disponibles en HubL para renderizar fácilmente los reproductores. Adicionalmente, el id y el media_type del contenido multimedia seleccionado se almacenan para habilitar la consulta del objeto del CRM subyacente a través de la función crm_objects de HubL. Esto se puede usar para extraer cualquiera o todas las propiedades que son parte de un objeto multimedia.
Un ejemplo de uso de la función HubL crm_objects con un objeto multimedia donde los ID son 459 y 922:
{% set objects = crm_objects("a123_Videos", [459,922]) %} {{ objects }}
Para buscar una imagen específica con el mismo objeto: {% set object = crm_object("a123_Images", 459) %} {{ object }}
Las aplicaciones pueden buscar el tipo de objeto (“a123_Videos” en el ejemplo) haciendo una solicitud GET a /media-bridge/{appId}/settings/object-definitions/{mediaType}.
Los desarrolladores deben usar los endpoints de la API del código origen del CMS para insertar su código de módulo personalizado en las cuentas de los clientes una vez que los clientes se hayan conectado a través de oAuth. Una vez que el código del módulo se introduce en la cuenta del cliente, automáticamente podrán comenzar a usar el módulo del desarrollador en su contenido.
Configurar un dominio oEmbed
Para utilizar la función HubL oEmbed, el dominio que se utiliza para obtener la respuesta oEmbed debe registrarse haciendo una solicitud a/media-bridge/v1/{appId}/settings/oembed-domains. Se deben incluir los siguientes parámetros:
-
Esquema: el patrón de URL para las URL de los elementos multimedia. Este patrón de URL se usa para hacer coincidir la URL a la función HubL oEmbed con la API de oEmbed. Los valores comodín se admiten utilizando
*(por ejemplo,www.domain.com/*). -
URL: la URL de la API de oEmbed. La URL multimedia se pasa a esta URL a través de un parámetro
URL. - Descubrimiento (booleano): determina si tu API oEmbed admite o no la función Discovery de oEmbed.
portalId a la solicitud de API al configurar el dominio oEmbed. Esto garantizará que solo la cuenta de HubSpot especificada pueda usar ese dominio oEmbed.
Crear un módulo personalizado
Para crear un módulo personalizado:- Navega a Marketing > Archivos y plantillas > Herramientas de diseño.
- En la parte superior izquierda, haz clic en Archivo > Archivo nuevo.
- En el cuadro de diálogo, haz clic en el menú desplegable Qué te gustaría crear hoy y selecciona Módulo.
- Haz clic en Siguiente.
- Selecciona la casilla de verificación junto a cada tipo de contenido en el que se utilizará el módulo: páginas, publicaciones de blog, páginas de índice de blogs, correos electrónicos o cotizaciones. Los módulos utilizados en las plantillas de correo electrónico no pueden incluir CSS o JavaScript.
- Selecciona si este módulo será un módulo local o un módulo global. Si creas un módulo global, editar el contenido de este módulo actualizará toda ubicación donde se utilizó el módulo.
- Introduce un nombre de archivo para tu módulo y haz clic en Crear.
- En la sección Campos a la derecha, haz clic en el menú desplegable Agregar campo y selecciona Insertar.
- En la sección Tipos de origen compatibles, selecciona Integración multimedia.
- En la sección Contenido insertado predeterminado, haz clic en Seleccionar desde la [aplicación del centro multimedia]
- En el panel derecho, selecciona el contenido multimedia que deseas insertar en el módulo.
- Establece cualquiera de las opciones de edición, condiciones de presentación de campos y opciones de repetidor de campos.
- Bajo el nombre de la variable HubL, haz clic en Copiar > Copiar fragmento.
- Pega el fragmento en la sección module.html.
- Para obtener una vista preliminar de cómo se verá el módulo en tu página, haz clic en Vista preliminar.
- En la sección de la izquierda, haz clic en Seleccionar desde la [aplicación del centro multimedia] y luego selecciona el elemento multimedia que deseas previsualizar.
Envía tus eventos multimedia
Un evento multimedia es un evento que ocurre en relación con un objeto multimedia, como un evento de reproducción. Una vez que se envía un evento multimedia a la aplicación del centro multimedia, se puede usar en informes y en las tarjetas CRM de la cronología. Hay tres tipos de eventos multimedia:- Evento de reproducción: representa cuándo un usuario comienza a reproducir un elemento multimedia. Este evento está disponible tanto en la cronología de los contactos como en la herramienta de informes.
- Evento de cuartil: representa cuándo un usuario alcanzó hitos trimestrales (0%, 25%, 50%, 75%, 100%) en términos de cuántos elementos multimedia ha consumido. Este evento solo está disponible en la cronología de contactos.
- Evento de período de atención: representa cuando un usuario haya consumido completamente un elemento multimedia o cuando el usuario haya completado su sesión. Este evento solo está disponible dentro de la herramienta de informes.
POST a /media-bridge/v2/events/media-played, /media-bridge/v2/events/media-played-percent y /media-bridge/v2/events/attention-span respectively.
Para que los eventos multimedia se muestren en la cronología de contacto del usuario en HubSpot, se debe enviar un evento de reproducción a la aplicación del centro multimedia para cada sesión. Los eventos de una sola sesión se mostrarán en una tarjeta en la cronología de actividad de contacto.
Cuando los eventos se envían utilizando los endpoints de eventos v2, se procesan de forma asincrónica, a diferencia de los enviados a través de los endpoints v1. Por lo tanto, recomendamos lo siguiente:
- La versión v1 de los endpoints debe usarse para cualquier prueba, ya que una solicitud errónea se eliminará inmediatamente.
- La versión v2 de los endpoints debe usarse en producción, ya que su naturaleza asincrónica ayudará a evitar retrasos en el cliente mientras se escribe el evento en el centro multimedia. Los eventos también se retienen y se vuelven a intentar en caso de una falla temporal en el servidor del centro multimedia.
Conectar un evento con un registro de contacto
Para conectar un evento multimedia con un registro de contacto, los integradores deben proporcionar uncontactId o un contactUtk. Si solo se proporciona un contactUtk, se convertirá en un contactId. Si ambos se proporcionan en la solicitud, el contactId se utilizará como fuente veraz. Este parámetro permite a la aplicación del centro multimedia crear una asociación entre el registro de contacto y el evento.
Una vez que un evento multimedia se ha conectado a un registro de contacto, el evento se puede usar en informes multiobjeto. Esto permite a los clientes vincular sus eventos multimedia con los registros de contacto, así como con las empresas y negocios asociados.
Conexión de un evento con un elemento multimedia
Para asociar un evento multimedia a un elemento multimedia específico, se deben incluir en la solicitud los parámetrosmediaID o externalID. Si se proporcionan ambos, el mediaID se utilizará como fuente veraz.
Nota:
HubSpot solo admite las asociaciones de Eventos reproducidos y Eventos de cuartil con un contenido multimedia.Conectar un evento con una página
Para asociar un evento multimedia a una página de HubSpot, se deben incluir los siguientes parámetros en la solicitud:- Si la página está alojada en el CMS de HubSpot, se debe proporcionar el
pageId. - Si la página no está alojada en el CMS de HubSpot, se debe incluir
pageNameypageUrl.
| Propiedad | Tipo de evento | Descripción |
|---|---|---|
mediaBridgeObjectId | Todos los eventos | El ID del contenido multimedia con los que se relaciona este evento. |
externalId | Cadena | El ID del contenido multimedia en el sistema de terceros. Esto les da a los desarrolladores la capacidad de referirse al contenido multimedia en el centro multimedia basándose en el mismo identificador que usan en su propio sistema. Esto se puede utilizar en lugar del mediaBridgeObjectId en eventos. Si se proporcionan tanto un externalId como mediaBridgeObjectId, se utilizará el mediaBridgeObjectId y el externalId se ignorará. |
sessionId | Todos los eventos | Un identificador único para representar una sesión de visualización. Esto puede significar cosas diferentes para diferentes proveedores y HubSpot permite que los proveedores decidan qué significa una sesión para ellos. Esto se utilizará para agrupar eventos que ocurrieron en la misma sesión. Se espera que esto lo genere el sistema del tercero. |
contactId | Todos los eventos | El ID del contacto en el sistema de HubSpot que consumió el contenido multimedia. Esto se puede buscar utilizando la API para obtener contactos mediante el token de usuario (utk) de HubSpot. La API también admite el suministro de un usertoken, y se encargará de convertirlo en un ID de contacto automáticamente. |
contactUtk | Todos los eventos | El usertoken (utk) que identifica qué contacto consumió los medios. |
pageId | Todos los eventos | El ID de contenido de la página en la que se produjo un evento. |
pageName | Todos los eventos | El nombre o el título de la página en la que se produjo un evento. |
pageUrl | Todos los eventos | La URL de la página en la que se produjo un evento. |
occurredTimestamp | Todos los eventos | La marca de tiempo en la que ocurrió este evento, en milisegundos desde la época (epoch). |
rawDataString / rawDataMap | Capacidad de atención | Estos son los datos sin formato que proporcionan los datos más granulares sobre los períodos del contenido multimedia y cuántas veces cada período fue consumido por el usuario. Por ejemplo, en un video de 10 segundos donde cada segundo representa un tramo, si un visitante ve los primeros 5 segundos del video, luego lo reinicia y vuelve a ver los primeros 2 segundos, el rawDataString resultante sería “0=2;1=2;2=1;3=1;4=1;5=0;6=0;7=0;8=0;9=0;”. |
totalPercentPlayed | Capacidad de atención | El porcentaje del contenido multimedia que el usuario consumió. Los proveedores pueden calcular esto de manera diferente según la forma en que consideren las vistas repetidas de la misma parte del contenido multimedia. Por esta razón, la API no intentará validar totalPercentWatched con respecto a la capacidad de atención del evento. Si hace falta, HubSpot calculará a partir del mapa de capacidad de atención de la siguiente manera: número de períodos con un valor de 1 o más sobre el número total de capacidades). |
totalSecondsPlayed | Capacidad de atención | Los segundos que un usuario pasó consumiendo el contenido multimedia. El centro multimedia calcula esto como totalPercentPlayed*mediaDuration. Si un proveedor desea que esto se calcule de manera diferente, puede proporcionar el valor previamente calculado cuando crea el evento |
playedPercent | Evento de cuartil | Un valor de porcentaje del cuartil (0, 25, 50, 75, 100) para saber cuánto de los elementos multimedia se ha consumido hasta ahora. |
iframeUrl | Evento de reproducción | Una URL que se puede utilizar para mostrar datos de un sistema externo utilizando un iFrame. Cuando se incluya, el evento de la cronología del contacto mostrará un enlace que abrirá una ventana modal que muestra el contenido del iFrame cuando se hace clic. |
mediaType | Cadena | El tipo multimedia al que pertenece el evento (por ejemplo, VIDEO o AUDIO) Esto nos permite asignar adecuadamente el evento a los objetos correctos cuando un solo proveedor admite varios tipos de elementos multimedia. |