Skip to main content

Read a show’s community sync status, or start a resync, from code

Premium Intermediate Community Integrations

The two routes behind a show’s Community settings tab. Both are for administrators only (manage_options, with the X-WP-Nonce header). Both refuse 404 benecaster_community_no_show for an ID that isn’t a show and 403 benecaster_community_off_for_show for a show where the add-on is switched off (Community Integrations is switched off for this show. Switch it on under Settings → Add-ons.). One show’s route never reads or changes another show’s community.

  • GET /wp-json/benecaster-community-integrations/v1/shows/{show_id}/community answers 200 { platforms, sync, failures, merge_tags }. platforms: every registered platform as { slug, configured }, configured asked of this show. sync: { last_synced, synced, retrying, failed }, the latest success already formatted in the site’s date and time format and time zone (or null), and how many member-and-platform pairs are in each state. failures: up to 20 pairs that are retrying or failed, newest first, as { user_id, name, email, platform, status, error, updated }. merge_tags: the add-on’s merge tags as { tag, description }: {{circle_community_url}} and {{discord_invite_url}}. Never a credential.
  • POST /wp-json/benecaster-community-integrations/v1/shows/{show_id}/resync answers 202 { queued: true } and resyncs the show in the background, in batches of 100: every active token holder plus every member a platform was told about there. A second request while the first batch is still waiting joins it. The same resync starts by itself when the add-on is switched back on for the show.

The tab’s Circle and Discord panels have routes of their own, with the same permission and the same 404 and 403 refusals. None ever returns a secret: an API key, bot token or Client Secret can be written but not read back, and the response says only whether one is saved.

  • GET / PUT …/shows/{show_id}/circle answers 200 { has_api_key, connected, community_url, community_name, verified, space_map, tag_map, remove_on_cancel, tiers }. PUT takes any of api_key (a new key clears the last test result), clear_api_key, community_url (https:// added if missing, trailing slash dropped), space_map and tag_map (tier slug => Circle ids) and remove_on_cancel, and answers like GET. A changed space_map or tag_map updates every member already on Circle in the background.
  • POST …/shows/{show_id}/circle/test is Test connection with the saved key: 200 { community_name, spaces, member_tags }, recording the community’s name and the time. It answers 400 benecaster_community_circle_invalid with no key saved, 400 benecaster_community_circle_{kind} with Circle’s reason in words (a bad key, a plan without Admin API access, Circle unreachable), and 429 benecaster_community_circle_rate_limited.
  • GET / PUT …/shows/{show_id}/discord answers 200 { has_bot_token, has_client_secret, connected, client_id, guild_id, server_name, verified, invite_url, role_map, base_role, on_cancel, former_role, tiers, redirect_url, connected_count }. redirect_url is the Redirect URL to register on the Discord application’s OAuth2 page for Connect Discord, the same for every show. connected_count is how many of the show’s subscribers have connected Discord and hold one of its tiers: a count, never who. PUT takes any of bot_token (a new token clears the last test), clear_bot_token, client_id, client_secret, clear_client_secret, guild_id (a new server clears every role choice), invite_url (any host, so a custom invite link works), role_map (tier slug => role ids), base_role, on_cancel (remove_roles, former_role or kick) and former_role, and answers like GET. A changed role_map or base_role updates every connected member in the background.
  • POST …/shows/{show_id}/discord/test is Test connection with the saved token: 200 { bot_name, client_id, servers, guild_id, server_name, roles: [{ id, name, assignable }], problems }. It chooses the server when none is chosen and the bot is in exactly one, and fills an empty Client ID from the bot’s application. problems lists, in words, what the test found wrong while still succeeding: Manage Roles or Create Invite missing, a mapped role at or above the bot’s, the kick permission missing when removing members is chosen, a Client ID or Client Secret Discord refuses, the server not found, mapped roles deleted.

Code

<?php
// A nightly check: resync any show whose community has failures.
$status = rest_do_request( new WP_REST_Request( 'GET', "/benecaster-community-integrations/v1/shows/{$show_id}/community" ) )->get_data();
if ( ( $status['sync']['failed'] ?? 0 ) > 0 ) {
    rest_do_request( new WP_REST_Request( 'POST', "/benecaster-community-integrations/v1/shows/{$show_id}/resync" ) );
}

View on GitHub →

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