Manage or change AI Search’s pinned results
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
postorpagewith no password. A post or page result hasdate: ''and its own excerpt. - A pin chooses the position, never the access: a pinned episode the visitor cannot open is left out in a
hiddenbox and is a lock card in alockedone. - 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_invalidand400 benecaster_ai_search_pin_priority_invalid(each withfield),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. pinnableis 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 ): arrayfilters 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 noidorcreated_at) andbenecaster_ai_search_after_pin_save( array $pin, bool $created ).benecaster_ai_search_before_pin_delete( array $pin )andbenecaster_ai_search_after_pin_delete( array $pin ).- Each
$pinis{ id, show_id, keyword, post_id, active, priority, created_at }. Theafteractions 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 );
Hooks Used
Need this built rather than just documented? See our services →