Skip to main content

Run or watch the guest import from code

Premium Intermediate Guest Manager

Report on an import, or run one from a script, through the routes behind Benecaster → Guests → Import Existing Guests. That screen turns the names typed into episodes’ Guests tab before Guest Manager into guest profiles, linked to their episodes.

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) and exist only while Guest Manager is on for at least one show.

  • Only episodes on shows where Guest Manager is on are read, any status but trash and auto-draft. The typed names are read, never written: they stay saved in the episode.
  • A group is one normalized name: case, accents, full stops, commas, apostrophes and quotes ignored, hyphens and runs of spaces read as one space.
  • A name counts as imported once its episode has a linked guest with that normalized name. No other record of an import is kept, so linking the guest any other way retires the matching names too.
  • existing is the oldest published guest on the roster with the group’s normalized name, or null.

GET /import → { groups, fingerprint, dismissed, row_count }. Each group is { key, name, website, existing: { id, name } | null, entries }, A–Z by name. name is the spelling most episodes use (a tie goes to the newest episode’s); website is the newest episode’s http/https address, or ''. Each entry is { episode_id, episode_title, show_id, show_title, when, name, website }, newest episode first: when is a published episode’s date in the site’s format, otherwise its status (Draft, Scheduled, Pending review, Private), and name and website are as typed on that episode. fingerprint is a 40-character hash of what is waiting ('' for nothing); dismissed is whether Not Now was pressed on exactly that.

POST /import takes { decisions: [...] }, one per group to import:

  • { key, action: 'link', guest_id, episode_ids } links the episodes to the group’s existing guest, and only that guest.
  • { key, action: 'create', name, website, email?, episode_ids } creates a guest first (name required, up to 200 characters; a website that is not http/https is dropped, not refused). email is optional and private: when a guest already has it, the group’s episodes go to that guest instead (counted in linked_existing) and nothing is created.

Emails are checked for every group before anything is written. A badly formed email, or one email given to two create decisions that have episodes, refuses the whole import before benecaster_guest_manager_before_import fires: created, linked_existing and links_added are 0, and failed opens with { key: '', name: '', message: 'Nothing was imported. Fix the emails below, then import again.' }, then one entry per offending group.

Only the group’s own episode_ids are used; leaving one out leaves that episode offered. The groups are worked out again on the server, so a stale screen cannot link an episode that is no longer waiting. Each episode’s new links go after its existing guests, in the order its names were typed, and each writes the episode note Guest linked: {name} added to this episode. Every show touched has its feed refreshed once. A created guest fires benecaster_guest_manager_before_save_guest and benecaster_guest_manager_after_save_guest, as the Guests screen does. The answer is { result: { created, linked_existing, links_added, failed: [ { key, name, message } ] }, plan }, plan being what GET would now answer. A group that fails is reported and the others still import. A body whose decisions is not a list is 400 benecaster_guest_manager_invalid_import.

POST /import/dismiss takes { fingerprint } (40 lowercase hex characters, otherwise 400 benecaster_guest_manager_invalid_import) and answers { dismissed: true }. The roster’s import box then stays hidden until the fingerprint changes.

benecaster_guest_manager_before_import fires with the $decisions before anything is written; benecaster_guest_manager_after_import fires once the import has finished, with the result above.

Code

<?php
// Tell a Slack channel how many guests an import made.
add_action( 'benecaster_guest_manager_after_import', static function ( array $result ): void {
    if ( $result['created'] + $result['linked_existing'] === 0 ) {
        return;
    }
    my_slack_post( sprintf(
        'Guest import: %d new guests, %d existing guests linked, %d episode links.',
        $result['created'],
        $result['linked_existing'],
        $result['links_added']
    ) );
} );

View on GitHub →

Hooks Used

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