title: Intents

# Intents Schema

Version 0.10.0

JSON-Schema

This document was generated from a JSON-Schema, and is intended to provide a human readable overview and examples of the methods contained in the module.

For the full schema, see the link below.

Table of Contents

• Schemas
  • AppIntentMessage
  • PlatformIntentMessage
  • Intent
  • IntentProperties
  • NavigationIntent
  • DiscoveryIntent
  • DeviceIntent
  • PlaybackControlIntent
  • DialogIntent
  • LaunchIntent
  • HomeIntent
  • EntityIntent
  • ChannelEntity
  • ProgramEntity
  • MovieEntity
  • TVEpisodeEntity
  • TVSeasonEntity
  • TVSeriesEntity
  • AdditionalEntity
  • UntypedEntity
  • TuneIntent
  • PlaybackIntent
  • SearchIntent
  • SectionIntent
  • ContentDiscoveryIntent
  • EntityAppSelectionIntent
  • ButtonIntent
  • VolumeIntent
  • PowerIntent
  • MicrophoneIntent
  • InputIntent
  • PauseIntent
  • PlaybackSpeedIntent
  • TrickPlayIntent
  • SeekIntent
  • SkipIntent
  • ClosedCaptionsIntent
  • AudioDescriptionIntent
  • MessageIntent
  • Identifier
  • Filter
  • Keyword
  • DirectionalOperation
  • BooleanToggle
  • IntentMessage

Schemas

AppIntentMessage

type AppIntentMessage = {
  type: string
  appId: string
  intent: NavigationIntent  // A Firebolt compliant representation of a user intention to navigate to a specific place in an app.
  metadata?: {
  }
}

{
  "type": "xrn:firebolt:intent:app:launch",
  "appId": "Netflix",
  "intent": {
    "action": "launch",
    "context": {
      "source": "voice"
    }
  },
  "metadata": {
    "foo": "bar"
  }
}

{
  "type": "xrn:firebolt:intent:app:entity",
  "appId": "Netflix",
  "intent": {
    "action": "entity",
    "data": {
      "entityType": "program",
      "programType": "movie",
      "entityId": "jerry-mcguire"
    },
    "context": {
      "source": "voice"
    }
  },
  "metadata": {
    "foo": "bar"
  }
}

Details

A message sent to a Firebolt app.

PlatformIntentMessage

type PlatformIntentMessage = {
  type: string
  intent: ContentDiscoveryIntent | EntityAppSelectionIntent | PauseIntent | SeekIntent | SkipIntent | TrickPlayIntent | ClosedCaptionsIntent | AudioDescriptionIntent | ButtonIntent | PowerIntent | VolumeIntent | MicrophoneIntent | InputIntent | TuneIntent | MessageIntent
  metadata?: {
  }
}

{
  "type": "xrn:firebolt:intent:platform:power",
  "intent": {
    "action": "power",
    "data": {
      "toggle": true
    },
    "context": {
      "source": "voice"
    }
  },
  "metadata": {
    "foo": "bar"
  }
}

{
  "type": "xrn:firebolt:intent:platform:discovery",
  "intent": {
    "action": "discovery",
    "data": {
      "query": "christmas",
      "menus": [
        "christmas-menu"
      ],
      "federation": [
        {
          "appId": "netflix",
          "exclude": true
        }
      ]
    },
    "context": {
      "source": "voice"
    }
  }
}

Details

A message sent to the Firebolt platform.

Intent

type Intent = {
  action: string
  context: {
    source: 'voice' | 'channel-lineup' | 'editorial' | 'device'
  }
}

Details

A Firebolt compliant representation of a user intention.

IntentProperties

type IntentProperties = {
  action: any
  data: any
  context: any
}

NavigationIntent

type NavigationIntent = HomeIntent | LaunchIntent | EntityIntent | PlaybackIntent | SearchIntent | SectionIntent | TuneIntent

Details

A Firebolt compliant representation of a user intention to navigate to a specific place in an app.

DiscoveryIntent

type DiscoveryIntent = ContentDiscoveryIntent | EntityAppSelectionIntent

Details

A Firebolt compliant representation of a user intention to discover something at the aggregate experience level, e.g. content, apps, etc.

DeviceIntent

type DeviceIntent = ButtonIntent | PowerIntent | VolumeIntent | MicrophoneIntent | InputIntent | TuneIntent

Details

A Firebolt compliant representation of a user intention to control some aspect of their device.

PlaybackControlIntent

type PlaybackControlIntent = PauseIntent | SeekIntent | SkipIntent | TrickPlayIntent | ClosedCaptionsIntent | AudioDescriptionIntent

Details

A Firebolt compliant representation of a user intention to control some aspect of in-progress playback.

DialogIntent

type DialogIntent = MessageIntent

Details

A Firebolt compliant representation of a platform or user intention to converse in a dialog.

LaunchIntent

type LaunchIntent = {
  action: "launch"
  context: {
    source: 'voice' | 'channel-lineup' | 'editorial' | 'device'
  }
}

{
  "action": "launch",
  "context": {
    "source": "voice"
  }
}

Details

A Firebolt compliant representation of a user intention to launch an app.

HomeIntent

type HomeIntent = {
  action: "home"
  context: {
    source: 'voice' | 'channel-lineup' | 'editorial' | 'device'
  }
}

{
  "action": "home",
  "context": {
    "source": "voice"
  }
}

Details

A Firebolt compliant representation of a user intention to navigate an app to it's home screen, and bring that app to the foreground if needed.

EntityIntent

type EntityIntent = {
  action: "entity"
  context: {
    source: 'voice' | 'channel-lineup' | 'editorial' | 'device'
  }
  data: MovieEntity | TVEpisodeEntity | TVSeriesEntity | TVSeasonEntity | AdditionalEntity | UntypedEntity
}

{
  "action": "entity",
  "context": {
    "source": "voice"
  },
  "data": {
    "entityType": "program",
    "programType": "movie",
    "entityId": "el-camino"
  }
}

Details

A Firebolt compliant representation of a user intention to navigate an app to a specific entity page, and bring that app to the foreground if needed.

ChannelEntity

type ChannelEntity = {
  entityType: "channel"
  channelType: 'streaming' | 'overTheAir'
  entityId: string                         // ID of the channel, in the target App's scope.
  appContentData?: string
}

ProgramEntity

type ProgramEntity = {
  entityType: "program"
  programType: ProgramType  // In the case of a program `entityType`, specifies the program type.
  entityId: string
}

See also:

• ProgramType

MovieEntity

type MovieEntity = {
  entityType: "program"
  programType: ProgramType  // In the case of a program `entityType`, specifies the program type.
  entityId: string
  assetId?: string
  appContentData?: string
}

{
  "entityType": "program",
  "programType": "movie",
  "entityId": "el-camino"
}

TVEpisodeEntity

type TVEpisodeEntity = {
  entityType: "program"
  programType: ProgramType  // In the case of a program `entityType`, specifies the program type.
  entityId: string
  seriesId: string
  seasonId: string
  assetId?: string
  appContentData?: string
}

{
  "entityType": "program",
  "programType": "episode",
  "entityId": "breaking-bad-pilot",
  "seriesId": "breaking-bad",
  "seasonId": "breaking-bad-season-1"
}

TVSeasonEntity

type TVSeasonEntity = {
  entityType: "program"
  programType: ProgramType  // In the case of a program `entityType`, specifies the program type.
  entityId: string
  seriesId: string
  assetId?: string
  appContentData?: string
}

{
  "entityType": "program",
  "programType": "season",
  "entityId": "breaking-bad-season-1",
  "seriesId": "breaking-bad"
}

Details

A Firebolt compliant representation of a TV Season entity.

TVSeriesEntity

type TVSeriesEntity = {
  entityType: "program"
  programType: ProgramType  // In the case of a program `entityType`, specifies the program type.
  entityId: string
  assetId?: string
  appContentData?: string
}

{
  "entityType": "program",
  "programType": "series",
  "entityId": "breaking-bad"
}

AdditionalEntity

type AdditionalEntity = {
  entityType: "program"
  programType: ProgramType  // In the case of a program `entityType`, specifies the program type.
  entityId: string
  assetId?: string
  appContentData?: string
}

{
  "entityType": "program",
  "programType": "concert",
  "entityId": "live-aid"
}

UntypedEntity

type UntypedEntity = {
  entityId: string
  assetId?: string
  appContentData?: string
}

{
  "entityId": "an-entity"
}

TuneIntent

type TuneIntent = {
  action: "tune"
  context: {
    source: 'voice' | 'channel-lineup' | 'editorial' | 'device'
  }
  data: {
    entity: ChannelEntity
    options?: {
      assetId?: string                                           // The ID of a specific 'listing', as scoped by the target App's ID-space, which the App should begin playback from.
      restartCurrentProgram?: boolean                            // Denotes that the App should start playback at the most recent program boundary, rather than 'live.'
      time?: string                                              // ISO 8601 Date/Time where the App should begin playback from.
    }
  }
}

{
  "action": "tune",
  "data": {
    "entity": {
      "entityType": "channel",
      "channelType": "streaming",
      "entityId": "an-ott-channel"
    },
    "options": {
      "restartCurrentProgram": true
    }
  },
  "context": {
    "source": "voice"
  }
}

Details

A Firebolt compliant representation of a user intention to 'tune' to a traditional over-the-air broadcast, or an OTT Stream from an OTT or vMVPD App.

PlaybackIntent

type PlaybackIntent = {
  action: "playback"
  context: {
    source: 'voice' | 'channel-lineup' | 'editorial' | 'device'
  }
  data: MovieEntity | TVEpisodeEntity | AdditionalEntity
}

{
  "action": "playback",
  "data": {
    "entityType": "program",
    "programType": "episode",
    "entityId": "breaking-bad-pilot",
    "seriesId": "breaking-bad",
    "seasonId": "breaking-bad-season-1"
  },
  "context": {
    "source": "voice"
  }
}

Details

A Firebolt compliant representation of a user intention to navigate an app to a the video player for a specific, playable entity, and bring that app to the foreground if needed.

SearchIntent

type SearchIntent = {
  action: "search"
  context: {
    source: 'voice' | 'channel-lineup' | 'editorial' | 'device'
  }
  data?: {
    query: string
  }
}

{
  "action": "search",
  "data": {
    "query": "walter white"
  },
  "context": {
    "source": "voice"
  }
}

Details

A Firebolt compliant representation of a user intention to navigate an app to it's search UI with a search term populated, and bring that app to the foreground if needed.

SectionIntent

type SectionIntent = {
  action: "section"
  context: {
    source: 'voice' | 'channel-lineup' | 'editorial' | 'device'
  }
  data?: {
    sectionName: string
  }
}

{
  "action": "section",
  "data": {
    "sectionName": "settings"
  },
  "context": {
    "source": "voice"
  }
}

Details

A Firebolt compliant representation of a user intention to navigate an app to a section not covered by home, entity, player, or search, and bring that app to the foreground if needed.

ContentDiscoveryIntent

type ContentDiscoveryIntent = {
  action: "discovery"
  context: {
    source: 'voice' | 'channel-lineup' | 'editorial' | 'device'
  }
  data: {
    query: string
    filters?: object[]
    keywords?: object[]
    menus?: string[]
    federation?: object[]
  }
}

{
  "action": "discovery",
  "context": {
    "source": "voice"
  },
  "data": {
    "query": "Bill Murray Comedies in 4K",
    "filters": [
      {
        "key": "videoResolution",
        "value": "UHD"
      }
    ],
    "keywords": [
      {
        "keyword": "Bill Murray",
        "type": "Person",
        "appId": "FooApp"
      },
      {
        "keyword": "Comedies",
        "type": "Genre",
        "appId": "FooApp"
      }
    ],
    "menus": [
      "abcdef",
      "ghijkl"
    ],
    "federation": [
      {
        "appId": "BarApp",
        "exclude": false
      }
    ]
  }
}

Details

A Firebolt compliant representation of a user intention to discover content with out a clear specific entity match.

EntityAppSelectionIntent

type EntityAppSelectionIntent = {
  action: "entityAppSelection"
  context: {
    source: 'voice' | 'channel-lineup' | 'editorial' | 'device'
  }
  data: {
    query: string
    entity: MovieEntity | TVEpisodeEntity | TVSeriesEntity | TVSeasonEntity | AdditionalEntity
    apps: object[]
    menus?: string[]
    federation?: object[]
  }
}

{
  "action": "entityAppSelection",
  "context": {
    "source": "voice"
  },
  "data": {
    "query": "the departed",
    "entity": {
      "entityType": "program",
      "programType": "movie",
      "entityId": "departed-merlin-id"
    },
    "apps": [
      {
        "appId": "hbo",
        "entity": {
          "entityType": "program",
          "programType": "movie",
          "entityId": "departed-hbo-id"
        }
      },
      {
        "appId": "netflix",
        "entity": {
          "entityType": "program",
          "programType": "movie",
          "entityId": "departed-netflix-id"
        }
      }
    ],
    "federation": [
      {
        "appId": "netflix",
        "exclude": true
      }
    ],
    "menusIds": [
      "123"
    ]
  }
}

Details

A Firebolt compliant representation of a user intention to navigate to a specific entity that could be served by more than one app.

ButtonIntent

type ButtonIntent = {
  action: "button"
  context: {
    source: 'voice' | 'channel-lineup' | 'editorial' | 'device'
  }
  data?: {
    operation: 'down' | 'up' | 'prev' | 'next' | 'enter' | 'exit' | 'info' | 'menu' | 'back' | 'cancel' | 'record'
  }
}

{
  "action": "button",
  "data": {
    "operation": "menu"
  },
  "context": {
    "source": "voice"
  }
}

Details

A Firebolt compliant representation of a user intention to interact with their device in a way analogous to pressing one of the remote buttons.

VolumeIntent

type VolumeIntent = {
  action: "volume"
  context: {
    source: 'voice' | 'channel-lineup' | 'editorial' | 'device'
  }
  data?: object | object
}

{
  "action": "volume",
  "data": {
    "toggle": true
  },
  "context": {
    "source": "voice"
  }
}

{
  "action": "volume",
  "data": {
    "value": 0.7
  },
  "context": {
    "source": "voice"
  }
}

{
  "action": "volume",
  "data": {
    "value": 0.1,
    "relative": true
  },
  "context": {
    "source": "voice"
  }
}

Details

A Firebolt compliant representation of a user intention to change the device volume.

PowerIntent

type PowerIntent = {
  action: "power"
  context: {
    source: 'voice' | 'channel-lineup' | 'editorial' | 'device'
  }
  data?: {
    value?: boolean
    toggle?: true
  }
}

{
  "action": "power",
  "data": {
    "value": false
  },
  "context": {
    "source": "voice"
  }
}

{
  "action": "power",
  "data": {
    "toggle": true
  },
  "context": {
    "source": "voice"
  }
}

Details

A Firebolt compliant representation of a user intention to turn their device on or off.

MicrophoneIntent

type MicrophoneIntent = {
  action: "microphone"
  context: {
    source: 'voice' | 'channel-lineup' | 'editorial' | 'device'
  }
  data?: {
    value?: boolean
    toggle?: true
  }
}

{
  "action": "microphone",
  "data": {
    "value": false
  },
  "context": {
    "source": "voice"
  }
}

{
  "action": "microphone",
  "data": {
    "toggle": true
  },
  "context": {
    "source": "voice"
  }
}

Details

A Firebolt compliant representation of a user intention to turn their microphone on or off.

InputIntent

type InputIntent = {
  action: "input"
  context: {
    source: 'voice' | 'channel-lineup' | 'editorial' | 'device'
  }
  data?: {
    interface: 'hdmi' | 'rca' | 'vga' | 'etc...'
    number?: number
  }
}

{
  "action": "input",
  "data": {
    "interface": "hdmi"
  },
  "context": {
    "source": "voice"
  }
}

{
  "action": "input",
  "data": {
    "interface": "hdmi",
    "number": 1
  },
  "context": {
    "source": "voice"
  }
}

Details

A Firebolt compliant representation of a user intention to change which video input is active.

PauseIntent

type PauseIntent = {
  action: "pause"
  context: {
    source: 'voice' | 'channel-lineup' | 'editorial' | 'device'
  }
  data?: {
    value?: boolean
    toggle?: true
  }
}

{
  "action": "pause",
  "data": {
    "value": false
  },
  "context": {
    "source": "voice"
  }
}

{
  "action": "pause",
  "data": {
    "toggle": true
  },
  "context": {
    "source": "voice"
  }
}

Details

A Firebolt compliant representation of a user intention to pause/unpause in-progress playback.

PlaybackSpeedIntent

type PlaybackSpeedIntent = {
  action: "speed"
  context: {
    source: 'voice' | 'channel-lineup' | 'editorial' | 'device'
  }
  data?: {
    value?: number
    toggle?: boolean
  }
}

{
  "action": "speed",
  "data": {
    "value": 2
  },
  "context": {
    "source": "voice"
  }
}

{
  "action": "speed",
  "data": {
    "toggle": true
  },
  "context": {
    "source": "voice"
  }
}

Details

A Firebolt compliant representation of a user intention to change the speed of in-progress playback.

TrickPlayIntent

type TrickPlayIntent = {
  action: "trickplay"
  context: {
    source: 'voice' | 'channel-lineup' | 'editorial' | 'device'
  }
  data?: true
}

{
  "action": "trickplay",
  "data": {
    "direction": "forward",
    "speed": 2
  },
  "context": {
    "source": "voice"
  }
}

{
  "action": "trickplay",
  "data": {
    "direction": "backward",
    "speed": 2
  },
  "context": {
    "source": "voice"
  }
}

Details

A Firebolt compliant representation of a user intention to fast-forward or rewind in-progress playback.

SeekIntent

type SeekIntent = {
  action: "seek"
  context: {
    source: 'voice' | 'channel-lineup' | 'editorial' | 'device'
  }
  data?: true
}

{
  "action": "seek",
  "data": {
    "seconds": 300
  },
  "context": {
    "source": "voice"
  }
}

{
  "action": "seek",
  "data": {
    "direction": "forward",
    "seconds": 30
  },
  "context": {
    "source": "voice"
  }
}

{
  "action": "seek",
  "data": {
    "direction": "backward",
    "seconds": 30
  },
  "context": {
    "source": "voice"
  }
}

Details

A Firebolt compliant representation of a user intention to seek to a different time for in-progress playback.

SkipIntent

type SkipIntent = {
  action: "skip"
  context: {
    source: 'voice' | 'channel-lineup' | 'editorial' | 'device'
  }
  data?: true
}

{
  "action": "skip",
  "data": {
    "direction": "forward",
    "count": 1
  },
  "context": {
    "source": "voice"
  }
}

{
  "action": "skip",
  "data": {
    "direction": "backward",
    "count": 1
  },
  "context": {
    "source": "voice"
  }
}

Details

A Firebolt compliant representation of a user intention to skip a scene/chapter/ad during in-progress playback.

ClosedCaptionsIntent

type ClosedCaptionsIntent = {
  action: "closedcaptions"
  context: {
    source: 'voice' | 'channel-lineup' | 'editorial' | 'device'
  }
  data?: {
    value?: boolean
    toggle?: true
  }
}

{
  "action": "closedcaptions",
  "data": {
    "value": false
  },
  "context": {
    "source": "voice"
  }
}

{
  "action": "closedcaptions",
  "data": {
    "toggle": true
  },
  "context": {
    "source": "voice"
  }
}

Details

A Firebolt compliant representation of a user intention to enable/disable closed captions.

AudioDescriptionIntent

type AudioDescriptionIntent = {
  action: "audiodescriptions"
  context: {
    source: 'voice' | 'channel-lineup' | 'editorial' | 'device'
  }
  data?: {
    value?: boolean
    toggle?: true
  }
}

{
  "action": "audiodescriptions",
  "data": {
    "value": false
  },
  "context": {
    "source": "voice"
  }
}

{
  "action": "audiodescriptions",
  "data": {
    "toggle": true
  },
  "context": {
    "source": "voice"
  }
}

Details

A Firebolt compliant representation of a user intention to enable/disable audio descriptions.

MessageIntent

type MessageIntent = {
  action: "message"
  context: {
    source: 'voice' | 'channel-lineup' | 'editorial' | 'device'
  }
  data?: {
    value?: string
  }
}

{
  "action": "message",
  "data": {
    "value": "Here's a message"
  },
  "context": {
    "source": "voice"
  }
}

Details

A Firebolt compliant representation of a platform intention to display a message on the device.

Identifier

type Identifier = string

Filter

type Filter = {
  key?: string
  value?: string
}

Keyword

type Keyword = {
  keyword?: string
  type?: string
  appId?: string
}

DirectionalOperation

type DirectionalOperation = {
  direction?: 'forward' | 'backward'
}

BooleanToggle

type BooleanToggle = {
  value?: boolean
  toggle?: true
}

IntentMessage

type IntentMessage = {
  type: string
}