social-media-automation/docs/THREAD_SERIES.md

Thread Series

Sistema para crear y publicar hilos de múltiples posts conectados.

Descripción

Los Thread Series permiten:

• Crear contenido largo dividido en posts conectados
• Generar hilos con IA
• Programar publicación escalonada
• Mantener cadena de respuestas (reply chain)

Modelos de Datos

ThreadSeries

ThreadSeries:
    id: int
    name: str
    description: str
    topic: str

    platform: str  # x, threads

    # Configuración de programación
    schedule_type: str  # sequential, timed
    interval_minutes: int  # Tiempo entre posts (default 5)
    start_time: datetime

    # Estado
    total_posts: int
    posts_published: int
    status: str  # draft, scheduled, publishing, completed, paused, cancelled

    # Reply chain
    first_platform_post_id: str  # ID del primer post (para replies)

    # IA
    ai_generated: bool
    generation_prompt: str

    hashtags: JSON  # Hashtags comunes

ThreadPost

ThreadPost:
    id: int
    series_id: int (FK -> thread_series)
    sequence_number: int  # 1, 2, 3...

    content: str
    image_url: str

    post_id: int (FK -> posts)

    # Para reply chain
    platform_post_id: str
    reply_to_platform_id: str

    scheduled_at: datetime
    status: str  # pending, scheduled, published, failed
    error_message: str
    published_at: datetime

API Endpoints

GET /api/threads/

Lista todas las series.

Parámetros:

• status: draft, scheduled, publishing, completed
• platform: x, threads
• limit (int, default=20)

GET /api/threads/{series_id}

Obtiene una serie con todos sus posts.

Respuesta:

{
    "id": 1,
    "name": "Hilo sobre IA",
    "topic": "Inteligencia Artificial",
    "platform": "x",
    "status": "scheduled",
    "total_posts": 5,
    "posts_published": 0,
    "start_time": "2025-02-01T10:00:00",
    "interval_minutes": 5,
    "posts": [
        {
            "id": 1,
            "sequence_number": 1,
            "content": "🧵 Hilo: Todo sobre IA...",
            "status": "scheduled",
            "scheduled_at": "2025-02-01T10:00:00"
        },
        {
            "id": 2,
            "sequence_number": 2,
            "content": "1/ La IA está transformando...",
            "status": "scheduled",
            "scheduled_at": "2025-02-01T10:05:00"
        }
    ]
}

POST /api/threads/

Crea una serie manualmente.

Body:

{
    "name": "Tips de productividad",
    "platform": "x",
    "posts": [
        {"content": "🧵 Hilo: 5 tips para ser más productivo"},
        {"content": "1/ Usa la técnica Pomodoro..."},
        {"content": "2/ Elimina distracciones..."},
        {"content": "3/ Prioriza con Eisenhower..."},
        {"content": "4/ Automatiza tareas repetitivas..."},
        {"content": "5/ Revisa tu progreso diario..."}
    ],
    "description": "Tips de productividad para profesionales",
    "schedule_type": "sequential",
    "interval_minutes": 3,
    "hashtags": ["#Productividad", "#Tips"]
}

Validaciones:

• Mínimo 2 posts, máximo 20
• Platform requerido

POST /api/threads/generate

Genera un hilo con IA.

Body:

{
    "topic": "Cómo empezar con inteligencia artificial",
    "platform": "x",
    "num_posts": 5,
    "style": "educational",
    "name": "Intro a IA"  // Opcional: si se incluye, guarda la serie
}

Estilos disponibles:

• educational: Contenido informativo y didáctico
• storytelling: Formato narrativo
• tips: Lista de consejos prácticos

Respuesta (sin name):

{
    "message": "Thread generated (not saved)",
    "generated_posts": [
        {"sequence": 1, "content": "🧵 Te explico qué es la IA..."},
        {"sequence": 2, "content": "1/ La IA es..."}
    ],
    "count": 5
}

Respuesta (con name):

{
    "message": "Thread generated and saved",
    "series": {...},
    "generated_posts": [...]
}

POST /api/threads/{series_id}/schedule

Programa una serie para publicación.

Body (opcional):

{
    "start_time": "2025-02-01T10:00:00"
}

Si no se especifica, inicia en 5 minutos.

Proceso:

1. Crea posts reales para cada ThreadPost
2. Programa cada uno con el intervalo configurado
3. Cambia status a "scheduled"

Respuesta:

{
    "message": "Series scheduled successfully",
    "success": true,
    "series_id": 1,
    "start_time": "2025-02-01T10:00:00",
    "posts_scheduled": 5
}

POST /api/threads/{series_id}/publish-next

Publica manualmente el siguiente post de la serie.

POST /api/threads/{series_id}/cancel

Cancela una serie y sus posts programados.

Tareas Programadas

check_thread_schedules

• Frecuencia: Cada minuto
• Función:
  • Busca ThreadPosts programados para ahora
  • Encola tarea de publicación
  • Actualiza estado

update_thread_post_status

• Trigger: Después de publicar un post
• Función:
  • Actualiza estado del ThreadPost
  • Guarda platform_post_id (para reply chain)
  • Actualiza progreso de la serie
  • Marca serie como completed si todos publicados

Tipos de Programación

Tipo	Descripción
sequential	Posts uno tras otro con intervalo fijo
timed	Posts en horarios específicos (próximamente)

Reply Chain

Para que los posts aparezcan como respuestas:

1. Se publica el primer post
2. Se guarda su platform_post_id
3. Los siguientes posts se publican como respuesta al anterior
4. Cada uno guarda su reply_to_platform_id

Post 1 (original)
  └── Post 2 (reply to 1)
       └── Post 3 (reply to 2)
            └── Post 4 (reply to 3)

Ejemplo de Uso

from app.services.thread_service import thread_service

# Crear serie manual
series = await thread_service.create_series(
    name="Tips de Python",
    platform="x",
    posts_content=[
        {"content": "🧵 Hilo: 5 tips de Python que debes conocer"},
        {"content": "1/ List comprehensions..."},
        {"content": "2/ F-strings..."},
        {"content": "3/ Context managers..."},
        {"content": "4/ Generators..."},
        {"content": "5/ Decorators..."}
    ],
    interval_minutes=3
)

# Generar con IA
result = await thread_service.generate_thread_with_ai(
    topic="Beneficios de la automatización",
    platform="threads",
    num_posts=5,
    style="storytelling"
)

# Programar
await thread_service.schedule_series(
    series_id=series.id,
    start_time=datetime(2025, 2, 1, 10, 0)
)

# Ver estado
series = await thread_service.get_series(series.id)
print(f"Publicados: {series['posts_published']}/{series['total_posts']}")

Flujo Completo

1. Crear Serie
   - Manual: Proporcionar posts
   - IA: Generar con prompt
        ↓
2. Revisar y Editar
   - Verificar contenido
   - Ajustar hashtags
        ↓
3. Programar
   - Establecer start_time
   - Crear posts reales
        ↓
4. Publicación Automática
   - Celery Beat cada minuto
   - Publica posts programados
   - Mantiene reply chain
        ↓
5. Completado
   - Todos los posts publicados
   - Status: completed

Mejores Prácticas

1. Primer post atractivo: El 1/5 o 🧵 debe captar atención
2. Numeración clara: "1/", "2/" o "1.", "2."
3. Intervalos cortos: 3-5 minutos mantienen engagement
4. Último post con CTA: Llamado a la acción al final
5. Hashtags solo al final: No saturar cada post
6. Máximo 10-15 posts: Hilos muy largos pierden audiencia

Plataformas Soportadas

Plataforma	Reply Chain	Notas
X (Twitter)	✅	Ideal para threads
Threads	✅	Buen soporte
Instagram	❌	No soporta threads
Facebook	❌	No soporta threads