Gist Answers for WordPress – User guide

The Gist Answers plugin: What it does, what it needs, every setting and placement option, and how it handles your data.

Plugin version
1.0.16
Requires
WordPress 6.8+, PHP 8.0+
Tested up to
WordPress 7.0, PHP 8.5
License
GPLv2
New to the plugin? Start with Getting started.Checking fit before you connect a site? See Limitations.
Getting started

Installation

The current release is available as a ZIP at cdn.gist.ai/wordpress/gist-answers-wp-plugin.zip. The release ZIP ships with its compiled assets and autoloader, so no build step is needed. The plugin folder is gist-answers and the entry file is gist-answers.php.

For a screenshot-by-screenshot walkthrough of each option, see Step 1 of the setup guide.

Standard WordPress

  • Single site: go to Plugins → Add Plugin → Upload Plugin, choose the ZIP, click Install Now, then Activate Plugin.
  • Multisite: log in as a network administrator, go to My Sites → Network Admin → Plugins → Add Plugin → Upload Plugin, choose the ZIP, click Install Now, then Network Activate.
  • Alternatively, upload the unzipped gist-answers folder to wp-content/plugins/ and activate it from the Plugins screen.

WordPress VIP

VIP does not allow plugins to be uploaded from the WordPress admin. Use one of these two options.

VIP supplies, loads and updates the plugin, and the API key is managed in the VIP Dashboard rather than in WordPress. An Org admin adds the integration to the organization; an App admin or Org admin configures it for each environment.

  1. 1In the VIP Dashboard, open the Integrations Center, open Gist Answers, and click + Add to Organization.
  2. 2Open your application, select Integrations, and choose an environment. Start with production: the first site you activate in the plugin must be your live site.
  3. 3Click Configure next to Gist Answers, turn Activate Integration to Active, enter the key from your onboarding email in the Gist API token field, and save. On a multisite network this activates the plugin for every site in the network.
  4. 4Repeat for any staging or development environment you want to test on, using the same key.

The plugin then reads the key from the VIP runtime config and hides its own key-entry form. See “WordPress VIP runtime config” under Connecting to Gist Answers.

Option B: install the plugin through your wpcomvip repository

Use this to manage the plugin code yourself. You need write access to the site’s wpcomvip GitHub repository. VIP’s guide to adding plugins covers the workflow in detail.

  1. 1Unzip the plugin. VIP needs the gist-answers folder, not the ZIP.
  2. 2In the repository, create a branch and add the folder to the plugins directory.
  3. 3Open a pull request and merge it into the branch that deploys to production, plus any non-production environments you want to test on. VIP deploys merged code automatically.
  4. 4Activate the plugin from the Plugins screen (Network Activate on a multisite network), or in code as described below.

With a manual install, the API key is entered in the plugin dashboard, the same as on standard WordPress, unless you supply it through an environment variable or constant. See “API key sources” under Connecting to Gist Answers.

Activating in code on WordPress VIP

VIP recommends loading plugins in code so that every environment runs the same set. Instead of activating Gist Answers from the Plugins screen, add this line to client-mu-plugins/plugin-loader.php and deploy it:

wpcom_vip_load_plugin( 'gist-answers' );

On a multisite network this loads the plugin for every site. A plugin loaded this way shows no Deactivate or Network Deactivate link on the Plugins screen; to remove it, delete the line and deploy again. See “Deactivating” under Maintenance.

After activation

A Gist Answers item appears in the WordPress admin menu (on Multisite, under My Sites → Network Admin → Dashboard as well as in each site’s own admin), and a notice links to the dashboard where you connect the site. The plugin makes no requests to Gist Answers until an API key is available from one of the supported sources.

Developer reference

Filters, actions and constants

Filters

FilterPurpose and default
Content ingestion
gist_answers_ingest_post_typesPurpose and defaultPost types to ingest. Default array( 'post' ).
gist_answers_ingest_post_statusesPurpose and defaultEligible post statuses. Default array( 'publish' ).
gist_answers_ingest_tax_queryPurpose and defaultA tax_query array content must match. Default array() (all terms).
gist_answers_should_enqueue_post_for_ingestionPurpose and defaultPer-post eligibility: ( bool $should, int $post_id, WP_Post $post ). Default true.
gist_answers_max_posts_for_ingestionPurpose and defaultPosts sent per run, clamped to 1–100. Default 10.
gist_answers_min_delay_for_ingestionPurpose and defaultSeconds to wait before sending a change, clamped to 1–300. Default 5.
Answer page detection
gist_answers_answer_page_typesPurpose and defaultPost types scanned for answer widgets. Default array( 'page', 'post' ).
gist_answers_answer_page_statusesPurpose and defaultStatuses scanned. Default array( 'publish' ).
gist_answers_max_flagged_answer_widget_postsPurpose and defaultFlagged posts processed per run, clamped to 1–100. Default 10.
Widget rendering
gist_answers_render_widgetPurpose and defaultThe arguments array passed to gist_answers_render_widget() (and used by the shortcode and blocks), before it is sanitized. Return a modified array to change the type, ID, target or echo behavior.
gist_answers_widget_htmlPurpose and defaultThe widget HTML about to be output: ( string $html, array $original_args ). Return an empty string to suppress the widget.
Other
gist_answers_network_sites_per_pagePurpose and defaultSites per page in the Network Hub, up to 100. Default 20.
gist_answers_api_timeoutPurpose and defaultTimeout in seconds for Gist API requests: ( int $seconds, bool $is_front_end ). Default 2 on the front end, 3 elsewhere.
gist_answers_error_logPurpose and defaultThe message about to be written to the PHP error log by the plugin’s logging function.

Actions

ActionWhen it fires
gist_answers_plugin_activated, gist_answers_plugin_deactivated, gist_answers_plugin_uninstalledWhen it firesOn plugin activation, deactivation and uninstall.
gist_answers_api_connectedWhen it firesAfter an API key entered in the dashboard has been validated and stored.
gist_answers_api_disconnectedWhen it firesWhen the stored key is rejected by Gist Answers. Receives 'single' or 'network'.
gist_answers_post_enqueued_for_ingestionWhen it firesWhen a post is queued: ( int $post_id, WP_Post $post ).
gist_answers_post_ingestedWhen it firesAfter a post’s permalink has been sent to Gist Answers: ( int $post_id, $response ).
gist_answers_post_flagged_as_answer_pageWhen it firesWhen an answer widget is detected in saved content: ( int $post_id ).
gist_answers_get_publishers, gist_answers_get_publishers_sites, gist_answers_get_publishers_widgets, gist_answers_post_publishers_ingest, gist_answers_put_publishers_crawl, gist_answers_delete_publishers_crawl, and one action per other API endpointWhen it firesAfter each call to the corresponding Gist Answers API endpoint, with the request object; gist_answers_api_call_count reports the number of calls made in a request. Useful for logging and diagnostics.

Constants and functions

NamePurpose
GIST_ANSWERS_API_KEYPurposeSupplies the API key as a PHP constant (or as an environment variable of the same name). See “API key sources” under Connecting to Gist Answers.
VIP_GIST_ANSWERS_CONFIGPurposeDefined by WordPress VIP, not by you. See “WordPress VIP runtime config” under Connecting to Gist Answers.
GIST_ANSWERS_SHOW_DEVELOPER_MENUPurposeSet to true to show the Developer menu. See Developer menu.
GIST_ANSWERS_VERSIONPurposeThe installed plugin version (read-only).
DISABLE_WP_CRONPurposeNot a plugin constant, but it matters: with WP-Cron disabled, queued content is sent only during admin activity.
gist_answers_render_widget( array $args )PurposeRenders a widget from PHP. See “PHP function” under Widgets.
gist_answers_error_log( string $message )PurposeWrites to the PHP error log through the gist_answers_error_log filter, adding a backtrace when that developer option is on.

Other identifiers you may meet while debugging: the REST namespace gist-answers/v1 used by the plugin’s own admin screens (not a public API), the WP-Cron hook gist_answers_ingest_queued_posts, options and transients prefixed gist_answers_, and the post meta keys gist_answers_ingest_after, gist_answers_ingest_response and gist_answers_answer_widget_*.

Troubleshooting content ingestion and answers

Most ingestion problems come down to one of four causes: the content is not eligible, the plugin has not sent it, Gist Answers cannot read the site, or Gist Answers has not finished crawling. Check them in that order.

For setup problems (API keys, linking a site, a widget that never appeared), see the Troubleshooting section of the setup guide.

Where to look

  • Gist Answers → Dashboard: the Status column for each site, and Refresh ingestion status, which fetches the latest status from Gist Answers. The status does not update on its own.
  • Manage → Sandbox: ask a question about a specific article and see whether its content is used, with a side-by-side view for comparing content-source settings. See Manage.
  • Reports → Content Usage: which of your content is used and cited in answers. Reports → Answers → Questions lists the questions visitors have asked.
  • Manage → Website Settings: the Homepage URL, the Dev site URL if you use one, and the Content sources setting, which decides whether answers draw on your site alone or also on your other publications, Wikipedia and the Gist content network.
  • Developer → Tools & Options (shown when GIST_ANSWERS_SHOW_DEVELOPER_MENU is set): Log API responses and Count API requests write each call to Gist Answers to the PHP error log with credentials redacted; Detected Answer Pages lists the pages the plugin has found answer widgets in. Enable logging only while you investigate. See Developer menu.
  • Post meta on each post: gist_answers_ingest_after is the Unix timestamp when the post is due to be sent, set on save to now plus the minimum delay (5 seconds by default) and reset by every save; while it is present the post is queued, and the cron job deletes it just before sending. gist_answers_ingest_response is the result of the last send: time, code (the HTTP status, or 999 if the request never completed), text (the raw body; {"error": "…"} on a 999) and data (the body decoded as JSON). A code of 200 means the permalink reached Gist Answers.
  • WP-Cron: the sending hook is gist_answers_ingest_queued_posts; while posts are waiting it reschedules itself one minute later. wp cron event list shows it, and wp cron event run gist_answers_ingest_queued_posts runs it immediately.
  • Custom logging: hook gist_answers_post_enqueued_for_ingestion, gist_answers_post_ingested and gist_answers_post_publishers_ingest to log sends to your own tooling. See Filters, actions and constants.
  • Browser console: on the front end, widget problems are logged as errors beginning Gist Answers: No widget HTML is available.
The status stays on Ingestion queued

Activation normally moves a site to Ingestion active immediately, so a status that still reads Ingestion queued after a refresh is a problem to investigate, not a wait.

  1. 1Click Refresh ingestion status. The dashboard shows the last status it fetched, not a live one.
  2. 2Check that the Content ingestion toggle for the site is on.
  3. 3Confirm the REST API posts endpoint is reachable by an anonymous visitor: open https://your-site.com/wp-json/wp/v2/posts in a private browser window. You should see JSON. A 401 or 403, a login prompt or a security challenge means the crawl of the feed fails. On WordPress VIP, also check that platform security rules and bot protection are not blocking the crawler.
  4. 4Open Manage → Website Settings and confirm the Homepage URL is filled in, and the Dev site URL if the site is a test site.
  5. 5Email support@gist.ai with the website URL and the time you activated it. Restarting a crawl needs Gist’s operations team.
The status shows “Error — API does not properly support 'after' parameter”

Before Gist Answers starts crawling a site, it checks that the site’s REST posts feed can be filtered by date with the after parameter. On sites with only a few posts, this check used to fail even when the feed was working: it asked for posts newer than the newest post, received the correct empty list, and treated that as the filter being ignored. Gist fixed the check on 3 November 2026, so a site with at least 2 published posts and a working feed now passes.

  1. 1Click Refresh ingestion status. If the status now shows Ingestion active, nothing else is needed.
  2. 2Check that the site has at least 2 published posts. The check compares post dates, so it needs two. With fewer, the status shows Error — Less than 2 articles on site instead. Publish another post so there are at least two, then go to step 4.
  3. 3Confirm the feed honors after for an anonymous visitor: open https://your-site.com/wp-json/wp/v2/posts?after=2099-01-01T00:00:00 in a private browser window. You should see an empty list, []. If you see posts, something in front of WordPress is ignoring the query string, such as a page or edge cache rule, a security rule, or a plugin that changes REST queries. Fix that before you go on.
  4. 4Email support@gist.ai with the website URL and ask for the site check to be run again. Refresh ingestion status fetches the latest status but does not repeat the check, so a site that already shows this error keeps it until Gist runs the check again.
Answers say “Looks like I don’t have the sources…” for content that is on the site

This response is expected until the content in question has been ingested. It also appears when the question is about content that is not eligible for ingestion, or that Gist Answers cannot read.

  1. 1Check the Status column: it should show Ingestion active, not Ingestion queued or Ingestion paused.
  2. 2Confirm the content is eligible: a post (not a page or custom post type, unless a filter adds it) with status Published, not excluded by a gist_answers_ingest_tax_query or gist_answers_should_enqueue_post_for_ingestion filter. See “Customizing what is ingested” in Content ingestion.
  3. 3Confirm the post is returned with its content to an anonymous request: open https://your-site.com/wp-json/wp/v2/posts?slug=the-post-slug in a private browser window. A password-protected post comes back marked protected with empty content, and a paywall plugin that strips content for anonymous visitors has the same effect; Gist Answers can answer from neither.
  4. 4Try the question in Manage → Sandbox, and check Reports → Content Usage to see whether the article has been used in any answer.
  5. 5If the message persists after the status shows Ingestion active and the content is eligible and readable, contact your Gist onboarding contact with the article URL and the question you asked.
A new or updated post is not reflected in answers

An eligible post is queued when a logged-in user who can edit it saves it, or when a scheduled post goes live. WP-Cron sends the queued permalinks after a minimum delay of 5 seconds, up to 10 posts per run, with the next run one minute later while more are waiting. Gist Answers then fetches the content and updates its index.

  1. 1Check eligibility, as above. A post moved out of Published status is not sent.
  2. 2Check who saved it. Saves by the WordPress Importer run by an administrator, by REST API requests with a user (for example an application password), and by WP-CLI with --user are queued. WP-CLI without --user, wp_insert_post() with no current user (cron jobs, scripts), direct SQL and database imports are not. Saving the post again from the editor queues it.
  3. 3Check that WP-Cron is running. If DISABLE_WP_CRON is set, or the site gets little traffic, queued content is sent only while someone is using the WordPress admin, and a post published and then left alone is not sent until an administrator opens the admin.
  4. 4Check the Dashboard for a notice that the API key was rejected or Gist Answers could not be reached. While the key cannot be confirmed, nothing is sent and the queue is retried every 5 minutes.
  5. 5Check the post’s gist_answers_ingest_response. A code of 200 means the permalink reached Gist Answers. A server error or 999 means the send failed, and failed sends are not retried: save the post again. Log API responses shows the same request and response in the PHP error log.
  6. 6If your page or edge cache is serving the old version, purge the post’s permalink and https://your-site.com/wp-json/wp/v2/posts/<id>. The plugin does not bypass or purge caches, and both URLs are anonymous URLs a cache can serve.
  7. 7Once the send has succeeded, the remaining delay is Gist Answers’ own fetch and re-index. Gist Answers also re-crawls the feed on its own schedule, so a post the plugin never sent is still picked up on a later crawl. If an update is still not reflected well after a successful send, contact your Gist onboarding contact with the post URL and the time it was saved.
Scheduled posts never reach Gist Answers

Plugin versions before 1.0.15 did not queue posts that WordPress published on a schedule. Update to 1.0.15 or later. Scheduled posts that went live on an earlier version can be queued by saving them again from the editor.

Pages or a custom post type are never used in answers

Only the post type is ingested by default. Add the type with the gist_answers_ingest_post_types filter, in a must-use plugin or your theme’s functions.php (on VIP, in client-mu-plugins), and make sure an anonymous visitor can read the content.

Adding a type is not retroactive. Only items saved after the filter is added are sent, and the initial crawl never includes them, because the only feed registered at activation is the REST posts endpoint. To send existing items, save each one again as an editor, or set gist_answers_ingest_after to the current time on each post and then open any admin page or run wp cron event run gist_answers_ingest_queued_posts. If you want a whole post type crawled as a feed, contact support@gist.ai.

A removed post still appears in answers

The plugin sends nothing when a post is unpublished, trashed, deleted or made private; it has no removal signal, so content already ingested stays in Gist Answers. A removal signal is planned for a later version. In the meantime, email support@gist.ai with the URLs to remove. To remove a whole website from your account, contact support@gist.ai.

The status shows Ingestion paused

The crawl has been stopped with the Content ingestion toggle; ingestion cannot be paused from the Gist console, and deactivating and reactivating the plugin does not pause it either. New and updated content is not available for answers until the crawl is resumed. Switch the toggle on and click Refresh ingestion status. On Multisite, the Network Hub lets a network administrator resume several sites at once.

A site that was working asks for the API key again, or says the key is no longer valid

While the installation is disconnected, widgets do not render and queued content is held; sending resumes once the key is accepted again. Gist issues a new key only when a partner’s key is lost or a regeneration is requested, so a rejected key is either a key someone on your side had regenerated or a key the plugin can no longer read. The fix depends on where the key came from:

  • Entered in the dashboard. If the WordPress security keys and salts in wp-config.php were rotated, the stored key can no longer be decrypted and the dashboard asks for it again. Enter the key from your onboarding email. If the salts were not changed, contact your Gist onboarding contact for a valid key.
  • Environment variable or PHP constant. The notice names the server administrator. Check that the variable or constant is still defined for every PHP process, including cron, and holds the current key.
  • VIP Integrations Center. The key is managed in the VIP Dashboard. Open the application, select Integrations, choose the environment, click Configure next to Gist Answers and enter a valid key in the Gist API token field.

The gist_answers_api_disconnected action fires when the stored key is rejected; hook it to alert your team.

A staging site shows the production site’s connection after a database copy

The plugin stores the site’s Gist website association in the WordPress database, and the encrypted API key as well when it was entered in the dashboard. Copying the production database to another environment (for example a WordPress VIP data sync from production) copies both, and the copy stays linked to the production website: the plugin keeps the stored website while it is enabled in your account and never compares its domain with the site’s home URL.

What happens next depends on the key. A dashboard-entered key is encrypted with the site’s own salts, so on a copy with different salts (the usual case) it decrypts to nothing and the site shows as not connected. On VIP, a key from the environment’s integration config overrides the copied one. With a working key, saving a post on the copy sends the copy’s own permalink to the production website; the first save of a page with an answer widget creates an answer widget for the copy’s URL; the copy shows production’s widgets, so answers come from production content; and posts that were still queued on production when the database was copied are sent by the copy’s cron with the copy’s URLs.

To recover:

  1. 1Stop the copy sending anything. Add a gist_answers_should_enqueue_post_for_ingestion filter in a must-use plugin that returns false unless the environment is production; on VIP, test VIP_GO_APP_ENVIRONMENT === 'production'.
  2. 2Clear the copied queue right after the sync: wp eval 'delete_post_meta_by_key( "gist_answers_ingest_after" );'.
  3. 3Optionally reset the copied connection data with Delete all Gist Answers database options in the developer Danger zone (see Developer menu), reconnect the key if it does not come from the VIP config, and click Activate website. A pre-production domain with a matching website name is linked to the production website automatically.

Two things do not help: deactivating and reactivating the plugin only clears scheduled cron events, and activating the copy as a test website links it to production, where it already is.

An answer page is not recognized

Detection happens inside the save itself: when a user who can edit the page saves, for the first time, a published page or post containing the answer widget block, shortcode or markup, the plugin creates the answer widget in Gist with the page URL, so Gist records the page straight away. The page then appears under Detected Answer Pages in the developer menu on the next admin page load, within a minute.

  1. 1Check that the widget is a top-level block, shortcode or pasted markup in the page content. Widgets nested inside Group, Columns and similar blocks, and widgets rendered from PHP templates, are not detected.
  2. 2Check that the page was saved by a logged-in user who can edit it. Saves with no user (WP-CLI without --user, imports with no user) are never detected.
  3. 3If the request to Gist failed during that first save, it is not retried on later saves. Remove the widget, save the page, then add the widget back and save again.
  4. 4Confirm the question widget’s Answer page points at this page. See Answer pages.
Widgets stopped rendering on a site that was working

For a widget that never appeared, see A widget doesn’t appear on the page in the setup guide. When widgets that were live disappear:

  1. 1Open Gist Answers → Dashboard and look for a notice that the installation is disconnected. A rejected key stops every widget on the installation.
  2. 2Check the browser console on the affected page. The error names the widget type, ID and page slug the plugin tried; a widget that was deleted in Gist, or belongs to a different website, fails this way.
  3. 3During a Gist Answers outage the plugin outputs nothing and caches the failed lookup for 1 minute, so widgets return within about a minute of service being restored. On WordPress VIP, front-end requests back off automatically after repeated failures, so widgets there can take a little longer to return.
  4. 4If the plugin was deactivated, blocks output nothing and shortcodes appear as plain text until it is reactivated.
Ingestion active shows fewer feeds than expected

The status reads Ingestion active (x of y feeds). A feed is a content source Gist Answers crawls; the plugin registers one at activation, the site’s REST posts endpoint, and further feeds (for example other post types) are added by Gist on request to support@gist.ai. If the active count is still lower than the total after Refresh ingestion status, email support@gist.ai with the website URL.

Contacting support

Email support@gist.ai or your Gist onboarding contact with:

  • the website URL and the URL of the affected post or page;
  • the Status shown on the Dashboard and when it last changed;
  • the plugin version, and whether WP-Cron is enabled;
  • your hosting (for WordPress VIP, the application and environment name) and whether the plugin was added from the Integrations Center;
  • the text of any Dashboard notice or browser-console error;
  • for a post that was not ingested, the code and text from its gist_answers_ingest_response post meta, or the publishers/ingest entries from the PHP error log if Log API responses was enabled.

Overview

The Gist Answers plugin connects a WordPress site to Gist Answers, the AI answer service from ProRata.ai. Once a site is connected, the plugin does four things:

  • Keeps your content in syncIt registers the site as a content source in Gist Answers and tells Gist Answers whenever eligible content is published or updated, so answers are grounded in your own articles. See Content ingestion.
  • Displays widgetsIt renders Gist Question Widgets and Answer Widgets anywhere on the site, through blocks, a shortcode, a sidebar widget, or a PHP function. See Widgets.
  • Brings the Gist console into WordPressWidget management, website settings, the sandbox, suggested questions, and reports open inside the WordPress admin. See Admin menu.
  • Manages many sites at onceOn WordPress Multisite, a Network Hub lists every site in the network with its activation and ingestion status. See Multisite.

Two kinds of widget

Question widgetInvites visitors to ask a question and sends them to an answer page.
Answer widgetThe answer experience itself, placed on that answer page.

See “Widget types” under Widgets.

The plugin does not replace the Gist console. Reports, website configuration, widget management, the sandbox, and suggested questions are managed in the Gist console and available in the plugin screens within WordPress.

Limitations

These are the known limits of the plugin and the Gist Answers integration, collected from the rest of this guide and from plugin engineering, so you can check fit before you connect a site.

Hosting and connectivity

  • WordPress 6.8 or later and PHP 8.0 or later are required. The plugin is tested up to WordPress 7.0 and PHP 8.5.
  • The WordPress server must reach https://cms.gist.ai, and the site’s public REST API must be reachable from the internet. At activation the plugin registers the REST posts endpoint, /wp-json/wp/v2/posts, as the website’s content feed, and Gist Answers reads content through it. The plugin never gives Gist Answers credentials, so Gist Answers sees only what an anonymous visitor sees.
  • The plugin does not follow redirects on its requests to Gist Answers and refuses private or internal addresses. An outbound proxy or firewall that redirects requests for cms.gist.ai, or resolves it to an internal address, stops the connection.
  • If the REST API is blocked for anonymous visitors, the crawl of the feed fails with a 401 or 403; permalinks sent on save still go out. Blocking the REST API for logged-in users also breaks the plugin’s own admin screens, which use the gist-answers/v1 namespace.
  • Only content an anonymous visitor can read is sent. Password-protected posts are skipped by default; a developer can opt them in with the gist_answers_should_enqueue_post_for_ingestion filter, but Gist Answers then receives only the password form and an empty, protected entry, so it cannot answer from them. Private posts, drafts and other content that isn’t publicly viewable are never sent, whatever the filters allow. The plugin does not detect content hidden by security or paywall plugins; what Gist Answers can read is what an anonymous visitor can read.
  • Visitors’ browsers must be able to load the widget script from https://cdn.gist.ai. The plugin only shows a widget whose script comes from exactly that address. Where the script is blocked, or Gist Answers supplies a script from anywhere else, the widget does not appear.
  • Sending depends on WP-Cron. Queued content, and the background refresh of widget code and widget lists, all run as WP-Cron events; loading the WordPress admin sends nothing itself. If DISABLE_WP_CRON is set, a server cron job must call wp-cron.php (WordPress VIP runs one for you). Without it, queued content is never sent.
  • Widget lookups time out after 2 seconds on the front end (3 seconds in the admin), and a page waits no more than 3 seconds in total for Gist Answers. A widget whose code has never been cached is left out if its lookup fails, and the failure is cached for 1 minute. A widget with cached code keeps showing it through a short outage; see How widgets render.
  • On WordPress VIP the plugin cannot be uploaded from the WordPress admin. It is added from the VIP Integrations Center or deployed through the wpcomvip repository. See Installation.

API key and site activation

  • One API key authenticates the whole installation. On Multisite it is stored for the network, and only a network administrator can enter or replace it.
  • The API key belongs to your Gist partner account, not to one site, and can link any website in that account. On a single site, the administrator can link any website in the account. On Multisite, a network administrator can link any site to any website in the account; a site administrator can only choose a website that lists the site’s own domain, or a production website not already linked to another site. Use a separate partner account for each organization, and don’t share one key across unrelated companies or clients.
  • When the key comes from the VIP runtime config, that config is always used, even when it is incomplete. The plugin does not fall back to another key source.
  • A key saved through the dashboard is encrypted with a key derived from the WordPress security keys and salts. Rotating the salts makes the stored key unreadable, and you must enter it again. Gist issues a new key only when a partner’s key is lost or a regeneration is requested.
  • A WordPress site is linked to an existing Gist website automatically only when one of the website’s domains matches the site’s domain and the names closely match. If only the domain matches, the activation dialog lists that website for you to choose. If the domains differ but the name matches, activating it as a new website fails with an “already exists” error. See Connecting to Gist Answers.
  • The first site activated in an installation, or anywhere in a Multisite network, must be a production site.
  • A test site’s link to its production site cannot be changed from the plugin. Email support@gist.ai.
  • A test site shares its production site’s content, settings and widgets; only the WordPress pages are separate. Editing a widget from a test site changes it on the production site.
  • Copying a production database to another environment copies the site’s Gist association with it. The copy stays linked to the production website and, with a working key, sends its own URLs there. Read the database-copy entry in Troubleshooting before syncing databases between environments.

Content ingestion

  • By default only posts (post type post, status publish) are kept in sync. Pages, custom post types and other statuses need a filter in code; there is no setting for this in WordPress.
  • Adding a post type with a filter is not retroactive. Only items saved after the filter is added are sent, and the initial crawl never includes them, because the only feed registered at activation is the REST posts endpoint. Pages and custom post types reach Gist Answers only as single URLs sent on save. Partners who want content ingested beyond the posts endpoint contact support@gist.ai.
  • Content is queued only when it is saved by a logged-in user who can edit it, or when a scheduled post goes live. Saves by the WordPress Importer run by an administrator, by REST API requests made with a user (for example an application password), and by WP-CLI with --user are queued. WP-CLI without --user, wp_insert_post() with no current user (cron jobs, scripts), direct SQL and database imports are not.
  • Changes are sent by WP-Cron after a minimum delay of 5 seconds, up to 10 posts per run (filterable up to 100). While more are waiting, the next run follows one minute later, so a large import drains at about 10 posts a minute by default. A change is never sent instantly.
  • A send that fails is retried. A post stays queued until Gist Answers accepts it. Timeouts, rate limits (429) and server errors are retried after 5 minutes, then 10, 20 and so on, doubling up to 6 hours between tries and never sooner than Gist Answers asks. After 8 attempts (about 10 to 13 hours) the post is given up on until it is saved again. Any other rejection is final at once. While the API key is rejected or can’t be confirmed, nothing is sent and the queue is retried every 5 minutes without using up attempts.
  • A post that stops being eligible before it is sent (unpublished, trashed, made private, given a password, or excluded by a filter) is dropped from the queue. Nothing is sent to remove it from Gist Answers, though: the plugin has no removal signal, so content already ingested stays there. A removal signal is planned for a later version. To have an article removed in the meantime, email support@gist.ai with its URL.
  • The plugin only starts or stops the crawl, for all of a website’s sites at once. It has no schedule and no resync; to push particular posts, save them again. Restarting a full crawl needs Gist’s operations team (support@gist.ai). Ingestion cannot be paused from the Gist console.
  • Pausing ingestion stops the crawl; it does not stop the plugin queuing and sending changes. Deactivating the plugin stops all sending but does not pause the crawl.
  • The plugin does not bypass or purge any cache. The feed URL and the permalinks it sends are anonymous URLs that a page or edge cache, including VIP’s, can serve, so Gist Answers may fetch a cached copy; purge them after a correction.
  • The plugin does not show what has been ingested. Content Usage in Reports shows which content is used in answers.

Widgets and placement

  • A widget belongs to one website in your Gist account and cannot be rendered on another.
  • Widgets created or changed in Gist can take a few minutes to appear in WordPress. The plugin refreshes each widget’s cached code in the background every 5 minutes while the widget is in use, so a change to a widget shows within a few minutes while WP-Cron is running.
  • The sidebar widget supports question widgets only. Answer widgets must be placed with a block, the shortcode or PHP.
  • The blocks cannot be edited as HTML and show a placeholder in the editor rather than a live preview.
  • Changing an account default setting changes every widget in the account that uses it, across all websites.
  • The widget script is loaded as a script module from cdn.gist.ai in the page footer. There is no consent setting and no JavaScript API to load or unload the widget, and a loaded widget cannot be unloaded without a page reload. See “Visitor privacy and consent” in Data and external services.
  • If a widget cannot be rendered, the page shows nothing where it was placed. The only signal is an error in the browser console beginning Gist Answers: No widget HTML is available.

Answer pages

  • Answer pages are detected during the save itself, when a user who can edit the page saves a published page or post that contains the answer widget. Existing content is detected the next time it is updated. Saves with no user (WP-CLI without --user, imports with no user) are never detected.
  • Answer widgets nested inside other blocks (Group, Columns and similar) and widgets rendered only from PHP templates are not detected.
  • If the request that records the page in Gist fails during that first save, it is not retried on later saves. Remove the widget, save, then add it back.
  • Create an answer page for me requires the parent of the path to exist already and never overwrites an existing page.
  • When you change an answer page in the Gist screens, WordPress creates the page only if you can publish pages. It moves or renames a page only if it is a WordPress page (not a post) that Gist created or that contains an answer widget, and you can edit it. The request must keep the site’s domain, never overwrites an existing page, and expires 30 minutes after the screen was opened; reload the screen if you see “The embed token has expired.”

Multisite

  • One Gist website per site, and one API key per network.
  • The Network Hub lists only the sites for which you are a member. The Manage and Reports screens are not available from it; open them from each site’s own Gist Answers menu.
  • Network Deactivate and the developer Danger zone tools act on every site in the network.
  • On WordPress VIP, adding Gist Answers from the Integrations Center activates it for every site on the chosen environment; the plugin’s VIP scope is network.

Admin screens and reporting

  • The Manage and Reports screens are Gist console pages embedded in WordPress and need a Gist console sign-in. To get console accounts for additional administrators, email partnerships@gist.ai for an invite.
  • Reports open from each site’s own menu. Answers and Content Usage are per website; Revenue covers the whole account and pays out once cumulative revenue reaches $1,000.

Deactivating and uninstalling

  • Deactivating the plugin stops widgets rendering: blocks output nothing and shortcodes appear as plain text. Deactivating and reactivating only clears the plugin’s scheduled WP-Cron events; it does not reset the connection or the queue.
  • Deactivating or deleting the plugin does not remove the website from your Gist Answers account or stop its crawl. Pause ingestion first, and contact support@gist.ai to remove the website.
  • Deleting the plugin keeps the encrypted API key and the other gist_answers_ options unless you clear them with the developer Danger zone first. Delete all Gist Answers database options clears options, transients and the stored key, but not the per-post records in post meta.

An answer page is the WordPress page a question widget sends visitors to. It contains an answer widget, and its URL is set in Gist as the widget’s Answer page (URL for answers to appear). It is an ordinary WordPress page: the answer widget is one block (or shortcode) in its content, so you can add your own content above, beside or below the widget, such as an introduction, related links, editorial modules or advertising, and style it with your theme like any other page. During widget setup you choose how the page is created:

  • Create an answer page for me (recommended). The plugin creates a published WordPress page at the URL you chose, with the title and slug taken from the last part of the path and a Gist Answer Widget block as its content. The parent of the path must already exist, and if a page already exists at that URL the plugin leaves it unchanged and reports that it exists. You can edit the page afterwards.
  • I’ll create the answer page myself. Create the page at that URL and add the answer widget with a block, the shortcode, or PHP.

Detection

Whenever a published page or post is saved, the plugin checks its content for answer widgets added as a block, as a shortcode, or as pasted Gist widget HTML. If Gist Answers does not already associate that page with an answer widget, the plugin sends its permalink so Gist can. Existing content is detected the next time it is updated. Two placements are not detected: answer-widget blocks nested inside other blocks (Group, Columns and similar), and widgets rendered only from PHP templates. The post types and statuses checked, and the number of posts processed per run, can be changed with the gist_answers_answer_page_types, gist_answers_answer_page_statuses and gist_answers_max_flagged_answer_widget_posts filters.

Changes requested from Gist

The embedded widget-management screens can ask the plugin to create or update an answer page, for example when you change a widget’s answer page URL. Every such request is checked against the current embed session and the user’s capability to manage that site, must keep the same domain, and will not overwrite an existing page. To change an answer page URL, see “Widgets” under Manage.

Getting started

Connecting to Gist Answers

Connecting has two parts: supplying an API key, which authenticates the whole WordPress installation with your Gist Answers account, and activating each WordPress site, which links it to a website in that account.

API key sources

The plugin looks for the API key in four places, in this order, and uses the first one it finds.

#SourceNotes
1SourceWordPress VIP runtime config: VIP_GIST_ANSWERS_CONFIG['api_token']NotesDefined by the VIP platform from what you enter in the VIP Dashboard. When this config is present it is always used, even if it is incomplete, and the other sources are ignored. See WordPress VIP runtime config.
2SourceServer environment variable: GIST_ANSWERS_API_KEYNotesSet in the web server or PHP-FPM environment. The plugin shows a notice naming the server administrator if the key is rejected.
3SourcePHP constant: GIST_ANSWERS_API_KEYNotesDefined in wp-config.php or a must-use plugin, before the plugin loads.
4SourceGist Answers dashboardNotesEntered by an administrator (a network administrator on Multisite). Stored encrypted in the WordPress database: as a network-wide option on Multisite, otherwise as a site option.

Example of supplying the key as a constant in wp-config.php:

define( 'GIST_ANSWERS_API_KEY', 'your-api-key' );

When the key comes from any source other than the dashboard, the dashboard hides its key-entry form. When it comes from the VIP runtime config, the plugin’s admin screens also show a notice that the token is managed by WordPress VIP.

Encryption and WordPress salts. A key saved through the dashboard is encrypted with a key derived from the installation’s WordPress security keys and salts. If you rotate the salts in wp-config.php, the stored key can no longer be decrypted; the dashboard will ask for the key again, so keep your onboarding email.

If Gist Answers rejects the key, the plugin tells you where to fix it: the dashboard asks for a new key when the key was entered there, and shows a notice pointing to the VIP Dashboard, the server environment, or the WordPress configuration when the key came from one of those sources.

WordPress VIP runtime config

When Gist Answers is added from the VIP Integrations Center, the platform defines the PHP constant VIP_GIST_ANSWERS_CONFIG, a plain associative array, before the plugin loads. Its contents come from the integration’s configuration form in the VIP Dashboard.

KeyTypeRequiredDescription
api_tokenTypesecretRequiredYesDescriptionThe API token for your Gist Answers partner account, from the onboarding email sent by answers@gist.ai. VIP stores it encrypted and never exposes it back through its API.
State of the configHow the plugin behaves
Valid (all required fields set)How the plugin behavesThe token from the config is used. The dashboard’s key-entry form is hidden and a notice says the token is managed by WordPress VIP.
Incomplete (setup in progress; api_token missing or empty)How the plugin behavesNo fatal error. The plugin stays disconnected, does not fall back to any other key source, and the dashboard names the missing field: “…its configuration (VIP_GIST_ANSWERS_CONFIG) is incomplete. Missing: api_token.”
Invalid (the constant is defined but is not an array)How the plugin behavesTreated as if no config were set; the other key sources are checked in order.
Not definedHow the plugin behavesThe environment variable, the PHP constant and the dashboard are checked in order.

Example valid config (mock value):

define( 'VIP_GIST_ANSWERS_CONFIG', array(
    'api_token' => 'mock-token',
) );

Example incomplete config (setup in progress; the required api_token is missing):

define( 'VIP_GIST_ANSWERS_CONFIG', array() );

Activating websites: matching, production and test sites

With a key in place, the dashboard lists each WordPress site as a card. A single-site installation lists one site; a Multisite installation lists every site in the network. Click Activate website next to a site to link it to your Gist Answers account.

  • Matching. If a website in your account lists this site’s domain (as its domain, home page URL, alias or dev site) and its name closely matches the site name, the plugin links the WordPress site to it immediately, without a dialog. If the domain matches but the name doesn’t, the dialog lists that website so you can choose it. If only the name matches, activating the site as a new website fails with an “already exists” error. On Multisite, a site administrator can only choose a website that lists the site’s domain, or a production website not already linked to another site; a network administrator can choose any website in the account.
  • Activating a new website. Otherwise a dialog offers to activate the site as a new website at the address shown. Activation sends the site’s name, tagline, domain and home URL, a Gist Answers category, a placeholder location, and the URL of its REST API posts endpoint, and starts content ingestion. See Data and external services.
  • The first site must be production. Select This is not a test website for your live site and activate it before any staging or development site, so Gist ingests the right content. You don’t have to add widgets to the production site until you are ready.
  • Every site after that can be another production site (This is not a test website) or a test site (This is a test website linked to: followed by the production website it mirrors).
The activation dialog for a second site, with the test-website option
The activation dialog for a second site, with the test-website option

Production and test websites

A test site linked to a production site uses the same content, settings and widgets in your Gist Answers account; only the WordPress pages are separate. You can link more than one test site to the same production site. Because widgets are shared, editing a widget from a test site also changes it wherever it is live on the production site. To try out changes safely, create a separate widget for testing and add it to the production site when it is ready.

You cannot currently change which production site a test site is linked to from the plugin. Check the selection before you click Submit; if you link the wrong site, email support@gist.ai.

Once a site is activated, its card shows a Set up widgets button (later View widgets), the Content ingestion toggle and the ingestion Status. See “Dashboard” under Admin menu.

Widgets

The Widgets screen, also opened from View widgets on a site’s dashboard card, has two tabs: Theme and Widgets.

Theme. Change the Website accent color, Website fonts and Icon. These are the default settings for the widgets you create.

The Theme tab
The Theme tab

Widgets. Manage your answer pages and question widgets.

The Widgets tab, with answer pages above question widgets
The Widgets tab, with answer pages above question widgets

To edit an answer page URL, click the ellipsis (⋯) on the answer page and choose Edit. In Edit answer page, change URL for answers to appear, then click Publish changes. Afterwards, make sure each question widget that should send visitors there has the new URL selected as its Answer page, confirm the WordPress page exists at that URL, and test the question-to-answer journey.

The Edit answer page dialog
The Edit answer page dialog

To add another answer page or question widget, click + Add another next to Answer pages or Question widgets.

To edit an existing widget, click its ellipsis (⋯) and choose Edit. There you can rename the widget, choose its Answer page, preview its states and adjust Custom colors and fonts; depending on the layout, you can also adjust scrolling and pinning offsets, the number of suggested-question rows, and more. Click Publish changes to apply.

The same menu has Copy shortcode and Get PHP code, two alternative ways to embed the widget in article pages besides Gutenberg blocks (see “Widget placement” under Widgets), and Duplicate, which makes a copy of the widget. Delete removes the widget.

A question widget’s ellipsis menu
A question widget’s ellipsis menu

Adding a question widget opens Add a widget, where you can Start with a default setting or Start from scratch. For full instructions on setting up and customizing a widget, see Step 4 and Step 5 of the setup guide.

The Add a widget dialog
The Add a widget dialog

Questions

Questions is where you choose which pages suggested questions appear on, and customize those questions. The panel on the left lists the Default settings (Home Page, Article Pages and Section Pages), then your Sections and Custom pages. To add a new custom section or custom article page, click Add next to Sections or Custom pages.

Home Page. Set your home page URL first. Suggested questions begin generating from your home page’s content, where all of your content aggregates. Enter the Home page URL and click Save.

Setting the home page URL
Setting the home page URL

Once your home page URL is set, you can create editorial questions, which you write yourself, rely on auto-generated questions, or use a combination of both. To add an editorial question, type it in Type a question and click Add.

The Home Page settings, with editorial questions added
The Home Page settings, with editorial questions added

Choose which kind of suggested questions to show from the Show these suggested questions dropdown: Auto-generated + Editorial, Auto-generated only, Editorial only or None, then click Publish changes. The screen recommends creating at least 8 to 20 questions for the best results.

The suggested questions dropdown
The suggested questions dropdown

Article Pages. Turn auto-generated suggested questions on or off for your article pages. Use When questions are unavailable, show: to choose what to show instead: Homepage questions or No questions. To look up or delete an article’s auto-generated questions, enter its URL under Look up / delete auto-generated questions and click Show. Click Publish changes to apply your changes.

The Article Pages settings
The Article Pages settings
The When questions are unavailable, show: dropdown
The When questions are unavailable, show: dropdown

Section Pages. Turn suggested questions on or off for your section pages, where content from articles generally aggregates: for instance, a health, art or entertainment section of a publisher’s website. As with article pages, choose what to show when questions are unavailable, and look up or delete a section page’s auto-generated questions by entering its URL and clicking Show.

The Section Pages settings
The Section Pages settings

Sections. Add a custom section when you want suggested questions for just one of your sections rather than all of them. Click Add next to Sections, enter the section’s Name and Page URL in Add New Section, and click Create.

The Add New Section form
The Add New Section form

Once the section is created, you can choose its type of suggested questions, as with the home page: let AI generate questions based on your content (auto-generated questions), or curate them yourself (editorial questions). The Section home page and Section article pages tabs let you set suggested questions for the section page and for its article pages, and a custom section’s dropdown also offers Use homepage questions.

A custom section’s suggested question options
A custom section’s suggested question options

Custom pages. Add a custom page to customize suggested questions on a single article page, for instance one article you want auto-generated or editorial questions on. Click Add next to Custom pages, enter the page’s Name and Page URL in Add New Page, and click Create.

The Add New Page form
The Add New Page form

Once the page is created, choose which arrangement of suggested questions displays there, as with the home page and custom sections. Custom sections and custom pages each have an edit (pencil) icon and a delete (trash) icon at the top right.

A custom page’s suggested question settings
A custom page’s suggested question settings

Sandbox

The sandbox is where you can see what answers look like based on different content source settings. You change your content source settings in the Website Settings tab.

The sandbox has a side-by-side comparison view, so you can see what answers look like for one group of settings against another.

The sandbox’s side-by-side comparison view
The sandbox’s side-by-side comparison view

Use the single and side-by-side view toggle to switch between the side-by-side view and a single view.

The single and side-by-side view toggle
The single and side-by-side view toggle
The side-by-side view
The side-by-side view
The single view
The single view

Choose the content sources for each side from its dropdown, such as My site only or My site + Wikipedia.

The content source options
The content source options

Click Use as site setting to change your content settings in the Website Settings tab to that specific setting. After you click it, the button becomes Current site setting, meaning this content sources setting is now live and will be reflected in the Website Settings tab.

The Use as site setting button
The Use as site setting button

Type your question in the Ask a question bar. When you ask a question, the two answers appear side by side, one for each group of settings.

Answers to the same question from two different content sources
Answers to the same question from two different content sources

Website Settings

Website Settings is a single long page. Its sections, from top to bottom:

Website name, category and homepage. Enter a name for your website under Website name, choose the Website category from the dropdown (for example, Health, Lifestyle, News or Other), and enter your Homepage URL. The website name and homepage URL are filled in by default when you connect your site through the WordPress plugin.

Website name, category and homepage
Website name, category and homepage

Dev site. If you have a dev site you’d like to test your widgets in, enter it under Dev site. This lets you test the full functionality of your widgets on the dev site, such as suggested questions showing what they would actually show in production.

The Dev site field
The Dev site field

Content sources. Choose which content source or sources your answers draw from. The choices are the same as in the sandbox. Click Save setting now to save your choice.

The Content sources setting
The Content sources setting
The content source options
The content source options

Website icon. Select the website icon you want to display. You can’t upload new icons here.

The Website icon options
The Website icon options

Publish changes. After you make changes on the Website Settings page, remember to click Publish changes at the bottom of the page.

The Publish changes button
The Publish changes button

Widgets are created and edited in Gist (from Gist Answers → Widgets in WordPress) and placed on the site with WordPress tools. Each widget has a Gist widget ID: question widgets use IDs beginning search-widget- and answer widgets IDs beginning chat-widget-. A widget belongs to a website in your Gist account, so a widget created for one website cannot be rendered on another.

Widget types

Question widgets

A question widget invites visitors to ask a question and takes them to the answer page you assign to it. It comes in three layouts; a widget’s initial settings are based on the widget theme you set, and the options available depend on the layout.

LayoutWhere it sitsOptions
Question BarWhere it sitsStretches across the page, just above or below your site navigation.OptionsChoose whether visitors get a Button, an Input box, or None (a scrolling marquee of suggested questions only); change the Prompt and Background color.
InlineWhere it sitsSits in a spot you choose on the page and scrolls with the content. By default its input box pins to the top of the page instead of scrolling off.OptionsCustomize the Header, Prompt and Background color.
FloatingWhere it sitsFloats at the bottom of the screen. By default it shrinks to a small input box once the visitor scrolls.OptionsSame options as Inline. A floating widget has two states: activated, which looks like the inline widget but floats over the page, and collapsed, a small input box.
Choosing a layout in the widget setup flow
Choosing a layout in the widget setup flow

Answer widgets

An answer widget is the answer and chat experience. It is placed on an answer page and shows the answer to the question a visitor submitted, with follow-up questions. Each answer page has one answer widget, and every question widget points at an answer page. Shared answers also open on the answer page.

Creating and managing widgets

Click Set up widgets on a site’s dashboard card to run the guided setup: sign in to the Gist console, set the widget theme (the website accent color as a hex code, a headline font and a body font, and optionally a dark-mode color), choose how many question widgets to start with, pick a layout for each, and set the answer page. Creating two widgets is recommended: one for navigation pages such as the home and section pages, and one for articles, so each can be tailored later.

After setup, you edit, add, duplicate and delete widgets and answer pages on the Widgets tab of Gist Answers → Manage → Widgets. See Manage.

Account default settings

Accounts with several websites can share settings between widgets through account-level defaults. When a widget uses Use account default settings, any change to that default is pushed to every widget in the account that uses it, across websites.

  • To apply a different default to a widget, pick it from the Use account default settings dropdown.
  • To change the default itself, click Modify these default settings; the edit propagates to every widget that shares it.
  • To give a widget settings of its own, uncheck Use account default settings and click Edit settings for just this widget.

Test and production sites share widgets. Editing a widget from a linked test site updates it everywhere it is used, including the live site. To test safely, create a new widget for the test site and add it to production when it is ready. See “Production and test websites” under Connecting to Gist Answers.

Widgets you create or change in Gist can take a few minutes to become available in WordPress. If a new widget is missing from a block’s Select a widget list, wait and reload the editor.

Widget placement

Choose one method for each placement. All four render the same widget.

MethodWidgetsBest for
BlockWidgetsQuestion and AnswerBest forPages and posts edited in the block editor. The recommended method.
ShortcodeWidgetsQuestion and AnswerBest forThe classic editor, page builders, and any field that accepts shortcodes.
Sidebar widgetWidgetsQuestion onlyBest forWidget areas (sidebars, footers) managed under Appearance → Widgets.
PHP functionWidgetsQuestion and AnswerBest forTheme templates and custom integrations, such as a question bar in the header.

For click-by-click instructions, see Step 5 of the setup guide.

Blocks

The plugin registers two blocks in a Gist Answers block category. Insert one by typing /gist in the editor or from the Block Inserter, then choose the widget under Widget Settings → Select a widget in the block sidebar.

BlockBlock nameNotes
Gist Question WidgetBlock namegist-answers/questionNotesLists the question widgets available to the current site. A widget must be selected.
Gist Answer WidgetBlock namegist-answers/answerNotesLists the answer widgets, plus Auto-detect (recommended), which renders whichever answer widget is assigned to the page the block is on.

Both blocks store a widgetId attribute, show a placeholder preview in the editor, and do not support editing as HTML.

The block’s Widget Settings panel
The block’s Widget Settings panel

Shortcode

The plugin provides one shortcode, [gist_answers_render_widget]. Copy shortcode on the Widgets tab gives you the exact shortcode for a widget.

[gist_answers_render_widget type="question" id="search-widget-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"]

[gist_answers_render_widget type="answer" id="chat-widget-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"]

[gist_answers_render_widget type="answer" target="answers"]
AttributeRequiredValue
typeRequiredYesValuequestion (aliases search, questions) or answer (aliases chat, answers).
idRequiredQuestion: yes; Answer: noValueThe Gist widget ID. For an answer widget, if no valid ID is given the plugin uses the answer widget assigned to the answer page: the page path in target, or otherwise the current page’s slug.
targetRequiredNoValueAnswer widgets only. The path of the answer page whose widget should be rendered, such as answers or help/answers. Ignored for question widgets.

Sidebar widget

Under Appearance → Widgets the plugin adds a Gist Question Widget for classic widget areas. Add it to a sidebar or footer area and choose the widget from its Widget dropdown. In block-based widget areas it appears as a Legacy Widget. Answer widgets are not offered as sidebar widgets; use a block, shortcode or PHP on the answer page instead.

PHP function

Theme templates and custom code can call gist_answers_render_widget(). Get PHP code on the Widgets tab gives you the exact call for a widget. Guard the call with function_exists() so the template still works if the plugin is deactivated.

<?php
if ( function_exists( 'gist_answers_render_widget' ) ) {
    gist_answers_render_widget(
        array(
            'type' => 'question',
            'id'   => 'search-widget-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
        )
    );
}
?>

To capture the markup instead of printing it, pass 'echo' => false:

$widget_html = gist_answers_render_widget(
    array(
        'type' => 'answer',
        'target' => 'answers',
        'echo' => false,
    )
);
ArgumentTypeValue
typeTypestringValue'question' or 'answer' (the same aliases as the shortcode).
idTypestringValueThe Gist widget ID. Required for question widgets; optional for answer widgets, which fall back to the page’s assigned widget.
targetTypestringValueAnswer widgets only: the answer page path. Defaults to the current page’s slug.
echoTypeboolValuetrue (default) prints the widget; false returns the HTML as a string.

Widgets rendered only from templates are not part of any post’s content, so they cannot be detected as answer pages. See Answer pages.

How widgets render

  • When a page containing a widget is rendered, the plugin requests the widget’s code (a script to load in the page head and the widget markup) from the Gist Answers API. A successful response is cached for five minutes; a failed lookup is cached for one minute so an outage does not slow every page view.
  • The script is enqueued and the markup printed where the widget was placed. From then on the widget communicates with Gist Answers directly from the visitor’s browser.
  • Front-end API requests time out after 2 seconds (3 seconds in the admin). Developers can change this with the gist_answers_api_timeout filter. On WordPress VIP, front-end requests go through vip_safe_wp_remote_request(), which backs off automatically after repeated failures.
  • If a widget cannot be rendered (an unknown type, an ID that does not belong to this site, or no answer widget assigned to the page), the plugin outputs nothing visible and logs a browser-console error beginning Gist Answers: No widget HTML is available, which names the type, ID and page slug it tried. If an answer widget’s ID does not match the page it is on, the plugin renders the page’s assigned widget instead and logs a console warning.
  • The rendered markup can be altered with the gist_answers_render_widget and gist_answers_widget_html filters. See Filters, actions and constants.
Admin menu

Reports

Answers

Answers has six tabs: Engagement, Questions, GA summary, GA adoption (beta), Ad performance and Prompt type report.

1

Engagement. An engagement report, with figures for Initializations, Widget views, Questions, Engagement rate and Suggested questions %.

The Engagement report
The Engagement report
2

Questions. A table of questions, with each question’s Type, Site content % and Count.

The Questions tab
The Questions tab
3

GA summary. Create charts based on the available data about your widget. Customize a chart with the settings above it: the date range, Daily, Download, Left axis and Right axis. The values you can assign to either axis are Widget views, Initializations, Answers, Valid searches, Invalid searches, Citation clicks, Citation CTR and Search engagement.

A GA summary chart
A GA summary chart
The GA summary chart settings
The GA summary chart settings
The values you can assign to an axis
The values you can assign to an axis
4

GA adoption (beta). Shows the extent to which users are using your widget or widgets, and provides more possible charts. For instance, you can break a chart down by Partners, Publications, Widget views, Searches, Engagement, Citation CTR, Partners trend, Publications trend, Widget views trend, Searches trend, Engagement trend or Citation CTR trend. Click a card above the chart to see a preset view.

The GA adoption (beta) tab
The GA adoption (beta) tab
The cards above the GA adoption chart
The cards above the GA adoption chart
5

Ad performance. A breakdown of answers by day, as a chart and as a table.

The Ad performance chart
The Ad performance chart
The Ad performance table
The Ad performance table
6

Prompt type report. A breakdown of question types per day, and how many questions of each type, in a table and a chart view. The table’s columns are Time period, Questions, Suggested questions %, Typed questions %, Follow-up questions % and Related questions %.

The Prompt type report table
The Prompt type report table

Content Usage

Content Usage shows how much your content is used and cited in answers. You can break it down by time period or by article.

1

Per time period. A breakdown by time period, as a chart and in table form.

Content usage per time period
Content usage per time period
Content usage per time period, in table form
Content usage per time period, in table form
2

Per article. A breakdown by article.

Content usage per article
Content usage per article

Used in answers is the number of times a particular article, or an article from this publisher in general, is cited in an answer.

Average attribution is the percentage of an answer that an article’s content makes up.

Citation clicks is the number of times a user clicks a citation card at the bottom of an answer page, which takes them to the article it links to.

Revenue

Revenue shows the amount of revenue your content is earning you by being referenced in answers. The payout threshold is $1,000 for all partners: you’re paid once your cumulative revenue meets or exceeds that amount.

The Revenue reports table
The Revenue reports table

Widgets and answer pages

Widgets are created and edited in Gist and placed on your site with WordPress tools. A question widget sends visitors to an answer page, where an answer widget shows the answer.

Content ingestion

Ingestion is how your published content reaches Gist Answers. It has two parts: an initial crawl that Gist Answers runs when a site is activated, and ongoing notifications that the plugin sends when eligible content changes.

The crawl and its status

Activating a site registers it as a content source in Gist Answers and starts the crawl. Gist Answers reads published content through the site’s public WordPress REST API; the plugin itself sends no post content. The Status column on the dashboard shows where the crawl is:

StatusMeaning
Ingestion queuedMeaningThe crawl is waiting to run. This does not mean your content is ready yet. Answers about content that has not been ingested begin “Looks like I don’t have the sources…”.
Ingestion active (x of y feeds)MeaningThe crawl is running on the content sources (feeds) configured for the website.
Ingestion pausedMeaningThe crawl has been stopped with the Content ingestion toggle. New content is not available for answers until it is resumed.
Error — …MeaningGist Answers could not start crawling the site; the text after the dash says why. For API does not properly support 'after' parameter or Less than 2 articles on site, see the troubleshooting entry for this error. For any other reason, email support@gist.ai with the website URL and the full text of the status.

Use the Content ingestion toggle on a site’s card to pause or resume the crawl, and Refresh ingestion status to fetch the latest status from Gist Answers.

Keeping content in sync

After the initial crawl, the plugin watches for changes to eligible content and queues it for Gist Answers:

  • By default, eligible content is published posts (post type post, status publish, any category or tag). Pages and other post types are included only if a filter adds them.
  • Content is queued when it is saved by a user who can edit it, or when WordPress publishes it on its own (for example, a scheduled post going live).
  • Queued content is sent by WP-Cron shortly afterwards, after a minimum delay of 5 seconds, in batches of up to 10 posts. It is also sent during activity in the WordPress admin. If WP-Cron is disabled on the site, queued content is sent during admin activity only.
  • Only the permalinks of the queued content are sent; Gist Answers then fetches the content through the REST API. If the Gist API cannot be reached or the key cannot be confirmed, sending is retried every five minutes.
  • Deactivating the plugin clears its scheduled sending events. Pausing ingestion from the dashboard tells Gist Answers to stop the crawl; it does not stop the plugin queuing changes.

Customizing what is ingested

Developers can change the defaults with WordPress filters. Each filter receives the current value and returns the new one.

FilterDefaultPurpose
gist_answers_ingest_post_typesDefaultarray( 'post' )PurposePost types whose changes are sent to Gist Answers.
gist_answers_ingest_post_statusesDefaultarray( 'publish' )PurposePost statuses that are eligible.
gist_answers_ingest_tax_queryDefaultarray() (all terms)PurposeA standard tax_query array (as accepted by WP_Tax_Query) that content must match. Use it to include or exclude categories, tags or custom taxonomies.
gist_answers_should_enqueue_post_for_ingestionDefaulttruePurposePer-post eligibility. Receives $should_enqueue, $post_id and $post; return false to skip a post.
gist_answers_max_posts_for_ingestionDefault10PurposeMaximum posts sent per run (1–100).
gist_answers_min_delay_for_ingestionDefault5PurposeMinimum delay in seconds between a change and its being sent (1–300).

Example: include pages, and limit ingestion to the “news” and “guides” categories.

add_filter( 'gist_answers_ingest_post_types', function ( $types ) {
    $types[] = 'page';
    return $types;
} );

add_filter( 'gist_answers_ingest_tax_query', function () {
    return array(
        array(
            'taxonomy' => 'category',
            'field'    => 'slug',
            'terms'    => array( 'news', 'guides' ),
        ),
    );
} );

Place filters in a must-use plugin or your theme’s functions.php (on VIP, in client-mu-plugins). The plugin also fires gist_answers_post_enqueued_for_ingestion and gist_answers_post_ingested actions; see Filters, actions and constants.

Timing expectations

What the plugin does at each step, and how long each step takes. The plugin-side figures are fixed; Gist Answers’ own crawling and indexing time varies with the size of the site.

EventWhat happensHow long
Site activatedWhat happensGist Answers registers the site and starts crawling the REST posts feedHow longIngestion active immediately; crawling the existing posts takes longer on large sites
Eligible post published or updatedWhat happensQueued on save by a user who can edit it; WP-Cron sends up to 10 permalinks per run after a minimum 5-second delay, with the next run one minute later while more are waiting; Gist Answers then fetches and re-indexes the postHow longPlugin: within a minute or two when WP-Cron runs normally; a large import drains at about 10 posts a minute
Send failsWhat happensA server error or a request that never completes is not retried; the post is sent again only when it is saved againHow longUntil the next save
Gist Answers unreachable or key not confirmedWhat happensNothing is sent; the queue is retriedHow longEvery 5 minutes until it succeeds
Post unpublished, trashed, deleted or made privateWhat happensNothing is sent; the content stays in Gist Answers until removed thereHow longUntil removed on request to support@gist.ai
Scheduled re-crawl of the feedWhat happensGist Answers re-reads the REST posts feed on its own schedule, independent of the pluginHow longPeriodic
Answer page saved for the first timeWhat happensThe plugin creates the answer widget in Gist during the save, so the page is recorded at once; it appears under Detected Answer Pages on the next admin page loadHow longDuring the save; listed within a minute
Widget created or edited in the Gist consoleWhat happensAppears in the block’s Select a widget list and on the Widgets tabHow longA few minutes
Widget code changedWhat happensThe plugin caches each widget’s codeHow longUp to 5 minutes; failed lookups are cached for 1 minute
Page with a widget renderedWhat happensThe plugin requests the widget’s codeHow longTimes out after 2 seconds (3 seconds in the admin); adjustable with gist_answers_api_timeout

When to treat a delay as a problem

Ingestion queued should not persist after a refresh at all; if it does, follow the steps in Troubleshooting. After publishing or correcting a post, the plugin side is done within a few minutes while WP-Cron is running, and a code of 200 in the post’s gist_answers_ingest_response confirms it; what remains is Gist Answers’ fetch and re-index, which takes longer on large sites and during a first crawl. The Status column shows the last status fetched, so click Refresh ingestion status before judging, and contact your Gist onboarding contact if an update is still missing well after a successful send.

Developer reference

Data and external services

Gist Answers depends on Gist, a third-party service operated by ProRata.ai, and cannot work without it. The connection is made only once an API key is configured. Gist’s terms of service and privacy policy are available at gist.ai.

Requests from the WordPress server

Requests go to the Gist Answers API at https://cms.gist.ai/api/cms/v1, authenticated with the installation’s API key and identified by the site’s home URL (sent in an X-CMS-Origin header). The plugin sends:

  • When the key is checked: a request that confirms the key is valid.
  • When a site is activated: the site’s name, its tagline (or its name, if it has none), its domain and home URL, a Gist Answers category, a placeholder location, and the URL of its WordPress REST API posts endpoint.
  • When eligible content is published or updated: the permalinks of that content, so Gist Answers can ingest it.
  • When an answer page is detected that Gist Answers does not yet associate with an answer widget: its permalink.
  • When ingestion is paused or resumed: the request to stop or start the crawl.
  • When the plugin’s admin screens load: requests for your account’s websites (to match them to this site), their sites, widgets, ingestion status and messages, the list of Gist Answers categories, and a short-lived ticket for each embedded Gist page.
  • When a page containing a widget is rendered: a request for the widget’s code, cached for five minutes.

No post content, comments or user data are sent from the WordPress server. Gist Answers reads published content through the site’s public REST API. The API key is never shown in the admin interface and is redacted from the plugin’s log output.

Content loaded from Gist Answers

  • The plugin’s Manage and Reports screens embed pages from https://cms.gist.ai/pages (website settings, widgets, questions, answers and reports).
  • Pages that contain a widget load the widget’s script and markup, as supplied by the Gist Answers API, in visitors’ browsers. Those widgets then communicate with Gist Answers directly; questions visitors type are sent to Gist Answers, not to your WordPress server.

Data stored in WordPress

The plugin stores the encrypted API key (when entered in the dashboard), the site’s Gist publisher association and cached site status, developer-tool settings, cached widget code (transients), and per-post ingestion and answer-page records (post meta). Nothing is stored about visitors.

This section covers what happens in a visitor’s browser, which is where a publisher’s privacy team will look. Facts about the widget come from plugin engineering; facts about collection and retention come from Gist’s Privacy Policy, which is written for all Gist services and is quoted here only where it applies to the widget.

What the widget does in the browser

A page that contains a widget loads the widget’s script as a script module from cdn.gist.ai, printed in the page footer (gist-answers-search-widget for question widgets, gist-answers-chat-widget for answer widgets), with the markup supplied by the Gist Answers API. From then on the widget communicates with Gist Answers directly: questions a visitor types, and the follow-up questions on the answer page, go to Gist Answers, not to your WordPress server. WordPress stores nothing about visitors.

The Privacy Policy covers Gist’s widgets. It lists query history (the questions typed, the answers generated and the citations the visitor clicks through on) and technical data: browser and operating system, IP address, device type and identifier, geolocation, log data and timestamps. Gist may replace the device identifier or IP address with a randomized identifier, and states that cookies and other tracking technologies may be used.

Cookies and browser storage the widget sets

This guide does not yet list the widget’s own cookies and browser storage. Gist’s Privacy Policy states that cookies and other tracking technologies may be used, so check what the widget sets in your browser’s developer tools before completing your cookie notice; browsers that block third-party cookies, including Safari, will not store cookies set on a Gist domain.

What Gist Answers keeps, and for how long

  • The questions visitors ask are listed in Reports → Answers → Questions (see Reports), so anything a visitor types, including personal information, is visible to the administrators who can open that report.
  • Retention: the Privacy Policy keeps information for as long as needed to provide the Services or for other legitimate business purposes such as disputes, security and legal obligations; it does not state a fixed period.
  • Models: Gist uses AI to provide, improve and optimize the Services and states that it does not use personal information to train AI models.
  • Deletion: visitors can request access, correction or deletion through the Consumer Choices page or by emailing info@prorata.ai; complaints go to privacy@prorata.ai.
  • Region and subprocessors: the Services are hosted in the United States, and information is processed and stored there; some employees and contractors may be outside the US. Subprocessors are described by function only (hosting, maintenance, data analysis, customer support, email delivery, infrastructure, analytics) and are bound by contract. Gist’s EU representative is Instant EU GDPR Representative Ltd. and its UK representative is GDPR Local Ltd.

The plugin has no consent setting and no JavaScript API to load or unload the widget. What works and what does not:

  • A consent management platform that blocks scripts by host can block cdn.gist.ai until consent is given, provided it can block module scripts.
  • A site can dequeue the module and load it itself after consent; test this on a staging site first, as the widget has not been verified for loading late. A loaded module cannot be unloaded without a page reload.
  • Server-side decisions per visitor are unreliable on WordPress VIP and other cached hosts, because the page is served from the edge cache. The gist_answers_widget_html filter hides the widget markup but not the script, which is enqueued first.

Which consent category to assign is a decision for your privacy team, based on the Privacy Policy and on what the widget stores.

What to disclose

Your privacy policy may need to state that questions typed into the widget, including any personal information a visitor includes, are sent to and processed by Gist Answers (ProRata.ai) to generate answers, and your cookie notice should list any cookies or storage the widget sets. Link to Gist’s own documents rather than the home page: Privacy Policy, Consumer Choices and Terms of Use. The Terms of Use say an executed agreement between Gist and the customer takes precedence over them, so check your partner agreement for data-processing terms.

FAQ, changelog and support

FAQ

Does Gist Answers replace the Gist console?

No. The plugin connects WordPress with the Gist console and API. Reporting, website configuration, widget management, the sandbox, suggested questions and other Gist features are managed in the Gist console and available in the plugin screens within WordPress.

Where do I find my API key?

In the onboarding email from answers@gist.ai, which also contains the Set password button for your console account. Check your Junk or Spam folder. If you cannot find it, contact your Gist onboarding contact. On WordPress VIP with the Integrations Center, the key is entered in the VIP Dashboard rather than in WordPress.

Can I use several widgets on one site?

Yes. The plugin lists every widget available to the site’s Gist website, and you choose which one each block, shortcode, sidebar widget or PHP call renders. Creating separate widgets for navigation pages and for articles is recommended.

Why doesn’t a widget I just created appear in WordPress?

There can be a short delay before newly created or updated widgets become available in WordPress. Allow a few minutes, then reload the relevant screen.

How do I see how many questions visitors have asked?

Open Gist Answers → Reports → Answers in WordPress. The Engagement tab shows the number of Questions, and the Questions tab lists them. On Multisite, open it from the site’s own admin menu. See Reports.

Can ingestion be limited to certain categories, tags or post types?

Yes, with the filters described under Customizing what is ingested in Content ingestion. By default only published posts are kept in sync; pages and custom post types need a filter.

Does the plugin detect answer pages automatically?

Yes, for answer widgets placed with the block, the shortcode or pasted Gist widget HTML in published pages and posts, when the page is saved. Blocks nested inside other blocks and widgets rendered only from PHP templates are not detected. See Answer pages.

What happens to my data if I deactivate or delete the plugin?

Deactivating keeps everything and stops widgets rendering (shortcodes show as plain text while the plugin is inactive). Deleting removes the plugin files and its per-post records but keeps the encrypted key and settings unless you clear them with the developer Danger zone first. Content already ingested stays in your Gist Answers account until you ask support to remove the website. See Maintenance.

Changelog

VersionChanges
1.0.15ChangesAdd instructions URL, fix handling of multiple feeds per publisher, fix publishing scheduled posts, fix other issues.

Versioning follows semantic versioning. This release requires no migration.

Support

Email support@gist.ai or your Gist onboarding contact. Include the affected website or page URL, what you were doing, and the status or error you see. For setup problems, the Troubleshooting section of the setup guide covers the most common cases.

For problems after setup, such as content missing from answers or a stale answer after a correction, see Troubleshooting.

Gist Answers is developed by ProRata.ai and licensed under the GPLv2. Plugin version 1.0.16; user guide last updated October 2026.

Getting started

Before you onboard, you will need: A partnership agreement with ProRata.ai, the developer of Gist Answers.

Enter your details and sign the click-through agreement, and within 2 business days you’ll receive your onboarding email to set up your Gist Answers account.

For the step-by-step walkthrough, use the setup guide.

What you need before you start, how to install the plugin, and how to connect your sites to Gist Answers.

Getting started

Requirements

RequirementDetails
WordPressDetails6.8 or later; tested up to 7.0. Single-site and Multisite installations are supported. On Multisite the plugin is network-activated.
PHPDetails8.0 or later; tested on 8.2 through 8.5. Token encryption uses libsodium when available, otherwise OpenSSL.
A partnership agreement with ProRata.ai, the developer of Gist AnswersDetailsEnter your details and sign the click-through agreement, and you’ll receive your onboarding email to set up your Gist Answers account within 2 business days.
Gist Answers account and API keyDetailsYour API key arrives in an onboarding email from answers@gist.ai. The same email contains a Set password link for creating your Gist console account, which you need to open the widget, settings and report screens. If you don’t have either, contact your Gist onboarding contact or support@gist.ai.
WordPress permissionsDetailsAn administrator (manage_options) can open the Gist Answers menu, activate the site and manage ingestion. Entering or changing the API key on Multisite needs a network administrator (manage_network_options), because the key is stored for the whole network. Placing a widget in a page needs permission to edit that page. Letting Gist create an answer page for you needs permission to publish pages (publish_pages), and letting it move an answer page needs permission to edit that page.
HostingDetailsAny WordPress host that allows plugins to be installed. WordPress VIP customers can add the plugin from the VIP Integrations Center or deploy it through their wpcomvip repository. See Installation.
ConnectivityDetailsThe WordPress server must be able to reach https://cms.gist.ai over HTTPS directly: the plugin does not follow redirects or connect to private or internal addresses. Gist Answers reads published content through the site’s public WordPress REST API, so the posts endpoint must be reachable from the internet. Visitors’ browsers load widget code from Gist Answers.
WP-CronDetailsRequired for sending. Queued content, and the background refresh of widget code and widget lists, run as WP-Cron events. If DISABLE_WP_CRON is set, a server cron job must call wp-cron.php (WordPress VIP runs one); otherwise queued content is never sent.

Admin menu

The Gist Answers menu is available to administrators. Before the installation is connected, it contains only the Dashboard. Once connected, the Manage and Reports groups appear; a Developer group appears only when the developer menu is enabled with a constant (see Developer menu).

The menu on a connected site
The menu on a connected site

The Manage and Reports screens are Gist console pages embedded from cms.gist.ai. The first time you open one you are asked to sign in with your Gist console credentials (the account created from the Set password link in your onboarding email). The plugin requests a short-lived ticket for each embedded page, so you never enter the API key there.

Dashboard

The Dashboard shows the connection status and, when the key is not supplied from elsewhere, the key-entry form. Each site has a card with Activate website, Set up widgets (later View widgets), the Content ingestion toggle, the ingestion Status and Refresh ingestion status. See Content ingestion.

Admin menu

Network Hub (Multisite)

On a Multisite installation, My Sites → Network Admin → Dashboard → Gist Answers opens the Network Hub, which lists the sites in the network that you are a member of, with:

  • site-title search, ascending and descending sorting, and pagination (20 sites per page by default; developers can raise this to 100 with the gist_answers_network_sites_per_page filter);
  • each site’s activation status and Activate website action;
  • each site’s ingestion status and Content ingestion toggle;
  • links to the site’s own Gist Answers dashboard and to widget setup and management.

The Manage and Reports screens are not part of the Network Hub; open them from each site’s own Gist Answers menu.

Multisite

Gist Answers is network-activated on WordPress Multisite (its scope in the VIP manifest is network). The key points:

  • One API key for the network. The key is stored as a network-wide option and can be entered or replaced only by a network administrator (manage_network_options). Site administrators who need a key changed are told to contact the network administrator.
  • One Gist website per site. Each site keeps its own association with a website in your Gist account, its own widgets and answer pages, and its own ingestion status and scheduled events. A site administrator can activate their own site; the Network Hub lets network administrators activate any site.
  • Activate production first. The first site activated anywhere in the network must be a live site. Later sites can be production sites or test sites linked to a production site. See “Activating websites” under Connecting to Gist Answers.
  • Where things live. The Network Hub in Network Admin lists and controls all sites; the Manage and Reports screens open from each site’s own Gist Answers menu.
  • Deactivation and cleanup affect every site. Network Deactivate clears the scheduled ingestion events on every site, and the developer Danger zone tools act on all sites in the network.

On WordPress VIP, adding Gist Answers from the Integrations Center activates it for every site on the chosen environment.

Developer reference

Everything in this section is optional. The plugin works without any custom code.

Developer reference

Developer menu

An optional Developer → Tools & Options screen is shown when this constant is defined in wp-config.php (on VIP, in vip-config/vip-config.php):

define( 'GIST_ANSWERS_SHOW_DEVELOPER_MENU', true );

Enable it only in development, QA or troubleshooting environments. The screen offers:

  • Log API responses, Log API backtraces and Count API requests: diagnostics written to the server’s PHP error log, with credentials redacted; the request count is printed in the page footer.
  • Simulate API server error and Simulate API token expiration: make the plugin behave as if Gist Answers were down or had rejected the key, for testing notices and recovery.
  • Detected Answer Pages: the pages and posts the plugin has found answer widgets in, and where in their content (block, shortcode or pasted HTML).
  • Danger zone: Delete the API token from the database, Move pages & posts containing Gist widgets to the Trash, Delete Gist widgets from sidebars, Delete all Gist Answers database options, and Delete the Gist Answers plugin. These act on every site in a Multisite network and cannot be undone.

Updating, deactivating and uninstalling

Updating

  • Standard WordPress: upload the new ZIP from Plugins → Add Plugin → Upload Plugin and choose Replace current with uploaded, or replace the gist-answers folder in wp-content/plugins/.
  • VIP Integrations Center: VIP supplies updates; nothing to deploy.
  • VIP manual install: replace the folder in your wpcomvip repository and merge.

Settings, the API key and site associations are kept across updates. If the admin screens still look like the old version after an update, your browser has cached the plugin’s assets: do a hard refresh (Shift+Command+R on a Mac, Ctrl+Shift+R on Windows).

Deactivating

  • Single site: go to Plugins and click Deactivate under Gist Answers.
  • Multisite: go to My Sites → Network Admin → Plugins and click Network Deactivate under Gist Answers.
  • VIP, added from the Integrations Center: in the VIP Dashboard open your application, select Integrations, choose the environment, open the ellipsis (⋯) menu next to Configure for Gist Answers, select Remove Integration and confirm with Remove. On a multisite network this removes it from every site on that environment.
  • VIP, activated in code: Network Deactivate is not shown. Remove the wpcom_vip_load_plugin( 'gist-answers' ); line from client-mu-plugins/plugin-loader.php and deploy the change.
Network Deactivate on a Multisite network
Network Deactivate on a Multisite network

Deactivating clears the plugin’s scheduled sending events on every site, and widgets stop rendering: blocks output nothing, and shortcodes appear as plain text until the plugin is reactivated or they are removed. The API key, site associations and other settings are kept, so reactivating restores the connection. The website stays in your Gist Answers account; if you want its crawl stopped, pause ingestion from the dashboard before deactivating.

Uninstalling

Deleting the plugin from the Plugins screen removes its files, its scheduled events and its per-post ingestion records. The encrypted API key and the other gist_answers_ options are left in place so that reinstalling reconnects without re-entering the key. To remove them as well, enable the developer menu first and use the Danger zone options (Delete the API token from the database and Delete all Gist Answers database options), optionally trashing the pages and sidebar widgets that contain Gist widgets, before deleting the plugin. To remove the website from your Gist Answers account, contact support@gist.ai.