PAYLOAD CMS

Connect Payload with mr.timmy.

Install the small Payload plugin, create a connector key and add the URL plus key in timmy.

For developers

Payload is code-first. Install the connector as an npm package, enable it in the Payload config, deploy, then create a key in the Payload admin.

Title, body, SEO fields, featured image, inline images, categories and tags are mapped. If your collection uses different field names, only the snippet mapping needs to change.

For agents: inspect the Payload collection first, then adjust the field names in the snippet. The timmy connection itself only needs an API URL and API key.

Back to integrations

PAYLOAD CMS

1. Install package

pnpm add @mrtimmy/payload-connector

PAYLOAD CMS

2. Enable plugin

import { buildConfig } from "payload"
import { mrTimmyPayloadConnector } from "@mrtimmy/payload-connector"

export default buildConfig({
  plugins: [
    mrTimmyPayloadConnector({
      postsCollection: "posts",
      media: {
        collection: "media",
      },
      fields: {
        title: "title",
        content: "content",
        excerpt: "excerpt",
        slug: "slug",
        metaTitle: "meta.title",
        metaDescription: "meta.description",
        focusKeyword: "focusKeyword",
        featuredImageUrl: "featuredImage",
        categories: "categories",
        tags: "tags",
      },
      taxonomies: {
        categories: {
          collection: "categories",
          matchFields: ["slug", "title"],
        },
        tags: {
          collection: "tags",
          matchFields: ["slug", "title"],
        },
      },
    }),
  ],
})

For Payload in Next.js, also add it to next.config.js as an external server package.

const nextConfig = {
  serverExternalPackages: ["@mrtimmy/payload-connector"],
}

export default nextConfig

PAYLOAD CMS

3. Check mapping

timmy sends these values. If your Payload fields use different names, only the paths under fields need to change.

timmy sends

Title
title
Post body
content
Excerpt
excerpt
SEO title
metaTitle
SEO description
metaDescription
URL slug
slug
Focus keyword
focusKeyword
Featured image
featuredImage
Inline images
Markdown images in content
Categories and tags
categories, tags

Payload expects

title
Text field for the post title
content
Rich text or text field for the main body
slug
URL field for the blog path
meta.title
SEO title or mapped SEO field
meta.description
SEO description or mapped SEO field
focusKeyword
Focus keyword, if the site stores one
featuredImage
Upload field for the media collection
categories
optional: relation or field for categories
tags
optional: relation or field for tags

PAYLOAD CMS

4. Add it in timmy

In the Payload admin under mr.timmy → Connector Keys create a key.

API URL:
https://example.com/api/mrtimmy/create-post
API key:
timmy_xxx

PAYLOAD CMS

Common errors

  • 401: The API key is wrong or disabled.
  • 404: The plugin is not installed, not deployed or the path is wrong.
  • 500: Payload server error. The response names the failing step: rich text conversion, taxonomy mapping, media upload or Payload create.