WordPress Plugin Guide

Install and configure the HQ Connector plugin on your WordPress site.

Installation

Download the hq-connector plugin from the plugins page
In WordPress admin, go to Plugins → Add New → Upload Plugin
Upload the ZIP file and click Install Now
Click Activate Plugin

Configuration

Go to Settings → HQ Connector
Enter your Hub URL (e.g., https://hub.your-agency.com)
Enter the API Token generated by the Hub
Click Save Settings

Creating Tokens

On the Hub side, create a token for this WordPress site:

php artisan connector:token my-hub --name=client-site --scopes=posts:write,posts:media

Copy the plaintext token — it's shown only once. Paste it into the WordPress plugin settings.

How It Works

The plugin registers REST API routes under /api/connector/ that mirror the Connector Protocol:

Endpoint	WordPress Function
`POST /posts`	`wp_insert_post()`
`PATCH /posts/{id}`	`wp_update_post()`
`DELETE /posts/{id}`	`wp_delete_post()`
`POST /media`	`wp_handle_upload()`
`POST /posts/{id}/media`	`wp_insert_attachment()`

Post Meta Storage

SEO metadata is stored in post meta with _hq_ prefix:

_hq_meta_title — SEO title
_hq_meta_description — Meta description
_hq_schema_markup — JSON-LD structured data
_hq_featured_image_url — Featured image URL from the Hub

Idempotency

The plugin maintains a hq_connector_post_mappings table that maps hub_post_id → WordPress post ID. Pushing the same hub_post_id twice updates the existing post instead of creating a duplicate.

Troubleshooting

Connection fails

Verify the Hub URL is correct and accessible from your WordPress server
Check that the token hasn't been revoked
Ensure your server allows outbound HTTP requests

Posts not appearing

Check the Hub dashboard for sync errors
Verify the token has posts:write scope
Check WordPress debug log for errors