TV Conversational Search plugin

Introduction

The TV Conversational Search plugin resolves requests from a user to obtain personalized recommendations for audiovisual content from Telefónica catalogs.

• Intent: intent.conversational.search
• Main result intents: MEDIA.SEARCH (default), CHANNEL.PLAY (when zapping to a live channel).

Validate input request

This step validates that the input request fulfills all the requirements from the input schema.

If the input data is invalid, the resource returned is:

• tv:video.model-validation.request.error.

Entities used for search

The plugin works with the following entity types:

Multiple entities & values:
You can repeat the same entity type multiple times and/or provide several values in a single entity using the \|\| separator.

Building the search query

The plugin constructs two query strings:

1. search_query → technical query sent to Kernel API:

   • Group query and channel entities in parentheses.
   • Joins different entity types with AND.
   • Query: split on ||, trim each value, and join with OR inside the parentheses (no quotes).
   • Example:

     (mystery OR series)
     

2. search_query_response → a simplified, user-readable query string included in the payload and telemetry.

If no entities are present, the plugin returns a no results response.

API video query (Handler 4P)

Plugin calls Handler4P.tv_4p_handler.get_user_content_search(...) with the following parameters:

• user_id: data[aura_user][user_id]
• administrative_number: data[app_context][user][account_number]
• access_token: data[aura_user][access_token]
• scopes: data[aura_user][scopes]
• purposes: data[aura_user][purposes]
• device_type: data[app_context][device][type]
• catalog_types:
  • Default: VOD, LIVE, L7D
  • Allowed: VOD, LIVE, L7D, LCH, LSR
  • Filtered according to allowed_catalog_types of the device
• search_query: built as explained above
• show_series: series
• profile: data[app_context][user][video_profile_name] (optional; only if present to avoid API 501 errors)
• commercialization_types: [SVOD]
• max_quality: data[app_context][device][max_quality] (optional)
• current_region: data[app_context][location][currentRegion] (optional)
• order: personal

Response logic

Depending on the number and type of results, the plugin builds different responses:

1. No results

• Plays negative sound unless the channel is disabled in the sound_disabled_channels configuration
• result_intent: MEDIA.SEARCH
• Resource: tv:video.conversational.search.no-results
• Status: SUCCESS.NO_CONTENT

2. One result

• Live channel:
  • Payload: { type: details, data: <channel info> }
  • Action: REMOTEON.ZAPTO (with params channelId and deviceId)
  • Plays positive sound
  • result_intent: CHANNEL.PLAY
  • Resource: tv:video.conversational.search.single-result
• Non-live content (VOD, L7D, etc.):
  • Payload: details of the single item
  • Plays positive sound unless the channel is disabled in the sound_disabled_channels configuration
  • result_intent: MEDIA.SEARCH
  • Resource: tv:video.conversational.search.by-default.simple-result

3. Multiple results

• Payload: list of items
• Plays positive sound unless the channel is disabled in the sound_disabled_channels configuration
• result_intent: MEDIA.SEARCH
• Resource: tv:video.conversational.search.multiple-results (with param query_displayed)

Resources returned

The TV Recommend plugin may return the following resources:

• tv:video.model-validation.request.error → input validation error
• tv:video.api.answer.error → API Video error
• tv:video.conversational.search.no-results → no content found
• tv:video.conversational.search.by-default.simple-result → one non-live result
• tv:video.conversational.search.multiple-results → multiple results
• tv:video.conversational.search.display.single-result → one live channel (tune channel)

Payload and actions

• Payload:

  • type: details (single item) or content_list (multiple items)
  • data: item(s) from Kernel API
  • For multiple results: includes search_query (human-readable string)

• Actions:

  • Sound feedback (positive/negative)
  • For a single live channel: {"name": "REMOTEON.ZAPTO", "params": {"channelId": "$channelId", "deviceId": "$deviceId"}, "target": "stb"}

Status codes

• status: Final status request. This field includes the following parameters:
  • code: Status code with value: SUCCESS, SUCCESS.NO_CONTENT or ERROR.INTERNAL.
  • message: Status message, which describes the status code.
  • params: Parameter that sends details of status. This field does not appear if it is empty.

Example behavior

• “Recommend me something”
  • for a single live channel result → CHANNEL.PLAY tune channel with live channel.
  • for a multiple results → MEDIA.SEARCH with tv:video.conversational.search.multiple-results.
  • for any results → tv:video.conversational.search.no-results.