Skip to main content

Link, unlink or reorder an episode’s guests from code, as the episode editor’s selector does

Premium Intermediate Guest Manager

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 (otherwise 404 benecaster_guest_manager_episode_not_found), and Guest Manager must be on for its show (otherwise 403 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 POST after the episode’s first save, and only if that episode’s show has Guest Manager on.
  • Every route answers { items, free_names }. items is the episode’s published guests in order, each { id, name, title, organization, photo_url } (photo_url the thumbnail, or ''). free_names is 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:

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 ) );
} );

View on GitHub →

Hooks Used

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