Typefully Social Media Management Skill

Overview

This skill enables Claude to interact with the Typefully API v2 for professional social media management. Typefully is a platform for drafting, scheduling, and analyzing social media content across multiple accounts and platforms.

Supported Platforms:

• X (Twitter) - Tweets and threads
• LinkedIn - Professional posts
• Threads - Meta's text-based platform
• Bluesky - Decentralized social network
• Mastodon - Federated social platform

Key Capabilities:

• Create drafts and scheduled posts
• Multi-platform publishing from a single draft
• Cross-post content to multiple accounts with unique adaptations
• Retrieve analytics and engagement data
• Manage multiple social media accounts through a unified interface
• Safety-first approach with draft-only mode by default

When to Use This Skill

Use this skill when:

• Creating posts for X, LinkedIn, Threads, or Bluesky
• Scheduling social media content for future publication
• Cross-posting announcements to multiple accounts
• Publishing the same content to multiple platforms simultaneously
• Retrieving social media analytics and performance data
• Managing social media workflows programmatically

Example triggers:

• "Create a Twitter thread about [topic] for my personal account"
• "Post this announcement to both X and LinkedIn"
• "Schedule this post for tomorrow at 2pm"
• "Cross-post this to my company and personal accounts with appropriate adaptations"
• "Show me last week's analytics"

Setup and Configuration

Initial Setup

1. Obtain Typefully API Keys:

   • Log into Typefully dashboard (https://typefully.com)
   • Navigate to Settings > Integrations
   • Generate an API key for each social media account
   • Note: API keys inherit permissions from your user account

2. Configure the Skill:

   • Create a .env file in the skill directory
   • Add API keys using the format: TYPEFULLY_API_KEY_<ACCOUNT_NAME>=your_key_here
   • Create a config.json file for global settings

3. Example Configuration:

.env:

TYPEFULLY_API_KEY_PERSONAL=your_personal_account_key
TYPEFULLY_API_KEY_COMPANY=your_company_account_key
TYPEFULLY_API_KEY_PROJECT=your_project_account_key

config.json:

{
  "scheduling_enabled": false,
  "default_platforms": ["x"],
  "default_share": true
}

Safety Settings

Draft-Only Mode (Default):

• scheduling_enabled: false creates drafts without auto-scheduling
• Allows human review before publication
• Recommended until confidence in content quality is established

Enable Scheduling:

• Set scheduling_enabled: true in config.json
• Only enable after validating draft quality
• Requires PUBLISH permission on API key

Core Workflows

Workflow 1: Create Draft for Single Account

Use Case: Draft a post for review before publishing

Process:

1. Use scripts/typefully_client.py to interact with the API
2. Load account configuration from .env
3. Create draft using TypefullyManager
4. Review draft in Typefully dashboard
5. Manually schedule or publish from dashboard

Example:

from typefully_client import TypefullyManager

manager = TypefullyManager()

# Create draft for review (X only)
result = manager.create_draft(
    account="personal",
    content="Your tweet content here.\n\n\n\nSecond tweet in thread.",
    platforms=["x"],
    schedule=False
)
print(f"Edit draft: {result['edit_url']}")

Command-line usage:

python scripts/typefully_client.py create-draft \
    --account personal \
    --content "Your tweet content" \
    --platforms x

Response:

{
  "id": "draft_abc123",
  "status": "draft",
  "edit_url": "https://typefully.com/?d=draft_abc123",
  "share_url": "https://typefully.com/share/abc123",
  "scheduled_date": null
}

Workflow 2: Multi-Platform Publishing

Use Case: Post the same announcement to X and LinkedIn

Example:

manager = TypefullyManager()

result = manager.create_draft(
    account="company",
    content="Major product update announcement.",
    platforms=["x", "linkedin"],
    schedule=True,
    schedule_date="next-free-slot"
)

Command-line usage:

python scripts/typefully_client.py create-draft \
    --account company \
    --content "Major product update" \
    --platforms x linkedin \
    --schedule

Notes:

• The same content is posted to all specified platforms
• Platform-specific formatting is handled by Typefully
• LinkedIn posts work best with longer, more professional content

Workflow 3: Schedule Post (When Enabled)

Use Case: Schedule content for future publication

Prerequisites:

• scheduling_enabled: true in config.json
• API key has PUBLISH permission

Process:

manager = TypefullyManager()

result = manager.create_draft(
    account="company",
    content="Scheduled announcement content",
    platforms=["x"],
    schedule=True,
    schedule_date="2024-12-20T14:30:00Z"  # ISO format or "next-free-slot"
)

Scheduling Options:

• "now" - Publish immediately
• "next-free-slot" - Use Typefully's optimal timing
• ISO-8601 datetime - Specific time (e.g., "2024-12-20T14:30:00Z")

Workflow 4: Cross-Post to Multiple Accounts

Use Case: Publish the same announcement across multiple accounts with unique content for each

Process:

1. Prepare content variations for each account
2. Create a JSON file mapping accounts to content
3. Use the cross-post functionality

Example content map (content.json):

{
  "personal": "Excited to share: we just launched our new feature! Check it out:",
  "company": "Introducing our latest product update with enhanced capabilities:"
}

Execute cross-post:

manager = TypefullyManager()

content_map = {
    "personal": "Casual, personal tone announcement",
    "company": "Professional, formal announcement"
}

results = manager.cross_post(
    accounts=["personal", "company"],
    content_map=content_map,
    platforms=["x"],
    schedule=False
)

for account, result in results.items():
    print(f"{account}: {result.get('edit_url', result.get('error'))}")

Command-line usage:

python scripts/typefully_client.py cross-post \
    --accounts personal company \
    --content-json content.json \
    --platforms x

Workflow 5: Retrieve Analytics

Use Case: Get performance data for recently published content

Process:

manager = TypefullyManager()

analytics = manager.get_analytics(account="personal", limit=20)

print(f"Published: {analytics['stats']['published_count']}")
print(f"Scheduled: {analytics['stats']['scheduled_count']}")

Command-line usage:

python scripts/typefully_client.py get-analytics \
    --account personal \
    --limit 20

Workflow 6: List Drafts by Status

Use Case: View all scheduled or draft posts

Draft Status Values:

• draft - Saved but not scheduled
• scheduled - Queued for future publication
• publishing - Currently being posted
• published - Successfully posted
• error - Publication failed

Command-line:

# List all scheduled drafts
python scripts/typefully_client.py get-drafts \
    --account personal \
    --status scheduled

# List all drafts (any status)
python scripts/typefully_client.py get-drafts \
    --account personal \
    --limit 50

Workflow 7: View Social Sets (Connected Platforms)

Use Case: See which platforms are connected for an account

Command-line:

python scripts/typefully_client.py list-social-sets --account personal

Response shows connected platforms:

Social sets for personal:
  - social_set_abc123: My Account
    x: @myhandle (connected)
    linkedin: (connected)
    threads: (not connected)

Thread Formatting

Creating Multi-Tweet Threads

Use 4 consecutive newlines (\n\n\n\n) to separate tweets in a thread:

content = """First tweet in the thread



Second tweet with more details



Third tweet wrapping up"""

manager.create_draft(account="personal", content=content, platforms=["x"])

The Python client automatically converts this to the API's posts array format.

Integration with Other Skills

This skill can be integrated with other content creation and brand management workflows:

Content Creation Pipeline:

1. Generate content using content creation agents
2. Validate with brand voice guidelines
3. Create Typefully draft for review
4. Manually approve and schedule (or auto-schedule if enabled)

Multi-Brand Management:

1. Adapt content for different brand voices
2. Use cross-post with unique content per account
3. Maintain consistent messaging with appropriate tone

Analytics and Reporting:

1. Retrieve performance data via analytics
2. Generate reports on engagement
3. Inform future content strategy

API Reference

For detailed API documentation, load references/typefully_api.md which includes:

• Complete v2 endpoint specifications
• Request/response formats with examples
• Multi-platform content structure
• Webhook events and verification
• Error handling guidance
• Migration notes from v1

Load reference when:

• Debugging API issues
• Implementing custom functionality
• Understanding response structures
• Setting up webhooks

Error Handling

The client provides clear, user-friendly error messages:

• 401 Unauthorized: "Invalid API key. Check your configuration and regenerate if needed."
• 403 Forbidden: "API key doesn't have permission for this operation."
• 429 Rate Limit: "Rate limit exceeded. Please wait before trying again."
• 400 Bad Request: Detailed error message with specific parameter issues

Common issues and solutions:

Account Not Found:

• Verify .env file contains TYPEFULLY_API_KEY_<ACCOUNT>=key
• Check account name matches exactly (case-insensitive in manager)
• Run list-accounts to see configured accounts

Scheduling Disabled Warning:

• Expected when scheduling_enabled: false
• Draft created for manual review
• Enable in config.json only when ready

No Social Sets Available:

• Connect at least one platform in Typefully dashboard
• Verify API key is for correct Typefully account

Platform Not Connected:

• The specified platform isn't connected in Typefully
• Only enabled platforms will receive posts

Best Practices

1. Start with Draft Mode:

   • Keep scheduling_enabled: false initially
   • Review drafts in Typefully dashboard
   • Enable scheduling only after validating quality

2. Multiple Accounts:

   • Use descriptive account names in .env
   • Maintain separate API keys per account
   • Organize content_map clearly for cross-posting

3. Multi-Platform Strategy:

   • X for quick updates and threads
   • LinkedIn for professional announcements
   • Test platform connections before important posts

4. Content Quality:

   • Validate content before creating drafts
   • Use brand voice guidelines for multi-account scenarios
   • Test with personal accounts before company accounts

5. Error Resilience:

   • Handle API errors gracefully
   • Fall back to draft mode on scheduling failures
   • Check rate limits when batch posting

CLI Commands Reference

# Create draft
python scripts/typefully_client.py create-draft \
    --account ACCOUNT \
    --content "Content" \
    --platforms x linkedin \
    --schedule \
    --schedule-date "next-free-slot" \
    --title "Draft Title" \
    --tags tag1 tag2

# Cross-post to multiple accounts
python scripts/typefully_client.py cross-post \
    --accounts account1 account2 \
    --content-json content.json \
    --platforms x \
    --schedule

# List drafts
python scripts/typefully_client.py get-drafts \
    --account ACCOUNT \
    --status scheduled \
    --limit 20

# Get analytics
python scripts/typefully_client.py get-analytics \
    --account ACCOUNT \
    --limit 20

# List social sets (connected platforms)
python scripts/typefully_client.py list-social-sets --account ACCOUNT

# List configured accounts
python scripts/typefully_client.py list-accounts

# Get user info
python scripts/typefully_client.py get-me --account ACCOUNT

Troubleshooting

Problem: "Account 'xyz' not found"

• Solution: Check .env file, verify account name matches configuration

Problem: Scheduling doesn't work despite schedule=True

• Solution: Verify scheduling_enabled: true in config.json

Problem: API returns 401 Unauthorized

• Solution: Regenerate API key in Typefully dashboard, update .env

Problem: Cross-post fails for some accounts

• Solution: Check each account's API key separately, ensure all are valid

Problem: Platform not receiving posts

• Solution: Verify platform is connected in Typefully social set

Problem: "No social sets available"

• Solution: Connect at least one platform in Typefully dashboard

For additional support, consult the official Typefully API documentation: https://typefully.com/docs/api