HubSpot: Create — media Bridge media Played

← Media bridge operations · Get started

Operation hubspot.media_bridge_media_played

Provider route: POST /media-bridge/2026-09/events/media-played. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/hubspot with npm, or alter-sdk-hubspot with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { HubSpotIntegration } from "@alter-ai/hubspot";

async function execute(input: Parameters<HubSpotIntegration["mediaBridge"]["mediaPlayed"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new HubSpotIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.mediaBridge.mediaPlayed(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_hubspot import HubSpotIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = HubSpotIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.media_bridge.media_played(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
body	Model	Required within parent	Expand Create — media Bridge media Played — request body — body

Referenced models: Create — media Bridge media Played — request body — body

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Create — media Bridge media Played — response body

Referenced models: Create — media Bridge media Played — response body

Schemas

Create — media Bridge media Played — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
_hsenc	string	Optional	An encoding parameter used internally by HubSpot.
contactId	integer	Optional	The unique identifier for the contact associated with the media play event. Format: int64
contactUtk	string	Optional	The unique tracking key for the contact, used for tracking purposes.
externalId	string	Optional	An external identifier for the media, used to correlate with external systems.
externalPlayContext	string	Optional	Additional context about the media play event, provided by external systems. One of: EMAIL, EXTERNAL_PAGE
iframeUrl	string	Optional	The URL of the iframe containing the media, if applicable.
mediaBridgeId	integer	Optional	A unique identifier for the media bridge instance. Format: int64
mediaName	string	Optional	The name of the media that was played.
mediaType	string	Required within parent	The type of media that was played, such as 'VIDEO', 'AUDIO', 'DOCUMENT', 'OTHER', or 'IMAGE'. One of: AUDIO, DOCUMENT, IMAGE, OTHER, VIDEO
mediaUrl	string	Optional	The URL of the media that was played.
occurredTimestamp	integer	Required within parent	The timestamp when the media play event occurred, in Unix time format. Format: int64
pageId	integer	Optional	A unique identifier for the page where the media was played. Format: int64
pageName	string	Optional	The name of the page where the media was played.
pageUrl	string	Optional	The URL of the page where the media was played.
sessionId	string	Required within parent	A unique identifier for the session during which the media was played.
state	string	Required within parent	The state of the media play event, indicating the current status. One of: STARTED, VIEWED

Create — media Bridge media Played — response body

Field	Type	Presence	Description and constraints
$	object	Root
contactId	JSON	Required within parent
contactId (anyOf 1)	integer	Alternative	The unique identifier for the contact associated with this media event. Format: int64
contactId (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
externalPlayContext	string	Optional	Additional context provided by external systems about the play event. Known values: EMAIL, EXTERNAL_PAGE
iframeUrl	string	Optional	The URL of the iframe where the media was embedded and played.
mediaBridgeId	JSON	Required within parent
mediaBridgeId (anyOf 1)	integer	Alternative	The unique identifier for the media bridge instance associated with this event. Format: int64
mediaBridgeId (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
mediaBridgeObjectCoordinates	string	Required within parent	Coordinates that specify the location or context of the media bridge object.
mediaBridgeObjectTypeId	string	Required within parent	The type identifier of the media bridge object involved in the event.
mediaName	string	Required within parent	The name of the media content that was played.
mediaType	string	Required within parent	The type of media that was played, such as video or audio. Known values: AUDIO, DOCUMENT, IMAGE, OTHER, VIDEO
mediaUrl	string	Optional	The URL where the media content is hosted.
occurredTimestamp	JSON	Required within parent
occurredTimestamp (anyOf 1)	integer	Alternative	A Unix timestamp in milliseconds indicating when the media play event occurred. Format: int64
occurredTimestamp (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
pageId	JSON	Optional
pageId (anyOf 1)	integer	Alternative	The unique identifier for the page where the media was played. Format: int64
pageId (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
pageName	string	Optional	The name of the page where the media was played.
pageObjectCoordinates	string	Optional	Coordinates that specify the location or context of the page object.
pageUrl	string	Optional	The URL of the page where the media was played.
portalId	JSON	Required within parent
portalId (anyOf 1)	integer	Alternative	The unique identifier of the HubSpot portal where the event occurred. Format: int32
portalId (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
providerId	JSON	Required within parent
providerId (anyOf 1)	integer	Alternative	The unique identifier for the media provider. Format: int32
providerId (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
sessionId	string	Required within parent	The unique identifier for the session during which the media was played.
state	string	Required within parent	The state of the media play event, such as 'started' or 'completed'. Known values: STARTED, VIEWED

Policy, approvals and errors

SDK function policy ID: hubspot.media_bridge_media_played. Catalog operation: media_bridge_media_played. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Required provider scopes: ["media_bridge.write"]

Official provider source