Use Cases

Real-world scenarios and examples for using the Boring API.

1. Social Media Agency

Scenario

You manage social media for multiple clients. Each client has Facebook Pages, Instagram accounts, and Threads accounts.

Solution

import os
from boring_api import BoringAPI

# Client configuration
CLIENTS = {
    "client_a": {
        "facebook": os.environ["CLIENT_A_FB_ID"],
        "instagram": os.environ["CLIENT_A_IG_ID"],
        "threads": os.environ["CLIENT_A_THREADS_ID"]
    },
    "client_b": {
        "facebook": os.environ["CLIENT_B_FB_ID"],
        "instagram": os.environ["CLIENT_B_IG_ID"],
        "threads": os.environ["CLIENT_B_THREADS_ID"]
    }
}

def post_for_client(client_name, content):
    """Post content across all client's platforms"""
    client = CLIENTS[client_name]
    results = {}

    for platform, account_id in client.items():
        result = publish_post(
            account_id=account_id,
            platform=platform,
            text=content["text"],
            media_urls=content.get("media_urls", [])
        )
        results[platform] = result

    return results

# Usage
content = {
    "text": "New product announcement! 🎉",
    "media_urls": ["https://cdn.example.com/product.jpg"]
}

results = post_for_client("client_a", content)

Benefits

• Centralized management
• Consistent posting across platforms
• Easy client onboarding/offboarding
• Audit trail in publishing history

2. Content Creator Cross-Posting

Scenario

You create content (photos, videos) and want to share it across all your social accounts simultaneously.

Solution

def cross_post_content(content, accounts):
    """
    Post content to all platforms with platform-specific adaptations
    """
    results = {}

    # Platform-specific adaptations
    adaptations = {
        "facebook": {
            "text": content["text"],
            "media_urls": content["media_urls"]
        },
        "instagram": {
            "text": f"{content['text']}\n\n{content.get('hashtags', '')}",
            "media_urls": content["media_urls"]  # Required for IG
        },
        "threads": {
            "text": f"{content['text']} {content.get('cta', '')}",
            "media_urls": content["media_urls"][:20]  # Up to 20
        }
    }

    for platform, account_id in accounts.items():
        adapted = adaptations[platform]

        result = publish_post(
            account_id=account_id,
            platform=platform,
            text=adapted["text"],
            media_urls=adapted.get("media_urls", [])
        )

        results[platform] = result
        print(f"{platform}: {'✓' if result['success'] else '✗'}")

    return results

# Usage
content = {
    "text": "Just finished editing this amazing sunset shot!",
    "hashtags": "#photography #sunset #nature",
    "cta": "What do you think? 💭",
    "media_urls": ["https://storage.example.com/sunset.jpg"]
}

accounts = {
    "facebook": "my-fb-page-id",
    "instagram": "my-ig-id",
    "threads": "my-threads-id"
}

results = cross_post_content(content, accounts)

3. E-Commerce Product Launches

Scenario

You're launching new products and want to announce them across social platforms with product images.

Solution

def announce_product(product, accounts):
    """
    Announce new product with images and details
    """

    # Facebook: Album with all product images
    fb_result = publish_post(
        account_id=accounts["facebook"],
        platform="facebook",
        text=f"""
🎉 New Product Launch: {product['name']}

{product['description']}

💰 Price: ${product['price']}
🛒 Shop now: {product['url']}

#newproduct #launch #shopping
        """.strip(),
        media_urls=product["images"]  # All images
    )

    # Instagram: Carousel with product photos
    ig_result = publish_post(
        account_id=accounts["instagram"],
        platform="instagram",
        text=f"""
✨ Introducing {product['name']}!

{product['description']}

Swipe to see all colors ➡️

Link in bio to shop!

#newproduct #shopping #{product['category']}
        """.strip(),
        media_urls=product["images"][:10]  # Max 10 for carousel
    )

    # Threads: Text post with main image
    threads_result = publish_post(
        account_id=accounts["threads"],
        platform="threads",
        text=f"""
Just dropped: {product['name']} 🔥

{product['short_description']}

Available now! What do you think? 💭
        """.strip(),
        media_urls=[product["images"][0]]  # Main image only
    )

    return {
        "facebook": fb_result,
        "instagram": ig_result,
        "threads": threads_result
    }

# Usage
product = {
    "name": "Summer Beach Tote",
    "description": "Perfect for beach days! Water-resistant, spacious, and stylish.",
    "short_description": "Water-resistant beach bag with plenty of space!",
    "price": 49.99,
    "url": "https://shop.example.com/beach-tote",
    "category": "bags",
    "images": [
        "https://cdn.example.com/tote-main.jpg",
        "https://cdn.example.com/tote-blue.jpg",
        "https://cdn.example.com/tote-pink.jpg",
        "https://cdn.example.com/tote-detail.jpg"
    ]
}

results = announce_product(product, accounts)

4. Event Promotion

Scenario

You're hosting an event and want to promote it on social media with countdown and updates.

Solution

from datetime import datetime, timedelta

def promote_event(event, accounts, days_before):
    """
    Create promotional posts leading up to event
    """

    event_date = datetime.fromisoformat(event["date"])
    days_until = (event_date - datetime.now()).days

    if days_until <= 0:
        message = "🔴 HAPPENING NOW!"
    elif days_until == 1:
        message = "⏰ Tomorrow!"
    else:
        message = f"📅 {days_until} days to go!"

    # Create promotional text
    promo_text = f"""
{message}

{event['name']}
📍 {event['location']}
🗓 {event['date_formatted']}

{event['description']}

Register: {event['url']}

#{event['hashtag']}
    """.strip()

    # Post to all platforms
    results = {}
    for platform, account_id in accounts.items():
        result = publish_post(
            account_id=account_id,
            platform=platform,
            text=promo_text,
            media_urls=[event["poster_url"]]
        )
        results[platform] = result

    return results

# Usage
event = {
    "name": "Web Dev Workshop 2025",
    "location": "Online",
    "date": "2025-02-15T10:00:00",
    "date_formatted": "February 15, 2025 @ 10 AM EST",
    "description": "Learn modern web development techniques from industry experts!",
    "url": "https://events.example.com/webdev-2025",
    "hashtag": "WebDev2025",
    "poster_url": "https://cdn.example.com/workshop-poster.jpg"
}

# Schedule promotions
promote_event(event, accounts, days_before=7)   # 1 week before
promote_event(event, accounts, days_before=3)   # 3 days before
promote_event(event, accounts, days_before=1)   # 1 day before
promote_event(event, accounts, days_before=0)   # Day of

5. Blog Post Sharing

Scenario

You publish blog posts and want to share them on social media with different formats for each platform.

Solution

def share_blog_post(blog_post, accounts):
    """
    Share blog post with platform-specific formatting
    """

    # Facebook: Full excerpt with featured image
    fb_result = publish_post(
        account_id=accounts["facebook"],
        platform="facebook",
        text=f"""
📝 New Blog Post: {blog_post['title']}

{blog_post['excerpt']}

Read more: {blog_post['url']}

#{blog_post['category']} #blog
        """.strip(),
        media_urls=[blog_post["featured_image"]]
    )

    # Instagram: Short teaser with compelling image
    ig_result = publish_post(
        account_id=accounts["instagram"],
        platform="instagram",
        text=f"""
📖 {blog_post['title']}

{blog_post['teaser']}

Link in bio to read full post!

#{blog_post['category']} #blog #content
        """.strip(),
        media_urls=[blog_post["featured_image"]]
    )

    # Threads: Create a thread summarizing key points
    thread_posts = [
        f"📝 New post: {blog_post['title']}",
        blog_post['key_point_1'],
        blog_post['key_point_2'],
        blog_post['key_point_3'],
        f"Read the full post: {blog_post['url']}"
    ]

    threads_result = publish_post(
        account_id=accounts["threads"],
        platform="threads",
        text=thread_posts,  # Array creates thread
        media_urls=[]
    )

    return {
        "facebook": fb_result,
        "instagram": ig_result,
        "threads": threads_result
    }

# Usage
blog_post = {
    "title": "10 Tips for Better Time Management",
    "excerpt": "Time management is crucial for productivity. Here are 10 actionable tips to help you make the most of your day...",
    "teaser": "Struggling with time management? Here are 10 game-changing tips!",
    "url": "https://blog.example.com/time-management-tips",
    "category": "productivity",
    "featured_image": "https://cdn.example.com/time-management.jpg",
    "key_point_1": "Tip #1: Use time blocking to allocate specific hours for tasks.",
    "key_point_2": "Tip #2: Eliminate distractions during focus time.",
    "key_point_3": "Tip #3: Take regular breaks to maintain productivity."
}

results = share_blog_post(blog_post, accounts)

6. User-Generated Content Sharing

Scenario

Customers share photos of your products. You want to reshare them with credit.

Solution

def share_ugc(ugc_content, accounts):
    """
    Share user-generated content with proper credit
    """

    credit_text = f"📸 by @{ugc_content['author']}"

    # Facebook
    fb_text = f"""
{ugc_content['caption']}

{credit_text}

Thanks for sharing! ❤️

{ugc_content.get('hashtags', '')}
    """.strip()

    # Instagram
    ig_text = f"""
{ugc_content['caption']}

{credit_text}

Thank you for tagging us! 🙌

{ugc_content.get('hashtags', '')}
    """.strip()

    # Publish to all platforms
    results = {}

    for platform in ["facebook", "instagram", "threads"]:
        if platform == "instagram":
            text = ig_text
        else:
            text = fb_text

        result = publish_post(
            account_id=accounts[platform],
            platform=platform,
            text=text,
            media_urls=[ugc_content["image_url"]]
        )

        results[platform] = result

    return results

# Usage
ugc = {
    "author": "happycustomer",
    "caption": "Loving my new purchase from @yourstore!",
    "image_url": "https://storage.example.com/customer-photo.jpg",
    "hashtags": "#customer #love #quality"
}

results = share_ugc(ugc, accounts)

7. Weekly Recap / Newsletter

Scenario

Share weekly highlights, updates, or newsletter summaries on social media.

Solution

def share_weekly_recap(week_number, highlights, accounts):
    """
    Share weekly recap with highlights
    """

    # Create thread for Threads platform
    thread_content = [
        f"🗓 Week {week_number} Recap 🧵",
    ]

    for i, highlight in enumerate(highlights, 1):
        thread_content.append(f"{i}. {highlight['title']}\n{highlight['summary']}")

    thread_content.append("Thanks for following along! See you next week 👋")

    # Threads: Full thread
    threads_result = publish_post(
        account_id=accounts["threads"],
        platform="threads",
        text=thread_content,
        media_urls=[]
    )

    # Facebook/Instagram: Single post with image
    recap_text = f"""
🗓 Week {week_number} Recap

This week's highlights:

{chr(10).join([f"• {h['title']}" for h in highlights])}

Check out our full newsletter for details!

#weeklyrecap #updates
    """.strip()

    fb_result = publish_post(
        account_id=accounts["facebook"],
        platform="facebook",
        text=recap_text,
        media_urls=["https://cdn.example.com/recap-graphic.jpg"]
    )

    ig_result = publish_post(
        account_id=accounts["instagram"],
        platform="instagram",
        text=recap_text + "\n\nLink in bio 🔗",
        media_urls=["https://cdn.example.com/recap-graphic.jpg"]
    )

    return {
        "facebook": fb_result,
        "instagram": ig_result,
        "threads": threads_result
    }

# Usage
highlights = [
    {
        "title": "New Feature Launch",
        "summary": "We launched our highly-requested dark mode!"
    },
    {
        "title": "Team Update",
        "summary": "Welcome our two new team members!"
    },
    {
        "title": "Customer Milestone",
        "summary": "We hit 10,000 active users! 🎉"
    }
]

results = share_weekly_recap(
    week_number=8,
    highlights=highlights,
    accounts=accounts
)

8. Automated Scheduling System

Scenario

Build a content scheduling system that publishes posts at optimal times.

Solution

import schedule
import time
from datetime import datetime

# Content queue
SCHEDULED_POSTS = [
    {
        "time": "09:00",
        "account_id": "fb-account-id",
        "platform": "facebook",
        "text": "Good morning! ☀️",
        "media_urls": []
    },
    {
        "time": "12:00",
        "account_id": "ig-account-id",
        "platform": "instagram",
        "text": "Lunch time post! 🍕",
        "media_urls": ["https://example.com/lunch.jpg"]
    },
    {
        "time": "18:00",
        "account_id": "threads-account-id",
        "platform": "threads",
        "text": "Evening thoughts 💭",
        "media_urls": []
    }
]

def publish_scheduled_post(post):
    """Publish a scheduled post"""
    print(f"[{datetime.now()}] Publishing scheduled post...")

    result = publish_post(
        account_id=post["account_id"],
        platform=post["platform"],
        text=post["text"],
        media_urls=post.get("media_urls", [])
    )

    if result["success"]:
        print(f"✓ Published: {result['data']['post_id']}")
    else:
        print(f"✗ Failed: {result['message']}")

def setup_scheduler():
    """Set up scheduled posts"""
    for post in SCHEDULED_POSTS:
        schedule.every().day.at(post["time"]).do(
            publish_scheduled_post,
            post=post
        )

    print("Scheduler started. Waiting for scheduled times...")

    while True:
        schedule.run_pending()
        time.sleep(60)  # Check every minute

# Run scheduler
setup_scheduler()

9. Analytics and Reporting

Scenario

Track publishing success rates and generate reports.

Solution

from collections import defaultdict
from datetime import datetime, timedelta

class PublishingAnalytics:
    def __init__(self):
        self.results = []

    def track_publish(self, platform, result):
        """Track a publishing result"""
        self.results.append({
            "platform": platform,
            "success": result["success"],
            "timestamp": datetime.now(),
            "error": result.get("error") if not result["success"] else None
        })

    def get_success_rate(self, platform=None, days=7):
        """Calculate success rate"""
        cutoff = datetime.now() - timedelta(days=days)

        filtered = [
            r for r in self.results
            if r["timestamp"] >= cutoff and
            (platform is None or r["platform"] == platform)
        ]

        if not filtered:
            return 0

        successes = sum(1 for r in filtered if r["success"])
        return (successes / len(filtered)) * 100

    def get_error_summary(self, days=7):
        """Get summary of errors"""
        cutoff = datetime.now() - timedelta(days=days)

        errors = defaultdict(int)

        for r in self.results:
            if r["timestamp"] >= cutoff and not r["success"]:
                errors[r["error"]] += 1

        return dict(errors)

    def generate_report(self):
        """Generate analytics report"""
        report = {
            "total_posts": len(self.results),
            "success_rate_overall": self.get_success_rate(),
            "success_rate_by_platform": {
                "facebook": self.get_success_rate("facebook"),
                "instagram": self.get_success_rate("instagram"),
                "threads": self.get_success_rate("threads")
            },
            "errors": self.get_error_summary()
        }

        return report

# Usage
analytics = PublishingAnalytics()

# Track each publish
result = publish_post(...)
analytics.track_publish("facebook", result)

# Generate weekly report
report = analytics.generate_report()
print(f"Success rate: {report['success_rate_overall']:.1f}%")
print(f"Common errors: {report['errors']}")

10. Content A/B Testing

Scenario

Test different variations of content to see what performs best.

Solution

import random

def ab_test_content(variations, account_id, platform):
    """
    Publish different content variations and track results
    """

    # Randomly select a variation
    variation = random.choice(variations)

    print(f"Testing variation: {variation['name']}")

    result = publish_post(
        account_id=account_id,
        platform=platform,
        text=variation["text"],
        media_urls=variation.get("media_urls", [])
    )

    # Track which variation was used
    return {
        "variation": variation["name"],
        "result": result,
        "post_id": result.get("data", {}).get("post_id")
    }

# Usage
variations = [
    {
        "name": "Variation A - Question",
        "text": "What's your favorite feature? Let us know! 👇"
    },
    {
        "name": "Variation B - Statement",
        "text": "Our users love these features! Check them out 🔥"
    },
    {
        "name": "Variation C - CTA",
        "text": "Try our new feature today! Link in bio 🚀"
    }
]

test_result = ab_test_content(
    variations=variations,
    account_id="threads-account-id",
    platform="threads"
)

# Later: Analyze engagement metrics for each variation
# to determine which performed best

Next Steps

• Python Examples - Detailed Python code
• JavaScript Examples - Node.js examples
• API Reference - Complete API docs
• Platform Guides - Platform-specific details