Link, unlink or reorder an episode’s guests from code, as the episode editor’s selector does
Link guests to an episode from a booking tool, keep your own data in step with an episode’s guests, or reorder them from a script, using the routes behind the episode editor’s Guests tab. On a show with Guest Manager on, that tab shows Guest Manager’s guest selector in place of the free name rows.
The routes live under /wp-json/benecaster-guest-manager/v1. They are admin only (manage_options, through benecaster_rest_permission_admin(), with the X-WP-Nonce header).
- Every route checks the episode’s own show.
{id}must be an episode that is not trashed or an auto-draft (otherwise404 benecaster_guest_manager_episode_not_found), and Guest Manager must be on for its show (otherwise403 benecaster_guest_manager_off_for_show). A switched-off show’s links can be neither read nor changed here. - Each request is saved at once, not with the episode. On a new episode the selector holds the chosen guests in the browser and sends them in one
POSTafter the episode’s first save, and only if that episode’s show has Guest Manager on. - Every route answers
{ items, free_names }.itemsis the episode’s published guests in order, each{ id, name, title, organization, photo_url }(photo_urlthe thumbnail, or'').free_namesis the names in the episode’s free guest rows that no linked guest matches by normalized name (as in the import), each once, in row order. The free rows are read, never written. - A link writes the episode note Guest linked: {name} added to this episode., an unlink Guest removed: {name} unlinked from this episode., and a reorder none. Any change that wrote something refreshes the show’s feed once, since the guests’ order is the order of the
<podcast:person>tags.
GET /episodes/{id}/guests answers as above.
POST /episodes/{id}/guests takes { guest_ids: [int, …] }: 1 to 100 distinct positive ids, linked in that order after the episode’s existing guests. A guest already linked is skipped quietly, so repeating a request changes nothing. A guest not on the roster refuses the whole request before anything is written (400 benecaster_guest_manager_unknown_guest, with data.guest_id). A list that is missing, empty, not a list, over 100, or holds a repeat, zero, negative or non-numeric id is 400 benecaster_guest_manager_invalid_guests (data.field guest_ids). Nothing new to link answers 200 with no note and no feed refresh; every write failing is 500 benecaster_guest_manager_link_failed.
DELETE /episodes/{id}/guests/{guest_id} unlinks one guest; the guest stays on the roster. A guest not linked to the episode is 404 benecaster_guest_manager_not_linked.
PUT /episodes/{id}/guests/order takes { guest_ids }, which must be exactly the episode’s guests in a new order. Any other set is 409 benecaster_guest_manager_stale_guests (the screen is out of date); the same order answers 200 and writes nothing.
The hooks:
- benecaster_guest_manager_before_change_episode_guests
( int $episode_id, string $change, array $guest_ids )fires once a request has validated and before it writes.$changeislink(the guests about to be linked, already-linked ones left out),unlink(the one guest) orreorder(the new order). - benecaster_guest_manager_after_change_episode_guests has the same arguments and fires once the write is done; for
link, the guests actually linked.
Neither fires for a refused request or one that wrote nothing. Import Existing Guests does not fire them; it has its own pair.
Code
<?php
// Keep a "featuring" line in your own episode meta, refreshed whenever the selector changes the guests.
add_action( 'benecaster_guest_manager_after_change_episode_guests', static function ( int $episode_id ): void {
$names = array_column( benecaster_guest_manager_get_episode_guests( $episode_id ), 'name' );
update_post_meta( $episode_id, '_my_featuring', implode( ', ', $names ) );
} );
Hooks Used
Need this built rather than just documented? See our services →