Connect WordPress

Connect a WordPress site to SerpPal with an application password, so you can publish and schedule posts with categories, tags and a featured image.

SerpPal publishes to WordPress through its built-in REST API. You sign in with an application password: a separate password made only for apps like SerpPal. You can revoke it at any time without changing your real login password.

This works with self-hosted WordPress (5.6 or newer) and with WordPress.com sites on a plan that allows plugins.

#Before you start

• Your site must use HTTPS. WordPress only offers application passwords on sites served over https://.
• Use an account that can write posts. The WordPress user must be an Author, Editor or Administrator. A Contributor or Subscriber can't publish.
• The REST API must be reachable. Most sites have it on. Some security plugins or hosts turn off application passwords or the REST API; see the troubleshooting part below.

#Step 1: Make an application password in WordPress

1. Sign in to your WordPress admin (usually https://yoursite.com/wp-admin).
2. Go to Users, then Profile. To make one for a different user, go to Users, All Users, then click Edit under that user.
3. Scroll down to Application Passwords.
4. Type a name you will recognize, for example SerpPal, and click the button to add it (Add New Application Password or Add Application Password, depending on your WordPress version).
5. WordPress shows the new password once, in groups of four characters, like abcd EFGH 1234 ijkl MNOP 5678. Copy it now. You can't see it again later.

If you don't see an Application Passwords section, your site isn't on HTTPS, or a plugin or your host has turned the feature off.

#Step 2: Connect it in SerpPal

1. Open your project and click Project settings. Under Publishing, click Connect a site.
2. Choose WordPress.
3. Fill in the three fields:

4. Click Connect. SerpPal signs in, checks that the user can write posts, and saves the site under your WordPress site's name.

#What SerpPal sends to WordPress

• Title, content, excerpt and slug. The article's first H1 is left out, because WordPress shows the post title itself.
• Status: Live post publishes it; Draft to review saves it as a draft in Posts.
• Tags and categories: SerpPal looks up each name and uses the existing tag or category. If one doesn't exist, it creates it. If the user isn't allowed to create terms, that name is skipped.
• Featured image: uploaded to your Media Library and set as the post's featured image, with its alt text.
• Images and videos in the article: uploaded to your Media Library, then placed in the post. Image alt text is saved on the media item too.

When you publish the same article to the same site again, SerpPal updates the existing post. If that post was deleted in WordPress, a new one is made.

#Changing or removing the connection

• To use a new application password, click the pencil next to the site, paste the new password and click Save and test.
• To stop SerpPal from reaching your site, click Disconnect in SerpPal, and revoke the application password in WordPress under Users, Profile, Application Passwords.

#Troubleshooting

"WordPress: ... (check the key or password)" WordPress refused the sign-in (HTTP 401 or 403). Check the user name, make a fresh application password and paste it again. If it still fails:

• A security plugin (for example Wordfence, iThemes or All In One WP Security) may block the REST API or application passwords. Allow REST API access for logged-in users, or for this user.
• Some hosts strip the Authorization header. Ask your host to pass it through to PHP, or try another host setting for "HTTP authentication".
• A firewall such as Cloudflare may block requests from servers. Allow requests to /wp-json/.

"WordPress: this user cannot write posts. Use an Author, Editor or Administrator account." Change the user's role in WordPress, or connect with another user.

"WordPress could not be reached" or "did not answer in time" Check the site address, and that the site is online. A wrong address (for example http:// on a site that redirects in an odd way) can also cause this.

"That address is not reachable from the internet" SerpPal can only reach public sites. A site on localhost, a local network or behind a VPN can't be connected.

Publishing fails while uploading an image or video. SerpPal uploads every file before it creates the post, so a refused upload stops the whole post. Common causes: the user isn't allowed to upload files, or the file is bigger than your host's upload limit (often 2 to 64 MB for videos). Use a smaller file, raise the limit with your host, or use a YouTube or Vimeo link for videos.

The featured image doesn't show on the site. Some themes don't show featured images on single posts. Check the post in WordPress: if the featured image is set there, it's a theme setting.

More fixes are in Publishing troubleshooting.