Data Machine Socials

Social media publishing extension for Data Machine. Enables automated publishing to Twitter/X, Facebook Pages, Bluesky, Mastodon, Threads, Pinterest, Tumblr, and TikTok.

Requirements

• WordPress 6.9+
• PHP 8.2+
• Data Machine core plugin (required)

Installation

1. Install and activate the Data Machine core plugin
2. Install this plugin in your WordPress plugins directory
3. Activate Data Machine Socials
4. Configure authentication for each platform in Data Machine settings

Supported Platforms

Configuration

Each platform requires authentication setup:

1. Go to Data Machine → Settings → Authentication
2. Select the platform you want to configure
3. Follow the OAuth flow or enter credentials
4. Save and verify connection

Platform-Specific Setup

Twitter/X:

• Requires Twitter Developer account
• Create an app at developer.twitter.com
• Enter API Key and API Secret in settings
• Complete OAuth authorization

Facebook:

• Requires Facebook App with Pages permissions
• Needs pages_manage_posts, pages_manage_engagement scopes
• Authorize your Facebook account
• Select which Page to publish to

Bluesky:

• Generate an App Password in Bluesky settings
• Enter your handle and app password
• No OAuth flow required

Threads:

• Requires Meta app registration
• OAuth 2.0 authentication
• threads_basic and threads_content_publish scopes

Pinterest:

• Requires Pinterest Developer account
• Generate an access token
• Configure default board or use category mapping

Tumblr:

• Register an app at www.tumblr.com/oauth/apps
• Configure its OAuth Consumer Key and OAuth Consumer Secret
• Complete OAuth 2.0 with the basic write offline_access scopes
• Set the target blog identifier in the Tumblr publish-handler settings

Usage in Pipelines

Once authenticated, social handlers appear in the Data Machine Pipeline Builder:

1. Create or edit a Pipeline
2. Add a "Publish" step
3. Select the social platform handler
4. Configure handler settings:
   • Include Images: Enable/disable image uploads
   • Link Handling: How to handle source URLs (append, reply, comment, none)
5. Save and run your flow

AI Tool Integration

Social handlers register AI tools that can be used in Data Machine Chat:

• twitter_publish - Post to Twitter with media support
• facebook_publish - Post to Facebook Pages
• bluesky_publish - Post to Bluesky
• threads_publish - Post to Threads
• pinterest_publish - Create Pinterest pins
• tumblr_publish - Create Tumblr NPF text posts

Architecture

This plugin follows the Data Machine extension pattern:

• Namespace: DataMachineSocials\Handlers\{Platform}
• Registration: Handlers self-register via HandlerRegistrationTrait
• Discovery: Core HandlerAbilities discovers handlers via WordPress filters
• Auth: Core AuthAbilities manages OAuth flows and token storage

Handler API

Each handler registers itself via HandlerRegistrationTrait::registerHandler() with a meta config array (the trailing array(...) argument). The shape exposed to clients via GET /datamachine/v1/socials/platforms is:

array(
    'charLimit'          => 280,                 // optional int
    'maxImages'          => 4,                   // optional int
    'aspectRatios'       => array( 'any' ),      // optional string[]
    'defaultAspectRatio' => 'any',               // optional string
    'supportsCarousel'   => false,               // optional bool
    'supportsVideo'      => true,                // optional bool
    'composer'           => array(               // required publish composition contract
        'crossPostCompatible' => true,
        'mediaKinds'           => array( 'image', 'carousel' ),
        // Specialized composers also declare an `ability` name.
    ),
    'capabilities'       => array(               // optional, canonicalised server-side
        array( 'slug' => 'publish', 'label' => 'Publish' ),
    ),
    'preview'            => array(               // optional — see "Preview shape" below
        'aspectRatio'     => '16:9',
        'captionPosition' => 'above',
        'previewSurface'  => 'feed',
    ),
)

The platform endpoint normalizes composer into a transport-ready contract with crossPostCompatible, mediaKinds, target, inputSchema, and mediaRequirements. Generic targets point to datamachine/v1/socials/post. Specialized targets point to their WordPress Ability and expose that ability's input schema, so consumers can preserve requirements such as TikTok privacy controls and YouTube title/video upload input without platform-name branches.

Preview shape

The preview field declares how clients should render a post preview for the platform. It exists so consumers (e.g. the Studio publish pane) can render platform-canonical previews without any per-platform branching — the client renders whatever shape the server declares.

Per-platform defaults declared in this plugin:

Backwards compatibility. preview is optional. Handlers that don't declare it (or older DM-Socials installs running against newer clients) get a generic feed-shaped default applied server-side:

array(
    'aspectRatio'     => 'native',
    'captionPosition' => 'above',
    'previewSurface'  => 'feed',
)

The field is always present on the response — clients never have to default it.

File Structure

data-machine-socials/
├── data-machine-socials.php          # Plugin entry point
├── composer.json                      # Dependencies (twitteroauth)
├── inc/
│   └── Handlers/
│       ├── Twitter/
│       │   ├── Twitter.php           # Handler implementation
│       │   ├── TwitterAuth.php       # OAuth 1.0a auth
│       │   └── TwitterSettings.php   # Handler settings
│       ├── Facebook/
│       │   ├── Facebook.php
│       │   ├── FacebookAuth.php      # OAuth 2.0 auth
│       │   └── FacebookSettings.php
│       ├── Bluesky/
│       │   ├── Bluesky.php
│       │   └── BlueskyAuth.php       # App password auth
│       ├── Threads/
│       │   ├── Threads.php
│       │   ├── ThreadsAuth.php       # OAuth 2.0 auth
│       │   └── ThreadsSettings.php
│       └── Pinterest/
│           ├── Pinterest.php
│           ├── PinterestAuth.php     # Bearer token auth
│           └── PinterestSettings.php
└── docs/
    └── handlers/
        ├── twitter.md
        ├── facebook.md
        ├── bluesky.md
        ├── threads.md
        └── pinterest.md

Dependencies

• abraham/twitteroauth - Twitter OAuth 1.0a client
• Data Machine core plugin - Provides base classes and abilities

Development

Setup

cd data-machine-socials
composer install

Coding Standards

This plugin follows WordPress coding standards and the Data Machine style guide:

• PSR-4 autoloading
• WordPress 6.9+ compatibility
• PHP 8.2+ features
• Proper namespacing and abstraction

License

GPL v2 or later - See LICENSE

Support

• Issues: GitHub Issues
• Documentation: Data Machine Docs
• Author: Chris Huber (chubes.net)