Gist Answers for WordPress

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.

wpcom_vip_load_plugin( 'gist-answers' );

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.

API key sources

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

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.

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.

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 with the same domain already exists in your account, the plugin links the WordPress site to it immediately, without a dialog. The domain in WordPress and the domain saved in Gist must match exactly; if only the name matches, you will see an “already exists” error.
• 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).

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.

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.

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:

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.

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 the actions reference.

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.

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.

Afterwards the Widgets tab (via View widgets on the dashboard, or Gist Answers → Widgets) lists your question widgets and answer pages. A widget’s ellipsis (⋯) menu offers:

• Edit: 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.
• Copy shortcode and Get PHP code: the exact snippets for the shortcode and PHP placement methods.
• Add another creates more widgets.

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.

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.

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.

Block	Block name	Notes
Gist Question Widget	gist-answers/question	Lists the question widgets available to the current site. A widget must be selected.
Gist Answer Widget	gist-answers/answer	Lists 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.

[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"]

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

$widget_html = gist_answers_render_widget(
	array(
		'type' => 'answer',
		'target' => 'answers',
		'echo' => false,
	)
);

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 the filters reference.

Filters

Actions

Constants and functions

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_*.

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

• 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.

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.