Skip to main content

Manage or change AI Search’s pinned results

Premium Intermediate AI Search

Put a chosen post first in a show’s AI Search box for a phrase (getting started → Episode 1, sponsor → the sponsorship page), from code as well as from the screen, and react when the podcaster changes their pins.

A pin places a post first in one show’s benecaster_ai_search box when the listener’s query contains its words, ignoring case and spacing (no similarity matching). Pins are managed on Show Settings → AI Search. Each has an id, show_id, keyword (up to 191 characters), post_id, active, priority (0–999, lower first) and created_at (UTC).

  • What may be pinned: an episode of that show, or a published post or page with no password. A post or page result has date: '' and its own excerpt.
  • A pin chooses the position, never the access: a pinned episode the visitor cannot open is left out in a hidden box and is a lock card in a locked one.
  • Firing pins come first, by priority then oldest first, are removed from further down, and count toward the 10 results. Pins cost nothing, so they are applied even when the provider could not rank.

The REST routes, under /wp-json/benecaster-ai-search/v1, are admin only (manage_options, through benecaster_rest_permission_admin(), with the X-WP-Nonce header), and answer 403 benecaster_ai_search_not_active for a show with AI Search off:

  • GET /shows/{show_id}/pins → { pins: [ { id, keyword, post_id, active, priority, post: { title, type_label, url, pinnable } } ] }
  • POST /shows/{show_id}/pins { keyword, post_id, active?, priority? } → 201 { pin }
  • PUT /shows/{show_id}/pins/{id} with any of those fields → { pin }
  • DELETE /shows/{show_id}/pins/{id} → { deleted: true }
  • GET /shows/{show_id}/pins/posts?search= → { posts: [ { id, title, type, type_label } ] }, at most 20, the show’s episodes first.
  • Refusals: 400 benecaster_ai_search_pin_keyword_invalid, 400 benecaster_ai_search_pin_post_invalid and 400 benecaster_ai_search_pin_priority_invalid (each with field), 409 benecaster_ai_search_pin_duplicate (the same words already pin that post, ignoring case), 404 benecaster_ai_search_pin_not_found, 500 benecaster_ai_search_pin_not_saved.
  • pinnable is false once the post is unpublished or password-protected: the pin is kept and never fires.

The hooks:

  • benecaster_ai_search_pinned_results( array $pins, string $query, int $show_id ): array filters the pins firing for one search, in order, each { post_id, keyword, priority }: add, drop or reorder. Every entry is still checked: only pinnable posts are placed, and access still decides how.
  • benecaster_ai_search_before_pin_save( array $pin, int $show_id ) (a new pin has no id or created_at) and benecaster_ai_search_after_pin_save( array $pin, bool $created ).
  • benecaster_ai_search_before_pin_delete( array $pin ) and benecaster_ai_search_after_pin_delete( array $pin ).
  • Each $pin is { id, show_id, keyword, post_id, active, priority, created_at }. The after actions fire only once the write succeeded, and none fires for a refused request.

Code

<?php
// During a live event, pin the event page for "live" on show 12, ahead of the podcaster's own pins.
add_filter( 'benecaster_ai_search_pinned_results', function ( array $pins, string $query, int $show_id ): array {
    if ( 12 === $show_id && false !== stripos( $query, 'live' ) ) {
        array_unshift( $pins, [ 'post_id' => 345, 'keyword' => 'live', 'priority' => 0 ] );
    }
    return $pins;
}, 10, 3 );

View on GitHub →

Hooks Used

Need this built rather than just documented? See our services →