Cookbook

Tres recetas orientadas a tareas que puedes copiar y ejecutar hoy, sin necesidad de usar la interfaz de SociaHive. Cada una es una automatización real construida con la misma superficie de herramientas MCP que llama un asistente de IA o un script: responder con un mensaje directo a los comentarios de Instagram, programar en lote una semana de publicaciones desde un CSV con la API REST o la CLI, y recibir un resumen diario de rendimiento en el chat de tu asistente de IA. Elige abajo la que se ajuste a tu forma de trabajar.

Responder automáticamente a comentarios de Instagram que mencionan “precio”

Perfil: quien usa IA (Claude.ai, Claude Desktop, Cursor) Tiempo: 2 minutos Código: ninguno, solo un prompt por MCP

Qué vas a construir: un flujo de automatización de SociaHive que envía un mensaje directo a quien comente “precio”, “costo” o “cuánto cuesta” en tus publicaciones de Instagram. Lo logras conversando con tu asistente de IA, sin hacer clic en la interfaz de SociaHive.

Requisitos previos: un cliente MCP conectado a SociaHive. Consulta la guía de configuración del MCP.

El prompt:

Usando SociaHive, créame un flujo de respuesta automática a comentarios de Instagram:

1. Actívalo con comentarios que contengan “precio”, “costo” o “cuánto cuesta”
2. Responde en público con “Te lo envío por mensaje directo ahora 📩”
3. Envía a quien comentó un mensaje directo con nuestro enlace de precios: https://example.com/pricing
4. Activa el flujo cuando termines

Usa mi primera cuenta de Instagram. Muéstrame el flujo final antes de activarlo.

Qué hace la IA internamente:

1. list_accounts                  → encuentra tu cuenta de Instagram
2. generate_flow (0 créditos de IA) → la IA construye todo el grafo del flujo
3. get_flow                       → te muestra el resultado
4. activate_flow                  → después de que confirmes

Variaciones:

Costo: 0 créditos de IA para crearla: generate_flow es IA de creación y es gratis en todos los planes. Los mensajes de plantilla que envía la automatización no cuestan nada. Solo la IA que responde a tu audiencia gasta créditos: las respuestas con IA cuestan 5 créditos cada una.

Programar una semana de publicaciones desde un CSV

Perfil: persona desarrolladora Tiempo: 5 minutos Código: Python + Node

Requisitos previos: una clave de API de SociaHive (consulta la guía rápida para desarrolladores) y el SDK de Python o el de Node instalado.

Formato del CSV:

text,platform,scheduled_at,image_url
"Monday motivation 💪",instagram,2026-06-01T09:00:00Z,https://cdn.example.com/mon.jpg
"Tuesday tip: keep it short",twitter,2026-06-02T09:00:00Z,
"Wednesday wisdom",linkedin,2026-06-03T09:00:00Z,

import csv
import os
import sys
from sociahive import SociaHive
 
sh = SociaHive(api_key=os.environ["SOCIAHIVE_API_KEY"])
 
with open(sys.argv[1]) as f:
    rows = list(csv.DictReader(f))
 
account_cache = {}
for platform in {r["platform"] for r in rows}:
    accounts = sh.accounts.list(platform=platform).get("data", [])
    if not accounts:
        sys.exit(f"No connected account for {platform}")
    account_cache[platform] = accounts[0]["id"]
 
payloads = [{
    "text": r["text"],
    "platforms": [{"platform": r["platform"], "account_id": account_cache[r["platform"]]}],
    "schedule_type": "scheduled",
    "scheduled_at": r["scheduled_at"],
    "timezone": "UTC",
    **({"media": [{"type": "image", "url": r["image_url"]}]} if r["image_url"] else {}),
} for r in rows]
 
# Use bulk endpoint when >10 posts; otherwise loop
if len(payloads) > 10:
    result = sh.posts.bulk(payloads)
    for post in result["data"]:
        print(f'scheduled {post["id"]} on {post["platforms"][0]["platform"]}')
else:
    for p in payloads:
        post = sh.posts.create(**p)
        print(f'scheduled {post["id"]} on {p["platforms"][0]["platform"]}')

CLI en un solo paso (sin escribir scripts):

sociahive posts create \
  --text "Monday motivation 💪" \
  --platforms '[{"platform":"instagram","account_id":"…"}]' \
  --schedule-type scheduled \
  --scheduled-at "2026-06-01T09:00:00Z" \
  --media '[{"type":"image","url":"https://cdn.example.com/mon.jpg"}]'

cURL, una sola llamada:

curl -X POST https://www.sociahive.com/api/v1/posts \
  -H "X-API-Key: $SOCIAHIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Monday motivation 💪",
    "platforms": [{"platform":"instagram","account_id":"…"}],
    "schedule_type": "scheduled",
    "scheduled_at": "2026-06-01T09:00:00Z"
  }'

Consejos ante errores:

• 413 en /posts/bulk: el tope por lote es de 100 filas; divide tu CSV en partes.
• 400 platform_user_id required: la búsqueda del ID de cuenta coincidió con la cuenta equivocada; pasa platform_user_id de forma explícita.
• 429: el límite predeterminado es de 1,000 solicitudes por hora por clave; guarda en caché los ID de cuenta y usa el endpoint bulk.

Verifica: sociahive posts list --status scheduled --limit 20.

Costo: $0 en créditos de IA.

Sube archivos multimedia y publica un carrusel de fotos en TikTok

Los archivos multimedia deben estar en nuestro almacenamiento antes de que una publicación pueda usarlos. Tu clave necesita uploads:write y posts:write.

Desde la CLI (archivos locales):

sociahive upload slide-1.jpg slide-2.jpg slide-3.jpg
# [{ "file": "slide-1.jpg", "url": "https://.../uploads/...jpg", "key": "uploads/...", "size_bytes": 182311 }, ...]
 
# Or upload and create in one go (repeat --media-file per file):
sociahive posts create --text "3 mistakes new founders make" \
  --platforms '[{"platform":"tiktok"}]' --scheduled-at "tomorrow 9am" \
  --media-file slide-1.jpg --media-file slide-2.jpg --media-file slide-3.jpg

sociahive upload termina con un código distinto de cero cuando falla algún archivo e indica el motivo de cada uno. Formatos admitidos: JPEG, PNG, WebP, MP4 y MOV, hasta el tamaño de subida de tu plan.

Con la API REST, cada archivo requiere tres llamadas:

1. POST /api/v1/uploads/presign con { filename, mime_type, size_bytes }.
2. Envía los bytes con PUT a upload_url, con todos los encabezados de required_headers, exactamente como se devolvieron (hoy Content-Type, Content-Length y Content-Disposition). Cada uno forma parte de la firma de la URL: si omites uno o cambias alguno, el almacenamiento responde 403.
3. POST /api/v1/uploads/verify con { key }. El public_url de la respuesta es la URL que debes usar como contenido multimedia de la publicación.

Desde Claude.ai o ChatGPT (sin bytes de archivo): la herramienta upload_media_from_url, o POST /api/v1/uploads/from-url con { url }, copia una imagen o un video públicos a tus subidas y devuelve { url, key, size_bytes, mime_type }. El tipo se lee del propio archivo y los archivos tienen un límite de 100 MB (para archivos más grandes, usa la subida con presign de arriba). Cuando el sitio no entrega el archivo, la respuesta es 422: upstream_refused (el sitio respondió con un error; su estado HTTP está en details.reason), upstream_timeout o upstream_unreachable. Elige otra URL o descarga el archivo y usa la subida con presign.

En ChatGPT, una imagen que genera ChatGPT, o una foto que agregas al chat, entra sin URL: ChatGPT pasa el archivo a upload_media_from_url como file (la herramienta declara _meta["openai/fileParams"]), y SociaHive lo copia al instante. Pide “haz una imagen de nuestra vela nueva y prográmala en Instagram mañana a las 9” y ChatGPT crea la imagen, la importa y programa la publicación.

POST /api/v1/posts con schedule_type: "scheduled" y un scheduled_at en el futuro programa la publicación en la misma llamada.

Resumen diario de rendimiento con Claude

Perfil: uso avanzado / operación de agencia Tiempo: 2 minutos Código: ninguno, solo un prompt por MCP

Qué obtendrás: un resumen matutino de una pantalla: qué flujos rindieron por debajo de lo esperado, qué publicaciones superaron lo esperado, qué hay en cola para hoy y dónde hace falta atención. Sin clics, sin SQL, sin buscar en el panel.

Requisitos previos: un cliente MCP conectado a SociaHive. Consulta la guía de configuración del MCP.

El prompt:

Dame un resumen del rendimiento de ayer en SociaHive. Pasos:

1. Lista mis flujos con las estadísticas de las últimas 24 horas.
2. Trae el panorama de estadísticas del mismo periodo en todas las plataformas.
3. Lista todo lo que esté programado para publicarse hoy.
4. Entrega un resumen de 6 líneas:
   • Flujo con mejor rendimiento (por completados) y por qué
   • Flujo con peor rendimiento (por tasa de error) y qué investigar
   • Mejor publicación (por interacción) y qué tenía en común
   • Alcance e impresiones totales en todas las plataformas frente al día anterior
   • Lo que está en cola para hoy y que debería revisar antes de que salga
   • Una acción concreta que recomiendes

Sé conciso: menos de 200 palabras en total. No modifiques nada.

Qué hace la IA internamente:

1. list_flows_with_stats     → rendimiento de los flujos + conteo de errores
2. get_analytics_overview    → impresiones / interacción entre plataformas
3. list_scheduled_posts      → la cola de hoy

Las tres son herramientas de solo lectura: no hay riesgo de cambios accidentales ni avisos de confirmación.

Variaciones:

Costo:

• 0 créditos de IA de SociaHive: las tres herramientas son endpoints de métricas de solo lectura y no se miden.
• Lo que cobre tu asistente de IA por sus propios tokens (normalmente centavos por ejecución con Claude Haiku o GPT-4o-mini).

Por qué supera al panel:

El panel te muestra datos. La IA te dice qué hacer con ellos, que es lo que querías de verdad cuando abriste el panel a las 9 a.m.

Preguntas frecuentes

¿Necesito escribir código para alguna de estas recetas? Las recetas 1 y 3 son solo prompts: le escribes una frase a tu asistente de IA y él llama a las herramientas MCP por ti. La receta 2 (importar un CSV) tiene un ejemplo en Python y otro en Node, pero los ejemplos de la CLI en un solo paso y de cURL de esa sección funcionan sin escribir nada de código.

¿Puedo ejecutarlas con ChatGPT en lugar de Claude? Sí. Todas las recetas usan el servidor MCP público de SociaHive, al que puede llamar cualquier agente compatible con MCP: Claude Desktop, Claude Code, los conectores de ChatGPT o Cursor. Consulta la guía de configuración del MCP para ver los pasos de conexión de cada cliente.

¿Qué pasa si un paso falla a la mitad? Las lecturas (list_accounts, get_flow, list_flows_with_stats) siempre se pueden reintentar sin riesgo. Las escrituras irreversibles (publicar algo ahora mismo, eliminar un flujo) devuelven un token de confirmación de corta duración en la primera llamada y solo se ejecutan con una segunda confirmación explícita; nada destructivo se ejecuta con una sola llamada. En el caso de la receta del CSV, consulta los consejos ante errores de arriba para los fallos comunes 413 y 429 y cómo recuperarte.

¿Cuánto cuestan estas recetas? Las recetas 1 y 3 cuestan $0 en créditos de IA: la generación de flujos y las herramientas de estadísticas de solo lectura son IA de creación gratuita, no se miden. La receta 2 no llama a la IA en absoluto; son llamadas directas a REST/CLI, así que no cuesta nada más allá del uso de tokens de tu propio asistente de IA (si manejas la CLI desde uno).

Qué leer después

• Patrones de flujo: las siete formas que adoptan la mayoría de los flujos de SociaHive, para que puedas describir lo que quieres construir.
• Guía rápida para desarrolladores: referencia de REST, SDK y CLI si quieres integrar SociaHive en una aplicación más grande.
• Guía de configuración del MCP: la integración con asistentes de IA que habilita las recetas 1 y 3.